docs(self-model): model the MCP server, Jupyter kernel, JSON-RPC commands, notebook packages, markup parsers and FMI gate

.agents/skills/testing-pilot-corpora-gate/SKILL.md

@@ -187,7 +187,7 @@ gate's own helpers are package-private but reusable (`pilotCorporaGate.files(t)`
 `actionlint`, `shellcheck`, `python3 scripts/check-doc-links.py`, `gofmt`, `go vet`,
 `go run -C tools ./cmd/pilot-diff` (validators pre-downloaded; ~4min, prints e.g.
 the headline the committed baseline holds — `920 file(s), 521 fully agreeing; 1098 agreed
-diagnostic(s), 359 only ours, 2448 only the pilot's` at the `2026-08` pin, so read it from
+diagnostic(s), 359 only ours, 2450 only the pilot's` at the `2026-08` pin, so read it from
 `docs/project/pilot-differential-baseline.json` rather than from this line)
 and `make lint` (staticcheck+gosec, ~2min) all work. There is **no** `yamllint` and **no**
 `circleci` CLI, so `.circleci/config.yml` can only be parsed as YAML, not schema-validated — say so

.agents/skills/testing-pilot-differential/SKILL.md

@@ -28,7 +28,7 @@ GNU-format diagnostics **relative to `--root`**. Consequences for testing:
   (`passes/literal_infinity.sysml`: `*` bound to a Boolean, a String, a part and an enumeration is
   our `binding-connector-type-conformance` error where the pilot warns, four severity-only pairs, and
   its `Integer[2] = *` count error is one only-ours row): `920 file(s), 521 fully agreeing; 1098 agreed,
-  359 only ours, 2448 only the pilot's`, JSON totals `openSysMLDiagnostics 1468 / pilotDiagnostics 3557 /
+  359 only ours, 2450 only the pilot's`, JSON totals `openSysMLDiagnostics 1468 / pilotDiagnostics 3559 /
   severityMismatch 11`; the two only-ours rows the multiplicity rule added are the expected `action-step-multiplicity-not-fixed`
   warnings on `training/18. Action Performance/Action Performance Example.sysml:10` and
   `pilot-examples/Camera Example/Camera.sysml:4`. ~2 min wall, byte-identical across runs *and* after a from-scratch rebuild of
@@ -153,7 +153,7 @@ warning (the `[1]` `RocketEquation` inputs still produce the warning at
 `takePicture[*]` in `Camera Example/Camera.sysml`, and the view concern framing round retired the
 six view-body `frame` `syntax` rows on `examples`, and the unbounded-literal typing round added
 `passes/literal_infinity.sysml` (four severity-only pairs, one only-ours count error); a live run gives `920 file(s), 521 fully
-agreeing; 1098 agreed, 359 only ours, 2448 only the pilot's`, byte-identical to the committed baseline, and
+agreeing; 1098 agreed, 359 only ours, 2450 only the pilot's`, byte-identical to the committed baseline, and
 `docs/project/pilot-differential.md`'s "Results" table matches. The prior rebaseline, when the
 Legend of the Red Dragon example left for its own repository, gave
 <!-- doc-count:historical -->`920 file(s), 517 fully agreeing; 1098 agreed, 366 only ours, 2448 only the pilot's`.

.agents/skills/testing-pilot-execution-referee/SKILL.md

@@ -155,7 +155,7 @@ pilot answers the representation's own. See
   such file or directory`.
 - **Additivity.** `go run -C tools ./cmd/pilot-diff` must still print the headline the
   committed baseline holds (`920 file(s), 521 fully agreeing; 1098 agreed
-  diagnostic(s), 359 only ours, 2448 only the pilot's` at the `2026-08` pin — read it from the baseline JSON, not from this line, since each
+  diagnostic(s), 359 only ours, 2450 only the pilot's` at the `2026-08` pin — read it from the baseline JSON, not from this line, since each
   fix round moves it) and `jq -S` diff clean against
   `docs/project/pilot-differential-baseline.json`; `git status --porcelain`
   empty at the end.

.agents/skills/testing-pilot-xpect/SKILL.md

