@kadabra-rs/spec-mcp 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @kadabra-rs/spec-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Self-contained [MCP](https://modelcontextprotocol.io) server for the **OMG KerML 1.0** and
+**SysML v2** specifications — an authoritative oracle agents consult *before* writing model
+code, so syntax and semantics come from the spec instead of being invented.
+
+Everything is embedded in a single binary (no repo checkout needed at runtime):
+
+- full clause text of both specs (Markdown conversions of the OMG PDFs)
+- the official textual-notation grammars (`.kebnf`)
+- every spec figure/diagram as an inline image
+- the OMG worked-example model corpus (KerML examples + SysML training/validation models)
+
+## Run with npx / bunx
+
+```bash
+npx -y @kadabra-rs/spec-mcp            # serve over stdio (downloads + SHA-256 verifies the binary)
+bunx @kadabra-rs/spec-mcp              # same under bun
+npx -y @kadabra-rs/spec-mcp install    # prefetch the binary only
+npx -y @kadabra-rs/spec-mcp path       # print the cached binary path
+```
+
+MCP client config (`.mcp.json`, `.omp/mcp.json`, Claude Desktop, …):
+
+```json
+{
+  "mcpServers": {
+    "spec": { "command": "npx", "args": ["-y", "@kadabra-rs/spec-mcp"] }
+  }
+}
+```
+
+First run caches the platform binary under `~/.cache/spec-mcp/<version>-<platform>/`;
+subsequent runs start instantly.
+
+## Tools
+
+Every tool takes `spec: "kerml" | "sysml"`.
+
+| Tool | Purpose |
+| --- | --- |
+| `search_sections` | full-text clause search (title hits first, body hits with snippets) |
+| `get_section` | clause body as Markdown + defined BNF productions + figures (images inline) |
+| `get_syntax` | official `.kebnf` production bodies by name, with defining clause |
+| `get_figure` | one captioned diagram by printed figure number, inline |
+| `list_examples` | index of the official worked-example model corpus |
+| `get_example` | full source of one example `.kerml`/`.sysml` file |
+| `follow_link` | resolve `#anchor` cross-references between clauses |
+| `spec_toc` | nested clause outline (chapters → sections → clauses), optional max_depth |
+| `find_implementation` | map a clause to compiler code (only inside the forge repo) |
+
+## Bundled agent skill
+
+The package ships a `sysml-modeling` skill teaching agents the two-surface workflow
+(**spec-mcp = documentation oracle**, **spec42 CLI = validator**): ground every construct in a
+BNF production / clause, learn shape from the official examples, then validate with
+`spec42 check`.
+
+```bash
+npx -y @kadabra-rs/spec-mcp skill install                    # -> ~/.omp/agent/skills/sysml-modeling
+npx -y @kadabra-rs/spec-mcp skill install --agent all        # omp + claude + codex + agents dirs
+npx -y @kadabra-rs/spec-mcp skill install --project          # -> ./.omp/skills (commit it)
+npx -y @kadabra-rs/spec-mcp skill remove
+```
+
+## Environment
+
+| Variable | Effect |
+| --- | --- |
+| `SPEC_MCP_BINARY` | use a prebuilt binary, skip download |
+| `SPEC_MCP_VERSION` | override the release version |
+| `SPEC_MCP_BASE_URL` | override the download base URL (mirrors/tests) |
+| `SPEC_MCP_CACHE_DIR` | override the cache directory |
+| `SPEC_MCP_CRATES_DIR` | passed to the server for `find_implementation` |
+
+Binaries are released on [GitHub](https://github.com/kadabra-rs/forge/releases) with
+`SHA256SUMS.txt`; the launcher refuses unverified downloads.
+
+## License
+
+AGPL-3.0-only (same as the spec-mcp source in
+[`kadabra-rs/forge`](https://github.com/kadabra-rs/forge/tree/main/tools/spec-mcp)).

package/bin/spec-mcp.mjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+// spec-mcp launcher: resolves the self-contained spec MCP binary for this
+// platform (download + SHA-256 verify + cache, or SPEC_MCP_BINARY), runs it
+// over stdio, and can install/remove the bundled `sysml-modeling` agent skill.
+//
+//   npx @kadabra-rs/spec-mcp                      # serve MCP on stdio
+//   npx @kadabra-rs/spec-mcp install              # fetch binary only
+//   npx @kadabra-rs/spec-mcp skill install        # skill -> agent dirs (user-level)
+//   npx @kadabra-rs/spec-mcp skill install --project --agent omp
+//   npx @kadabra-rs/spec-mcp skill remove
+//   npx @kadabra-rs/spec-mcp path                 # print binary path
+//
+// Environment:
+//   SPEC_MCP_BINARY    absolute path to a prebuilt spec-mcp (skips download)
+//   SPEC_MCP_VERSION   override the release tag version (e.g. 0.2.0)
+//   SPEC_MCP_BASE_URL  override the download base URL (mirrors/tests)
+//   SPEC_MCP_CACHE_DIR override the cache dir (default ~/.cache/spec-mcp)
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync,
+  realpathSync, renameSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8"));
+const SKILL_NAME = "sysml-modeling";
+const GITHUB_REPO = "kadabra-rs/forge";
+
+const err = (msg) => process.stderr.write(`${msg}\n`);
+const fail = (msg) => { err(`spec-mcp: ${msg}`); process.exit(1); };
+
+export function detectPlatform() {
+  const arch = process.arch === "arm64" ? "arm64"
+    : process.arch === "x64" ? "x64" : null;
+  const os = process.platform === "darwin" ? "darwin"
+    : process.platform === "linux" ? "linux" : null;
+  if (!os || !arch) {
+    fail(`no prebuilt spec-mcp binary for ${process.platform}/${process.arch}; \
+build it (cargo build --release -p spec-mcp in the forge repo, tools/spec-mcp) \
+and set SPEC_MCP_BINARY, or run: cargo install --git https://github.com/${GITHUB_REPO} --bin spec-mcp`);
+  }
+  // Intel macOS is not released: the semantic engine's onnxruntime
+  // (ort-sys 2.0.0-rc.13) publishes no x86_64-apple-darwin prebuilt, so the
+  // release workflow has no darwin-x64 leg.
+  if (os === "darwin" && arch === "x64") {
+    fail(`no prebuilt spec-mcp binary for darwin/x64 (Intel macOS is not released); \
+build it (cargo build --release -p spec-mcp in the forge repo, tools/spec-mcp) and set SPEC_MCP_BINARY, or run: cargo install --git https://github.com/${GITHUB_REPO} --bin spec-mcp`);
+  }
+  if (os === "linux" && !process.report?.getReport?.().header?.glibcVersionRuntime) {
+    fail(`no prebuilt spec-mcp binary for linux/${arch}; build it \
+(cargo build --release -p spec-mcp in the forge repo, tools/spec-mcp) and set SPEC_MCP_BINARY`);
+  }
+  return `${os}-${arch}`;
+}
+
+export function releaseVersion() {
+  return process.env.SPEC_MCP_VERSION ?? PKG.version;
+}
+
+export function assetName(version, platform) {
+  return `spec-mcp-${version}-${platform}.tar.gz`;
+}
+
+export function cacheDir() {
+  return process.env.SPEC_MCP_CACHE_DIR ?? join(homedir(), ".cache", "spec-mcp");
+}
+
+function fetchBuffer(url) {
+  return (async () => {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+    return Buffer.from(await res.arrayBuffer());
+  })();
+}
+
+function sha256(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+// Extract one named member from a tar.gz using only node builtins: gzip via
+// zlib, then a minimal USTAR/PAX reader (release archives hold one regular
+// file, but pax size/longname overrides are honored defensively).
+import { gunzipSync } from "node:zlib";
+
+// PAX extended-header body, one record per line. GNU tar length-prefixes
+// every record (`206 path=./…`, `29 mtime=…`); libarchive omits the length.
+// Strip the optional leading `<len> ` and parse `keyword=value`.
+function paxRecords(body) {
+  const out = {};
+  for (const line of body.split("\n")) {
+    if (!line) continue;
+    const rec = line.replace(/^\d+\s/, "");
+    const m = /^(\w+)=([\s\S]*)$/.exec(rec);
+    if (!m) continue;
+    out[m[1]] = m[2];
+  }
+  return out;
+}
+
+export function untarOne(gz, memberName) {
+  const tar = gunzipSync(gz);
+  let off = 0;
+  let paxName = null;
+  let paxSize = null;
+  while (off + 512 <= tar.length) {
+    const h = tar.subarray(off, off + 512);
+    if (h[0] === 0) break; // end-of-archive zero block
+    const field = (s, e) => h.toString("utf8", s, e).split("\0")[0].trim();
+    const rawName = field(0, 100);
+    const prefix = field(345, 500);
+    const size = parseInt(field(124, 136), 8) || 0;
+    const type = String.fromCharCode(h[156]);
+    off += 512;
+    const dataStart = off;
+    // GNU longname and pax extended headers describe the *next* entry.
+    if (type === "L") {
+      paxName = tar.subarray(dataStart, dataStart + size).toString("utf8").split("\0")[0];
+      off += Math.ceil(size / 512) * 512;
+      continue;
+    }
+    if (type === "x" || type === "g") {
+      const kv = paxRecords(tar.subarray(dataStart, dataStart + size).toString("utf8"));
+      if (kv.path !== undefined) paxName = kv.path;
+      if (kv.size !== undefined) paxSize = parseInt(kv.size, 10);
+      else paxSize = null;
+      off += Math.ceil(size / 512) * 512;
+      continue;
+    }
+    const entryName = paxName ?? (prefix ? `${prefix}/` : "") + rawName;
+    const normalized = entryName.replace(/^\.\//, "");
+    const isFile = type === "0" || type === "\0";
+    const effectiveSize = paxSize ?? size;
+    paxName = null;
+    paxSize = null;
+    if (isFile && normalized === memberName) {
+      return tar.subarray(dataStart, dataStart + effectiveSize);
+    }
+    off += Math.ceil(size / 512) * 512;
+  }
+  throw new Error(`member ${memberName} not found in archive`);
+}
+
+export async function ensureBinary({ quiet = false } = {}) {
+  if (process.env.SPEC_MCP_BINARY) {
+    const p = process.env.SPEC_MCP_BINARY;
+    if (!existsSync(p)) fail(`SPEC_MCP_BINARY points at a missing file: ${p}`);
+    return p;
+  }
+  const version = releaseVersion();
+  const platform = detectPlatform();
+  const dir = join(cacheDir(), `${version}-${platform}`);
+  const bin = join(dir, "spec-mcp");
+  if (existsSync(bin)) return bin;
+
+  const base = process.env.SPEC_MCP_BASE_URL ??
+    `https://github.com/${GITHUB_REPO}/releases/download/spec-mcp-v${version}`;
+  const asset = assetName(version, platform);
+  err(`spec-mcp: downloading ${asset} (v${version})`);
+  const [archive, sums] = await Promise.all([
+    fetchBuffer(`${base}/${asset}`),
+    fetchBuffer(`${base}/SHA256SUMS.txt`).catch(() => null),
+  ]);
+  if (sums) {
+    const expected = sums.toString("utf8").split("\n")
+      .map((l) => l.trim().split(/\s+/))
+      .filter(([h, f]) => h && f && (f === asset || f.endsWith("/" + asset)))
+      .map(([h]) => h)[0];
+    if (!expected) fail(`${asset} is not listed in the published SHA256SUMS.txt`);
+    const got = sha256(archive);
+    if (got !== expected) fail(`checksum mismatch for ${asset}: expected ${expected}, got ${got}`);
+    if (!quiet) err(`spec-mcp: checksum OK`);
+  } else {
+    fail("could not fetch SHA256SUMS.txt from the release; refusing unverified download");
+  }
+
+  const data = untarOne(archive, "spec-mcp");
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${bin}.tmp-${process.pid}`;
+  try {
+    writeFileSync(tmp, data);
+    chmodSync(tmp, 0o755);
+    renameSync(tmp, bin);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+  if (!quiet) err(`spec-mcp: cached at ${bin}`);
+  return bin;
+}
+
+// -- skill install ------------------------------------------------------------
+
+export function skillSource() {
+  const packaged = join(HERE, "..", "skill", "SKILL.md");
+  if (existsSync(packaged)) return packaged;
+  // Inside the forge repo checkout, fall back to the canonical skill location.
+  const canonical = join(HERE, "..", "..", "..", "..", "skills", SKILL_NAME, "SKILL.md");
+  if (existsSync(canonical)) return canonical;
+  fail(`bundled skill missing from package (${packaged})`);
+}
+
+export function skillTargets(scope, agents) {
+  const home = homedir();
+  const roots = {
+    omp: scope === "project" ? ".omp/skills" : join(home, ".omp/agent/skills"),
+    claude: scope === "project" ? ".claude/skills" : join(home, ".claude/skills"),
+    codex: scope === "project" ? ".codex/skills" : join(home, ".codex/skills"),
+    agents: scope === "project" ? ".agents/skills" : join(home, ".agents/skills"),
+  };
+  const list = agents.includes("all")
+    ? ["omp", "claude", "codex", "agents"] : agents;
+  for (const a of list) if (!Object.hasOwn(roots, a)) fail(`unknown agent '${a}' (omp|claude|codex|agents|all)`);
+  return list.map((a) => ({ agent: a, dir: join(roots[a], SKILL_NAME) }));
+}
+
+export function installSkill({ scope = "user", agents = ["omp"], force = false } = {}) {
+  const src = skillSource();
+  const content = readFileSync(src);
+  const results = [];
+  for (const { agent, dir } of skillTargets(scope, agents)) {
+    const target = join(dir, "SKILL.md");
+    let state = "installed";
+    if (existsSync(target)) {
+      const cur = readFileSync(target);
+      if (cur.equals(content)) { state = "up-to-date"; }
+      else if (!force) { state = "skipped (modified locally; --force to overwrite)"; }
+      else { writeFileSync(target, content); state = "overwritten"; }
+    } else {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(target, content);
+      state = "installed";
+    }
+    results.push({ agent, scope, path: target, state });
+  }
+  return results;
+}
+
+export function removeSkill({ scope = "user", agents = ["omp"] } = {}) {
+  const results = [];
+  for (const { agent, dir } of skillTargets(scope, agents)) {
+    const existed = existsSync(join(dir, "SKILL.md"));
+    if (existed) rmSync(dir, { recursive: true, force: true });
+    results.push({ agent, scope, path: dir, state: existed ? "removed" : "absent" });
+  }
+  return results;
+}
+
+// -- arg parsing ---------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = { scope: "user", agents: [], force: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--project") opts.scope = "project";
+    else if (a === "--user") opts.scope = "user";
+    else if (a === "--force") opts.force = true;
+    else if (a === "--agent") {
+      const v = argv[++i];
+      if (!v) fail("--agent requires a value (omp|claude|codex|agents|all, repeatable)");
+      if (v === "all") opts.agents = ["all"];
+      else opts.agents.push(...v.split(","));
+    } else if (a === "--help" || a === "-h") {
+      positional.length = 0;
+      positional.push("help");
+    }
+    else if (a.startsWith("-")) fail(`unknown option: ${a} (see --help)`);
+    else positional.push(a);
+  }
+  if (opts.agents.length === 0) opts.agents = ["omp"];
+  return { positional, opts };
+}
+
+const USAGE = `spec-mcp ${PKG.version} — OMG KerML/SysML v2 specification MCP server
+
+usage: spec-mcp [command] [options]
+
+commands
+  (default)          serve the MCP server over stdio (for MCP client config)
+  install            download + verify the platform binary only
+  skill install      install the '${SKILL_NAME}' agent skill
+  skill remove       remove the '${SKILL_NAME}' skill
+  path               print the resolved binary path
+  version            print the launcher version
+
+options (skill commands)
+  --user             install to user-level agent dirs (default)
+  --project          install to <cwd>/.<agent>/skills (checked in with your repo)
+  --agent <a>        omp|claude|codex|agents|all (default omp; repeatable/comma list)
+  --force            overwrite locally modified SKILL.md
+
+MCP client config (project .mcp.json / .omp/mcp.json):
+  { "mcpServers": { "spec": { "command": "npx", "args": ["-y", "@kadabra-rs/spec-mcp"] } } }
+bun: use "command": "bunx", same args.
+`;
+
+async function main() {
+  const { positional, opts } = parseArgs(process.argv.slice(2));
+  const cmd = positional.join(" ") || "serve";
+  switch (cmd) {
+    case "help":
+      process.stdout.write(USAGE);
+      return;
+    case "version":
+      process.stdout.write(`spec-mcp launcher ${PKG.version}\n`);
+      return;
+    case "path":
+      process.stdout.write(`${await ensureBinary({ quiet: true })}\n`);
+      return;
+    case "install":
+      await ensureBinary();
+      return;
+    case "skill install":
+      for (const r of installSkill(opts)) err(`spec-mcp: skill ${r.state}: ${r.path}`);
+      err(`spec-mcp: skill '${SKILL_NAME}' ready for ${opts.agents.join(", ")} (${opts.scope}-level)`);
+      return;
+    case "skill remove":
+      for (const r of removeSkill(opts)) err(`spec-mcp: skill ${r.state}: ${r.path}`);
+      return;
+    case "serve": {
+      const bin = await ensureBinary({ quiet: true });
+      const args = process.env.SPEC_MCP_CRATES_DIR ? [process.env.SPEC_MCP_CRATES_DIR] : [];
+      const child = spawn(bin, args, { stdio: "inherit" });
+      child.on("error", (e) => fail(`failed to exec ${bin}: ${e.message}`));
+      for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.on(sig, () => {
+          if (child.exitCode === null && child.signalCode === null) child.kill(sig);
+          else {
+            // Re-raised from the exit handler below: restore default and die.
+            process.removeAllListeners(sig);
+            process.kill(process.pid, sig);
+          }
+        });
+      }
+      child.on("exit", (code, signal) => {
+        if (signal) process.kill(process.pid, signal);
+        else process.exit(code ?? 1);
+      });
+      return;
+    }
+    default:
+      fail(`unknown command: ${cmd} (see --help)`);
+  }
+}
+
+// Run only when executed as a program; importers (tests) get the functions.
+// npm exposes bins through symlinks while Node realpath-resolves the main
+// module, so compare realpaths rather than the URL of the invoked path.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@kadabra-rs/spec-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Self-contained MCP server for the OMG KerML 1.0 and SysML v2 specifications: clause text, official BNF grammars, figures, and worked-example models, embedded in one binary.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kadabra-rs/forge.git",
+    "directory": "tools/spec-mcp/npm"
+  },
+  "homepage": "https://github.com/kadabra-rs/forge/tree/main/tools/spec-mcp/npm",
+  "keywords": ["mcp", "sysml", "sysml-v2", "kerml", "omg", "specification", "mbse"],
+  "bin": {
+    "spec-mcp": "bin/spec-mcp.mjs"
+  },
+  "files": [
+    "bin/spec-mcp.mjs",
+    "skill",
+    "README.md"
+  ],
+  "scripts": {
+    "prepare": "node scripts/copy-skill.mjs",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: sysml-modeling
+description: Use when creating, extending, reviewing, validating, or exploring SysML v2 and KerML models, or when asked how something should be modeled per the OMG specification. Grounds syntax and semantics in the spec-mcp oracle (clauses, BNF productions, figures, official worked examples) and validates models with the spec42 CLI.
+---
+
+# SysML v2 / KerML modeling with the spec oracle and spec42
+
+Two distinct surfaces, never interchangeable:
+
+| Surface | What it is | Use it for |
+| --- | --- | --- |
+| **`spec` MCP server** (package `@kadabra-rs/spec-mcp`) | The OMG KerML 1.0 + SysML v2 specifications embedded in a binary: clause text, official BNF grammars, diagrams, and the OMG worked-example model corpus. It is *documentation*, not a validator. | How something is modeled: normative rules, concrete syntax (BNF), figures, real example models, clause citations. |
+| **`spec42` CLI** | SysML v2 / KerML language tooling (parser, resolver, validator). It *compiles* model files. | Does my model parse/resolve/validate; what do diagnostics mean; resolved structure (`model-export`). |
+
+Typical loop: learn from the oracle → write the smallest slice → validate with spec42 → repair root causes → cite the oracle when uncertain.
+
+## Ground rules
+
+- Never invent concrete syntax. If you are not sure a construct exists or how it is written, ask the oracle: `get_syntax` (BNF production bodies) and `get_section` (the clause that defines it). Every syntax claim you write down should trace to a BNF production or a clause ID; when reporting, cite it (e.g. "§8.2.2.21.2").
+- Before modeling an unfamiliar concept (requirements, ports, successions, variance, metadata, views…), look at how the OMG themselves modeled it: `list_examples` then `get_example`. The corpus is the official SysML v2 release material — training examples (`NN. <Topic>/…`), validation suites, KerML examples. Copy *shape* from examples only after confirming the governing syntax with `get_syntax`.
+- Semantics questions ("may a RequirementUsage specialize…", "what does conjugates do to directions") go to `search_sections` + `get_section`, never to memory.
+- Validation is what `spec42` says, not what the oracle says, and not what the source text looks like. Never claim a model is valid without an observed `spec42 check` run; never claim the oracle validated anything — it does not compile.
+
+## spec oracle tools (MCP, all take `spec: "kerml" | "sysml"`)
+
+| Tool | Returns |
+| --- | --- |
+| `search_sections {spec, query}` | Clauses whose id/title/body match, body hits with snippets. Entry point for any question. |
+| `semantic_search {spec, query, limit?}` | Meaning-based lookup when a concept is phrased differently than the spec's terms (lexical search misses it); ranked by cosine similarity. First call downloads the embedding model and caches clause embeddings. |
+| `get_section {spec, clause_id}` | Clause body as Markdown + BNF production names defined there + figures; diagram images arrive inline (uncaptioned diagrams have `number: null`, captioned ones carry their printed number). |
+| `get_syntax {spec, production}` | `.kebnf` production bodies (exact or substring match, exact first) with the defining clause. |
+| `get_figure {spec, figure_number}` | One captioned diagram, inline, with title and owning clause. |
+| `list_examples {spec}` | Index of the official worked-example corpus (paths grouped by topic). |
+| `get_example {spec, path}` | Full source of one example `.kerml`/`.sysml` file from the corpus. |
+| `follow_link {spec, link}` | Resolves `#anchor` cross-references found in clause text to their clause. |
+| `spec_toc {spec, max_depth?}` | Nested clause outline (id, title, anchor, depth); max_depth 1–2 to orient, omit for the full tree. |
+| `find_implementation {spec, clause_id}` | Maps a clause to compiler code in the forge repo (only meaningful there). |
+
+The KerML spec holds the kernel semantics (clause 7.x), textual + abstract syntax (8.x); SysML v2 builds the systems layer on top. When a SysML clause says "see KerML 8.4.x", switch `spec` and follow it.
+
+## spec42 CLI contract
+
+```bash
+command -v spec42 || echo "spec42 missing: in the forge repo run: sh tools/install-sysml-tooling.sh; elsewhere download a platform archive from https://github.com/elan8/spec42/releases and verify it against that release's SHA256SUMS.txt"
+
+spec42 doctor --format json                                   # environment/stdlib first on suspect setups
+spec42 check <path-or-dir> --format json                      # validation report
+spec42 check file.sysml --workspace-root <dir> --format json  # single file inside a multi-file project
+spec42 explain-diagnostic --code <code> --format json         # stable meaning of a diagnostic code
+spec42 model-export <dir> --format json                       # resolved structure (elements, relationships, connectors)
+spec42 model-export <dir> --max-nodes 500 --format json       # bounded; ALWAYS inspect projection.truncation
+```
+
+Reading `check`: gate on `summary.error_count == 0`; report `summary.warning_count` separately; per-document diagnostics carry `code`, `message`, LSP `range`; `advice` flags environment problems (missing standard library). Many `unresolved_*` codes → run `doctor` before rewriting imports or types. A clean check proves the file compiles — not that the model satisfies what the user intended.
+
+Reading `model-export`: it is resolved truth (specialization, typing, connector topology, metadata), the source text is not. Check `projection.schema_version`, state when a bounded export truncated.
+
+There is no spec42 MCP server or HTTP API — upstream removed both in v0.50.0; the CLI is the only surface. If the binary is missing, do not claim validation happened: write "Not validated with Spec42" and offer an unvalidated draft.
+
+## Modeling workflow (small steps, always)
+
+1. **Frame.** System boundary, owning package, exact requested change. Inspect existing model conventions first (imports, package layout, naming).
+2. **Ground.** `search_sections` → `get_section` for the governing clauses; `get_syntax` for every construct you intend to emit; `get_example` on one or two official examples of that construct. Collect: normative rules, production bodies, example shapes.
+3. **Separate.** Facts from the conversation vs assumptions vs open questions. Do not turn every utterance into a requirement; attribute claims and preserve ambiguity.
+4. **Slice.** Smallest coherent change; definitions/usages stay in their owning packages; one authoritative definition per concept, reference it instead of duplicating.
+5. **Edit.** Minimal diff, existing conventions preserved.
+6. **Validate.** `spec42 check` with correct workspace scope. New error → root cause first, in this order: toolchain/stdlib → syntax → names/imports → typing/specialization → relations/behavior → traceability. Re-run after each fix; stop a speculative chain the moment it introduces new diagnostics; keep a baseline count so preexisting errors aren't blamed on you.
+7. **Verify structure.** When resolved relationships matter, `model-export` and cite the projection — with truncation status.
+8. **Report.** What changed; exact check scope and counts; clause/BNF citations backing the syntax; remaining warnings; assumptions; one next question when a material decision lacks evidence.
+
+## Repair and review specifics
+
+- Reviewing a model or diff: read it, `check` it, then verify constructs against `get_syntax` — a construct can compile under spec42 yet be modelled against the spec's intent; the clause text is the arbiter of intent, cite it.
+- Unusual syntax in someone's model is not a license to copy it: confirm in the grammar before reusing.
+- Never suppress diagnostics by deleting content, disabling the standard library, or rewriting imports to hide errors; fix the root cause or report it.
+
+## Anti-fabrication checklist
+
+- Syntax invented without a `get_syntax`/`get_section` citation → do not emit it.
+- "Validated" without an observed `spec42 check` JSON → say "Not validated with Spec42".
+- "Complete structure" from a `--max-nodes` export → check `projection.truncation` first.
+- Relationship not present in `model-export` projection → report it as missing/inferred, never as verified.