docs: every command of `torb` has a page or a line that says it is internal

orion commented

2026-11-13 12:39:37 +00:00

Collaborator

Context

The command table of compiler/src/main.trb (lines 546-790) has commands that no page under docs/tooling/ describes: torb upgrade (not mentioned in the-torb-command.md either), torb natives, torb manifest, torb highlight, and the subcommands torb docs check, docs index, docs declarations, docs skill, docs bundle (only docs site and docs source have pages). torb docs check and torb docs index --check are CI gates that every contributor meets.

Source

Cleanup audit 2026-11 (#742), finding F9; the report is docs/project/2026-11-cleanup-audit.md.
Related: #596 (the Tools section of the book) reads from these pages.

Goal

A reader finds every command torb accepts: a page for each command a user runs, and one table in the-torb-command.md for the commands that exist for the toolchain's own tests (tokens, ast, parse, ir, natives, manifest, highlight), marked as internal and unstable.

Design record point

docs/design/CLI.md; docs/contributing/ (how a tooling page is written).

Acceptance criteria

Pages torb-upgrade.md and torb-docs-check.md (covering check, index, declarations, skill, bundle, or one page each) exist in the form of the other tooling pages
the-torb-command.md lists every command of the command table; the internal ones are in one table that says so
A test compares the command table with the tooling pages and fails for a command without a page or a line
torb docs check and torb docs index --check are green

Dependencies

None. If the torb canon removal lands first, its page is already gone.

Seed

None (documentation and one test).

Size

One PR, two commits (pages, then the test).

## Context The command table of `compiler/src/main.trb` (lines 546-790) has commands that no page under `docs/tooling/` describes: `torb upgrade` (not mentioned in `the-torb-command.md` either), `torb natives`, `torb manifest`, `torb highlight`, and the subcommands `torb docs check`, `docs index`, `docs declarations`, `docs skill`, `docs bundle` (only `docs site` and `docs source` have pages). `torb docs check` and `torb docs index --check` are CI gates that every contributor meets. ## Source - Cleanup audit 2026-11 (#742), finding F9; the report is `docs/project/2026-11-cleanup-audit.md`. - Related: #596 (the Tools section of the book) reads from these pages. ## Goal A reader finds every command `torb` accepts: a page for each command a user runs, and one table in `the-torb-command.md` for the commands that exist for the toolchain's own tests (`tokens`, `ast`, `parse`, `ir`, `natives`, `manifest`, `highlight`), marked as internal and unstable. ## Design record point `docs/design/CLI.md`; `docs/contributing/` (how a tooling page is written). ## Acceptance criteria - [ ] Pages `torb-upgrade.md` and `torb-docs-check.md` (covering `check`, `index`, `declarations`, `skill`, `bundle`, or one page each) exist in the form of the other tooling pages - [ ] `the-torb-command.md` lists every command of the command table; the internal ones are in one table that says so - [ ] A test compares the command table with the tooling pages and fails for a command without a page or a line - [ ] `torb docs check` and `torb docs index --check` are green ## Dependencies None. If the `torb canon` removal lands first, its page is already gone. ## Seed None (documentation and one test). ## Size One PR, two commits (pages, then the test).

orion added the

ready

loop

labels

2026-11-13 12:39:37 +00:00

orion referenced this issue

2026-11-13 12:41:37 +00:00

book: Tools section #596

orion referenced this issue

2026-11-13 12:41:38 +00:00

cleanup: 2026-11 audit plan (epic) #742

orion referenced this issue

2026-11-13 12:55:46 +00:00

book: Tools section #596

orion commented

2026-11-13 12:55:46 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261113 until 2026-11-13T18:55Z

orion referenced this issue from a commit

2026-11-13 12:59:35 +00:00

docs(tooling): pages for torb upgrade and the docs subcommands, and the internal commands

orion referenced this issue from a commit

2026-11-13 12:59:35 +00:00

test(docs): every command of torb has a tooling page or a row in the internal table

orion referenced this issue from a pull request that will close it,

2026-11-13 12:59:40 +00:00

docs(tooling): a page or an internal row for every command of torb #757

orion commented

2026-11-13 13:04:56 +00:00

Author

Collaborator

PR #757 is open on loop/752-command-pages with two commits: the pages (torb-upgrade.md, torb-docs-check.md, the internal-commands table in the-torb-command.md, the index entries) and compiler/tests/command-pages.test.trb. Waiting for CI on the head; nothing was run locally because there is no torb binary in this container.

PR #757 is open on `loop/752-command-pages` with two commits: the pages (`torb-upgrade.md`, `torb-docs-check.md`, the internal-commands table in `the-torb-command.md`, the index entries) and `compiler/tests/command-pages.test.trb`. Waiting for CI on the head; nothing was run locally because there is no `torb` binary in this container.

orion commented

2026-11-13 13:56:31 +00:00

Author

Collaborator