@@ -426,7 +426,7 @@ census in `w5c_census_test.go` is live two ways: perturb one pinned triple (e.g.
 
 `go run -C tools ./cmd/pilot-diff` (~1m12s) must still print the headline the *committed* baseline holds —
 at the `2026-08` pin that is `920 file(s), 521 fully agreeing; 1098 agreed diagnostic(s), 359
-only ours, 2448 only the pilot's`. Read the number out of
+only ours, 2450 only the pilot's`. Read the number out of
 `docs/project/pilot-differential-baseline.json` rather than trusting this line, since a landing fix
 round moves it. When the baseline is itself stale (it was at `19a3ce03`, holding 273 / 281 / 317), a
 failing `cmp` against it is *not* evidence of an Xpect regression — compare the summary line, and see

README.md

@@ -346,11 +346,11 @@ The project is under active development, with the core infrastructure operationa
 <!-- doc-counts:begin refereed-figures -->
 **Measured against the pinned reference** (`PILOT_TAG=2026-08`, artifact `0.62.0`). Every number below is generated by `make docs-counts` from the committed baselines and gated; none of them is typed in by hand.
 
-- **Corpus agreement:** 521 of 920 files agree diagnostic-by-diagnostic; 359 diagnostics are ours alone and 2448 the reference's alone, and the first number must be read by root: the aggregate includes candidate conformance differences, intentional execution-scope warnings on reference corpora and diagnostics from our own examples ([differential](docs/project/pilot-differential.md), `go run -C tools ./cmd/pilot-diff`).
+- **Corpus agreement:** 521 of 920 files agree diagnostic-by-diagnostic; 359 diagnostics are ours alone and 2450 the reference's alone, and the first number must be read by root: the aggregate includes candidate conformance differences, intentional execution-scope warnings on reference corpora and diagnostics from our own examples ([differential](docs/project/pilot-differential.md), `go run -C tools ./cmd/pilot-diff`).
 - **Declared-diagnostic silence:** of the 512 declared `errors` rows in the reference's own Xpect suites, we report nothing for 0. 245 we report word-for-word; 248 wording-only and 7 location-only differences are agreement in substance and are not counted as gaps; 0 more we report as a warning and 2 elsewhere in the file ([Xpect oracle](docs/project/pilot-xpect.md), `go run -C tools ./cmd/pilot-xpect`).
 - **Scope agreement:** 230 of 230 declared scope assertions match exactly (same source).
 - **Permissiveness gaps:** of 349 invalid models we wrote ourselves, the reference rejects 5 that we accept by default, and 332 both reject; 5 further cases agree only when we are asked strictly. We authored every one of these cases ourselves, so the denominator measures the reach of our own corpus and not our conformance; agreement reached only under an opt-in strict mode is weaker evidence than agreement by default ([rejection oracle](docs/project/pilot-rejection.md), `go run -C tools ./cmd/pilot-reject`).
-- **Declared errata:** the registry declares 16 defect(s) in the published reference material — 9 with a specification-derived correction, 7 documented without one, since no intended reading can be inferred ([OMG issues](docs/project/omg-issues.md), `tools/oracle/errata`). Every figure above is as published and stays the conformance statement; running the same oracles over the corrected text instead reports 522 of 920 files agreeing, 358 diagnostics ours alone and 2448 the reference's alone, 0 declared rows we are silent on, and 0 of 349 authored cases the reference alone rejects. The corrected figures are diagnostic only: an erratum never reclassifies a divergence category, and the published corpus is never edited.
+- **Declared errata:** the registry declares 16 defect(s) in the published reference material — 9 with a specification-derived correction, 7 documented without one, since no intended reading can be inferred ([OMG issues](docs/project/omg-issues.md), `tools/oracle/errata`). Every figure above is as published and stays the conformance statement; running the same oracles over the corrected text instead reports 522 of 920 files agreeing, 358 diagnostics ours alone and 2450 the reference's alone, 0 declared rows we are silent on, and 0 of 349 authored cases the reference alone rejects. The corrected figures are diagnostic only: an erratum never reclassifies a divergence category, and the published corpus is never edited.
 - **Self-assessed surface:** the action, state-machine and classifier-behavior rows have no external referee at all — the four refereed figures above cannot see them, because the pinned artifact evaluates expressions but executes neither actions nor state machines. [Spec compliance](docs/project/spec-compliance.md) counts them.
 
 What these numbers cannot show: the OMG corpora are demonstrations rather than an official conformance suite; the differential is one-directional, comparing the diagnostics the two implementations report on the same files; the Xpect suites are the pilot authors' test intent rather than a certification oracle; and none of these is a percentage of the specification — no global compliance figure is claimed anywhere.

changes/unreleased/document-whole-bodies.added.md

@@ -0,0 +1 @@
+- Whole-document markup bodies: a Markdown or AsciiDoc `rep` in a `Document` or `Section` may now carry headings (`#`…`######`, `==`…), which open `Section`s nested by level in place among the sibling parts, so one body can write a whole document outline. The first heading met is one level below the owner; a heading that skips a level or rises above the body's base is the new `document-plan-markup-heading-level` planning error, and a heading in a `part : Paragraph` body stays refused. Each such section is named by its AsciiDoc `[[id]]`/`[#id]`, else by a slug of its title (lower-cased, runs of other characters one underscore, `_2`, `_3`… on a repeat), and `[](sysml:<name>)`, `sysml:ref[<name>]`, `<<name>>` and `sysml:<Document>::<name>` from another document resolve to it; numbering, tables of contents and title pages treat it as any section.

cmd/sysml/manual_examples_test.go

@@ -34,6 +34,38 @@ func TestManualWorkedExampleMatchesCommittedOutput(t *testing.T) {
 	}
 }
 
