docs audit (1/2) — the first-run path: index, build-without-code, getting-started/, concepts/, data-modeling/

[os-elon]

Continues the new-developer journey audit (#10264), which covered the README and the running product but could not reach the docs site. The site is served from this repo, so the audit is content/docs/**.

Scope — exactly these, nothing else

content/docs/index.mdx, content/docs/build-without-code.mdx, content/docs/getting-started/**, content/docs/concepts/**, content/docs/data-modeling/** (~33 pages).

Explicitly out of scope, do not touch or audit:

• content/docs/references/** — 214 auto-generated pages (⚠️ AUTO-GENERATED — DO NOT EDIT, produced by packages/spec/scripts/build-docs.ts). A defect there is a generator bug; file it against the generator, do not hand-edit.
• content/docs/releases/** — written centrally at release time. Never edit in a code PR.
• Everything covered by card 2/2 (ui/, automation/, permissions/, ai/).

Already machine-covered — do not re-derive

These gates were run on origin/main before dispatch:

Gate	Result
check:doc-authoring	✓ 380 files clean, no bare metadata literals
check:docs-redirects	✓ 92 entries, all destinations resolve
check:doc-anchors	exists and runs in CI (needs node_modules locally)

So anchors, redirect integrity and metadata literals are the machine's job. Spend nothing on them. Your job is what no gate can see.

Method — cheap checks first, prose reasoning last

This ordering is the point of the card; inverting it burns budget for little yield.

1. Mechanically falsifiable claims first. Every identifier a doc names — a field type, a schema property, a method, a CLI flag, an option key — either exists in packages/spec / the implementing package or it does not. That is a grep, not a reading exercise. Sweep the identifiers out of the code fences and check them in bulk against source. Docs that name things which no longer exist are the highest-yield, cheapest defect class in this tree.
2. Runnable claims second. Commands and code samples a reader is invited to run. Run the cheap ones. Note that node_modules is absent in a fresh clone — if a documented first command requires an install the doc never mentions, that itself is a finding.
3. Pedagogical holes last, and only on the first-run path. Read as a stranger following the path in order: does each page's prerequisite actually get established by an earlier page, or is the reader assumed to know something nobody told them? dogfood: simulate a brand-new developer's first-run journey — README → create an app → skills-driven AI build → validate & test #10264 found exactly this shape in the product — the rule a newcomer needed existed only in a file they had no reason to open.

Deliverable

Audit-only. Do not open a PR and do not edit any doc. File one finding issue per distinct defect, unassigned, finding label only — no domain and no type label, those are the triage seat's product. Dedupe-search before each one. Back-link this issue.

If the hit rate is high, say so plainly in your report: whether the remaining 88 unaudited pages are worth a second round is a decision that rests on your measured rate, and an honest low rate is as useful as a high one.

Report as a comment here: pages audited, defects found by class (nonexistent identifier / broken command / pedagogical hole), findings filed with numbers, and your hit rate per page.

[os-elon]

Claim: PM loop round 2
Session: session_01NxN6g5ZUisyybeP9ngcC4Z
Branch: n/a — audit card, no PR expected
Worktree: n/a — read-only audit, no edits to any file
Domain: domain:devx
File surface: reads content/docs/{index.mdx,build-without-code.mdx,getting-started,concepts,data-modeling} and packages/** source for verification; writes nothing (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — subagent rather than cloud deliberately: the cloud dev on #10264 could not file its findings for lack of GitHub write access, and a subagent in the PM container inherits this session's working GitHub connection. Judgment tier opus: the pedagogical half is judgment, and the mechanical half is cheap either way.
Clause-②: no
Serial constraints cleared: disjoint by construction from #10564 — the two cards partition content/docs/** with no shared page, and neither writes.

---

Generated by Claude Code

[os-elon]

os-dev-report — see terminal report (posting deferred, rate limit probe)

---

Generated by Claude Code

[os-elon]

os-dev-report

Audit complete. Findings are NOT filed as issues — the shared GitHub identity's API read quota is exhausted (search_issues, list_issues and issue_read all return "API rate limit already exceeded for user ID 318303764"; the write path still works, which is how this comment posted). Ruling 3 requires a dedupe-search before every finding, and filing 12 issues blind into a repo where parallel agents file constantly is the wrong trade. Every finding is written out below in filing-ready form; drafted bodies are on disk in the PM container at /tmp/claude-0/-home-user-objectstack/00f1a0a5-e483-51b5-acba-ee4926b4a1ba/scratchpad/issue-10563/F1.md … F12.md.

(Please ignore the placeholder comment immediately above this one — it was a rate-limit probe on the write path.)

---

Headline: the PM mechanism assumption is measurably wrong for this tree

"The cheapest high-yield defect class is identifiers the docs name that no longer exist in source. This is bulk grep, not reading."

I ran that sweep exhaustively. It yielded one hit out of roughly 350 identifier checks.

Mechanical sweep	Result
Internal /docs/ links resolve to a file	182 / 182 ✓
ADR-nnnn references resolve under docs/adr/	33 / 33 ✓
OS_* environment variables exist in packages/**	12 / 12 ✓
ERR_* codes exist	1 / 1 ✓
Query operators ($eq … $searchFields) exist in spec + objectql	24 / 24 ✓
define* factories exist and are exported	10 / 10 ✓
Symbols imported from @objectstack/* exist at the named subpath	42 / 42 ✓
@objectstack/* package names exist	9 / 9 ✓
CEL functions named in formulas.mdx vs packages/formula/src/stdlib.ts	all present ✓
field-types.mdx covers every member of the FieldType enum	49 / 49 ✓
Documented os / objectstack invocations map to real commands	20 / 20 ✓
sys_* object names	17 checked, 1 apparent miss — verified as an illustrative sample, false positive
I*Service contracts	5 checked, 1 real miss → F5
Retired-key sweep (60 surfaces from migrations/entries/semantic/) vs docs	2 hits → F3, F6
MongoDB / SQL driver config keys in drivers.mdx	all verified ✓
north-star.mdx + design-principles.mdx paths and symbols	all resolve ✓

The real yield came from a class the assumption did not name: contract drift the type-checker structurally cannot see. Nine of twelve findings are of that shape — a key that is .optional() in Zod but an error in the author-time lint, a stored-value shape, a retired key still spelled in prose, a behaviour claim, a completeness claim. grep finds none of them; they need the schema read next to the doc.

One structural cause explains most of it: only 57 of 237 TypeScript fences in this tree (24%) carry the {/* os:check */} marker, so 76% are compiled by nothing. And the marker is weaker than it looks — the single worst finding (F11) sits inside an os:check block, because the omitted key is .optional() and therefore type-checks clean.

