book: Std pages, core (slice of #591)

orion commented

2026-10-29 23:50:59 +00:00

Collaborator

Slice of #591 (Std pages, core and text), which is a slice of the epic #582. Starts after nothing; #585 is merged. The other Std slices (#592 to #595) and the Guide and Reference slices are independent of this one. Governing note: book/CONCEPT.md ("How a page is written", "What CI checks"). Touches the seed: no (documentation only; no syntax change, no native, no driver flag, no std name looked up by the compiler).

Goal

Write the Std page(s) book/std/prelude.md, book/std/core.md. Read like book/std/json.md (merged in #585): the page opens with what the module is for and an example of the most common task, then covers the handful of tasks people use it for, each with a real program and its output. It does not list every declaration; the generated API reference of torb doc std does that.

Replaces in `docs/`

docs/standard-library/prelude.md
docs/standard-library/core.md

Acceptance criteria

Every page has the kind page, status: stable, front matter in the shape of book/std/json.md (title, summary, order, package; the summary within the docs check limit), names its module (package: std/prelude, package: std/core), and is written as book/CONCEPT.md, "How a page is written", says: the first paragraph says in two to four sentences what the page covers, headings name ideas, prose first, no history words, no internal references (no issue numbers, no links into docs/design, docs/contributing, docs/internals, CONCEPT.md), no Related/Next/See also sections, lists of at most seven items, every section starts with a sentence; links only to book pages that exist on main
Every trb run and trb error block is followed by its output block with the real output (a trb error block shows what torb check prints, from error: on); no fragments, no // prints comments
The signature features of book/CONCEPT.md that the area touches are shown, not just named
book/std/index.md lists the new page(s) (generated block via torb docs index book); torb docs check book, torb docs index --check book and torb docs site book --check pass, and tools/gates.sh passes in CI
The old pages listed under "Replaces in docs/" are deleted in the same PR unless a skill is still built from them (skills are generated by torb docs skill docs skills): for every old page a skill still needs, it stays in docs/ unpublished and the PR description names it and why; the others are deleted together with every link to them, and the skills are regenerated so docs skill --check stays green
No other book page is changed except the links that must follow from the deletion; the other Std pages of #591 are not started

Notes for the implementer

Read book/CONCEPT.md, book/std/json.md and the old pages first; run every example with torb before pasting its output. A behaviour that only the old page states and that you cannot reproduce is checked against the compiler or the std source, not copied.
Commits: one or two Conventional Commits, for example docs(book): std prelude and, if needed, docs: retire the pages the std pages replace.
Size: one PR, 30-40 minutes. Do not write the other Std pages.

Slice of #591 (Std pages, core and text), which is a slice of the epic #582. Starts after nothing; #585 is merged. The other Std slices (#592 to #595) and the Guide and Reference slices are independent of this one. Governing note: `book/CONCEPT.md` ("How a page is written", "What CI checks"). Touches the seed: no (documentation only; no syntax change, no native, no driver flag, no std name looked up by the compiler). ## Goal Write the Std page(s) `book/std/prelude.md`, `book/std/core.md`. Read like `book/std/json.md` (merged in #585): the page opens with what the module is for and an example of the most common task, then covers the handful of tasks people use it for, each with a real program and its output. It does not list every declaration; the generated API reference of `torb doc std` does that. ## Replaces in `docs/` - `docs/standard-library/prelude.md` - `docs/standard-library/core.md` ## Acceptance criteria - [ ] Every page has the kind `page`, `status: stable`, front matter in the shape of `book/std/json.md` (`title`, `summary`, `order`, `package`; the summary within the `docs check` limit), names its module (`package: std/prelude`, `package: std/core`), and is written as `book/CONCEPT.md`, "How a page is written", says: the first paragraph says in two to four sentences what the page covers, headings name ideas, prose first, no history words, no internal references (no issue numbers, no links into `docs/design`, `docs/contributing`, `docs/internals`, `CONCEPT.md`), no Related/Next/See also sections, lists of at most seven items, every section starts with a sentence; links only to book pages that exist on main - [ ] Every `trb run` and `trb error` block is followed by its `output` block with the real output (a `trb error` block shows what `torb check` prints, from `error:` on); no fragments, no `// prints` comments - [ ] The signature features of `book/CONCEPT.md` that the area touches are shown, not just named - [ ] `book/std/index.md` lists the new page(s) (generated block via `torb docs index book`); `torb docs check book`, `torb docs index --check book` and `torb docs site book --check` pass, and `tools/gates.sh` passes in CI - [ ] The old pages listed under "Replaces in `docs/`" are deleted in the same PR unless a skill is still built from them (skills are generated by `torb docs skill docs skills`): for every old page a skill still needs, it stays in `docs/` unpublished and the PR description names it and why; the others are deleted together with every link to them, and the skills are regenerated so `docs skill --check` stays green - [ ] No other book page is changed except the links that must follow from the deletion; the other Std pages of #591 are not started ## Notes for the implementer - Read `book/CONCEPT.md`, `book/std/json.md` and the old pages first; run every example with `torb` before pasting its output. A behaviour that only the old page states and that you cannot reproduce is checked against the compiler or the std source, not copied. - Commits: one or two Conventional Commits, for example `docs(book): std prelude` and, if needed, `docs: retire the pages the std pages replace`. - Size: one PR, 30-40 minutes. Do not write the other Std pages.

orion added the

loop

label

2026-10-29 23:50:59 +00:00

orion referenced this issue

2026-10-29 23:51:16 +00:00

book: Std pages, core and text #591

orion referenced this issue

2026-10-29 23:51:16 +00:00

book: Std pages, core and text #591

orion added the

ready

label

2026-10-30 00:07:50 +00:00

orion commented

2026-10-30 00:07:50 +00:00

Author

Collaborator

[loop:torbscript] ready: slice of #591, the first std page group, filed with the criteria of its parent.
[loop:torbscript] claim implement by session:loop-torbscript-20261030 until 2026-10-30T06:07Z

[loop:torbscript] ready: slice of #591, the first std page group, filed with the criteria of its parent. [loop:torbscript] claim implement by session:loop-torbscript-20261030 until 2026-10-30T06:07Z

orion commented

2026-10-30 00:17:25 +00:00

Author

Collaborator

[loop:torbscript] checkpoint: first push of loop/638-std-prelude-core (book/std/prelude.md, book/std/core.md, index entries); all examples were run with the nightly torb. Next: run the book checker from source, regenerate nothing if the old docs pages stay (skills are built from docs/standard-library/), open the PR.

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

2026-10-30 00:24:37 +00:00

docs(book): std prelude and core #654

orion commented

2026-10-30 00:24:42 +00:00

Author

Collaborator

[loop:torbscript] checkpoint: PR #654 is open (docs check, index check and site check pass from source). Old docs/standard-library/prelude.md and core.md stay, because the standard-library skill carries that directory. Next: waiting on forge CI.

orion commented

2026-10-30 00:41:09 +00:00

Author

Collaborator

[loop:torbscript] release implement: PR #654 opened, head 16f66776b0; CI queued (no runner picked it up yet). Old pages kept: the skill torbscript-standard-library is built from docs/standard-library/. The item is in review; CI and Argus decide.

[loop:torbscript] release implement: PR #654 opened, head 16f66776b0b8628e65578730955330f5150e4196; CI queued (no runner picked it up yet). Old pages kept: the skill torbscript-standard-library is built from docs/standard-library/. The item is in review; CI and Argus decide.

orion referenced this issue

2026-10-30 01:15:25 +00:00

book: Std pages, core and text #591