fix(ai): author the canonical agent id everywhere the platform teaches one (#14461)

[hotlong]

Closes#14461. Maintainer ruling (2026-09-03): option A, full — Studio re-pinned, MCP example corrected, lint value roster narrowed.

The finding, and the one thing that made it a ruling

skills/objectstack-ai tells authors that data_chat and metadata_assistant "are not vocabulary — always write ask / build". Every live example the platform shipped taught the opposite. The card could not decide which side moves, because the deciding fact lived in the closed cloud repo: does service-ai-studio register under the legacy id? If it did, re-pinning would be a behaviour change in a consumer this repo cannot see.

Measured, not assumed. At cloudmain@3856fbf7:

// service-ai-studio/src/agents/metadata-assistant-agent.ts
:12exportconstBUILD_AGENT_NAME='build';
:15exportconstLEGACY_BUILD_AGENT_NAME='metadata_assistant';
:40 name: BUILD_AGENT_NAME,// ← the record's canonical id// service-ai-studio/src/plugin.ts
:58registerAgentAlias(LEGACY_BUILD_AGENT_NAME,BUILD_AGENT_NAME);

The alias table is one-way, legacy→canonical, and service-ai/src/agents/agent-aliases.ts:20-23 states it is "resolution-only: they are NOT separate metadata records". The canonical id isbuild. The reading that made this undecidable is falsified; the skill's sentence was right and the code was residue.

Three sites, one spelling

1. studio.app.ts — the repo's only app.defaultAgent usage.

- defaultAgent: 'metadata_assistant',+ defaultAgent: 'build',

This is not cosmetic. The alias resolves only if an in-memory registerAgentAlias call has actually run, and cloud carries two defensive docblocks about that registration silently no-op'ing for real under bundle load ordering — service-ai-studio/src/plugin.ts:44-57 (use the string constant, never AGENT.name, or the guard no-ops and "drops build from both the legacy alias AND the framework's listAgents catalog") and service-ai/src/agent-runtime.ts:30-41 ("a missed alias must never hide a real platform agent like build"). The canonical id never touches the alias table, so the re-pin removes a load-order dependency from the platform's own flagship authoring surface.

Nothing moves on the UI side: objectui's AGENT_ALIAS_GROUPS is bidirectional and canonical-first (['build','metadata_assistant']), surfaceAgent.ts:82 bounds the key by group membership, and SURFACE_DEFAULT['studio-build'] was already 'build'. Measured at objectuimain@e3784607f.

2. mcp-server-runtime.ts:1349 — a site the card's census did not reach, and the louder one, because it is served to LLM clients at runtime:

- agentName: z.string().describe('Name of the agent to load (e.g. "data_chat", "metadata_assistant")'),+ agentName: z.string().describe('Name of the agent to load (e.g. "ask", "build")'),

Two retired aliases, neither canonical id present. Every MCP client asking what to pass was handed the exact two spellings the catalogue forbids.

3. validate-ai-agent-authoring — the gate itself. The defaultAgentvalue limb reused the four-name PLATFORM_AGENT_NAMES set, so it deliberately accepted metadata_assistant. The rule that exists to make authoring mistakes loud waved through the banned spelling — the silent-tolerance shape ADR-0078 exists to close, committed by the gate.

The two limbs now read different tables, because they ask different questions:

limb	question	roster	change
declaration	does this record shadow a platform record?	all four	none — declaring metadata_assistant shadows build through the alias exactly as declaring build does
value	is this the right thing to write?	ask / build	a legacy alias now warns under its own rule id default-agent-legacy-alias (exported)

Separate rule ids because the two defects are genuinely different: an alias resolves (the app gets the agent it meant — a spelling defect), an unknown name does not (the pin is inert). A message describing the alias as "has no effect" would send an author hunting a bug that is not there; there is a test pinning exactly that distinction.

#6041's ruling is intact. Its two operative decisions were warning tier, not error and no Zod enum narrowing. Both stand. defaultAgent: 'metadata_assistant' still parses, still builds, still resolves — the only change is that authoring it now says so.

Two corrections to the card's suggested inputs

• No pin test guarded the value.defaultAgent appears in packages/platform-objects only at studio.app.ts:48,50 — the comment and the value. One-liner plus its comment; nothing to update.
• The retired-keys registry cannot carry this residue.packages/spec/src/migrations/entries/retired-keys/ (76 entries) is keyed <domain>/<Type>:<key> — it records retired keys. metadata_assistant is a retired value of a live key, which that registry has no shape for. The residue is recorded where it will actually be read instead: the pin site's comment, the rule's docblock, and the tests. A value-level ledger shape is a separate card if it is wanted.

Verification

@objectstack/lint	93 files / 2845 tests pass (incl. reference-integrity-suite membership)
@objectstack/mcp	25 files / 271 tests pass
@objectstack/platform-objects	33 files / 518 tests pass
build	turbo build green for all three (dts emitted)
gates	check:skill-identifier-liveness, check:corpus-claim-drift, check:doc-authoring, check:empty-changeset, check:adr-0087-registration, check:changeset-gate-self-tests — all EXIT=0
eslint	clean on all five changed files

Not breaking: nothing an author can write was removed, and both aliases stay resolvable for old bookmarks and persisted agent_ids — the only job ADR-0063 §2 ever gave them.

🤖 Generated with Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/lint, @objectstack/mcp, @objectstack/platform-objects, touching 10 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/lint/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/ui/apps.mdx(via defaultAgent (symbol, a field of const object STUDIO_APP))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/lint/src/index.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 17 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 df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 — the merge of head 2a18188f8d6899b85f3090ea849eebe2ec4aa697 into base df657d9df1fac5a2222f183008532613a1df585f, 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 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 && git checkout 5d575e9eb27f9d5603d454353bcf4eb69d1bba11
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f 2a18188f8d6899b85f3090ea849eebe2ec4aa697 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff 2a18188f8d6899b85f3090ea849eebe2ec4aa697
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

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

[hotlong]

Closes#14461. Maintainer ruling (2026-09-03): option A, full — Studio re-pinned, MCP example corrected, lint value roster narrowed.

The finding, and the one thing that made it a ruling

skills/objectstack-ai tells authors that data_chat and metadata_assistant "are not vocabulary — always write ask / build". Every live example the platform shipped taught the opposite. The card could not decide which side moves, because the deciding fact lived in the closed cloud repo: does service-ai-studio register under the legacy id? If it did, re-pinning would be a behaviour change in a consumer this repo cannot see.

Measured, not assumed. At cloudmain@3856fbf7:

// service-ai-studio/src/agents/metadata-assistant-agent.ts
:12exportconstBUILD_AGENT_NAME='build';
:15exportconstLEGACY_BUILD_AGENT_NAME='metadata_assistant';
:40 name: BUILD_AGENT_NAME,// ← the record's canonical id// service-ai-studio/src/plugin.ts
:58registerAgentAlias(LEGACY_BUILD_AGENT_NAME,BUILD_AGENT_NAME);

The alias table is one-way, legacy→canonical, and service-ai/src/agents/agent-aliases.ts:20-23 states it is "resolution-only: they are NOT separate metadata records". The canonical id isbuild. The reading that made this undecidable is falsified; the skill's sentence was right and the code was residue.

Three sites, one spelling

1. studio.app.ts — the repo's only app.defaultAgent usage.

- defaultAgent: 'metadata_assistant',+ defaultAgent: 'build',

This is not cosmetic. The alias resolves only if an in-memory registerAgentAlias call has actually run, and cloud carries two defensive docblocks about that registration silently no-op'ing for real under bundle load ordering — service-ai-studio/src/plugin.ts:44-57 (use the string constant, never AGENT.name, or the guard no-ops and "drops build from both the legacy alias AND the framework's listAgents catalog") and service-ai/src/agent-runtime.ts:30-41 ("a missed alias must never hide a real platform agent like build"). The canonical id never touches the alias table, so the re-pin removes a load-order dependency from the platform's own flagship authoring surface.

Nothing moves on the UI side: objectui's AGENT_ALIAS_GROUPS is bidirectional and canonical-first (['build','metadata_assistant']), surfaceAgent.ts:82 bounds the key by group membership, and SURFACE_DEFAULT['studio-build'] was already 'build'. Measured at objectuimain@e3784607f.

2. mcp-server-runtime.ts:1349 — a site the card's census did not reach, and the louder one, because it is served to LLM clients at runtime:

- agentName: z.string().describe('Name of the agent to load (e.g. "data_chat", "metadata_assistant")'),+ agentName: z.string().describe('Name of the agent to load (e.g. "ask", "build")'),

Two retired aliases, neither canonical id present. Every MCP client asking what to pass was handed the exact two spellings the catalogue forbids.

3. validate-ai-agent-authoring — the gate itself. The defaultAgentvalue limb reused the four-name PLATFORM_AGENT_NAMES set, so it deliberately accepted metadata_assistant. The rule that exists to make authoring mistakes loud waved through the banned spelling — the silent-tolerance shape ADR-0078 exists to close, committed by the gate.

The two limbs now read different tables, because they ask different questions:

limb	question	roster	change
declaration	does this record shadow a platform record?	all four	none — declaring metadata_assistant shadows build through the alias exactly as declaring build does
value	is this the right thing to write?	ask / build	a legacy alias now warns under its own rule id default-agent-legacy-alias (exported)

Separate rule ids because the two defects are genuinely different: an alias resolves (the app gets the agent it meant — a spelling defect), an unknown name does not (the pin is inert). A message describing the alias as "has no effect" would send an author hunting a bug that is not there; there is a test pinning exactly that distinction.

#6041's ruling is intact. Its two operative decisions were warning tier, not error and no Zod enum narrowing. Both stand. defaultAgent: 'metadata_assistant' still parses, still builds, still resolves — the only change is that authoring it now says so.

Two corrections to the card's suggested inputs

• No pin test guarded the value.defaultAgent appears in packages/platform-objects only at studio.app.ts:48,50 — the comment and the value. One-liner plus its comment; nothing to update.
• The retired-keys registry cannot carry this residue.packages/spec/src/migrations/entries/retired-keys/ (76 entries) is keyed <domain>/<Type>:<key> — it records retired keys. metadata_assistant is a retired value of a live key, which that registry has no shape for. The residue is recorded where it will actually be read instead: the pin site's comment, the rule's docblock, and the tests. A value-level ledger shape is a separate card if it is wanted.

Verification

@objectstack/lint	93 files / 2845 tests pass (incl. reference-integrity-suite membership)
@objectstack/mcp	25 files / 271 tests pass
@objectstack/platform-objects	33 files / 518 tests pass
build	turbo build green for all three (dts emitted)
gates	check:skill-identifier-liveness, check:corpus-claim-drift, check:doc-authoring, check:empty-changeset, check:adr-0087-registration, check:changeset-gate-self-tests — all EXIT=0
eslint	clean on all five changed files

Not breaking: nothing an author can write was removed, and both aliases stay resolvable for old bookmarks and persisted agent_ids — the only job ADR-0063 §2 ever gave them.

🤖 Generated with Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/lint, @objectstack/mcp, @objectstack/platform-objects, touching 10 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/lint/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/ui/apps.mdx(via defaultAgent (symbol, a field of const object STUDIO_APP))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/lint/src/index.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 17 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 df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 — the merge of head 2a18188f8d6899b85f3090ea849eebe2ec4aa697 into base df657d9df1fac5a2222f183008532613a1df585f, 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 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 && git checkout 5d575e9eb27f9d5603d454353bcf4eb69d1bba11
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f 2a18188f8d6899b85f3090ea849eebe2ec4aa697 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff 2a18188f8d6899b85f3090ea849eebe2ec4aa697
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

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

[hotlong]

Closes#14461. Maintainer ruling (2026-09-03): option A, full — Studio re-pinned, MCP example corrected, lint value roster narrowed.

The finding, and the one thing that made it a ruling

skills/objectstack-ai tells authors that data_chat and metadata_assistant "are not vocabulary — always write ask / build". Every live example the platform shipped taught the opposite. The card could not decide which side moves, because the deciding fact lived in the closed cloud repo: does service-ai-studio register under the legacy id? If it did, re-pinning would be a behaviour change in a consumer this repo cannot see.

Measured, not assumed. At cloudmain@3856fbf7:

// service-ai-studio/src/agents/metadata-assistant-agent.ts
:12exportconstBUILD_AGENT_NAME='build';
:15exportconstLEGACY_BUILD_AGENT_NAME='metadata_assistant';
:40 name: BUILD_AGENT_NAME,// ← the record's canonical id// service-ai-studio/src/plugin.ts
:58registerAgentAlias(LEGACY_BUILD_AGENT_NAME,BUILD_AGENT_NAME);

The alias table is one-way, legacy→canonical, and service-ai/src/agents/agent-aliases.ts:20-23 states it is "resolution-only: they are NOT separate metadata records". The canonical id isbuild. The reading that made this undecidable is falsified; the skill's sentence was right and the code was residue.

Three sites, one spelling

1. studio.app.ts — the repo's only app.defaultAgent usage.

- defaultAgent: 'metadata_assistant',+ defaultAgent: 'build',

This is not cosmetic. The alias resolves only if an in-memory registerAgentAlias call has actually run, and cloud carries two defensive docblocks about that registration silently no-op'ing for real under bundle load ordering — service-ai-studio/src/plugin.ts:44-57 (use the string constant, never AGENT.name, or the guard no-ops and "drops build from both the legacy alias AND the framework's listAgents catalog") and service-ai/src/agent-runtime.ts:30-41 ("a missed alias must never hide a real platform agent like build"). The canonical id never touches the alias table, so the re-pin removes a load-order dependency from the platform's own flagship authoring surface.

Nothing moves on the UI side: objectui's AGENT_ALIAS_GROUPS is bidirectional and canonical-first (['build','metadata_assistant']), surfaceAgent.ts:82 bounds the key by group membership, and SURFACE_DEFAULT['studio-build'] was already 'build'. Measured at objectuimain@e3784607f.

2. mcp-server-runtime.ts:1349 — a site the card's census did not reach, and the louder one, because it is served to LLM clients at runtime:

- agentName: z.string().describe('Name of the agent to load (e.g. "data_chat", "metadata_assistant")'),+ agentName: z.string().describe('Name of the agent to load (e.g. "ask", "build")'),

Two retired aliases, neither canonical id present. Every MCP client asking what to pass was handed the exact two spellings the catalogue forbids.

3. validate-ai-agent-authoring — the gate itself. The defaultAgentvalue limb reused the four-name PLATFORM_AGENT_NAMES set, so it deliberately accepted metadata_assistant. The rule that exists to make authoring mistakes loud waved through the banned spelling — the silent-tolerance shape ADR-0078 exists to close, committed by the gate.

The two limbs now read different tables, because they ask different questions:

limb	question	roster	change
declaration	does this record shadow a platform record?	all four	none — declaring metadata_assistant shadows build through the alias exactly as declaring build does
value	is this the right thing to write?	ask / build	a legacy alias now warns under its own rule id default-agent-legacy-alias (exported)

Separate rule ids because the two defects are genuinely different: an alias resolves (the app gets the agent it meant — a spelling defect), an unknown name does not (the pin is inert). A message describing the alias as "has no effect" would send an author hunting a bug that is not there; there is a test pinning exactly that distinction.

#6041's ruling is intact. Its two operative decisions were warning tier, not error and no Zod enum narrowing. Both stand. defaultAgent: 'metadata_assistant' still parses, still builds, still resolves — the only change is that authoring it now says so.

Two corrections to the card's suggested inputs

• No pin test guarded the value.defaultAgent appears in packages/platform-objects only at studio.app.ts:48,50 — the comment and the value. One-liner plus its comment; nothing to update.
• The retired-keys registry cannot carry this residue.packages/spec/src/migrations/entries/retired-keys/ (76 entries) is keyed <domain>/<Type>:<key> — it records retired keys. metadata_assistant is a retired value of a live key, which that registry has no shape for. The residue is recorded where it will actually be read instead: the pin site's comment, the rule's docblock, and the tests. A value-level ledger shape is a separate card if it is wanted.

Verification

@objectstack/lint	93 files / 2845 tests pass (incl. reference-integrity-suite membership)
@objectstack/mcp	25 files / 271 tests pass
@objectstack/platform-objects	33 files / 518 tests pass
build	turbo build green for all three (dts emitted)
gates	check:skill-identifier-liveness, check:corpus-claim-drift, check:doc-authoring, check:empty-changeset, check:adr-0087-registration, check:changeset-gate-self-tests — all EXIT=0
eslint	clean on all five changed files

Not breaking: nothing an author can write was removed, and both aliases stay resolvable for old bookmarks and persisted agent_ids — the only job ADR-0063 §2 ever gave them.

🤖 Generated with Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/lint, @objectstack/mcp, @objectstack/platform-objects, touching 10 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/lint/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/ui/apps.mdx(via defaultAgent (symbol, a field of const object STUDIO_APP))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/lint/src/index.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 17 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 df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 — the merge of head 2a18188f8d6899b85f3090ea849eebe2ec4aa697 into base df657d9df1fac5a2222f183008532613a1df585f, 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 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 && git checkout 5d575e9eb27f9d5603d454353bcf4eb69d1bba11
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f 2a18188f8d6899b85f3090ea849eebe2ec4aa697 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff 2a18188f8d6899b85f3090ea849eebe2ec4aa697
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

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

[hotlong]

Closes#14461. Maintainer ruling (2026-09-03): option A, full — Studio re-pinned, MCP example corrected, lint value roster narrowed.

The finding, and the one thing that made it a ruling

skills/objectstack-ai tells authors that data_chat and metadata_assistant "are not vocabulary — always write ask / build". Every live example the platform shipped taught the opposite. The card could not decide which side moves, because the deciding fact lived in the closed cloud repo: does service-ai-studio register under the legacy id? If it did, re-pinning would be a behaviour change in a consumer this repo cannot see.

Measured, not assumed. At cloudmain@3856fbf7:

// service-ai-studio/src/agents/metadata-assistant-agent.ts
:12exportconstBUILD_AGENT_NAME='build';
:15exportconstLEGACY_BUILD_AGENT_NAME='metadata_assistant';
:40 name: BUILD_AGENT_NAME,// ← the record's canonical id// service-ai-studio/src/plugin.ts
:58registerAgentAlias(LEGACY_BUILD_AGENT_NAME,BUILD_AGENT_NAME);

The alias table is one-way, legacy→canonical, and service-ai/src/agents/agent-aliases.ts:20-23 states it is "resolution-only: they are NOT separate metadata records". The canonical id isbuild. The reading that made this undecidable is falsified; the skill's sentence was right and the code was residue.

Three sites, one spelling

1. studio.app.ts — the repo's only app.defaultAgent usage.

- defaultAgent: 'metadata_assistant',+ defaultAgent: 'build',

This is not cosmetic. The alias resolves only if an in-memory registerAgentAlias call has actually run, and cloud carries two defensive docblocks about that registration silently no-op'ing for real under bundle load ordering — service-ai-studio/src/plugin.ts:44-57 (use the string constant, never AGENT.name, or the guard no-ops and "drops build from both the legacy alias AND the framework's listAgents catalog") and service-ai/src/agent-runtime.ts:30-41 ("a missed alias must never hide a real platform agent like build"). The canonical id never touches the alias table, so the re-pin removes a load-order dependency from the platform's own flagship authoring surface.

Nothing moves on the UI side: objectui's AGENT_ALIAS_GROUPS is bidirectional and canonical-first (['build','metadata_assistant']), surfaceAgent.ts:82 bounds the key by group membership, and SURFACE_DEFAULT['studio-build'] was already 'build'. Measured at objectuimain@e3784607f.

2. mcp-server-runtime.ts:1349 — a site the card's census did not reach, and the louder one, because it is served to LLM clients at runtime:

- agentName: z.string().describe('Name of the agent to load (e.g. "data_chat", "metadata_assistant")'),+ agentName: z.string().describe('Name of the agent to load (e.g. "ask", "build")'),

Two retired aliases, neither canonical id present. Every MCP client asking what to pass was handed the exact two spellings the catalogue forbids.

3. validate-ai-agent-authoring — the gate itself. The defaultAgentvalue limb reused the four-name PLATFORM_AGENT_NAMES set, so it deliberately accepted metadata_assistant. The rule that exists to make authoring mistakes loud waved through the banned spelling — the silent-tolerance shape ADR-0078 exists to close, committed by the gate.

The two limbs now read different tables, because they ask different questions:

limb	question	roster	change
declaration	does this record shadow a platform record?	all four	none — declaring metadata_assistant shadows build through the alias exactly as declaring build does
value	is this the right thing to write?	ask / build	a legacy alias now warns under its own rule id default-agent-legacy-alias (exported)

Separate rule ids because the two defects are genuinely different: an alias resolves (the app gets the agent it meant — a spelling defect), an unknown name does not (the pin is inert). A message describing the alias as "has no effect" would send an author hunting a bug that is not there; there is a test pinning exactly that distinction.

#6041's ruling is intact. Its two operative decisions were warning tier, not error and no Zod enum narrowing. Both stand. defaultAgent: 'metadata_assistant' still parses, still builds, still resolves — the only change is that authoring it now says so.

Two corrections to the card's suggested inputs

• No pin test guarded the value.defaultAgent appears in packages/platform-objects only at studio.app.ts:48,50 — the comment and the value. One-liner plus its comment; nothing to update.
• The retired-keys registry cannot carry this residue.packages/spec/src/migrations/entries/retired-keys/ (76 entries) is keyed <domain>/<Type>:<key> — it records retired keys. metadata_assistant is a retired value of a live key, which that registry has no shape for. The residue is recorded where it will actually be read instead: the pin site's comment, the rule's docblock, and the tests. A value-level ledger shape is a separate card if it is wanted.

Verification

@objectstack/lint	93 files / 2845 tests pass (incl. reference-integrity-suite membership)
@objectstack/mcp	25 files / 271 tests pass
@objectstack/platform-objects	33 files / 518 tests pass
build	turbo build green for all three (dts emitted)
gates	check:skill-identifier-liveness, check:corpus-claim-drift, check:doc-authoring, check:empty-changeset, check:adr-0087-registration, check:changeset-gate-self-tests — all EXIT=0
eslint	clean on all five changed files

Not breaking: nothing an author can write was removed, and both aliases stay resolvable for old bookmarks and persisted agent_ids — the only job ADR-0063 §2 ever gave them.

🤖 Generated with Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/lint, @objectstack/mcp, @objectstack/platform-objects, touching 10 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/lint/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/ui/apps.mdx(via defaultAgent (symbol, a field of const object STUDIO_APP))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/lint/src/index.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 17 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 df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 — the merge of head 2a18188f8d6899b85f3090ea849eebe2ec4aa697 into base df657d9df1fac5a2222f183008532613a1df585f, 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 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 && git checkout 5d575e9eb27f9d5603d454353bcf4eb69d1bba11
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f 2a18188f8d6899b85f3090ea849eebe2ec4aa697 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff 2a18188f8d6899b85f3090ea849eebe2ec4aa697
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

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

[hotlong]

Closes#14461. Maintainer ruling (2026-09-03): option A, full — Studio re-pinned, MCP example corrected, lint value roster narrowed.

The finding, and the one thing that made it a ruling

skills/objectstack-ai tells authors that data_chat and metadata_assistant "are not vocabulary — always write ask / build". Every live example the platform shipped taught the opposite. The card could not decide which side moves, because the deciding fact lived in the closed cloud repo: does service-ai-studio register under the legacy id? If it did, re-pinning would be a behaviour change in a consumer this repo cannot see.

Measured, not assumed. At cloudmain@3856fbf7:

// service-ai-studio/src/agents/metadata-assistant-agent.ts
:12exportconstBUILD_AGENT_NAME='build';
:15exportconstLEGACY_BUILD_AGENT_NAME='metadata_assistant';
:40 name: BUILD_AGENT_NAME,// ← the record's canonical id// service-ai-studio/src/plugin.ts
:58registerAgentAlias(LEGACY_BUILD_AGENT_NAME,BUILD_AGENT_NAME);

The alias table is one-way, legacy→canonical, and service-ai/src/agents/agent-aliases.ts:20-23 states it is "resolution-only: they are NOT separate metadata records". The canonical id isbuild. The reading that made this undecidable is falsified; the skill's sentence was right and the code was residue.

Three sites, one spelling

1. studio.app.ts — the repo's only app.defaultAgent usage.

- defaultAgent: 'metadata_assistant',+ defaultAgent: 'build',

This is not cosmetic. The alias resolves only if an in-memory registerAgentAlias call has actually run, and cloud carries two defensive docblocks about that registration silently no-op'ing for real under bundle load ordering — service-ai-studio/src/plugin.ts:44-57 (use the string constant, never AGENT.name, or the guard no-ops and "drops build from both the legacy alias AND the framework's listAgents catalog") and service-ai/src/agent-runtime.ts:30-41 ("a missed alias must never hide a real platform agent like build"). The canonical id never touches the alias table, so the re-pin removes a load-order dependency from the platform's own flagship authoring surface.

Nothing moves on the UI side: objectui's AGENT_ALIAS_GROUPS is bidirectional and canonical-first (['build','metadata_assistant']), surfaceAgent.ts:82 bounds the key by group membership, and SURFACE_DEFAULT['studio-build'] was already 'build'. Measured at objectuimain@e3784607f.

2. mcp-server-runtime.ts:1349 — a site the card's census did not reach, and the louder one, because it is served to LLM clients at runtime:

- agentName: z.string().describe('Name of the agent to load (e.g. "data_chat", "metadata_assistant")'),+ agentName: z.string().describe('Name of the agent to load (e.g. "ask", "build")'),

Two retired aliases, neither canonical id present. Every MCP client asking what to pass was handed the exact two spellings the catalogue forbids.

3. validate-ai-agent-authoring — the gate itself. The defaultAgentvalue limb reused the four-name PLATFORM_AGENT_NAMES set, so it deliberately accepted metadata_assistant. The rule that exists to make authoring mistakes loud waved through the banned spelling — the silent-tolerance shape ADR-0078 exists to close, committed by the gate.

The two limbs now read different tables, because they ask different questions:

limb	question	roster	change
declaration	does this record shadow a platform record?	all four	none — declaring metadata_assistant shadows build through the alias exactly as declaring build does
value	is this the right thing to write?	ask / build	a legacy alias now warns under its own rule id default-agent-legacy-alias (exported)

Separate rule ids because the two defects are genuinely different: an alias resolves (the app gets the agent it meant — a spelling defect), an unknown name does not (the pin is inert). A message describing the alias as "has no effect" would send an author hunting a bug that is not there; there is a test pinning exactly that distinction.

#6041's ruling is intact. Its two operative decisions were warning tier, not error and no Zod enum narrowing. Both stand. defaultAgent: 'metadata_assistant' still parses, still builds, still resolves — the only change is that authoring it now says so.

Two corrections to the card's suggested inputs

• No pin test guarded the value.defaultAgent appears in packages/platform-objects only at studio.app.ts:48,50 — the comment and the value. One-liner plus its comment; nothing to update.
• The retired-keys registry cannot carry this residue.packages/spec/src/migrations/entries/retired-keys/ (76 entries) is keyed <domain>/<Type>:<key> — it records retired keys. metadata_assistant is a retired value of a live key, which that registry has no shape for. The residue is recorded where it will actually be read instead: the pin site's comment, the rule's docblock, and the tests. A value-level ledger shape is a separate card if it is wanted.

Verification

@objectstack/lint	93 files / 2845 tests pass (incl. reference-integrity-suite membership)
@objectstack/mcp	25 files / 271 tests pass
@objectstack/platform-objects	33 files / 518 tests pass
build	turbo build green for all three (dts emitted)
gates	check:skill-identifier-liveness, check:corpus-claim-drift, check:doc-authoring, check:empty-changeset, check:adr-0087-registration, check:changeset-gate-self-tests — all EXIT=0
eslint	clean on all five changed files

Not breaking: nothing an author can write was removed, and both aliases stay resolvable for old bookmarks and persisted agent_ids — the only job ADR-0063 §2 ever gave them.

🤖 Generated with Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/lint, @objectstack/mcp, @objectstack/platform-objects, touching 10 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/lint/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/ui/apps.mdx(via defaultAgent (symbol, a field of const object STUDIO_APP))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/lint/src/index.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 17 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 df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 — the merge of head 2a18188f8d6899b85f3090ea849eebe2ec4aa697 into base df657d9df1fac5a2222f183008532613a1df585f, 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 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 && git checkout 5d575e9eb27f9d5603d454353bcf4eb69d1bba11
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f 2a18188f8d6899b85f3090ea849eebe2ec4aa697 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff 2a18188f8d6899b85f3090ea849eebe2ec4aa697
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

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

[hotlong]

Closes#14461. Maintainer ruling (2026-09-03): option A, full — Studio re-pinned, MCP example corrected, lint value roster narrowed.

The finding, and the one thing that made it a ruling

skills/objectstack-ai tells authors that data_chat and metadata_assistant "are not vocabulary — always write ask / build". Every live example the platform shipped taught the opposite. The card could not decide which side moves, because the deciding fact lived in the closed cloud repo: does service-ai-studio register under the legacy id? If it did, re-pinning would be a behaviour change in a consumer this repo cannot see.

Measured, not assumed. At cloudmain@3856fbf7:

// service-ai-studio/src/agents/metadata-assistant-agent.ts
:12exportconstBUILD_AGENT_NAME='build';
:15exportconstLEGACY_BUILD_AGENT_NAME='metadata_assistant';
:40 name: BUILD_AGENT_NAME,// ← the record's canonical id// service-ai-studio/src/plugin.ts
:58registerAgentAlias(LEGACY_BUILD_AGENT_NAME,BUILD_AGENT_NAME);

The alias table is one-way, legacy→canonical, and service-ai/src/agents/agent-aliases.ts:20-23 states it is "resolution-only: they are NOT separate metadata records". The canonical id isbuild. The reading that made this undecidable is falsified; the skill's sentence was right and the code was residue.

Three sites, one spelling

1. studio.app.ts — the repo's only app.defaultAgent usage.

- defaultAgent: 'metadata_assistant',+ defaultAgent: 'build',

This is not cosmetic. The alias resolves only if an in-memory registerAgentAlias call has actually run, and cloud carries two defensive docblocks about that registration silently no-op'ing for real under bundle load ordering — service-ai-studio/src/plugin.ts:44-57 (use the string constant, never AGENT.name, or the guard no-ops and "drops build from both the legacy alias AND the framework's listAgents catalog") and service-ai/src/agent-runtime.ts:30-41 ("a missed alias must never hide a real platform agent like build"). The canonical id never touches the alias table, so the re-pin removes a load-order dependency from the platform's own flagship authoring surface.

Nothing moves on the UI side: objectui's AGENT_ALIAS_GROUPS is bidirectional and canonical-first (['build','metadata_assistant']), surfaceAgent.ts:82 bounds the key by group membership, and SURFACE_DEFAULT['studio-build'] was already 'build'. Measured at objectuimain@e3784607f.

2. mcp-server-runtime.ts:1349 — a site the card's census did not reach, and the louder one, because it is served to LLM clients at runtime:

- agentName: z.string().describe('Name of the agent to load (e.g. "data_chat", "metadata_assistant")'),+ agentName: z.string().describe('Name of the agent to load (e.g. "ask", "build")'),

Two retired aliases, neither canonical id present. Every MCP client asking what to pass was handed the exact two spellings the catalogue forbids.

3. validate-ai-agent-authoring — the gate itself. The defaultAgentvalue limb reused the four-name PLATFORM_AGENT_NAMES set, so it deliberately accepted metadata_assistant. The rule that exists to make authoring mistakes loud waved through the banned spelling — the silent-tolerance shape ADR-0078 exists to close, committed by the gate.

The two limbs now read different tables, because they ask different questions:

limb	question	roster	change
declaration	does this record shadow a platform record?	all four	none — declaring metadata_assistant shadows build through the alias exactly as declaring build does
value	is this the right thing to write?	ask / build	a legacy alias now warns under its own rule id default-agent-legacy-alias (exported)

Separate rule ids because the two defects are genuinely different: an alias resolves (the app gets the agent it meant — a spelling defect), an unknown name does not (the pin is inert). A message describing the alias as "has no effect" would send an author hunting a bug that is not there; there is a test pinning exactly that distinction.

#6041's ruling is intact. Its two operative decisions were warning tier, not error and no Zod enum narrowing. Both stand. defaultAgent: 'metadata_assistant' still parses, still builds, still resolves — the only change is that authoring it now says so.

Two corrections to the card's suggested inputs

• No pin test guarded the value.defaultAgent appears in packages/platform-objects only at studio.app.ts:48,50 — the comment and the value. One-liner plus its comment; nothing to update.
• The retired-keys registry cannot carry this residue.packages/spec/src/migrations/entries/retired-keys/ (76 entries) is keyed <domain>/<Type>:<key> — it records retired keys. metadata_assistant is a retired value of a live key, which that registry has no shape for. The residue is recorded where it will actually be read instead: the pin site's comment, the rule's docblock, and the tests. A value-level ledger shape is a separate card if it is wanted.

Verification

@objectstack/lint	93 files / 2845 tests pass (incl. reference-integrity-suite membership)
@objectstack/mcp	25 files / 271 tests pass
@objectstack/platform-objects	33 files / 518 tests pass
build	turbo build green for all three (dts emitted)
gates	check:skill-identifier-liveness, check:corpus-claim-drift, check:doc-authoring, check:empty-changeset, check:adr-0087-registration, check:changeset-gate-self-tests — all EXIT=0
eslint	clean on all five changed files

Not breaking: nothing an author can write was removed, and both aliases stay resolvable for old bookmarks and persisted agent_ids — the only job ADR-0063 §2 ever gave them.

🤖 Generated with Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/lint, @objectstack/mcp, @objectstack/platform-objects, touching 10 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/lint/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/ui/apps.mdx(via defaultAgent (symbol, a field of const object STUDIO_APP))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/lint/src/index.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 17 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 df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 — the merge of head 2a18188f8d6899b85f3090ea849eebe2ec4aa697 into base df657d9df1fac5a2222f183008532613a1df585f, 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 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 && git checkout 5d575e9eb27f9d5603d454353bcf4eb69d1bba11
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f 2a18188f8d6899b85f3090ea849eebe2ec4aa697 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff 2a18188f8d6899b85f3090ea849eebe2ec4aa697
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

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

[hotlong]

Closes#14461. Maintainer ruling (2026-09-03): option A, full — Studio re-pinned, MCP example corrected, lint value roster narrowed.

The finding, and the one thing that made it a ruling

skills/objectstack-ai tells authors that data_chat and metadata_assistant "are not vocabulary — always write ask / build". Every live example the platform shipped taught the opposite. The card could not decide which side moves, because the deciding fact lived in the closed cloud repo: does service-ai-studio register under the legacy id? If it did, re-pinning would be a behaviour change in a consumer this repo cannot see.

Measured, not assumed. At cloudmain@3856fbf7:

// service-ai-studio/src/agents/metadata-assistant-agent.ts
:12exportconstBUILD_AGENT_NAME='build';
:15exportconstLEGACY_BUILD_AGENT_NAME='metadata_assistant';
:40 name: BUILD_AGENT_NAME,// ← the record's canonical id// service-ai-studio/src/plugin.ts
:58registerAgentAlias(LEGACY_BUILD_AGENT_NAME,BUILD_AGENT_NAME);

The alias table is one-way, legacy→canonical, and service-ai/src/agents/agent-aliases.ts:20-23 states it is "resolution-only: they are NOT separate metadata records". The canonical id isbuild. The reading that made this undecidable is falsified; the skill's sentence was right and the code was residue.

Three sites, one spelling

1. studio.app.ts — the repo's only app.defaultAgent usage.

- defaultAgent: 'metadata_assistant',+ defaultAgent: 'build',

This is not cosmetic. The alias resolves only if an in-memory registerAgentAlias call has actually run, and cloud carries two defensive docblocks about that registration silently no-op'ing for real under bundle load ordering — service-ai-studio/src/plugin.ts:44-57 (use the string constant, never AGENT.name, or the guard no-ops and "drops build from both the legacy alias AND the framework's listAgents catalog") and service-ai/src/agent-runtime.ts:30-41 ("a missed alias must never hide a real platform agent like build"). The canonical id never touches the alias table, so the re-pin removes a load-order dependency from the platform's own flagship authoring surface.

Nothing moves on the UI side: objectui's AGENT_ALIAS_GROUPS is bidirectional and canonical-first (['build','metadata_assistant']), surfaceAgent.ts:82 bounds the key by group membership, and SURFACE_DEFAULT['studio-build'] was already 'build'. Measured at objectuimain@e3784607f.

2. mcp-server-runtime.ts:1349 — a site the card's census did not reach, and the louder one, because it is served to LLM clients at runtime:

- agentName: z.string().describe('Name of the agent to load (e.g. "data_chat", "metadata_assistant")'),+ agentName: z.string().describe('Name of the agent to load (e.g. "ask", "build")'),

Two retired aliases, neither canonical id present. Every MCP client asking what to pass was handed the exact two spellings the catalogue forbids.

3. validate-ai-agent-authoring — the gate itself. The defaultAgentvalue limb reused the four-name PLATFORM_AGENT_NAMES set, so it deliberately accepted metadata_assistant. The rule that exists to make authoring mistakes loud waved through the banned spelling — the silent-tolerance shape ADR-0078 exists to close, committed by the gate.

The two limbs now read different tables, because they ask different questions:

limb	question	roster	change
declaration	does this record shadow a platform record?	all four	none — declaring metadata_assistant shadows build through the alias exactly as declaring build does
value	is this the right thing to write?	ask / build	a legacy alias now warns under its own rule id default-agent-legacy-alias (exported)

Separate rule ids because the two defects are genuinely different: an alias resolves (the app gets the agent it meant — a spelling defect), an unknown name does not (the pin is inert). A message describing the alias as "has no effect" would send an author hunting a bug that is not there; there is a test pinning exactly that distinction.

#6041's ruling is intact. Its two operative decisions were warning tier, not error and no Zod enum narrowing. Both stand. defaultAgent: 'metadata_assistant' still parses, still builds, still resolves — the only change is that authoring it now says so.

Two corrections to the card's suggested inputs

• No pin test guarded the value.defaultAgent appears in packages/platform-objects only at studio.app.ts:48,50 — the comment and the value. One-liner plus its comment; nothing to update.
• The retired-keys registry cannot carry this residue.packages/spec/src/migrations/entries/retired-keys/ (76 entries) is keyed <domain>/<Type>:<key> — it records retired keys. metadata_assistant is a retired value of a live key, which that registry has no shape for. The residue is recorded where it will actually be read instead: the pin site's comment, the rule's docblock, and the tests. A value-level ledger shape is a separate card if it is wanted.

Verification

@objectstack/lint	93 files / 2845 tests pass (incl. reference-integrity-suite membership)
@objectstack/mcp	25 files / 271 tests pass
@objectstack/platform-objects	33 files / 518 tests pass
build	turbo build green for all three (dts emitted)
gates	check:skill-identifier-liveness, check:corpus-claim-drift, check:doc-authoring, check:empty-changeset, check:adr-0087-registration, check:changeset-gate-self-tests — all EXIT=0
eslint	clean on all five changed files

Not breaking: nothing an author can write was removed, and both aliases stay resolvable for old bookmarks and persisted agent_ids — the only job ADR-0063 §2 ever gave them.

🤖 Generated with Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/lint, @objectstack/mcp, @objectstack/platform-objects, touching 10 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/lint/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/ui/apps.mdx(via defaultAgent (symbol, a field of const object STUDIO_APP))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/lint/src/index.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 17 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 df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 — the merge of head 2a18188f8d6899b85f3090ea849eebe2ec4aa697 into base df657d9df1fac5a2222f183008532613a1df585f, 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 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 && git checkout 5d575e9eb27f9d5603d454353bcf4eb69d1bba11
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f 2a18188f8d6899b85f3090ea849eebe2ec4aa697 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff 2a18188f8d6899b85f3090ea849eebe2ec4aa697
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

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

[hotlong]

Closes#14461. Maintainer ruling (2026-09-03): option A, full — Studio re-pinned, MCP example corrected, lint value roster narrowed.

The finding, and the one thing that made it a ruling

skills/objectstack-ai tells authors that data_chat and metadata_assistant "are not vocabulary — always write ask / build". Every live example the platform shipped taught the opposite. The card could not decide which side moves, because the deciding fact lived in the closed cloud repo: does service-ai-studio register under the legacy id? If it did, re-pinning would be a behaviour change in a consumer this repo cannot see.

Measured, not assumed. At cloudmain@3856fbf7:

// service-ai-studio/src/agents/metadata-assistant-agent.ts
:12exportconstBUILD_AGENT_NAME='build';
:15exportconstLEGACY_BUILD_AGENT_NAME='metadata_assistant';
:40 name: BUILD_AGENT_NAME,// ← the record's canonical id// service-ai-studio/src/plugin.ts
:58registerAgentAlias(LEGACY_BUILD_AGENT_NAME,BUILD_AGENT_NAME);

The alias table is one-way, legacy→canonical, and service-ai/src/agents/agent-aliases.ts:20-23 states it is "resolution-only: they are NOT separate metadata records". The canonical id isbuild. The reading that made this undecidable is falsified; the skill's sentence was right and the code was residue.

Three sites, one spelling

1. studio.app.ts — the repo's only app.defaultAgent usage.

- defaultAgent: 'metadata_assistant',+ defaultAgent: 'build',

This is not cosmetic. The alias resolves only if an in-memory registerAgentAlias call has actually run, and cloud carries two defensive docblocks about that registration silently no-op'ing for real under bundle load ordering — service-ai-studio/src/plugin.ts:44-57 (use the string constant, never AGENT.name, or the guard no-ops and "drops build from both the legacy alias AND the framework's listAgents catalog") and service-ai/src/agent-runtime.ts:30-41 ("a missed alias must never hide a real platform agent like build"). The canonical id never touches the alias table, so the re-pin removes a load-order dependency from the platform's own flagship authoring surface.

Nothing moves on the UI side: objectui's AGENT_ALIAS_GROUPS is bidirectional and canonical-first (['build','metadata_assistant']), surfaceAgent.ts:82 bounds the key by group membership, and SURFACE_DEFAULT['studio-build'] was already 'build'. Measured at objectuimain@e3784607f.

2. mcp-server-runtime.ts:1349 — a site the card's census did not reach, and the louder one, because it is served to LLM clients at runtime:

- agentName: z.string().describe('Name of the agent to load (e.g. "data_chat", "metadata_assistant")'),+ agentName: z.string().describe('Name of the agent to load (e.g. "ask", "build")'),

Two retired aliases, neither canonical id present. Every MCP client asking what to pass was handed the exact two spellings the catalogue forbids.

3. validate-ai-agent-authoring — the gate itself. The defaultAgentvalue limb reused the four-name PLATFORM_AGENT_NAMES set, so it deliberately accepted metadata_assistant. The rule that exists to make authoring mistakes loud waved through the banned spelling — the silent-tolerance shape ADR-0078 exists to close, committed by the gate.

The two limbs now read different tables, because they ask different questions:

limb	question	roster	change
declaration	does this record shadow a platform record?	all four	none — declaring metadata_assistant shadows build through the alias exactly as declaring build does
value	is this the right thing to write?	ask / build	a legacy alias now warns under its own rule id default-agent-legacy-alias (exported)

Separate rule ids because the two defects are genuinely different: an alias resolves (the app gets the agent it meant — a spelling defect), an unknown name does not (the pin is inert). A message describing the alias as "has no effect" would send an author hunting a bug that is not there; there is a test pinning exactly that distinction.

#6041's ruling is intact. Its two operative decisions were warning tier, not error and no Zod enum narrowing. Both stand. defaultAgent: 'metadata_assistant' still parses, still builds, still resolves — the only change is that authoring it now says so.

Two corrections to the card's suggested inputs

• No pin test guarded the value.defaultAgent appears in packages/platform-objects only at studio.app.ts:48,50 — the comment and the value. One-liner plus its comment; nothing to update.
• The retired-keys registry cannot carry this residue.packages/spec/src/migrations/entries/retired-keys/ (76 entries) is keyed <domain>/<Type>:<key> — it records retired keys. metadata_assistant is a retired value of a live key, which that registry has no shape for. The residue is recorded where it will actually be read instead: the pin site's comment, the rule's docblock, and the tests. A value-level ledger shape is a separate card if it is wanted.

Verification

@objectstack/lint	93 files / 2845 tests pass (incl. reference-integrity-suite membership)
@objectstack/mcp	25 files / 271 tests pass
@objectstack/platform-objects	33 files / 518 tests pass
build	turbo build green for all three (dts emitted)
gates	check:skill-identifier-liveness, check:corpus-claim-drift, check:doc-authoring, check:empty-changeset, check:adr-0087-registration, check:changeset-gate-self-tests — all EXIT=0
eslint	clean on all five changed files

Not breaking: nothing an author can write was removed, and both aliases stay resolvable for old bookmarks and persisted agent_ids — the only job ADR-0063 §2 ever gave them.

🤖 Generated with Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/lint, @objectstack/mcp, @objectstack/platform-objects, touching 10 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/lint/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/ui/apps.mdx(via defaultAgent (symbol, a field of const object STUDIO_APP))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/lint/src/index.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 17 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 df657d9df1fac5a2222f183008532613a1df585f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 — the merge of head 2a18188f8d6899b85f3090ea849eebe2ec4aa697 into base df657d9df1fac5a2222f183008532613a1df585f, 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 5d575e9eb27f9d5603d454353bcf4eb69d1bba11 && git checkout 5d575e9eb27f9d5603d454353bcf4eb69d1bba11
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df657d9df1fac5a2222f183008532613a1df585f 2a18188f8d6899b85f3090ea849eebe2ec4aa697 && git checkout -B drift-repro df657d9df1fac5a2222f183008532613a1df585f && git merge --no-ff 2a18188f8d6899b85f3090ea849eebe2ec4aa697
node scripts/docs-audit/affected-docs.mjs --json df657d9df1fac5a2222f183008532613a1df585f

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