Diagram/text integration: diagrams replace reflection prints, trim whole-dump notebooks

.claude/skills/toaster-recipe/SKILL.md

@@ -15,7 +15,7 @@ The 7 cells below are the **required skeleton**. Additional markdown+code pairs
 |---|---|---|
 | **Concept** | Markdown | Exactly one sentence: "This notebook introduces X; after running it you can Y." |
 | **Context** | Markdown | One paragraph locating this notebook in the chapter arc. One link to prior notebook if model state carries over. |
-| **Model increment** | Code | Two-phase. (1) Declare the increment: Pattern A (Editor API, returns full model) or Pattern B (SysML string fragment for gap constructs). Assign to `TOASTER_INCREMENT`; print immediately as reflection. Only in construct-introducing notebooks — see scope table in `decisions/declarative-construction-plan.md`. (2) Load full chapter cumulative from `models/chXX-cumulative.sysml`; `assert model.ok`. |
+| **Model increment** | Code | Two-phase. (1) Declare the increment: Pattern A (Editor API, returns full model) or Pattern B (SysML string fragment for gap constructs). Assign to `TOASTER_INCREMENT`; it is not printed here — see "Construction cells" below for what fills the reflection step (the chapter's diagram or a confirmation query). Only in construct-introducing notebooks — see scope table in `decisions/declarative-construction-plan.md`. (2) Load full chapter cumulative from `models/chXX-cumulative.sysml`; `assert model.ok`. |
 | **Negative control** | Code + Markdown | Short bad_source string. `bad = conn.load_from_content(bad_source, strict=False)`. `assert not bad.ok`. Markdown: one sentence naming the error type and pointing to the diagnostic. |
 | **Demonstration** | Code + Markdown | One key operation per code cell. If two things happen, split into two cells each with its own narration markdown. |
 | **Seam** | Markdown | Exactly one sentence, addressing in behavior that the written construct, the tool that loaded it, and the rendered result are three distinct things the reader has just watched connect. Never names Tall or "the three worlds" (AGENTS.md 1.10) — see "Tall's three worlds" below. |
@@ -40,8 +40,10 @@ The construction zone replaces the single cell-02 with a sequence of code+markdo
 [code]     next fragment variable + printed         ← mirrors next editor.add_*() call
 [markdown] narration
 ...
-[code]     TOASTER_INCREMENT assembled + printed    ← reflection
+[code]     TOASTER_INCREMENT assembled (not printed)
            cumulative model loaded; assert model.ok ← for subsequent cells
+[markdown] bridge: what's about to be shown and why
+[code]     the chapter's diagram, or a model.find()/model.query() confirmation ← reflection
 ```
 
 **Fragment size rule:** ≤5 lines per fragment variable (ideally 1–3). If longer, split further.
@@ -87,9 +89,9 @@ POWER_ATTR = "    attribute power : ISQ::PowerValue default = 800.0 [SI::W];"
 print(POWER_ATTR)
 ```
 ```python
-# Cell: assembly + reflection + cumulative load
+# Cell: assembly + cumulative load (TOASTER_INCREMENT is assigned, not printed --
+# the reflection step is a diagram or confirmation query, shown in a later cell)
 TOASTER_INCREMENT = f"{HEATER_DEF}\n{POWER_ATTR}\n    ...\n}}"
-print(TOASTER_INCREMENT)
 
 source = Path("../../models/ch01-cumulative.sysml").read_text()
 model = conn.load_from_content(source, strict=False)
@@ -98,8 +100,14 @@ assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}"
 
 **Notes:**
 - `TOASTER_INCREMENT` = new declarations introduced by this notebook only (not the full model).
-- It is assembled from the named fragment variables and printed as the reflection.
-- 13 notebooks have construction cells; judgment, depth, navigation, analysis, param-sweep do not.
+- It is assembled from the named fragment variables and assigned, not printed. The reflection
+  step is the chapter's diagram where one exists, otherwise a confirmation query against the
+  construct just declared (`model.find()`/`model.query()`/`model.eval()`, or the
+  `src/toaster/query.py` helper where those surfaces do not see the construct).
+- Construction-introducing notebooks assign `TOASTER_INCREMENT` for their model fragment;
+  judgment notebooks that introduce a new `ReviewRecordRef` tag also assign it for that tag
+  fragment (DL-084). Python-only reconstruction, depth, navigation, analysis and param-sweep
+  notebooks do not assign it at all.
 - The cumulative model file is authored by A3 and must exist before A4 finalizes the assembly cell.
 
 ## Tall's three worlds (builder-facing lens; corrected DL-015/DL-050)
@@ -186,7 +194,7 @@ Identify required cells by content type, not by cell index — additional narrat
 
 - [ ] **Concept statement present:** exactly one sentence starting "This notebook introduces"; cell 0's own heading is level 1 (`#`), and the notebook's `metadata` carries `short_title: "ChN-NN"`
 - [ ] **Context cell present:** one paragraph with link to prior notebook (where applicable)
-- [ ] **Model increment cell present (construct-introducing notebooks only):** two-phase — (1) `TOASTER_INCREMENT` assigned and printed as reflection (Pattern A: `str(editor.apply())`; Pattern B: SysML fragment string); (2) full cumulative loaded from `models/chXX-cumulative.sysml`; `assert model.ok`. Judgment/depth/navigation/analysis notebooks: cell-02 loads cumulative only, no TOASTER_INCREMENT.
+- [ ] **Model increment cell present (construct-introducing notebooks only):** two-phase — (1) `TOASTER_INCREMENT` assigned, not printed (Pattern A: `str(editor.apply())`; Pattern B: SysML fragment string); the reflection step is the chapter's diagram or a confirmation query, not a reprint; (2) full cumulative loaded from `models/chXX-cumulative.sysml`; `assert model.ok`. Judgment notebooks introducing a new `ReviewRecordRef` tag: same rule, for the tag fragment (DL-084). Depth/navigation/analysis/param-sweep notebooks and Python-only judgment reconstructions: cell-02 loads cumulative only, no `TOASTER_INCREMENT`.
 - [ ] **Negative control present:** short bad_source inline; `assert not bad.ok`; markdown names the error type
 - [ ] **Demo cell(s) present:** one key operation per code cell; each code cell followed by markdown narration
 - [ ] **Seam present:** exactly one sentence addressing, in behavior, that the definition, the loading tool, and the printed result are three distinct things the reader just watched connect — never naming Tall, "the three worlds", A-F, O-S or E
@@ -201,12 +209,15 @@ own design purposes only:
 
 - **A-F:** the SysML declaration produced by the construction call or written as a string
 - **O-S:** `editor.apply()` (Pattern A) or `conn.load_from_content()` (Pattern B) executes it
-- **E:** `TOASTER_INCREMENT` printed as the reflection — the engineer sees the validated canonical SysML
+- **E:** the chapter's diagram, or a confirmation query against the construct just declared --
+  the engineer sees the validated canonical SysML reflected back by a real result, not a reprint
+  of the string from before it loaded
 
 The seam cell (slot 5) addresses the connection behaviorally, as above — for a Pattern A notebook
 that means pointing at what `editor.add_*()` produced and what running it validated; for Pattern B,
-at the `TOASTER_INCREMENT` string and what loading it validated. Neither the labels above nor "Tall"
-nor "three worlds" appear in the sentence itself.
+at the fragment variables already printed when declared and the diagram or confirmation query that
+shows what loading validated. Neither the labels above nor "Tall" nor "three worlds" appear in the
+sentence itself.
 
 ## What A4 must never do
 

.claude/skills/toaster-review-protocol/SKILL.md

@@ -109,7 +109,7 @@ Hawkins' taxonomy is answering, not by the dataclass's field order:
            print(SOME_TAG)
 [markdown] narration: this fragment is the same text now committed in the cumulative model
 [code]     TOASTER_INCREMENT = SOME_TAG   # or assembled with any other new fragment this notebook adds
-           print(TOASTER_INCREMENT)
+           # assigned, not printed -- the anchor fragment above was already printed when declared
 [markdown] narration: the claim itself comes next
 [code]     claim = "..."
            model_ref = "..."
@@ -147,9 +147,10 @@ Hawkins-taxonomy groups); five when it is a Python-only reconstruction that cite
 identifier from an earlier chapter (no new SysML, so no anchor groups, but `model=model` and the
 `Model tag` lookup still run, exercising the cross-representation check against the already-committed
 tag). Every code cell is still followed by a markdown cell narrating what's next (no two code cells
