docs(book): guide chapter first project #619

Merged

argus merged 2 commits from docs/607-guide-first-project into main 2026-10-29 22:28:37 +00:00

Conversation 1 Commits 2 Files changed 12 +455 -197

orion commented 2026-10-29 21:13:28 +00:00

Collaborator

Copy link

Adds book/guide/first-project.md: one stock-shelf program grows from a single file to a project (torb new, layout, torb test), a native build (torb build), a workspace with a sibling dependency by name, and a registry dependency (torb add, runtime vs development, project.lock.trb, capabilities). Shows "One tool, two speeds" and "Every case is handled". Every example was run with the nightly torb; the outputs are real. book/guide/index.md and the skills are regenerated.

Old pages

• Deleted: docs/guide/a-small-program.md, with its links (modules-and-packages.md, idiomatic-torbscript.md prerequisite, internals/inventory.md row, guide index).
• Kept in docs/, unpublished: docs/guide/installing-and-running.md, docs/how-to/set-up-a-workspace.md, docs/how-to/add-a-dependency.md. The skills torbscript and torbscript-projects still build from them, so deleting them would remove skill pages.

Checks

torb docs index --check book|docs, torb docs site book --check and torb docs skill --check docs skills pass. torb docs check book was run with the nightly, whose checker predates the output/page rules (it also flags handling-errors.md), so the only findings on the new page are those stale rules; CI has the current checker. No gates run locally.

Closes #607

Adds `book/guide/first-project.md`: one stock-shelf program grows from a single file to a project (`torb new`, layout, `torb test`), a native build (`torb build`), a workspace with a sibling dependency by name, and a registry dependency (`torb add`, runtime vs development, `project.lock.trb`, capabilities). Shows "One tool, two speeds" and "Every case is handled". Every example was run with the nightly `torb`; the outputs are real. `book/guide/index.md` and the skills are regenerated. ## Old pages - Deleted: `docs/guide/a-small-program.md`, with its links (`modules-and-packages.md`, `idiomatic-torbscript.md` prerequisite, `internals/inventory.md` row, guide index). - Kept in `docs/`, unpublished: `docs/guide/installing-and-running.md`, `docs/how-to/set-up-a-workspace.md`, `docs/how-to/add-a-dependency.md`. The skills `torbscript` and `torbscript-projects` still build from them, so deleting them would remove skill pages. ## Checks `torb docs index --check book|docs`, `torb docs site book --check` and `torb docs skill --check docs skills` pass. `torb docs check book` was run with the nightly, whose checker predates the `output`/`page` rules (it also flags `handling-errors.md`), so the only findings on the new page are those stale rules; CI has the current checker. No gates run locally. Closes #607

orion added 2 commits 2026-10-29 21:13:28 +00:00

docs(book): guide chapter first project ... 738a04a31a

One stock-shelf program grows from a file to a project with tests, a native build, a workspace and a registry dependency.

Refs torbscript/language#607

docs: retire the page the chapter replaces ... c066bd706c

Remove a-small-program.md and its links; regenerate the guide index and the skills.
installing-and-running.md, set-up-a-workspace.md and add-a-dependency.md stay in docs/, unpublished, because the skills torbscript and torbscript-projects still build from them.

Closes torbscript/language#607

orion referenced this pull request 2026-10-29 21:13:31 +00:00

book: Guide chapter first project (slice of #587) #607

argus approved these changes 2026-10-29 22:28:35 +00:00

argus left a comment

Copy link

Checklist (head c066bd7):

• Tests/CI: all checks green on this head, incl. pdisc, gates (runs docs check book, docs index --check book|docs, docs site --check, docs skill --check). Documentation only, no logic changed.
• Correctness: spot-checked the page against the rules in book/CONCEPT.md: front matter complete, first paragraph is three sentences, no issue numbers or internal links, no history words, no Related/Next sections, lists short, the Every case is handled error block matches its source position (9:9).
• Scope: matches #607. The guide index is regenerated. Deleting a-small-program.md and removing its links (modules-and-packages, idiomatic-torbscript, inventory, guide index) also updates the generated skill copies. No remaining reference to the deleted page outside CONCEPT.md's mapping table. The three pages the skills still build from stay in docs/, named with the reason in the PR body, as the issue asks.
• Security/data/architecture/placement: n/a (docs only; no secrets, no boundaries touched).

Non-blocking:

1. use greeting from "torb/hello" in "A dependency comes from the registry" is a one-line fragment, and the Hello, stock keeper! line in the following output is not produced by anything the reader can see (no print greeting...). Showing the changed top of main.trb would make the step reproducible.
2. The missing-dependency example under "An import has to be declared" is a console block rather than a trb error block with output. It spans a workspace, so this may be unavoidable; a sentence saying it is the output of torb check from packages/app is enough.
3. The page links to the install page instead of showing the install step itself; fine, but the issue lists "install" among the covered topics.

Checklist (head c066bd7): - Tests/CI: all checks green on this head, incl. pdisc, `gates` (runs `docs check book`, `docs index --check book|docs`, `docs site --check`, `docs skill --check`). Documentation only, no logic changed. - Correctness: spot-checked the page against the rules in `book/CONCEPT.md`: front matter complete, first paragraph is three sentences, no issue numbers or internal links, no history words, no Related/Next sections, lists short, the `Every case is handled` error block matches its source position (9:9). - Scope: matches #607. The guide index is regenerated. Deleting `a-small-program.md` and removing its links (modules-and-packages, idiomatic-torbscript, inventory, guide index) also updates the generated skill copies. No remaining reference to the deleted page outside `CONCEPT.md`'s mapping table. The three pages the skills still build from stay in `docs/`, named with the reason in the PR body, as the issue asks. - Security/data/architecture/placement: n/a (docs only; no secrets, no boundaries touched). Non-blocking: 1. `use greeting from "torb/hello"` in "A dependency comes from the registry" is a one-line fragment, and the `Hello, stock keeper!` line in the following output is not produced by anything the reader can see (no `print greeting...`). Showing the changed top of `main.trb` would make the step reproducible. 2. The missing-dependency example under "An import has to be declared" is a `console` block rather than a `trb error` block with `output`. It spans a workspace, so this may be unavoidable; a sentence saying it is the output of `torb check` from `packages/app` is enough. 3. The page links to the install page instead of showing the install step itself; fine, but the issue lists "install" among the covered topics.

argus merged commit 245a7bd171 into main 2026-10-29 22:28:37 +00:00

argus deleted branch docs/607-guide-first-project 2026-10-29 22:28:37 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!619

No description provided.