Page	os:check / total ts fences
data-modeling/field-types.mdx	0 / 50
data-modeling/seed-data.mdx	0 / 13
data-modeling/drivers.mdx	0 / 11
concepts/metadata-driven.mdx	5 / 18
data-modeling/formulas.mdx	2 / 16
data-modeling/fields.mdx	1 / 15
data-modeling/queries.mdx	8 / 25
all in-scope pages	57 / 237

---

Findings

F11 — 22 object examples across 12 pages omit sharingModel, which os validate errors on ← highest value

packages/lint/src/validate-security-posture.ts:266-281 raises severity: 'error', rule security-owd-unset, for any custom (non-sys_) object declaring no sharingModel.

Sharpest instance: data-modeling/index.mdx:14-30 introduces its snippet as "A real object definition looks like this (from the CRM example app)" and reproduces crm_lead minus the key. The real file examples/app-crm/src/objects/lead.object.ts:12 declares sharingModel: 'public_read_write'. All 7 example objects in examples/ declare it; none of these 22 doc snippets does.

Why no gate caught it: that snippet is os:check-marked, but sharingModel is z.enum([...]).optional() with no .default() (deliberately — see validate-sharing-rule-enforceability.ts:223-227), so the omission type-checks. The rule that rejects it is an author-time lint run by os validate, and no docs gate runs os validate over fenced blocks.

Sites: examples.mdx:128 · architecture.mdx:96,402 · metadata-driven.mdx:80,244,342,388,464,487 · schema-design.mdx:21,285,404 · fields.mdx:18 · seed-data.mdx:247 · validation.mdx:27 · objects.mdx:16,365 · formulas.mdx:94 · external-datasources.mdx:73,253 · data-modeling/index.mdx:16 · drivers.mdx:906. (Two of these are deliberate ❌ counter-examples in metadata-driven.mdx; the rest are presented as correct, several under an explicit ✅ heading.)

