docs(quickstart): make "Add your own object" load on CLI 17.7.0

[objectstack-fleet]

Fixes #327

The quickstart's "Add your own object" did not produce an object on @objectstack/cli 17.7.0, the npm latest at dispatch. This PR rewrites that section and "Project layout" in content/docs/quickstart.mdx (the only file changed) so the page matches what 17.7.0 compiles and boots. Each claim the section now makes was measured on a 17.7.0 boot. The two claims that did not hold as written were rewritten from the measurement.

What the published section did, reproduced

All runs used a fresh os init my-app -t app --install from the 17.7.0 binary, with all 53 @objectstack/* packages at 17.7.0. Boot 1's scaffold was installed on 2026-10-15. Boot 2's was installed with npm_config_before=2026-10-15T14:00Z because the unbounded install now fails (Acceptance note 2).

Step, as published	Measured
src/objects/task.ts as written, pnpm build	exit 0, Data: 1 Objects 3 Fields; the artifact holds my_app_item only. On a running pnpm dev: GET /api/v1/data/task returns 404 OBJECT_NOT_FOUND
plus export { Task as task } from './task' in src/objects/index.ts	exit 2: Object 'task' is missing the package namespace prefix. Rename it to 'my_app_task' (namespace = 'my_app').
renamed to my_app_task, no sharingModel	exit 1, rule security-owd-unset: custom object "my_app_task" declares no sharingModel (OWD)
plus sharingModel: 'private'	exit 0, Data: 2 Objects 7 Fields

The PM's unverified premise holds. Without sharingModel the compile refuses the object, so the corrected sample declares it.

There was also no file to "edit". The 17.7.0 scaffold ships src/objects/my_app_item.object.ts and no task.ts. objectstack generate object task writes src/objects/task.object.ts and the barrel line export { default as task } from './task.object';, and the sample now uses the same file name and barrel line.

The corrected section, followed literally

The blocks were extracted byte for byte from this PR's quickstart.mdx (cmp equal) and applied to a running pnpm dev on a fresh scaffold:

• Creating task.object.ts on its own: the dev server recompiles and restarts, and the endpoint still answers 404, because the barrel does not export the file yet.
• Adding the barrel line: the dev server prints ✚ new object(s): my_app_task — table & seeds sync on restart, then ✓ server restarted — the new build is live.
• pnpm build then reports Data: 2 Objects 7 Fields, and pnpm validate passes.
• The page's curl block, run verbatim, exits 0: sign-in 200, create 201, list 200.
• Without a session the endpoint answers 401 UNAUTHENTICATED. The bullet now says so and the page shows the sign-in.

How each bullet was measured, and what changed:

Bullet	Measured on the 17.7.0 boot	Change
/api/v1/data/my_app_task, full CRUD with filter, sort and paginate	POST 201, GET by id 200, PATCH 200, DELETE 200. where, orderBy, limit and offset filter, sort and page as asked	path renamed; links the REST API reference
A "Task" view: list, form, detail	List, New form (Subject, Done, Due, Assignee) and record page all render. The scaffold declares no app (UI: 0 Apps), so nothing links to them. They are reached at /_console/apps/setup/my_app_task. App-neutral spellings tried (/_console/my_app_task, /objects/…, /object/…, /data/…) redirect to home	names the URL and why nothing links to it
Permission rows in Setup, per role	Setup → Permission Sets → a set → Design in Studio shows a Task (my_app_task) row with C/R/U/D toggles, in 3 of 3 sets opened (member_default, viewer_readonly, admin_full_access). The grants are per permission set. The Setup sidebar has no Roles entry	"per role" becomes "for that set", with the click path
Audit log entries	sys_audit_log holds create, update and delete rows for my_app_task (boot 1: 3/1/1; boot 2: 2/1/1). Setup → Audit Logs lists them in the Console	kept, with where to find them
"No migrations. No code generation. No restarting."	The table appears without a migration step. The server restarts itself (↻ restarting server to apply the new build)	replaced by the measured sentence

Changes besides the four bullets

• Namespace rule. The page now gives the rule in the CLI's own words: Every object.name must be `${manifest.namespace}_${shortName}`., together with the refusal's Rename it to 'my_app_task'.
• Failed-recompile hint. One sentence: if the dev server prints only ✗ compile failed, run pnpm build to see why. Measured on 2 of 2 boots: the dev watcher prints only ✗ compile failed (2702ms) (and (2497ms) on the second boot) with no reason, while pnpm build on the same tree prints the refusal and exits 2. The upstream defect is listed under Acceptance notes.
• Barrel line shown inline. The barrel line is inline code, not a ts block. The doc-samples gate evaluates every ts block as statements and refused a bare re-export (FAIL quickstart.mdx:269 — evaluate as published: Unexpected token 'export').
• Project layout. The tree now lists the 17.7.0 scaffold's eight barrels: actions, apps, dashboards, flows, objects, picklists, skills and views. It also lists pnpm-workspace.yaml and .objectstack/, the directory pnpm dev creates for the local SQLite databases. A note names what the tree leaves out: .gitignore and the installer's lockfile (package-lock.json when the scaffold is created through npx).

The section's boot banners were not re-transcribed (objectos#141 is on hold). apps/docs/lib/positioning.ts was not touched. The page has no locale siblings.

Verification on head 8cf78f7

Every exit code was captured before any pipe. The heavy runs went through the shared verify lock with --force (0 cached).

Gate	Exit	Verdict
pnpm turbo run type-check --continue --force	0	1 successful, 0 cached
pnpm turbo run build --force	0	1 successful, 0 cached
pnpm turbo run test --force	0	✓ 11 self-test(s) passed
node .github/scripts/check-doc-samples.mjs	0	98 pass · 10 not a spec sample · 2 opted out (quickstart.mdx:244 PASS)
node apps/docs/scripts/gen-zh-hant.mjs --check	0	54 generated files match
node .github/scripts/check-locale-surface.mjs	0	✓
node .github/scripts/check-positioning.mjs	0	✓
node .github/scripts/check-search-locales.mjs	0	✓ all 8 locales
node .github/scripts/check-translations.mjs	0	✓ translations gate passed
check-translation-output.mjs --self-test / --files	0 / 0	✓ / ✓ (213 pre-existing reported)
check-translation-ownership.mjs --files (M content/docs/quickstart.mdx)	0	0 translation artifacts, 1 other file

Other checks on the same head:

• A control-byte scan of quickstart.mdx found nothing (grep exit 1).
• The built en/docs/quickstart.html contains my_app_task 16 times and Every object.name must be 2 times. It contains no per role, no No code generation and no name: 'task'.
• The page was served with next start and rendered in Chromium at 1300 px and 390 px: no page errors and 0 px of horizontal page overflow.

No ablation applies: this is a docs change with no code under test.

Acceptance notes

Two upstream defects found while measuring. Neither is fixed here:

1. The dev watcher drops the compile refusal's reason. objectstack dev prints only ✗ compile failed (…ms). objectstack compile writes its refusal to stdout: measured, 10 stdout lines including the refusal, 0 stderr bytes. The watcher spawns the compile with stdout ignored (objectstack 54770208 packages/cli/src/commands/dev.ts:931-938, read from source). Main's print path for this refusal was not measured. The fix lands in objectstack.
2. The Path B install fails today with npm. os init my-app -t app --install (npm, which the CLI auto-picks under npx) fails 3 of 3 times with npm error Cannot read properties of null (reading 'edgesOut'), and the CLI exits 2. That includes a run with an empty npm cache; npm is 10.9.4.
   • Bounded with npm_config_before, the install succeeds 2 of 2 times: at 2026-10-15T14:00Z and at 14:40Z.
   • The trigger is a publish after 14:40Z. That is consistent with vitest 4.1.12 (14:51Z), the newest match for @objectstack/metadata-core 17.7.0's optional peer vitest ^4.0.0, but it was not isolated further.
   • This hits the page's first Path B command. That command sits outside this card's two sections, so the page is not changed for it.

Observations, not filed:

• The scaffold's .gitignore (node_modules/, dist/, *.tsbuildinfo) does not ignore .objectstack/, where pnpm dev writes its SQLite databases. objectstack main writes the same file (init.ts:1309).
• The quickstart's "What's running" table says Setup holds "users, roles, …". The 17.7.0 Setup sidebar lists Positions and Permission Sets, and no Roles entry. That table is outside this card's sections.
• The doc-samples gate cannot judge a barrel re-export written as a ts block, so this page states the barrel line inline.

No owner has been named for these: 承接者:无.

---

Generated by Claude Code

[objectstack-fleet]

席位核对

ACCEPT: PR #336 for #327 · 2026-10-16T05:17Z · seat repo:objectos, session session_01CXCwzqwMhkphKoBC11oPSz. Implemented-by: os-dev subagent, branch claude/issue-327-quickstart-own-object. Reviewed-by: this seat.

Shape.

• Draft, base main (76988da), head 8cf78f7, mergeable_state: clean, assignee os-tesla.
• The first line is Fixes #327. A full-body scan finds no other closing keyword.
• One file, content/docs/quickstart.mdx, +62/−14, inside the claim's surface. The page has no locale siblings. No governed path is touched.

Checks pinned to 8cf78f7: build success (every step, including docs samples, the size budget and the rendered-page smoke check), Node floor success, Ownership & freshness success. Deploy docs skipped (PR event).

Card criteria, read against the diff and the dev's measurements on @objectstack/cli 17.7.0 (two fresh scaffolds, the page's blocks applied verbatim):

• Following the page yields a loaded object.
  • The page now creates src/objects/task.object.ts named my_app_task with sharingModel: 'private', and adds the barrel line.
  • Measured: the compile counts it (Data: 2 Objects 7 Fields). After restarting, the server answers GET /api/v1/data/my_app_task with 200, and 401 without a session. The page's curl block ran verbatim with exit 0.
  • The seat's unverified sharingModel premise held: without it the build exits 1 (security-owd-unset).
• The namespace rule is stated the way the CLI states it, quoted from the refusal.
• The bullets were measured or rewritten, none carried forward:
  • the generated list, form and record page at /_console/apps/setup/my_app_task;
  • the Task row in the permission-set designer;
  • the audit rows for create, update and delete;
  • "no restart to run" became "restarts itself", as measured.
• Project layout matches the 17.7.0 scaffold: the eight barrels, .objectstack/ and pnpm-workspace.yaml.

Out-of-scope findings — two class: a findings land in objectstack, and the seat routes them there:

• the pnpm dev watcher prints ✗ compile failed with no reason;
• npx @objectstack/cli init … --install currently fails for every new install with npm's edgesOut error, because of a newly published optional peer.

The rest are Acceptance notes.

Landing. Non-governed and well under the size line. The seat marks the PR ready. ❗ Merging to main publishes production, and the merge is a human's. #141, on hold over the same file, re-arms on the next CLI publish as recorded.

---

Generated by Claude Code