sysprom 1.13.1 → 1.14.0

package/README.md

@@ -17,44 +17,87 @@ npm install -g github:ExaDev/SysProM
 npx sysprom --help
 ```
 
-Both `sysprom` and `spm` are available as commands.
+Both `sysprom` and `spm` are available as commands — use `sysprom` for new projects.
 
 ## CLI
 
 ```sh
 # Convert between formats
-spm json2md .spm.json ./.spm
-spm md2json ./.spm output.spm.json
+sysprom json2md --input .SysProM.json --output ./.SysProM
+sysprom md2json --input ./.SysProM --output output.SysProM.json
 
-# Validate and summarise (auto-detects .spm.json in current directory)
-spm validate
-spm stats
+# Validate and summarise (auto-detects .SysProM.json in current directory)
+sysprom validate
+sysprom stats
 
 # Query nodes and relationships
-spm query nodes --type decision
-spm query node D1
-spm query rels --from D1
-spm query trace I1
-spm query timeline
-spm query state-at 2026-03-22
+sysprom query nodes --type decision
+sysprom query node D1
+sysprom query rels --from D1
+sysprom query trace I1
+sysprom query timeline
+sysprom query state-at 2026-03-22
 
 # Add nodes (ID auto-generated from type prefix if --id omitted)
-spm add invariant --name "New Rule" --description "Must hold"
-spm add decision --name "Choose X" \
+sysprom add invariant --name "New Rule" --description "Must hold"
+sysprom add decision --name "Choose X" \
   --option "OPT-A:Use framework X" --option "OPT-B:Use framework Y" \
   --selected OPT-A --rationale "Lower migration effort"
 
 # Remove nodes
-spm remove INV23
+sysprom remove INV23
 
 # Update nodes, relationships, and metadata
-spm update node D1 --status deprecated
-spm update add-rel D1 affects EL5
-spm update remove-rel D1 affects EL5
-spm update meta --fields version=2
+sysprom update node D1 --status deprecated
+sysprom update add-rel D1 affects EL5
+sysprom update remove-rel D1 affects EL5
+sysprom update meta --fields version=2
 ```
 
-All commands auto-detect the document — they search the current directory for `.spm.json`, `.spm.md`, or `.spm/` (in that priority order), then fall back to `*.spm.json`, `*.spm.md`, or `*.spm/`. Use `--path` to specify an explicit path.
+All commands auto-detect the document — they search the current directory for `.SysProM.json`, `.SysProM.md`, or `.SysProM/` (in that priority order), then fall back to `.spm.json`, `.spm.md`, or `.spm/`. Use `--path` to specify an explicit path. Note: `spm` is an alias for `sysprom` for backwards compatibility.
+
+## MCP Server
+
+SysProM includes an MCP (Model Context Protocol) server exposing 11 tools over stdio transport. Any MCP-compatible agent — Cursor, Windsurf, VS Code Copilot, Cline, or custom clients — can use it.
+
+### Configuration
+
+Add the following to your MCP client's configuration (e.g. `.cursor/mcp.json`, `.vscode/mcp.json`, `cline_mcp_settings.json`, or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "sysprom": {
+      "command": "npx",
+      "args": ["-y", "sysprom", "mcp"]
+    }
+  }
+}
+```
+
+Or via the CLI subcommand (equivalent):
+
+```sh
+sysprom mcp   # starts the MCP server on stdio
+```
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `validate` | Validate a SysProM document and return issues |
+| `stats` | Return document statistics |
+| `query-nodes` | Query nodes by type, status, or text |
+| `query-node` | Retrieve a single node by ID |
+| `query-relationships` | Query relationships by source, target, or type |
+| `trace` | Trace refinement chains from a node |
+| `add-node` | Add a new node to the document |
+| `remove-node` | Remove a node by ID |
+| `update-node` | Update fields on an existing node |
+| `add-relationship` | Add a relationship between nodes |
+| `remove-relationship` | Remove a relationship |
+
+All tools accept a `path` parameter to specify the SysProM document location.
 
 ## Programmatic API
 
@@ -101,7 +144,7 @@ import {
 } from "sysprom";
 
 // Validate
-const doc = JSON.parse(fs.readFileSync(".spm.json", "utf8"));
+const doc = JSON.parse(fs.readFileSync(".SysProM.json", "utf8"));
 const result = validate(doc);
 console.log(result.valid, result.issues);
 
@@ -194,7 +237,7 @@ SysProM models systems as directed graphs across abstraction layers — intent,
 SysProM is format-agnostic. This repository includes:
 
 - **JSON** — validated against `schema.json`, supports recursive subsystems
-- **Markdown** — single file (`.spm.md`), multi-document folder, or recursive nested folders with automatic grouping by type
+- **Markdown** — single file (`.SysProM.md`), multi-document folder, or recursive nested folders with automatic grouping by type
 
 Round-trip conversion between JSON and Markdown is supported with zero information loss.
 
@@ -214,29 +257,29 @@ pnpm spm <command>    # Run the CLI from source (e.g. pnpm spm validate ...)
 
 ## Self-Description
 
-`.spm.json` is SysProM describing itself — the specification, its decisions, invariants, changes, and worked examples are all encoded as a SysProM document. The `./.spm/` folder contains the same content as human-readable Markdown.
+`.SysProM.json` is SysProM describing itself — the specification, its decisions, invariants, changes, and worked examples are all encoded as a SysProM document. The `./.SysProM/` folder contains the same content as human-readable Markdown.
 
