docs(guide): objectstack.config.ts belongs to the server project — link it, do not re-type it (#5160)

[os-support-ai]

Fixes#5160

The last of the 15 non-exported-symbol imports measured across this repo's published pages. The other 14 landed in #5260; this is the AppManifest block at content/docs/guide/objectos-integration.mdx:80.

The measurement that selected the branch

The maintainer ruling of 2026-08-19 is Option C — delete the block and link to the framework repo's own objectstack.config.ts documentation, with a pre-ruled fallback to Option A (rewrite to defineStack) if the framework repo has no such page. So the branch turns on one cross-repo reading:

Searched objectstack-ai/objectstack at origin/main (43cd348a2), over content/docs/** — 429 files — by filename and by content:

probe	result
filenames matching config	7 files, none of them the authoring page (config-resolution, *-node-config, auth/email/registry-config)
content objectstack\.config	34 files, 60+ hits
content defineStack (counter-probe, known present)	58 files
content ObjectStackDefinitionSchema (counter-probe, known present)	6 files
content zzqqxxnotapage (negative control)	0 files

Not a zero, and the apparatus discriminates: a term known present returns 58 of 429, a nonsense term returns 0. The framework repo does document this file, so Option C it is; Option A was not taken.

Three pages carry it, and all three are linked from the rewritten section:

• content/docs/getting-started/your-first-project.mdx — the generated objectstack.config.ts walked through key by key, in a fence titled with that exact filename
• content/docs/deployment/cli.mdx — discovery order, validation against ObjectStackDefinitionSchema, compilation to dist/objectstack.json
• content/docs/api/data-flow.mdx — how defineStack() becomes a running application

URL construction, stated because I could not fetch it: every probe of objectstack.ai / docs.objectstack.ai returned 000 through this container's proxy, which is a proxy reading and not a site reading. The URLs are therefore built from the framework repo's own convention rather than from a fetch: its README.md links https://objectstack.ai/docs/getting-started/build-with-claude-code and https://objectstack.ai/docs/deployment/self-hosting, and both of those map onto files that exist at the same path under content/docs/ with an .mdx extension. https://objectstack.ai/docs is the dominant form in that repo (61 occurrences). Each of the three files linked here was confirmed present at origin/main.

Why the block is gone rather than re-typed

Option B — correcting only the import path to @objectstack/spec/system — stays rejected, and the diff does not drift toward it. The name is real there, but AppManifestSchema is {name, label, version, description?, objects: string[], views: string[], flows: string[], dependencies: string[]} while the literal beneath the annotation has no label and its objects is a map of full object definitions. A path-only fix trades TS2305 for a fresh TS2739/TS2322 on the same lines: the page keeps teaching something that does not compile while the ledger reads as improved.

The section keeps its heading and its place in the numbered walkthrough — content/docs/guide/console.md:72 and console-architecture.md:75 both point readers here for the server-side shape, and they still land on an answer. It now says the file belongs to the ObjectStack server project, that it is authored with defineStack() and compiled by the os CLI, and where the authoritative reference lives.

The ledger, in the same PR

Re-measured after the edit and restated. Nothing added, nothing widened, no entry deleted.

	before	after
ts/tsx blocks compiled	22	21
parse	36	36
undefined-name	10	10
unresolved-module	7	7
TS2305	1 (:80, AppManifest)	0
TS2339	1	1

The page does not reach zero, so the entry stays — it is the mix that changed. The mechanical half of the new reason string is generated, not hand-counted: the generator was first validated by reproducing the current entry byte-for-byte from the pre-edit tree, then re-run against the tree as committed, where the committed entry is a prefix match on the freshly measured mix plus triage prose.

Verification — all at 57aef7f3e, working tree clean

Whether a build artifact sits between each edit and the thing under test, per leg:

• doc edit to measurement — no artifact between them. The gate reads the .mdx from the working tree at run time. Artifacts do sit under the packages the snippets are judged against, so those were built first: pnpm exec turbo run build $(node scripts/check-doc-snippet-types.mjs --build-filter) -> Tasks: 20 successful, plus four measurement-only packages (components, fields, plugin-form, plugin-kanban) that un-gating this page for measurement pulls in -> 14 successful.
• ledger edit to gate — no artifact between them either. check-doc-snippet-types.mjs runs from source as an .mjs script.
• reverse-verification of the ledger edit — mutated the committed entry to a one-character reason: gate goes exit 1 with content/docs/guide/objectos-integration.mdx [unexplained-ungated-entry] an entry with no written reason is not a declaration. Restored with git checkout of the branch path for scripts/check-doc-snippet-types.mjs (never git stash); gate returns to exit 0 and git status is clean. Predicted direction was red-on-mutation and that is what happened.

Runs:

• node scripts/check-doc-snippet-types.mjs -> exit 0. Semantic phase: 68 of 68 block(s) judged, 0 failed. All three controls proven in the same run: resolution landed on packages/types/dist/index.d.ts, sentinel produced TS2305, positive produced 0.
• pnpm exec vitest run scripts/__tests__/check-doc-snippet-types.test.ts from the repo root -> Test Files 1 passed (1), Tests 20 passed (20). Running the script is not running its test; both were run.
• --build-filter output is byte-identical before and after (diff clean). Expected: the page stays ungated, and the deleted block imported @objectstack/spec, an external package that never entered the filter. Gate CI cost does not move.
• node scripts/check-doc-links.mjs -> Links are valid across 13 scan roots.
• pnpm turbo run build --filter='@object-ui/site' -> Tasks: 29 successful, 29 total (the diff touches content/, so Build Docs will run in CI).
• node scripts/check-control-bytes.mjs -> OK, 4721 tracked text files; plus a direct grep -naP over the two changed files -> clean.
• pnpm type-check:scripts -> exit 0. pnpm lint:root -> 0 errors, 24 pre-existing warnings, none in either changed file.
• node scripts/check-changeset-presence.mjs -> No source of a released package changed in this range, so no changeset is owed. Followed the verdict rather than assuming; no changeset added.

Heavy runs were serialized on the shared /tmp/os-heavy-verify.lock. CI convergence is not awaited here, per the 2026-08-10 ruling.

---

Generated by Claude Code

[os-support-ai]

ACCEPT — PM review, round 17. This closes #5160: the 15th and last name.

• Path surface (git diff --name-only origin/main... @ 57aef7f): 2 files — content/docs/guide/objectos-integration.mdx, scripts/check-doc-snippet-types.mjs. Zero governed-surface hits. No changeset owed and none added — check-changeset-presence.mjs was run and its verdict followed rather than guessed.
• Gates: every gate job completed: success — Lint, Type Check, Test shards 1–4, Build & E2E, Build Docs, Doc Snippet / Doc Component Type Check, Changeset Declaration / Fixed Group, Control Byte Scan, Internal Docs Link Check, Skill Guide Path Check. No cancelled, no in_progress.

The branch selection was measured, not assumed — which is the whole card

The ruling was C, with A as a pre-ruled fallback if the framework repo has no page to link. The measurement came back non-zero, so C it is: 34 files / 60+ hits for objectstack\.config across content/docs/** in objectstack-ai/objectstack. Counter-probes on the same corpus in the same run — defineStack 58 files, ObjectStackDefinitionSchema 6 files, and a nonsense control zzqqxxnotapage at 0 — so the apparatus discriminates and the non-zero is a reading, not an artefact.

I verified the three link targets independently before accepting, because a dead link in published docs is the one way C goes wrong quietly. All three exist on objectstack main: content/docs/getting-started/your-first-project.mdx, content/docs/deployment/cli.mdx, content/docs/api/data-flow.mdx. And the URL form is confirmed by the framework repo's own README against files that exist — deployment/self-hosting, ai/connect-mcp, getting-started/build-with-claude-code all map to content/docs/<path>.mdx. The report's caveat that every live probe of the host returned 000through this container's proxy is stated correctly as a proxy reading rather than a site reading; the derivation stands on the repo, which is the right place to stand it.

Option B never entered the diff — correct. Fixing only the import path would have traded TS2305 for a fresh TS2739/TS2322 on the same lines while the ledger read as improved.

The ledger is restated, not shrunk

TS2305x1 is gone from the mix because it is genuinely zero; TS2339x1 and the 36 parse / 10 undefined-name / 7 unresolved-module counts stay, and the entry now records why the block went and what covering the page would still take. Entry not deleted, not widened, none added — the page does not reach zero and the entry says so. That is what an honest ledger looks like.

Two things worth keeping from the verification: the reason-string generator was validated by reproducing the current entry byte-for-byte from the pre-edit tree before being trusted to write the new one; and the ledger edit was reverse-verified by mutating the committed entry to a one-character reason and watching the gate fail with [unexplained-ungated-entry] an entry with no written reason is not a declaration. Predicted direction, observed direction, matched. --build-filter output byte-identical, so gate CI cost does not move.

Merging via the queue.

---

Generated by Claude Code