docs(mcp): correct MCPServerPlugin's docblock to the canonical stdio switch

[os-trump]

Fixes#14473

MCPServerPlugin's own class docblock still taught the pre-split stdio
trigger, about 100 lines above a runtime warning saying the opposite.

Step 2 said the long-lived transport starts "only when autoStart is enabled or
OS_MCP_SERVER_ENABLED is explicitly true", and the Environment Variables
block said explicit true "additionally auto-starts the stdio transport".
Neither named OS_MCP_STDIO_ENABLED anywhere.

Read against the authority — resolveMcpStdioAutoStart() in
packages/types/src/env.ts — that is backwards. The resolver reads
OS_MCP_STDIO_ENABLED first and returns it clean; OS_MCP_SERVER_ENABLED=true
falls through to a legacy branch that returns viaDeprecatedAlias: true, and
start() then warns the operator that this exact trigger is DEPRECATED. So the
docblock presented the deprecated trigger as the design and never named the
canonical one. An author following it got a working transport plus a
deprecation warning at every boot, with no way from this file to learn the
right spelling.

A comment card with a demonstrated downstream

This is not tidiness. The published skills/objectstack-ai MCP section was
written from this docblock and inherited the same error — caught in contract
review and corrected by PR #14463 (5dabfd2a). This file is the upstream of that
defect and was still uncorrected. One catch happened to be in review; the next
may not be.

The change

packages/mcp/src/plugin.ts, comments only, no behaviour change:

• step 2 — starts "only when autoStart is enabled or
  OS_MCP_STDIO_ENABLED is truthy";
• Environment Variables — OS_MCP_SERVER_ENABLED is described as the
  default-on HTTP gate only; OS_MCP_STDIO_ENABLED is added as the stdio
  transport's own switch (default OFF); and the legacy trigger is marked
  deprecated in the runtime warning's own words, copied verbatim from the
  ctx.logger.warn below it rather than paraphrased, so the two cannot drift
  into two phrasings of one rule.

Both blocks now point at the two decision points by name (isMcpServerEnabled,
resolveMcpStdioAutoStart) so the next reader lands on the authority instead of
on prose about it.

The blast radius stayed at one file, re-measured

Triage measured that every neighbour was already updated when the split landed.
I re-ran that independently rather than taking it on trust, with a positive
control first:

git grep -n 'OS_MCP_SERVER_ENABLED' -- ':(glob)packages/**' ':(glob)content/**' \
':(glob)skills/**' ':(glob)apps/**' ':(exclude)*CHANGELOG.md' \
':(exclude)content/docs/releases/**'

Positive control: the same pathspec and flags for OS_MCP_STDIO_ENABLED returns
many hits and exit 0, so the pathspec and cwd are sound and a zero would have
meant something. The result confirms triage — packages/mcp/README.md:79,:86-88
scopes the var to HTTP and carries the deprecation,
content/docs/deployment/environment-variables.mdx:257,:264-268 gates it to HTTP
with the deprecation spelled out, and skills/objectstack-ai/SKILL.md:188-190 is
the corrected text that PR #14463 landed. No neighbour still teaches the deprecated
trigger, so nothing rode along with this fix.

Changeset: owed, and measured rather than assumed

A comment-only diff can qualify for skip-changeset, but only if it publishes
nothing. Measured from packages/mcp's own manifest, it publishes:

• files is ["dist", "README.md", "CHANGELOG.md"] — so dist ships;
• root tsup.config.ts sets dts: !process.env.OS_SKIP_DTS, so declaration
  emit is on;
• packages/mcp/src/index.ts:13 exports MCPServerPlugin, so this docblock sits
  on the package entry;
• and declaration emit preserves JSDoc verbatim — measured on an isolated
  fixture through this repo's own toolchain, where a sentinel comment on an
  exported class came through into the emitted index.d.ts unchanged.

So the corrected text reaches consumers as dist/index.d.ts and renders in
editor IntelliSense. That is user-visible, so a changeset is included and
skip-changeset does not apply here.

Could a gate have caught this drift?

Asked deliberately, and not built in this PR. None of the 204 discovered
check families does this today: the nearest neighbours grade docs pages against
source paths or the mechanics of comment masking, none reads a docblock's claims
against the code it documents.

One could, and fairly narrowly, because this repo already gives it an anchor: env
switches have a single decision point per switch in packages/types/src/env.ts,
and the deprecated-alias relationship is structural rather than a wordlist. A
gate could key on the resolver's own shape — the var read in the branch returning
viaDeprecatedAlias: true is the legacy spelling, the var read in the clean
branch is the canonical one — and then require that any JSDoc block naming the
legacy var also names the canonical var in the same block. That is exactly the
condition this docblock violated, it needs no hand-maintained list of variable
pairs, and it would go red the next time a split lands and one comment is missed.

Verification

Gate union derived mechanically at the final HEAD 9544e659bb on a clean tree
via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, not
from a hand-written path list: 33 families (25 by path plus the 8 that only
apply once a changeset exists). Re-run in full at that same commit:

• 30 green, 0 red.
• 3 NOT MEASURED (exit 3, PREREQUISITE NOT MET) — reported as such, never as
  a pass and never as a red: check:dual-build-cjs-loads and
  check-test-completeness both require a whole-repo pnpm build / a real test
  run log, and scripts/pm/check-half-states.mjs needs GitHub API access this
  seat's session gate refuses.

Repo-wide ESLint was run in full rather than narrowed — pnpm lint
(eslint . --no-inline-config), exit 0 in 2m13s over the whole tree.

Declared narrowing:pnpm build and pnpm --filter @objectstack/mcp typecheck were not measured. Three attempts on the shared verification lock
each returned exit 99 (queue-timeout, never acquired, 9 minutes each, about 27
minutes total) behind sibling seats' long-running builds. The derived union for
this card names no build and no test family, and the diff is comments only, so
nothing here is claimed green on that basis — CI runs the farm regardless.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts) — pages documenting those are invisible to this run
• 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 — 12 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 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 → packageMentionDocs.

