create-objectstack: converge scaffold docs on canonical host, drop last dead monorepo refs

[os-elon]

Fixes#10990
Fixes#11022

Premise check

Both cards' claimed line numbers and file states were re-measured against origin/main before editing, and both held:

• create-objectstack templates: AGENTS.md links objectstack.com, Dockerfile/docker-compose.yml still use the docs.objectstack.ai alias #10990 — all three lines present exactly as described: templates/AGENTS.md:99 (objectstack.com), templates/blank/Dockerfile:10 and templates/blank/docker-compose.yml:7 (docs.objectstack.ai). CANONICAL_DOCS_ORIGIN = 'https://objectstack.ai' confirmed at scripts/check-published-readme-links.mjs:259.
• create-objectstack: the blank template's README still cites ADR-0097 and "the ObjectStack framework repo" — the last two dead references in a scaffolded project #11022 — both lines present, shifted five lines from the card's stale numbers (:77→:82, :134→:139), text matching verbatim.
• The "no gate covers create-objectstack templates: AGENTS.md links objectstack.com, Dockerfile/docker-compose.yml still use the docs.objectstack.ai alias #10990" claim, independently re-verified: check:published-readme-links's population (publishedDocs()) walks each publishable package's files array. create-objectstack's files is ["dist", "README.md", "CHANGELOG.md"] — templates/AGENTS.md lives under src/, never published as a top-level README. tsup.config.tsdoes copy src/templates → dist/templates on build, so in principle a built dist/templates/AGENTS.md would match the dist glob — but lint.yml's lint job (which runs this gate) never builds create-objectstack before running it, so dist/ doesn't exist there and the population is unaffected. Confirmed by running the gate on this tree: 60 published markdown file(s) — matches its own documented census, create-objectstack absent. Dockerfile/docker-compose.yml aren't markdown regardless.
• README.md:102's See `AGENTS.md` for the full convention — re-verified, not a defect.packages/create-objectstack/src/index.ts really does writeIfAbsent(path.join(targetDir, 'AGENTS.md'), rendered), and the scaffolded project sweep below shows it landing.

No premise held wrong; nothing here needed a route change from the brief.

The fix

#10990 — converged all three lines on the ruled canonical origin (maintainer, 2026-08-21): https://objectstack.ai/docs, https://objectstack.ai/docs/deployment/self-hosting ×2. Each rewritten URL verified to resolve against content/docs before committing (content/docs/index.mdx, content/docs/deployment/self-hosting.mdx both exist).

#11022 — templates/blank/README.md, both lines rewritten self-contained per the #10324 style (state the fact, link a public page instead of an internal identifier):

• :82 — dropped (ADR-0097), added a link to https://objectstack.ai/docs/automation/connectors (verified: covers connector materialization directly, and resolves via content/docs/automation/connectors.mdx).
• :139 — dropped "in the ObjectStack framework repo" (unfollowable — a reader with only their own project has no path to it), replaced with the followable install form the scaffolder's own closing output already uses: `npx skills add objectstack-ai/objectstack/skills` (see `AGENTS.md`). AGENTS.md is already established (line :102 above) as a file that really ships into the project, and it already documents this exact install command in full.

Neither edit deletes the rationale each comment was carrying — both facts survive, reworded, with a resolvable pointer replacing the internal identifier.

Pin design

