@ericrisco/rsc 0.1.27 → 0.1.29

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.27",
+  "version": "0.1.29",
   "counts": {
     "skills": 231
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/rsc.js

@@ -187,6 +187,26 @@ async function main() {
       for (const o of toOutcomes(ids)) say(`${o.id}\t${o.label}`);
       return;
     }
+    case 'catalog': {
+      // Full catalog dump for SEMANTIC in-agent discovery: every skill as
+      // `id  <installed|available>  short description`, unranked. `consult` ranks
+      // lexically and returns nothing for natural-language / Catalan intent; `catalog`
+      // hands the agent the whole candidate set so the MODEL picks the best-fit missing
+      // skill by meaning. `--available` drops what's already installed for this target.
+      const m = loadManifest();
+      const installed = new Set(listInstalled({ target }));
+      const onlyAvailable = argv.includes('--available');
+      const short = (d) => {
+        const s = String(d || '').split('. ')[0].replace(/\s+/g, ' ').trim();
+        return s.length > 160 ? `${s.slice(0, 159)}…` : s;
+      };
+      for (const sk of [...m.skills].sort((a, b) => a.id.localeCompare(b.id))) {
+        const state = installed.has(sk.id) ? 'installed' : 'available';
+        if (onlyAvailable && state === 'installed') continue;
+        say(`${sk.id}\t${state}\t${short(sk.description)}`);
+      }
+      return;
+    }
     case 'audit': {
       const report = audit();
       const written = writeAuditReport(report);

package/skills/agent-eval/SKILL.md

@@ -199,7 +199,7 @@ Pick by where the eval runs and what it must do. Versions as of 2026-06 — re-v
 
 ## Project grounding
 
-If the workspace has a `02-DOCS/` harness, record the eval policy in `02-DOCS/wiki/stack/evals.md`: dataset location, scorer mix, gate baseline file, judge model, and the failure modes covered. Link it from root `CLAUDE.md` under `## Knowledge map`. This is **recorded, not gated** — skip silently if there is no harness.
+If the workspace has a `02-DOCS/` harness, record the eval policy in `02-DOCS/wiki/stack/evals.md`: dataset location, scorer mix, gate baseline file, judge model, and the failure modes covered. Index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer). This is **recorded, not gated** — skip silently if there is no harness.
 
 ## verify.sh
 

package/skills/analyze/SKILL.md

@@ -53,7 +53,7 @@ If no profile exists, default to L2 and note that the harness has not gauged the
 
 ## Inputs — locate the four artifacts
 
-Read all four before analyzing. The rsc-sdd artifacts live under `02-DOCS/wiki/sdd/` (the harness Karpathy-wiki convention), indexed from the root `CLAUDE.md` `## Knowledge map`:
+Read all four before analyzing. The rsc-sdd artifacts live under `02-DOCS/wiki/sdd/` (the harness Karpathy-wiki convention), indexed from `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it):
 
 | Artifact | Canonical location | Role in the check |
 | --- | --- | --- |
@@ -111,7 +111,7 @@ Produce a single consistency report:
 3. **Findings table** — `# | Severity | Type | Artifact A (loc) | Artifact B (loc) | Conflict | Resolve in (phase)`.
 4. **Recommended routing** — group fixes by the phase that owns them (`clarify` for spec ambiguity, `plan` for missing architecture, `tasks` for a missing done-check, `constitution` if a principle itself is wrong).
 
-Write the report to `02-DOCS/wiki/sdd/analysis/<slug>.md` (create the dir if absent) and add/refresh its row in the root `CLAUDE.md` `## Knowledge map` under the `sdd/` topic, so the next phase and the harness can find it. The report is the artifact analyze owns — it is the *only* thing analyze writes. Per-run point-in-time; overwrite on re-run, the wiki keeps history.
+Write the report to `02-DOCS/wiki/sdd/analysis/<slug>.md` (create the dir if absent) and index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic, so the next phase and the harness can find it. The report is the artifact analyze owns — it is the *only* thing analyze writes. Per-run point-in-time; overwrite on re-run, the wiki keeps history.
 
 Adapt the rendered verbosity to the dial (L0 = table only; L3 = full walk-through). Do not log a decision to `decisions.md` — analyze decides nothing; the phase that resolves the finding logs its own decision.
 

package/skills/author-skill/SKILL.md

@@ -124,7 +124,7 @@ Run in order. Each step gates the next.
 4. **Write the body** in the rsc voice (see below). Tag every code/example fence with a language. Add a copy-able checklist or decision table *only where the flow actually branches* — not as decoration. Add a short anti-patterns table.
 5. **Extract references** for anything long or branch-specific.
 6. **Write the evals** — `cases.yaml` then `README.md`. → `references/eval-authoring.md`.
-7. **Wire it into the rsc plumbing** (`tags`, `recommends`, `npm run manifest`, Knowledge map). → `references/rsc-conventions.md`.
+7. **Wire it into the rsc plumbing** (`tags`, `recommends`, `npm run manifest`, and indexing any artifact in `02-DOCS/wiki/index.md` — the Knowledge map; root `CLAUDE.md` keeps only a short pointer). → `references/rsc-conventions.md`.
 8. **Self-audit against the rubric** (below). Fix every miss or justify it.
 
 ## The rsc voice
@@ -149,7 +149,7 @@ A skill ships only when every box is checked or a miss is consciously justified.
 - [ ] **Every fence language-tagged**; no placeholder/TODO prose; examples concrete.
 - [ ] **Checklist/decision table only where a flow branches**; an **anti-patterns table** present.
 - [ ] **Accompaniment dial honored** — reads the profile, adapts verbosity.
-- [ ] **Artifacts under `02-DOCS/wiki/`** and indexed in the root CLAUDE.md Knowledge map, if the skill produces any.
+- [ ] **Artifacts under `02-DOCS/wiki/`** and indexed in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer), if the skill produces any.
 - [ ] **Concrete tooling delegated** to the stack skills rather than reinvented.
 - [ ] **evals present** — `cases.yaml` (≥5 `should_trigger` incl. non-obvious, ≥4 `should_not_trigger` each with a real-sibling `route_to`, ≥1 `capability` with a `must_include` rubric) + an honest `README.md`. `scripts/eval-lint.sh` passes — but it only checks presence and the counts (≥5/≥4/≥1) and that those keys are lists; the `route_to`-points-at-a-real-sibling, non-obvious phrasings, and `must_include` quality are yours to verify here, not the linter's.
 - [ ] **verify.sh** present iff the skill has a checkable artifact; process skills rely on evals.
@@ -195,7 +195,7 @@ only when **both** are green:
 
 ## Project grounding (02-DOCS + CLAUDE.md)
 