[os-trump]

Fixes#14473

MCPServerPlugin's own class docblock still taught the pre-split stdio
trigger, about 100 lines above a runtime warning saying the opposite.

Step 2 said the long-lived transport starts "only when autoStart is enabled or
OS_MCP_SERVER_ENABLED is explicitly true", and the Environment Variables
block said explicit true "additionally auto-starts the stdio transport".
Neither named OS_MCP_STDIO_ENABLED anywhere.

Read against the authority — resolveMcpStdioAutoStart() in
packages/types/src/env.ts — that is backwards. The resolver reads
OS_MCP_STDIO_ENABLED first and returns it clean; OS_MCP_SERVER_ENABLED=true
falls through to a legacy branch that returns viaDeprecatedAlias: true, and
start() then warns the operator that this exact trigger is DEPRECATED. So the
docblock presented the deprecated trigger as the design and never named the
canonical one. An author following it got a working transport plus a
deprecation warning at every boot, with no way from this file to learn the
right spelling.

A comment card with a demonstrated downstream

This is not tidiness. The published skills/objectstack-ai MCP section was
written from this docblock and inherited the same error — caught in contract
review and corrected by PR #14463 (5dabfd2a). This file is the upstream of that
defect and was still uncorrected. One catch happened to be in review; the next
may not be.

The change

packages/mcp/src/plugin.ts, comments only, no behaviour change:

• step 2 — starts "only when autoStart is enabled or
  OS_MCP_STDIO_ENABLED is truthy";
• Environment Variables — OS_MCP_SERVER_ENABLED is described as the
  default-on HTTP gate only; OS_MCP_STDIO_ENABLED is added as the stdio
  transport's own switch (default OFF); and the legacy trigger is marked
  deprecated in the runtime warning's own words, copied verbatim from the
  ctx.logger.warn below it rather than paraphrased, so the two cannot drift
  into two phrasings of one rule.

Both blocks now point at the two decision points by name (isMcpServerEnabled,
resolveMcpStdioAutoStart) so the next reader lands on the authority instead of
on prose about it.

The blast radius stayed at one file, re-measured

Triage measured that every neighbour was already updated when the split landed.
I re-ran that independently rather than taking it on trust, with a positive
control first:

git grep -n 'OS_MCP_SERVER_ENABLED' -- ':(glob)packages/**' ':(glob)content/**' \
':(glob)skills/**' ':(glob)apps/**' ':(exclude)*CHANGELOG.md' \
':(exclude)content/docs/releases/**'

Positive control: the same pathspec and flags for OS_MCP_STDIO_ENABLED returns
many hits and exit 0, so the pathspec and cwd are sound and a zero would have
meant something. The result confirms triage — packages/mcp/README.md:79,:86-88
scopes the var to HTTP and carries the deprecation,
content/docs/deployment/environment-variables.mdx:257,:264-268 gates it to HTTP
with the deprecation spelled out, and skills/objectstack-ai/SKILL.md:188-190 is
the corrected text that PR #14463 landed. No neighbour still teaches the deprecated
trigger, so nothing rode along with this fix.

Changeset: owed, and measured rather than assumed

A comment-only diff can qualify for skip-changeset, but only if it publishes
nothing. Measured from packages/mcp's own manifest, it publishes:

• files is ["dist", "README.md", "CHANGELOG.md"] — so dist ships;
• root tsup.config.ts sets dts: !process.env.OS_SKIP_DTS, so declaration
  emit is on;
• packages/mcp/src/index.ts:13 exports MCPServerPlugin, so this docblock sits
  on the package entry;
• and declaration emit preserves JSDoc verbatim — measured on an isolated
  fixture through this repo's own toolchain, where a sentinel comment on an
  exported class came through into the emitted index.d.ts unchanged.

So the corrected text reaches consumers as dist/index.d.ts and renders in
editor IntelliSense. That is user-visible, so a changeset is included and
skip-changeset does not apply here.

Could a gate have caught this drift?

Asked deliberately, and not built in this PR. None of the 204 discovered
check families does this today: the nearest neighbours grade docs pages against
source paths or the mechanics of comment masking, none reads a docblock's claims
against the code it documents.

One could, and fairly narrowly, because this repo already gives it an anchor: env
switches have a single decision point per switch in packages/types/src/env.ts,
and the deprecated-alias relationship is structural rather than a wordlist. A
gate could key on the resolver's own shape — the var read in the branch returning
viaDeprecatedAlias: true is the legacy spelling, the var read in the clean
branch is the canonical one — and then require that any JSDoc block naming the
legacy var also names the canonical var in the same block. That is exactly the
condition this docblock violated, it needs no hand-maintained list of variable
pairs, and it would go red the next time a split lands and one comment is missed.

Verification

Gate union derived mechanically at the final HEAD 9544e659bb on a clean tree
via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, not
from a hand-written path list: 33 families (25 by path plus the 8 that only
apply once a changeset exists). Re-run in full at that same commit:

• 30 green, 0 red.
• 3 NOT MEASURED (exit 3, PREREQUISITE NOT MET) — reported as such, never as
  a pass and never as a red: check:dual-build-cjs-loads and
  check-test-completeness both require a whole-repo pnpm build / a real test
  run log, and scripts/pm/check-half-states.mjs needs GitHub API access this
  seat's session gate refuses.

Repo-wide ESLint was run in full rather than narrowed — pnpm lint
(eslint . --no-inline-config), exit 0 in 2m13s over the whole tree.

Declared narrowing:pnpm build and pnpm --filter @objectstack/mcp typecheck were not measured. Three attempts on the shared verification lock
each returned exit 99 (queue-timeout, never acquired, 9 minutes each, about 27
minutes total) behind sibling seats' long-running builds. The derived union for
this card names no build and no test family, and the diff is comments only, so
nothing here is claimed green on that basis — CI runs the farm regardless.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts) — pages documenting those are invisible to this run
• 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 — 12 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 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 → packageMentionDocs.

