Repository navigation
[finding] docs on-ramp drift a first-time reader hits in sequence: stale CONTRIBUTING.md (retired spec repo), README's first curl gets 401, three pnpm floors, "three examples" vs five, os dev --help / os init strings, tutorial transcript #22156
Description
Activity
Path: the road — start: the docs on-ramp reads true | 缺项 | P3
Triage: first grade,
documentation·priority:p3·domain:devx·area:devpath·pm:queue(findingremoved). Direction: the seven one-line fixes, as listedTriage seat (objectstack-wide, seat post #6015) ·
session_01AavokzJ5DndAwitDXvKy4U· 2026-10-08T05:09Z. ⛔ Not a claim, ⛔ not a dispatch.Triage: lands in
CONTRIBUTING.md,README.mdandcontent/docs/getting-started/{index,examples,build-with-claude-code}.mdx, plus two CLI help strings (packages/cli/src/commands/dev.ts,os init's next-steps text) ⇒domain:devx; rationale: the docs are that lane's; the two CLI strings are declared todomain:clicross-lane. Read onmainec8f37c890.- Why p3: each item misleads a first-time reader for a step, and none breaks a command.
- Direction:
- fix each listed item as the body measures it
- the README
curlexample states that it needs a session, or uses a public endpoint
- Serial with [finding] README's
pnpm install && pnpm build && pnpm devserves 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 and [maintainer] README "Hack on the framework" should state what its commands cost on a fresh clone —pnpm objectui:build≈ 10 min to get the Console,pnpm test≈ 54 min — and point to turbo's--affectedpath for a contributor's own change #22164 on the README. Clause-②: no. Patch changeset only for the CLI strings.
Claim: PM loop round 1
Session:session_0115N1oNnQS5WqofZ2DzaT3q
Account:os-sales(the seat's linked user asGET /useranswers it; the card's assignee)
Branch:claude/issue-22156-docs-onramp-drift
Worktree:objectstack-issue-22156
Domain:domain:devx
Seat:domain:devx#1
File surface:CONTRIBUTING.md,README.md(the data-endpointcurlexample),content/docs/getting-started/index.mdx,content/docs/getting-started/examples.mdx,content/docs/getting-started/build-with-claude-code.mdx; cross-lane intodomain:cli(declared on its seat post):packages/cli/src/commands/dev.ts(the--portflag description) andpackages/cli/src/commands/init.ts(the Next-steps text), with any test pinning those two strings; one patch.changeset/22156-*.mdfor@objectstack/cli(stop on breach; explain in the report)
Container & model:M,mode:subagent,model: opus — the default tier; dispatch-gates --tier: "no path-derived mandate", so the PM's per-card call (seven items, two of them with a choice to make)
Clause-②: no
Responsibility:this lane's on-ramp docs and two CLI help strings | none | every first-time reader walking README → Getting Started → scaffold, today
Thread-read: 6052757727
Serial constraints cleared:PR #22193 (domain:spec, draft) edits build-with-claude-code.mdx at the "author-time rules (49)" transcript line — a different hunk from item 6; whichever lands later merges main. PR #22215 (draft) edits getting-started/your-first-project.mdx, outside this surface. #22155/#22164 and #22152/#22165 (the README and getting-started serial predecessors triage named) are landed. No open PR touches CONTRIBUTING.md, README.md, index.mdx, examples.mdx or the two CLI files (9 open PRs' file lists read); in-flight domain:devx claims (#22085, #22014, #22253) are disjoint— open-PR file lists read at 2026-10-08T10:20Z
Generated by Claude Code
os-dev-report
{
"issue": 22156,
"status": "done",
"branch": "claude/issue-22156-docs-onramp-drift",
"pr": "#22280",
"session": "session_0115N1oNnQS5WqofZ2DzaT3q (mode:subagent, the dispatching PM session's id; the container's CLAUDE_CODE_REMOTE_SESSION_ID resolves to the same id)",
"premise_still_valid": true,
"summary": "All seven items fixed as the card measures them, each re-measured on the branch first (base 3513ac7, main 8cbe255 merged in at 8fe75a2 because #22193 landed during the run). Items 1-6 are docs. Items 5 and 7 are the two CLI strings, carried by one patch changeset for @objectstack/cli. Item 7's real defect is wider and its literal repro is narrower than the card says: under --no-install the chosenPm variable kept its literal 'npm' initialiser, so --package-manager pnpm and pnpm-invoked runs printed npm install too. The fix resolves it before the install branch. A plain npx run still prints npm install, which is correct because the scaffold deliberately supports npm (init.test.ts pins it), so no scaffold files change. Item 6 took the PM's clean-example route on the four axes: the view file declares the create and edit form that places description. Verbatim validate: the old page warns field-no-consumers, the new page passes with 50 rules and no warning.",
"items": {
"1": "CONTRIBUTING.md rewritten for this repo. Every card row fixed: title and scope, objectstack.git clone and upstream URLs, issue and discussion URLs, internal/planning links removed, real docs trees listed with references/ marked generated and releases/ release-owned (the old text told authors to hand-write MDX in references/), the .cn.mdx section removed, pnpm 10, the dead QUICK_START_IMPLEMENTATION.md link removed. It points to AGENTS.md instead of restating rules, adds the changeset step and the worktree note, and keeps the needs:pack-smoke criterion word for word because pack-smoke-optin.yml cites this file for it.",
"2": "README data curl now signs in first (POST /api/v1/auth/sign-in/email as the seeded dev admin, cookie jar) and then GETs with the cookie, with one sentence saying data calls need a session. Measured on a booted tutorial scaffold: no session 401 UNAUTHENTICATED, sign-in 200, with cookie 200.",
"3": "One floor, pnpm 10, in README (already said it), getting-started/index.mdx, examples.mdx and CONTRIBUTING.md. Measured: root engines declares only node. packageManager is pnpm@10.31.0. A global pnpm 10.28.0 runs as 10.31.0 inside the repo. pnpm@8.15.9 gives ERR_PNPM_LOCKFILE_BREAKING_CHANGE and pnpm@9.15.9 gives ERR_PNPM_LOCKFILE_CONFIG_MISMATCH (overrides) on a frozen install.",
"4": "examples.mdx now opens with five examples: three runnable apps, each with a pnpm dev:* script, then app-multi-package (linked to its section) and embed-objectql, matching the tree and the README table.",
"5": "dev.ts --port help now reads 'Server port (overrides $OS_PORT; $PORT is the legacy alias)'. Verified with os dev --help on the built CLI. No test, snapshot or generated docs page pins the string.",
"6": "The tutorial's view file gains a form (one section, name ticket, with subject, description, priority and status). The prompt asks for the form, one paragraph explains field-no-consumers, and the clean transcript adds the Logic and Security lines the command prints today. The (50) rule-count line from #22193 is untouched.",
"7": "init.ts resolves chosenPm before the install branch, by the same rule (flag, then user agent, then npm). Measured before and after on the built CLI: npm agent with no flag gives npm install both times (control). npm agent with --package-manager pnpm went from npm install to pnpm install. pnpm agent with no flag went from npm install to pnpm install."
},
"tests": "HEAD 8fe75a2. New unit-tier test packages/cli/src/commands/init-next-steps-package-manager.test.ts (in-process Init.run, 3 cases), 3 passed. Ablation with the fix committed: scripts/ablation-replace.mjs restored the old semantics (anchor 1 to 0, blob c4c2caca to 9b93b146) and 2 of 3 failed (flag case and pnpm-agent case), the npm control passed. Restored: blob == HEAD and git diff HEAD is empty. pnpm --filter @objectstack/cli typecheck: VERDICT command-exit 0, check:test-typecheck OK. pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2: 265 files, 3918 tests passed. The integration tier is declared to CI because the diff touches no spawn entry or integration-tier file. The first full unit run was red only on the new test (5s default timeout under load, which let one run leak into the next case), fixed with the 60s budget the in-process doctor tests use. Item 6: verbatim os validate on a blank scaffold with the page's files passes with no warning at 8fe75a2, the old view still warns (control), and tsc --noEmit on the scaffold passes with ticket.view.ts confirmed in --listFiles.",
"gates": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 8fe75a2 (merge base 8cbe255, 9 paths): 94 commands, all 94 exit 0. --ran reconciliation (with exit codes): 94 derived, 94 run, 0 NOT-MEASURED (a derived zero). History: the first pass at 6be33e2 had one real red, check-docs-section-name (the new form section lacked name, fixed), and four exit 3 prerequisite refusals: plugin-teardown self-test on the shallow clone (cleared by fetching its pinned fixture commit), and spec check:skill-examples, check:dual-build-cjs-loads and check:i18n-coverage (cleared by a full pnpm build). CI on PR #22280: in_progress at report time, not waited on.",
"line_budget": "+256 / -407 over 9 files (663 changed lines, under the 5000 human-merge threshold). No skills/** or governed path touched. CONTRIBUTING.md shrinks 447 to 158 lines.",
"files_changed": [
".changeset/22156-cli-port-help-and-init-next-steps.md",
"CONTRIBUTING.md",
"README.md",
"content/docs/getting-started/build-with-claude-code.mdx",
"content/docs/getting-started/examples.mdx",
"content/docs/getting-started/index.mdx",
"packages/cli/src/commands/dev.ts",
"packages/cli/src/commands/init-next-steps-package-manager.test.ts",
"packages/cli/src/commands/init.ts"
],
"deviations": [
"Merged main (8cbe255) into the branch at 8fe75a2. The serial note said the later PR merges main, and #22193 landed mid-run. The merge was clean, and I rebuilt and re-ran everything after it.",
"Added a test file not named in the boundaries: packages/cli/src/commands/init-next-steps-package-manager.test.ts (unit tier, in the declared cli/commands directory). It pins the fixed Next-steps behaviour; no existing test pinned either string.",
"Commit trailers use the model-free pair AGENTS.md requires (Co-authored-by: Claude) rather than the harness reminder's model-named trailer. The PR body footer uses the AGENTS.md session-URL form rather than the reminder's form. AGENTS.md outranks the reminder by the reminder's own precedence line.",
"Fetched commit 621a487 into the shared object store (no ref written) so check-plugin-teardown-shape --self-test could read its pinned fixture on this shallow clone.",
"Created and removed one throwaway detached worktree at the base commit for the pnpm 8 and 9 probes. Its status was clean (no node_modules), and it was removed without --force."
],
"mcp_calls": "0",
"api_writes": "3: POST /repos/objectstack-ai/objectstack/pulls via fleet-write relay (pr_create, PR #22280, read-back identical 10927 bytes); POST /repos//issues/22280/assignees via label-write relay (os-sales, read back); POST /repos//issues/22156/comments via post-stamped (this report). Each relay stroke is one POST /repos/objectstack-ai/objectstack/dispatches. Plus git push of the branch (not REST).",
"open_questions": [],
"out_of_scope_findings": [
"class: a · reach: public door os start --help prints 'Port to listen on (overrides $PORT, default 3000)' while start reads OS_PORT first (start.ts readEnvWithDeprecation('OS_PORT', 'PORT')) · evidence: measured on the built CLI at 8fe75a2, landing packages/cli/src/commands/start.ts:94. Same defect as #22156 item 5, but the file is outside the PM-declared surface, so not edited · dedupe words: os start --help port OS_PORT PORT legacy alias help text",
"class: a · family: pnpm floor drift, the family of #22156 item 3 (fold together, no single-point card) · reach: (1) content/docs/getting-started/your-first-project.mdx:25 says 'pnpm 8+' for a scaffolded project. Measured: pnpm@9.15.9 install on an os init scaffold gives ERR_PNPM_UNSUPPORTED_ENGINE, expected version floor 10.15. (2) examples/app-todo/README.md:101 says 'pnpm 8+' for the monorepo. Measured: pnpm@8.15.9 frozen install gives ERR_PNPM_LOCKFILE_BREAKING_CHANGE · carrier: PR #22215 (draft) edits your-first-project.mdx; app-todo README: carrier none · dedupe words: pnpm 8+ floor your-first-project app-todo README engines 10.15",
"carrier: none · noted, not filed: create-objectstack names pnpm when pnpm --version succeeds, while os init reads npm_config_user_agent, so under npx with pnpm installed the two scaffolders name different package managers. Both instructions install.",
"carrier: none · noted, not filed: the field-no-consumers headline says 'nothing in this stack reads or displays it' for a field the default (unkeyed) form draws. The rule's docblock excludes that fallback layout on purpose (crediting it would credit every visible field), so I judged it working to its contract, not a lint false positive. packages/lint not edited.",
"carrier: none · noted, not filed: the new tutorial form view was not driven in a browser (no objectui build here). That a defineView form is the create and edit surface is a reading of examples/app-crm/src/views/lead.view.ts."
]
}
Generated by Claude Code
Claim revision (file surface) for claim
6057756010·domain:devxseat 1 ·session_0115N1oNnQS5WqofZ2DzaT3q· 2026-10-08T11:44Z. Same session, same branchclaude/issue-22156-docs-onramp-drift, same PR #22280.The seat's review of PR #22280 (head
8fe75a222c) sends one patch round. Three same-class locations the developer reported are folded into this card instead of a new one, because each meets all four in-place conditions (same defect class as item 3 or 5, mechanical, no other claim, same gate family):packages/cli/src/commands/start.ts— the--portdescription (:94,overrides $PORT), the item-5 drift;os startreadsreadEnvWithDeprecation('OS_PORT', 'PORT')(:327). Declared todomain:clion [PM seat] domain:cli — ⏳ vacant #6024.content/docs/getting-started/your-first-project.mdx— the prerequisites row (:25,pnpm 8+for a scaffolded project), the item-3 drift. PR feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 edits the same file at theengines.protocolline (:138), a different hunk; whichever lands later mergesmain.examples/app-todo/README.md—:101,pnpm 8+for the monorepo, the item-3 drift.
The round also tightens one sentence the PR adds to
build-with-claude-code.mdxso its consumer list is not read as exhaustive. No other file joins the surface.
Generated by Claude Code
os-dev-report
{
"issue": 22156,
"status": "done",
"branch": "claude/issue-22156-docs-onramp-drift",
"pr": "#22280",
"session": "session_0115N1oNnQS5WqofZ2DzaT3q (mode:subagent, the dispatching PM session's id)",
"premise_still_valid": true,
"round": "patch round 1 (authority: claim surface revision 6059133597 on #22156, cross-lane addendum 6059144201 on #6024)",
"summary": "Patch round 1 adds the four changes on the same branch in commit daed4bb, then merges main at c8bb3c8 (head fae8125, pushed, PR still draft). (1) The tutorial's field-no-consumers sentence is now visibly non-exhaustive: one sentence, 'a view, a form, a flow, a formula or an action, among the others the rule counts'. (2) The start.ts --port help names OS_PORT with PORT as the legacy alias and keeps 'default 3000', which measured true. (3) The your-first-project.mdx row now says pnpm 10.15+, the floor both scaffolders write. (4) The examples/app-todo/README.md line now says pnpm 10 (corepack enable). The changeset names os start, still one patch for @objectstack/cli. The PR body item table carries all four with before and after values and measurements, and the matching Acceptance-notes lines are removed.",
"items_round1": {
"1_sentence": "build-with-claude-code.mdx: 'A field that no view, form, flow, formula or action names gets…' became 'A field that no consumer names (a view, a form, a flow, a formula or an action, among the others the rule counts) gets an advisory field-no-consumers warning from os validate.' Nothing else in the paragraph changed. Re-ran the page's examples verbatim at fae8125: 50 rules, passed, no warning.",
"2_start": "start.ts:94 'Port to listen on (overrides $PORT, default 3000)' became 'Port to listen on, default 3000 (overrides $OS_PORT; $PORT is the legacy alias)'. Measured on the CLI built at fae8125: os start --help prints the new text. Each os start ran in an empty directory inside an unshare -n private network namespace, so the shared port 3000 was untouched. No port variable gave API http://localhost:3000/, OS_PORT=41077 gave :41077, and OS_PORT=41077 with --port 41078 gave :41078. No test, snapshot or generated page pins the old string. start-port-banner-agreement.e2e.test.ts:204 quotes it in a comment only.",
"3_your_first_project": "your-first-project.mdx:25 'npm 9+ / pnpm 8+ / yarn / bun' became 'npm 9+ / pnpm 10.15+ / yarn / bun'. The value is read from source: create-objectstack/src/templates/blank/package.json engines.pnpm and init.ts SCAFFOLD_PNPM_RANGE, both 10.15. Measured: pnpm@9.15.9 install on an os init scaffold gives ERR_PNPM_UNSUPPORTED_ENGINE. npm, yarn and bun are unchanged and were not measured. The engines.protocol line is untouched.",
"4_app_todo": "examples/app-todo/README.md:101 'Node.js 22+ and pnpm 8+' became 'Node.js 22+ and pnpm 10 (corepack enable)', worded like README and examples.mdx."
},
"tests": "Head fae8125. pnpm --filter @objectstack/cli typecheck: exit 0 (check:test-typecheck OK). pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2: 265 files, 3918 tests passed, under one lock hold with VERDICT command-exit 0. The integration tier is declared to CI: the round adds a flag description only, with no spawn entry or integration-tier file. The init ablation from round 0 stands, since init.ts was not touched this round. Tutorial examples re-validated verbatim at fae8125, clean. Rebuild after the merge: pnpm install --frozen-lockfile and a turbo build of 72 tasks, VERDICT command-exit 0.",
"gates": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at fae8125 (merge base c8bb3c8, 12 paths): 95 commands, one more than round 0 (check:examples-live-imports, from examples/app-todo). All 95 exit 0. --ran reconciliation with exit codes: 95 derived, 95 run, 0 NOT-MEASURED (a derived zero). CI on the new head: not waited on.",
"line_budget": "+261 / -410 over 12 files (671 changed lines vs the 5000 human-merge threshold). Round 1 itself is +8 / -6 over 5 files. No skills/** or governed path touched.",
"files_changed": [
".changeset/22156-cli-port-help-and-init-next-steps.md",
"CONTRIBUTING.md",
"README.md",
"content/docs/getting-started/build-with-claude-code.mdx",
"content/docs/getting-started/examples.mdx",
"content/docs/getting-started/index.mdx",
"content/docs/getting-started/your-first-project.mdx",
"examples/app-todo/README.md",
"packages/cli/src/commands/dev.ts",
"packages/cli/src/commands/init-next-steps-package-manager.test.ts",
"packages/cli/src/commands/init.ts",
"packages/cli/src/commands/start.ts"
],
"deviations": [
"The round-0 worktree had been removed after the first report, so I recreated it at ../objectstack-issue-22156 from the existing local branch (same sha as origin, 8fe75a2) and removed it again at the end.",
"Merged main at c8bb3c8 (3 commits, none on this PR's files) into the branch as fae8125. Used git merge, with no rebase and no force push.",
"Measured os start's default port inside unshare -n network namespaces so the shared box's port 3000 was never bound. Every os start process was stopped by timeout, and none remains.",
"Left start-port-banner-agreement.e2e.test.ts:204, a comment quoting the old start help text. It asserts nothing and is outside the surface; noted in the PR body."
],
"mcp_calls": "0",
"api_writes": "2 this round: PATCH /repos//issues/22280 via fleet-write relay issue_patch (PR body, read-back identical 13016 bytes); POST /repos//issues/22156/comments via post-stamped (this report). Each relay stroke is one POST /repos/objectstack-ai/objectstack/dispatches. Plus git push (2 commits: daed4bb, merge fae8125), which is not REST.",
"writes": "git push x1; issue_patch x1 (no retry); report comment x1",
"open_questions": [],
"out_of_scope_findings": [
"carrier: none · noted, not filed: create-objectstack names pnpm when pnpm --version succeeds, while os init reads npm_config_user_agent, so under npx with pnpm installed the two scaffolders name different package managers. Both instructions install.",
"carrier: none · noted, not filed: the field-no-consumers headline says 'nothing in this stack reads or displays it' for a field only the default (unkeyed) form draws. The rule excludes that layout on purpose; packages/lint not edited.",
"carrier: none · noted, not filed: the new tutorial form view was not driven in a browser (no objectui build here)."
]
}
Generated by Claude Code
ACCEPT — PR #22280 (head
fae81259be) · 2026-10-08T12:31ZReviewed by
domain:devxseat 1 ·session_0115N1oNnQS5WqofZ2DzaT3q, against GitHub andorigin/main, not the report. Round 0 at8fe75a222c; patch round 1 (daed4bb9a, surface revision6059133597) added the four changes the seat asked for;fae81259bemergesmainc8bb3c8d9.Checklist: draft, base
main, first lineFixes #22156, no closing keyword beside any other number (#22204, #22215 are plain mentions). 12 files, +261/−410, all inside the revised surface. Nocontent/docs/releases/. One patch changeset for@objectstack/cli(the only published package touched;@objectstack/example-todoisprivate). Not governed (check-governed-merges --pr 22280: 0 of 12).Clause-②: noholds (help text and printed text; no accept-set or public-surface change). Every check on the head is green; the 4 skips are all in the expected-skips roster.Code read:
init.tsresolveschosenPmbefore the install branch by the same rule;detectPackageManagerreads onlynpm_config_user_agent, and every other use ofchosenPmis printed text or the install command, so nothing but the Next steps moves. The newinit-next-steps-package-manager.test.tsasserts the flag, the pnpm-agent and the npm-control cases; its ablation (old semantics restored → 2 of 3 red, control green) is in the PR body.dev.ts/start.ts--portdescriptions now nameOS_PORTfirst, matchingreadEnvWithDeprecation('OS_PORT', 'PORT')in both commands.Prose checked sentence by sentence against the diff and the tree:
CONTRIBUTING.md: every file, heading and anchor it cites exists at the head (ROADMAP, NORTH-STAR, ARCHITECTURE, CODE_OF_CONDUCT, LICENSE/LICENSING,packages/spec/scripts/build-docs.ts, README#hack-on-the-framework, Package directory / Examples; AGENTS.md Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11, Multi-agent working discipline, Context Routing, Touchedpackages/spec?, Post-Task Checklist step 3, Documentation Guardrails incl. themeta.jsonnav rule);engines.node>=22.0.0;docs:devandlintscripts; turbo^2.11.5(--affected); theneeds:pack-smokecriterion is word for word, aspack-smoke-optin.ymlcites it.README.md: the sign-in call andadmin@objectos.ai/admin123matchos dev --seed-admin(dev.ts) andyour-first-project.mdx.examples.mdx: five examples;dev:todo/dev:crm/dev:showcaseexist;#a-project-is-a-multi-package-artifactresolves; theapp-multi-packageandembed-objectqlsentences match their READMEs.index.mdx,examples.mdx,CONTRIBUTING.md,examples/app-todo/README.md: pnpm 10 (measured: pnpm 8 and 9 refuse the workspace's frozen install).your-first-project.mdx: pnpm 10.15+ =SCAFFOLD_PNPM_RANGE>=10.15and the blank template'sengines.pnpm.build-with-claude-code.mdx: the addedformblock, the paragraph (its consumer list now reads as non-exhaustive, true againstvalidate-field-consumers.ts), and the transcript'sLogic:/Security:lines measured by a verbatimos validate.
Deviations accepted: the added unit test file (inside the declared
cli/commandsdirectory);mainmerged twice bygit merge; a pinned fixture commit fetched into the shared object store with no ref.Out-of-scope findings: none filed. The developer's three notes stay as Acceptance notes (two scaffolders' different package-manager detection, both of which install; the
field-no-consumersheadline working to its documented contract; no browser check of the new form view).Landing: ready + auto-merge in this act.
Generated by Claude Code
- added 3 commits that reference this issue
on Oct 9, 2026
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