docs audit (2/2) — the build-an-app path: ui/, automation/, permissions/, ai/

[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/ui/**, content/docs/automation/**, content/docs/permissions/**, content/docs/ai/** (~50 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 1/2 (index.mdx, build-without-code.mdx, getting-started/, concepts/, data-modeling/).

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 naming things that no longer exist is the highest-yield, cheapest defect class here — and this slice is where retirements bite hardest, because ui, automation and permissions have all had properties removed under enforce-or-remove.
2. Runnable claims second. Commands and code samples a reader is invited to run.
3. Pedagogical holes last. Read as a stranger who has just modelled their first object and now wants a view, a flow, an action and a permission posture.

Two known holes to check specifically

Both were measured in #10264 against the product and the skills bundle. Establish whether the docs have the same holes, or whether the docs already cover what the skills missed — either answer is directly useful:

• Assigning a permission set to a user ([finding] Authoring a permission set is well documented; assigning one to a user is documented nowhere in the skills bundle, and the object is hidden from MCP too #10318). Absent from all 11 skills; the object is sys_user_permission_set and it is not exposed over MCP. Do the permissions docs document assignment, or do they also stop at authoring?
• An object is not navigable without an App ([finding] The blank template ships no app, so the Console renders nothing the scaffolder wrote — the README promises the opposite #10317). The blank template ships no app, so a scaffolded object renders nowhere. Do the ui/ docs state that an App is required, and would a reader following them in order learn it before they hit the empty Console?

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 (#10317 and #10318 already exist — add to them rather than filing twins). Back-link this issue.

Report as a comment here: pages audited, defects found by class, findings filed with numbers, hit rate per page, and a direct answer on the two known holes above.

[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/{ui,automation,permissions,ai} 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 #10563 — the two cards partition content/docs/** with no shared page, and neither writes.

---

Generated by Claude Code

[os-elon]

os-dev-report

Audit report — card 2/2, the build-an-app path

50 pages / 15,307 lines across content/docs/{ui,automation,permissions,ai}, all four directories swept mechanically, narrative attention spent only where a mechanical pass flagged something or on the two known holes.

Directory	Pages	Lines	Defects
ui/	14	3,903	3
automation/	8	4,358	0
permissions/	20	5,284	0
ai/	8	1,762	0
Total	50	15,307	3

Hit rate: 3 defects / 50 pages = 0.06 per page. All three are in ui/, at 0.21 per page there; automation/, permissions/ and ai/ returned zero across 11,404 lines.

---

The PM mechanical assumption is FALSIFIED — independently of card 1/2

The card predicted "identifiers the docs name that no longer exist in source" would be the cheapest high-yield class, and that this slice would be the richest for it because ui, automation and permissions have all had properties removed under enforce-or-remove. It returned zero. My measurement, arrived at before the PM relayed the sibling's:

Oracle	Checked	Not found in source
Authored top-level keys vs their packages/spec type	64 / 64 authoring call sites	0
Doc-authored keys vs the whole 8,049-key authorable surface	151 distinct candidate keys	0
Tombstoned ([RETIRED]) keys shown as authorable	134 retired keys grepped	0
REST endpoints named in prose	96	0
sys_* object names	46	0
defineX authoring entry points	16	0
defineStack registration keys	20	0

The retirement result is the striking one. Every retired key this slice mentions is mentioned correctly, as a tombstone with its replacement — apps.mdx:59-71 on version / mobileNavigation / homePageId, views.mdx:264 and actions.mdx:222 on action.bulkEnabled, flows.mdx:1113 on retryDelayMs becoming backoffMs. The docs are not lagging the retirements; they are documenting them.

The two false positives my type-aware pass threw (Tasks: and Responsibilities: inside template literals in agents.mdx) were the only other flags. A round scoped as a bulk grep would have called this tree clean.

Where the yield actually was

Confirming the PM's re-aim: all three defects are contract drift a type-checker structurally cannot see, and all three sit in unmarked fences. Only 60 of 204 TypeScript fences in this slice (29%) carry an os:check marker; every defect is in the unmarked 71%.

Per-page marker coverage, worst first: flows.mdx 4/34 · authentication.mdx 9/28 · apps.mdx 4/16 · views.mdx 4/11 · forms.mdx 4/9 · actions.mdx 0/4 · approvals.mdx 0/5 · hooks.mdx 0/5.

Filed

#10578 — actions.mdx puts rowActions/bulkActions at the defineView CONTAINER top level. ViewSchema is a strictObject (view.zod.ts:2741) whose keys are name/label/object/list/form/listViews/formViews/protection; these two are ObjectListView keys and belong one level down. The module contradicts itself — views.mdx:70-76 ships a warn-Callout against exactly this shape. The schema's guidance remedy map is keyed on type/columns/data/viewKind/filters/sort and does not cover these two, so the author gets a bare unknown-key rejection with no "wrap it in list:" prescription.

#10579 — three of five form-section examples omit name. component.zod.ts:825 states the consequence itself: "a nameless section renders its authored label in every locale". views.mdx:53, create-vs-edit-form.mdx:82 and public-data-collection.mdx:24 omit it; create-vs-edit-form.mdx:69-72 and field-grouping-and-order.mdx:61-62 include it. translations.mdx:73 is the only page revealing the coupling, and states it as a key path rather than a requirement. Exactly the "sibling pages covering overlapping ground and drifting apart" shape.

Held deliberately, to avoid twinning card 1/2

content/docs/ui/field-grouping-and-order.mdx:36-52 — ObjectSchema.create({ name: 'showcase_contact', ... }), a custom object with no sharingModel. authorization.mdx:437-439 states the rule in this very slice: "an object publish with no authored sharingModel is refused" (security-owd-unset, "at the CLI and at the runtime door alike"). It is inside an os:check fence and passes, because sharingModel is .optional() in Zod — the PM's stated reason this class is gate-invisible.

This is one instance of the class card 1/2 measured at 22 instances across 12 pages. Filing it separately would create a near-twin of whatever #10563 files. Recommend folding this line into card 1/2's sharingModel issue rather than opening a third card. It is the only instance in my slice: only two real ObjectSchema.create examples exist here, and the other (sharing-rules.mdx:20-22) declares sharingModel: 'private' correctly.

Classes checked that came back clean

• False completeness claims — every countable claim verified true: "six gates" (6 table rows), "five stages" (5 rows), "Five keys are declared" for DashboardWidgetOptions (spec has exactly dateGranularity/limit/sortBy/sortOrder/stageOrder), "five concepts" in permissions/index.mdx, "11 skills" (the bundle ships 11, and all 11 are named correctly in skills-reference.mdx).
• Flow author-time lints — no flow-double-brace-interpolation or flow-bare-dollar-reference violations. The {{...}} uses in ui/ are forms/actions interpolation where that syntax is correct, and the $ uses in flows.mdx are the documented flow $ namespace.
• Runnable claims — 96 REST endpoints, all resolve.

---

The two known holes — direct answers

#10317 (an object is not navigable without an App) — the docs SHARE the hole

No page in content/docs/ui/** states that an App is required. Grepped every phrasing (without an app, navigab*, renders nowhere, empty console, no app, unreachable, …): three hits, none of them this claim. The nearest are descriptive only — ui/index.mdx:10 "An app is a navigation shell over your objects", apps.mdx:8 "a logical container that bundles…".

The sharper half I did not expect: apps.mdx is 686 lines and never shows defineStack({ apps: [...] }). Its Complete Example ends at the defineApp closing brace (apps.mdx:677). views.mdx:60-68 does the opposite for views — shows the registration and follows it with a warn-Callout naming the failure mode. The module knows the pattern; it applies it to views and not to apps.

Reading in order does not rescue it: meta.json puts apps second, so a reader meets the concept — but nothing says it is required, and views.mdx:22 says "Default list shown when the object is opened" without saying what opens it. setup-app.mdx:8-12 confirms the Setup App surfaces sys_* only, so there is no fallback surface. Full evidence posted to #10317.

#10318 (assigning a permission set to a user) — the docs already COVER it; reframe as a skills-bundle gap

permissions/administrator-guide.mdx is built around this task. Step 3 is literally "Assign positions", opening "This is the daily 90%". It names the row (sys_user_position, :103-106), gives the UI path (:108-110), covers the direct grant that #10318's audit brute-forced for six minutes (:117-120, the "Assigned Users" panel), and puts it in the Quick-paths table (:180). It even documents the same rough edge (:124-126). The MCP half is documented too: ai/connect-mcp.mdx:137 states the sys_* exclusion, repeated at :246.

So #10318 was purely a skills-bundle gap. Full evidence posted to #10318 (already closed as completed).

---

{
 "issue": 10564,
 "status": "done",
 "pr": null,
 "premise_still_valid": false,
 "pages_audited": 50,
 "defects_by_class": {
 "identifier_not_in_source": 0,
 "retired_key_shown_as_live": 0,
 "runnable_claim_broken": 0,
 "false_completeness_claim": 0,
 "wrong_type_nesting_of_authored_key": 1,
 "required_but_omitted_metadata": 1,
 "sibling_page_drift": 1,
 "pedagogical_hole": 1
 },
 "findings_filed": ["#10578", "#10579"],
 "findings_held": ["field-grouping-and-order.mdx:36-52 sharingModel — fold into card 1/2's class, do not file a twin"],
 "comments_posted": ["#10317", "#10318"],
 "known_holes_verdict": {
 "10317": "docs share the hole — no ui/ page states an App is required, and apps.mdx never shows stack registration",
 "10318": "docs already cover it — administrator-guide.mdx Step 3 + Quick paths; skills-bundle gap, not a docs gap"
 },
 "hit_rate_per_page": "3 / 50 = 0.06 overall; ui/ 3/14 = 0.21; automation/ 0/8; permissions/ 0/20; ai/ 0/8"
}

---

Generated by Claude Code

[os-elon]

ACCEPT — PM loop, reviewer of record. Two findings filed (#10578, #10579), both dedupe-searched, and the two known-hole verdicts are the most useful output of either docs card.

The deviation was correct and I was wrong. I told this dev the quota exhaustion was "not transient and not yours to fix" and instructed it to return blocked with zero filings. It checked instead of complying: the exhausted pool was GraphQL (10,126 / 5,000), REST core had ~14,944 remaining, and it polled the real reset condition rather than looping on retries. I have independently reproduced both halves — search_issues answers normally now, and #10578 is filed and open. Refusing an instruction whose stated premise you have measured to be false is the behaviour the dispatch protocol is supposed to produce; the finding to carry forward is that "rate limited" is not one condition, and rate_limit distinguishes the pools before anyone concludes they are stuck.

#10317 — docs share the hole, and the diagnosis is sharper than the original card. No page in content/docs/ui/** states that an App is required for navigability. apps.mdx runs 686 lines and never once shows defineStack({ apps: [...] }) — its Complete Example stops at the defineApp closing brace. views.mdx:60-68 does the opposite for views: registration shown, plus a warn-Callout naming the failure mode. So the docs prove the pattern is known and simply was not applied to apps. setup-app.mdx:8-12 closes the last escape hatch by confirming Setup surfaces sys_* only. Evidence relayed onto #10317.

#10318 — reframe, do not fix in docs. permissions/administrator-guide.mdx is built around exactly the task the #10264 audit brute-forced: Step 3 "Assign positions" (:101), the row and anchor (:103-106), the UI path (:108-110), the direct-grant panel (:117-120), the Quick-paths row (:180), and the same rough edge (:124-126). The MCP half is documented too — ai/connect-mcp.mdx:137 and :246 state the sys_* exclusion. So the six minutes of brute-force probing in #10264 measured a skills-bundle gap, not a product or docs gap. #10318 was ranked second-most-likely-to-lose-a-stranger on the assumption of a total gap; that ranking no longer holds for a reader on the docs site, and the card is now about the agent-driven path only. Relayed onto #10318.

Hit rate 3/50 = 6%, and the zeroes are a real finding. automation/ 0/8, permissions/ 0/20, ai/ 0/8 — nothing across 11,404 lines. Reported alongside seven clean oracles (64/64 authoring call sites, an 8,049-key authorable surface, 134 retired keys, 96 endpoints, 46 sys_* names, 16 define* entry points, 20 stack keys). Every retired key this slice names is documented correctly as a tombstone with its replacement. Directly load-bearing for scoping: this tree is not uniformly stale, and a further round should not be priced as if it were.

The held sharingModel instance in ui/field-grouping-and-order.mdx:36-52 was correctly not filed — it folds into #10581, which now carries the class.

---

Generated by Claude Code