packages/create-objectstack/src/starter-comments-self-contained.test.ts (#10324) gets three changes:

1. EXCLUDED entry for blank/README.md deleted. The retirement fired as designed: the file no longer cites anything MONOREPO_ONLY, so it's scanned like every other shipped file (assertion 1) rather than staying silently exempt.

2. A fifth MONOREPO_ONLY pattern — /\bObjectStack (?:framework )?(?:mono)?repo\b/i — closes the hole flagged at claim time: the original four patterns are all syntactic identifiers (ADR id, issue number, script path, package path), and :139's "the ObjectStack framework repo" is the same defect class in prose form — nothing in the original four could have matched it. Deliberately scoped to the framework's own name next to a "repo" word, not the literal sentence, so a reword still gets caught; deliberately not a bare repo/monorepo match, because this same template tree correctly calls the reader's own scaffolded project "a monorepo root" (blank/pnpm-workspace.yaml) — a true, self-contained, followable statement about a directory they do have. Verified against the whole shipped tree: exactly one hit, the line being fixed, both before and after — no false positives anywhere else in the 12 shipped files.

3. A new assertion 4 — host convergence, driven by the same shippedFiles() walker that already enumerates everything a scaffold ships. This is the pin create-objectstack templates: AGENTS.md links objectstack.com, Dockerfile/docker-compose.yml still use the docs.objectstack.ai alias #10990 had none of: check:published-readme-links prescribes the same canonical origin but its population (publishable packages' published markdown) never reaches these template files (see premise-check section above). The host list is restated, not imported, from check-published-readme-links.mjs's DOCS_HOSTS/CANONICAL_DOCS_ORIGIN — the same cross-package-read-radius reason assertion 3's candidate list already gives for restating rather than importing. Swept the whole shipped tree for every host in that list before adding the assertion: zero occurrences outside the three lines this PR fixes.

Reverse-verification (committed fix first, then reverted on top, restored via git checkout HEAD --)

• Restored all three pre-fixcreate-objectstack templates: AGENTS.md links objectstack.com, Dockerfile/docker-compose.yml still use the docs.objectstack.ai alias #10990 lines (objectstack.com / docs.objectstack.ai ×2) → assertion 4 fails on exactly those 3 files, each error naming the exact offending host string (e.g. blank/Dockerfile cites "https://docs.objectstack.ai"). 31/34 tests still pass. Restored, green again (34/34).
• Restored the pre-fix :82 (ADR-0097) and:139 (framework repo) together → assertion 1 fails on blank/README.md, first hit reported is the ADR pattern (loop order), confirming the existing pattern still catches its half.
• Restored only:139 (kept :82 fixed) → isolates the fifth pattern: assertion 1 fails on blank/README.md with cites a reference to the ObjectStack repo as an unlinked location ("ObjectStack framework repo") — proves the new pattern is what would have caught the hole the claim-time review flagged, not a coincidence of pattern-loop ordering. Restored, green again (34/34).

PM review addendum — assertion 2 coverage for blank/README.md

PM review flagged a real gap: assertion 2 (RATIONALE, "the rationale survives") listed only
#10324's two original files, so this PR's own two blank/README.md rewrites were unguarded —
deleting the "materializes ... at boot" clause or the npx skills add objectstack-ai/objectstack/skills install command would leave assertions 1/3/4 all green (no
ADR id to find, no non-canonical host, every present URL still resolves) while the fact
disappeared. Exactly the failure mode the file's own header describes: "a one-way grep stays
green while the explanation is deleted."

Added a blank/README.md entry to RATIONALE with one fact per rewritten line:

• :82 — that a provider-bound connector is materialized into a live, dispatchable connector
  at boot (not written by hand): /materializ\w*[^.]*?\bat\s+boot\b/i (the [^.]*? spans
  the line wrap between "at" and "boot" in the source).
• :139 — the followable skills install command itself:
  /npx skills add objectstack-ai\/objectstack\/skills/i.

Reverse-verification of both new legs (same method: commit fix, mutate on top, restore via git checkout HEAD --)

• Deleted the "at boot" materialization clause from :82's paragraph (kept it grammatical,
  reintroduced nothing unfollowable) → exactly 1 test fails, by name:
  blank/README.md > still explains that a provider-bound connector is materialized into a live, dispatchable connector at boot (not written by hand). 35/36 other tests — including
  assertions 1, 3, 4 and the other new leg — stayed green, confirming the exposure PM described
  was real before this fix. Restored, green again (36/36).
• Deleted the npx skills add objectstack-ai/objectstack/skills install command from :139
  (replaced with "the skills CLI", still true, still no unfollowable reference) →
  exactly 1 test fails, by name: blank/README.md > still explains the followable skills install command. Same 35/36-green pattern. Restored, green again (36/36).

