fix(cli): Console-dist warning names the remedy for where it runs; README states the Console step and command costs

[objectstack-fleet]

Fixes #22155
Fixes #22164
Clause-②: no

One PR for the two-card bundle that edits the same README section. #22156 is serial after this PR and is not addressed here: its README items (the first curl, the pnpm floors) and CONTRIBUTING.md are untouched.

What changes

README, "Hack on the framework"

This covers #22164 and the README half of #22155.

• The command block gains pnpm objectui:build as the Console step, between pnpm build and pnpm dev.

• A paragraph under the block says what the step does:

  • it builds objectui at the commit pinned in .objectui-sha into the gitignored packages/console/dist;
  • it builds from a ../objectui checkout when one exists, otherwise from a shallow clone into .cache/;
  • it installs objectui's dependencies either way, so it needs network;
  • without it, pnpm dev still serves the REST API, but no Console;
  • rerun it when .objectui-sha moves.
    This matches content/docs/getting-started/examples.mdx and scripts/build-console.sh, both read on origin/main c6fe02d7ac.

• A table gives each command's measured cost, quoted as the cards measured it on a fresh clone (4-vCPU container, Node 22.22, pnpm 10.31):

  Command	Time
  pnpm install	16 s
  pnpm build	6 m 54 s (72 turbo tasks)
  pnpm objectui:build	10 m 36 s
  pnpm test	54 m 03 s (135 turbo tasks)

  These were not re-measured here.

• For a contributor's own change, the section now points to pnpm turbo run test --affected and pnpm --filter @objectstack/PKG test. A note says that --affected compares the branch with the local main.

• The pnpm install line's text is unchanged; only its comment column moved.

CLI boot warning

This is the warning half of #22155, cross-lane to domain:cli as declared on the claim.

packages/cli/src/commands/serve.ts used to print the same remedy wherever it ran: install @object-ui/console (already built) or run pnpm --filter @object-ui/console build in the objectui workspace. It now calls formatConsoleDistMissingWarning(consolePath), which is new in packages/cli/src/utils/console.ts beside the drift formatters. The function picks the remedy from one signal: whether the nearest package.json above the resolved console package declares an objectui:build script.

• Framework repo (the root manifest declares the script). The warning reads Console dist not found at packages/console/dist, says pnpm build does not produce it, and says to build it with pnpm objectui:build in the root directory, which it names. The directory matters because pnpm dev runs in examples/app-showcase, where the root script does not resolve.
• Anywhere else. The warning gives the dist path and says the Console ships prebuilt in @objectstack/console, a dependency of @objectstack/cli, to reinstall at the CLI's version. A scaffolded project depends on @objectstack/cli (packages/create-objectstack/src/templates/blank/package.json), and the CLI depends on @objectstack/console (packages/cli/package.json). The resolver reads @objectstack/console only. An installed @object-ui/console is never consulted.

Why this signal (Zone 2, item 3):

• The script's presence is exactly the claim the message makes, so the command is named only where it exists.
• The .objectui-sha pin that the drift guard keys on would also match another repository that carries a pin without the script.
• A layout check such as packages/console or scripts/build-console.sh couples the CLI to this repo's file tree.
• The walk stops at the nearest manifest. A project created inside a framework checkout therefore gets the install remedy for the console it actually resolved. The pnpm store layout's intermediate directories carry no manifest, so the walk reaches the project's own.

Only the text changes; mount and refuse decisions are untouched. There is a patch changeset for @objectstack/cli.

The new export is internal. test/published-subpath-console.pin.test.ts partitions every export of utils/console.ts into public and not-public lists, and it went red until the name was recorded there as INTERNAL_SINCE_RETIREMENT. The two "exactly three names" checks still hold it off the published ./console subpath. The helper's build-root walk is not exported.

Not done here

• The bare-404 HTTP half of [finding] README's pnpm install && pnpm build && pnpm dev serves no Console on a fresh clone: /_console/ and / answer 404, and the boot warning names a remedy that does not exist in this repo #22155, which belongs to domain:cli. GET /_console/ on a composition with no Console still answers 404; this boot measured it at 404.

Verification

All runs below were on 0ef75bd7d9 unless noted.

• Unit test, both branches with controls (packages/cli/test/console-resolve.test.ts, four new cases):

  • framework layout: names pnpm objectui:build and the root;
  • control: the same layout without the script gets the install remedy;
  • installed CLI, hoisted and pnpm-store layouts: names @objectstack/console;
  • a project inside a framework checkout gets the install remedy. Its control removes the project's manifest, and the walk then reaches the outer one and names the build.

  Every case asserts that @object-ui/console is absent.

