docs: fact-check and correct markdown across repo

Audit verified docs against src/, recipes, and CI. Fixes stale glob/batchInsert
claims, audit --base git archive wording, MCP vs HTTP resources, plan status
headers, agent-content paths, and low-priority drift in rules/skills/templates.

Author: SutuSebastian

.agents/rules/agents-tier-system.md

@@ -51,7 +51,7 @@ Today's Tier-2 rules:
 
 Pure intent-triggered. The skill description is detailed enough that Cursor surfaces it on relevant phrases. No always-on cost.
 
-Skills stay rule-less when the work is **explicitly invoked** by the user, not pattern-triggered. Today: `audit-pr-architecture`, `diagnose`, `docs-governance`, `docs-lifecycle-sweep`, `grill-me`, `improve-codebase-architecture`, `pr-comment-fact-check`, `write-a-skill`. (Skills like `gritql-codemods` and `ubiquitous-language` would also fit this tier if adopted.)
+Skills stay rule-less when the work is **explicitly invoked** by the user, not pattern-triggered. Today: `audit-pr-architecture`, `codemap` (consumer pointer), `diagnose`, `docs-governance`, `docs-lifecycle-sweep`, `grill-me`, `improve-codebase-architecture`, `pr-comment-fact-check`, `write-a-skill`. (Skills like `gritql-codemods` and `ubiquitous-language` would also fit this tier if adopted.)
 
 ## Authoring guidelines
 

.agents/rules/concise-comments.md

@@ -1,6 +1,5 @@
 ---
 description: Sweep your own new comments at the end of every change. Keep what code can't say; cut the rest.
-globs: "**/*.{ts,tsx,css,html,md}"
 alwaysApply: true
 ---
 

.agents/rules/docs-governance.md

@@ -8,7 +8,7 @@ alwaysApply: false
 
 Before authoring or editing any doc in this repo, **read the [`docs-governance` skill](../skills/docs-governance/SKILL.md)** for the full reference. This rule is the priming layer.
 
-The canonical Rules (1–9) live in [`docs/README.md`](../../docs/README.md) — cite them by number; never restate them.
+The canonical Rules (1–10) live in [`docs/README.md`](../../docs/README.md) — cite them by number; never restate them.
 
 ## Surface tiers (which subset of governance applies)
 
@@ -51,6 +51,6 @@ If none → fold + delete.
 - Full reference: [`.agents/skills/docs-governance/SKILL.md`](../skills/docs-governance/SKILL.md)
 - Doc janitor (operational sweep — apply the spec mechanically, classify Tier A / B / C, delete dead weight): [`.agents/skills/docs-lifecycle-sweep/SKILL.md`](../skills/docs-lifecycle-sweep/SKILL.md). Fire on intent ("clean up stale docs", "compact audits") or proactively after closing a Plan / Audit / Research file.
 - Audit framework: [`.agents/skills/audit-pr-architecture/SKILL.md`](../skills/audit-pr-architecture/SKILL.md). Fire on intent ("audit this PR's architecture", "structural review of #N") or proactively when a PR moves ≥5 files between top-level `src/` modules.
-- Canonical Rules: [`docs/README.md`](../../docs/README.md) — Rules 1–9 cited from across `docs/` and `.agents/`. Don't renumber without a coordinated re-grep + edit pass.
+- Canonical Rules: [`docs/README.md`](../../docs/README.md) — Rules 1–10 cited from across `docs/` and `.agents/`. Don't renumber without a coordinated re-grep + edit pass.
 - File-layout: [`agents-first-convention`](./agents-first-convention.md)
 - Rules vs skills tier system: [`agents-tier-system`](./agents-tier-system.md)

.agents/rules/lessons.md

@@ -1,3 +1,8 @@
+---
+description: Read lessons at session start; append after corrections
+alwaysApply: true
+---
+
 # Lessons Convention
 
 ## Rules

.agents/rules/preserve-comments.md

@@ -1,6 +1,5 @@
 ---
 description: Never remove comments, TODOs, or commented-out code without explicit confirmation
-globs: "**/*.{ts,tsx,css,html}"
 alwaysApply: true
 ---
 

.agents/skills/audit-pr-architecture/SKILL.md

@@ -5,7 +5,7 @@ description: Audit a PR's structural choices against architecture-priming, the r
 
 # Audit a PR's architecture
 