-When authoring produces a durable design note (a skill's scope decision, a description rationale worth keeping), persist it under `02-DOCS/wiki/sdd/` and add a row to the root CLAUDE.md `## Knowledge map`, per the `../harness/SKILL.md` convention — never a stray file at the repo root. The skill's own `evals/` is the executable record of intent; the wiki note is the human-readable why.
+When authoring produces a durable design note (a skill's scope decision, a description rationale worth keeping), persist it under `02-DOCS/wiki/sdd/` and index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer), per the `../harness/SKILL.md` convention — never a stray file at the repo root. The skill's own `evals/` is the executable record of intent; the wiki note is the human-readable why.
 
 ## See Also
 

package/skills/building-agents/SKILL.md

@@ -449,14 +449,12 @@ if __name__ == "__main__":
 
 When this skill runs in a project with a `02-DOCS/` layer (the
 [`harness`](../harness/SKILL.md) Karpathy wiki), record this
-project's agent decisions there and index them from the root `CLAUDE.md`, so the next
+project's agent decisions there and index them in `02-DOCS/wiki/index.md`, so the next
 agent inherits the conventions instead of re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/agents.md`, linked from a `## Knowledge map` section in the root
-   `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/agents.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — the provider(s) and model routing, where the provider adapter lives, tool/RAG conventions, the eval gates, and the observability backend —
-   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
-   `CLAUDE.md` itself, if absent).
+   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the
    article (bump its `Updated` date) in the same change.
 

package/skills/constitution/SKILL.md

@@ -13,7 +13,7 @@ origin: risco
 
 A constitution is small, durable, and enforceable. It is **not** a wiki of everything you know about the project (that is what `02-DOCS/wiki/` already is, run by the `harness`). It is the short list of principles that, if violated, mean the work is wrong regardless of whether it runs. If a rule here cannot be checked or pointed at later, it does not belong here — move it to the stack wiki and link it.
 
-This skill produces `02-DOCS/wiki/sdd/constitution.md` and one Knowledge-map row in the root `CLAUDE.md`. It reconciles with — never duplicates — the stack conventions the harness keeps under `02-DOCS/wiki/stack/*`.
+This skill produces `02-DOCS/wiki/sdd/constitution.md` and one Knowledge-map row. The constitution is one of the few **read-first** pointer entries kept directly in the root `CLAUDE.md` `## Knowledge map` (everything else lives in `02-DOCS/wiki/index.md`, the full Knowledge map that root `CLAUDE.md` points to). It reconciles with — never duplicates — the stack conventions the harness keeps under `02-DOCS/wiki/stack/*`.
 
 ## Model tier — `heavy` (opt-in routing)
 
@@ -52,7 +52,7 @@ Do NOT use when (route instead):
 
 The harness may already hold real conventions under `02-DOCS/wiki/stack/*` (e.g. `nextjs.md`, `fastapi.md`, `postgresdb.md`). The constitution does not copy them — it **ratifies the principle and links the detail**. Run this reconciliation pass first:
 
-1. **Read the Knowledge map** in the root `CLAUDE.md`. List every `02-DOCS/wiki/stack/*` article that exists.
+1. **Read the Knowledge map** — the full index lives in `02-DOCS/wiki/index.md` (root `CLAUDE.md` keeps only a short pointer to it). List every `02-DOCS/wiki/stack/*` article that exists.
 2. **Read each stack article.** Pull out anything already phrased as a rule (a version pin, a lint config, a test threshold, a naming convention).
 3. **For each existing rule, decide:** is it a *project-wide non-negotiable* (→ ratify it as a principle, linking the stack article for detail) or a *local mechanic* (→ leave it in the stack wiki, do not lift it into the constitution)?
 4. **Contradictions are findings, not fixes.** If two stack articles disagree, or a stack article contradicts what the user states now, surface it and let the user resolve — never silently pick a winner.
@@ -137,12 +137,12 @@ The constitution is versioned so `analyze` and `review` can cite "constitution v
 - [ ] The Definition-of-Done checklist is present (what `verify` runs against).
 - [ ] Fixed principles included: human git authorship + decisions logged.
 - [ ] `02-DOCS/wiki/sdd/constitution.md` written with version + ratified date + amendment log.
-- [ ] Root `CLAUDE.md` Knowledge map has a row for the constitution (additive only — never delete sections).
+- [ ] Root `CLAUDE.md` `## Knowledge map` pointer has the read-first row for the constitution (it is one of the few entries kept in root `CLAUDE.md`; the full index lives in `02-DOCS/wiki/index.md`). Additive only — never delete sections.
 - [ ] The constitution was shown to the user and explicitly ratified.
 
 ## Project grounding (02-DOCS + CLAUDE.md)
 
-This skill's `02-DOCS` record is the constitution at `02-DOCS/wiki/sdd/constitution.md`, linked from a `## Knowledge map` row in the root `CLAUDE.md` (create `CLAUDE.md` if absent, additive only — never delete existing sections). Add this row if it is not already present:
+This skill's `02-DOCS` record is the constitution at `02-DOCS/wiki/sdd/constitution.md`. It is a **read-first** pointer entry, so its row stays in the short `## Knowledge map` pointer in the root `CLAUDE.md` (create `CLAUDE.md` if absent, additive only — never delete existing sections) — unlike other sdd artifacts, which are indexed in `02-DOCS/wiki/index.md` (the full Knowledge map that root `CLAUDE.md` points to). Add this row to the root pointer if it is not already present:
 
 ```markdown
 | Project constitution (SDD non-negotiables) | `02-DOCS/wiki/sdd/constitution.md` |
@@ -159,6 +159,6 @@ The constitution is the guardrail; now describe what to build. Hand off to **`..
 - `../sdd/SKILL.md` — the rsc-sdd dispatcher: the method, the phase map, the invoke rule.
 - `../specify/SKILL.md` — the next phase: intent → spec.
 - `../analyze/SKILL.md` — the consistency gate that checks specs/plans against this constitution.
-- `harness` — owns `02-DOCS/wiki/` (including `wiki/stack/*` and the Knowledge map this skill reconciles with and links into).
+- `harness` — owns `02-DOCS/wiki/` (including `wiki/stack/*` and the full Knowledge map at `02-DOCS/wiki/index.md` this skill reconciles with; the constitution's read-first row stays in the root `CLAUDE.md` pointer).
 - Stack skills the constitution *names but does not duplicate*: `../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`, `../design/SKILL.md`, `../secure-coding/SKILL.md`.
 - References: `references/constitution-template.md`.

package/skills/continuous-learning/SKILL.md

@@ -92,7 +92,7 @@ Copy-pasteable and **situation-tagged**, so it retrieves on the trigger that mat
 - **We believed:** <the wrong assumption>
 - **Actually:** <what is true>
 - **Durable home:** <path + surface that now holds it>
-- **Fires next time via:** <rule / eval / verify.sh / Knowledge-map entry>
+- **Fires next time via:** <rule / eval / verify.sh / index entry in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer)>
 ```
 
 The last two lines are not optional. An entry with no durable home and no "fires next time" is a chat message with a date on it.
@@ -104,7 +104,7 @@ This is the rigor of this process skill, and it stands in for a `verify.sh` (thi
 - a rule the agent reads on its next pass (`CLAUDE.md` or a skill body), or
 - an eval case (`should_not_trigger` / `should_trigger`) that would have caught the miss, or
 - a `verify.sh` check on the owning skill that fails on the banned pattern, or
-- a `## Knowledge map` entry pointing at the new wiki article.
+- a `02-DOCS/wiki/index.md` entry (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) pointing at the new wiki article.
 
 If you cannot name one of those, the lesson is not captured — keep going. Prefer a surface a human can review (a rule, an eval, a profile line) over an opaque store: a single agent reflecting alone can talk itself into a local optimum, so the durable write should be legible enough for a human to sanity-check.
 

package/skills/coolify/SKILL.md

@@ -186,14 +186,13 @@ live deploy. Exits 0 on a clean/empty target.
 ## Project grounding (02-DOCS + CLAUDE.md)
 
 When this skill runs in a project with a `02-DOCS/` layer (the harness Karpathy wiki), record this
-instance's deploy topology there and index it from the root `CLAUDE.md`, so the next agent inherits it
+instance's deploy topology there and index it in `02-DOCS/wiki/index.md`, so the next agent inherits it
 instead of re-deriving it.
 
-1. **Find the article** `02-DOCS/wiki/stack/coolify.md`, linked from a `## Knowledge map` section in the
-   root `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/coolify.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the real choices — the box (provider/specs), instance
    FQDN, which apps/databases run on it, build packs in use, the backup destination + cron + retention,
-   and the port/firewall decisions — then add/refresh the `CLAUDE.md` link.
+   and the port/firewall decisions — then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
 3. **Read it first on every use** and stay consistent; when the topology changes, update the article (bump
    its `Updated` date) in the same change. Never commit credentials here — record *where* secrets live,
    not their values.

package/skills/course-storytelling/SKILL.md

@@ -37,13 +37,13 @@ Do NOT use when (delegate or decline):
 
 Run this gate before reframing a single concept:
 
-1. **Locate the teaching profile.** Read the project's root `CLAUDE.md` and look for a `## Knowledge map` section linking into `02-DOCS/wiki/teaching/` (the `harness` Karpathy-wiki convention: compiled profile articles live under `02-DOCS/wiki/teaching/`, raw inputs the user pastes live under `02-DOCS/raw/teaching/`). If `CLAUDE.md` is absent, the link is missing, or it points nowhere, treat the profile as ABSENT.
+1. **Locate the teaching profile.** Read the project's root `CLAUDE.md` and follow its short `## Knowledge map` pointer to the full index at `02-DOCS/wiki/index.md`, looking for the entry into `02-DOCS/wiki/teaching/` (the `harness` Karpathy-wiki convention: compiled profile articles live under `02-DOCS/wiki/teaching/`, raw inputs the user pastes live under `02-DOCS/raw/teaching/`). If `CLAUDE.md` is absent, the index entry is missing, or it points nowhere, treat the profile as ABSENT.
 
 2. **Check completeness** against the checklist in `references/learner-grounding.md`. The profile is complete only when every dimension is filled: the LEARNER (level, prior knowledge, pains, desires, current false beliefs, what they want to DO after); the AUDIENCE (same as the buyer or not? live vs recorded? size? context?); the target TRANSFORMATION (the one result, before→after); and constraints/format. **Any empty dimension = INCOMPLETE.**
 
 3. **If ABSENT or INCOMPLETE, STOP and interview the user.** Ask the question script from `references/learner-grounding.md`, **one focused batch at a time** (do not dump all questions at once; ask, wait, persist, then continue). Then:
    - **a.** Write/update the profile into `02-DOCS/wiki/teaching/` as wiki articles (`learner.md`, `audience.md`, `transformation.md`, `false-beliefs.md`, `constraints.md`, plus an `index.md`), following the article format in `references/learner-grounding.md`. Save any raw material the user pastes (transcripts, outlines, existing slides) verbatim into `02-DOCS/raw/teaching/` and link it from the article's `> Raw:` line. Create the directories if they do not exist.
-   - **b.** Add or update a `## Knowledge map` section in the root `CLAUDE.md` linking to the teaching profile. Create `CLAUDE.md` if absent (additive only — never delete existing sections). The exact snippet is in `references/learner-grounding.md`.
+   - **b.** Index the teaching profile in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer). Ensure root `CLAUDE.md` carries that short pointer to the index, creating `CLAUDE.md` if absent (additive only — never delete existing sections). The exact snippet is in `references/learner-grounding.md`.
 
 4. **Only once the profile exists and is complete, proceed.** Cite which articles you used (e.g. "grounded in `02-DOCS/wiki/teaching/learner.md` and `false-beliefs.md`") so every reframing is traceable to a real learner, not an imagined one.
 
@@ -188,12 +188,12 @@ Automate → `scripts/verify.sh` (read-only; warns by default, `--strict` to gat
 
 ## Project grounding (02-DOCS + CLAUDE.md)
 
-This skill's 02-DOCS record has two parts, both indexed from a `## Knowledge map` section in the root `CLAUDE.md`:
+This skill's 02-DOCS record has two parts, both indexed in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer):
 
-- The **learner + audience profile** at `02-DOCS/wiki/teaching/` — a hard gate (see "Learner grounding" above): if the root `CLAUDE.md` lacks the link or any dimension is empty (learner, audience, transformation, false beliefs, constraints), ask until complete, persist it (raw inputs to `02-DOCS/raw/teaching/`), link it from `## Knowledge map` (create `CLAUDE.md` if absent), and only then teach.
+- The **learner + audience profile** at `02-DOCS/wiki/teaching/` — a hard gate (see "Learner grounding" above): if the index lacks the entry or any dimension is empty (learner, audience, transformation, false beliefs, constraints), ask until complete, persist it (raw inputs to `02-DOCS/raw/teaching/`), index it in `02-DOCS/wiki/index.md` and ensure root `CLAUDE.md` carries the short pointer to that index (create `CLAUDE.md` if absent), and only then teach.
 - The **course teaching conventions** at `02-DOCS/wiki/stack/course-storytelling.md` (or alongside the profile under `02-DOCS/wiki/teaching/`) — the established narrative spine, the named mental models already coined, the Big Dominoes per module, and the teacher's Attractive Character. Recorded, not gated.
 
-Create/update both as decisions are made and refresh their `CLAUDE.md` links. Read them first on every use and keep every reframing consistent with them. If the project has no `02-DOCS` layer at all, skip this section silently and proceed with the in-session profile.
+Create/update both as decisions are made and keep their entries current in `02-DOCS/wiki/index.md` (root `CLAUDE.md` keeps only a short pointer to it). Read them first on every use and keep every reframing consistent with them. If the project has no `02-DOCS` layer at all, skip this section silently and proceed with the in-session profile.
 
 ## See Also
 

package/skills/cpp/SKILL.md

@@ -314,15 +314,13 @@ bad index is UB, not an exception.
 ## Project grounding (02-DOCS + CLAUDE.md)
 
 When this skill runs in a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md)
-Karpathy wiki), record this project's C++ decisions there and index them from the root `CLAUDE.md`,
+Karpathy wiki), record this project's C++ decisions there and index them in `02-DOCS/wiki/index.md`,
 so the next agent inherits them instead of re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/cpp.md`, linked from a `## Knowledge map` section in
-   the root `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/cpp.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — std version and
    compiler matrix, CMake layout and presets, the sanitizer/warning policy, and the ownership/error
-   conventions — then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
-   `CLAUDE.md` itself, if absent).
+   conventions — then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the article
    (bump its `Updated` date) in the same change.
 

package/skills/decision-records/SKILL.md

@@ -40,7 +40,7 @@ Prefer **numeric-prefix**: `NNNN-title-with-dashes.md`. Stable IDs are what make
 **Where to store** (first match wins):
 1. The project's existing convention — never invent a parallel log.
 2. A code repo with no convention: `docs/adr/` (also seen as `doc/adr/`).
-3. A harness workspace: `02-DOCS/wiki/decisions/`, linked from the wiki knowledge map.
+3. A harness workspace: `02-DOCS/wiki/decisions/`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer).
 
 ```text
 Bad:  decision-final-v2-REAL.md          # no ID, no order, will rot
@@ -169,7 +169,7 @@ A decision log is only useful if it stays navigable.
 - **Index every ADR at creation.** One row: `| 0007 | Choose Postgres | accepted | 2026-06-02 |`. No orphans.
 - **Keep supersession links live** in both directions.
 - **Review cadence.** Periodically sweep `accepted` ADRs — anything reality has overtaken gets a superseding record, not a silent edit.
-- **Link the log from the entry point** — root `CLAUDE.md` or the wiki knowledge map — so onboarding finds it. The broader wiki and onboarding doc are owned by `knowledge-ops` and `codebase-onboarding`; this skill owns only the ADRs the wiki links to. The meeting that spawned a decision routes to [`meeting-notes`](../meeting-notes/SKILL.md); the repeatable how-to it implies routes to [`sop-builder`](../sop-builder/SKILL.md).
+- **Index the log from the entry point** — `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) — so onboarding finds it. The broader wiki and onboarding doc are owned by `knowledge-ops` and `codebase-onboarding`; this skill owns only the ADRs the wiki links to. The meeting that spawned a decision routes to [`meeting-notes`](../meeting-notes/SKILL.md); the repeatable how-to it implies routes to [`sop-builder`](../sop-builder/SKILL.md).
 
 ## Anti-patterns
 

package/skills/deployment/SKILL.md

@@ -409,14 +409,12 @@ async def readyz() -> dict[str, str]:
 
 When this skill runs in a project with a `02-DOCS/` layer (the
 [`harness`](../harness/SKILL.md) Karpathy wiki), record this
-project's deploy decisions there and index them from the root `CLAUDE.md`, so the next
+project's deploy decisions there and index them in `02-DOCS/wiki/index.md`, so the next
 agent inherits the conventions instead of re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/deployment.md`, linked from a `## Knowledge map` section in the root
-   `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/deployment.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — the base-image/container choices, the CI pipeline, the Coolify/target config, the secrets flow, and the rollback strategy —
-   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
-   `CLAUDE.md` itself, if absent).
+   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the
    article (bump its `Updated` date) in the same change.
 

package/skills/design/SKILL.md

@@ -368,8 +368,8 @@ Score = Σ(dimension × weight), max 115 (normalize to /100 by ×100/115 if you
 
 ## Project grounding (02-DOCS + CLAUDE.md)
 
-This skill's 02-DOCS record has two parts, both indexed from a `## Knowledge map` section in
-the root `CLAUDE.md`:
+This skill's 02-DOCS record has two parts, both indexed in `02-DOCS/wiki/index.md` (the Knowledge
+map index; root `CLAUDE.md` points to it):
 
 - The **brand study** at `02-DOCS/wiki/brand/` — a hard gate (see "Brand grounding" above): if
   missing or incomplete, ask until complete before designing.
@@ -377,8 +377,8 @@ the root `CLAUDE.md`:
   (color/OKLCH, type scale, spacing, radius, shadow, motion), the 2026 direction picked, and the
   reference sites. Recorded, not gated.
 
-Create/update both as decisions are made and add/refresh their `CLAUDE.md` links (create the
-`## Knowledge map` section, and `CLAUDE.md` itself, if absent). Read them first on every use and
+Create/update both as decisions are made and index them in `02-DOCS/wiki/index.md` (the Knowledge map;
+root `CLAUDE.md` keeps only a short pointer to it). Read them first on every use and
 keep outputs consistent with them.
 
 ## See Also

package/skills/duckdb/SKILL.md

@@ -203,5 +203,6 @@ version. If neither the CLI nor the Python module is present it prints `SKIP` an
 
 In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), record this project's
 DuckDB decisions — version pin, file layout, persistent vs in-memory, remote/secret setup — in
-`02-DOCS/wiki/stack/duckdb.md` and link it from the root `CLAUDE.md` `## Knowledge map`. Read it first on
+`02-DOCS/wiki/stack/duckdb.md` and index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md`
+keeps only a short pointer to it). Read it first on
 every use and keep choices consistent. No `02-DOCS/`? Skip silently. Conventions are recorded, never gated.

package/skills/fastapi/SKILL.md

@@ -480,14 +480,14 @@ shutdown, keyset pagination, caching, `ORJSONResponse` and proxy headers all liv
 
 When this skill runs in a project with a `02-DOCS/` layer (the
 [`harness`](../harness/SKILL.md) Karpathy wiki), record this project's API decisions in
-`02-DOCS/wiki/stack/fastapi.md` and link it from a `## Knowledge map` section in the root
-`CLAUDE.md`, so the next agent inherits the conventions instead of re-deriving them.
+`02-DOCS/wiki/stack/fastapi.md` and index it in `02-DOCS/wiki/index.md` (the Knowledge map index; root
+`CLAUDE.md` points to it), so the next agent inherits the conventions instead of re-deriving them.
 
 - **Read it first** on every use and stay consistent; bump its `Updated` date when a
   convention changes.
 - **Create/update it** with the project's real choices — auth model (JWT/OAuth2 provider,
   token TTLs), DB session + migration tool, error-envelope shape, settings/secrets approach,
-  deployment target — adding the `CLAUDE.md` link (and the file) if absent.
+  deployment target — indexing it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it) if absent.
 
 No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Technical conventions are
 *recorded, not gated* — never block the task on this.

package/skills/flutter/SKILL.md

@@ -423,14 +423,12 @@ encapsulation → `references/i18n-and-dependencies.md`.
 
 When this skill runs in a project with a `02-DOCS/` layer (the
 [`harness`](../harness/SKILL.md) Karpathy wiki), record this
-project's app decisions there and index them from the root `CLAUDE.md`, so the next
+project's app decisions there and index them in `02-DOCS/wiki/index.md`, so the next
 agent inherits the conventions instead of re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/flutter.md`, linked from a `## Knowledge map` section in the root
-   `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/flutter.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — the state-management choice (Riverpod/Bloc), the architecture layers, routing, the Material 3 token system, and codegen setup —
-   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
-   `CLAUDE.md` itself, if absent).
+   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the
    article (bump its `Updated` date) in the same change.
 

package/skills/go/SKILL.md

@@ -411,14 +411,12 @@ Docker note: distroless/static base, `CGO_ENABLED=0`, multi-stage build. Full Co
 
 When this skill runs in a project with a `02-DOCS/` layer (the
 [`harness`](../harness/SKILL.md) Karpathy wiki), record this
-project's service decisions there and index them from the root `CLAUDE.md`, so the next
+project's service decisions there and index them in `02-DOCS/wiki/index.md`, so the next
 agent inherits the conventions instead of re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/go.md`, linked from a `## Knowledge map` section in the root
-   `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/go.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — the project layout, the router (stdlib 1.22 / chi), the error and `slog` logging conventions, and concurrency/timeout defaults —
-   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
-   `CLAUDE.md` itself, if absent).
+   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the
    article (bump its `Updated` date) in the same change.
 

package/skills/harness/SKILL.md

@@ -276,6 +276,31 @@ Once the structure stands, make sure the workspace has the rsc skills its stack
    Can't run a shell? Print the exact command for another terminal tab.
 3. **Flag the new session.** New skills load at session start — tell the user to open a **new tab/session** (or reload Cursor/Codex/Gemini) in this folder for them to activate. Log the installed set in `02-DOCS/wiki/harness/decisions.md`.
 
+## Keep CLAUDE.md lean — the index lives in the wiki
+
+Root `CLAUDE.md` is read on **every** turn, so every line is a permanent context tax (2026 best
+practice: keep it **under ~200 lines**; beyond that, adherence rots as the rules that matter get
+diluted by an index nobody needs in context). The biggest growth vector is the `## Knowledge map` —
+a row per wiki article, appended by many skills, forever.
+
+**The rule:** the **full** Knowledge map lives in `02-DOCS/wiki/index.md` (loaded on demand, grows
+freely). Root `CLAUDE.md`'s `## Knowledge map` is a **short pointer** — only the read-first entries
+(`harness/user-profile.md`, `sdd/constitution.md`) plus "full index → `02-DOCS/wiki/index.md`".
+
+**Offload when it bloats (a move, never a trim — no info lost):** when `CLAUDE.md` passes ~200 lines
+(the SessionStart hook nudges you) or its `## Knowledge map` has grown past the read-first entries:
+
+1. Open `02-DOCS/wiki/index.md` (create it if absent).
+2. **Move** every Knowledge-map row beyond the read-first entries from `CLAUDE.md` into
+   `02-DOCS/wiki/index.md`, merging — don't duplicate, don't delete.
+3. Leave `CLAUDE.md`'s `## Knowledge map` as the short pointer above.
+4. Same for any other section overgrown into an index (e.g. a huge tool table): detail to the wiki,
+   pointer stays.
+
+From then on, **new index entries go to `02-DOCS/wiki/index.md`**, not `CLAUDE.md`. This is additive
+and reversible; it honors the "never delete user content" rule (you relocate it, with a pointer).
+Opt out of the size nudge with `.rsc/.no-claudemd-check`.
+
 ## Iron rules (non-negotiable)
 
 These rules cut across every phase. Violating any one of them aborts the run.

package/skills/harness/references/claude-md-template.md

@@ -14,32 +14,19 @@ workspace. If you're working in a subproject that also has its own
 
 ## Knowledge map
 
-The living record of this project's conventions lives under `02-DOCS/wiki/` and is maintained by
-the stack skills, plus the `harness/` topic maintained by the harness itself (user profile +
-decisions log). Each skill links its article here as it is created — read the relevant article
-before working in its area (the `harness/user-profile.md` first, to match the user's technical +
-accompaniment level), and update it when conventions change.
+The **full** index of this project's conventions lives in **`02-DOCS/wiki/index.md`** — maintained by
+the stack skills plus the `harness/` topic. Read the relevant article before working in its area, and
+update it when conventions change. Keep this section a **short pointer**: CLAUDE.md is read on every
+turn, so the full per-area table belongs in `02-DOCS/wiki/index.md`, not here. New index entries go
+there, not into this file.
+
+Read first, always:
 
 | Area | Article |
 |------|---------|
 | User profile (technical + accompaniment level) | `02-DOCS/wiki/harness/user-profile.md` |
-| Decisions log (append-only, "siempre 3 opciones") | `02-DOCS/wiki/harness/decisions.md` |
 | SDD constitution (project non-negotiables) | `02-DOCS/wiki/sdd/constitution.md` |
-| SDD specs (what & why, per feature) | `02-DOCS/wiki/sdd/specs/` |
-| SDD plans (technical approach, per feature) | `02-DOCS/wiki/sdd/plans/` |
-| SDD decisions (implement-phase log) | `02-DOCS/wiki/sdd/decisions.md` |
-| Brand & voice | `02-DOCS/wiki/brand/` |
-| Design system | `02-DOCS/wiki/stack/design.md` |
-| FastAPI / API | `02-DOCS/wiki/stack/fastapi.md` |
-| Next.js app | `02-DOCS/wiki/stack/nextjs.md` |
-| Go services | `02-DOCS/wiki/stack/go.md` |
-| PostgreSQL | `02-DOCS/wiki/stack/postgresdb.md` |
-| Flutter app | `02-DOCS/wiki/stack/flutter.md` |
-| Agents | `02-DOCS/wiki/stack/agents.md` |
-| Security | `02-DOCS/wiki/stack/security.md` |
-| Deployment | `02-DOCS/wiki/stack/deployment.md` |
-| Presentations | `02-DOCS/wiki/stack/presentations.md` |
-| Course storytelling | `02-DOCS/wiki/stack/course-storytelling.md` |
+| **Everything else — full index** | `02-DOCS/wiki/index.md` |
 
 ## Workspace map
 

package/skills/implement/SKILL.md

@@ -180,7 +180,7 @@ done-checks, the constitution and decision logging hold at every level, includin
 
 When you make a choice the plan did not fully specify — a library, a data shape, an error contract, a
 deviation from the plan — append it to `02-DOCS/wiki/sdd/decisions.md` (append-only; create it if
-absent and add a row to the root `CLAUDE.md` `## Knowledge map` under the `sdd/` topic). One entry:
+absent and index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic). One entry:
 
 ```text
 ## YYYY-MM-DD — <short title>  (feature: <slug>, task: <n>)

package/skills/init/SKILL.md

@@ -51,7 +51,7 @@ Before discovery, before any recommendation, write the profile to `02-DOCS` and
 
 - `02-DOCS/wiki/harness/user-profile.md` — the living profile (technical level, accompaniment level, goals, context, constraints). Format in `references/accompaniment-and-profile.md`.
 - `02-DOCS/wiki/harness/decisions.md` — an **append-only** decisions log. Every significant decision gets one entry, never edited or deleted. Format in `references/accompaniment-and-profile.md`.
-- Root `CLAUDE.md` → a `## Knowledge map` section linking to BOTH files. Create `CLAUDE.md` if absent (additive only — never delete existing sections).
+- Root `CLAUDE.md` → a SHORT `## Knowledge map` pointer: the read-first entries (this `user-profile.md` and the `decisions.md` log) plus a "full index → `02-DOCS/wiki/index.md`" line. Keep this pointer tiny — it loads on every turn; ALL other index entries live in `02-DOCS/wiki/index.md`, not here. Create `CLAUDE.md` if absent (additive only — never delete existing sections).
 
 If `02-DOCS/` does not yet exist (greenfield), create `02-DOCS/wiki/harness/` now — just enough to hold these two files. That, plus the `CLAUDE.md` Knowledge-map link, is everything `init` writes; ALL other `01-TOOLS/` + `02-DOCS/` scaffolding is the `harness` skill's job.
 
@@ -196,7 +196,7 @@ These thoughts mean the skill is about to break its own rules. Recognize and abo
 
 ## Project grounding (02-DOCS + CLAUDE.md)
 
-This skill's `02-DOCS` record is the **user profile** at `02-DOCS/wiki/harness/user-profile.md` plus the append-only **decisions log** at `02-DOCS/wiki/harness/decisions.md`. Both are written in Phase 1 and updated throughout, and both are linked from a `## Knowledge map` section in the root `CLAUDE.md` (created if absent, additive only). Every rsc skill reads the profile first and adapts its verbosity and question count to `accompaniment_level` and `technical_level`. Those two files plus the Knowledge-map link are everything `init` writes; ALL other `01-TOOLS/` + `02-DOCS/` scaffolding is the `harness` skill's job, and it reads this same profile.
+This skill's `02-DOCS` record is the **user profile** at `02-DOCS/wiki/harness/user-profile.md` plus the append-only **decisions log** at `02-DOCS/wiki/harness/decisions.md`. Both are written in Phase 1 and updated throughout. Because they are the read-first entries, both stay in the SHORT `## Knowledge map` pointer in the root `CLAUDE.md` (created if absent, additive only) — alongside a "full index → `02-DOCS/wiki/index.md`" line where every OTHER index entry lives. Every rsc skill reads the profile first and adapts its verbosity and question count to `accompaniment_level` and `technical_level`. Those two files plus the Knowledge-map link are everything `init` writes; ALL other `01-TOOLS/` + `02-DOCS/` scaffolding is the `harness` skill's job, and it reads this same profile.
 
 Verify the profile and the Knowledge-map link exist with `scripts/verify.sh` (read-only; warns, never fails).
 

package/skills/java/SKILL.md

@@ -303,13 +303,13 @@ When this skill runs in a project with a `02-DOCS/` layer (the
 [`harness`](../harness/SKILL.md) Karpathy wiki), record this project's Java decisions there
 and index them from the root `CLAUDE.md`, so the next agent inherits them instead of re-deriving.
 
-1. **Find the article** `02-DOCS/wiki/stack/java.md`, linked from a `## Knowledge map` section
-   in the root `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/java.md`, indexed in `02-DOCS/wiki/index.md` (the
+   Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — JDK/LTS target,
    Maven vs Gradle, the domain-modeling conventions (records/sealed), the concurrency model
    (virtual threads, structured-concurrency preview on/off), and the error/null conventions —
-   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section and `CLAUDE.md`
-   itself if absent).
+   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a
+   short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the
    article (bump its `Updated` date) in the same change.
 

package/skills/marketing/SKILL.md

@@ -221,9 +221,9 @@ Automate → `scripts/verify.sh` (read-only grep gate; warns by default, `--stri
 This skill's 02-DOCS record is the **brand & voice study** at `02-DOCS/wiki/brand/` — a hard
 gate (see "Brand grounding" above): if the root `CLAUDE.md` lacks the link or the study is
 incomplete (no voice samples, positioning, do/don't lists), ask until complete, persist it, and
-link it from a `## Knowledge map` section in `CLAUDE.md` (create `CLAUDE.md` if absent). Read it
-first on every use and ground all copy in it. Site and visual conventions belong to the sibling
-`design` and `nextjs` articles in the same Knowledge map.
+index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short
+pointer to it). Read it first on every use and ground all copy in it. Site and visual conventions
+belong to the sibling `design` and `nextjs` articles in the same Knowledge map index.
 
 ## See Also
 

package/skills/modal/SKILL.md

@@ -296,7 +296,8 @@ exits 0.
 
 In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), record this
 app's real Modal choices — GPU types, image base, Volume names, schedule, endpoint shape — in
-`02-DOCS/wiki/stack/modal.md` and link it from the root `CLAUDE.md` `## Knowledge map`. Read it
+`02-DOCS/wiki/stack/modal.md` and index it in `02-DOCS/wiki/index.md` (the Knowledge map; root
+`CLAUDE.md` keeps only a short pointer to it). Read it
 first on every use; create/update it with the real decisions. No `02-DOCS/`? Skip silently.
 
 ## See Also

package/skills/mongodb/SKILL.md

@@ -311,12 +311,12 @@ When this skill runs in a project with a `02-DOCS/` layer (the [`harness`](../ha
 Karpathy wiki), record this project's MongoDB decisions there and index them from the root
 `CLAUDE.md`, so the next agent inherits the conventions instead of re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/mongodb.md`, linked from a `## Knowledge map` section in
-   the root `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/mongodb.md`, indexed in `02-DOCS/wiki/index.md` (the
+   Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — collection layout and
    embed/reference decisions, the index set and its ESR rationale, read/write concern policy, the
-   Atlas tier, and any encryption/RBAC setup — then add/refresh the `CLAUDE.md` link (create the
-   `## Knowledge map` section, and `CLAUDE.md` itself, if absent).
+   Atlas tier, and any encryption/RBAC setup — then index it in `02-DOCS/wiki/index.md` (the
+   Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the article
    (bump its `Updated` date) in the same change.
 

package/skills/nextjs/SKILL.md

@@ -454,11 +454,11 @@ When this skill runs in a project with a `02-DOCS/` layer (the
 project's app decisions there and index them from the root `CLAUDE.md`, so the next
 agent inherits the conventions instead of re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/nextjs.md`, linked from a `## Knowledge map` section in the root
-   `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/nextjs.md`, indexed in `02-DOCS/wiki/index.md` (the
+   Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — the caching model in use (v15 fetch-cache vs v16 `use cache`), the auth approach, server-action and data-fetching conventions, runtime choices (edge/node), and the design-system hookup —
-   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
-   `CLAUDE.md` itself, if absent).
+   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a
+   short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the
    article (bump its `Updated` date) in the same change.
 

package/skills/plan/SKILL.md

@@ -51,7 +51,7 @@ Run this gate. Skipping it produces a plan that drifts from intent on contact.
 3. **Read the constitution.** `02-DOCS/wiki/sdd/constitution.md` holds the project's non-negotiables
    (stack canon, quality bars, conventions). Every architectural choice must be consistent with it;
    when the plan needs to bend a principle, say so explicitly with a reason — don't bend it silently.
-4. **Read the Knowledge map.** The root `CLAUDE.md` `## Knowledge map` points at existing
+4. **Read the Knowledge map.** The full index at `02-DOCS/wiki/index.md` (root `CLAUDE.md` keeps only a short pointer to it) points at existing
    `02-DOCS/wiki/stack/*` and prior plans/decisions. Reuse what's already established. A plan that
    reinvents a pattern the project already settled is scope drift.
 
@@ -172,8 +172,8 @@ complete; it's just quiet.
 
 Write to `02-DOCS/wiki/sdd/plans/<slug>.md`, where `<slug>` matches the spec's slug exactly (one
 plan per spec, same name — that's how `tasks`, `analyze`, and `implement` find it). Use
-`references/plan-template.md` verbatim as the skeleton. Then index it: add a row under the
-`## Knowledge map` section of the root `CLAUDE.md` pointing at the new plan, so the harness wiki and
+`references/plan-template.md` verbatim as the skeleton. Then index it in `02-DOCS/wiki/index.md`
+(the Knowledge map; root `CLAUDE.md` keeps only a short pointer) pointing at the new plan, so the harness wiki and
 every later phase can find it. If a plan for this slug already exists, update it in place and note
 what changed — don't fork a `-v2`.
 

package/skills/postgresdb/SKILL.md

@@ -353,11 +353,11 @@ When this skill runs in a project with a `02-DOCS/` layer (the
 project's database decisions there and index them from the root `CLAUDE.md`, so the next
 agent inherits the conventions instead of re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/postgresdb.md`, linked from a `## Knowledge map` section in the root
-   `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/postgresdb.md`, indexed in `02-DOCS/wiki/index.md` (the
+   Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — schema and naming conventions, the migration tool, indexing/partitioning decisions, the pooling setup, and any RLS policies —
-   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
-   `CLAUDE.md` itself, if absent).
+   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a
+   short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the
    article (bump its `Updated` date) in the same change.
 

package/skills/presentations/SKILL.md

@@ -276,8 +276,8 @@ When this skill runs in a project with a `02-DOCS/` layer (the
 conventions there and index them from the root `CLAUDE.md`, so the next agent inherits them instead of
 re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/presentations.md`, linked from a `## Knowledge map` section in the root `CLAUDE.md`.
-2. **If missing or stale**, create/update it with this project's real choices — the chosen pipeline (Marp / Slidev / python-pptx) and why; the theme file path and how it maps the design tokens (`02-DOCS/wiki/stack/design.md`); the standard deck arc(s); export commands and the canonical output (PDF / PPTX); presenter-vs-leave-behind convention; font-embedding and asset-location notes — then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and `CLAUDE.md` itself, if absent).
+1. **Find the article** `02-DOCS/wiki/stack/presentations.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
+2. **If missing or stale**, create/update it with this project's real choices — the chosen pipeline (Marp / Slidev / python-pptx) and why; the theme file path and how it maps the design tokens (`02-DOCS/wiki/stack/design.md`); the standard deck arc(s); export commands and the canonical output (PDF / PPTX); presenter-vs-leave-behind convention; font-embedding and asset-location notes — then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the article (bump its `Updated` date) in the same change.
 
 The deck theme is downstream of the design tokens: always reconcile `02-DOCS/wiki/stack/presentations.md`

package/skills/python/SKILL.md

@@ -348,9 +348,9 @@ When this skill runs in a project with a `02-DOCS/` layer (the
 [`harness`](../harness/SKILL.md) Karpathy wiki), record this project's Python conventions
 there so the next agent inherits them — *recorded, not gated*, never block the task on this.
 
-1. **Find** `02-DOCS/wiki/stack/python.md`, linked from a `## Knowledge map` in the root `CLAUDE.md`.
+1. **Find** `02-DOCS/wiki/stack/python.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, write the project's real choices (interpreter floor, `src/` layout,
-   uv workflow, ruff/mypy config, async-vs-sync stance, data-modeling defaults) and add the link.
+   uv workflow, ruff/mypy config, async-vs-sync stance, data-modeling defaults) and index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
 3. **Read it first on every use**; bump its `Updated` date when a convention changes.
 
 No `02-DOCS/` layer? Skip silently (optionally suggest `harness`).

package/skills/review/SKILL.md

@@ -219,7 +219,7 @@ Review is mostly a conversation, but two artifacts persist into the harness wiki
 - **Accepted/declined findings** of consequence → append to `02-DOCS/wiki/sdd/decisions.md` (e.g. "declined NPE finding on documents.py:42 — guarded by require_auth; added regression test"). This is the same append-only log `implement` writes to.
 - If a finding reveals a **missing constitution rule** (a defect class the project keeps hitting), propose adding it to `02-DOCS/wiki/sdd/constitution.md` so the next review catches it earlier.
 
-Index both under the root `CLAUDE.md` `## Knowledge map` (the `sdd/` topic) — the harness owns that map; this skill just keeps its rows honest.
+Index both in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic — the harness owns that map; this skill just keeps its rows honest.
 
 ## Next in the chain
 

package/skills/rust/SKILL.md

@@ -365,12 +365,12 @@ When this skill runs in a project with a `02-DOCS/` layer (the
 [`harness`](../harness/SKILL.md) Karpathy wiki), record this project's service decisions there and index
 them from the root `CLAUDE.md`, so the next agent inherits the conventions instead of re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/rust.md`, linked from a `## Knowledge map` section in the
-   root `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/rust.md`, indexed in `02-DOCS/wiki/index.md` (the
+   Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — the crate/workspace layout,
    the runtime (tokio), the HTTP framework (axum 0.8), the error strategy (thiserror enum + IntoResponse
-   mapping), the DB layer (sqlx + pool), and tracing/concurrency defaults — then add/refresh the
-   `CLAUDE.md` link (create the `## Knowledge map` section, and `CLAUDE.md` itself, if absent).
+   mapping), the DB layer (sqlx + pool), and tracing/concurrency defaults — then index it in
+   `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the article
    (bump its `Updated` date) in the same change.
 

package/skills/sdd/SKILL.md

@@ -145,9 +145,10 @@ Every phase writes under `02-DOCS/wiki/sdd/` so the feature's reasoning outlives
 └── decisions.md             ← append-only log of decisions taken while building
 ```
 
-Index these from the root `CLAUDE.md` `## Knowledge map` under an `sdd/` topic, so every other skill reads them before working in the area. The harness maintains and improves these files just like any other wiki topic — `sdd` produces them, the harness keeps them honest.
+Index these in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under an `sdd/` topic, so every other skill reads them before working in the area. The harness maintains and improves these files just like any other wiki topic — `sdd` produces them, the harness keeps them honest.
 
 ```markdown
+# 02-DOCS/wiki/index.md
 ## Knowledge map
 | Topic | Where | What |
 | --- | --- | --- |

package/skills/secure-coding/SKILL.md

@@ -336,11 +336,11 @@ When this skill runs in a project with a `02-DOCS/` layer (the
 project's security decisions there and index them from the root `CLAUDE.md`, so the next
 agent inherits the conventions instead of re-deriving them.
 
-1. **Find the article** `02-DOCS/wiki/stack/security.md`, linked from a `## Knowledge map` section in the root
-   `CLAUDE.md`.
+1. **Find the article** `02-DOCS/wiki/stack/security.md`, indexed in `02-DOCS/wiki/index.md` (the
+   Knowledge map index; root `CLAUDE.md` points to it).
 2. **If missing or stale**, create/update it with the project's real choices — the threat model, the auth model, the secrets backend, the CI security gates, and any accepted risks —
-   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section, and
-   `CLAUDE.md` itself, if absent).
+   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a
+   short pointer to it).
 3. **Read it first on every use** and stay consistent; when a convention changes, update the
    article (bump its `Updated` date) in the same change.
 

package/skills/security-scan/SKILL.md

@@ -216,8 +216,9 @@ Emit one `security-scan-report.json` — the machine-checkable contract CI gates
 
 In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md)
 Karpathy wiki), record the scanner choices, pinned versions, gate thresholds, and
-any accepted-risk suppressions in `02-DOCS/wiki/stack/security-scan.md`, and link
-it from the root `CLAUDE.md` `## Knowledge map`. Read it first on every run so the
+any accepted-risk suppressions in `02-DOCS/wiki/stack/security-scan.md`, and index
+it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short
+pointer to it). Read it first on every run so the
 next agent inherits the pinned tools and thresholds instead of re-deriving them.
 No `02-DOCS/`? Skip silently. Conventions are recorded, not gated — never block
 the scan on this.

package/skills/ship/SKILL.md

@@ -228,7 +228,7 @@ When no profile exists, default to L2 and proceed — don't stall the ship to as
 Ship is mostly git actions, but the outcome is recorded so the knowledge model stays whole:
 
 - **The landing decision** (which of the three options, and why) → append to `02-DOCS/wiki/sdd/decisions.md`, the same append-only log `implement`, `verify`, and `review` write to. Parks and discards are logged with their reason so dead-ends aren't re-walked.
-- A **shipped feature** flips its spec under `02-DOCS/wiki/sdd/specs/<slug>.md` to a shipped state (note the merge commit / PR). The harness owns the wiki; ship just keeps the `sdd/` rows in the root `CLAUDE.md` `## Knowledge map` honest.
+- A **shipped feature** flips its spec under `02-DOCS/wiki/sdd/specs/<slug>.md` to a shipped state (note the merge commit / PR). The harness owns the wiki; ship just keeps the `sdd/` rows in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) honest.
 - An **archive bundle** closes the loop under `02-DOCS/wiki/sdd/archive/<slug>/`:
   - `final-report.md` — what shipped, why, landing decision, links.
   - `apply-progress.md` — copy or link to `progress/<slug>.md`.

package/skills/specify/SKILL.md

@@ -11,7 +11,7 @@ origin: risco
 
 This is the **specify** phase of the rsc-sdd chain: `constitution` → **`specify`** → `clarify` → `plan` → `tasks` → `analyze` → `implement` → `verify` → `review` → `ship`. Its single job is to turn a fuzzy intent into a written specification that states **WHAT** the change is and **WHY** it matters — and nothing about **HOW** it gets built.
 
-A spec is a contract about behaviour and outcomes, readable by a non-technical stakeholder and precise enough that a `plan` can be derived from it. The output is one file: `02-DOCS/wiki/sdd/specs/<slug>.md`, indexed in the root `CLAUDE.md` Knowledge map.
+A spec is a contract about behaviour and outcomes, readable by a non-technical stakeholder and precise enough that a `plan` can be derived from it. The output is one file: `02-DOCS/wiki/sdd/specs/<slug>.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer).
 
 ## Detect the moment — and hold the gate
 
@@ -93,7 +93,8 @@ Run these in order. It is a collaborative dialogue, not a form you fill in silen
 5. PROPOSE 2-3 approaches → distinct directions with honest trade-offs; lead with your recommendation and why
 6. PRESENT the design     → section by section (problem, users, behaviour, acceptance), scaled to complexity;
                             after EACH section ask "does this look right?" and adjust before moving on
-7. WRITE the spec         → 02-DOCS/wiki/sdd/specs/<slug>.md (WHAT/WHY), index it in CLAUDE.md, commit if a repo
+7. WRITE the spec         → 02-DOCS/wiki/sdd/specs/<slug>.md (WHAT/WHY), index it in 02-DOCS/wiki/index.md
+                            (the Knowledge map; root CLAUDE.md keeps only a short pointer), commit if a repo
 8. SELF-REVIEW            → scan for TODO/placeholder, contradictions, ambiguity, scope creep; fix inline
 9. USER APPROVES          → ask them to read the written spec and confirm; loop on changes until they approve
 10. HAND OFF              → only now, result envelope → clarify/plan. NEVER to implement.
@@ -191,7 +192,7 @@ The proposal is allowed to mention options and tradeoffs; the spec that follows
 - Read `02-DOCS/wiki/sdd/constitution.md` first — its principles are inherited constraints, not things to re-decide. If it's missing, note that the project has no constitution yet and suggest the `constitution` phase before continuing (you can still draft a spec, but flag the absence).
 - **No constitution yet?** Still write the spec, but inherit nothing — lean harder on the wiki and the user's answers, and record every constraint you would have inherited as a *point to clarify* instead of assuming it.
 - Write the spec to `02-DOCS/wiki/sdd/specs/<slug>.md`. Create the directory if absent.
-- Add a row under the `## Knowledge map` section of the root `CLAUDE.md` linking the new spec under the `sdd/specs` topic (additive only — never delete existing rows). Create `CLAUDE.md` if absent.
+- Add a row in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) linking the new spec under the `sdd/specs` topic (additive only — never delete existing rows). Create the index if absent.
 - Log the spec's creation and any significant scoping decision to `02-DOCS/wiki/sdd/decisions.md` (append-only), so the chain keeps a trace of why scope landed where it did. This is the canonical SDD decisions log shared with `constitution` and `plan` — not the harness's own `02-DOCS/wiki/harness/decisions.md`.
 
 ## Result envelope

package/skills/suggest/SKILL.md

@@ -56,8 +56,8 @@ When the current task would clearly benefit from an rsc skill that is **not inst
 Rules:
 
 - Installing changes the user's environment — always confirm first.
-- To know what exists, run `npx @ericrisco/rsc consult "<the task>"` instead of guessing.
-- For a project-level view, prefer `.rsc/skill-registry.json` when present; if it is missing or stale, suggest `npx @ericrisco/rsc registry refresh`. This is a cheap index, not a reason to load every skill.
+- To know what exists, run `npx @ericrisco/rsc catalog --available` (every NOT-installed skill as `id  available  short description`) and **pick the best fit yourself, by meaning** — see the detector below. Don't guess from memory.
+- `npx @ericrisco/rsc consult "<task>"` is only a cheap **lexical** hint: it keyword-matches and silently returns nothing for natural-language or non-English/Catalan intent (e.g. it finds no email skill for "mandar emails"). Never let it be the decider; if it's empty, scan `catalog` and judge semantically.
 - Never recommend something already installed (`npx @ericrisco/rsc list`).
 - One suggestion at a time. Don't interrupt the flow for nice-to-haves.
 
@@ -78,24 +78,29 @@ This is broader than "start a project". It includes mid-conversation requests su
 - Knowledge and research: "documenta cómo funciona esto", "crea una wiki", "procesa este inbox", "research competitors", "turn this into SOPs".
 - Other languages: any equivalent phrasing. Match the user's intent, not exact words.
 
-When a capability intent appears:
-
-1. Run `npx @ericrisco/rsc list` to know what is already installed.
-2. Run `npx @ericrisco/rsc consult "<the user's exact intent>"`.
-3. Read the ordered result as the install queue, but pick only the **first missing**
-   skill that is useful right now. Skip `suggest` and any installed skill.
+When a capability intent appears, **you** make the match semantically — do not delegate the decision to a keyword ranker:
+
+1. Run `npx @ericrisco/rsc catalog --available` to get every NOT-installed skill as
+   `id  available  short description`. (It already excludes what's installed.)
+2. **Read the catalog and pick the single best-fit skill by MEANING** — match the user's
+   intent to a skill's *purpose*, semantically, in any language (CA/ES/EN/…), the way you'd
+   match a request to a teammate's expertise. Judge meaning, not shared keywords:
+   "mandar emails de bienvenida" → `email-connector` even though no words overlap its tags;
+   "login con Google" → an auth/security skill, not `flutter`; "transcripció de veu" → a
+   speech/audio skill *if one exists*.
+3. If nothing in the catalog genuinely fits, **say so and move on** — don't force a weak
+   match, and don't propose a tangential skill just to have an answer. (`npx @ericrisco/rsc
+   consult "<intent>"` is available as a lexical hint, but it misses natural-language and
+   Catalan intent and is silent for many real needs — never read its silence as "no skill
+   exists." The catalog + your judgment is the source of truth.)
 4. Ask before installing: "Para esto instalaría `<id>`, que aún no tienes. ¿La instalo? (sí/no)".
-5. On yes, run `npx @ericrisco/rsc add <id>` and then continue the original request.
-
-Example: if the user says "quiero montar una pagina web para vender cursos online",
-do not just start building. Check the installed list, consult that exact phrase, and
-recommend the first missing skill from the returned queue. In a base install, `init`
-and `harness` may already exist, so the first missing skill is usually `nextjs`. In a
-bare install, `init` may be first. Install one skill at a time.
+5. On yes, run `npx @ericrisco/rsc add <id>` and continue the original request. One at a time.
 
-Example: if the user says "hazme una secuencia de cold emails para vender mi SaaS",
-consult that exact phrase and recommend the first missing email/marketing skill rather
-than writing generic copy with no specialist loaded.
+Example: "quiero montar una pagina web para vender cursos online" → scan the catalog and
+pick the web stack skill (usually `nextjs`) by meaning; don't start building before offering it.
+Example: "hazme una secuencia de cold emails para vender mi SaaS" → pick the email/outreach
+skill (`cold-outreach` / `email-connector`) because it *means* email outreach — not because
+the keywords happen to match (they often won't).
 
 ## Onboarding gate (first contact)
 

package/skills/suggest/evals/cases.yaml

@@ -62,17 +62,17 @@ capability:
   - scenario: "Mid-conversation, after base install, the user says 'quiero montar una pagina web para vender cursos online'. `init`, `harness`, `orient`, and `suggest` are already installed; `nextjs` is not. Show how rsc-suggest behaves."
     must_include:
       - "Treats the message as in-agent capability intent, not as a CLI-only consult task"
-      - "Runs `npx @ericrisco/rsc list` before recommending so installed `init`/`harness` are skipped"
-      - "Runs `npx @ericrisco/rsc consult \"quiero montar una pagina web para vender cursos online\"` or equivalent exact-intent consult"
-      - "Names `nextjs` as the first missing useful skill for the website work"
+      - "Runs `npx @ericrisco/rsc catalog --available` to see the not-installed skills (already excludes installed `init`/`harness`)"
+      - "Picks the best-fit skill by MEANING from the catalog, not by relying on lexical `consult` ranking"
+      - "Names `nextjs` as the missing useful skill for the website work"
       - "Asks one short confirmation before installing and does not auto-install"
       - "On confirmation, runs `npx @ericrisco/rsc add nextjs`, then resumes the original website task"
 
   - scenario: "Mid-conversation, the user says 'Automatiza el flujo de leads desde el formulario hasta mi CRM'. The base skills are installed, but `automation-flows` and CRM/connector skills are not. Show how rsc-suggest behaves."
     must_include:
       - "Treats the message as in-agent capability intent for automation/integration, not only as a coding task"
-      - "Runs `npx @ericrisco/rsc list` before recommending"
-      - "Runs `npx @ericrisco/rsc consult \"Automatiza el flujo de leads desde el formulario hasta mi CRM\"` or equivalent exact-intent consult"
-      - "Names the first missing useful automation/connector skill from the consult results"
+      - "Runs `npx @ericrisco/rsc catalog --available` to see the not-installed skills"
+      - "Picks the best-fit missing automation/connector skill by MEANING (not by lexical `consult` ranking, which may return nothing)"
+      - "Names that one missing automation/connector skill"
       - "Asks one short confirmation before installing and does not auto-install"
       - "On confirmation, runs `npx @ericrisco/rsc add <id>` for that one missing skill, then resumes the automation task"

package/skills/tasks/SKILL.md

@@ -153,7 +153,8 @@ The task list is **not** a new document. Append it to the existing plan under a
        T001 … T0NN as the table below, + a one-line "generated by tasks on <date>"
 ```
 
-Then ensure the plan is indexed in the root `CLAUDE.md` `## Knowledge map` under
+Then ensure the plan is indexed in `02-DOCS/wiki/index.md` (the Knowledge map;
+root `CLAUDE.md` keeps only a short pointer) under
 the `sdd/` topic (the `plan` phase usually added the row; confirm it points at
 `02-DOCS/wiki/sdd/plans/<slug>.md`, add it if missing — additive only, never
 delete a user's map entry).
@@ -219,7 +220,7 @@ Before handing off, confirm:
 - [ ] Every task traces to a spec line; no orphan tasks.
 - [ ] Dependencies form a valid order (nothing precedes what it needs).
 - [ ] `[P]` markers only on file/state-disjoint tasks.
-- [ ] The list is appended under `## Tasks` in the plan artifact, indexed in the Knowledge map.
+- [ ] The list is appended under `## Tasks` in the plan artifact, indexed in the Knowledge map at `02-DOCS/wiki/index.md` (root `CLAUDE.md` keeps only a short pointer).
 - [ ] A final closer task gates on all done-checks + `verify.sh`.
 - [ ] Review workload forecast and suggested delivery strategy appended.
 

package/skills/verify/SKILL.md

@@ -113,7 +113,7 @@ A criterion you "reviewed by reading the code" is not verified. Reading is `revi
 
 ### 4 — RECORD
 
-Write a dated verification record to `02-DOCS/wiki/sdd/verifications/<slug>-YYYY-MM-DD.md` so the project's living knowledge carries the proof, then ensure it's indexed in the root `CLAUDE.md` `## Knowledge map` under the `sdd/` topic. Keep it short and factual:
+Write a dated verification record to `02-DOCS/wiki/sdd/verifications/<slug>-YYYY-MM-DD.md` so the project's living knowledge carries the proof, then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic. Keep it short and factual:
 
 ```markdown
 # Verification — <slug> — YYYY-MM-DD

package/targets/session-start.mjs

@@ -107,6 +107,28 @@ ACTION: run \`npx @ericrisco/rsc audit\`. Opt out with .rsc/.no-audit.
 `);
 }
 
+// CLAUDE.md hygiene: the root CLAUDE.md is read on EVERY turn, so an overgrown one (usually
+// the Knowledge map accreting a row per wiki article) is a permanent context tax that rots
+// adherence. When it passes the ~200-line 2026 budget, nudge to offload the index into
+// 02-DOCS/wiki/index.md and keep CLAUDE.md a short pointer (the `harness` skill owns the move;
+// it's a relocation, not a delete). Opt out with .rsc/.no-claudemd-check.
+const CLAUDEMD_MAX_LINES = 200;
+if (!has('.rsc', '.no-claudemd-check')) {
+  try {
+    const lines = readFileSync(join(root, 'CLAUDE.md'), 'utf8').split('\n').length;
+    if (lines > CLAUDEMD_MAX_LINES) {
+      process.stdout.write(`
+===== rsc CLAUDE.md hygiene =====
+CLAUDE.md is ${lines} lines — over the ~${CLAUDEMD_MAX_LINES}-line budget (it's read every turn, so each line costs context).
+ACTION: offload the Knowledge map / overgrown sections into 02-DOCS/wiki/index.md and leave a short
+pointer in CLAUDE.md (no info lost — it's a move). The \`harness\` skill owns the procedure.
+Opt out with .rsc/.no-claudemd-check.
+=================================
+`);
+    }
+  } catch { /* no CLAUDE.md → nothing to check */ }
+}
+
 // Update check: compare the installed version (.rsc/.version, written at install)
 // against the latest published on npm, and nudge the agent to offer an update.
 // Fail-silent (offline / missing baseline / parse error → nothing). Disable with