Publish the book on GitHub Pages; OpenSysML terminology and contribution policy

[mzargham]

Summary

Publishes the book on GitHub Pages at https://open-mbee.github.io/toaster/, and brings the repository's wording and contribution policy into line with how the book is now published.

Nothing deploys from this PR. The deploy job runs only on a push to main, and Pages has to be enabled first (see "Before merging").

What changed

1. A reproducible build and a Pages pipeline (the work that makes the site publishable)

• toaster.tools resolves every external tool (the sysmlv2 binary, its standard library, the PlantUML jar, Java, Z3) from environment variables, then .tools/, then PATH. No notebook, test or script names a home directory or a Homebrew path any more (a guard test fails if one comes back).
• scripts/provision-tools.py downloads the pinned tools (scripts/tool-pins.json: sysml-toolkit v0.9.1, Z3 5.1.0, PlantUML 1.2026.8, the SysML v2 standard library at a pinned commit), verifies each download by sha256 or commit before installing, and is idempotent. scripts/check-tools.py reports what was resolved.
• scripts/check-site.py is the release gate: the executed build's log has no cell errors; the content has the expected 18 figures; no built text file contains a host path; no exercise notebook or DEFERRED.md is published as a raw download; every root-relative link and asset carries the /toaster base and resolves.
• .github/workflows/ci.yml runs on ubuntu-24.04: provision, test (with TOASTER_REQUIRE_TOOLS=1, so a missing tool fails instead of skipping), myst build --html --execute --strict with BASE_URL=/toaster, the gate, then upload and deploy only from a push to main. Pull requests build and gate but cannot deploy.
• Learner-visible references to repo-internal artifacts (365 occurrences found by a survey) are now links to GitHub or reworded so each page stands alone. Exercises are linked, not published. Findings: decisions/pages-publishing-survey.md and decisions/pages-publishing/.

2. OpenSysML terminology (opensysml.org calls OpenSysML a stack; this repo had used the name for the Go runtime only)

• "OpenSysML" now names the stack. The tutorial's two components are named as the OpenSysML runtime (Go, opensysml, v0.9.0) and sysml-toolkit (Rust, sysmlv2, v0.9.1); a claim true of one component names it. The OMG SysML v2 Pilot Implementation is the conformance baseline, not part of OpenSysML. Convention: AGENTS.md 1.2.
• Several statements that were true of the runtime only (for example about trigger-name resolution and cross-file import) would have become false under the broader name; each was checked against its DEFERRED.md entry and rewritten.
• Six lint rules (glossary/lint_rules.toml) now block the ambiguous patterns in learner prose.

3. Contribution policy (AGENTS.md 1.12, docs/contributor.md, .github/PULL_REQUEST_TEMPLATE.md)

• The contributions the project wants keep the tutorial current to its toolchain and to the OMG SysML v2 specifications. New chapters, notebooks, exercises, constructs, model elements, judgment records, glossary terms and learning outcomes are not accepted by pull request. Existing content may be improved only if the change is strictly dominant across spec conformance, didactic clarity and demonstrative tool use.

4. Protection against regressions in the edits themselves

• scripts/check-terminology-edit.py verifies that a prose-only change leaves models, judgment records, notebook code cells and stored outputs, DEFERRED.md headings, skill code fences and protected tokens alone.

Evidence

• CI on this branch (run 37171146381): build job green. 1882 tests passed (2 skipped: glossary tests that quote the source PDFs, which are gitignored), 59 pages built, all five gate checks passed, deploy skipped.
• Whole-branch regression gates (independent review on a different model, executed --strict builds of both base and head with the pinned tools): executed outputs identical across 59 content files; models/ and decisions/judgment-records/ byte-identical; the judgment record's content_hash still equals the model file's sha256; visible page text differs only on edited sources, and every changed line maps to an approved text.
• Content and code changes were built by one agent and reviewed independently by an agent on a different model; judgment calls were ruled and recorded. Two small mechanical edits (the PR template and the lint's unknown-key check) were verified directly and then covered by the whole-branch gates. The decision log entries are DL-111 to DL-129 in decisions/log.md.

Before merging

• Enable Pages: Settings, Pages, Source: GitHub Actions (repository admin; the deploy job fails until this is on).
• Confirm the open points in DL-129: one sentence in the Chapter 10 conclusion is the whole "in the notebooks" statement of the contribution policy; the three small readings of AGENTS.md 1.9 / "content" / "keep current"; and the defaults that 1.12 carries no pull-request exception.

Test plan

• build job green on this PR (provision, tests, executed strict build, release gate)
• deploy job skipped on this PR
• After merge, the main run: build green, deploy runs, the deploy step reports the Pages URL
• After deploy, smoke test: curl -sS -o /dev/null -w '%{http_code}' returns 200 for /toaster/, /toaster/setup, /toaster/glossary, /toaster/part-def, /toaster/interfaces, /toaster/judgment-synthesis; /toaster/interfaces.json and /toaster/judgment-synthesis.json contain image/svg+xml; no fetched page contains Documents/GitHub or /opt/homebrew

Known, not blocking

• The OpenSysML itself label in a Chapter 7 stored output stays (stored outputs are not edited in a prose pass); the prose around it explains it.
• A stale claim in decisions/diagram-survey.md is kept as dated evidence.
• glossary lint exits 1 on 77 pre-existing em-dash findings; it is not a CI gate, and the contributor guide asks for "no new hits against the base".
• The theme MyST downloads at build time is not pinned (survey finding F8, decisions/pages-publishing-survey.md); recorded there as a follow-up, not yet a tracked issue.

🤖 Generated with Claude Code

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[HuiJun]

I ran this through our agents and checked all the nits that it had, but seems they're all documented as well. We could also open a PR to bump the version once we have permission.