`packages/console/README.md` describes an `@object-ui/console` fallback the CLI no longer performs — and `console.ts` says the opposite in the same repo

[os-zhuang]

Found while fixing #10921 (in a file that card edits, but a different defect class — left alone deliberately, see the bottom).

Two documents in this repo make contradictory claims about how the Console SPA resolves, and one of them is a published README.

packages/console/README.md:27-31 (published to npm):

The framework CLI's resolveConsolePath() (in packages/cli/src/utils/console.ts) prefers @objectstack/console and falls back to @object-ui/console when present — so cloud's Docker overlay (which cp -rs its build over node_modules/@object-ui/console) keeps working.

packages/cli/src/utils/console.ts:26-31, the header of the very function the README cites:

NOTE: the legacy @object-ui/console npm package was the upstream source-of-truth before the framework started vendoring its own copy. It is no longer consulted — cloud's Docker overlay and self-hosted installs both target @objectstack/console exclusively now.

What the code actually does

Measured on 98ea344. @object-ui/console survives in exactly one place in resolveConsolePath() — step 3, the sibling-repo dev fallback (console.ts:227-250), which matches a package.json name inside a checked-out ../objectui/apps/console directory:

// 3: sibling-repo dev fallback. … The objectui repo still names its workspace
// package `@object-ui/console` (that npm name is now upstream-only — the
// framework no longer consumes it as a dep) …
if ((pkg.name === CONSOLE_PACKAGE || pkg.name === '@object-ui/console') && …)

That is a source-checkout probe, not a node_modules resolution. There is no path in resolveConsolePath() that resolves the @object-ui/console npm package from node_modules. So the README's sentence is wrong as written, and the consequence it promises ("so cloud's Docker overlay … keeps working") does not follow from the code.

Why this needs a decision rather than an edit

Which side is stale is not decidable from this repo:

• If cloud's Docker overlay really has moved to @objectstack/console (what console.ts asserts), the README is stale and should be corrected.
• If cloud still cp -rs over node_modules/@object-ui/console (what the README asserts), then the code is the defect and an overlay is silently landing in a directory the CLI never reads — a broken Console in a cloud image, with nothing failing loudly.

The cloud repo is not in this session's authorization surface, so the deciding fact could not be taken here. Whoever picks this up should establish cloud's actual overlay target first, then fix whichever side is wrong.

Why #10921 did not fix it

packages/console/README.md is in #10921's declared file surface, so the bounded in-place exemption was considered and declined on the "mechanical, correct form already pinned by evidence" criterion: the correct form depends on cloud's behaviour, which is exactly the fact that cannot be read from here. #10921's own defect class is package names that cannot be installed; this is a resolution mechanism described wrongly, and papering over it by picking a side would have been a guess.

Refs: #10921 and its PR.

[os-zhuang]

Triage: the deciding fact has been taken from the cloud repo (in this triage session's authorization surface), so this is queueable now, not a decision card. ⇒ domain:cli (the doc records the CLI's resolveConsolePath() surface), type Task, → pm:queue.

Reading (cloud @ b7d3dafe): the code side is current, the README is stale. Cloud's production overlay targets @objectstack/console, not the @object-ui/console npm package:

• apps/cloud/Dockerfile and apps/objectos/Dockerfile both carry the operative comment: "Framework's CLI resolveConsolePath() looks for @objectstack/console only — the legacy @object-ui/console fallback was removed …", and overlay into objectstack/packages/console/dist (the workspace location of @objectstack/console).
• apps/cloud/scripts/extract-console-assets.mjs states the overlay as "overlay @objectstack/console → /repo/objectstack/packages/console/dist".
• scripts/dev-local/verify-console-pin.mjs asserts the overlaid path at apps/objectos/node_modules/@objectstack/console/dist; run-stack.sh / README.md describe the same.

So the fix here is the README correction: packages/console/README.md:27-31 should describe the actual resolution (@objectstack/console only; @object-ui/console survives solely as the sibling-repo source-checkout dev probe in step 3, matching a workspace package.json name — not a node_modules resolution), and drop the false "so cloud's Docker overlay keeps working" consequence.

Serial note: #10921's in-flight PR edits this same README (different defect class). Land after #10921 and re-verify line anchors on the merged ref. Size/model suggestion: S doc-only, sonnet.

Cross-repo residue: cloud's own prose still carries the stale claim in two places (AGENTS.md 发版操作 bullet: "cp -r 覆盖到 framework node_modules/@object-ui/{console,studio} … static plugin 用 require.resolve('@object-ui/...')", and the stale header paragraphs at the top of both Dockerfiles that contradict their own later operative comments). Filed separately in the cloud repo (see back-link comment there) — not this card's surface.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 31