[os-trump]

Fixes#14473

MCPServerPlugin's own class docblock still taught the pre-split stdio
trigger, about 100 lines above a runtime warning saying the opposite.

Step 2 said the long-lived transport starts "only when autoStart is enabled or
OS_MCP_SERVER_ENABLED is explicitly true", and the Environment Variables
block said explicit true "additionally auto-starts the stdio transport".
Neither named OS_MCP_STDIO_ENABLED anywhere.

Read against the authority — resolveMcpStdioAutoStart() in
packages/types/src/env.ts — that is backwards. The resolver reads
OS_MCP_STDIO_ENABLED first and returns it clean; OS_MCP_SERVER_ENABLED=true
falls through to a legacy branch that returns viaDeprecatedAlias: true, and
start() then warns the operator that this exact trigger is DEPRECATED. So the
docblock presented the deprecated trigger as the design and never named the
canonical one. An author following it got a working transport plus a
deprecation warning at every boot, with no way from this file to learn the
right spelling.

A comment card with a demonstrated downstream

This is not tidiness. The published skills/objectstack-ai MCP section was
written from this docblock and inherited the same error — caught in contract
review and corrected by PR #14463 (5dabfd2a). This file is the upstream of that
defect and was still uncorrected. One catch happened to be in review; the next
may not be.

The change

packages/mcp/src/plugin.ts, comments only, no behaviour change:

• step 2 — starts "only when autoStart is enabled or
  OS_MCP_STDIO_ENABLED is truthy";
• Environment Variables — OS_MCP_SERVER_ENABLED is described as the
  default-on HTTP gate only; OS_MCP_STDIO_ENABLED is added as the stdio
  transport's own switch (default OFF); and the legacy trigger is marked
  deprecated in the runtime warning's own words, copied verbatim from the
  ctx.logger.warn below it rather than paraphrased, so the two cannot drift
  into two phrasings of one rule.

Both blocks now point at the two decision points by name (isMcpServerEnabled,
resolveMcpStdioAutoStart) so the next reader lands on the authority instead of
on prose about it.

The blast radius stayed at one file, re-measured

Triage measured that every neighbour was already updated when the split landed.
I re-ran that independently rather than taking it on trust, with a positive
control first:

git grep -n 'OS_MCP_SERVER_ENABLED' -- ':(glob)packages/**' ':(glob)content/**' \
':(glob)skills/**' ':(glob)apps/**' ':(exclude)*CHANGELOG.md' \
':(exclude)content/docs/releases/**'

Positive control: the same pathspec and flags for OS_MCP_STDIO_ENABLED returns
many hits and exit 0, so the pathspec and cwd are sound and a zero would have
meant something. The result confirms triage — packages/mcp/README.md:79,:86-88
scopes the var to HTTP and carries the deprecation,
content/docs/deployment/environment-variables.mdx:257,:264-268 gates it to HTTP
with the deprecation spelled out, and skills/objectstack-ai/SKILL.md:188-190 is
the corrected text that PR #14463 landed. No neighbour still teaches the deprecated
trigger, so nothing rode along with this fix.

Changeset: owed, and measured rather than assumed

A comment-only diff can qualify for skip-changeset, but only if it publishes
nothing. Measured from packages/mcp's own manifest, it publishes:

• files is ["dist", "README.md", "CHANGELOG.md"] — so dist ships;
• root tsup.config.ts sets dts: !process.env.OS_SKIP_DTS, so declaration
  emit is on;
• packages/mcp/src/index.ts:13 exports MCPServerPlugin, so this docblock sits
  on the package entry;
• and declaration emit preserves JSDoc verbatim — measured on an isolated
  fixture through this repo's own toolchain, where a sentinel comment on an
  exported class came through into the emitted index.d.ts unchanged.

So the corrected text reaches consumers as dist/index.d.ts and renders in
editor IntelliSense. That is user-visible, so a changeset is included and
skip-changeset does not apply here.

Could a gate have caught this drift?

Asked deliberately, and not built in this PR. None of the 204 discovered
check families does this today: the nearest neighbours grade docs pages against
source paths or the mechanics of comment masking, none reads a docblock's claims
against the code it documents.

One could, and fairly narrowly, because this repo already gives it an anchor: env
switches have a single decision point per switch in packages/types/src/env.ts,
and the deprecated-alias relationship is structural rather than a wordlist. A
gate could key on the resolver's own shape — the var read in the branch returning
viaDeprecatedAlias: true is the legacy spelling, the var read in the clean
branch is the canonical one — and then require that any JSDoc block naming the
legacy var also names the canonical var in the same block. That is exactly the
condition this docblock violated, it needs no hand-maintained list of variable
pairs, and it would go red the next time a split lands and one comment is missed.

Verification

Gate union derived mechanically at the final HEAD 9544e659bb on a clean tree
via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, not
from a hand-written path list: 33 families (25 by path plus the 8 that only
apply once a changeset exists). Re-run in full at that same commit:

• 30 green, 0 red.
• 3 NOT MEASURED (exit 3, PREREQUISITE NOT MET) — reported as such, never as
  a pass and never as a red: check:dual-build-cjs-loads and
  check-test-completeness both require a whole-repo pnpm build / a real test
  run log, and scripts/pm/check-half-states.mjs needs GitHub API access this
  seat's session gate refuses.

Repo-wide ESLint was run in full rather than narrowed — pnpm lint
(eslint . --no-inline-config), exit 0 in 2m13s over the whole tree.

Declared narrowing:pnpm build and pnpm --filter @objectstack/mcp typecheck were not measured. Three attempts on the shared verification lock
each returned exit 99 (queue-timeout, never acquired, 9 minutes each, about 27
minutes total) behind sibling seats' long-running builds. The derived union for
this card names no build and no test family, and the diff is comments only, so
nothing here is claimed green on that basis — CI runs the farm regardless.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts) — pages documenting those are invisible to this run
• 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 — 12 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 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 → packageMentionDocs.

