Skip to main content

n3Plugins Reference Resource Map

Repository reference material supports implementation and validation.

Reference resources are not runtime dependencies.

1. Authority Categories​

Use references according to their role.

Source of Truth​

N3PLUGINS_SOURCE_OF_TRUTH.md

Owns repository current-state facts.

Live implementation​

src/main/**
src/test/**
build.gradle
settings.gradle
gradle/**

Owns actual implementation reality.

Focused documentation​

docs/**

Explains specifications, design, behavior, and workflows.

Curated reference artifacts​

REFERENCE_RESOURCES/**

May contain versioned:

  • RuneLite source snapshots,
  • injected-client artifacts,
  • revision references,
  • generated analysis inputs,
  • external reference material.

2. Reference Resource Rules​

Before using a reference artifact, identify:

what it is
its version
its revision
its provenance
why it is relevant
whether it matches current project state

Do not assume the newest-looking file is current.

Filesystem modification timestamps are not version authority.

3. Version Mismatch​

Reference artifacts may intentionally represent different versions.

Example:

current RuneLite API source snapshot
vs
older injected-client artifact needed for historical/revision comparison

Do not combine mismatched artifacts as though they represent one runtime.

State the mismatch.

4. Upstream Source Trees​

Do not commit full upstream repositories to make them searchable unless you have a vendoring requirement.

Prefer:

dependency resolution
curated source snapshot
GitHub/upstream inspection
generated index
small versioned reference subset

Large third-party repositories create:

  • stale copies,
  • repository bloat,
  • licensing complexity,
  • duplicated authority.

5. Vendored Resources​

Vendored resources should have:

upstream source
pinned commit/version
license
update process
purpose

Where possible, include machine-readable metadata.

Do not manually edit generated/vendored snapshots unless the update process allows it.

6. Local Developer Resources​

Inspect paths outside the repository only when available and relevant.

Never make production behavior depend on a path such as:

C:\Users\<developer>\...
/home/<developer>/...

Local files do not exist in cloud workspaces unless you deliberately copy or expose them.

7. Generated Tool State​

Do not treat generated tool databases as reference authority.

Examples:

.serena/
.codegraph/
.gradle/
build/
node_modules/
IDE indexes

These are disposable local/cloud workspace state unless the repository says otherwise.

8. When Updating Reference Resources​

When a task updates a versioned reference:

  1. identify the upstream version/revision,
  2. use the repository's update mechanism when one exists,
  3. update associated metadata,
  4. validate consumers,
  5. inspect the diff for accidental bulk changes.

Do not update reference snapshots during unrelated work.

The committed revision-240 parity authority is the narrow source subset under REFERENCE_RESOURCES/runelite_sources/rev240/2026-09-03-rev240. Its SOURCE.properties pins the RuneLite commit, included files, purpose, and license. Keep that versioned directory unignored because clean checkouts need it to run LegacyConstantParityTest.