docs: consolidate hub and golden queries; clarify API docs and incremental git

- Add golden-queries doc, remove superseded plan; refresh docs hub and links
- Restore multi-line JSDoc on public API and CLI query surfaces
- Document getChangedFiles strategy and git status porcelain path slicing

Author: SutuSebastian

.github/CONTRIBUTING.md

@@ -38,7 +38,7 @@ Then open a PR on GitHub into **`main`**.
 - **Public API** — Anything exported from the package entry (`src/index.ts` → `src/api.ts`, `config.ts`, shared types) should have **JSDoc** that reads well in hovers and in published typings.
 - **Layers** — Keep boundaries clear: [architecture.md](../docs/architecture.md) (`cli` → `application` → infrastructure). Don’t let CLI concerns leak into parsers or the DB layer.
 - **Before you open / update a PR** — `bun run check` (or at least `bun run test` + `bun run typecheck` while iterating).
-- **Golden queries (Tier A)** — If you change `fixtures/minimal/` or schema/query behavior expected by [fixtures/golden/](../fixtures/golden/), run `bun scripts/query-golden.ts --update`, review diffs, and commit updated JSON under `fixtures/golden/minimal/`. Prefer **fixing the indexer** when output changes for the wrong reason; only refresh goldens when the new rows are correct. See [docs/plan-query-golden-scenarios.md](../docs/plan-query-golden-scenarios.md).
+- **Golden queries (Tier A)** — If you change `fixtures/minimal/` or schema/query behavior expected by [fixtures/golden/](../fixtures/golden/), run `bun scripts/query-golden.ts --update`, review diffs, and commit updated JSON under `fixtures/golden/minimal/`. Prefer **fixing the indexer** when output changes for the wrong reason; only refresh goldens when the new rows are correct. See [docs/golden-queries.md](../docs/golden-queries.md).
 - **Golden queries (Tier B)** — Against a **local** clone, use `bun run test:golden:external` with `CODEMAP_ROOT` / `--root`. Copy [fixtures/golden/scenarios.external.example.json](../fixtures/golden/scenarios.external.example.json) to `scenarios.external.json` if you need custom scenarios; goldens under `fixtures/golden/external/` are gitignored — do not commit snapshots from proprietary trees.
 - **Style** — Match Oxfmt/Oxlint; prefer **straight-line code** and extracted helpers over long nested blocks.
 

.gitignore

@@ -9,7 +9,7 @@ dist/
 !.env.example
 tsconfig.lint-staged.json
 
-# Tier B golden query outputs (local / private trees — see docs/plan-query-golden-scenarios.md)
+# Tier B golden query outputs (local / private trees — see docs/golden-queries.md)
 fixtures/golden/external/
 fixtures/golden/scenarios.external.json
 

README.md

@@ -5,7 +5,7 @@
 - **Not** full-text search or grep on arbitrary strings — use those when you need raw file-body search.
 - **Is** a fast, token-efficient way to navigate **structure**: definitions, imports, dependency direction, components, and other extracted facts.
 
-**Documentation:** [docs/README.md](docs/README.md) is the hub (topic index + single-source rules). Topics: [architecture](docs/architecture.md), [agents](docs/agents.md) (`codemap agents init`), [benchmark](docs/benchmark.md), [golden query plan](docs/plan-query-golden-scenarios.md), [packaging](docs/packaging.md), [roadmap](docs/roadmap.md), [why Codemap](docs/why-codemap.md). **Bundled rules/skills:** [`.agents/rules/`](.agents/rules/), [`.agents/skills/codemap/SKILL.md`](.agents/skills/codemap/SKILL.md). **Consumers:** [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).
+**Documentation:** [docs/README.md](docs/README.md) is the hub (topic index + single-source rules). Topics: [architecture](docs/architecture.md), [agents](docs/agents.md) (`codemap agents init`), [benchmark](docs/benchmark.md), [golden queries](docs/golden-queries.md), [packaging](docs/packaging.md), [roadmap](docs/roadmap.md), [why Codemap](docs/why-codemap.md). **Bundled rules/skills:** [`.agents/rules/`](.agents/rules/), [`.agents/skills/codemap/SKILL.md`](.agents/skills/codemap/SKILL.md). **Consumers:** [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).
 
 ---
 

docs/README.md