The contrast is the point: the three first-run pages a newcomer copies from all declare it, and quick-start.mdx:96 even states "The validation gate rejects custom objects that omit it." Taught on the first-run path, contradicted by every reference page downstream. This is the #10264 shape.

F4 — the monorepo Quick Run omits the required pnpm build (broken command, measured)

examples.mdx:51-56 says git clone → cd → pnpm install → pnpm dev:showcase. Measured on this fresh clone:

$ node scripts/check-dev-prereqs.mjs ; echo "EXIT=$?"
✗ The workspace is not built — 1 unmet precondition, not a list of problems.
 67 of 67 workspace packages declare an entry point under dist/ that is not on disk:
 Fix:
 pnpm install && pnpm build
EXIT=1

Nothing supplies it implicitly: root package.json has no postinstall; prepare is setup-git-hooks.mjs only. The repo's own README.md:210-212 documents the correct three-step sequence, so the docs site contradicts the README on the very first command a newcomer runs.

The "Standalone" tabs are worse and bypass the gate (it guards only the root dev:* scripts): examples.mdx:107-109 and :283-285 run objectstack dev against an unbuilt workspace, producing exactly the misleading cascade check-dev-prereqs.mjs was written to prevent (its docblock cites #5726: a datasource: connect failed whose two suggested fixes are both wrong, then 20+ TS errors that are pure stale-dist artefact). The second pnpm install block at :256-259 is fine — that one is the external hotcrm repo.

This is the card's "documented first command silently requires an install the doc never mentions" premise, confirmed — with build rather than install as the missing step.

F5 — IGraphQLService names a contract that no longer exists

getting-started/index.mdx:99 and :133 — "GraphQL is exposed via the IGraphQLService contract". The symbol exists nowhere in packages/**; only in CHANGELOG history. The capability went with it: packages/runtime/src/http-dispatcher.ts:2026 — // /graphql removed — GraphQL is not in the product plan (#2462 follow-on); packages/spec/src/system/core-services.zod.ts:130-135 records the entry's deletion in #4451 (v17). No handleGraphQL in the dispatcher; only stale test doubles in packages/adapters/hono/src/__mocks__/runtime.ts.

Lands on the second page of the first-run path, in the "Real-World Benefits" table an evaluator reads. Same family, in-scope: // Expose via REST/GraphQL as the gloss on enable.apiEnabled at metadata-driven.mdx:474, schema-design.mdx:65, objects.mdx:82 — the schema's own .describe() says only "Expose object via automatic APIs". Out of this card's scope but same fix: content/docs/api/index.mdx:19 carries the identical stale claim.

F1 — location stored value documented as {latitude, longitude}; it is {lat, lng}

field-types.mdx:533 and validation-rules.mdx:373. The enforced contract is LocationValueSchema (packages/spec/src/data/field-value.zod.ts:251-256), routed by valueSchemaFor at line 437. The shape the docs print is the deprecated LocationCoordinatesSchema, whose own docblock (field.zod.ts:222-229) says: "Never consumed by the runtime, and its key names contradict what the platform actually stores: a location value is {lat, lng} … not {latitude, longitude}." An author following either page writes keys that fail validation. (The neighbouring address shape on both pages is correct.)

F3 — retired index key partial presented as live

validation.mdx:13 (prose) and :135 (inside the uniqueness code sample: // partial expresses a scoped/conditional constraint). type and partial were retired at protocol 17 (#5248, #4943, ADR-0049); IndexSchema (object.zod.ts:377-397) is a strictObject declaring exactly name/fields/unique, so authoring partial is now a rejection with guidance. The sibling page objects.mdx:225-237 documents the retirement correctly — validation.mdx is the page that did not track it. Same page, adjacent: the frontmatter still advertises "uniqueness" while the body at :126 says "There is no uniqueness validation type."

F6 — data-modeling/index.mdx:41 advertises retired joins and windowFunctions

The landing page sells the query AST as compiling "with joins, aggregations, window functions, HAVING, and subqueries". Both were retired in protocol 17 (#4286, ADR-0049) and are tombstoned — authoring joins is a tsc error and even joins: [] fails to parse. The module's own child page documents both removals under the headings "Joins — removed" (queries.mdx:432-441) and "Window Functions — removed from the request surface" (queries.mdx:566-575). HAVING is fine (query.zod.ts:548).

F12 — validation-rules.mdx claims "each field type", covers 44 of 49

Missing sections: secret, user, composite, repeater, record. field-types.mdx has all 49, so the drift is one-sided. secret is the least guessable omission (fail-closed, writes throw with no ICryptoProvider, ciphertext in sys_secret, masked on read).

Triage note: this one page carries three of the twelve findings (F1b, F2, F12) while the page it duplicates carries one. validation-rules.mdx and field-types.mdx document overlapping ground and sit adjacent in meta.json. Whether to complete this page or fold it into field-types.mdx is a maintainer call — but patching the five gaps without deciding leaves the duplication that produced them.

F8 — "unknown keys are stripped by the schema" — they are rejected

field-types.mdx:317 and :339. FieldSchema is a strictObject (field.zod.ts:663) and referenceFilters has a hand-written tombstone carrying the upgrade (field.zod.ts:721-723). strictObject's docblock names this as its whole purpose: "the difference between a silent strip and a fixable error." Telling a reader their typo vanishes quietly is the pre-#4001 behaviour and the exact failure mode ADR-0078 exists to delete. validation-rules.mdx:245 and relationships.mdx:39 carry the same retirement without the wrong claim.

F2 — currency documented as "Stored as { value, currency } pair"

validation-rules.mdx:147. It is a bare number — NUMERIC_VALUE_TYPES (field-value.zod.ts:52-55) includes currency with the explicit comment "currency IS a bare number", and valueSchemaFor returns z.number().finite(). The per-record currency code is currencyConfig, documented correctly two rows above. field-types.mdx makes no stored-shape claim and is unaffected.

F9 — apiMethods sample says "six primitives only" and lists five

schema-design.mdx:71-77 omits bulk. ApiMethod (object.zod.ts:18-22) is get/list/create/update/delete/bulk. A whitelist is exact, so a reader copying this sample silently denies batch operations while believing they enumerated everything. objects.mdx:96 has it right.

F7 — "Four database drivers in this repo"; there are five

data-modeling/index.mdx:44 omits @objectstack/driver-turso (v17.1.0, public, packages/drivers/driver-turso). Not a shorthand: drivers.mdx documents Turso as a first-class URL-inferred driver (libsql://, *.turso.io, inferred by os serve/start/dev and createStandaloneStack), optional only in the sense that the package is not installed by default. A reader who stops at the landing page never learns Turso is supported.

F10 — drifted count in "Why it's fast"

how-ai-development-works.mdx:31 — "1,792 lines across 31 files". Measured: 1,930 lines, 31 files (file count and "six objects" both exact). +7.7% drift. Low severity, but it is load-bearing in the page's own argument, and nothing guards it — check:quick-reference-counts covers quick-reference.mdx and has no equivalent here.

---

Recorded, deliberately NOT filed

• SeedMode.replace docblock is stale in source. packages/spec/src/data/seed.zod.ts:16 says "Delete ALL records in object then insert". The loader does not delete — packages/metadata-protocol/src/seed-loader.ts:1763-1766: "Replace mode: just insert (caller should have cleared the table)". seed-data.mdx documents this correctly; the source comment is the wrong one. Out of content/docs/** scope (ruling 2), and the doc is right, so nothing to fix on this card.
• packages/spec/src/index.ts:23,32 documents @objectstack/spec/auth as an import path in two JSDoc examples. There is no ./auth export — the subpaths are ./identity and ./security. Source file, out of scope.
• quick-start.mdx:124-137 presents one src/ layout as navigating "any ObjectStack project". app-showcase — the repo's kitchen-sink reference and the target of pnpm dev — uses src/{automation,data,docs,security,system,ui} instead. Rhetorical overreach rather than a factual identifier defect; not padding the list with it.
• packages/cli/src/commands/dev.ts:76 describes --port as overriding $PORT, while getting-started/index.mdx:189-194 correctly says OS_PORT with PORT as the legacy alias (matching readEnvWithDeprecation('OS_PORT', 'PORT') at dev.ts:357). Source-side, out of scope.
• MetadataHmrReloader (metadata-lifecycle.mdx, 5 mentions) and the debounceMs: 400 figure live in the objectui console app, not this repo. Unverifiable from here — not counted as a miss.

Verified clean (worth recording, so a second round is not re-spent here)

indexing.mdx (no retired type/partial) · drivers.mdx config keys (MongoDB pool/timeout keys, sqliteJournalMode, OS_DATABASE_SQLITE_JOURNAL_MODE, all five driver packages) · queries.mdx (all operators; both retirement callouts accurate; findWithWindowFunctions confirmed on SqlDriver) · formulas.mdx (CEL stdlib) · seed-data.mdx (SeedMode enum, two-arg defineSeed signature, subpath) · analytics.mdx (dataset/report shapes incl. order: [{by, direction}], runtimeFilter) · field-type-decision-tree.mdx · glossary.mdx · quick-reference.mdx · north-star.mdx · design-principles.mdx · build-without-code.mdx · your-first-project.mdx (matches the real blank template file-for-file) · build-with-claude-code.mdx (os dev --ui, dev-admin credentials, template scripts all verified) · external-datasources.mdx (DatasourceConnectPolicy / publicReason accurate) · relationships.mdx · metadata-lifecycle.mdx (MetadataRepository.put, metadata-change SSE).

First-run ordering (the pedagogical question)

Walked getting-started/meta.json order as a stranger: index → how-ai-development-works → build-with-claude-code → your-first-project → quick-start → examples. Pages 1-5 are prerequisite-clean — each establishes what it needs or links to the page that does; the two scaffolding pages each carry their own prerequisites table; quick-start assumes a project but links up to the page that creates one.

The chain breaks at page 6. examples.mdx is the first page that assumes a framework monorepo checkout rather than a scaffolded project, and it is exactly where the missing pnpm build sits (F4) — the ordering hole and the broken command are the same defect.

Hit rate per page

Measure	Value
Pages in scope	33 .mdx (+3 meta.json, read for nav ordering)
Pages audited	33 / 33 mechanically; 14 read with narrative attention
Distinct defects	12
Pages with a defect unique to that page	8 / 33 = 24%
Pages carrying any defect instance (incl. the systemic F11)	16 / 33 = 48%
Defect instances (F11 counted per site)	33
Defects per page	0.36 distinct · 1.0 instances

By class: nonexistent identifier 1 (F5) · retired-key-still-documented 2 (F3, F6) · wrong contract / stored shape 3 (F1, F2, F8) · broken command 1 (F4) · false completeness claim 3 (F7, F9, F12) · drifted count 1 (F10) · pedagogical hole 1 systemic (F11).

Is a second round on the remaining 88 pages worth it?

Yes, but scope it differently. 24% of pages carrying a page-specific defect is a real rate — but a round scoped as "sweep identifiers with grep" would have returned one finding from these 33 pages and read as a clean tree. The next round should be scoped to the classes that actually paid:

1. Every os:check-marked block that constructs metadata, re-checked against the author-time lints, not just tsc. F11 proves the marker's blind spot is exactly the .optional()-in-Zod / error-in-lint gap. Mechanizable: run os validate over os:check blocks. That closes the class instead of the instances, and it is the single highest-leverage follow-up from this audit.
2. The 76% of fences with no marker, on the pages where they cluster.
3. Sibling pages that document overlapping ground — the field-types.mdx / validation-rules.mdx pair produced 4 of 12 findings on its own. Look for the same pattern in ui/ and automation/.
4. Stored-value and retired-key claims in prose, which no fence gate reaches at all.

An identifier-only sweep of the remaining 88 pages is not worth a round on this evidence.

Deviations

1. No issues filed. GitHub API reads (search_issues, list_issues, issue_read) are rate-limited on the shared identity os-elon; ruling 3 mandates a dedupe-search before each finding, and filing blind was the worse trade. Bodies are drafted at scratchpad/issue-10563/F1.md…F12.md and reproduced above.
2. One stray placeholder comment on this issue, immediately above — a write-path probe during the rate-limit window.
3. Read-only throughout, as ruled. No worktree, no branch, no file edited, no PR. git status clean.
4. node_modules never installed and no build run — the fresh-clone state was itself the instrument for F4. No shared verify-lock was taken; the only command executed was node scripts/check-dev-prereqs.mjs (single-file, no deps).

Generated by Claude Code

---

Generated by Claude Code