-Mid-flight or post-merge structural review of a PR against the repo's own architecture and boundary conventions. Sister skill to [`pr-comment-fact-check`](../pr-comment-fact-check/SKILL.md) when codemap adopts that one (reviewer-comment-driven).
+Mid-flight or post-merge structural review of a PR against the repo's own architecture and boundary conventions. Sister skill to [`pr-comment-fact-check`](../pr-comment-fact-check/SKILL.md) (reviewer-comment-driven triage).
 
 This skill exists because:
 
@@ -34,7 +34,7 @@ Also fire **proactively** when:
 ### 1. Reindex codemap and identify the diff scope
 
 ```bash
-bun run codemap   # or: codemap (from outside the repo)
+bun src/index.ts   # or: codemap (from outside the repo)
 git diff --name-status origin/main...HEAD
 ```
 
@@ -148,7 +148,7 @@ Doc shape — mirror the most recent audit under `docs/audits/` (or — if this
 **Scope:** <one paragraph: what diff, what HEAD, what subtree(s)>.
 **Method:** <codemap audit + structural-smell recipes + cross-check; cite which queries>.
 
-This audit follows [docs/README.md Rule 6](../README.md) (no inventory counts in evergreen prose) and [docs/README.md Rule 7](../README.md) (no line-number references). All numbers below are flagged "at audit time."
+This audit follows [docs/README.md Rule 6](../../../docs/README.md) (no inventory counts in evergreen prose) and [docs/README.md Rule 7](../../../docs/README.md) (no line-number references). All numbers below are flagged "at audit time."
 
 ---
 

.agents/skills/docs-governance/SKILL.md

@@ -20,7 +20,7 @@ Every doc in this repo lives in one of **two surface tiers** (codemap is small e
 
 The same shared spine applies to both. The differences are what subset each tier needs.
 
-> **Why no Tier C / Tier A in codemap?** Tier C (per-feature governance) only kicks in when a codebase grows independently-evolving feature folders (`app/features/<f>/`). Tier A (per-shared-component) only kicks in when shared components accumulate enough rationale to need a `README.md` next to the source. Codemap has neither today — the source tree is `src/cli/`, `src/application/`, `src/adapters/`, `src/parsers/`, `src/db.ts`, etc., all governed by the central `docs/` surface. If codemap ever grows a `src/<feature>/` partition or a `src/components/<x>/` shared-component substrate worth documenting in-place, this skill grows the corresponding tier rows then — not before (per § 5 anti-bloat).
+> **Why no Tier C / Tier A in codemap?** Tier C (per-feature governance) only kicks in when a codebase grows independently-evolving feature folders (`app/features/<f>/`). Tier A (per-shared-component) only kicks in when shared components accumulate enough rationale to need a `README.md` next to the source. Codemap has neither today — the source tree is `src/cli/`, `src/application/`, `src/adapters/`, `src/parser.ts`, `src/db.ts`, etc., all governed by the central `docs/` surface. If codemap ever grows a `src/<feature>/` partition or a `src/components/<x>/` shared-component substrate worth documenting in-place, this skill grows the corresponding tier rows then — not before (per § 5 anti-bloat).
 
 ---
 

.agents/skills/pr-comment-fact-check/SKILL.md

@@ -137,12 +137,11 @@ When this exception applies, drop a one-line summary of contested rebuttals into
 ### Commands
 
 ```bash
-# Reply to a thread
+# Reply to a thread — write body to a temp file first (heredocs mangle backticks in markdown)
+printf '%s' '<reply text>' > /tmp/pr-<number>-reply.md
 gh api "repos/{owner}/{repo}/pulls/<number>/comments" \
-  -f body="$(cat <<'EOF'
-<reply text>
-EOF
-)" -F in_reply_to=<comment_id>
+  --field body=@/tmp/pr-<number>-reply.md \
+  -F in_reply_to=<comment_id>
 
 # Resolve a thread (GraphQL only — REST endpoints don't support resolve)
 gh api graphql -f query='mutation($id: ID!) {
@@ -156,7 +155,7 @@ The thread node ID (`PRRT_…`) comes from the GraphQL `reviewThreads` query in
 
 These come up repeatedly with LLM reviewers and warrant extra scrutiny. The codemap-shape ones (1–4) come from the codemap thesis — what Codemap deliberately is and isn't (per [`docs/why-codemap.md` § When to reach for something else](../../../docs/why-codemap.md#when-to-reach-for-something-else) and [`docs/roadmap.md` § Non-goals](../../../docs/roadmap.md#non-goals-v1)). The shape-5+ ones are universal across TS projects:
 
-1. **"Just regex this"** when the file is in `src/parsers/` or `src/adapters/` — codemap is AST-backed by design (oxc for TS, lightningcss for CSS). Suggesting a regex replacement undoes the architectural choice. Verify against [`docs/architecture.md` § Parsers / Adapters](../../../docs/architecture.md) before accepting.
+1. **"Just regex this"** when the file is in `src/parser.ts`, `src/css-parser.ts`, or `src/adapters/` — codemap is AST-backed by design (oxc for TS, lightningcss for CSS). Suggesting a regex replacement undoes the architectural choice. Verify against [`docs/architecture.md` § Parsers](../../../docs/architecture.md#parsers) before accepting.
 2. **"Add full-text search"** — explicitly a non-goal per [`docs/roadmap.md` § Non-goals (v1)](../../../docs/roadmap.md#non-goals-v1). Push back with that anchor.
 3. **"Add a daemon for performance"** — same; one-shot CLI is intentional, sub-100ms cold start makes a daemon unnecessary. Same non-goal anchor.
 4. **"Index this column"** in `src/db.ts` — Codemap's SQLite schema is intentionally lean. Indexes are added when a query benchmark proves them necessary, not pre-emptively. Push back: ask for the query that's slow.

.github/CONTRIBUTING.md

@@ -13,7 +13,7 @@ bun run dev   # same as `bun src/index.ts` — CLI from source
 bun test
 bun run test:golden   # golden SQL vs fixtures/minimal (also runs at end of `bun run check`)
 bun run test:golden:external   # Tier B: local tree via CODEMAP_ROOT / --root (not in CI)
-bun run check   # format + lint + tests + typecheck + build + test:golden
+bun run check   # build, then format:check + lint:ci + test + typecheck, then test:golden
 bun run clean   # remove untracked/ignored build artifacts (keeps `.env`, `.codemap/`)
 bun run check-updates   # interactive dependency updates (`bun update -i --latest`)
 ```
@@ -60,7 +60,9 @@ Releases: **[@changesets/cli](https://github.com/changesets/changesets)** — ru
 
 **Upstream** skill and rules in this repo (e.g. `codemap`) stay **generic** — placeholder SQL and triggers, no product-specific paths. Consumer projects can run **`codemap agents init`** (ships **`templates/agents`** on npm; see [docs/agents.md](../docs/agents.md)) or **copy/symlink** manually, then **edit their copy** for team aliases and queries. Customization always belongs in the **consumer** repo.
 
-Rules live under **`.agents/rules/`** as `.md` files; skills under **`.agents/skills/<name>/SKILL.md`**. Symlink into **`.cursor/`** with `.mdc` extension (Cursor requires `.mdc` for frontmatter parsing; see [agents-first-convention.md](../.agents/rules/agents-first-convention.md)):
+Rules live under **`.agents/rules/`** as `.md` files; skills under **`.agents/skills/<name>/SKILL.md`**. Symlink into **`.cursor/`** with `.mdc` extension (Cursor requires `.mdc` for frontmatter parsing; see [agents-first-convention.md](../.agents/rules/agents-first-convention.md)). Full rule inventory and tier system: [docs/agents.md](../docs/agents.md) and [agents-tier-system.md](../.agents/rules/agents-tier-system.md).
+
+Example minimum symlink set:
 
 ```bash
 mkdir -p .cursor/rules .cursor/skills
@@ -70,13 +72,4 @@ done
 ln -sf ../../.agents/skills/codemap .cursor/skills/codemap
 ```
 
-| Rule                         | Purpose                                   |
-| ---------------------------- | ----------------------------------------- |
-| `codemap.md`                 | Query SQLite index before structural grep |
-| `agents-first-convention.md` | `.agents/` source + `.cursor/` symlinks   |
-| `no-bypass-hooks.md`         | Never `--no-verify` on commit             |
-| `verify-after-each-step.md`  | Run checks between milestones             |
-| `tracer-bullets.md`          | Vertical slices end-to-end                |
-| `concise-reporting.md`       | Short agent replies                       |
-
 Thank you for helping make structural codebase queries fast and reusable for agents.

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,7 +4,7 @@
 
 ## Checklist
 
-- [ ] `bun run check` passes (format, lint, test, typecheck, build)
+- [ ] `bun run check` passes (build, format, lint, test, typecheck, golden queries)
 - [ ] User-facing change? **Add a [Changeset](https://github.com/changesets/changesets)** (`bun run changeset`) and commit the `.changeset/*.md` file
 - [ ] Docs updated if behavior or public API changed — hub: [`docs/README.md`](../docs/README.md); CLI/agents: [`docs/agents.md`](../docs/agents.md)