[os-trump]

Fixes#14473

MCPServerPlugin's own class docblock still taught the pre-split stdio
trigger, about 100 lines above a runtime warning saying the opposite.

Step 2 said the long-lived transport starts "only when autoStart is enabled or
OS_MCP_SERVER_ENABLED is explicitly true", and the Environment Variables
block said explicit true "additionally auto-starts the stdio transport".
Neither named OS_MCP_STDIO_ENABLED anywhere.

Read against the authority — resolveMcpStdioAutoStart() in
packages/types/src/env.ts — that is backwards. The resolver reads
OS_MCP_STDIO_ENABLED first and returns it clean; OS_MCP_SERVER_ENABLED=true
falls through to a legacy branch that returns viaDeprecatedAlias: true, and
start() then warns the operator that this exact trigger is DEPRECATED. So the
docblock presented the deprecated trigger as the design and never named the
canonical one. An author following it got a working transport plus a
deprecation warning at every boot, with no way from this file to learn the
right spelling.

A comment card with a demonstrated downstream

This is not tidiness. The published skills/objectstack-ai MCP section was
written from this docblock and inherited the same error — caught in contract
review and corrected by PR #14463 (5dabfd2a). This file is the upstream of that
defect and was still uncorrected. One catch happened to be in review; the next
may not be.

The change

packages/mcp/src/plugin.ts, comments only, no behaviour change:

• step 2 — starts "only when autoStart is enabled or
  OS_MCP_STDIO_ENABLED is truthy";
• Environment Variables — OS_MCP_SERVER_ENABLED is described as the
  default-on HTTP gate only; OS_MCP_STDIO_ENABLED is added as the stdio
  transport's own switch (default OFF); and the legacy trigger is marked
  deprecated in the runtime warning's own words, copied verbatim from the
  ctx.logger.warn below it rather than paraphrased, so the two cannot drift
  into two phrasings of one rule.

Both blocks now point at the two decision points by name (isMcpServerEnabled,
resolveMcpStdioAutoStart) so the next reader lands on the authority instead of
on prose about it.

The blast radius stayed at one file, re-measured

Triage measured that every neighbour was already updated when the split landed.
I re-ran that independently rather than taking it on trust, with a positive
control first:

git grep -n 'OS_MCP_SERVER_ENABLED' -- ':(glob)packages/**' ':(glob)content/**' \
':(glob)skills/**' ':(glob)apps/**' ':(exclude)*CHANGELOG.md' \
':(exclude)content/docs/releases/**'

Positive control: the same pathspec and flags for OS_MCP_STDIO_ENABLED returns
many hits and exit 0, so the pathspec and cwd are sound and a zero would have
meant something. The result confirms triage — packages/mcp/README.md:79,:86-88
scopes the var to HTTP and carries the deprecation,
content/docs/deployment/environment-variables.mdx:257,:264-268 gates it to HTTP
with the deprecation spelled out, and skills/objectstack-ai/SKILL.md:188-190 is
the corrected text that PR #14463 landed. No neighbour still teaches the deprecated
trigger, so nothing rode along with this fix.

Changeset: owed, and measured rather than assumed

A comment-only diff can qualify for skip-changeset, but only if it publishes
nothing. Measured from packages/mcp's own manifest, it publishes:

• files is ["dist", "README.md", "CHANGELOG.md"] — so dist ships;
• root tsup.config.ts sets dts: !process.env.OS_SKIP_DTS, so declaration
  emit is on;
• packages/mcp/src/index.ts:13 exports MCPServerPlugin, so this docblock sits
  on the package entry;
• and declaration emit preserves JSDoc verbatim — measured on an isolated
  fixture through this repo's own toolchain, where a sentinel comment on an
  exported class came through into the emitted index.d.ts unchanged.

So the corrected text reaches consumers as dist/index.d.ts and renders in
editor IntelliSense. That is user-visible, so a changeset is included and
skip-changeset does not apply here.

Could a gate have caught this drift?

Asked deliberately, and not built in this PR. None of the 204 discovered
check families does this today: the nearest neighbours grade docs pages against
source paths or the mechanics of comment masking, none reads a docblock's claims
against the code it documents.

One could, and fairly narrowly, because this repo already gives it an anchor: env
switches have a single decision point per switch in packages/types/src/env.ts,
and the deprecated-alias relationship is structural rather than a wordlist. A
gate could key on the resolver's own shape — the var read in the branch returning
viaDeprecatedAlias: true is the legacy spelling, the var read in the clean
branch is the canonical one — and then require that any JSDoc block naming the
legacy var also names the canonical var in the same block. That is exactly the
condition this docblock violated, it needs no hand-maintained list of variable
pairs, and it would go red the next time a split lands and one comment is missed.

Verification

Gate union derived mechanically at the final HEAD 9544e659bb on a clean tree
via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, not
from a hand-written path list: 33 families (25 by path plus the 8 that only
apply once a changeset exists). Re-run in full at that same commit:

• 30 green, 0 red.
• 3 NOT MEASURED (exit 3, PREREQUISITE NOT MET) — reported as such, never as
  a pass and never as a red: check:dual-build-cjs-loads and
  check-test-completeness both require a whole-repo pnpm build / a real test
  run log, and scripts/pm/check-half-states.mjs needs GitHub API access this
  seat's session gate refuses.

Repo-wide ESLint was run in full rather than narrowed — pnpm lint
(eslint . --no-inline-config), exit 0 in 2m13s over the whole tree.

Declared narrowing:pnpm build and pnpm --filter @objectstack/mcp typecheck were not measured. Three attempts on the shared verification lock
each returned exit 99 (queue-timeout, never acquired, 9 minutes each, about 27
minutes total) behind sibling seats' long-running builds. The derived union for
this card names no build and no test family, and the diff is comments only, so
nothing here is claimed green on that basis — CI runs the farm regardless.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts) — pages documenting those are invisible to this run
• 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 — 12 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 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 → packageMentionDocs.

