docs(spec, docs): App.defaultAgent and actions-as-tools name the agent route as the one chat door

[objectstack-fleet]

Fixes #21968

Merge gate: this PR merges only once objectstack-ai/cloud#2651 has merged. That PR removes the three assistant routes. Until it lands, the corrected text would be ahead of the server.

Clause-②: no

What changed

The App.defaultAgent docblock and one docs callout named POST /api/v1/ai/assistant/chat, a route the maintainer's ruling on objectstack-ai/cloud#2621 retires. Both texts now name the agent route, POST /api/v1/ai/agents/:agentName/chat, as the one chat door.

• packages/spec/src/ui/app.zod.ts, the App.defaultAgent docblock. It no longer says a server route reads the key. It now describes the reader that exists, objectui at the .objectui-sha pin 0abd4f9f87: the chat dock passes the active app's defaultAgent to the console's one surface-to-agent resolver. That resolver honours the value only when it names ask or build (legacy aliases included) and otherwise falls back to the surface default. The resolved agent is then called by name on the agent route, where the :agentName path segment selects the agent. The sentence on the bare POST /api/v1/ai/chat route stays, shortened: it reads no agent, so the key does not scope it. The ADR-0063 surface-binding paragraph and the rule that only the two platform agents resolve are unchanged.
• content/docs/ai/actions-as-tools.mdx. The in-product chat-route callout lists the agent route only. It keeps its account of how the principal is taken from req.user and forwarded as toolExecutionContext.
• Changeset @objectstack/spec patch. Measured: after pnpm --filter @objectstack/spec build, the new docblock text has 1 hit in each of dist/ui/index.mjs and dist/ui/index.js, and in the dist/browser bundles. The old route string has 0 hits in dist. The positive control, the unchanged ADR-0063 paragraph, has 1 hit in dist/ui/index.mjs. The package's files list also ships src/**/*.zod.ts. The .d.ts files do not carry the docblock.

No schema, parse, .describe(), export, type or accept-set change. check:generated confirms that no generated reference moved.

How the console reads the key (objectui at 0abd4f9f87, read-only)

• ConsoleLayout.tsx passes activeApp?.defaultAgent to the chat dock, both on desktop and in the mobile sheet.
• ChatDock.tsx (ChatDockConversation) calls resolveSurfaceAgent('default', { agents, appDefaultAgent: defaultAgent, aiStudioEnabled, canAuthorMetadata }). It posts to apiBase/agents/NAME/chat, with the resolved name URL-encoded.
• surfaceAgent.ts (resolveSurfaceAgent) runs these steps in order:
  1. It keeps the value only if isBuiltinAgentName holds. That means build, metadata_assistant, ask or data_chat. Any other value is dropped.
  2. With no kept value, the surface default applies: build on studio-build, ask everywhere else.
  3. A build request falls back to ask when AI Studio is off.
  4. An ask request becomes build for a principal who may author metadata, when the catalog serves build.
  5. The result is matched against the live catalog, alias-aware. If nothing matches, the catalog's platform default is used.

Census of the three retired routes, and of claims that a server route reads defaultAgent

Searched at c9761cd2fb (git grep, outside content/docs/releases/):

Hit	Lane	Disposition
packages/spec/src/ui/app.zod.ts:1658	spec	moved with this card
content/docs/ai/actions-as-tools.mdx:275	docs	moved with this card
packages/spec/CHANGELOG.md:29568, packages/client/CHANGELOG.md:3498, packages/runtime/CHANGELOG.md:31673	release-owned	listed, not edited. These are historical entries.
packages/spec/liveness/agent.json:3 and :70 cite cloud routes/assistant-routes.ts#buildAssistantRoutes	spec, ledger evidence	listed, not edited. They name the handler file, not a route path, and are anchored at cloud @cb8ee7ff, where they stay true. planning.maxIterations is still live through agent-routes.ts and eval-runner.ts. This lane cannot read cloud to re-anchor them.

