book: Tools section

orion commented

2026-10-29 14:25:46 +00:00

Collaborator

Slice of the epic #582. Starts after #585 (the concept, the vertical slice and the book gates) is merged.

Scope

Add book/tools/, one page per workflow of the torb command, and put Tools into the header of the site:

New page	Replaces in `docs/`
`tools/index.md`	`tooling/the-torb-command.md`, `tooling/index.md`
`tools/running-and-building.md`	`tooling/torb-run.md`, `tooling/torb-build.md`, `tooling/torb-repl.md`
`tools/testing.md`	`tooling/torb-test.md`, `tooling/verifying-your-work.md`
`tools/checking-and-formatting.md`	`tooling/torb-format.md`, `tooling/torb-lint.md`, `tooling/torb-canon.md`, `tooling/torb-check.md`
`tools/projects.md`	`tooling/torb-new.md`, `tooling/torb-init.md`, `tooling/project-trb.md`, `tooling/project-lock-trb.md`, `tooling/config-trb.md`, `tooling/package-capabilities.md`
`tools/packages.md`	`tooling/torb-add.md` and the other package commands
`tools/editors-and-debugging.md`	`tooling/torb-lsp.md`, `how-to/set-up-your-editor.md`, `tooling/torb-debug.md`
`tools/documentation.md`	`tooling/torb-doc.md`, `tooling/torb-docs-site.md`, `tooling/torb-docs-source.md`, `language/syntax/doc-comments.md`

Acceptance criteria

Every page has the kind page and is written as book/CONCEPT.md, "How a page is written", says: the first paragraph says what the page covers, headings name ideas, prose first, no history, no internal references, no Related/Next sections
Every trb run and trb error block has its output block with the real output; torb docs check book, torb docs index --check book and torb docs site book --check pass in CI
The signature features of book/CONCEPT.md that the area touches are shown, not just named
The old pages of docs/ this slice replaces are deleted in the same PR, unless a skill is still built from them (then they stay, unpublished, and the PR says which)
Terminal sessions are console blocks whose output is the real output of the command; where a command's output can be checked by torb docs check, it is
A page explains the workflow in prose; the full flag list of a command is one table, not a wall of list items

Slice of the epic #582. Starts after #585 (the concept, the vertical slice and the book gates) is merged. ## Scope Add `book/tools/`, one page per workflow of the `torb` command, and put Tools into the header of the site: | New page | Replaces in `docs/` | |---|---| | `tools/index.md` | `tooling/the-torb-command.md`, `tooling/index.md` | | `tools/running-and-building.md` | `tooling/torb-run.md`, `tooling/torb-build.md`, `tooling/torb-repl.md` | | `tools/testing.md` | `tooling/torb-test.md`, `tooling/verifying-your-work.md` | | `tools/checking-and-formatting.md` | `tooling/torb-format.md`, `tooling/torb-lint.md`, `tooling/torb-canon.md`, `tooling/torb-check.md` | | `tools/projects.md` | `tooling/torb-new.md`, `tooling/torb-init.md`, `tooling/project-trb.md`, `tooling/project-lock-trb.md`, `tooling/config-trb.md`, `tooling/package-capabilities.md` | | `tools/packages.md` | `tooling/torb-add.md` and the other package commands | | `tools/editors-and-debugging.md` | `tooling/torb-lsp.md`, `how-to/set-up-your-editor.md`, `tooling/torb-debug.md` | | `tools/documentation.md` | `tooling/torb-doc.md`, `tooling/torb-docs-site.md`, `tooling/torb-docs-source.md`, `language/syntax/doc-comments.md` | ## Acceptance criteria - [ ] Every page has the kind `page` and is written as `book/CONCEPT.md`, "How a page is written", says: the first paragraph says what the page covers, headings name ideas, prose first, no history, no internal references, no Related/Next sections - [ ] Every `trb run` and `trb error` block has its `output` block with the real output; `torb docs check book`, `torb docs index --check book` and `torb docs site book --check` pass in CI - [ ] The signature features of `book/CONCEPT.md` that the area touches are shown, not just named - [ ] The old pages of `docs/` this slice replaces are deleted in the same PR, unless a skill is still built from them (then they stay, unpublished, and the PR says which) - [ ] Terminal sessions are `console` blocks whose output is the real output of the command; where a command's output can be checked by `torb docs check`, it is - [ ] A page explains the workflow in prose; the full flag list of a command is one table, not a wall of list items

orion added the

loop

label

2026-10-29 14:25:46 +00:00

orion added a new dependency

2026-10-29 14:25:51 +00:00

#585 docs(book): a book for people, and the site built from it

orion added a new dependency

2026-10-29 14:25:52 +00:00

#599 book: retire the human pages of docs/

orion referenced this issue

2026-10-29 14:25:57 +00:00

Epic: human documentation rewrite (by humans, for humans) #582

orion referenced this issue

2026-10-29 14:26:01 +00:00

Epic: human documentation rewrite (by humans, for humans) #582

orion commented

2026-10-30 03:34:00 +00:00

Author

Collaborator

[loop:torbscript] intake: in scope (book Tools section, slice of epic #582; dependency #585 is merged), no duplicate, no seed impact. Next: refine (seven pages replacing about 25 old tooling pages; size check and split just in time, after the open book PRs have cleared CI).

orion commented

2026-10-30 04:28:00 +00:00

Author

Collaborator

[loop:torbscript] wait until 2026-10-30T09:00Z: refine is due (eight pages, will be split into one child per page just in time). Seven book slices (#641 in work, #642 to #674 unready) already queue behind the open book PRs #601, #663, #670; starting another split now only grows the unready backlog.

Rows
Columns

book: Tools section #596

Scope

Acceptance criteria