[os-trump]

Fixes#14473

MCPServerPlugin's own class docblock still taught the pre-split stdio
trigger, about 100 lines above a runtime warning saying the opposite.

Step 2 said the long-lived transport starts "only when autoStart is enabled or
OS_MCP_SERVER_ENABLED is explicitly true", and the Environment Variables
block said explicit true "additionally auto-starts the stdio transport".
Neither named OS_MCP_STDIO_ENABLED anywhere.

Read against the authority — resolveMcpStdioAutoStart() in
packages/types/src/env.ts — that is backwards. The resolver reads
OS_MCP_STDIO_ENABLED first and returns it clean; OS_MCP_SERVER_ENABLED=true
falls through to a legacy branch that returns viaDeprecatedAlias: true, and
start() then warns the operator that this exact trigger is DEPRECATED. So the
docblock presented the deprecated trigger as the design and never named the
canonical one. An author following it got a working transport plus a
deprecation warning at every boot, with no way from this file to learn the
right spelling.

A comment card with a demonstrated downstream

This is not tidiness. The published skills/objectstack-ai MCP section was
written from this docblock and inherited the same error — caught in contract
review and corrected by PR #14463 (5dabfd2a). This file is the upstream of that
defect and was still uncorrected. One catch happened to be in review; the next
may not be.

The change

packages/mcp/src/plugin.ts, comments only, no behaviour change:

• step 2 — starts "only when autoStart is enabled or
  OS_MCP_STDIO_ENABLED is truthy";
• Environment Variables — OS_MCP_SERVER_ENABLED is described as the
  default-on HTTP gate only; OS_MCP_STDIO_ENABLED is added as the stdio
  transport's own switch (default OFF); and the legacy trigger is marked
  deprecated in the runtime warning's own words, copied verbatim from the
  ctx.logger.warn below it rather than paraphrased, so the two cannot drift
  into two phrasings of one rule.

Both blocks now point at the two decision points by name (isMcpServerEnabled,
resolveMcpStdioAutoStart) so the next reader lands on the authority instead of
on prose about it.

The blast radius stayed at one file, re-measured

Triage measured that every neighbour was already updated when the split landed.
I re-ran that independently rather than taking it on trust, with a positive
control first:

git grep -n 'OS_MCP_SERVER_ENABLED' -- ':(glob)packages/**' ':(glob)content/**' \
':(glob)skills/**' ':(glob)apps/**' ':(exclude)*CHANGELOG.md' \
':(exclude)content/docs/releases/**'

Positive control: the same pathspec and flags for OS_MCP_STDIO_ENABLED returns
many hits and exit 0, so the pathspec and cwd are sound and a zero would have
meant something. The result confirms triage — packages/mcp/README.md:79,:86-88
scopes the var to HTTP and carries the deprecation,
content/docs/deployment/environment-variables.mdx:257,:264-268 gates it to HTTP
with the deprecation spelled out, and skills/objectstack-ai/SKILL.md:188-190 is
the corrected text that PR #14463 landed. No neighbour still teaches the deprecated
trigger, so nothing rode along with this fix.

Changeset: owed, and measured rather than assumed

A comment-only diff can qualify for skip-changeset, but only if it publishes
nothing. Measured from packages/mcp's own manifest, it publishes:

• files is ["dist", "README.md", "CHANGELOG.md"] — so dist ships;
• root tsup.config.ts sets dts: !process.env.OS_SKIP_DTS, so declaration
  emit is on;
• packages/mcp/src/index.ts:13 exports MCPServerPlugin, so this docblock sits
  on the package entry;
• and declaration emit preserves JSDoc verbatim — measured on an isolated
  fixture through this repo's own toolchain, where a sentinel comment on an
  exported class came through into the emitted index.d.ts unchanged.

So the corrected text reaches consumers as dist/index.d.ts and renders in
editor IntelliSense. That is user-visible, so a changeset is included and
skip-changeset does not apply here.

Could a gate have caught this drift?

Asked deliberately, and not built in this PR. None of the 204 discovered
check families does this today: the nearest neighbours grade docs pages against
source paths or the mechanics of comment masking, none reads a docblock's claims
against the code it documents.

One could, and fairly narrowly, because this repo already gives it an anchor: env
switches have a single decision point per switch in packages/types/src/env.ts,
and the deprecated-alias relationship is structural rather than a wordlist. A
gate could key on the resolver's own shape — the var read in the branch returning
viaDeprecatedAlias: true is the legacy spelling, the var read in the clean
branch is the canonical one — and then require that any JSDoc block naming the
legacy var also names the canonical var in the same block. That is exactly the
condition this docblock violated, it needs no hand-maintained list of variable
pairs, and it would go red the next time a split lands and one comment is missed.

Verification

Gate union derived mechanically at the final HEAD 9544e659bb on a clean tree
via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, not
from a hand-written path list: 33 families (25 by path plus the 8 that only
apply once a changeset exists). Re-run in full at that same commit:

• 30 green, 0 red.
• 3 NOT MEASURED (exit 3, PREREQUISITE NOT MET) — reported as such, never as
  a pass and never as a red: check:dual-build-cjs-loads and
  check-test-completeness both require a whole-repo pnpm build / a real test
  run log, and scripts/pm/check-half-states.mjs needs GitHub API access this
  seat's session gate refuses.

Repo-wide ESLint was run in full rather than narrowed — pnpm lint
(eslint . --no-inline-config), exit 0 in 2m13s over the whole tree.

Declared narrowing:pnpm build and pnpm --filter @objectstack/mcp typecheck were not measured. Three attempts on the shared verification lock
each returned exit 99 (queue-timeout, never acquired, 9 minutes each, about 27
minutes total) behind sibling seats' long-running builds. The derived union for
this card names no build and no test family, and the diff is comments only, so
nothing here is claimed green on that basis — CI runs the farm regardless.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts) — pages documenting those are invisible to this run
• 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 — 12 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 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 → packageMentionDocs.

