docs(ai): correct the agent.knowledge row to a retirement

[claude]

Closes#10730

The defect

The "shape of an agent" field table in content/docs/ai/agents.mdx documented
knowledge as live RAG access, noting only that a nested alias had been removed —
and handed the reader a migration command for a key that no longer exists.

But packages/spec/src/ai/agent.zod.ts declares knowledge: retiredKey(...). The whole
key is retired: it types as never (so writing it fails tsc) and any value that reaches
the runtime is rejected at parse. The row taught a key that cannot be written.

This is the more dangerous of the two rows on this table, because the key read as a
security control and was not one: declaring sources / indexes on an agent never
scoped retrieval — search_knowledge takes sourceIds from the LLM's own tool-call
arguments, not from the agent record. An author who believed they had scoped retrieval
here scoped nothing.

The page already contradicted itself, 64 lines apart

The Sales Assistant example further down the same file already carried the correct rule:

(There is no agent-level knowledge block — it was removed in protocol 17 (#3896
close-out): declaring sources never scoped retrieval. Restrict access at the
knowledge-service/source level; describe intended grounding in instructions.)

So the prescription did not have to be invented — only moved into the row, in the row's
own register. The two now agree.

Before

| `knowledge` | RAG access: `{ sources: string[], indexes: string[] }`. `sources` is the only key; the `topics` alias was removed in protocol 17 (#3855) — `os migrate meta --from 16` rewrites it |

After

| `knowledge` | **Removed in protocol 17 (#3896)** — typed `never`, so writing it fails `tsc`, and a value that reaches the runtime is rejected at parse. Declaring `sources` / `indexes` here never scoped retrieval: `search_knowledge` takes `sourceIds` from the LLM's own tool-call arguments, not from the agent record, so an author who "scoped" access here scoped nothing. This is **not** a rename: there is no key the value moves to — delete the block. Restrict retrieval at the knowledge-service / source level (per-source permissions), and describe intended grounding in `instructions` so the model asks for the right sources |

Written from the tombstone's own words, following the shape of the sibling tools row
(PR #10732), which rewrote from its tombstone, offered no migration command, and carried
the reason the key is gone so the row reads as a prescription rather than a neutral
"this moved".

Two judgment calls, flagged for review

1. No migration command is offered. The tombstone does name one, verbatim:

Run os migrate meta --from 16 to list the mechanical edits for existing sources; apply them by hand.

That sentence is the identical boilerplate carried by the tools tombstone, and it
describes a lister, not a rewriter — there is no key a knowledge block moves to. The
row it replaces claimed the command "rewrites it", which is the false half. I omitted the
command rather than restate it, for two reasons: the sibling tools row omits it too, and
an asymmetry between two adjacent rows whose tombstones carry the same sentence would imply
knowledge has a migration path that tools lacks. Happy to add it back framed as a
lister if the reviewer prefers.

2. The topics / #3855 fact is dropped. It remains historically true, and the
protocol-17 agent-knowledge-topics-to-sources conversion does remain in the chain (per
the header comment in agent.zod.ts, it rewrites historical sources and imports
nothing from the removed schema). But for an author, a nested alias of a key that cannot be
written at all is unreachable information — and leading with the alias is exactly what made
the old row imply the parent was live. The conversion-chain fact stays recorded where it
belongs, in agent.zod.ts and the ADR-0087 registries, not in the authoring field table.

Note the two issue numbers are distinct and both real: #3855 is the topics alias
removal, #3896 is the knowledge key's own removal. The old row cited only the first.

Verification

Gate union re-run on the final commit 934022ee4a; the set was derived with
node scripts/pm/dispatch-gates.mjs (no paths) rather than assumed — it returned 13
families for this path, not the 4 predicted. All green:

check:cross-package-test-inputs · check:doc-anchors · check:doc-authoring ·
check:doc-formula-expressions · check:docs-audit-scope · check:docs-redirects ·
check:published-readme-links · check:role-word · check:empty-state ·
check:liveness · check:strictness-ledger · check:variant-docs ·
check-cross-package-test-inputs.mjs · plus check:nul-bytes.

The mutation was confirmed on disk by anchor count in both directions (old row 1 → 0, new
row 0 → 1; file line count unchanged at 391), since a markdown table row is exactly where a
zero-match edit reads as a clean no-op.

check:skill-examples was not run: the nearest {/* os:check */} fence on this page is
at line 247, below this hunk at line 211 and outside it. Verified for this hunk rather than
inherited from the sibling PR.

Docs-only, publishes nothing ⇒ no changeset; skip-changeset label applied.

---

Generated by Claude Code