docs(readme): stop ordering the field transcript back into the tree (#1494)

[os-sales]

Fixes #1494

What was false

Two statements about docs/developers/api_reference.md, both left stranded when PR #1495 replaced that page's transcript with a pointer at source:

docs/README.md:20   | Object field reference | [developers/api_reference.md](developers/api_reference.md) |
docs/README.md:63   3. Update `docs/developers/api_reference.md` when object fields change.

Line 63 is the sharp one. It orders a maintainer to update a file that now states, in its own words, that it deliberately does not carry the thing they would be updating:

docs/developers/api_reference.md:17   Field lists are deliberately **not** restated here either — the `fields:`
docs/developers/api_reference.md:18   block of each `src/objects/*.object.ts` is their source of truth …

A reader who follows it faithfully re-creates the fifteen Key fields: lists PR #1495 removed, which is the act AGENTS.md documentation-discipline rule 5 forbids by name: "The single source of truth for a machine fact — a dataset's dimensions, an object's fields, the roster of objects itself — is the self-describing metadata under src/." Line 20's label described the page as it was rather than as it is.

The call: reword both lines in place, not delete

The card left this open on purpose, so here is the argument for the route taken.

1. The repo has already answered this question twice, in the same ruling's cleanup, and answered it "reword". docs/ARCHITECTURE.md kept its engines.protocol sentence and repointed it at objectstack.config.ts (PR #1476). docs/MAINTENANCE.md kept step 2 of its own numbered per-PR change loop — the closest structural twin of the line under edit — and repointed it at src/translations/. Both carry a *Supersedes … — 2026-08-31 ruling, item 5.* note. Deleting here would make docs/README.md the one site in that family that answers the same question with silence, and a reader comparing the two checklists would find no rule where its sibling has one.

2. Deleting removes the question, not the answer. Step 3 exists because someone wanted the field reference to stay current — a real want. A checklist that simply drops the entry leaves the next maintainer looking at an api_reference.md row in the Start Here index with no maintenance rule attached to it, and re-adding a table is the cheapest thing they can do about that. That is how one roster reached four files. A negative instruction is enforceable by a reader; an absent one is not.

3. Deleting is safe, it just buys nothing. Measured, not assumed: nothing in this repo cross-references "step 3" of this list, and nothing links to the Maintain The Docs heading, so renumbering would break no reference. The argument against deleting is editorial, not mechanical — which is why the honest route was to argue it rather than pick the smaller diff.

What a maintainer should do instead when object fields change

This is the half a bare deletion would drop, so the step now states it:

• Edit the object's own src/objects/*.object.ts file. The fields: block is the reference — editing the object file is the update, and there is no second copy to keep in step. api_reference.md is a pointer page and needs no edit at all.
• If user-facing behaviour changed, update the business-concept docs under content/docs/ — step 1 of the same list already says this, and rule 5 governs its shape: concepts, never a transcribed field table.
• Run the checks in docs/STATUS.md — step 5, where pnpm validate is authoritative for object and field counts.

Before / after

Line 20:

- | Object field reference | [developers/api_reference.md](developers/api_reference.md) |
+ | Where object and field metadata is declared | [developers/api_reference.md](developers/api_reference.md) |

The new label is the page's own subtitle read back — "Where this repository's object and field inventory lives, and how to read it from source" — and it fits the Need column's noun-phrase style.

Line 63:

- 3. Update `docs/developers/api_reference.md` when object fields change.
+ 3. Leave `docs/developers/api_reference.md` alone when object fields change — the `fields:`
+    block of `src/objects/*.object.ts` is the reference, and that page points at it rather
+    than restating it. *Supersedes the instruction to hand-update that page, which asked for
+    the field transcript since removed from it — 2026-08-31 ruling, item 5.*

Measurements

1. Lines 20 and 63 are the only two sites in docs/README.md that describe api_reference.md as carrying field lists. Whole file read (69 lines). api_reference — 2 hits, both of them. field case-insensitive — 2 hits, the same two lines. reference — 4 hits: lines 20 and 63, plus lines 6 and 28, which describe the whole docs/ tree as "developer reference" and make no claim about this page. No third sentence anywhere.
2. No other file carries the same standing instruction. Swept docs/, .github/, content/docs/, AGENTS.md, CLAUDE.md, README.md for Update-this-doc instruction shapes and for field-transcription language. The literal shape "Update docs/…" returns exactly three hits, all inside this one list (lines 62, 63, 64). Every other hit is a pointer-at-source statement of the kind this PR is aligning with (docs/ARCHITECTURE.md, docs/MAINTENANCE.md, docs/DEPLOYMENT.md, api_reference.md itself) or the rule text in AGENTS.md:267 and AGENTS.md:326. Nothing to report as a second offender.
3. Nothing keys on the row label or the wording. Object field reference had exactly one occurrence in the repo — the line being changed. Only two test files reference docs/README.md at all (below). link-check.yml runs check-modified-files-only on PRs, so it does read this file; the relative link target developers/api_reference.md is unchanged and resolves, and the edit adds no new link.
4. Numbering stays coherent, and it would also have survived deletion. No step 3 cross-reference to this list exists anywhere in the repo — the step N hits are docs/MAINTENANCE.md:193 (its own §5 loop), .github/instructions/architect.md, two content/docs pages and three test/script comments, none of them about this list. Nothing links to the Maintain The Docs anchor either. Reword keeps 1–5 intact regardless.
5. docs/README.md is inside a guarded tree, and the guard stays green and non-vacuous. test/docs-src-tree-paths.test.ts lists it in both TREE_DOCS (line 114) and TREE_DIAGRAM_DOCS (line 174). Neither pins contents: the first resolves every src/DIR/ path named inline against the real tree, the second every entry drawn under the tree diagram's src/ node. The new step-3 text names src/objects/*.object.ts inline, which inlineSrcDirs reads as objects — a directory that exists — so membership has not gone vacuous and the file gained a second real inline claim. test/docs-role-hierarchy.test.ts:187 also scans it for forbidden role-hierarchy spellings; the edit introduces none. docs/ is inside TEXT_SCANNED in scripts/lib/source-hygiene-surface.mjs, so the control-byte check reads this file — self-scanned clean before committing, and pnpm hygiene confirms. docs/README.md is not in COUNT_DOCS and not in the token ratchet surface (src/**/*.ts), so neither can be affected.

No ablation. Nothing behavioural changes — this is two lines of English in an index file, with no code path, no guard and no generated artefact behind it. There is nothing to mutate and no red leg to produce, and manufacturing one would be ceremony rather than evidence. The edit is instead proved on disk: blob 3dfceefe before, 9a7c73f9 after, with anchored counts on both the removed text (Object field reference 0, the old step 3 line 0) and the injected text (new label 1, new step-3 head 1, the Supersedes note 1), and both edited sections read back in full.

Verification

pnpm verify in full, on the tree committed as e2fddae8 (working tree clean against HEAD, so the measured tree is the pushed tree), run under this container's shared heavy-verify lock:

os-verify-lock: VERDICT command-exit 0 · held the lock 217s (3m37s) · waited 0s

  ✓ Validation passed (1933ms)                       pnpm validate
  (silent)                                           pnpm typecheck
  ✓ i18n lint gate: 0 `i18n/missing-*` issues        pnpm lint + lint:i18n-gate
  ✓ source hygiene clean                             pnpm hygiene
      ✓ no raw control bytes in first-party files
  ✓ source token ratchet clean                       pnpm hygiene:tokens
  ✓ Build complete (1743ms)                          pnpm build

  Test Files  160 passed (160)
       Tests  3371 passed | 1 skipped (3372)

Exit code captured before any pipe; the verdict line above is the lock entry point's own, not a bare $?.

Scope

docs/README.md plus .changeset/readme-stops-ordering-the-field-transcript.md, exactly as declared. docs/developers/api_reference.md is correct after PR #1495 and was read but not touched; AGENTS.md is governed and is the source of the rule. No guard is added or retired — 2026-08-31 ruling item 3 keeps gate-type mechanisms on the platform.

🤖 Generated with Claude Code

https://claude.ai/code/session_019hUuCQStzXGMFSX4dzww5t

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 3, 2026 1:06pm UTC