[os-trump]

Fixes#14473

MCPServerPlugin's own class docblock still taught the pre-split stdio
trigger, about 100 lines above a runtime warning saying the opposite.

Step 2 said the long-lived transport starts "only when autoStart is enabled or
OS_MCP_SERVER_ENABLED is explicitly true", and the Environment Variables
block said explicit true "additionally auto-starts the stdio transport".
Neither named OS_MCP_STDIO_ENABLED anywhere.

Read against the authority — resolveMcpStdioAutoStart() in
packages/types/src/env.ts — that is backwards. The resolver reads
OS_MCP_STDIO_ENABLED first and returns it clean; OS_MCP_SERVER_ENABLED=true
falls through to a legacy branch that returns viaDeprecatedAlias: true, and
start() then warns the operator that this exact trigger is DEPRECATED. So the
docblock presented the deprecated trigger as the design and never named the
canonical one. An author following it got a working transport plus a
deprecation warning at every boot, with no way from this file to learn the
right spelling.

A comment card with a demonstrated downstream

This is not tidiness. The published skills/objectstack-ai MCP section was
written from this docblock and inherited the same error — caught in contract
review and corrected by PR #14463 (5dabfd2a). This file is the upstream of that
defect and was still uncorrected. One catch happened to be in review; the next
may not be.

The change

packages/mcp/src/plugin.ts, comments only, no behaviour change:

• step 2 — starts "only when autoStart is enabled or
  OS_MCP_STDIO_ENABLED is truthy";
• Environment Variables — OS_MCP_SERVER_ENABLED is described as the
  default-on HTTP gate only; OS_MCP_STDIO_ENABLED is added as the stdio
  transport's own switch (default OFF); and the legacy trigger is marked
  deprecated in the runtime warning's own words, copied verbatim from the
  ctx.logger.warn below it rather than paraphrased, so the two cannot drift
  into two phrasings of one rule.

Both blocks now point at the two decision points by name (isMcpServerEnabled,
resolveMcpStdioAutoStart) so the next reader lands on the authority instead of
on prose about it.

The blast radius stayed at one file, re-measured

Triage measured that every neighbour was already updated when the split landed.
I re-ran that independently rather than taking it on trust, with a positive
control first:

git grep -n 'OS_MCP_SERVER_ENABLED' -- ':(glob)packages/**' ':(glob)content/**' \
':(glob)skills/**' ':(glob)apps/**' ':(exclude)*CHANGELOG.md' \
':(exclude)content/docs/releases/**'

Positive control: the same pathspec and flags for OS_MCP_STDIO_ENABLED returns
many hits and exit 0, so the pathspec and cwd are sound and a zero would have
meant something. The result confirms triage — packages/mcp/README.md:79,:86-88
scopes the var to HTTP and carries the deprecation,
content/docs/deployment/environment-variables.mdx:257,:264-268 gates it to HTTP
with the deprecation spelled out, and skills/objectstack-ai/SKILL.md:188-190 is
the corrected text that PR #14463 landed. No neighbour still teaches the deprecated
trigger, so nothing rode along with this fix.

Changeset: owed, and measured rather than assumed

A comment-only diff can qualify for skip-changeset, but only if it publishes
nothing. Measured from packages/mcp's own manifest, it publishes:

• files is ["dist", "README.md", "CHANGELOG.md"] — so dist ships;
• root tsup.config.ts sets dts: !process.env.OS_SKIP_DTS, so declaration
  emit is on;
• packages/mcp/src/index.ts:13 exports MCPServerPlugin, so this docblock sits
  on the package entry;
• and declaration emit preserves JSDoc verbatim — measured on an isolated
  fixture through this repo's own toolchain, where a sentinel comment on an
  exported class came through into the emitted index.d.ts unchanged.

So the corrected text reaches consumers as dist/index.d.ts and renders in
editor IntelliSense. That is user-visible, so a changeset is included and
skip-changeset does not apply here.

Could a gate have caught this drift?

Asked deliberately, and not built in this PR. None of the 204 discovered
check families does this today: the nearest neighbours grade docs pages against
source paths or the mechanics of comment masking, none reads a docblock's claims
against the code it documents.

One could, and fairly narrowly, because this repo already gives it an anchor: env
switches have a single decision point per switch in packages/types/src/env.ts,
and the deprecated-alias relationship is structural rather than a wordlist. A
gate could key on the resolver's own shape — the var read in the branch returning
viaDeprecatedAlias: true is the legacy spelling, the var read in the clean
branch is the canonical one — and then require that any JSDoc block naming the
legacy var also names the canonical var in the same block. That is exactly the
condition this docblock violated, it needs no hand-maintained list of variable
pairs, and it would go red the next time a split lands and one comment is missed.

Verification

Gate union derived mechanically at the final HEAD 9544e659bb on a clean tree
via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, not
from a hand-written path list: 33 families (25 by path plus the 8 that only
apply once a changeset exists). Re-run in full at that same commit:

• 30 green, 0 red.
• 3 NOT MEASURED (exit 3, PREREQUISITE NOT MET) — reported as such, never as
  a pass and never as a red: check:dual-build-cjs-loads and
  check-test-completeness both require a whole-repo pnpm build / a real test
  run log, and scripts/pm/check-half-states.mjs needs GitHub API access this
  seat's session gate refuses.

Repo-wide ESLint was run in full rather than narrowed — pnpm lint
(eslint . --no-inline-config), exit 0 in 2m13s over the whole tree.

Declared narrowing:pnpm build and pnpm --filter @objectstack/mcp typecheck were not measured. Three attempts on the shared verification lock
each returned exit 99 (queue-timeout, never acquired, 9 minutes each, about 27
minutes total) behind sibling seats' long-running builds. The derived union for
this card names no build and no test family, and the diff is comments only, so
nothing here is claimed green on that basis — CI runs the farm regardless.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts) — pages documenting those are invisible to this run
• 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 — 12 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 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 → packageMentionDocs.