-All significant activity — decisions, changes, new capabilities, and invariants — should be recorded in the self-describing document. Updates can be made either by editing the Markdown files in `./.spm/` directly or by using the CLI:
+All significant activity — decisions, changes, new capabilities, and invariants — should be recorded in the self-describing document. Updates can be made either by editing the Markdown files in `./.SysProM/` directly or by using the CLI:
 
 ```sh
 # Add a decision via the CLI
-spm add decision --id D23 --name "My Decision" --context "Why this was needed"
+sysprom add decision --id D23 --name "My Decision" --context "Why this was needed"
 
-# Or edit ./.spm/DECISIONS.md directly, then sync
-spm md2json ./.spm .spm.json
+# Or edit ./.SysProM/DECISIONS.md directly, then sync
+sysprom md2json --input ./.SysProM --output .SysProM.json
 ```
 
 Keep both representations in sync after any change:
 
 ```sh
 # JSON → Markdown
-spm json2md .spm.json ./.spm
+sysprom json2md --input .SysProM.json --output ./.SysProM
 
 # Markdown → JSON
-spm md2json ./.spm .spm.json
+sysprom md2json --input ./.SysProM --output .SysProM.json
 ```
 
-> **Important:** Always keep `.spm.json` and `./.spm/` up to date with current activity and in sync with each other. Record all decisions, changes, and new capabilities as they happen. After any change to either representation, run the appropriate conversion command above. Validate with `spm validate` before committing.
+> **Important:** Always keep `.SysProM.json` and `./.SysProM/` up to date with current activity and in sync with each other. Record all decisions, changes, and new capabilities as they happen. After any change to either representation, run the appropriate conversion command above. Validate with `sysprom validate` before committing.
 
 ## Claude Code Plugin
 

package/dist/src/cli/commands/init.d.ts

@@ -1,9 +1,7 @@
 import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
-declare const argsSchema: z.ZodObject<{
-    path: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-}, z.core.$strip>;
 declare const optsSchema: z.ZodObject<{
+    path: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     title: z.ZodOptional<z.ZodString>;
     scope: z.ZodOptional<z.ZodString>;
     format: z.ZodOptional<z.ZodEnum<{
@@ -12,5 +10,5 @@ declare const optsSchema: z.ZodObject<{
         dir: "dir";
     }>>;
 }, z.core.$strict>;
-export declare const initCommand: CommandDef<typeof argsSchema, typeof optsSchema>;
+export declare const initCommand: CommandDef<z.ZodObject<z.ZodRawShape>, typeof optsSchema>;
 export {};

package/dist/src/cli/commands/init.js

@@ -15,9 +15,9 @@ function formatToIoFormat(fmt) {
     }
 }
 const suffixMap = {
-    json: ".spm.json",
-    md: ".spm.md",
-    dir: ".spm",
+    json: ".SysProM.json",
+    md: ".SysProM.md",
+    dir: ".SysProM",
 };
 function resolveInitTarget(pathArg, format) {
     const resolved = resolve(pathArg);
@@ -30,20 +30,26 @@ function resolveInitTarget(pathArg, format) {
         };
     }
     const fmt = format ?? "dir";
+    const suffix = suffixMap[fmt];
+    // If path already ends with the correct suffix, use it as-is
+    if (resolved.endsWith(suffix)) {
+        return {
+            outputPath: resolved,
+            ioFormat: formatToIoFormat(fmt),
+        };
+    }
     return {
-        outputPath: `${resolved}${suffixMap[fmt]}`,
+        outputPath: `${resolved}${suffix}`,
         ioFormat: formatToIoFormat(fmt),
     };
 }
