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

.claude/skills/ace-protocol/SKILL.md

@@ -60,7 +60,7 @@ Frame decisions the way Z thinks: an **objective** (what is good and good enough
 | SA-3 | Energy model = `Q = ηPt`, sympy+numpy+matplotlib for the base tutorial. scipy is permitted if it is the right tool for the job. |
 | SA-4 | Single-platform CI (ubuntu-latest) |
 | SA-5 | Default book-theme, no custom CSS |
-| SA-6 | Bounded model checking: opensysml `check` engine only |
+| SA-6 | Bounded model checking: opensysml `check` engine only (the runtime's engine; for "holds" questions Z accepted sysml-toolkit's `sysmlv2 verify --solve` wrapped by `toaster.modelcheck`: DL-046, D-025) |
 | SA-7 | All judgment records are worked examples; `disposition` stays `"pending"` |
 | SA-8 | One new construct or analysis operation per sub-notebook; depth notebooks may introduce neither |
 | SA-9 | DOT for sequences/relationships; SysMLD first-class for interconnection; PlantUML for action flow; Matplotlib for quantitative; never Mermaid |
@@ -127,9 +127,9 @@ Earlier entries with a single `Rationale:` line pre-date this format.
 ## Escalate to Z
 
 - SA challenge without an obvious "no" — e.g., renderer limitation that genuinely threatens a learning outcome
-- Licensing questions (GPL PlantUML, pilot EPL-2.0, redistribution)
+- Licensing questions (GPL PlantUML, the OMG SysML v2 Pilot Implementation's EPL-2.0, redistribution)
 - Spec ambiguity spanning multiple chapters, not resolvable by existing SAs
-- Required opensysml capability missing from v0.9.0 with no workable simplification
+- Required OpenSysML runtime capability missing from v0.9.0 with no workable simplification
 - A request to change a confirmed glossary definition or to approve a `differsFrom`: only Z acts. If Z's recorded positions show the change is wrong, decline it yourself and log it (nothing changes, so Z need not act); if you cannot tell whether the change would be right, escalate
 - Any question the frameworks and principles in `z-principles.md` do not determine (the default for the unknown)
 - A proposal to reopen an SA rule

.claude/skills/ace-protocol/z-model.md

@@ -18,7 +18,7 @@ Every item below is something Z said or approved in this session. Cite an item a
 
 ## Sources and definitions
 - Z-11. Canonical sources take priority; own definitions appear only as contextual refinements where necessary, to make learning easier. Never make things up. Never teach something misaligned with canon. The sources are complementary KINDS of definition, not rivals: SEBoK gives the idea (conceptual, generic), the OMG specs give formal and checkable semantics, Douglas gives analogy and story (didactic, aligned with as far as possible to lower cognitive cost). They are treated as non-contradicting. Our tutorial edge is the bridge. Do not phrase a ruling as one source "governing" another; say which kind of definition is needed.
-- Z-12. OpenSysML and other implementations are toolchain, cited only to flag spec gaps. Tall's three worlds and the optimization/control lens are builder-facing and never named in learner content.
+- Z-12. OpenSysML and other implementations are toolchain, cited only to flag spec gaps. Tall's three worlds and the optimization/control lens are builder-facing and never named in learner content. [Reading note, 2026-10-03, DL-116/DL-117: said when this repository used "OpenSysML" for the runtime; it now names the stack whose components the tutorial uses are the OpenSysML runtime and sysml-toolkit. The position holds under both readings.]
 - Z-13. Douglas says what / who / where; the tutorial's what / how / where is Z's own sharpening and must be presented as such (attribute it plainly).
 - Z-14. SEBoK's "logical architecture" contains the functional view; the tutorial's "logical" is therefore a `differsFrom` edge, and Z APPROVED that departure in planning ("differsFrom, approved"). Learners are told the word is used more narrowly than in SEBoK.
 - Z-15. Mechanism and policy are grounded in public canonical texts (Astrom and Murray; Sutton and Barto), not in Z's own generalized-dynamical-systems paper (which informs Z's thinking but is not a canonical source). Neither text uses the word "mechanism" in Z's sense, so the tutorial's "mechanism" is a recorded refinement of the input/output dynamics definitions, word and determinism emphasis marked as ours.

.claude/skills/opensysml-api/SKILL.md

@@ -3,7 +3,7 @@ name: opensysml-api
 description: opensysml v0.9.0 interface — correct method names, return shapes, limitations, and the D-001 encapsulation rule.
 ---
 
-# OpenSysML v0.9.0 API
+# The OpenSysML runtime v0.9.0 API
 
 ## Connection
 

.claude/skills/opensysml-query/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: opensysml-query
-description: Tested cookbook for interrogating a loaded SysML v2 model with OpenSysML v0.9.0 (three surfaces, what each sees, id formats, recipes, what does not work and the workaround). Snippets are executed by tests/test_skill_snippets.py.
+description: Tested cookbook for interrogating a loaded SysML v2 model with the OpenSysML runtime v0.9.0 (three surfaces, what each sees, id formats, recipes, what does not work and the workaround). Snippets are executed by tests/test_skill_snippets.py.
 ---
 
-# Querying a model (OpenSysML v0.9.0)
+# Querying a model (the OpenSysML runtime v0.9.0)
 
 SysML v2 is declarative and database-like (AGENTS.md 1.4): we build a model, then ask it questions. There are three surfaces, and none of them sees everything. Pick by what you need to see. Results and dates are in `decisions/probes.md`; gap ids (G1 to G7) are in `decisions/log.md` DL-015.
 
@@ -129,7 +129,7 @@ assert satisfies()
 
 ## Recipe 5: a staged conformance check (port types on connected ends)
 
-OpenSysML accepts a connection between ports of unrelated types with no diagnostic (gap G4, `decisions/probes.md`), and the KerML text searched has no validation constraint for it. So this is a **project conformance check**, not a language one (AGENTS.md 1.9): apply it from the chapter and section where the connection is declared complete, keep a negative control that shows it catching a fault, and report it as *open* before then.
+The OpenSysML runtime v0.9.0 and sysml-toolkit v0.9.1 both accept a connection between ports of unrelated types with no diagnostic (gap G4, `decisions/probes.md`), and the KerML text searched has no validation constraint for it. So this is a **project conformance check**, not a language one (AGENTS.md 1.9): apply it from the chapter and section where the connection is declared complete, keep a negative control that shows it catching a fault, and report it as *open* before then.
 
 ```python
 def feature_type_names(feature_qn):
@@ -174,7 +174,7 @@ The API JSON `@id` uses `__` for `::` and escapes `_` (`named_flow` becomes `nam
 | `conn.load(path)` exists but does not resolve imports either | Same workaround. |
 | Writing these joins by hand in a notebook | Import the tested helpers from `toaster.query`: `find_connectors`, `find_allocations`, `allocations_for`, `satisfy_relationships`, `perform_relationships`, `requirement_coverage`, `specializes_transitively`, `port_type_mismatches`. The recipes above show what they do; `tests/test_query.py` covers them against `models/ch08-cumulative.sysml`. |
 
-The sysml-toolkit Python binding (`sysmlv2.Session.from_files`) does resolve imports across files and sees unnamed elements through `elements_of_metaclass`. It is toolchain, not a chapter dependency (see `decisions/probes.md`).
+The sysml-toolkit Python binding (`sysmlv2.Session.from_files`) does resolve imports across files and sees unnamed elements through `elements_of_metaclass`. It is toolchain, not a chapter dependency: every notebook loads its model through the OpenSysML runtime, and Chapters 5, 8 and 10 use sysml-toolkit only through its `sysmlv2` binary (`viz` in Chapter 5, `verify --solve` in Chapters 8 and 10; DL-118 B3/B4), not through this binding (see `decisions/probes.md`).
 
 ## Before you assert something works
 

.claude/skills/sysml-diagrams/SKILL.md

@@ -13,15 +13,15 @@ Use one default pipeline for each figure type. Read only the relevant recipe in
 
 | Question / figure type | Default pipeline | Why |
 |---|---|---|
-| What is the system made of? Definition and decomposition view | `model_to_dot()` (in-house, `src/toaster/render.py`) → Graphviz SVG | Draws the whole model's containment graph from a full `model.query()`, not one root's direct children — a real-fixture rerun of the diagram trade study (`decisions/diagram-study-real-fixtures.md`) found the OMG pilot fails on all real chapter content (qualified-name `allocate` targets), and rendering a single root via OpenSysML's `#tree:` form only shows that root's own direct features, one level deep. |
+| What is the system made of? Definition and decomposition view | `model_to_dot()` (in-house, `src/toaster/render.py`) → Graphviz SVG | Draws the whole model's containment graph from a full `model.query()`, not one root's direct children — a real-fixture rerun of the diagram trade study (`decisions/diagram-study-real-fixtures.md`) found the OMG SysML v2 Pilot Implementation fails on all real chapter content (qualified-name `allocate` targets), and rendering a single root via the OpenSysML runtime's `#tree:` form only shows that root's own direct features, one level deep. |
 | How do parts connect through ports? Interconnection view | Model query → `render_interconnection()` (in-house, `src/toaster/render.py`; the same real-fixture study found the actual third-party SysMLD tool cannot index real content at all) → Graphviz SVG | Draws part connectivity, port identity (as edge labels), and allocations, with zero dependency on a tool proven unreliable on real content. **Use sysml-toolkit instead specifically when port identity itself is the chapter's own pedagogical point** (e.g. a chapter introducing or exercising a conjugated port) — it draws real port names as their own boxes, not folded into one edge label, confirmed on every real fixture tested (`decisions/diagram-study-real-fixtures.md`). Otherwise default to the in-house renderer: a chapter using interconnection only to show an allocation or a connection, where port identity is not itself the point, does not need the extra external-binary dependency (`decisions/diagram-survey.md`, Ch5-vs-Ch6 example). |
-| What happens next? Action-flow view | OpenSysML CLI, `-render #action:element -render-form dot` → Graphviz SVG | Confirmed directly against real chapter content (Ch6's `ApplyHeat` action): exit 0, real action-flow notation. No in-house action-flow renderer exists yet. |
-| How does behavior change with events? State-transition view | OpenSysML CLI, `-render #state:element -render-form dot` → Graphviz SVG | The real-fixture study confirmed this directly against Ch7's real `Cycle` state machine — 100% success across both OpenSysML render forms. The OMG pilot (this table's earlier default) fails on all real chapter content; do not use it. |
-| Who sends what, in what order? Sequence view | OpenSysML sequence query → DOT → Graphviz SVG | White background, relationship-consistent rendering, no Mermaid dependency. Provisional: no chapter's real model has a `FlowUsage` yet, so this pipeline has not been exercised against real content. Fallback: PlantUML if `opensysml -render-form dot` unsupported for sequences (confirmed at WP-1 and documented below). |
+| What happens next? Action-flow view | OpenSysML runtime CLI, `-render #action:element -render-form dot` → Graphviz SVG | Confirmed against real chapter content (Ch4's `ToastBread`, Ch6's `ApplyHeat`): exit 0 and the control sequence is drawn, but the CLI's DOT omits the actions' declared typed flows (D-037); the caption must say so. No in-house action-flow renderer exists yet. |
+| How does behavior change with events? State-transition view | OpenSysML runtime CLI, `-render #state:element -render-form dot` → Graphviz SVG | The real-fixture study ran this against Ch7's real `Cycle` state machine: both OpenSysML runtime render forms exit 0 and draw the states and transitions, but the `do` activity label omits the performed action's name (D-037); the caption must say so. The pilot (this table's earlier default) fails on all real chapter content; do not use it. |
+| Who sends what, in what order? Sequence view | OpenSysML runtime sequence query → DOT → Graphviz SVG | White background, relationship-consistent rendering, no Mermaid dependency. Provisional: no chapter's real model has a `FlowUsage` yet, so this pipeline has not been exercised against real content. Fallback: PlantUML if `opensysml -render-form dot` unsupported for sequences (confirmed at WP-1 and documented below). |
 | Which requirement or function relates to which element? Traceability graph | Model query → Graphviz DOT → SVG | Explicit typed relationships and controllable grouping. Use a table when the purpose is exhaustive coverage. |
 | How does a modeled quantity change? Scientific plot | Model execution results → Matplotlib → SVG | Axes, units, reference values, and parameter comparisons. |
 
-These are working defaults for this tutorial, not universal tool rankings, and are grounded in `decisions/diagram-study-real-fixtures.md` (a rerun of the original trade study against real chapter models, not the simplified toy fixture the original comparison used). Keep the same pipeline for a given figure type throughout the book. An unsupported construct warrants an explicit recipe change; a crowded figure usually warrants a smaller scope or better layout. **Never use the OMG pilot or the third-party SysMLD/sysml2d tool for real chapter content** — both are confirmed, on real content, to fail entirely (pilot: qualified-name `allocate` targets; SysMLD: an indexer bug that mis-tracks brace scope on ordinary real syntax like a doc-comment block or an `assert constraint` body).
+These are working defaults for this tutorial, not universal tool rankings, and are grounded in `decisions/diagram-study-real-fixtures.md` (a rerun of the original trade study against real chapter models, not the simplified toy fixture the original comparison used). Keep the same pipeline for a given figure type throughout the book. An unsupported construct warrants an explicit recipe change; a crowded figure usually warrants a smaller scope or better layout. **Never use the pilot or the third-party SysMLD/sysml2d tool for real chapter content** — both are confirmed, on real content, to fail entirely (pilot: qualified-name `allocate` targets; SysMLD: an indexer bug that mis-tracks brace scope on ordinary real syntax like a doc-comment block or an `assert constraint` body).
 
 ## Make a figure recipe
 
@@ -53,15 +53,15 @@ Use white backgrounds, readable typography, restrained color, and consistent nam
 
 - **DOT/Graphviz** — default for structure, interconnection, sequence, and relationship diagrams
 - **`render_interconnection()`** (in-house, `src/toaster/render.py`) — first-class for port-level interconnection; the intent dict is built from `model.query()` + `model.to_api_json()`. This function does not use, and never used, the third-party SysMLD tool — see the real-fixture study for why that tool is now confirmed unusable on real content.
-- **OpenSysML CLI (`-render-form dot`)** — action flow and state views, confirmed directly against real chapter content
+- **OpenSysML runtime CLI (`-render-form dot`)** — action flow and state views, confirmed directly against real chapter content
 - **Matplotlib** — quantitative figures only
 - **Mermaid** — NOT used anywhere in this tutorial
-- **The OMG pilot** — NOT used anywhere in this tutorial; confirmed to fail on all real chapter content (qualified-name `allocate` targets)
+- **The OMG SysML v2 Pilot Implementation** — NOT used anywhere in this tutorial; confirmed to fail on all real chapter content (qualified-name `allocate` targets)
 - **The third-party SysMLD/sysml2d tool** — NOT used anywhere in this tutorial; confirmed to fail to index any real chapter content (an indexer bug, see `decisions/log.md` DL-055)
 
-**A note on an earlier finding, corrected by the real-fixture study (`decisions/diagram-study-real-fixtures.md`):** an earlier probe (WP-1, 2026-09-25, against a small hand-written test model, not a real chapter model) found opensysml had no native DOT or render-form CLI, and that finding drove a stopgap of generating DOT directly from `model.query()` output for the structure view. That stopgap (`model_to_dot()`) is still the right choice for structure specifically (it draws the whole model, not one root), but the earlier finding about OpenSysML's CLI itself no longer holds: the pinned binary's `-render #kind:element -render-form dot` (or `plantuml`) form is real, works on real chapter content (confirmed for both action-flow and state views), and is simply undocumented in the binary's own `-help` output.
+**A note on an earlier finding, corrected by the real-fixture study (`decisions/diagram-study-real-fixtures.md`):** an earlier probe (WP-1, 2026-09-25, against a small hand-written test model, not a real chapter model) found the OpenSysML runtime had no native DOT or render-form CLI, and that finding drove a stopgap of generating DOT directly from `model.query()` output for the structure view. That stopgap (`model_to_dot()`) is still the right choice for structure specifically (it draws the whole model, not one root), but the earlier finding about the OpenSysML runtime's CLI no longer holds: the pinned binary's `-render #kind:element -render-form dot` (or `plantuml`) form is real, works on real chapter content (confirmed for both action-flow and state views), and is simply undocumented in the binary's own `-help` output.
 
-For action flow and state: OpenSysML's own `-render` CLI, not a custom Python renderer — none exists yet for action flow, and none is needed.
+For action flow and state: the OpenSysML runtime's own `-render` CLI, not a custom Python renderer — none exists yet for action flow, and none is needed.
 For interconnection: `render_interconnection()`'s intent dict, built from `model.query()` + `model.to_api_json()` (unchanged from WP-4; only the function's name changed, since it never depended on the tool its old name implied).
 Never use Mermaid as a fallback for anything.