chore(release): 0.10.0

.agents/skills/testing-doc-pdf/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: testing-doc-pdf
-description: How to end-to-end test the sysml PDF document backend (internal/doc/docpdf + -doc-form pdf) on Linux — provisioning the pinned WeasyPrint/mermaid/KaTeX/Graphviz/PlantUML toolchain, rendering the worked example and the docrender goldens, and proving inline runs, anchors, links, LaTeX formulas and every diagram form render rather than appearing literal.
+description: How to end-to-end test the sysml PDF document backend (internal/doc/docpdf + -doc-form pdf) on Linux — provisioning the pinned WeasyPrint/mermaid/KaTeX/Graphviz/PlantUML/D2 toolchain, rendering the worked example and the docrender goldens, and proving inline runs, anchors, links, LaTeX formulas and every diagram form render rather than appearing literal.
 ---
 
 # Testing the PDF document backend
 
 ## Toolchain
-- Provision once: `./scripts/download-doc-pdf-toolchain.sh` installs a pinned WeasyPrint venv, pandoc, mermaid-cli, KaTeX, Graphviz (unpacked from the upstream Ubuntu .debs; its `neato` plugin needs the host's `libgts-0.7-5`) and the PlantUML jar under `build/doc-pdf/`. PlantUML needs a `java` on `PATH` (or `OPENSYSML_JAVA`).
+- Provision once: `./scripts/download-doc-pdf-toolchain.sh` installs a pinned WeasyPrint venv, pandoc, mermaid-cli, KaTeX, Graphviz (unpacked from the upstream Ubuntu .debs; its `neato` plugin needs the host's `libgts-0.7-5`) the PlantUML jar and D2 under `build/doc-pdf/`. PlantUML needs a `java` on `PATH` (or `OPENSYSML_JAVA`).
 - Export before any PDF render (env does NOT persist between exec tool calls even in the same shell session — re-export in the same command line):
   - `OPENSYSML_WEASYPRINT=$PWD/build/doc-pdf/weasyprint/bin/weasyprint`
   - `OPENSYSML_MMDC=$PWD/build/doc-pdf/mermaid/node_modules/.bin/mmdc`
@@ -15,8 +15,9 @@ description: How to end-to-end test the sysml PDF document backend (internal/doc
   - `OPENSYSML_KATEX=$PWD/build/doc-pdf/katex/node_modules/.bin/katex` (only a document with formulas needs it)
   - `OPENSYSML_DOT=$PWD/build/doc-pdf/graphviz/bin/dot` (for `-diagram-form dot`; absent, DOT blocks stay as source under a notice)
   - `OPENSYSML_PLANTUML_JAR=$PWD/build/doc-pdf/plantuml/plantuml-1.2026.8.jar` (for `-diagram-form plantuml`; absent, PlantUML blocks stay as source under a notice)
+  - `OPENSYSML_D2=$PWD/build/doc-pdf/d2/d2-v0.9.0/bin/d2` (for `-diagram-form d2`; absent, D2 blocks stay as source under a notice naming the variable)
 - `go test -run Installed ./internal/doc/docpdf` runs the real-toolchain integration tests (they skip per missing tool, `pdftotext`/`pdfimages` from `poppler-utils` included — the tests read every PDF back through them, so install the package or the text assertions never run); the rest of the package's tests use fake tools and need nothing installed. `OPENSYSML_REQUIRE_PDF_TOOLCHAIN=1` turns every such skip but Prince's into a failure — set it once the script has run, so a misconfigured variable cannot pass as a skip. This is how the CI `pdf-toolchain` job runs them.
-- Diagram forms: render the worked example with `-diagram-form dot` and `-diagram-form plantuml` too; the PDF must contain no "did not draw" notice (pypdf `extract_text`) and the page's XObjects grow by one per diagram. With `OPENSYSML_DOT=/nonexistent` the render still succeeds and the notice names `OPENSYSML_DOT`. A `// layout: neato -n` block (the DOT writer emits one for a positioned diagram) must run neato: `dot -Kneato` failing with "no layout engine support" means the GTS library is missing.
+- Diagram forms: render the worked example with `-diagram-form dot`, `-diagram-form plantuml` and `-diagram-form d2` too; the PDF must contain no "did not draw" notice (pypdf `extract_text`) and the page's XObjects grow by one per diagram. With `OPENSYSML_DOT=/nonexistent` the render still succeeds and the notice names `OPENSYSML_DOT`; the same with `OPENSYSML_D2`. A `// layout: neato -n` block (the DOT writer emits one for a positioned diagram) must run neato: `dot -Kneato` failing with "no layout engine support" means the GTS library is missing.
 
 ## Rendering
 - Worked example: `bin/sysml docs/manual/examples/observatory.sysml -render-document Observatory::MassReport -doc-form pdf -pdf-title-page -pdf-toc -pdf-number-sections -o /tmp/observatory.pdf`. It exercises emphasis, code span, external Link, Ref (`#breakdown`), a standalone `<a id="breakdown"></a>` anchor line, grouped table (`**zone: ...**` headings), numbered list and two mermaid diagrams.
@@ -28,7 +29,8 @@ description: How to end-to-end test the sysml PDF document backend (internal/doc
 - Formulas: `internal/doc/docrender/testdata/math_report.sysml` → `Optics::OpticsReport` has an inline `$m \propto D^{2.5}_{\text{eff}}$` beside an escaped prose `\$`, a captioned `Formula` that is a `Ref` target, a multi-line display block, a `\$` inside math, and query-driven math list items. Render under both engines and check with pypdf: the page's `/Font` `/BaseFont`s must include `KaTeX_Main`, `KaTeX_Math-Italic` (and `KaTeX_Size3` for the tall parenthesis); extracted text must contain `∝`, `π`, `θ`, `λ` and none of `$$`, `\propto`, `\frac`, `_{`, `^{`, `katex`, `<span`. Text from absolutely-positioned KaTeX spans extracts out of reading order (superscripts on their own lines) — that is pypdf, not a bug. For a visual check, `pip install pypdfium2` into the WeasyPrint venv and `PdfDocument(path)[0].render(scale=1.3).to_pil().save(png)`.
 - KaTeX is run with `--format html` (no MathML), deliberately: the MathML branch carries the LaTeX source as `<annotation>` text, which paged-media engines would set literally. A malformed formula (`\frac{a}`) fails the run with `KaTeX parse error: ...` from the CLI's stderr, not a PDF with a gap.
 - `docpdf.Render`'s second argument is the engine NAME (`"weasyprint"`, `"pandoc"`, `"prince"`), not a binary path; binaries come from the OPENSYSML_* env vars.
-- Diagrams: Mermaid is drawn once through `mmdc` and the image replaces the block (`HTMLOptions.DiagramImages` / the Lua filter); a table-kind diagram stays a table. DOT and PlantUML are not drawn — the PDF carries an emphasized notice and the source, under both engines.
+- Diagrams: each is drawn once through its tool and the image replaces the block (`HTMLOptions.DiagramImages` / the Lua filter); a table-kind diagram stays a table. Mermaid's `mmdc` is required; Graphviz, the PlantUML jar and `d2` are optional — absent, the PDF carries an emphasized notice and the source, under both engines.
+- D2 needs pixels, not text: `d2` writes the `<mask>` that cuts a connection's label out of its line after the connections, and WeasyPrint draws such a mask as a white rectangle over the whole figure while `pdftotext` still extracts every label. `docpdf/d2.go` `defineMasks` moves the masks under `<defs>`; regress it with a labelled connection (`telescope_report.sysml`'s `link`), rasterize the page (`pdftoppm -r 100 -png`) and look for the nested containers, the state glyphs and the gap in the line around the label, under both engines.
 - Linked sets: `-render-documents ... -doc-form pdf` is refused with a typed error; render each document with `-render-document`. A `Ref` into another document then links to that document's page file name, which no PDF beside it carries.
 
 ## Verifying the PDF is real, not literal

.agents/skills/testing-docs-site/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: testing-docs-site
+description: How to build and browser-test the MkDocs documentation site locally — genuine Material instant navigation, Back/forward restoration, palette toggle and responsive landing-page behavior — without changing repository configuration.
+---
+
+# Testing the documentation site in a browser
+
+Use a virtualenv with `pip install -r docs-requirements.txt`. Do not change repository configuration
+to serve a local preview: build to a directory outside the checkout and serve that with
+`python -m http.server`.
+
+For instant-navigation testing, the build's `site_url` must match the local origin, port included.
+Material's sitemap resolver can rewrite protocol and hostname without rewriting the port, so a
+production build served on a nonstandard local port can silently fall back to full navigation.
+
+From the repository root, build through the MkDocs API with runtime overrides:
+
+```python
+from mkdocs.config import load_config
+from mkdocs.commands.build import build
+config = load_config(
+    "mkdocs.yml",
+    site_url="http://localhost:8766/",
+    site_dir="<outside-checkout>/site-browser-test",
+    strict=True,
+)
+build(config)
+```
+
+Serve that directory on the matching port. Verify instant navigation rather than assuming it: read
+`performance.timeOrigin`, click an internal link through the UI, and read it again; it must not
+change. Test browser Back too, and check visually that page-specific UI is removed and restored
+without duplicates.
+
+Use the header palette toggle for light and dark modes, and DevTools responsive mode for narrow
+widths. Verify pixels, not just element presence.
+
+If browser inspection tooling appears to alter `target="_blank"` attributes, repeat the external-link
+tests from a fresh page without annotated DOM inspection before the click. Read-only CDP inspection
+plus native mouse input distinguishes tooling interference from the built page's behavior.
+
+When the change under test is in `overrides/` — a stylesheet or template — do not
+assume `mkdocs serve` reloaded it. The live reload may keep serving the old asset
+through a browser hard refresh. Restart the server, wait for the build and serving
+messages, reload, and confirm the loaded file carries the intended rule before
+diagnosing a CSS fix as ineffective. Do not change repository configuration solely
+to make a preview work.
+
+### The in-browser engines
+
+The landing diagram and the CLI page's REPL load generated assets: `docs/assets/sysml-engine.wasm.gz`,
+`sysml-repl.wasm.gz`, `wasm_exec.js` and `repl-examples/`. They are gitignored; if any is missing,
+run `make docs-engine-assets` before building the site.
+
+The REPL walkthroughs' inputs and expected output strings live in `docs/assets/repl-walkthroughs.json`.
+Run each step through its button and check only newly appended terminal output. Wait for the input
+queue to drain and `is-busy` to clear before sending the next command.
+
+To check the SMT refusal, declare a valid constraint first, for example
+`constraint def Positive { in x : ScalarValues::Integer; x > 0 }`, then run `%check Positive`. Expect
+the message that a WebAssembly build cannot start external processes.
+
+Completion considers every matching name, standard library included. `%inst` has several candidates;
+`%instanti` has one. For a shared-prefix test, pick names that no library name shares.
+
+At mobile width, navigate through the header menu. `label[for="__drawer"]` also matches a hidden
+overlay, so scope automation to `header label[for="__drawer"]`. Compare the document's width with the
+viewport's; a code textarea's own horizontal scrolling is not page overflow.
+
+### Devin Secrets Needed
+
+None for the public local site and public outbound link checks.

.agents/skills/testing-engine-browser/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: testing-engine-browser
+description: How to build sysml-engine for js/wasm and exercise it in a real browser through an external static harness — JSON-RPC envelopes, typed values, error recovery after bad calls, and startup/transfer measurements.
+---
+
+# Testing `sysml-engine` in a browser
+
+## Setup
+
+- Read `docs/reference/wasm.md`, `cmd/sysml-engine/serve_js.go`, `internal/frontend/engine/json.go`
+  and `tests/wasm/testdata/` first.
+- Keep the harness page outside the checkout. The targeted build can live outside it too:
+  `make build-wasm-js WASM_COMMANDS=sysml-engine WASM_DIR=<harness-dir>/build`.
+- Serve the page with `python3 -m http.server 8765 --bind 127.0.0.1 --directory <harness-dir>`.
+- Load the matching `build/js/wasm_exec.js`. Instantiate the module with `new Go().importObject` and
+  `WebAssembly.instantiateStreaming`; check the server sends `application/wasm`, and fall back to
+  `arrayBuffer` if it does not.
+- Run with no extra argv. Do not await `go.run(instance)` before checking `globalThis.sysmlEngine`:
+  the engine stays alive on purpose. Record promise rejection and unexpected resolution as runtime
+  events.
+
+## Browser controls and assertions
+
+- Give the page editable source textareas for `model.sysml` and `engine.sysml`, and
+  Parse/Evaluate/ExecuteAction/ExecuteState/Instantiate controls.
+- Use the lowerCamelCase fields from `json.go`. ParseSources takes `{documents:[{name,content}]}`.
+  Reuse the `modelHash` it returns; never hardcode one.
+- `sysmlEngine.call(method, JSON.stringify(params))` synchronously returns a JSON-RPC envelope as a
+  string, not the bare protojson result.
+- Fixture expectations: total realValue 6; speed quantity 5 metres/second; `Color::red` enum; Double
+  input `x:{intValue:"6"}` returns y `"12"`; Switch visits `"on"` and instantiates a graph.
+- SysML sequences are written `(1, 2, 3)`, not `[1,2,3]`. A parity-only test can treat matching
+  error payloads as equal, so assert actual values in browser checks.
+- Probe unknown modelHash (5), unsupported method (12), `schedule:"explore"` (12), malformed params
+  JSON (3) and invalid source (diagnostics with spans). After every error, reparse edited source and
+  confirm a new hash and the updated value.
+- To enter fixture text with literal tabs into a textarea, paste it through the clipboard; typed tab
+  keystrokes move focus to the buttons. Plain spaces are safe to type.
+
+## Evidence
+
+- Open DevTools Network before the first navigation; record transfer size and response headers.
+- Take `performance.now()` when the global first appears: that is navigation-to-ready time. Record
+  the local HTTP compression and cache configuration; an uncompressed localhost transfer is not
+  comparable with a production gzip budget.
+- Keep raw request/response envelopes and per-call durations, but drive every call through the
+  visible UI.
+- Capture console errors, unhandled rejections, Go panic/exit events, and that calls keep working
+  after the error probes.
+- Record the build commit and the displayed version. A later checkout does not change a wasm file
+  that is already being served.
+
+### Devin Secrets Needed
+
+None. The page runs the engine entirely inside the browser.

.agents/skills/testing-node-browser-client/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: testing-node-browser-client
+description: How to test the @openmbee/opensysml browser entry point (client/node/src/browser) against a real sysml-grpc service — CORS-allowed origins, observing requests without altering them, decoding captured bodies, protobuf versus JSON encodings, and differential comparison with the Python client.
+---
+
+# Testing the Node client's browser entry point
+
+## Setup
+
+- Read the browser section of `client/node/README.md` and `docs/reference/node-api.md` (In a
+  browser), and `client/node/test/browser.test.ts`, which starts the service the way a page needs it.
+- Build the service (`make build-grpc`) and start it with the page's exact origin allowed:
+  `bin/sysml-grpc -port 0 -health-port 0 -report-address -cors-allowed-origins <origin>`. The first
+  stdout line is the address. Never allow `*`; an HTTPS page also needs `-tls-cert`/`-tls-key`.
+- Bundle a harness page importing `@openmbee/opensysml/browser` outside the checkout and serve it from
+  the allowed origin. `connect({ address })` is the only path: a browser cannot start a service.
+
+## Shared-core browser validation
+
+- Wrap the browser's `fetch` only to observe and forward the original request and response
+  unchanged. Counting observed service calls distinguishes a client-side refusal from a similarly
+  typed backend error; assert zero requests for invalid inputs.
+- Decode captured unary request bodies with the generated schema and protobuf `fromBinary`/`fromJson`.
+  That verifies `strictConformance` and collection union kinds while the real request still runs.
+  Never substitute responses.
+- Verify collection conversion with a real Echo calculation, not only `toValue`: check both the
+  outgoing sequence/set union and the returned values.
+- Read the public result types before writing assertions. Verification methods can return a wrapper
+  with `.verdict.standing`, while `CalcResult` has `.standing`.
+- Run every check under both protobuf and JSON (`connect({ encoding: "json" })`). Record the concrete
+  error class, code, `instanceof` result and elapsed time rather than assuming browser `fetch` maps
+  failures the way Node gRPC does; an unreachable service or CORS refusal arrives as `UNKNOWN`.
+
+## Differential options and baseline preservation
+
+- When reusing saved Python output, verify every baseline file is unchanged.
+- Compare option semantics, not just spelling: Python `strict` raises on parsing diagnostics, while
+  Node's `strict` is a deprecated alias of `strictConformance`. That intentional difference can change
+  hashes for otherwise identical source. Report it, or agree on equivalent inputs before regenerating
+  baselines; do not quietly remove or normalize the hash field.
+- Keep approved differences separate from newly acknowledged intentional exceptions. A prior finding
+  is not automatically an approved difference.
+
+### Devin Secrets Needed
+
+None for a local unauthenticated service and an external harness.

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

@@ -12,7 +12,7 @@ Four pinned OMG model roots, **one mechanism, two policies** (`tests/corpus/corp
 
 | root | dir | policy | expectation file |
 |---|---|---|---|
-| training | `examples/sysml-v2-training` | **assertion** — errors only, `.sysml` only, must be 100% clean, no per-file counts allowed | `testdata/training_examples_expected.txt` |
+| training | `examples/sysml-v2-training` | **assertion** — zero semantic errors, `.sysml` only; warnings are outside the gate, no per-file counts allowed | `testdata/training_examples_expected.txt` |
 | sysml-examples | `examples/pilot-corpora/sysml-examples` | per-file **ratchet**, every severity | `testdata/pilot_corpora_expected.txt` |
 | sysml-validation | `examples/pilot-corpora/sysml-validation` | ratchet | same |
 | kerml-examples | `examples/pilot-corpora/kerml-examples` | ratchet | same |
@@ -33,7 +33,7 @@ examples/sysml-v2-training /tmp/pristine/`) — every absence/mutation test move
 Expect `--- PASS` for `TestTrainingExamplesSemanticErrors`, `TestPilotCorporaDiagnostics` and
 `TestCorpusGatesCacheStateIndependent` (subtests `training` and `pilot-corpora` — the older
 `TestTrainingExamplesCacheStateIndependent` / `TestPilotCorporaCacheStateIndependent` no longer
-exist), plus `100/100 training files clean` and three `N/M pilot corpus files clean` lines
+exist), plus the error-only `100/100 training files clean` line and three `N/M pilot corpus files clean` lines
 (observed 2026-08: sysml-examples 76/98, sysml-validation 52/56, kerml-examples 51/58 — these move
 whenever diagnostics change, so read the current numbers from `docs/project/pilot-corpora.md`
 rather than hard-coding them).
@@ -183,8 +183,8 @@ 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 — `380 file(s), 345 fully agreeing; 38 agreed
-diagnostic(s), 41 only ours, 1614 only the pilot's` at the `2026-08` pin, so read it from
+the headline the committed baseline holds — `391 file(s), 353 fully agreeing; 45 agreed
+diagnostic(s), 282 only ours, 92 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