• Ablations, each landed on disk via scripts/ablation-replace.mjs and restored with blob equal to HEAD and an empty git diff HEAD:

  • the signal forced to null: 2 of 4 red (the framework case and the stop-rule control);
  • the walk made to keep climbing past the nearest manifest: 1 of 4 red (the stop-rule case).

• Live boot, framework context: pnpm dev -- --fresh -p 38592 from this worktree, with no packages/console/dist and no ../objectui beside it. The boot printed:

  ⚠ Console dist not found at packages/console/dist — `pnpm build` does not produce it. Build it with `pnpm objectui:build` in /home/user/objectstack-issue-22155 (uses a ../objectui checkout if present, else clones objectui at the pinned commit — needs network).
  

  /api/v1/health answered 200 and /_console/ answered 404. The non-framework branch was verified by the unit test only; no scaffolded project was booted.

• --affected, verified with pnpm turbo run test --affected --dry-run=json (turbo 2.11.5):

  • TURBO_SCM_BASE=origin/main before the change: 0 packages;
  • after the change: 8 packages, namely //, @objectstack/cli and its six dependents dogfood, downstream-contract and example-{crm,multi-package,showcase,todo};
  • against this checkout's stale local main (9cc2c7954a, 108 commits behind): 81 packages. That is why the README says a stale main widens the set.

• @objectstack/cli:

  • build: exit 0;
  • typecheck, including check:test-typecheck: exit 0;
  • vitest run --project unit: 263 files and 3878 tests passed;
  • --project integration, run locally because serve.ts is on the boot path: 93 files, 897 tests passed and 2 skipped.

• Gates: node scripts/pm/dispatch-gates.mjs --commands over this diff derived 68 commands. That is the dispatch's 53 plus 15 that the changeset and test files bring in. All 68 exited 0. --ran reconciliation: 68 derived, 68 run, 0 NOT-MEASURED, 0 UNRUN.

• Lint, a proven narrowing: eslint --no-inline-config --format json on the 4 changed TS files reported 4 files, 0 errors and 0 warnings. --print-config shows each file is in the config's population. eslint.config.mjs enables no type-aware linting (no parserOptions.project or projectService), so this diff cannot move a verdict on an untouched file. The repo-wide pnpm lint is left to CI.

Acceptance notes

• os serve --help still describes --[no-]ui as Enable the bundled Console portal at /_console/ when @object-ui/console is installed. That is the same wrong package name, at serve.ts:1198 and mirrored in packages/cli/README.md:244. It is outside this claim's file surface, so it is reported to the PM rather than changed here.
• packages/spec/scripts/publish-smoke-boot-failure.test.ts and a comment in scripts/publish-smoke.sh quote the old warning line. Those quotes are verbatim records of past CI runs, kept unchanged on purpose. The smoke's boot-failure predicate does not key on this line, and neither does the new wording.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 4 documentable anchor(s).

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

• content/docs/deployment/cli.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/deployment/self-hosting.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/deployment/tenancy-modes.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/deployment/troubleshooting.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/getting-started/examples.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/getting-started/your-first-project.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/plugins/development.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/plugins/index.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/protocol/kernel/index.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/protocol/kernel/plugin-spec.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/protocol/objectql/schema.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/upgrading.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))

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

• content/docs/releases/v17/17-3.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))
• content/docs/releases/v17/17-4.mdx (via package.json (literal, a string literal in findConsoleBuildRoot))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os serve (command, 31 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 28 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 3b493184e1e395549d80723e267d2ff80ce33da4 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 3788587880472349aea61099ba9fdcaa5de40422 — the merge of head 0ef75bd7d96b5d91b96e669f0617094947a1cfb0 into base 3b493184e1e395549d80723e267d2ff80ce33da4, 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 3788587880472349aea61099ba9fdcaa5de40422 && git checkout 3788587880472349aea61099ba9fdcaa5de40422
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 3b493184e1e395549d80723e267d2ff80ce33da4 0ef75bd7d96b5d91b96e669f0617094947a1cfb0 && git checkout -B drift-repro 3b493184e1e395549d80723e267d2ff80ce33da4 && git merge --no-ff 0ef75bd7d96b5d91b96e669f0617094947a1cfb0

node scripts/docs-audit/affected-docs.mjs --json 3b493184e1e395549d80723e267d2ff80ce33da4

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