[os-trump]

Fixes#14473

MCPServerPlugin's own class docblock still taught the pre-split stdio
trigger, about 100 lines above a runtime warning saying the opposite.

Step 2 said the long-lived transport starts "only when autoStart is enabled or
OS_MCP_SERVER_ENABLED is explicitly true", and the Environment Variables
block said explicit true "additionally auto-starts the stdio transport".
Neither named OS_MCP_STDIO_ENABLED anywhere.

Read against the authority — resolveMcpStdioAutoStart() in
packages/types/src/env.ts — that is backwards. The resolver reads
OS_MCP_STDIO_ENABLED first and returns it clean; OS_MCP_SERVER_ENABLED=true
falls through to a legacy branch that returns viaDeprecatedAlias: true, and
start() then warns the operator that this exact trigger is DEPRECATED. So the
docblock presented the deprecated trigger as the design and never named the
canonical one. An author following it got a working transport plus a
deprecation warning at every boot, with no way from this file to learn the
right spelling.

A comment card with a demonstrated downstream

This is not tidiness. The published skills/objectstack-ai MCP section was
written from this docblock and inherited the same error — caught in contract
review and corrected by PR #14463 (5dabfd2a). This file is the upstream of that
defect and was still uncorrected. One catch happened to be in review; the next
may not be.

The change

packages/mcp/src/plugin.ts, comments only, no behaviour change:

• step 2 — starts "only when autoStart is enabled or
  OS_MCP_STDIO_ENABLED is truthy";
• Environment Variables — OS_MCP_SERVER_ENABLED is described as the
  default-on HTTP gate only; OS_MCP_STDIO_ENABLED is added as the stdio
  transport's own switch (default OFF); and the legacy trigger is marked
  deprecated in the runtime warning's own words, copied verbatim from the
  ctx.logger.warn below it rather than paraphrased, so the two cannot drift
  into two phrasings of one rule.

Both blocks now point at the two decision points by name (isMcpServerEnabled,
resolveMcpStdioAutoStart) so the next reader lands on the authority instead of
on prose about it.

The blast radius stayed at one file, re-measured

Triage measured that every neighbour was already updated when the split landed.
I re-ran that independently rather than taking it on trust, with a positive
control first:

git grep -n 'OS_MCP_SERVER_ENABLED' -- ':(glob)packages/**' ':(glob)content/**' \
':(glob)skills/**' ':(glob)apps/**' ':(exclude)*CHANGELOG.md' \
':(exclude)content/docs/releases/**'

Positive control: the same pathspec and flags for OS_MCP_STDIO_ENABLED returns
many hits and exit 0, so the pathspec and cwd are sound and a zero would have
meant something. The result confirms triage — packages/mcp/README.md:79,:86-88
scopes the var to HTTP and carries the deprecation,
content/docs/deployment/environment-variables.mdx:257,:264-268 gates it to HTTP
with the deprecation spelled out, and skills/objectstack-ai/SKILL.md:188-190 is
the corrected text that PR #14463 landed. No neighbour still teaches the deprecated
trigger, so nothing rode along with this fix.

Changeset: owed, and measured rather than assumed

A comment-only diff can qualify for skip-changeset, but only if it publishes
nothing. Measured from packages/mcp's own manifest, it publishes:

• files is ["dist", "README.md", "CHANGELOG.md"] — so dist ships;
• root tsup.config.ts sets dts: !process.env.OS_SKIP_DTS, so declaration
  emit is on;
• packages/mcp/src/index.ts:13 exports MCPServerPlugin, so this docblock sits
  on the package entry;
• and declaration emit preserves JSDoc verbatim — measured on an isolated
  fixture through this repo's own toolchain, where a sentinel comment on an
  exported class came through into the emitted index.d.ts unchanged.

So the corrected text reaches consumers as dist/index.d.ts and renders in
editor IntelliSense. That is user-visible, so a changeset is included and
skip-changeset does not apply here.

Could a gate have caught this drift?

Asked deliberately, and not built in this PR. None of the 204 discovered
check families does this today: the nearest neighbours grade docs pages against
source paths or the mechanics of comment masking, none reads a docblock's claims
against the code it documents.

One could, and fairly narrowly, because this repo already gives it an anchor: env
switches have a single decision point per switch in packages/types/src/env.ts,
and the deprecated-alias relationship is structural rather than a wordlist. A
gate could key on the resolver's own shape — the var read in the branch returning
viaDeprecatedAlias: true is the legacy spelling, the var read in the clean
branch is the canonical one — and then require that any JSDoc block naming the
legacy var also names the canonical var in the same block. That is exactly the
condition this docblock violated, it needs no hand-maintained list of variable
pairs, and it would go red the next time a split lands and one comment is missed.

Verification

Gate union derived mechanically at the final HEAD 9544e659bb on a clean tree
via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, not
from a hand-written path list: 33 families (25 by path plus the 8 that only
apply once a changeset exists). Re-run in full at that same commit:

• 30 green, 0 red.
• 3 NOT MEASURED (exit 3, PREREQUISITE NOT MET) — reported as such, never as
  a pass and never as a red: check:dual-build-cjs-loads and
  check-test-completeness both require a whole-repo pnpm build / a real test
  run log, and scripts/pm/check-half-states.mjs needs GitHub API access this
  seat's session gate refuses.

Repo-wide ESLint was run in full rather than narrowed — pnpm lint
(eslint . --no-inline-config), exit 0 in 2m13s over the whole tree.

Declared narrowing:pnpm build and pnpm --filter @objectstack/mcp typecheck were not measured. Three attempts on the shared verification lock
each returned exit 99 (queue-timeout, never acquired, 9 minutes each, about 27
minutes total) behind sibling seats' long-running builds. The derived union for
this card names no build and no test family, and the diff is comments only, so
nothing here is claimed green on that basis — CI runs the farm regardless.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts) — pages documenting those are invisible to this run
• 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 — 12 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 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 → packageMentionDocs.

[os-trump]

