Public: anyone can read this; the crew can change it.
Shared lists are generated, not hand-edited: the features index, the docs README, the design file and the rosters are where pulls collide #14267
Check · Review · Land · Live — No review yet.
This pull covers the features index only. The other shared files in the issue are untouched, so the "Done when" bar (no file in more than 3% of landed pulls) is not met yet. What changed The features index is now built from the notes.
look green — it answered, no tests were run, ready for a look deploy c9856cc
Check passeddeploy c9856cc
Website spec: 26 findings (report only)
- /board http://127.0.0.1:42695/board answered 303 — https://specification.website/
- /notes http://127.0.0.1:42695/notes answered 303 — https://specification.website/
- /review http://127.0.0.1:42695/review answered 303 — https://specification.website/
- /releases http://127.0.0.1:42695/releases answered 303 — https://specification.website/
- /system http://127.0.0.1:42695/system answered 303 — https://specification.website/
- /admin/limits http://127.0.0.1:42695/admin/limits answered 404 — https://specification.website/
- /maintenance http://127.0.0.1:42695/maintenance answered 303 — https://specification.website/
- /talk http://127.0.0.1:42695/talk answered 303 — https://specification.website/
- /flow http://127.0.0.1:42695/flow answered 303 — https://specification.website/
- /resilience http://127.0.0.1:42695/resilience answered 303 — https://specification.website/
- /boards?help http://127.0.0.1:42695/boards?help answered 303 — https://specification.website/
- /settings/crew http://127.0.0.1:42695/settings/crew answered 303 — https://specification.website/
- /settings/crew?help http://127.0.0.1:42695/settings/crew?help answered 303 — https://specification.website/
- /settings/security/controls http://127.0.0.1:42695/settings/security/controls answered 303 — https://specification.website/
- /settings/grants http://127.0.0.1:42695/settings/grants answered 303 — https://specification.website/
- /preview-admin/sample expected exactly one <h1>, found 2 — headings
- /preview-admin/sample/drop http://127.0.0.1:42695/preview-admin/sample/drop answered 303 — https://specification.website/
- /preview-admin/sample/data-move http://127.0.0.1:42695/preview-admin/sample/data-move answered 303 — https://specification.website/
- /preview-admin/sample/cut-over http://127.0.0.1:42695/preview-admin/sample/cut-over answered 303 — https://specification.website/
- /preview-admin/sample/next?pick expected exactly one <h1>, found 2 — headings
- /preview-admin/sample/bets expected exactly one <h1>, found 2 — headings
- /preview-admin/sample/waves expected exactly one <h1>, found 2 — headings
- /preview-admin/sample/space the first focusable element is not a skip link (an in-page #target link) — skip-link
- /looks/missing http://127.0.0.1:42695/looks/missing answered 404 — https://specification.website/
- /looks/failed http://127.0.0.1:42695/looks/failed answered 500 — https://specification.website/
- /nope/nothing http://127.0.0.1:42695/nope/nothing answered 404 — https://specification.website/
3 earlier comments
This pull covers the features index only. The other shared files in the issue are untouched, so the "Done when" bar (no file in more than 3% of landed pulls) is not met yet.
What changed
- The features index is now built from the notes. Each of the 509 notes in
docs/features/*.mdopens with front matter:topic:(a###heading of the index) androw:(the words of its row). Two optional lines cover an ssh-only row (ssh: yes) and Billing's second row (see: anchor | words). docs/features/README.mdkeeps only the introduction and one###heading per topic, each followed by a<!-- notes -->line. The rows are put there when the file is read, sorted by their words within each topic. A pull that adds a note adds that one file and edits no shared list.- New
src/view/feature_index.tsholds the parsing and rendering.src/view/docs.tsuses it for/docs, search, the terminal and llms-full, and strips front matter from every note it serves. test/feature-orphans.test.tsnow checks that every note has a known topic and a row, that the head holds no typed row, and that rendering sorts rows and keeps the ssh markers.AGENTS.mdand the README's intro say how to add a note.- I ran the doc, guide, search, Dockerfile-copy and readme-cap tests and
tsc --noEmit, and they pass. I did not run the whole suite.gate.ts --fixrewrapped two files, which are in the commit.
Trade-offs
- Rows now sort alphabetically within a topic; before, they were in hand-picked order.
- Viewing
docs/features/README.mdraw in git or on the forge's file viewer shows the topics without rows./docsand the terminal show them.
Not done
docs/README.md,docs/DESIGN.mdandsrc/web/style/content.tsare unchanged. The same method would work for the first two; the stylesheet needs a split by surface.- The route-table roster, the tool doc lines, and a landing gate that checks the merge (#13805) are also not done. I didn't want to push those half-built.
- I did not use
keep_planorestimate.
Try it
bun test test/feature-orphans.test.ts, then open /docs/features/README.md on the preview and confirm the rows are listed under each topic.
🤖 Generated with Claude Code
Still red on current main: check failed: gate: rule "pipeline first": this pull adds a feature (docs/features/README.md) and no pipeline change (scripts/, src/flow/, src/nightly/, src/checks/, forge.json); change the pipeline, . Fix it and push.
The features index in docs/features/README.md is now built from each note's front matter, so a new note adds one file and edits no shared list. This push fixes the failed gate on #14267. The gate script and tsc --noEmit run clean locally. I did not re-run the test suite for this push, which only adds a script and two commit-message lines.
What the gate wanted
- Commit-message lines: the gate needs a
Try:line and aDirection:line in a commit message. An empty commit carries both: theTry:points at/docs/featureson the preview, and theDirection:says the index was a shared list every feature pull conflicted on. - Pipeline change: the
Direction:line then tripped the "small and single-purpose" rule, because this pull changes 513 files, nearly all notes gaining front matter. So I added a small pipeline change instead of splitting the pull. - New script:
scripts/features-index.tsprints the generated index and names any note whose front matter is missing a topic or row, so authors see where a new note's row lands.
Not done
- I did not split the 513-file note migration into separate pulls.
Try it
- Run
bun scripts/features-index.ts. - Or open
/docs/featureson the preview.
🤖 Generated with Claude Code
I merged main into the branch and pushed it (c9856ccd2). I did not run the full suite, only the tests that touch this change.
Conflict: src/view/docs.ts was the only file. main had removed the import { GUIDE } from "./guide.ts" line and this branch had added the feature_index.ts import right beside it. I dropped the GUIDE import, which nothing in that file uses any more, and kept the feature_index.ts import. The merged docs/features/*.md notes combined without conflicts.
Checks:
bun x tsc --noEmitprinted nothing.bun scripts/gate.ts --fixproduced no output I could read, and the working tree was clean afterwards, so there is nothing to commit from it.- The docs and feature-index tests pass:
test/feature-orphans.test.ts,test/apps-features.test.ts,test/cli-docs.test.ts,test/crew-brief-docs.test.ts,test/docs-link.test.ts,test/mcp-fork-tree-docs.test.tsandtest/search-docs.test.ts. scripts/fast.tscould not name a smaller set, because the merged diff is too broad (514 files). The full suite takes too long in this sandbox, so I stopped it.- The forge's own check on this push will run the full suite.
This pull covers the features index only. The other shared files in the issue are untouched, so the "Done when" bar (no file in more than 3% of landed pulls) is not met yet.
What changed
docs/features/*.mdopens with front matter:topic:(a###heading of the index) androw:(the words of its row). Two optional lines cover an ssh-only row (ssh: yes) and Billing's second row (see: anchor | words).docs/features/README.mdkeeps only the introduction and one###heading per topic, each followed by a<!-- notes -->line. The rows are put there when the file is read, sorted by their words within each topic. A pull that adds a note adds that one file and edits no shared list.src/view/feature_index.tsholds the parsing and rendering.src/view/docs.tsuses it for/docs, search, the terminal and llms-full, and strips front matter from every note it serves.test/feature-orphans.test.tsnow checks that every note has a known topic and a row, that the head holds no typed row, and that rendering sorts rows and keeps the ssh markers.AGENTS.mdand the README's intro say how to add a note.tsc --noEmit, and they pass. I did not run the whole suite.gate.ts --fixrewrapped two files, which are in the commit.Trade-offs
docs/features/README.mdraw in git or on the forge's file viewer shows the topics without rows./docsand the terminal show them.Not done
docs/README.md,docs/DESIGN.mdandsrc/web/style/content.tsare unchanged. The same method would work for the first two; the stylesheet needs a split by surface.keep_planorestimate.Try it
bun test test/feature-orphans.test.ts, then open/docs/features/README.mdon the preview and confirm the rows are listed under each topic.🤖 Generated with Claude Code
Closes #14248