Full suite at the new HEAD (cf9a767b36): pnpm --filter create-objectstack test — Test Files 13 passed (13) / Tests 160 passed (160) (158 → 160: the two new RATIONALE legs).
pnpm --filter create-objectstack typecheck — clean. Re-ran the convention-triggered ratchets
this test-file edit implicates (check:query-options-erasure, check:type-check-coverage,
check:engine-double-contract, check:where-matcher — all green, baselines unchanged) and
check:type-check-debt --re-measure after rebuilding the full workspace closure again
(turbo build, 70/70 tasks) — identical verdict to the first measurement: OK — 33 ledger entr(ies) re-measured ..., 1896 raw tsc error(s) total, none above its recorded number.
check:nul-bytes and a manual control-byte scan of the diff stayed clean.

CI-red fix — check:cross-package-test-inputs (PM review, second pass)

Lint & Repo Gates came back red on check:cross-package-test-inputs: its flat literal
collector (repoRelativeLiterals) matches ANY backtick/quote-wrapped repo-relative path
anywhere in a file's TEXT — prose included, no parsing — and my RATIONALE addendum commit's
prose named the published-readme-links gate's script path in backticks three times while
explaining why assertion 4 could not live there. The test does not actually read that file (the
host list is restated, not imported), so the flag was spurious — a real dependency was never
created.

