Filing gate: ① user-visible defects with named landing spots (finding class (a): "能用但用户可见地错 … 误导文案"), folded into one card per the filing gate's quota rule — seven doc/help-string items, each a one-line fix, each verified in this session.
reach: public entries measured once each — git clone + ls for the CONTRIBUTING links (absent), curl for the README data endpoint (401), npx os dev --help and npx os init --no-install for the help strings, pnpm run validate for the tutorial transcript.
Reader: domain:devx seat for CONTRIBUTING.md, README.md, content/docs/getting-started/{index,examples,build-with-claude-code}.mdx; domain:cli for the two CLI strings (os dev --help port text in packages/cli/src/commands/dev.ts, os init next-steps text).
Dedup: search_issues "CONTRIBUTING.md stale outdated references spec repository internal/planning PRIORITIES.md" → 0 on CONTRIBUTING (#12366, closed, cleaned the docs-site spec links only); "README curl data endpoint returns 401 UNAUTHENTICATED without sign-in example misleading" → 0; "docs prerequisites pnpm 8+ vs pnpm 10 inconsistent README getting-started examples three examples os dev --help PORT OS_PORT" → 0 (open + closed).
Filed on the maintainer's instruction in this session: 「设想你是一个新人,第一次打开 github objectstack 项目主页,了解本项目,并按照文档指引执行完整的试用流程,并对阅读文档和试用过程中遇到的问题立 issue」.
Summary
Walking README → Getting Started → scaffold → validate → dev as a newcomer on main (packages at 17.7.0), these are the places where the text and the tool disagree. None blocks the flow; each costs a double-take, and together they read as "the docs are not run". One card because every item is a one-line fix in a doc or a help string; split if the owning seat prefers.
1. CONTRIBUTING.md describes the retired objectstack-ai/spec repository
The README's Community section sends a contributor here first. On a fresh clone of main:
| Line(s) |
What it says |
What is true |
| 34, 38 |
git clone https://github.com/YOUR_USERNAME/spec.git / git remote add upstream https://github.com/objectstack-ai/spec.git |
the repository is objectstack-ai/objectstack |
| 55–56, 425 |
links to ./internal/planning/PRIORITIES.md, DEVELOPMENT_ROADMAP.md, PLANNING_INDEX.md |
no internal/ directory exists |
| 57, 443 |
objectstack-ai/spec/issues, objectstack-ai/spec/discussions |
wrong repository |
| 26 |
PNPM >= 8.0.0 |
packageManager pins pnpm@10.31.0; README says pnpm 10 |
| 153–156 |
docs live in content/docs/guides/ and content/docs/specifications/ |
neither directory exists |
| 371–375 |
bilingual my-schema.mdx / my-schema.cn.mdx |
zero *.cn.mdx files under content/docs/ |
| 1–3 |
"Contributing to ObjectStack Protocol … the protocol specifications" |
the repo is the whole open stack |
It also never mentions AGENTS.md, which CLAUDE.md and the README call the single source of truth, and shows a git add . + push-to-fork flow in place of the worktree-first, changeset-carrying flow that actually gates a PR.
2. README's first curl returns 401
README, "The runtime runs it": "The REST API exists the moment the object does — no controllers to write:" followed by curl http://localhost:3000/api/v1/data/support_desk_ticket. Against a scaffolded project this answers 401 {"error":"UNAUTHENTICATED",…}. The scaffolded project's own README and your-first-project.mdx show the sign-in/email call first; the root README should too, or say the endpoint needs a session.
3. Three pnpm floors for one monorepo
README: pnpm 10 (corepack enable); getting-started/index.mdx and examples.mdx: pnpm 8+; CONTRIBUTING.md: >= 8.0.0; package.json: packageManager: pnpm@10.31.0 — the only value corepack honours.
4. "The monorepo ships three ready-to-run examples"
examples.mdx opens with three (Todo, CRM, Showcase); examples/ holds five (app-multi-package, embed-objectql as well), the README lists all five, and the same page documents app-multi-package further down.
5. os dev --help and the docs disagree on the port variable
npx os dev --help → -p, --port=<value> Server port (overrides $PORT). deployment/cli.mdx → OS_PORT / PORT; getting-started/index.mdx → "OS_PORT; PORT is the legacy alias". The CLI reads readEnvWithDeprecation('OS_PORT', 'PORT') (packages/cli/src/utils/port-contract.ts), so the help string names only the deprecated spelling.
6. The tutorial's "clean" transcript omits a warning its verbatim example produces
build-with-claude-code.mdx says every example passes os validate verbatim and prints, under "Once it's clean", a transcript with no warning. It does pass — but description: Field.textarea(…) on the ticket object sits in no view, so every validate / build / dev run prints the field-no-consumers warning for it (a ~900-character paragraph). Either place description on a view in the example, or show the warning and say why it is expected.
7. os init writes a pnpm project and then says npm install
npx os init init-app --no-install writes pnpm-workspace.yaml and "engines": { "pnpm": ">=10.15" }, then prints npm install # Install dependencies under Next steps. create-objectstack already prints the detected package manager (pnpm run dev); os init should do the same, or drop the pnpm-only files when it recommends npm.
Environment
Fresh clone of main; create-objectstack@17.7.0, @objectstack/cli@17.7.0; Node v22.22.0; pnpm 10.31.0; npm 10.9.4. Every command above was run in this session.
Generated by Claude Code
Filing gate: ① user-visible defects with named landing spots (
findingclass (a): "能用但用户可见地错 … 误导文案"), folded into one card per the filing gate's quota rule — seven doc/help-string items, each a one-line fix, each verified in this session.reach: public entries measured once each —
git clone+lsfor the CONTRIBUTING links (absent),curlfor the README data endpoint (401),npx os dev --helpandnpx os init --no-installfor the help strings,pnpm run validatefor the tutorial transcript.Reader:
domain:devxseat forCONTRIBUTING.md,README.md,content/docs/getting-started/{index,examples,build-with-claude-code}.mdx;domain:clifor the two CLI strings (os dev --helpport text inpackages/cli/src/commands/dev.ts,os initnext-steps text).Dedup:
search_issues"CONTRIBUTING.md stale outdated references spec repository internal/planning PRIORITIES.md" → 0 on CONTRIBUTING (#12366, closed, cleaned the docs-sitespeclinks only); "README curl data endpoint returns 401 UNAUTHENTICATED without sign-in example misleading" → 0; "docs prerequisites pnpm 8+ vs pnpm 10 inconsistent README getting-started examples three examples os dev --help PORT OS_PORT" → 0 (open + closed).Filed on the maintainer's instruction in this session: 「设想你是一个新人,第一次打开 github objectstack 项目主页,了解本项目,并按照文档指引执行完整的试用流程,并对阅读文档和试用过程中遇到的问题立 issue」.
Summary
Walking README → Getting Started → scaffold → validate → dev as a newcomer on
main(packages at 17.7.0), these are the places where the text and the tool disagree. None blocks the flow; each costs a double-take, and together they read as "the docs are not run". One card because every item is a one-line fix in a doc or a help string; split if the owning seat prefers.1. CONTRIBUTING.md describes the retired
objectstack-ai/specrepositoryThe README's Community section sends a contributor here first. On a fresh clone of
main:git clone https://github.com/YOUR_USERNAME/spec.git/git remote add upstream https://github.com/objectstack-ai/spec.gitobjectstack-ai/objectstack./internal/planning/PRIORITIES.md,DEVELOPMENT_ROADMAP.md,PLANNING_INDEX.mdinternal/directory existsobjectstack-ai/spec/issues,objectstack-ai/spec/discussionsPNPM >= 8.0.0packageManagerpinspnpm@10.31.0; README says pnpm 10content/docs/guides/andcontent/docs/specifications/my-schema.mdx/my-schema.cn.mdx*.cn.mdxfiles undercontent/docs/It also never mentions
AGENTS.md, which CLAUDE.md and the README call the single source of truth, and shows agit add .+ push-to-fork flow in place of the worktree-first, changeset-carrying flow that actually gates a PR.2. README's first
curlreturns 401README, "The runtime runs it": "The REST API exists the moment the object does — no controllers to write:" followed by
curl http://localhost:3000/api/v1/data/support_desk_ticket. Against a scaffolded project this answers401 {"error":"UNAUTHENTICATED",…}. The scaffolded project's own README andyour-first-project.mdxshow thesign-in/emailcall first; the root README should too, or say the endpoint needs a session.3. Three pnpm floors for one monorepo
README:
pnpm 10 (corepack enable);getting-started/index.mdxandexamples.mdx:pnpm 8+;CONTRIBUTING.md:>= 8.0.0;package.json:packageManager: pnpm@10.31.0— the only value corepack honours.4. "The monorepo ships three ready-to-run examples"
examples.mdxopens with three (Todo, CRM, Showcase);examples/holds five (app-multi-package,embed-objectqlas well), the README lists all five, and the same page documentsapp-multi-packagefurther down.5.
os dev --helpand the docs disagree on the port variablenpx os dev --help→-p, --port=<value> Server port (overrides $PORT).deployment/cli.mdx→OS_PORT / PORT;getting-started/index.mdx→ "OS_PORT; PORT is the legacy alias". The CLI readsreadEnvWithDeprecation('OS_PORT', 'PORT')(packages/cli/src/utils/port-contract.ts), so the help string names only the deprecated spelling.6. The tutorial's "clean" transcript omits a warning its verbatim example produces
build-with-claude-code.mdxsays every example passesos validateverbatim and prints, under "Once it's clean", a transcript with no warning. It does pass — butdescription: Field.textarea(…)on the ticket object sits in no view, so everyvalidate/build/devrun prints thefield-no-consumerswarning for it (a ~900-character paragraph). Either placedescriptionon a view in the example, or show the warning and say why it is expected.7.
os initwrites a pnpm project and then saysnpm installnpx os init init-app --no-installwritespnpm-workspace.yamland"engines": { "pnpm": ">=10.15" }, then printsnpm install # Install dependenciesunder Next steps.create-objectstackalready prints the detected package manager (pnpm run dev);os initshould do the same, or drop the pnpm-only files when it recommends npm.Environment
Fresh clone of
main;create-objectstack@17.7.0,@objectstack/cli@17.7.0; Node v22.22.0; pnpm 10.31.0; npm 10.9.4. Every command above was run in this session.Generated by Claude Code