fix(docs): correct every row of the "What each one runs" preset table, and guard it

[amiddavid]

The defect

Every row of the "What each one runs" table in docs/how-to/choose-a-preset.md was stale relative to the presets map in config/config.go:

• codesmart, coding and general were documented as running toon — which was retired from them after it acted 0 times on 5,752 production requests and converted 0 candidates in 11.67M measured tokens.
• Every row omitted components that do run: the lossless pair textclean and searchfold, and linecap.
• Three presets in the map were never in the table at all: agentdiet, house, housellm.

Severity

docs/reference/presets.md was correct at the same moment, so the two documents contradicted each other — in the exact table a reader uses to decide what a preset will do to their context. That is worse than an out-of-date sentence: the answer was wrong in the direction that matters, naming a component that does not run and omitting three that do. A reader had no way to tell which document was lying.

The fix

1. The table is regenerated from the presets map. Existing row order is preserved; the three never-listed presets are appended. Nothing else in the document is restructured.

2. config/docdrift_test.go asserts set equality in both directions between the presets map and both doc tables (docs/how-to/choose-a-preset.md and docs/reference/presets.md): every preset has a row with the pipeline it runs, and nothing is documented that does not exist. It reads either formatting — one backtick pair around a comma list, or per-name backticks joined by →.

   Revision after review: the first version iterated the rows it happened to find and stood in for completeness with a hand-tuned multi < 5 floor. That let a shipping preset with no row pass (seven of twelve rows deletable, codesmart among them), let a documented-but-nonexistent preset pass — which is a startup failure, config: config: unknown preset "cache", the skeleton/coding class — and silently skipped any row name with a digit or hyphen. Inverting the loop deleted that block and its magic number; docRow widened to `([a-z0-9_-]+)`.

Revert-verification

Every mutation was asserted to have landed in the source (anchor found exactly once, post-write re-read confirming it) before the test result was believed; an apply that fails its own check aborts the run rather than reporting a vacuous "ok".

(a) a preset that ships with no row — agentdiet's row deleted

--- FAIL: TestPresetDocsDoNotDrift (0.00s)
    docdrift_test.go:116: ../docs/how-to/choose-a-preset.md: preset "agentdiet" ships [format agentdiet cachesplit] but has no row in this table. An undocumented preset is the same defect as a misdocumented one: a reader cannot tell it exists, or what it would do to their context.
FAIL	github.com/rossoctl/context-guru/config	0.229s

