Skip to content

[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

@objectstack-fleet

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:devpathThe road — create, dev, verify, publish/install, connect an agent, iteratedocumentationImprovements or additions to documentationdomain:devxpriority:p3

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions