docs(spec,client): stop documenting bare POST /ai/chat as agent-resolved

[os-elon]

Fixes #10510

Two shipped docblocks described a resolution step the bare chat route does not
perform. Both read as a security-relevant scoping guarantee — an agent-resolved
endpoint would have its tool offer scoped by that agent's skills (ADR-0063
§1/§5) — so a reader auditing "which endpoints are surface-scoped?" got the
wrong answer at both sites. Per the triage direction on the card, this corrects
the documentation; making the bare endpoint agent-resolved is a behaviour change
in another repo, is explicitly not this card, and would need its own decision.

Site 1 — packages/client/src/index.ts (client.ai.agents JSDoc)

Was: "/ai/chat talks to the environment's default agent; these talk to one you
name." Now states that these are the only SDK methods that reach an agent, and
that POST /ai/chat (ai.chat / ai.chatStream) is a raw chat plane that
resolves no agent at all, so nothing about that call is scoped by an agent's
skills.

Site 2 — packages/spec/src/ui/app.zod.ts (App.defaultAgent JSDoc)

Was: "the ambient chat endpoint (POST /api/v1/ai/chat with context.appName)
auto-resolves to this agent". Now attributes the resolution chain (explicit >
defaultAgent of the named app > first active) to the assistant chat endpoint,
POST /api/v1/ai/assistant/chat, and says plainly that the bare route is not
part of that chain and never reads context.appName.

This repo corroborates the corrected attribution independently of the cloud
sources the card records: content/docs/ai/actions-as-tools.mdx names
/api/v1/ai/assistant/chat and /api/v1/ai/agents/:agentName/chat as the
in-product chat routes that resolve the principal and forward tool-execution
context.

Scope

Documentation text only. The diff is comment lines in both files — no schema
key, no .describe(), no parse behaviour and no runtime path changes; the
clause-② expectation of no holds. The App.defaultAgent .describe() string
is deliberately untouched: it says the key binds a platform agent to the app's
ambient chat, which stays true once the endpoint attribution is corrected, and
it is the string that reaches content/docs/references/.

Verification

pnpm --filter @objectstack/spec check:generated reports all 14 generated
artifacts up to date, check:docs among them — TSDoc on a schema property does
not reach content/docs/references/ (only .describe() does), so no
regeneration was required.

Gate set re-derived against the actual diff with
node scripts/pm/dispatch-gates.mjs (no paths passed — the script takes its own
change set from the merge base). It reproduced the dispatch-named families and
added node scripts/check-dev-prereqs.mjs, plus the five changeset families
once .changeset/ carried a file.

Green union re-run after the final commit, at 954e143: eighteen gates —
check:cross-package-test-inputs, check:doc-formula-expressions,
check:empty-state, check:liveness, check:merge-driver,
check:slot-lookup, check:spec-parsed-alias, check:strictness-ledger,
check:test-source-alias, check:type-source-resolution, check:variant-docs,
check-affected-docs.mjs, check:changeset-gate-self-tests,
check:objectui-changeset, check-adr-0087-registration.mjs,
check-changeset-no-major.mjs, check-empty-changeset.mjs,
check-nul-bytes.mjs. @objectstack/spec and @objectstack/client typecheck
both pass.

One declared exception: node scripts/check-dev-prereqs.mjs is red locally, and
its own verdict says why — "The workspace is not built — 1 unmet precondition,
not a list of problems", listing 36 of 67 packages whose dist/ entry point is
absent. That is a fact about this worktree's build state, not about the diff:
the gate reads built entry points, and a diff of comment lines adds no package
and no entry point. CI builds the workspace before its gates run, so it is
satisfied there structurally. A full pnpm build was deliberately not run for
this — it would hold the shared verify lock for many minutes across a container
of parallel agents to satisfy a precondition unrelated to a two-docblock change.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

10 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/assistant/chat (route))
• content/docs/api/client-sdk.mdx (via ObjectStackClient (symbol))
• content/docs/api/environment-routing.mdx (via ObjectStackClient (symbol))
• content/docs/api/wire-format.mdx (via ObjectStackClient (symbol))
• content/docs/getting-started/quick-reference.mdx (via AppSchema (symbol))
• content/docs/kernel/runtime-services/data-service.mdx (via ObjectStackClient (symbol))
• content/docs/kernel/runtime-services/storage-service.mdx (via ObjectStackClient (symbol))
• content/docs/permissions/authentication.mdx (via ObjectStackClient (symbol))
• content/docs/plugins/packages.mdx (via ObjectStackClient (symbol))
• content/docs/protocol/kernel/realtime-protocol.mdx (via ObjectStackClient (symbol))

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

• content/docs/releases/v14.mdx (via AppSchema (symbol))
• content/docs/releases/v17.mdx (via AppSchema (symbol), ObjectStackClient (symbol), /api/v1/ai/chat (route))

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 45 of 221 client-bound route-ledger rows — the other 176 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 129 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 bde0ab95de0c5b3f2f18a6960dfda1ff06f7cd82 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 07fd0f9a3d221da94c8f78a6b339519a2814977c — the merge of head 954e1430266679fbf819be0ec559a5dfa0abbc09 into base bde0ab95de0c5b3f2f18a6960dfda1ff06f7cd82, 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 07fd0f9a3d221da94c8f78a6b339519a2814977c && git checkout 07fd0f9a3d221da94c8f78a6b339519a2814977c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin bde0ab95de0c5b3f2f18a6960dfda1ff06f7cd82 954e1430266679fbf819be0ec559a5dfa0abbc09 && git checkout -B drift-repro bde0ab95de0c5b3f2f18a6960dfda1ff06f7cd82 && git merge --no-ff 954e1430266679fbf819be0ec559a5dfa0abbc09

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

⚠️ 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 bde0ab95de0c5b3f2f18a6960dfda1ff06f7cd82 → pass the list as
args.docs, on the commit named under Which tree this was computed on.