(b) a preset documented that does not exist — a cache row added (the exact state a merge of #141 onto an unguarded table would produce)

--- FAIL: TestPresetDocsDoNotDrift (0.00s)
    docdrift_test.go:145: ../docs/how-to/choose-a-preset.md: preset "cache" is documented but does not exist in the presets map; `--preset cache` exits at startup with `unknown preset "cache"`.
FAIL	github.com/rossoctl/context-guru/config	0.169s

(c) the hyphen hole, tripping both directions at once — codesmart renamed to code-smart

--- FAIL: TestPresetDocsDoNotDrift (0.00s)
    docdrift_test.go:116: ../docs/how-to/choose-a-preset.md: preset "codesmart" ships [format textclean searchfold dedup failed_run cmdfilter extract_llm extract linecap cachesplit] but has no row in this table. An undocumented preset is the same defect as a misdocumented one: a reader cannot tell it exists, or what it would do to their context.
    docdrift_test.go:145: ../docs/how-to/choose-a-preset.md: preset "code-smart" is documented but does not exist in the presets map; `--preset code-smart` exits at startup with `unknown preset "code-smart"`.
FAIL	github.com/rossoctl/context-guru/config	0.165s

(d) a wrong component list — safe cut to format → cachesplit in docs/reference/presets.md

--- FAIL: TestPresetDocsDoNotDrift (0.00s)
    docdrift_test.go:128: ../docs/reference/presets.md: preset "safe" is documented as running
          [format cachesplit]
        but ships
          [format textclean searchfold cachesplit]
        A reader uses this table to decide what a preset will do to their context; naming a component that does not run, or omitting one that does, is the failure this guard exists for.
FAIL	github.com/rossoctl/context-guru/config	0.172s

Restoring each mutation returns go test ./config/ -run Drift to ok. Full go test ./config/ passes (7.1s); gofmt -l . and go vet ./config/ are clean (eval box, Go 1.26.4). The earlier row-level mutations from the first round (stale codesmart row, dropped components) still fail as before.

Merge order with #141 (please merge this PR first)

Both PRs edit the same hunk of docs/how-to/choose-a-preset.md and git merge-tree confirms a content conflict. #141 added a | `cache` | `cachesplit` | row onto the stale table; this PR rewrites every row without knowing cache exists, so both mechanical resolutions lose something — taking this table drops the cache row, taking #141's restores all nine stale rows including toon.

Correct resolution: this PR's corrected rows plus #141's cache row placed after codesafe, in both guarded files.

#142 should merge first. With the inverted guard in place, forgetting the cache row becomes a CI failure — mutation (a) above is literally that scenario — instead of a silent regression. Merged the other way round, the omission is invisible. Note the guard also runs in the other direction, so #141 must carry a cache row in both docs/how-to/choose-a-preset.md and docs/reference/presets.md, and this PR deliberately does not add one: cache does not exist on main and a row for it would fail this PR's own "documented but does not exist" check.

Non-blocking review items, all addressed

• Test renamed to TestPresetDocsDoNotDrift, so go test ./config/ -run Drift matches it (verified).
• The "lossless repack first … cache directives last" sentence now carries the house/housellm exemption, pointing at config/config.go and the preset reference.
• house/housellm are marked as the service configs and agentdiet as a published baseline rather than a recommendation, so nobody reads this how-to and sets --preset house.
• "the presets map above" corrected to name config/config.go.

Why this is its own PR

Found while adding a row to this table during the local-distribution work. It is split out because a stale preset-pipeline table has nothing to do with distribution and should not wait on it.

Heads-up for whoever merges second: the sibling PR feat/local-distribution also touches this table (it adds one row for a new cache preset), so it will need a trivial rebase there — one row, no semantic conflict.

Not fixed here (out of scope, reported)

Other documents also carry stale pipeline listings in prose/snippets, outside the two preset tables this guard covers:

• README.md:133-134 — codesmart and codesafe described with the pre-August pipelines (toon present, lossless pair and linecap absent).
• docs/get-started/connect-ibm-service.md:22 — "Default pipeline" given as [format, toon, dedup, failed_run, cmdfilter, extract, cachesplit], which is not the house pipeline the map ships.

(docs/results/** intentionally records the pipelines as measured at the time and is correctly "stale".)

🤖 Generated with Claude Code

[OsherElhadad]

Reviewed against main e88f5d8, in a clean worktree. Build, gofmt, go vet and the full
go test ./config/... all pass; mkdocs build --strict builds clean and the edited page is in
the nav at mkdocs.yml:115 with all seven outbound links resolving.

The correction itself is right: all 14 rows now match config/config.go, and three presets the
table never listed (agentdiet, house, housellm) are added. Confirmed the drift this fixes
was real — running the new guard against main's table fails 9 of 10 rows (every one except
summarize).

The guard's within-row coverage is genuinely solid. Adding, reordering and removing a
component in config.go each fail the test, in both documented files:

add     "mcp": +linecap             -> FAIL  documented [format textclean smartcrush cachesplit]
                                             but ships [format textclean smartcrush linecap cachesplit]
reorder "codesmart": swap textclean/searchfold -> FAIL
remove  "balanced": -linecap        -> FAIL

Two things to fix before this merges.

1. Blocking — the guard checks rows, not the preset set, so the drift class it was written for still passes

The loop iterates doc rows and asks "is this row correct?". It never iterates presets and
asks "does every preset have a row?". Standing in for that is a hand-tuned coverage floor at
config/docdrift_test.go:113:

len(seen) == 0 || multi < 5

Magic number 5, against an actual population of 12 multi-component presets. Three holes,
each verified by mutating a scratch copy and running the real test:

Mutation	Guard
A preset documented in the table that does not exist in presets	passes
A preset that ships but has no row	passes
A row name containing a hyphen or digit (`code-smart`, `preset2`)	silently skipped — docRow is ^|\s*`([a-z_]+)`\s*|

Hole B tolerates deleting 7 of the 12 multi-component rows before the floor trips on the 8th
— including codesmart itself, because the surviving rows satisfy multi >= 5.

This matters because it is the class the PR itself just fixed by hand. The commit message says
the map had "presets the table never listed at all (agentdiet, house, housellm)" — that
exact defect can recur tomorrow with CI green. It is also already live: #141 adds a cache
preset, and on a merge of both, the pipeline table has no cache row and the guard passes.

Hole A is not cosmetic. A documented preset that does not exist is a startup failure, not a
graceful degradation — confirmed directly:

$ PRESET=cache ./context-guru-proxy
config: config: unknown preset "cache"      # process exits

Same class as the skeleton/coding incident this file's own comments describe.

Fix — invert the loop. This deletes code: the seen/multi/multi < 5 block and its
magic number go away, and the guard then scales with the map instead of needing the floor
re-tuned.

documented := map[string][]string{}
for _, m := range docRow.FindAllStringSubmatch(string(b), -1) {
    name, row := m[1], m[2]
    cell := row
    if i := strings.Index(row, "|"); i >= 0 {
        cell = row[:i]
    }
    documented[name] = pipelineFromCell(cell)
}
for name, want := range presets {
    got, ok := documented[name]
    if !ok {
        t.Errorf("%s: preset %q ships %v but has no row in this table. "+
            "An undocumented preset is the same defect as a misdocumented one.", path, name, want)
        continue
    }
    if len(want) == 0 && len(got) == 0 {
        continue // `off`, which also subsumes the current strings.Contains(cell, "empty") sentinel
    }
    if strings.Join(got, ",") != strings.Join(want, ",") {
        t.Errorf(...) // message unchanged
    }
}
for name := range documented {
    if _, ok := presets[name]; !ok {
        t.Errorf("%s: preset %q is documented but does not exist; `--preset %s` exits at startup", path, name, name)
    }
}

Also widen docRow to `([a-z0-9_-]+)` so hole C closes.

2. Blocking — merge-order hazard with #141

Both PRs edit the same hunk of docs/how-to/choose-a-preset.md:

$ git merge-tree --write-tree --messages refs/remotes/pr141 HEAD
CONFLICT (content): Merge conflict in docs/how-to/choose-a-preset.md

#141 added a | `cache` | `cachesplit` | row onto the stale table; this PR rewrites all
rows without knowing cache exists. Both mechanical resolutions lose something — taking this
PR's table drops the cache row; taking #141's restores all 9 stale rows including toon.

Correct resolution: this PR's corrected rows plus #141's cache row after codesafe.
Landing fix 1 first makes forgetting it a CI failure instead of a silent regression, which is the
argument for merging #142 before #141.

Non-blocking

• docs/how-to/choose-a-preset.md:41-45 — the new house/housellm rows contradict the
  unchanged sentence beneath them. It says "lossless repack first … cache directives last", but
  those pipelines run two offloaders before the lossless pair and put toolfilter after
  cachesplit. reference/presets.md:10 carries the exemption note ("the order is the
  operator's") and config/config.go:414-431 records both deviations at length so nobody
  "fixes" them — but that context did not travel with the rows. One clause on :44-45.
• :41-42 — house/housellm are now listed as peers of codesmart in a user-facing
  how-to, with no service-only marker; the chooser (:12-23) and notes (:47+) mention neither
  them nor agentdiet. Someone sets --preset house and gets toon and no linecap.
• Test name — go test ./config/ -run Drift matches nothing (no tests to run). The file
  is docdrift_test.go but the test is TestDocumentedPresetPipelinesMatchTheShippedOnes.
  TestPresetDocsDoNotDrift would make the obvious selector work.
• :16 — "the presets map above" — it is in config.go, not this file.

Out of scope

The preset facts stated outside the two guarded files are stale, and the guard's shape cannot
reach them (README's prose lists, the wrong default preset in five places). Filed as #145 rather
than loaded onto this PR.

Verdict

Needs changes — both blocking items are small, and fix 1 is a net deletion. Nothing here
touches an invariant or risks the running proxy. This is the best documentation work in the
current batch; the guard just needs to assert set equality rather than trust the rows it happens
to find.