@@ -4,18 +4,18 @@ Technical docs for **[@stainless-code/codemap](https://github.com/stainless-code
 
 **Start here:** [../README.md](../README.md) (install, CLI, API, dev commands). **This folder** is deeper reference — pick a row below.
 
-| File                                                               | Topic                                                                                                                                                                                                                                                                                                                                   |
-| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [why-codemap.md](./why-codemap.md)                                 | Why index + SQL for agents (speed, tokens, accuracy) — good first read after the readme                                                                                                                                                                                                                                                 |
-| [architecture.md](./architecture.md)                               | Schema, layering, CLI internals, API, [**User config**](./architecture.md#user-config) (Zod), parsers, [Key Files](./architecture.md#key-files)                                                                                                                                                                                         |
-| [agents.md](./agents.md)                                           | **`codemap agents init`** — bundled **`templates/agents`** → **`.agents/`** in **consumer projects** (this repo’s **`.agents/`** is dev/maintainer — see [agents.md](./agents.md)); per-file IDE symlink/copy, **[pointer files](./agents.md#pointer-files)** (`codemap-pointer`), **`--interactive`**, **`.gitignore` / `.codemap.*`** |
-| [benchmark.md](./benchmark.md)                                     | [**Indexing another project**](./benchmark.md#indexing-another-project) · [**Benchmark script**](./benchmark.md#the-benchmark-script) · [**Custom scenarios**](./benchmark.md#custom-scenarios-codemap_benchmark_config) (`CODEMAP_BENCHMARK_CONFIG`) · [`fixtures/minimal/`](../fixtures/minimal/)                                     |
-| [plan-query-golden-scenarios.md](./plan-query-golden-scenarios.md) | Golden `query` snapshots + Tier B external corpus — **implementation plan** (runner: [scripts/query-golden.ts](../scripts/query-golden.ts); not LLM eval)                                                                                                                                                                               |
-| [fixtures/golden/](../fixtures/golden/)                            | [scenarios.json](../fixtures/golden/scenarios.json) + [minimal/](../fixtures/golden/minimal/) — **`bun run test:golden`**; Tier B: [scenarios.external.example.json](../fixtures/golden/scenarios.external.example.json) + **`bun run test:golden:external`** ([benchmark § Fixtures](./benchmark.md#fixtures))                         |
-| [fixtures/benchmark/](../fixtures/benchmark/)                      | Tracked [scenarios.example.json](../fixtures/benchmark/scenarios.example.json) — copy to `*.local.json` (gitignored) for [`CODEMAP_BENCHMARK_CONFIG`](./benchmark.md#custom-scenarios-codemap_benchmark_config)                                                                                                                         |
-| [fixtures/qa/](../fixtures/qa/)                                    | [prompts.external.template.md](../fixtures/qa/prompts.external.template.md) — optional chat QA prompts for an external index (`*.local.md` gitignored)                                                                                                                                                                                  |
-| [packaging.md](./packaging.md)                                     | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets)                                                                                                                                                                    |
-| [roadmap.md](./roadmap.md)                                         | Forward-looking backlog (not a `src/` inventory)                                                                                                                                                                                                                                                                                        |
+| File                                          | Topic                                                                                                                                                                                                                                                                                                                                   |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [why-codemap.md](./why-codemap.md)            | Why index + SQL for agents (speed, tokens, accuracy) — good first read after the readme                                                                                                                                                                                                                                                 |
+| [architecture.md](./architecture.md)          | Schema, layering, CLI internals, API, [**User config**](./architecture.md#user-config) (Zod), parsers, [Key Files](./architecture.md#key-files)                                                                                                                                                                                         |
+| [agents.md](./agents.md)                      | **`codemap agents init`** — bundled **`templates/agents`** → **`.agents/`** in **consumer projects** (this repo’s **`.agents/`** is dev/maintainer — see [agents.md](./agents.md)); per-file IDE symlink/copy, **[pointer files](./agents.md#pointer-files)** (`codemap-pointer`), **`--interactive`**, **`.gitignore` / `.codemap.*`** |
+| [benchmark.md](./benchmark.md)                | [**Indexing another project**](./benchmark.md#indexing-another-project) · [**Benchmark script**](./benchmark.md#the-benchmark-script) · [**Custom scenarios**](./benchmark.md#custom-scenarios-codemap_benchmark_config) (`CODEMAP_BENCHMARK_CONFIG`) · [`fixtures/minimal/`](../fixtures/minimal/)                                     |
+| [golden-queries.md](./golden-queries.md)      | Golden `query` **design & policy** (Tier A/B, no proprietary trees); runner: [scripts/query-golden.ts](../scripts/query-golden.ts)                                                                                                                                                                                                      |
+| [fixtures/golden/](../fixtures/golden/)       | [scenarios.json](../fixtures/golden/scenarios.json) + [minimal/](../fixtures/golden/minimal/) — **`bun run test:golden`**; Tier B: [scenarios.external.example.json](../fixtures/golden/scenarios.external.example.json) + **`bun run test:golden:external`** ([benchmark § Fixtures](./benchmark.md#fixtures))                         |
+| [fixtures/benchmark/](../fixtures/benchmark/) | Tracked [scenarios.example.json](../fixtures/benchmark/scenarios.example.json) — copy to `*.local.json` (gitignored) for [`CODEMAP_BENCHMARK_CONFIG`](./benchmark.md#custom-scenarios-codemap_benchmark_config)                                                                                                                         |
+| [fixtures/qa/](../fixtures/qa/)               | [prompts.external.template.md](../fixtures/qa/prompts.external.template.md) — optional chat QA prompts for an external index (`*.local.md` gitignored)                                                                                                                                                                                  |
+| [packaging.md](./packaging.md)                | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets)                                                                                                                                                                    |
+| [roadmap.md](./roadmap.md)                    | Forward-looking backlog (not a `src/` inventory)                                                                                                                                                                                                                                                                                        |
 
 ## Single source of truth (do not duplicate)
 
@@ -26,7 +26,7 @@ Technical docs for **[@stainless-code/codemap](https://github.com/stainless-code
 | **`codemap agents init`**: **`--force`** on **`.agents/`** in **consumer projects** (template file paths only), IDE matrix, per-file symlink/copy, **`templates/agents`** | [agents.md](./agents.md)                                                                 | Link here; do not paste the integration table into README or packaging                             |
 | **`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / Copilot** — managed **`codemap-pointer`** sections, merge vs **`--force`**                                                    | [agents.md § Pointer files](./agents.md#pointer-files)                                   | Link here; do not duplicate the situation table                                                    |
 | End-user CLI (index, **`query --json`**, agents, flags, env) — query has no row cap; use SQL **`LIMIT`**                                                                  | [../README.md § CLI](../README.md#cli)                                                   | [architecture § CLI usage](./architecture.md#cli-usage) summarizes and links back                  |
-| Golden query regression (`test:golden`, `test:golden:external`, `--update`)                                                                                               | [plan-query-golden-scenarios.md](./plan-query-golden-scenarios.md)                       | CONTRIBUTING § Golden queries; [benchmark § Fixtures](./benchmark.md#fixtures)                     |
+| Golden query regression (`test:golden`, `test:golden:external`, `--update`)                                                                                               | [golden-queries.md](./golden-queries.md)                                                 | CONTRIBUTING § Golden queries; [benchmark § Fixtures](./benchmark.md#fixtures)                     |
 | **`CODEMAP_BENCHMARK_CONFIG`** (per-repo benchmark JSON)                                                                                                                  | [benchmark § Custom scenarios](./benchmark.md#custom-scenarios-codemap_benchmark_config) | [fixtures/benchmark/scenarios.example.json](../fixtures/benchmark/scenarios.example.json) only     |
 | `bun run qa:external` — index + disk checks + `benchmark.ts` on **`CODEMAP_*`**                                                                                           | [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md)                                    | [scripts/qa-external-repo.ts](../scripts/qa-external-repo.ts) (invocation only)                    |
 

docs/benchmark.md

@@ -206,7 +206,7 @@ bun run benchmark
 
 **CI:** the workflow **Benchmark (fixture)** runs the same steps with `CODEMAP_ROOT=$GITHUB_WORKSPACE/fixtures/minimal`.
 
-**Correctness (golden queries):** `bun run test:golden` indexes `fixtures/minimal`, runs SQL against [fixtures/golden/scenarios.json](../fixtures/golden/scenarios.json), and compares to [fixtures/golden/minimal/](../fixtures/golden/minimal/). See [plan-query-golden-scenarios.md](./plan-query-golden-scenarios.md). Refresh goldens after intentional fixture or schema changes: `bun scripts/query-golden.ts --update`.
+**Correctness (golden queries):** `bun run test:golden` indexes `fixtures/minimal`, runs SQL against [fixtures/golden/scenarios.json](../fixtures/golden/scenarios.json), and compares to [fixtures/golden/minimal/](../fixtures/golden/minimal/). See [golden-queries.md](./golden-queries.md). Refresh goldens after intentional fixture or schema changes: `bun scripts/query-golden.ts --update`.
 
 **Tier B (local tree, not in default CI):** `bun run test:golden:external` (or `bun scripts/query-golden.ts --corpus external`) indexes **`CODEMAP_ROOT`**, **`CODEMAP_TEST_BENCH`**, or **`--root`**, loads [fixtures/golden/scenarios.external.json](../fixtures/golden/scenarios.external.json) if present else [scenarios.external.example.json](../fixtures/golden/scenarios.external.example.json), and writes/compares goldens under `fixtures/golden/external/` (gitignored). Use **`match`** in scenarios for subset checks (`minRows`, `everyRowContains`); use **`budgetMs`** with optional **`--strict-budget`** for perf warnings. Do not commit proprietary paths or goldens from private apps.