Per PM's instruction, did not widen the package's declared globs — that would declare a
false dependency and invalidate the turbo cache on every unrelated scripts/ change for a read
that does not exist. Reworded all three sites to name the gate ("the published-readme-links
gate") without spelling or quoting its path — the same convention this file's own pre-existing
assertion-3 comment already uses for check-docs-redirects.mjs ("check-docs-redirects'
pageCandidates", no backticks, no scripts/ prefix), and the same trade this package's OWN
entry in check-cross-package-test-inputs.mjs's ledger documents for a prior, structurally
identical case (sync-template-versions.mjs, while it was still only a mention: "rewording ...
into unquoted prose unforced a live radius").

Verified: pnpm check:cross-package-test-inputs now prints OK: 13 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob (was previously failing
with create-objectstack names path(s) no declared glob covers). Also ran every other step
still queued behind the failing one in lint.yml's lint job (it aborts at first failure, so
CI's report could not have surfaced a second failure past this one) — all ~20 remaining check:*
steps green: check:live-db-isolation, check-ci-filter-parity (self-test + real),
partition-test-shards --self-test, check-declaration-mirrors (self-test + real),
check:examples-live-imports, check:test-source-alias, check:refd-timer-probe,
check:type-source-resolution, check:published-files, check:engine-double-contract,
check:where-matcher, check:kernel-hook-pairs, check:plugin-teardown-shape,
check:resume-authority-declared, check:driver-memory-census, check:merge-driver,
check:spec-parsed-alias, check:tenant-chokepoint, check:pnpm-filter-targets. Also re-ran
check:nul-bytes, check:published-readme-links (both unaffected, still green) and ESLint
scoped to the changed file (clean, exit 0 — full-repo pnpm lint was not re-run locally; nothing
in this diff is JS/TS logic, only comments). Full package suite reconfirmed at the new HEAD
(f50d8b0eff): 160/160 tests, typecheck clean.

Gap confirmed and filed: dispatch-gates.mjs never named check:cross-package-test-inputs
for this diff at all — not matched, not convention-triggered, not unreachable — because the
gate's trigger (a test file's content gaining a new escaping read or a new quoted mention) is
identical in kind to the five gates already in the 'adds or edits a test file' convention list
(check:query-options-erasure etc.), but it isn't itself in that list. Filed unassigned as
#11199 with the root cause and a suggested one-line fix (add it as a sixth entry in that
same convention-trigger kind); not fixed here because widening dispatch-gates.mjs is unrelated
to this PR's own scope.

Gate verdicts (all at d4bfa10cd4, first HEAD — see the two addenda above for the cf9a767b36 / f50d8b0eff re-runs)

Package-scoped:

• pnpm --filter create-objectstack build — clean (tsup + dts, exit 0)
• pnpm --filter create-objectstack test — Test Files 13 passed (13) / Tests 158 passed (158)
• pnpm --filter create-objectstack typecheck — clean, no output (exit 0)

node scripts/pm/dispatch-gates.mjs (no paths — merge-base derived, 6 paths incl. the changeset) named these local gates, all run and green:

• pnpm check:changeset-gate-self-tests — ✓ (self-tests) + real-diff run: ✓ No empty-frontmatter changeset introduced / ✓ adds no declared-breaking changeset / ✓ introduces no major bump
• pnpm check:objectui-changeset — ✓ self-test all checks passed
• pnpm check:slot-lookup — ✓ ratchet holds, no new sites, baseline unchanged
• pnpm check:template-version-sync — ✓ self-test 40 assertions (real check lives in template-version-stamps.test.ts, covered by the package test run above)
• pnpm check:test-source-alias — ✓ OK, 72 packages scanned
• pnpm check:type-source-resolution — ✓ OK, 77 packages scanned
• node scripts/check-ci-filter-parity.mjs — OK: all 86 declared cross-package glob(s) ... covered
• node scripts/check-plugin-teardown-shape.mjs — ✓ 63 plugins, 0 known-unreached
• node scripts/docs-audit/check-affected-docs.mjs — ✓ self-test 339 cases pass, exit 0

Convention-triggered (test file added/edited):

• pnpm check:query-options-erasure — ✓ ratchet holds, baseline key set verified against 2f93d0f53 (merge base): no files added
• pnpm check:type-check-coverage — ✓ OK, 65/78 packages type-checked, unchanged from baseline
• pnpm check:type-check-debt --re-measure — built the full workspace closure first (pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*', 70/70 tasks, exit 0). An unbuilt-closure attempt was made first and correctly refused with --re-measure cannot run: 55 workspace dependenc(ies) ... have no built type entry point on disk (NOT MEASURED, not "not applicable"). After the build: check-type-check-coverage --re-measure: OK — 33 ledger entr(ies) re-measured in 207.7s, 1896 raw tsc error(s) total, none above its recorded number. (create-objectstack carries no DEBT/TEST_DEBT ledger entry at all, consistent with its own clean typecheck run above.) Informational-only notes on 4 pre-existing, unrelated ledger entries with room to lower (plugin-approvals, runtime, plugin-auth, trigger-record-change) are untouched — out of this PR's scope, no regression.
• pnpm check:engine-double-contract — ✓ OK, 384 pinned / 133 DEBT / 2 exempt (unrelated to this diff — no fake-engine doubles touched)
• pnpm check:where-matcher — ✓ 281 matchers, 0 silently-wrong, baseline unchanged

Byte discipline: node scripts/check-nul-bytes.mjs clean; manual grep -naP control-byte scan of the diff clean.

CI e2e local-equivalent

packages/create-objectstack/** path-triggers Scaffold E2E's Scaffold with repo dist job. Ran its local-equivalent by hand (network/docker unavailable in this container, so the install/build/boot/docker legs are out of reach here — CI covers those): built the CLI from dist, scaffolded a real project (node bin/create-objectstack.js e2e-check-app --skip-install --skip-skills), then swept the generated project, not the template source. Every fixed line lands correctly in the output: canonical-host URLs in AGENTS.md/Dockerfile/docker-compose.yml, the rewritten connectors and skills lines in README.md; zero remaining objectstack.com / docs.objectstack.ai / ADR- / "framework repo" occurrences anywhere in the scaffolded tree. This is the same method #11022's card used to measure the original defect.

Out of scope

Nothing found beyond the two cards' stated surface, except the dispatch-gates.mjs gap above (filed as #11199 — a tooling finding about this repo's PM dispatch machinery, unrelated to what #10990/#11022 ask for).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 2 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 4 changed file(s) yielded no anchor (packages/create-objectstack/src/templates/AGENTS.md, packages/create-objectstack/src/templates/blank/Dockerfile, packages/create-objectstack/src/templates/blank/README.md, …) — pages documenting those are invisible to this run

Coarse fallback — 8 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 52a41b72ee01bc24bdd6ac8eb1a37485eb2b4946 → packageMentionDocs.