-const argsSchema = z.object({
+const optsSchema = z
+    .object({
     path: z
         .string()
         .optional()
         .default(".")
         .describe("Target path (default: current directory)"),
-});
-const optsSchema = z
-    .object({
     title: z.string().optional().describe("Document title"),
     scope: z.string().optional().describe("Document scope"),
     format: z
@@ -56,10 +62,9 @@ export const initCommand = {
     name: "init",
     description: initDocumentOp.def.description,
     apiLink: initDocumentOp.def.name,
-    args: argsSchema,
     opts: optsSchema,
-    action(args, opts) {
-        const { outputPath, ioFormat } = resolveInitTarget(args.path, opts.format);
+    action(_args, opts) {
+        const { outputPath, ioFormat } = resolveInitTarget(opts.path, opts.format);
         if (existsSync(outputPath)) {
             console.error(`Already exists: ${outputPath}`);
             process.exit(1);

package/dist/src/cli/commands/json2md.d.ts

@@ -1,2 +1,9 @@
+import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
-export declare const json2mdCommand: CommandDef;
+declare const optsSchema: z.ZodObject<{
+    input: z.ZodString;
+    output: z.ZodString;
+    singleFile: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const json2mdCommand: CommandDef<z.ZodObject<z.ZodRawShape>, typeof optsSchema>;
+export {};

package/dist/src/cli/commands/json2md.js

@@ -4,35 +4,24 @@ import { resolve } from "node:path";
 import { SysProMDocument } from "../../schema.js";
 import { jsonToMarkdown } from "../../json-to-md.js";
 import { jsonToMarkdownOp } from "../../operations/index.js";
-function isArgs(arg) {
-    return (typeof arg === "object" && arg !== null && "input" in arg && "output" in arg);
-}
-function isOpts(opt) {
-    return typeof opt === "object" && opt !== null;
-}
+const optsSchema = z
+    .object({
+    input: z.string().describe("Path to SysProM JSON file"),
+    output: z.string().describe("Output path (file or directory)"),
+    singleFile: z
+        .boolean()
+        .optional()
+        .describe("Force single-file output format"),
+})
+    .strict();
 export const json2mdCommand = {
     name: "json2md",
     description: jsonToMarkdownOp.def.description,
     apiLink: jsonToMarkdownOp.def.name,
-    args: z.object({
-        input: z.string().describe("Path to SysProM JSON file"),
-        output: z.string().describe("Output path (file or directory)"),
-    }),
-    opts: z
-        .object({
-        singleFile: z
-            .boolean()
-            .optional()
-            .describe("Force single-file output format"),
-    })
-        .strict(),
-    action(args, opts) {
-        if (!isArgs(args))
-            throw new Error("Invalid args");
-        if (!isOpts(opts))
-            throw new Error("Invalid opts");
-        const inputPath = resolve(args.input);
-        const outputPath = resolve(args.output);
+    opts: optsSchema,
+    action(_args, opts) {
+        const inputPath = resolve(opts.input);
+        const outputPath = resolve(opts.output);
         const raw = JSON.parse(readFileSync(inputPath, "utf8"));
         if (!SysProMDocument.is(raw)) {
             const result = SysProMDocument.safeParse(raw);

package/dist/src/cli/commands/md2json.d.ts

@@ -1,2 +1,8 @@
+import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
-export declare const md2jsonCommand: CommandDef;
+declare const optsSchema: z.ZodObject<{
+    input: z.ZodString;
+    output: z.ZodString;
+}, z.core.$strict>;
+export declare const md2jsonCommand: CommandDef<z.ZodObject<z.ZodRawShape>, typeof optsSchema>;
+export {};

package/dist/src/cli/commands/md2json.js

@@ -4,23 +4,20 @@ import { resolve } from "node:path";
 import { markdownToJson } from "../../md-to-json.js";
 import { canonicalise } from "../../canonical-json.js";
 import { markdownToJsonOp } from "../../operations/index.js";
-function isArgs(arg) {
-    return (typeof arg === "object" && arg !== null && "input" in arg && "output" in arg);
-}
+const optsSchema = z
+    .object({
+    input: z.string().describe("Path to SysProM Markdown (file or directory)"),
+    output: z.string().describe("Output JSON file path"),
+})
+    .strict();
 export const md2jsonCommand = {
     name: "md2json",
     description: markdownToJsonOp.def.description,
     apiLink: markdownToJsonOp.def.name,
-    args: z.object({
-        input: z.string().describe("Path to SysProM Markdown (file or directory)"),
-        output: z.string().describe("Output JSON file path"),
-    }),
-    opts: z.object({}).strict(),
-    action(args) {
-        if (!isArgs(args))
-            throw new Error("Invalid args");
-        const inputPath = resolve(args.input);
-        const outputPath = resolve(args.output);
+    opts: optsSchema,
+    action(_args, opts) {
+        const inputPath = resolve(opts.input);
+        const outputPath = resolve(opts.output);
         const doc = markdownToJson(inputPath);
         writeFileSync(outputPath, canonicalise(doc, { indent: "\t" }) + "\n");
         console.log(`Written to ${outputPath}`);

package/dist/src/cli/commands/plan.js

@@ -6,10 +6,8 @@ import { planInitOp, planAddTaskOp, planStatusOp, planProgressOp, planGateOp, }
 // ============================================================================
 // Subcommands
 // ============================================================================
-const initArgs = z.object({
-    output: z.string().describe("Path to output SysProM file"),
-});
 const initOpts = z.object({
+    output: z.string().describe("Path to output SysProM file"),
     prefix: z.string().describe("Plan prefix (e.g. PLAN)"),
     name: z.string().optional().describe("Plan name (defaults to prefix)"),
 });
@@ -17,10 +15,9 @@ const initSubcommand = {
     name: "init",
     description: planInitOp.def.description,
     apiLink: planInitOp.def.name,
-    args: initArgs,
     opts: initOpts,
-    action(args, opts) {
-        const outputPath = args.output;
+    action(_args, opts) {
+        const outputPath = opts.output;
         const prefix = opts.prefix;
         const name = opts.name ?? prefix;
         if (existsSync(outputPath)) {

package/dist/src/cli/commands/speckit.js

@@ -45,11 +45,9 @@ function compareDocuments(oldDoc, newDoc) {
 // ============================================================================
 // Subcommands
 // ============================================================================
-const importArgs = z.object({
+const importOpts = z.object({
     speckitDir: z.string().describe("Path to Spec-Kit feature directory"),
     output: z.string().describe("Path to output SysProM file"),
-});
-const importOpts = z.object({
     prefix: z
         .string()
         .optional()
@@ -58,11 +56,10 @@ const importOpts = z.object({
 const importSubcommand = {
     name: "import",
     description: speckitImportOp.def.description,
-    args: importArgs,
     opts: importOpts,
-    action(args, opts) {
-        const specKitDir = resolve(args.speckitDir);
-        const outputPath = resolve(args.output);
+    action(_args, opts) {
+        const specKitDir = resolve(opts.speckitDir);
+        const outputPath = resolve(opts.output);
         if (!existsSync(specKitDir)) {
             console.error(`Error: Spec-Kit directory does not exist: ${specKitDir}`);
             process.exit(1);
@@ -97,21 +94,18 @@ const importSubcommand = {
         console.log(`  ${String(nodeCount)} nodes, ${String(relationshipCount)} relationships`);
     },
 };
-const exportArgs = z.object({
+const exportOpts = z.object({
     input: z.string().describe("Path to SysProM document"),
     speckitDir: z.string().describe("Path to Spec-Kit output directory"),
-});
-const exportOpts = z.object({
     prefix: z.string().describe("ID prefix identifying nodes to export"),
 });
 const exportSubcommand = {
     name: "export",
     description: speckitExportOp.def.description,
-    args: exportArgs,
     opts: exportOpts,
-    action(args, opts) {
-        const inputPath = resolve(args.input);
-        const specKitDir = resolve(args.speckitDir);
+    action(_args, opts) {
+        const inputPath = resolve(opts.input);
+        const specKitDir = resolve(opts.speckitDir);
         if (!opts.prefix) {
             console.error("Error: --prefix flag is required for export (identifies which nodes to export)");
             process.exit(1);
@@ -125,11 +119,9 @@ const exportSubcommand = {
         console.log(`  Generated Spec-Kit files with prefix: ${opts.prefix}`);
     },
 };
-const syncArgs = z.object({
+const syncSubOpts = z.object({
     input: z.string().describe("Path to SysProM document"),
     speckitDir: z.string().describe("Path to Spec-Kit directory"),
-});
-const syncOpts = z.object({
     prefix: z
         .string()
         .optional()
@@ -138,11 +130,10 @@ const syncOpts = z.object({
 const syncSubcommand = {
     name: "sync",
     description: speckitSyncOp.def.description,
-    args: syncArgs,
-    opts: syncOpts,
-    action(args, opts) {
-        const inputPath = resolve(args.input);
-        const specKitDir = resolve(args.speckitDir);
+    opts: syncSubOpts,
+    action(_args, opts) {
+        const inputPath = resolve(opts.input);
+        const specKitDir = resolve(opts.speckitDir);
         if (!existsSync(inputPath)) {
             console.error(`Error: Input file does not exist: ${inputPath}`);
             process.exit(1);
@@ -226,11 +217,9 @@ const syncSubcommand = {
         }
     },
 };
-const diffArgs = z.object({
+const diffSubOpts = z.object({
     input: z.string().describe("Path to SysProM document"),
     speckitDir: z.string().describe("Path to Spec-Kit directory"),
-});
-const diffOpts = z.object({
     prefix: z
         .string()
         .optional()
@@ -239,11 +228,10 @@ const diffOpts = z.object({
 const diffSubcommand = {
     name: "diff",
     description: speckitDiffOp.def.description,
-    args: diffArgs,
-    opts: diffOpts,
-    action(args, opts) {
-        const inputPath = resolve(args.input);
-        const specKitDir = resolve(args.speckitDir);
+    opts: diffSubOpts,
+    action(_args, opts) {
+        const inputPath = resolve(opts.input);
+        const specKitDir = resolve(opts.speckitDir);
         if (!existsSync(inputPath)) {
             console.error(`Error: Input file does not exist: ${inputPath}`);
             process.exit(1);

package/dist/src/cli/commands/sync.d.ts

@@ -1,3 +1,4 @@
+import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
 import { type BidirectionalSyncResult, type ConflictStrategy } from "../../operations/index.js";
 interface SyncCommandInput {
@@ -14,5 +15,13 @@ interface SyncCommandInput {
  * const result = syncCommand({ jsonPath: "doc.spm.json", mdPath: "doc.spm.md" });
  */
 export declare function syncCommand(input: SyncCommandInput): BidirectionalSyncResult;
-export declare const syncCommandDef: CommandDef;
+declare const syncOpts: z.ZodObject<{
+    input: z.ZodString;
+    output: z.ZodString;
+    preferJson: z.ZodOptional<z.ZodBoolean>;
+    preferMd: z.ZodOptional<z.ZodBoolean>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+    report: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const syncCommandDef: CommandDef<z.ZodObject<z.ZodRawShape>, typeof syncOpts>;
 export {};

package/dist/src/cli/commands/sync.js

@@ -47,47 +47,36 @@ export function syncCommand(input) {
     }
     return result;
 }
-function isArgs(arg) {
-    return (typeof arg === "object" && arg !== null && "input" in arg && "output" in arg);
-}
-function isOpts(opt) {
-    return typeof opt === "object" && opt !== null;
-}
+const syncOpts = z
+    .object({
+    input: z.string().describe("Path to JSON file"),
+    output: z.string().describe("Path to Markdown file"),
+    preferJson: z
+        .boolean()
+        .optional()
+        .describe("Prefer JSON as source of truth in conflicts"),
+    preferMd: z
+        .boolean()
+        .optional()
+        .describe("Prefer Markdown as source of truth in conflicts"),
+    dryRun: z
+        .boolean()
+        .optional()
+        .describe("Preview changes without writing files"),
+    report: z
+        .boolean()
+        .optional()
+        .describe("Report conflicts without resolving"),
+})
+    .strict();
 export const syncCommandDef = {
     name: "sync",
     description: "Synchronise JSON and Markdown representations with conflict resolution",
     apiLink: "syncDocuments",
-    args: z.object({
-        input: z.string().describe("Path to JSON file"),
-        output: z.string().describe("Path to Markdown file"),
-    }),
-    opts: z
-        .object({
-        preferJson: z
-            .boolean()
-            .optional()
-            .describe("Prefer JSON as source of truth in conflicts"),
-        preferMd: z
-            .boolean()
-            .optional()
-            .describe("Prefer Markdown as source of truth in conflicts"),
-        dryRun: z
-            .boolean()
-            .optional()
-            .describe("Preview changes without writing files"),
-        report: z
-            .boolean()
-            .optional()
-            .describe("Report conflicts without resolving"),
-    })
-        .strict(),
-    action(args, opts) {
-        if (!isArgs(args))
-            throw new Error("Invalid args");
-        if (!isOpts(opts))
-            throw new Error("Invalid opts");
-        const jsonPath = resolve(args.input);
-        const mdPath = resolve(args.output);
+    opts: syncOpts,
+    action(_args, opts) {
+        const jsonPath = resolve(opts.input);
+        const mdPath = resolve(opts.output);
         // Determine conflict strategy
         let strategy = "json";
         if (opts.preferMd)

package/dist/src/cli/shared.d.ts

@@ -1,26 +1,29 @@
 import * as z from "zod";
 import { type Format } from "../io.js";
 import type { SysProMDocument } from "../schema.js";
-/** @deprecated Use --path option in readOpts/mutationOpts instead. */
-export declare const inputArg: z.ZodString;
 /** Empty args schema for commands that take no positional arguments. */
 export declare const noArgs: z.ZodObject<{}, z.core.$strict>;
 /**
  * Resolve a SysProM document path. If no explicit path is given, search the
  * working directory by priority:
- *   1. .spm.json     2. .spm.md     3. .spm/
- *   4. .sysprom.json  5. .sysprom.md  6. .sysprom/
- *   7. *.spm.json    8. *.spm.md    9. *.spm/
- *  10. *.sysprom.json 11. *.sysprom.md 12. *.sysprom/
+ *   1. .SysProM.json   2. .SysProM.md   3. .SysProM/
+ *   4. .spm.json       5. .spm.md       6. .spm/
+ *   7. .sysprom.json   8. .sysprom.md   9. .sysprom/
+ *  10. *.SysProM.json  11. *.SysProM.md 12. *.SysProM/
+ *  13. *.spm.json     14. *.spm.md     15. *.spm/
+ *  16. *.sysprom.json 17. *.sysprom.md 18. *.sysprom/
  *
- * All matching is case-insensitive. Glob tiers must have exactly one match.
+ * Matching is case-insensitive for base names and directory matches.
+ * Files like .SysProM.json, .sysprom.json, and .SYSPROM.JSON are treated
+ * as equivalent and all match the .SysProM.json priority tier.
+ * Glob tiers must have exactly one match.
  * @param input - Explicit document path, or undefined for auto-detection.
  * @param cwd - Working directory to search from (defaults to `.`).
  * @returns The resolved document path.
  * @example
  * ```ts
- * resolveInput() // => auto-detects ".spm.json" in cwd
- * resolveInput("my-doc.spm.json") // => "my-doc.spm.json"
+ * resolveInput() // => auto-detects ".SysProM.json" in cwd
+ * resolveInput("my-doc.SysProM.json") // => "my-doc.SysProM.json"
  * ```
  */
 export declare function resolveInput(input?: string, cwd?: string): string;

package/dist/src/cli/shared.js

@@ -6,10 +6,6 @@ import { jsonToMarkdownMultiDoc } from "../json-to-md.js";
 // ---------------------------------------------------------------------------
 // Reusable CLI schemas — shared across all commands
 // ---------------------------------------------------------------------------
-/** @deprecated Use --path option in readOpts/mutationOpts instead. */
-export const inputArg = z
-    .string()
-    .describe("SysProM document path (JSON, .md, or directory)");
 /** Empty args schema for commands that take no positional arguments. */
 export const noArgs = z.object({}).strict();
 /** Shared --path option for specifying the SysProM document location. */
@@ -23,27 +19,34 @@ const pathOpt = z
 /**
  * Resolve a SysProM document path. If no explicit path is given, search the
  * working directory by priority:
- *   1. .spm.json     2. .spm.md     3. .spm/
- *   4. .sysprom.json  5. .sysprom.md  6. .sysprom/
- *   7. *.spm.json    8. *.spm.md    9. *.spm/
- *  10. *.sysprom.json 11. *.sysprom.md 12. *.sysprom/
+ *   1. .SysProM.json   2. .SysProM.md   3. .SysProM/
+ *   4. .spm.json       5. .spm.md       6. .spm/
+ *   7. .sysprom.json   8. .sysprom.md   9. .sysprom/
+ *  10. *.SysProM.json  11. *.SysProM.md 12. *.SysProM/
+ *  13. *.spm.json     14. *.spm.md     15. *.spm/
+ *  16. *.sysprom.json 17. *.sysprom.md 18. *.sysprom/
  *
- * All matching is case-insensitive. Glob tiers must have exactly one match.
+ * Matching is case-insensitive for base names and directory matches.
+ * Files like .SysProM.json, .sysprom.json, and .SYSPROM.JSON are treated
+ * as equivalent and all match the .SysProM.json priority tier.
+ * Glob tiers must have exactly one match.
  * @param input - Explicit document path, or undefined for auto-detection.
  * @param cwd - Working directory to search from (defaults to `.`).
  * @returns The resolved document path.
  * @example
  * ```ts
- * resolveInput() // => auto-detects ".spm.json" in cwd
- * resolveInput("my-doc.spm.json") // => "my-doc.spm.json"
+ * resolveInput() // => auto-detects ".SysProM.json" in cwd
+ * resolveInput("my-doc.SysProM.json") // => "my-doc.SysProM.json"
  * ```
  */
 export function resolveInput(input, cwd) {
     if (input)
         return input;
     const dir = resolve(cwd ?? ".");
-    // Exact names to check, in priority order (case-insensitive)
     const exactNames = [
+        ".SysProM.json",
+        ".SysProM.md",
+        ".SysProM",
         ".spm.json",
         ".spm.md",
         ".spm",
@@ -52,9 +55,42 @@ export function resolveInput(input, cwd) {
         ".sysprom",
     ];
     const entries = readdirSync(dir);
+    // Phase 1: Try exact case-sensitive matches first
+    for (const name of exactNames) {
+        const isDirSuffix = name.endsWith(".SysProM") ||
+            name.endsWith(".spm") ||
+            name.endsWith(".sysprom");
+        const found = entries.filter((e) => e === name);
+        if (found.length === 1) {
+            // Before returning, check for case-variant collisions on case-sensitive
+            // filesystems (e.g. both .spm.json and .SPM.json exist).
+            const nameLower = name.toLowerCase();
+            const caseVariants = entries.filter((e) => e !== name && e.toLowerCase() === nameLower);
+            if (caseVariants.length > 0) {
+                throw new Error(`Multiple SysProM documents found: ${[name, ...caseVariants].join(", ")}. Specify one explicitly.`);
+            }
+            const candidate = join(dir, found[0]);
+            if (isDirSuffix) {
+                try {
+                    if (statSync(candidate).isDirectory())
+                        return candidate;
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            else {
+                return candidate;
+            }
+        }
+    }
+    // Phase 2: Try case-insensitive matches (supports case variations like .SPM.JSON)
     for (const name of exactNames) {
-        const isDirSuffix = name.endsWith(".spm") || name.endsWith(".sysprom");
-        const found = entries.filter((e) => e.toLowerCase() === name);
+        const isDirSuffix = name.endsWith(".SysProM") ||
+            name.endsWith(".spm") ||
+            name.endsWith(".sysprom");
+        const nameLower = name.toLowerCase();
+        const found = entries.filter((e) => e.toLowerCase() === nameLower);
         if (found.length > 1) {
             throw new Error(`Multiple SysProM documents found: ${found.join(", ")}. Specify one explicitly.`);
         }
@@ -76,6 +112,9 @@ export function resolveInput(input, cwd) {
     }
     // Glob suffixes in priority order (case-insensitive)
     const globSuffixes = [
+        ".SysProM.json",
+        ".SysProM.md",
+        ".SysProM",
         ".spm.json",
         ".spm.md",
         ".spm",
@@ -84,11 +123,16 @@ export function resolveInput(input, cwd) {
         ".sysprom",
     ];
     for (const suffix of globSuffixes) {
-        const isDirSuffix = suffix === ".spm" || suffix === ".sysprom";
+        const isDirSuffix = suffix === ".SysProM" || suffix === ".spm" || suffix === ".sysprom";
+        const suffixLower = suffix.toLowerCase();
         const matches = entries
             .filter((e) => {
             const lower = e.toLowerCase();
-            return lower.endsWith(suffix) && lower !== suffix;
+            // Match files ending with this suffix (case-insensitive) that don't start with "."
+            // and are not exact matches (those were already checked)
+            return (lower.endsWith(suffixLower) &&
+                lower !== suffixLower &&
+                !e.startsWith("."));
         })
             .map((e) => join(dir, e))
             .filter((p) => {

package/dist/src/json-to-md.js

@@ -22,6 +22,58 @@ function renderFrontMatter(fields) {
     lines.push("---");
     return lines.join("\n");
 }
+// ---------------------------------------------------------------------------
+// Node location map (for hyperlinking)
+// ---------------------------------------------------------------------------
+/** GitHub-compatible heading anchor slug. */
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/\s/g, "-");
+}
+/** Heading anchor for a node: `id--name` slugified from `### ID — Name`. */
+function nodeAnchor(n) {
+    return slugify(`${n.id} — ${n.name}`);
+}
+/** Build a map from node ID to its markdown file and heading anchor. */
+function buildNodeLocationMap(nodes, mode) {
+    const map = new Map();
+    for (const n of nodes) {
+        const anchor = nodeAnchor(n);
+        if (mode === "single-file") {
+            map.set(n.id, { file: "", anchor });
+        }
+        else {
+            const file = fileForNodeType(n.type);
+            map.set(n.id, { file, anchor });
+        }
+    }
+    return map;
+}
+/** Determine the markdown file a node type belongs to in multi-doc mode. */
+function fileForNodeType(type) {
+    for (const [fileName, types] of Object.entries(NODE_FILE_MAP)) {
+        if (types.includes(type))
+            return `${fileName}.md`;
+    }
+    return "README.md";
+}
+/**
+ * Format a node ID as a markdown hyperlink.
+ * In single-file mode: `[ID](#anchor)`
+ * In multi-doc mode: `[ID](./FILE.md#anchor)`
+ * Falls back to plain ID if the node isn't in the map.
+ */
+function linkNodeId(id, nodeMap, currentFile) {
+    const loc = nodeMap.get(id);
+    if (!loc)
+        return id;
+    if (loc.file === "" || loc.file === currentFile) {
+        return `[${id}](#${loc.anchor})`;
+    }
+    return `[${id}](./${loc.file}#${loc.anchor})`;
+}
 function indexRelationshipsFrom(rels) {
     const idx = new Map();
     for (const r of rels) {
@@ -79,7 +131,7 @@ function renderLifecycle(lifecycle) {
         return `- [${checkbox}] ${label}`;
     });
 }
-function renderNodeRelationships(nodeId, fromIdx) {
+function renderNodeRelationships(nodeId, fromIdx, nodeMap, currentFile) {
     const rels = fromIdx.get(nodeId);
     if (!rels || rels.length === 0)
         return [];
@@ -97,12 +149,12 @@ function renderNodeRelationships(nodeId, fromIdx) {
             ? RELATIONSHIP_TYPE_LABELS[type]
             : type;
         if (targets.length === 1) {
-            lines.push(`- ${label}: ${targets[0]}`);
+            lines.push(`- ${label}: ${linkNodeId(targets[0], nodeMap, currentFile)}`);
         }
         else {
             lines.push(`- ${label}:`);
             for (const t of targets) {
-                lines.push(`  - ${t}`);
+                lines.push(`  - ${linkNodeId(t, nodeMap, currentFile)}`);
             }
         }
     }
@@ -123,7 +175,7 @@ function renderExternalReferences(refs) {
     }
     return lines;
 }
-function renderNode(n, headingLevel, fromIdx) {
+function renderNode(n, headingLevel, fromIdx, nodeMap, currentFile) {
     const prefix = "#".repeat(headingLevel);
     const lines = [];
     lines.push(`${prefix} ${n.id} — ${n.name}`);
@@ -132,7 +184,7 @@ function renderNode(n, headingLevel, fromIdx) {
         lines.push(renderText(n.description));
         lines.push("");
     }
-    const rels = renderNodeRelationships(n.id, fromIdx);
+    const rels = renderNodeRelationships(n.id, fromIdx, nodeMap, currentFile);
     if (rels.length > 0) {
         lines.push(...rels);
         lines.push("");
@@ -207,7 +259,7 @@ function renderNode(n, headingLevel, fromIdx) {
     if (n.includes && n.includes.length > 0) {
         lines.push("Includes:");
         for (const inc of n.includes) {
-            lines.push(`- ${inc}`);
+            lines.push(`- ${linkNodeId(inc, nodeMap, currentFile)}`);
         }
         lines.push("");
     }
@@ -233,8 +285,9 @@ function renderNode(n, headingLevel, fromIdx) {
         const subNodes = n.subsystem.nodes;
         const subRels = n.subsystem.relationships ?? [];
         const subIdx = indexRelationshipsFrom(subRels);
+        const subMap = buildNodeLocationMap(subNodes, "single-file");
         for (const sub of subNodes) {
-            lines.push(...renderNode(sub, headingLevel + 2, subIdx));
+            lines.push(...renderNode(sub, headingLevel + 2, subIdx, subMap));
         }
     }
     return lines;
@@ -242,7 +295,7 @@ function renderNode(n, headingLevel, fromIdx) {
 // ---------------------------------------------------------------------------
 // File generators
 // ---------------------------------------------------------------------------
-function renderNodesGrouped(nodes, types, fromIdx, headingLevel) {
+function renderNodesGrouped(nodes, types, fromIdx, headingLevel, nodeMap, currentFile) {
     const lines = [];
     for (const type of types) {
         const matching = nodes.filter((n) => n.type === type);
@@ -252,12 +305,12 @@ function renderNodesGrouped(nodes, types, fromIdx, headingLevel) {
         lines.push(`${"#".repeat(headingLevel)} ${label}`);
         lines.push("");
         for (const n of matching) {
-            lines.push(...renderNode(n, headingLevel + 1, fromIdx));
+            lines.push(...renderNode(n, headingLevel + 1, fromIdx, nodeMap, currentFile));
         }
     }
     return lines;
 }
-function generateReadme(doc, fromIdx) {
+function generateReadme(doc, fromIdx, nodeMap) {
     const lines = [];
     const title = doc.metadata?.title ?? "SysProM";
     lines.push(renderFrontMatter({
@@ -329,7 +382,7 @@ function generateReadme(doc, fromIdx) {
     // Views
     const views = doc.nodes.filter((n) => n.type === "view");
     if (views.length > 0) {
-        lines.push(...renderNodesGrouped(doc.nodes, ["view"], fromIdx, 2));
+        lines.push(...renderNodesGrouped(doc.nodes, ["view"], fromIdx, 2, nodeMap, "README.md"));
     }
     // Graph-level external references
     if (doc.external_references && doc.external_references.length > 0) {
@@ -347,7 +400,7 @@ function generateReadme(doc, fromIdx) {
     }
     return lines.join("\n") + "\n";
 }
-function generateDocFile(doc, fileName, types, fromIdx) {
+function generateDocFile(doc, fileName, types, fromIdx, nodeMap) {
     const lines = [];
     lines.push(renderFrontMatter({
         title: fileName.replace(".md", ""),
@@ -356,7 +409,7 @@ function generateDocFile(doc, fileName, types, fromIdx) {
     lines.push("");
     lines.push(`# ${fileName.replace(".md", "")}`);
     lines.push("");
-    lines.push(...renderNodesGrouped(doc.nodes, types, fromIdx, 2));
+    lines.push(...renderNodesGrouped(doc.nodes, types, fromIdx, 2, nodeMap, `${fileName}.md`));
     return lines.join("\n") + "\n";
 }
 /**
@@ -371,6 +424,7 @@ function generateDocFile(doc, fileName, types, fromIdx) {
  */
 export function jsonToMarkdownSingle(doc) {
     const fromIdx = indexRelationshipsFrom(doc.relationships ?? []);
+    const nodeMap = buildNodeLocationMap(doc.nodes, "single-file");
     const lines = [];
     const title = doc.metadata?.title ?? "SysProM";
     lines.push(renderFrontMatter({
@@ -394,7 +448,7 @@ export function jsonToMarkdownSingle(doc) {
         "milestone",
         "version",
     ];
-    lines.push(...renderNodesGrouped(doc.nodes, allTypes, fromIdx, 2));
+    lines.push(...renderNodesGrouped(doc.nodes, allTypes, fromIdx, 2, nodeMap));
     // Relationships summary
     if (doc.relationships && doc.relationships.length > 0) {
         lines.push("## Relationships");
@@ -433,12 +487,13 @@ export function jsonToMarkdownSingle(doc) {
 export function jsonToMarkdownMultiDoc(doc, outDir) {
     mkdirSync(outDir, { recursive: true });
     const fromIdx = indexRelationshipsFrom(doc.relationships ?? []);
-    writeFileSync(join(outDir, "README.md"), generateReadme(doc, fromIdx));
+    const nodeMap = buildNodeLocationMap(doc.nodes, "multi-doc");
+    writeFileSync(join(outDir, "README.md"), generateReadme(doc, fromIdx, nodeMap));
     for (const [fileName, types] of Object.entries(NODE_FILE_MAP)) {
         const hasNodes = doc.nodes.some((n) => types.includes(n.type));
         if (!hasNodes)
             continue;
-        writeFileSync(join(outDir, `${fileName}.md`), generateDocFile(doc, fileName, types, fromIdx));
+        writeFileSync(join(outDir, `${fileName}.md`), generateDocFile(doc, fileName, types, fromIdx, nodeMap));
     }
     // Subsystem folders or single files
     const subsystemNodes = doc.nodes.filter((n) => n.subsystem);

package/dist/src/mcp/server.js

@@ -2,7 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as z from "zod";
-import { loadDocument } from "../io.js";
+import { loadDocument, saveDocument } from "../io.js";
 import { NodeType, RelationshipType } from "../schema.js";
 import { validateOp, statsOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, nextIdOp, } from "../operations/index.js";
 // Create MCP server instance
@@ -145,14 +145,14 @@ server.registerTool("add-node", {
         description: z.string().optional().describe("Node description"),
     }),
 }, ({ path, type, id, name, description }) => {
-    const { doc } = loadDocument(path);
+    const loaded = loadDocument(path);
     const nodeType = NodeType.safeParse(type);
     if (!nodeType.success) {
         throw new Error(`Invalid node type: "${type}". Valid types: ${NodeType.options.join(", ")}`);
     }
-    const nodeId = id ?? nextIdOp({ doc, type: nodeType.data });
+    const nodeId = id ?? nextIdOp({ doc: loaded.doc, type: nodeType.data });
     const updated = addNodeOp({
-        doc,
+        doc: loaded.doc,
         node: {
             id: nodeId,
             type: nodeType.data,
@@ -160,6 +160,7 @@ server.registerTool("add-node", {
             ...(description && { description }),
         },
     });
+    saveDocument(updated, loaded.format, loaded.path);
     return {
         content: [
             {
@@ -181,8 +182,9 @@ server.registerTool("remove-node", {
         id: z.string().describe("Node ID"),
     }),
 }, ({ path, id }) => {
-    const { doc } = loadDocument(path);
-    const result = removeNodeOp({ doc, id });
+    const loaded = loadDocument(path);
+    const result = removeNodeOp({ doc: loaded.doc, id });
+    saveDocument(result.doc, loaded.format, loaded.path);
     return {
         content: [
             {
@@ -205,7 +207,7 @@ server.registerTool("update-node", {
         fields: z.record(z.string(), z.unknown()).describe("Fields to update"),
     }),
 }, ({ path, id, fields }) => {
-    const { doc } = loadDocument(path);
+    const loaded = loadDocument(path);
     // Validate fields are valid node property updates
     const validFields = Object.entries(fields).reduce((acc, [key, value]) => {
         // Allow common node fields; unknown fields are silently ignored
@@ -231,10 +233,11 @@ server.registerTool("update-node", {
         return acc;
     }, {});
     const updated = updateNodeOp({
-        doc,
+        doc: loaded.doc,
         id,
         fields: validFields,
     });
+    saveDocument(updated, loaded.format, loaded.path);
     const node = updated.nodes.find((n) => n.id === id);
     return {
         content: [
@@ -255,19 +258,20 @@ server.registerTool("add-relationship", {
         type: z.string().describe("Relationship type"),
     }),
 }, ({ path, from, to, type }) => {
-    const { doc } = loadDocument(path);
+    const loaded = loadDocument(path);
     const relType = RelationshipType.safeParse(type);
     if (!relType.success) {
         throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
     }
     const updated = addRelationshipOp({
-        doc,
+        doc: loaded.doc,
         rel: {
             from,
             to,
             type: relType.data,
         },
     });
+    saveDocument(updated, loaded.format, loaded.path);
     return {
         content: [
             {
@@ -290,17 +294,18 @@ server.registerTool("remove-relationship", {
         type: z.string().describe("Relationship type"),
     }),
 }, ({ path, from, to, type }) => {
-    const { doc } = loadDocument(path);
+    const loaded = loadDocument(path);
     const relType = RelationshipType.safeParse(type);
     if (!relType.success) {
         throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
     }
     const result = removeRelationshipOp({
-        doc,
+        doc: loaded.doc,
         from,
         to,
         type: relType.data,
     });
+    saveDocument(result.doc, loaded.format, loaded.path);
     return {
         content: [
             {

package/dist/src/md-to-json.js

@@ -2,6 +2,10 @@ import * as z from "zod";
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, basename } from "node:path";
 import { NODE_FILE_MAP, NODE_LABEL_TO_TYPE, RELATIONSHIP_TYPE_LABELS, RELATIONSHIP_LABEL_TO_TYPE, NodeType, RelationshipType, NodeStatus, ExternalReferenceRole, } from "./schema.js";
+/** Strip markdown link syntax `[text](url)` → `text`. */
+function stripMarkdownLink(s) {
+    return s.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+}
 const LABEL_TO_TYPE = Object.fromEntries(Object.entries(NODE_LABEL_TO_TYPE).map(([k, v]) => [k.toLowerCase(), v]));
 const operationType = z.enum(["add", "update", "remove", "link"]);
 function parseNodeType(s) {
@@ -162,18 +166,18 @@ function parseListItems(body, prefix) {
             collecting = true;
             const inline = line.slice(prefix.length + 1).trim();
             if (inline) {
-                items.push(inline);
+                items.push(stripMarkdownLink(inline));
                 collecting = false;
             }
             continue;
         }
         if (collecting && line.startsWith("  - ")) {
-            items.push(line.slice(4));
+            items.push(stripMarkdownLink(line.slice(4)));
         }
         else if (collecting &&
             line.startsWith("- ") &&
             !isRelationshipLabel(line)) {
-            items.push(line.slice(2));
+            items.push(stripMarkdownLink(line.slice(2)));
         }
         else if (collecting) {
             collecting = false;
@@ -210,7 +214,7 @@ function parseRelationshipsFromBody(body, nodeId) {
         if (items.length === 0) {
             const val = parseSingleValue(body, `- ${label}`);
             if (val) {
-                rels.push({ from: nodeId, to: val, type: relType });
+                rels.push({ from: nodeId, to: stripMarkdownLink(val), type: relType });
             }
         }
         else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sysprom",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "SysProM — System Provenance Model CLI and library",
   "author": "ExaDev",
   "homepage": "https://exadev.github.io/SysProM",