Fixes#14473

MCPServerPlugin's own class docblock still taught the pre-split stdio
trigger, about 100 lines above a runtime warning saying the opposite.

Step 2 said the long-lived transport starts "only when autoStart is enabled or
OS_MCP_SERVER_ENABLED is explicitly true", and the Environment Variables
block said explicit true "additionally auto-starts the stdio transport".
Neither named OS_MCP_STDIO_ENABLED anywhere.

Read against the authority — resolveMcpStdioAutoStart() in
packages/types/src/env.ts — that is backwards. The resolver reads
OS_MCP_STDIO_ENABLED first and returns it clean; OS_MCP_SERVER_ENABLED=true
falls through to a legacy branch that returns viaDeprecatedAlias: true, and
start() then warns the operator that this exact trigger is DEPRECATED. So the
docblock presented the deprecated trigger as the design and never named the
canonical one. An author following it got a working transport plus a
deprecation warning at every boot, with no way from this file to learn the
right spelling.

A comment card with a demonstrated downstream

This is not tidiness. The published skills/objectstack-ai MCP section was
written from this docblock and inherited the same error — caught in contract
review and corrected by PR #14463 (5dabfd2a). This file is the upstream of that
defect and was still uncorrected. One catch happened to be in review; the next
may not be.

The change

packages/mcp/src/plugin.ts, comments only, no behaviour change:

• step 2 — starts "only when autoStart is enabled or
  OS_MCP_STDIO_ENABLED is truthy";
• Environment Variables — OS_MCP_SERVER_ENABLED is described as the
  default-on HTTP gate only; OS_MCP_STDIO_ENABLED is added as the stdio
  transport's own switch (default OFF); and the legacy trigger is marked
  deprecated in the runtime warning's own words, copied verbatim from the
  ctx.logger.warn below it rather than paraphrased, so the two cannot drift
  into two phrasings of one rule.

Both blocks now point at the two decision points by name (isMcpServerEnabled,
resolveMcpStdioAutoStart) so the next reader lands on the authority instead of
on prose about it.

The blast radius stayed at one file, re-measured

Triage measured that every neighbour was already updated when the split landed.
I re-ran that independently rather than taking it on trust, with a positive
control first:

git grep -n 'OS_MCP_SERVER_ENABLED' -- ':(glob)packages/**' ':(glob)content/**' \
':(glob)skills/**' ':(glob)apps/**' ':(exclude)*CHANGELOG.md' \
':(exclude)content/docs/releases/**'

Positive control: the same pathspec and flags for OS_MCP_STDIO_ENABLED returns
many hits and exit 0, so the pathspec and cwd are sound and a zero would have
meant something. The result confirms triage — packages/mcp/README.md:79,:86-88
scopes the var to HTTP and carries the deprecation,
content/docs/deployment/environment-variables.mdx:257,:264-268 gates it to HTTP
with the deprecation spelled out, and skills/objectstack-ai/SKILL.md:188-190 is
the corrected text that PR #14463 landed. No neighbour still teaches the deprecated
trigger, so nothing rode along with this fix.

Changeset: owed, and measured rather than assumed

A comment-only diff can qualify for skip-changeset, but only if it publishes
nothing. Measured from packages/mcp's own manifest, it publishes:

• files is ["dist", "README.md", "CHANGELOG.md"] — so dist ships;
• root tsup.config.ts sets dts: !process.env.OS_SKIP_DTS, so declaration
  emit is on;
• packages/mcp/src/index.ts:13 exports MCPServerPlugin, so this docblock sits
  on the package entry;
• and declaration emit preserves JSDoc verbatim — measured on an isolated
  fixture through this repo's own toolchain, where a sentinel comment on an
  exported class came through into the emitted index.d.ts unchanged.

So the corrected text reaches consumers as dist/index.d.ts and renders in
editor IntelliSense. That is user-visible, so a changeset is included and
skip-changeset does not apply here.

Could a gate have caught this drift?

Asked deliberately, and not built in this PR. None of the 204 discovered
check families does this today: the nearest neighbours grade docs pages against
source paths or the mechanics of comment masking, none reads a docblock's claims
against the code it documents.

One could, and fairly narrowly, because this repo already gives it an anchor: env
switches have a single decision point per switch in packages/types/src/env.ts,
and the deprecated-alias relationship is structural rather than a wordlist. A
gate could key on the resolver's own shape — the var read in the branch returning
viaDeprecatedAlias: true is the legacy spelling, the var read in the clean
branch is the canonical one — and then require that any JSDoc block naming the
legacy var also names the canonical var in the same block. That is exactly the
condition this docblock violated, it needs no hand-maintained list of variable
pairs, and it would go red the next time a split lands and one comment is missed.

Verification

Gate union derived mechanically at the final HEAD 9544e659bb on a clean tree
via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, not
from a hand-written path list: 33 families (25 by path plus the 8 that only
apply once a changeset exists). Re-run in full at that same commit:

• 30 green, 0 red.
• 3 NOT MEASURED (exit 3, PREREQUISITE NOT MET) — reported as such, never as
  a pass and never as a red: check:dual-build-cjs-loads and
  check-test-completeness both require a whole-repo pnpm build / a real test
  run log, and scripts/pm/check-half-states.mjs needs GitHub API access this
  seat's session gate refuses.

Repo-wide ESLint was run in full rather than narrowed — pnpm lint
(eslint . --no-inline-config), exit 0 in 2m13s over the whole tree.

Declared narrowing:pnpm build and pnpm --filter @objectstack/mcp typecheck were not measured. Three attempts on the shared verification lock
each returned exit 99 (queue-timeout, never acquired, 9 minutes each, about 27
minutes total) behind sibling seats' long-running builds. The derived union for
this card names no build and no test family, and the diff is comments only, so
nothing here is claimed green on that basis — CI runs the farm regardless.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/mcp/src/plugin.ts) — pages documenting those are invisible to this run
• 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 — 12 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 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 → packageMentionDocs.