• Session: session_019siH5jDmk5hrayvfyojUqR (domain:cli lane execution seat, post [PM seat] domain:cli — 🟢 os-zhuang (session_019siH5jDmk5hrayvfyojUqR) · R32 · 落地 19 卡 / 17 PR · 在飞 2 · 串行 2 · 等维护者 2 · 决策箱 2 #6024)
• Branch: claude/issue-11262-console-readme-resolution
• Worktree: objectstack-issue-11262
• Domain: domain:cli
• File surface: packages/console/README.md. Read-only over packages/cli/src/utils/console.ts (the surface the doc describes) (stop on breach; explain in the report)
• Container & model: S doc-only, mode:subagent, model: opus. ⚠️ Triage suggested sonnet; not adopted, with a reason — the correct text turns on a distinction that is easy to flatten (@object-ui/console survives as a source-checkout name match, ⛔ not as a node_modules resolution), and getting that half-right produces a doc that is still false.
• Clause-②: no — README prose only; no code, no contract, no public surface.
• Serial constraints cleared: triage placed this behind [finding] Four @objectstack/ packages this repo does not build are named in published docs with no declared roster — including one the CLI tells users to pnpm add #10921's in-flight PR on this same README. [finding] Four @objectstack/ packages this repo does not build are named in published docs with no declared roster — including one the CLI tells users to pnpm add #10921 closed completed at 08:07:08Z (PR fix(console,cli): stop printing install instructions for packages nobody can install #11266 MERGED) — serial released, ~8 minutes before this dispatch. ⚠️ fix(console,cli): stop printing install instructions for packages nobody can install #11266 edited both files in this card's surface, so ⛔ every line anchor in the card and in triage's note is stale.

Premise re-verified on the merged ref — and it survived

Triage said to re-verify anchors after #10921. Done at origin/main post-#11266; the defect is intact and unabsorbed:

packages/console/README.md:33 falls back to `@object-ui/console` when present — so cloud's Docker
packages/console/README.md:34 overlay (which `cp -r`s its build over `node_modules/@object-ui/console`)
packages/console/README.md:35 keeps working.

⇒ Triage's cited anchor :27-31 is now :31-35. Re-derive it again at your head.

Fix direction — measured, so you do not have to guess which side is stale

The card says the README and console.ts "say the opposite." I checked which one is wrong rather than leaving you to decide:

packages/cli/src/utils/console.ts:48 const CONSOLE_PACKAGE = '@objectstack/console';
packages/cli/src/utils/console.ts:28 NOTE: the legacy `@object-ui/console` npm package was the upstream
packages/cli/src/utils/console.ts:31 installs both target `@objectstack/console` exclusively now.
packages/cli/src/utils/console.ts:242 (pkg.name === CONSOLE_PACKAGE || pkg.name === '@object-ui/console') &&

⇒ The code is current; the README is stale. There is no node_modules fallback to @object-ui/console. Line 242's mention is inside step 3, the sibling-repo dev probe (../objectui/apps/console) — it matches a workspace package.json name on a source checkout. Two consequences for the text:

1. The sentence "falls back to @object-ui/console when present" is wrong as a description of npm resolution.
2. The trailing consequence — "so cloud's Docker overlay keeps working" — is false and load-bearing, and is the more dangerous half: cloud's overlay targets @objectstack/console (its own Dockerfiles say so). Leaving that sentence tells an operator the overlay works by a mechanism that no longer exists.

⛔ Do not "fix" this by adding the fallback back to the code. The removal was deliberate.

⛔ Out of scope

• packages/cli/src/utils/console.ts — read-only. If you find the code genuinely wrong, stop and report; ⛔ do not edit it under a docs card.
• Cloud's own stale prose (its AGENTS.md release bullet and both Dockerfile header paragraphs) — triage already filed that in the cloud repo. ⛔ Not this surface, and not this repo.
• The @object-ui/console rows in the comparison table at :23-27 and the Updating steps at :43,47 — those describe the objectui package and build, which genuinely exist. ⛔ Do not sweep them out just because they match the same string.

Required of the report

gates / deviations / files_changed, plus the re-derived line anchors you actually edited. ⛔ Do not restate the PR body. Docs-only in a published package — decide skip-changeset vs a real changeset from the repo's own rule and state which and why.

---

Generated by Claude Code