gdref

Deterministic, agent-oriented retrieval for godot-skills/ and godot-docs/.

Use this when you want exact, low-noise retrieval without broad directory search.

Install (Human Setup)

gdref is a lightweight Python CLI (stdlib only). No package install required.

In this repo

1. Ensure executable bits are set:

chmod +x ./gdref ./tools/gdref/gdref.py

2. Build the initial index:

./gdref index build
./gdref validate

Tip:

./gdref index build && ./gdref validate

Expected Project Layout

gdref expects these paths at project root:

your-project/
├─ gdref
├─ tools/
│  └─ gdref/
│     ├─ gdref.py
│     ├─ lexicon.json
│     ├─ README.md
│     ├─ AGENTS_SNIPPET.md
│     ├─ skill/
│     │  └─ gdref-agent-operator/SKILL.md
│     └─ .cache/              # created after index build
├─ godot-skills/
│  ├─ godot-foundations/
│  ├─ godot-secondary/
│  ├─ godot-tertiary/
│  └─ godot-operational/
└─ godot-docs/
   ├─ classes/
   └─ tutorials/

Minimum required for indexing:

• godot-skills/
• godot-docs/

Copy to another project

Your target project must contain both:

• godot-skills/
• godot-docs/

Copy these paths into the target project root:

• gdref
• tools/gdref/

Then run:

./gdref index build
./gdref validate

If your project is in a different location, you can also point at it explicitly:

./gdref --root /path/to/project index build

Quick Start

./gdref index build
./gdref --agent find "multiplayer intent replication reconnect"
./gdref --agent bridge class EditorUndoRedoManager

Why

• No runtime directory grepping for retrieval.
• Exact symbol lookup for classes/methods/doc labels.
• Direct skill<->doc bridge to reduce bad keyword retrieval.
• Low-token outputs by default (paths only).

Scope

• Indexes only:
  • godot-skills/**/SKILL.md
  • godot-docs/**/*.rst

No runtime directory grepping is used for retrieval.

Common Pitfall

Global flags go before subcommands.

Correct:

./gdref --agent find "undo redo editor plugin"

Incorrect:

./gdref find "undo redo editor plugin" --agent

Build index

./gdref index build
./gdref index status
./gdref validate

Skill queries

./gdref skill get editor-undo-redo-contract
./gdref skill ls --tier tertiary --tag editor
./gdref skill chain multiplayer-intent-replication-workflow --transitive
./gdref skill docs qa-validation-loop

Doc symbol queries

./gdref doc class EditorUndoRedoManager
./gdref doc method EditorUndoRedoManager create_action
./gdref doc label doc_high_level_multiplayer
./gdref doc show godot-docs/classes/class_editorundoredomanager.rst --line 269 --context 6

Bridge queries

./gdref bridge class EditorUndoRedoManager
./gdref bridge method EditorUndoRedoManager create_action
./gdref bridge doc godot-docs/tutorials/networking/high_level_multiplayer.rst
./gdref bridge skill networking-reliability-reconciliation-contract

Concept map retrieval

./gdref find undo redo plugin history
./gdref find replay schema compatibility deterministic hash
./gdref find ui theme localization controller accessibility

Output modes

• default: newline-delimited paths
• --json: structured output for agents
• --agent: compact JSON profile (fixed keys, minimal whitespace)

Example:

./gdref --agent find "undo redo editor plugin"
./gdref --agent bridge class EditorUndoRedoManager

Notes

• Concept map lives in tools/gdref/lexicon.json.
• Cache DB lives in tools/gdref/.cache/index.sqlite.
• Drop-in agent skill file: tools/gdref/skill/gdref-agent-operator/SKILL.md.
• AGENTS.md copy/paste snippet: tools/gdref/AGENTS_SNIPPET.md.