-adjacent). Each printed group is its own reflection, the same role a printed `TOASTER_INCREMENT`
-plays for a model fragment — and `TOASTER_INCREMENT` here really is the Hawkins record's own model-
-side anchor, assembled and loaded the same way any other chapter's model increment is.
+adjacent). Each printed group is its own reflection. `TOASTER_INCREMENT` here is the Hawkins record's own
+model-side anchor, assigned and checked the same way any other chapter's increment is -- not
+printed again, since the anchor fragment it's built from was already printed above; the
+`Model tag:` line printed when the record assembles is its confirmation.
 
 **Size limit:** `toaster-recipe`'s ≤600 words / ≤50 lines budget is sized for a notebook whose main
 content is one model construct. A notebook whose construct is a judgment record may exceed it — the

.claude/skills/tutorial-style-guide/SKILL.md

@@ -90,15 +90,22 @@ structure stays the same.
   # spec: SysML v2 formal/2026-03-02 §7.3.3
   TOASTING_SYSTEM_DEF = "abstract part def ToastingSystem;"
   ```
-- `TOASTER_INCREMENT` is assembled from the fragment variables in the final cell of the
-  construction zone; it equals the **new declarations for this notebook only** (not the full
-  cumulative model). Print it as the reflection.
+- `TOASTER_INCREMENT` is assembled from the fragment variables in the final construction cell
+  and equals the **new declarations for this notebook only** (not the full cumulative model).
+  It is assigned, not printed: each fragment was already printed when declared, and
+  `scripts/check_construction.py` reads the assignment, never the print. The reflection -- the
+  result the seam cell points at -- is the chapter's diagram where one exists; otherwise a short
+  confirmation query against the construct just declared (`model.find()`/`model.query()`/
+  `model.eval()`, or the `src/toaster/query.py` helper for constructs those surfaces do not see:
+  `get_review_record_refs` for metadata usages, `satisfy_relationships` for `assert satisfy`,
+  `find_allocations`/`perform_relationships` for allocations and performs), added if none exists.
 - The cumulative load (`conn.load_from_content(ch0X-cumulative.sysml)`) happens in the same
-  final cell, after printing `TOASTER_INCREMENT`.
+  final cell as the assignment.
 - `conn.close()` belongs at the end of the last code cell in the notebook (cell-04 or later),
   never in the construction zone.
-- Judgment, depth, navigation, analysis, and param-sweep notebooks have no construction zone
-  and do not assign `TOASTER_INCREMENT`.
+- Judgment notebooks that introduce a new `ReviewRecordRef` tag assign (not print)
+  `TOASTER_INCREMENT` as the tag fragment(s), per DL-084. Python-only reconstruction, depth,
+  navigation, analysis and param-sweep notebooks do not assign it at all.
 
 ## What every agent loading this skill must never do
 

DEFERRED.md

@@ -690,7 +690,7 @@ committed to `models/`), restating only `deliveredEnergyBoundedBySupply` and the
 two usages it needs, which carries no `assert satisfy` declaration and so never
 hits this parser gap. The construct itself is real, committed content in
 `models/ch08-cumulative.sysml` (introduced in
-`chapters/ch08-checking/01-invariant-def.ipynb`); only the file handed to
+`chapters/ch08-checking/01-assert-constraint-def.ipynb`); only the file handed to
 `verify_holds` is a restatement, and the notebook says so. See D-030 and D-031 for
 the separate, deeper reason this construct is a hand-restated lemma rather than a
 solver-checked reference to `HeatGenerator`'s own `efficiencyBounded` and
@@ -795,7 +795,7 @@ checked reference to them, and re-checking it after either original element
 changes is a manual, not automatic, step.
 
 **Workaround:** `deliveredEnergyBoundedBySupply`'s own doc comment, and Chapter 8's
-prose (`chapters/ch08-checking/01-invariant-def.ipynb`,
+prose (`chapters/ch08-checking/01-assert-constraint-def.ipynb`,
 `02-violation-witness.ipynb`, `index.md`, `conclusion.md`), state this limit
 plainly rather than claiming a link the toolchain cannot check.
 **Resolution:** none attempted; would need `verify --solve` (or a successor tool)

chapters/ch01-system-purpose/01-abstract-def.ipynb

@@ -111,7 +111,7 @@
    "metadata": {},
    "outputs": [],
    "execution_count": null,
-   "source": "TOASTER_INCREMENT = f\"{BREAD_DEF}\\n{TOAST_DEF}\\n{TOASTBREAD_DEF}\\n{TOASTING_SYSTEM_DEF}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\""
+   "source": "TOASTER_INCREMENT = f\"{BREAD_DEF}\\n{TOAST_DEF}\\n{TOASTBREAD_DEF}\\n{TOASTING_SYSTEM_DEF}\"\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\""
   },
   {
    "cell_type": "markdown",

chapters/ch01-system-purpose/02-part-def.ipynb

@@ -70,7 +70,7 @@
    "metadata": {},
    "outputs": [],
    "execution_count": null,
-   "source": "TOASTER_INCREMENT = f\"{HEATING_SYS_DEF}\\n{CONTROL_SYS_DEF}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\""
+   "source": "TOASTER_INCREMENT = f\"{HEATING_SYS_DEF}\\n{CONTROL_SYS_DEF}\"\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\""
   },
   {
    "cell_type": "markdown",

chapters/ch01-system-purpose/03-specialization.ipynb

@@ -54,7 +54,7 @@
    "metadata": {},
    "outputs": [],
    "execution_count": null,
-   "source": "TOASTER_INCREMENT = TOASTER_SPEC_DEF\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\""
+   "source": "TOASTER_INCREMENT = TOASTER_SPEC_DEF\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\""
   },
   {
    "cell_type": "markdown",

chapters/ch01-system-purpose/04-composition.ipynb

@@ -86,7 +86,7 @@
    "metadata": {},
    "outputs": [],
    "execution_count": null,
-   "source": "TOASTER_INCREMENT = f\"{TOASTER_DEF}\\n{CYCLE_TIME_ATTR}\\n{HEATING_PART}\\n{CONTROL_PART}\\n}}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\""
+   "source": "TOASTER_INCREMENT = f\"{TOASTER_DEF}\\n{CYCLE_TIME_ATTR}\\n{HEATING_PART}\\n{CONTROL_PART}\\n}}\"\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\""
   },
   {
    "cell_type": "markdown",
@@ -165,7 +165,7 @@
    "id": "cell-13",
    "metadata": {},
    "source": [
-    "`part def Toaster :> ToastingSystem { ... }` printed above loaded without error, and `toaster.parts()` returns the two part symbols shown below, confirming the composition is now part of the model."
+    "The assembled `Toaster` declaration loaded without error, and the diagram above confirms `heating` and `control` are part of the model."
    ]
   },
   {

chapters/ch02-requirements/01-requirement-def.ipynb

@@ -99,7 +99,7 @@
   {
    "cell_type": "code",
    "id": "e77ee323",
-   "source": "TOASTER_INCREMENT = f\"{TIMELY_TOAST_REQ}{CONSTRAINT_BODY}\\n}}\\n{NOMINAL_PART}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch02-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"",
+   "source": "TOASTER_INCREMENT = f\"{TIMELY_TOAST_REQ}{CONSTRAINT_BODY}\\n}}\\n{NOMINAL_PART}\"\nsource = Path(\"../../models/ch02-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"",
    "metadata": {},
    "execution_count": null,
    "outputs": []
@@ -167,7 +167,7 @@
    "cell_type": "markdown",
    "id": "cell-06",
    "metadata": {},
-   "source": "The `requirement def TimelyToast { doc /* ... */ subject toaster : Toaster; require constraint { toaster.cycleTime <= 180.0 [SI::s] } }` printed above loaded without error, and `model.find()` returns its symbol while `model.query()` lists it as a `RequirementDefinition`, confirming it's now part of the model."
+   "source": "The `TimelyToast` fragments printed above loaded without error, and `model.find()`/`model.query()` confirm it's now part of the model."
   },
   {
    "cell_type": "markdown",

chapters/ch02-requirements/02-assumptions.ipynb

@@ -68,7 +68,7 @@
   {
    "cell_type": "code",
    "id": "ec2c4402",
-   "source": "TOASTER_INCREMENT = f\"{SLOW_PART}\\n{CYCLE_OVERRIDE}\\n}}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch02-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"",
+   "source": "TOASTER_INCREMENT = f\"{SLOW_PART}\\n{CYCLE_OVERRIDE}\\n}}\"\nsource = Path(\"../../models/ch02-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"",
    "metadata": {},
    "execution_count": null,
    "outputs": []
@@ -138,7 +138,7 @@
    "cell_type": "markdown",
    "id": "cell-06",
    "metadata": {},
-   "source": "The `part slow : Toaster { attribute :>> cycleTime = 200.0 [SI::s]; }` printed above loaded without error, and `slow.attributes()` returns the overridden symbol shown above, confirming the redeclaration is now part of the model."
+   "source": "The `slow` fragments printed above loaded without error, and `slow.attributes()` confirms the override is now part of the model."
   },
   {
    "cell_type": "markdown",