skills/**, .claude/**, docs/adr/** and examples/** have zero hits for the three routes. No text in content/docs, skills or examples says a server route reads defaultAgent. No test asserts the docblock text, so no needle moves.

Tests

All runs are at 7f6089bd50 (HEAD). The spec build was taken at 4e79442153, whose source is the same; the build-input stamp matched.

• pnpm --filter @objectstack/spec build: VERDICT command-exit 0.
• pnpm --filter @objectstack/spec check:generated: exit 0, "All 15 generated artifacts are up to date".
• pnpm --filter @objectstack/spec run typecheck: VERDICT command-exit 0.
• vitest run --project local over the six src/ui/app*.test.ts files: 6 files, 203 tests passed. This is a declared narrowing. The diff is a comment in app.zod.ts, so the full spec suite is left to CI.
• node scripts/pm/dispatch-gates.mjs --ran: 101 derived, 100 run, 1 NOT MEASURED, 0 UNRUN.
  • Five gates first refused with PREREQUISITE NOT MET (exit 3): check:doc-formula-expressions, check:doc-security-posture, check:skill-examples, check:docs-transcript-drift and check:lean-entry-closure. After a build of formula, lint, client, client-react and objectql, all five exited 0.
  • NOT MEASURED: check:dual-build-cjs-loads, reason: it needs dist for the whole workspace (87 packages). As a narrowed stand-in, all 19 require entries of @objectstack/spec load. CI's Lint & Repo Gates runs the full gate.
  • The six artifact-roster gates flagged under my paths also exited 0: check-changeset-fixed, check:authz-resolver, check:error-code-casing, check:filter-alias-parity, check:meta-url-spelling and check:spec-changes.
• Lint, narrowed: eslint --no-inline-config --format json over the two edited source files.
  • Population, read from eslint's own answer: app.zod.ts is linted, with 0 errors and 0 warnings. The .mdx file is outside the population ("no matching configuration").
  • Invariance: eslint.config.mjs never enables type-aware linting (it has no parserOptions.project), so this diff cannot move the result for any file it does not touch.

Acceptance notes

• objectui's AiChatPage.tsx also takes a defaultAgent prop, and resolves it with resolveDefaultAgentName, which is not bounded to ask / build. But the console mounts it in apps/console/src/App.tsx with no props, so app.defaultAgent never reaches it there. The docblock therefore describes only the dock path. This is noted, not filed: nothing passes the key down that path. Carrier: none.
• Whether defaultAgent needs a server consumer is not this card's question (triage).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 documentable anchor(s).

4 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/ai/actions-as-tools.mdx (via /api/v1/ai/agents/:agentName/chat (route, a path literal in a comment in AppSchema))
• content/docs/ai/index.mdx (via /api/v1/ai/agents/:agentName/chat (route, a path literal in a comment in AppSchema))
• content/docs/getting-started/quick-reference.mdx (via AppSchema (symbol, a top-level const))
• content/docs/protocol/kernel/error-handling.mdx (via /api/v1/ai/agents/:agentName/chat (route, a path literal in a comment in AppSchema))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v14.mdx (via AppSchema (symbol, a top-level const))
• content/docs/releases/v17/17-0.mdx (via AppSchema (symbol, a top-level const), /api/v1/ai/chat (route, a path literal in a comment in AppSchema))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 138 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json f76c6221acd3997dd778fdd3e8e7d43e0bec4851 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 04a85f58e75f24bd57cd468fa264295a925a7bf2 — the merge of head 7f6089bd504e05ec21401abdedb7c280712bf00c into base f76c6221acd3997dd778fdd3e8e7d43e0bec4851, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 04a85f58e75f24bd57cd468fa264295a925a7bf2 && git checkout 04a85f58e75f24bd57cd468fa264295a925a7bf2
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin f76c6221acd3997dd778fdd3e8e7d43e0bec4851 7f6089bd504e05ec21401abdedb7c280712bf00c && git checkout -B drift-repro f76c6221acd3997dd778fdd3e8e7d43e0bec4851 && git merge --no-ff 7f6089bd504e05ec21401abdedb7c280712bf00c

node scripts/docs-audit/affected-docs.mjs --json f76c6221acd3997dd778fdd3e8e7d43e0bec4851

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs f76c6221acd3997dd778fdd3e8e7d43e0bec4851 → pass the list as
args.docs, on the commit named under Which tree this was computed on.