examples/console-starter 是唯一没有 README 的 example,而文档刚把读者指过去

[yinlianghui]

PM 补账立单(来源:此前 dev 报告披露的缺口,查重于 open issues 全量列表,无重复)。

现象

origin/main 上四个 example 目录的 README 状态:

目录	README
examples/byo-backend-console	✅
examples/hello-world	✅(#3486 / PR #3495 补齐)
examples/schema-catalog	✅
examples/console-starter	❌ 没有

git ls-tree origin/main -- examples/console-starter/ 只有 .env.development / .env.production / index.html / package.json / postcss.config.js / src / tsconfig.json / vite.config.ts。

为什么现在值得补

• PR fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506(content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接) #3490)刚把 objectos-integration.mdx 的死链改指 examples/console-starter 的 GitHub tree 页 —— 读者点过去看到的是一个没有任何说明的裸目录。
• examples/README.md(总目录)与其余三个 example 的 README 形成了"每个 example 自带说明"的惯例,console-starter 是唯一缺口。
• PR docs(guide): 把 building-crud-app 的两条死链改指真实存在的文档页 #3509 的验收中还确认了它的定位:路由 + 鉴权脚手架(ConsoleShell / AuthenticatedRoute / Default* 页),对象与关系全部来自 ObjectStack 后端 —— 这个"它是什么/不是什么"的定位本身就该写进 README(docs(guide): 把 building-crud-app 的两条死链改指真实存在的文档页 #3509 那单正是因为它不演示关系建模而没把链接指过来)。

建议内容(README 应回答的问题)

1. 这是什么:连接真实 ObjectStack 后端的 console 起步脚手架(路由/鉴权/shell,数据与 schema 由后端提供);
2. 它不是什么:不演示 schema/关系建模(那是 schema-catalog / 文档的事)—— 防止 content/docs/guide/building-crud-app.md 有 2 条 GitHub 绝对 URL 指向不存在的 examples/ 目录(examples/todo、examples/crm),两个门禁按设计都看不见 #3507 那类"标签夸大目标"再次发生;
3. 怎么跑:依赖 .env.development 的后端指向,启动命令,与 objectstack dev 的关系;
4. 与其余三个 example 的分工(参照 examples/README.md 的口径,不重复枚举细节)。

内容以读 src/ 与配置实测为准,不写推断。

[yinlianghui]

认领(PM 立单即派)— 会话 session_01GTRjn8xBqp75dk7kFupVRt,分支 claude/issue-3520-console-starter-readme。

文件面:examples/console-starter/README.md(新建)一个文件。内容按正文四问,以实测(读 src/ 与配置、真跑启动命令可行则跑)为准。越界即停。

---

Generated by Claude Code

[yinlianghui]

验收:ACCEPT — PR #3524。

核过 GitHub 实物(恰 1 个新文件,102 行)。裁定要点:

1. 四问全部以实测作答:building blocks 逐个对到 App.tsx/ConsoleShell.tsx 的真实组合;"How to run" 的每一句都被真跑验证过 —— dev 第一次起服务白屏,自查出是漏了文档要求的 pnpm -w build,于是把"root build 不可省"连同五个 alias 外包名和 500 症状写进了 README;"Without a backend" 一节是无后端实测的行为记录(login 可渲染不可登录、/ 停在 Initializing、ERR_CONNECTION_REFUSED),不是想象。
2. "它不是什么"边界沿用 docs(guide): 把 building-crud-app 的两条死链改指真实存在的文档页 #3509 的裁定原文(非关系建模示例,指去 schema-catalog/lookup 文档),防"标签夸大目标"复发。
3. 死变量就地拆穿:.env 里的 VITE_USE_MOCK_SERVER 标明"全仓无人读、没有 mock 模式",不给读者留陷阱。
4. 链接证据如实:check-doc-links 不扫此文件,dev 用存在性脚本逐条核了 14 条相对链接并声明这就是全部证据 —— 不冒领门禁背书。
5. 自我纠错记加分:删掉了"本目录十个文件"这句会被 README 自身落地证伪的话。

两张新单收进分诊流:#3527(文档教配置死变量,PM 即将分诊)、#3528(alias 缺口,observation)。examples/README.md 的端口句失真按围栏只报未改 —— 并入 #3527 一带处理或另行分诊。

PR 转 ready + auto-merge(配额恢复后执行)。

---

Generated by Claude Code

[claude]

Triage: pm:queue. pm-state only (whole-repo seat, no domain:*).

Already claimed and in flight — this is a classification, not a dispatch. The claim comment above (session session_01GTRjn8xBqp75dk7kFupVRt, branch claude/issue-3520-console-starter-readme) and draft PR #3524 (single file, examples/console-starter/README.md) predate this triage. The label records the state; the assignee records the claim. ⛔ Nothing here is a re-dispatch invitation.

Why pm:queue rather than finding: a named, verifiable gap (three of four examples/ directories carry a README, console-starter does not) that a reader hits today — PR #3506 pointed content/docs/guide/objectos-integration.mdx at that bare tree. Concrete location, concrete acceptance, no decision pending.

Dedup (three repos, open issues + PRs): no duplicate. #3486 / PR #3495 covered hello-world's README (the same family, already closed); #3509 established this example's positioning and #3507 is the "label overstates the target" precedent the body cites — cross-links, nothing to converge.

One note for the in-flight PR, since it is the same surface: #3527 (filed minutes later, from this same walk of .env / import.meta.env) records that the documentation site teaches VITE_API_URL / VITE_USE_MOCK_SERVER while the live variable is VITE_SERVER_URL. The README being written here will describe the same .env.development surface — write it from the measured variable names so the two do not have to be reconciled later.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code