+// TestManualWholeDocumentExampleMatchesCommittedOutput renders the manual's
+// whole-document example, whose outline is one Markdown body, and compares it
+// against the committed output.
+func TestManualWholeDocumentExampleMatchesCommittedOutput(t *testing.T) {
+	binary := buildCLI(t)
+	examples := filepath.Join("..", "..", "docs", "manual", "examples")
+	committed, err := os.ReadFile(filepath.Join(examples, "whole-document.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := filepath.Join(t.TempDir(), "whole-document.md")
+	cmd := exec.Command(binary, filepath.Join(examples, "whole-document.sysml"), "-render-document", "Whole::MassReport", "-o", out)
+	if output, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("render: %v\n%s", err, output)
+	}
+	written, err := os.ReadFile(out)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(written) != string(committed) {
+		t.Errorf("rendered whole-document example differs from docs/manual/examples/whole-document.md:\n%s", written)
+	}
+	for _, want := range []string{
+		"## Overview", "### Mass budget", "#### Margins", "## Design", "## Appendix", "### Derivation",
+		"[Mass budget](#overview-mass_budget)", "[Mass budget](#overview-mass_budget_2)",
+	} {
+		if !strings.Contains(string(written), want) {
+			t.Errorf("rendered whole-document example lacks %q", want)
+		}
+	}
+}
+
 // TestManualProseExampleMatchesCommittedOutput renders the manual's Markdown
 // prose example, whose paragraphs and lists are `rep language "markdown"`
 // bodies, and compares it against the committed output.

cmd/sysml/render_document_whole_bodies_test.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+const wholeBodiesFixture = "../../internal/doc/docrender/testdata/whole_report.sysml"
+
+// wholeBodiesNotes is a second document whose only section is markup-born, so
+// a cross-document reference has to resolve to a generated section.
+const wholeBodiesNotes = `
+	part def Notes :> Document {
+		:>> title = "Notes";
+
+		rep language "markdown" /* # Shared notes
+		 *
+		 * The report's [budget](sysml:WholeReport::mass_budget) is kept there.
+		 */
+	}
+`
+
+// TestRenderDocumentWholeBodies renders a report whose outline is one
+// Markdown body: its headings are sections the title page, table of contents
+// and numbering options treat exactly as the part-born section after them.
+func TestRenderDocumentWholeBodies(t *testing.T) {
+	binary := buildCLI(t)
+	source, err := os.ReadFile(wholeBodiesFixture)
+	if err != nil {
+		t.Fatal(err)
+	}
+	model := string(source)
+
+	wantReport(t, check(t, binary, model, "-render-document", "Whole::WholeReport"), 0,
+		"## Overview", "### Mass budget", "#### Margins", "## Appendix", "### Derivation",
+		"[Mass budget](#overview-mass_budget)", "back to [Overview](#overview)")
+
+	linked := strings.Replace(model, "and [](sysml:appendix).", "[](sysml:appendix) and [](sysml:Notes::shared_notes).", 1)
+	linked = strings.TrimSuffix(strings.TrimSpace(linked), "}") + wholeBodiesNotes + "}\n"
+	wantReport(t, check(t, binary, linked, "-render-document", "Whole::WholeReport"), 0,
+		"[Shared notes](Whole-Notes.md#shared_notes)")
+	wantReport(t, check(t, binary, linked, "-render-document", "Whole::Notes"), 0,
+		"# Shared notes", "[budget](Whole-WholeReport.md#overview-mass_budget)")
+
+	html := filepath.Join(t.TempDir(), "report.html")
+	wantReport(t, check(t, binary, model, "-render-document", "Whole::WholeReport", "-doc-form", "html",
+		"-doc-title-page", "-doc-toc", "-doc-number-sections", "-o", html), 0)
+	page, err := os.ReadFile(html)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{
+		`<nav class="sysml-toc"`,
+		`<li><a href="#overview-mass_budget_2-margins">`,
+		`<h2><span class="sysml-section-number">1</span> Overview</h2>`,
+		`<h3><span class="sysml-section-number">1.2</span> Mass budget</h3>`,
+		`<h4><span class="sysml-section-number">1.2.1</span> Margins</h4>`,
+		`<h2><span class="sysml-section-number">3</span> Appendix</h2>`,
+		`<h3><span class="sysml-section-number">3.1</span> Derivation</h3>`,
+	} {
+		if !strings.Contains(string(page), want) {
+			t.Errorf("HTML lacks %q", want)
+		}
+	}
+
+	deep := strings.Replace(model, "### Margins", "##### Margins", 1)
+	wantReport(t, check(t, binary, deep, "-render-document", "Whole::WholeReport"), 2,
+		"markup-heading-level", `level 5 heading "Margins" is out of sequence: expected a level between 1 and 3 (body line 18)`)
+}

docs/internals/architecture.md

@@ -871,11 +871,11 @@ Every behavioral feature must have:
 <!-- doc-counts:begin refereed-figures -->
 **Measured against the pinned reference** (`PILOT_TAG=2026-08`, artifact `0.62.0`). Every number below is generated by `make docs-counts` from the committed baselines and gated; none of them is typed in by hand.
 
-- **Corpus agreement:** 521 of 920 files agree diagnostic-by-diagnostic; 359 diagnostics are ours alone and 2448 the reference's alone, and the first number must be read by root: the aggregate includes candidate conformance differences, intentional execution-scope warnings on reference corpora and diagnostics from our own examples ([differential](../project/pilot-differential.md), `go run -C tools ./cmd/pilot-diff`).
+- **Corpus agreement:** 521 of 920 files agree diagnostic-by-diagnostic; 359 diagnostics are ours alone and 2450 the reference's alone, and the first number must be read by root: the aggregate includes candidate conformance differences, intentional execution-scope warnings on reference corpora and diagnostics from our own examples ([differential](../project/pilot-differential.md), `go run -C tools ./cmd/pilot-diff`).
 - **Declared-diagnostic silence:** of the 512 declared `errors` rows in the reference's own Xpect suites, we report nothing for 0. 245 we report word-for-word; 248 wording-only and 7 location-only differences are agreement in substance and are not counted as gaps; 0 more we report as a warning and 2 elsewhere in the file ([Xpect oracle](../project/pilot-xpect.md), `go run -C tools ./cmd/pilot-xpect`).
 - **Scope agreement:** 230 of 230 declared scope assertions match exactly (same source).
 - **Permissiveness gaps:** of 349 invalid models we wrote ourselves, the reference rejects 5 that we accept by default, and 332 both reject; 5 further cases agree only when we are asked strictly. We authored every one of these cases ourselves, so the denominator measures the reach of our own corpus and not our conformance; agreement reached only under an opt-in strict mode is weaker evidence than agreement by default ([rejection oracle](../project/pilot-rejection.md), `go run -C tools ./cmd/pilot-reject`).
-- **Declared errata:** the registry declares 16 defect(s) in the published reference material — 9 with a specification-derived correction, 7 documented without one, since no intended reading can be inferred ([OMG issues](../project/omg-issues.md), `tools/oracle/errata`). Every figure above is as published and stays the conformance statement; running the same oracles over the corrected text instead reports 522 of 920 files agreeing, 358 diagnostics ours alone and 2448 the reference's alone, 0 declared rows we are silent on, and 0 of 349 authored cases the reference alone rejects. The corrected figures are diagnostic only: an erratum never reclassifies a divergence category, and the published corpus is never edited.
+- **Declared errata:** the registry declares 16 defect(s) in the published reference material — 9 with a specification-derived correction, 7 documented without one, since no intended reading can be inferred ([OMG issues](../project/omg-issues.md), `tools/oracle/errata`). Every figure above is as published and stays the conformance statement; running the same oracles over the corrected text instead reports 522 of 920 files agreeing, 358 diagnostics ours alone and 2450 the reference's alone, 0 declared rows we are silent on, and 0 of 349 authored cases the reference alone rejects. The corrected figures are diagnostic only: an erratum never reclassifies a divergence category, and the published corpus is never edited.
 - **Self-assessed surface:** the action, state-machine and classifier-behavior rows have no external referee at all — the four refereed figures above cannot see them, because the pinned artifact evaluates expressions but executes neither actions nor state machines. [Spec compliance](../project/spec-compliance.md) counts them.
 
 What these numbers cannot show: the OMG corpora are demonstrations rather than an official conformance suite; the differential is one-directional, comparing the diagnostics the two implementations report on the same files; the Xpect suites are the pilot authors' test intent rather than a certification oracle; and none of these is a percentage of the specification — no global compliance figure is claimed anywhere.