sysprom 1.2.1 → 1.2.3

package/README.md

@@ -124,24 +124,33 @@ SysProM models systems as directed graphs across abstraction layers — intent,
 
 ## How SysProM Compares
 
-| System | Readable | Parseable | State | Rationale | History | Constraints | Nesting | Diagrams | Inference | Impact | Temporal | Scaffolding | Planning | Tracking |
-|--------|----------|-----------|-------|-----------|---------|-------------|---------|----------|-----------|--------|----------|-------------|----------|----------|
-| [MBSE (SysML)](https://www.omg.org/spec/SysML/) | 🔶 | ✅ | ✅ | 🔶 | 🔶 | ✅ | ✅ | ✅ | | ✅ | | | | |
-| [Knowledge Graphs](https://www.w3.org/TR/rdf12-concepts/) | | ✅ | ✅ | | | 🔶 | ✅ | 🔶 | ✅ | | | | | |
-| [EA (ArchiMate)](https://pubs.opengroup.org/architecture/archimate-spec/) | ✅ | 🔶 | ✅ | | | 🔶 | 🔶 | ✅ | | ✅ | | | | |
-| [Git](https://git-scm.com/) | 🔶 | ✅ | ✅ | | ✅ | | | | | | ✅ | | | 🔶 |
-| [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) | | ✅ | 🔶 | | ✅ | 🔶 | | | | | ✅ | | | |
-| [DDD](https://www.domainlanguage.com/ddd/) | ✅ | | ✅ | | | 🔶 | 🔶 | | | | | | | |
-| [C4](https://c4model.com/) | ✅ | | ✅ | | | | 🔶 | ✅ | | | | | | |
-| [Traceability Matrices](https://en.wikipedia.org/wiki/Traceability_matrix) | ✅ | | ✅ | | | 🔶 | | | | 🔶 | | | | 🔶 |
-| [Spec Kit](https://github.com/github/spec-kit) | ✅ | | ✅ | 🔶 | 🔶 | | 🔶 | | | | | ✅ | ✅ | ✅ |
-| [ADR](https://adr.github.io/) | ✅ | | | ✅ | 🔶 | | | | | | | | | |
-| [RFC Processes](https://www.rfc-editor.org/rfc/rfc2026) | ✅ | | | ✅ | 🔶 | | | | | | | | 🔶 | 🔶 |
-| [Ralplan](https://github.com/yeachan-heo/oh-my-claudecode/blob/main/skills/ralplan/SKILL.md) | ✅ | | 🔶 | ✅ | | 🔶 | | | | | | | ✅ | 🔶 |
-| [GSD](https://github.com/gsd-build/get-shit-done) | ✅ | | | 🔶 | | 🔶 | | | | | | | | |
-| [OpenSpec](https://github.com/Fission-AI/OpenSpec) | ✅ | 🔶 | ✅ | ✅ | ✅ | | 🔶 | | | | | ✅ | ✅ | ✅ |
-| [Superpowers](https://github.com/obra/superpowers) | ✅ | 🔶 | 🔶 | 🔶 | 🔶 | ✅ | 🔶 | | ✅ | 🔶 | | ✅ | ✅ | ✅ |
-| **SysProM** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🔶 | | 🔶 | ✅ | ✅ | ✅ | ✅ |
+| System | Readable | Parseable | State | Nesting | Diagrams | Rationale | Constraints | History | Temporal | Inference | Impact | Scaffolding | Planning | Tracking |
+|--------|----------|-----------|-------|---------|----------|-----------|-------------|---------|----------|-----------|--------|-------------|----------|----------|
+| [MBSE (SysML)](https://www.omg.org/spec/SysML/) | 🔶 | ✅ | ✅ | ✅ | ✅ | 🔶 | ✅ | 🔶 | | | ✅ | | | |
+| [Knowledge Graphs](https://www.w3.org/TR/rdf12-concepts/) | | ✅ | ✅ | ✅ | 🔶 | | 🔶 | | | ✅ | | | | |
+| [EA (ArchiMate)](https://pubs.opengroup.org/architecture/archimate-spec/) | ✅ | 🔶 | ✅ | 🔶 | ✅ | | 🔶 | | | | ✅ | | | |
+| [Git](https://git-scm.com/) | 🔶 | ✅ | ✅ | | | | | ✅ | ✅ | | | | | 🔶 |
+| [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) | | ✅ | 🔶 | | | | 🔶 | ✅ | ✅ | | | | | |
+| [DDD](https://www.domainlanguage.com/ddd/) | ✅ | | ✅ | 🔶 | | | 🔶 | | | | | | | |
+| [C4](https://c4model.com/) | ✅ | | ✅ | 🔶 | ✅ | | | | | | | | | |
+| [Traceability Matrices](https://en.wikipedia.org/wiki/Traceability_matrix) | ✅ | | ✅ | | | | 🔶 | | | | 🔶 | | | 🔶 |
+| [PRD](https://en.wikipedia.org/wiki/Product_requirements_document) | ✅ | | 🔶 | 🔶 | 🔶 | ✅ | 🔶 | 🔶 | | | 🔶 | | ✅ | 🔶 |
+| [ADR](https://adr.github.io/) | ✅ | | | | | ✅ | | 🔶 | | | | | | |
+| [RFC Processes](https://www.rfc-editor.org/rfc/rfc2026) | ✅ | | | | | ✅ | | 🔶 | | | | | 🔶 | 🔶 |
+| [BDD (Gherkin)](https://cucumber.io/docs/gherkin/) | ✅ | ✅ | 🔶 | 🔶 | | | ✅ | | | | | 🔶 | 🔶 | ✅ |
+| [Spec Kit](https://github.com/github/spec-kit) | ✅ | | ✅ | 🔶 | | 🔶 | | 🔶 | | | | ✅ | ✅ | ✅ |
+| [Ralplan](https://github.com/yeachan-heo/oh-my-claudecode/blob/main/skills/ralplan/SKILL.md) | ✅ | | 🔶 | | | ✅ | 🔶 | | | | | | ✅ | 🔶 |
+| [GSD](https://github.com/gsd-build/get-shit-done) | ✅ | | | | | 🔶 | 🔶 | | | | | | | |
+| [GSD-2](https://github.com/gsd-build/gsd-2) | ✅ | 🔶 | ✅ | ✅ | | 🔶 | 🔶 | ✅ | | | 🔶 | ✅ | ✅ | ✅ |
+| [Taskmaster](https://github.com/eyaltoledano/claude-task-master) | ✅ | ✅ | ✅ | ✅ | | 🔶 | | 🔶 | | 🔶 | 🔶 | 🔶 | ✅ | ✅ |
+| [OpenSpec](https://github.com/Fission-AI/OpenSpec) | ✅ | 🔶 | ✅ | 🔶 | | ✅ | | ✅ | | | | ✅ | ✅ | ✅ |
+| [Kiro](https://github.com/kirodotdev/Kiro) | ✅ | 🔶 | ✅ | 🔶 | | 🔶 | 🔶 | 🔶 | | | 🔶 | ✅ | ✅ | ✅ |
+| [cc-sdd](https://github.com/gotalab/cc-sdd) | ✅ | 🔶 | ✅ | 🔶 | | 🔶 | 🔶 | 🔶 | | | 🔶 | ✅ | ✅ | ✅ |
+| [Ouroboros](https://github.com/Q00/ouroboros) | ✅ | 🔶 | ✅ | | | ✅ | ✅ | 🔶 | | ✅ | 🔶 | 🔶 | ✅ | 🔶 |
+| [Spec Kitty](https://github.com/Priivacy-ai/spec-kitty) | ✅ | 🔶 | ✅ | 🔶 | | 🔶 | 🔶 | 🔶 | | | 🔶 | ✅ | ✅ | ✅ |
+| [Shotgun](https://github.com/shotgun-sh/shotgun) | ✅ | 🔶 | 🔶 | | | 🔶 | | 🔶 | | | 🔶 | 🔶 | ✅ | 🔶 |
+| [Superpowers](https://github.com/obra/superpowers) | ✅ | 🔶 | 🔶 | 🔶 | | 🔶 | ✅ | 🔶 | | ✅ | 🔶 | ✅ | ✅ | ✅ |
+| **SysProM** | ✅ | ✅ | ✅ | ✅ | 🔶 | ✅ | ✅ | ✅ | ✅ | | 🔶 | ✅ | ✅ | ✅ |
 
 ✅ = first-class support. 🔶 = partial or implicit.
 

package/dist/src/canonical-json.d.ts

@@ -20,5 +20,10 @@ export interface FormatOptions {
  * @param value - The value to serialise.
  * @param options - Formatting options (e.g. indentation).
  * @returns The canonical JSON string.
+ * @example
+ * ```ts
+ * canonicalise({ b: 1, a: 2 }) // => '{"a":2,"b":1}'
+ * canonicalise({ b: 1 }, { indent: "\t" }) // => '{\n\t"b": 1\n}'
+ * ```
  */
 export declare function canonicalise(value: unknown, options?: FormatOptions): string;

package/dist/src/canonical-json.js

@@ -15,6 +15,11 @@
  * @param value - The value to serialise.
  * @param options - Formatting options (e.g. indentation).
  * @returns The canonical JSON string.
+ * @example
+ * ```ts
+ * canonicalise({ b: 1, a: 2 }) // => '{"a":2,"b":1}'
+ * canonicalise({ b: 1 }, { indent: "\t" }) // => '{\n\t"b": 1\n}'
+ * ```
  */
 export function canonicalise(value, options = {}) {
     const indent = options.indent ?? "";

package/dist/src/cli/define-command.d.ts

@@ -15,6 +15,12 @@ export interface CommandDef<TArgs extends z.ZodObject<z.ZodRawShape> = z.ZodObje
  * @param def - The command definition to build from.
  * @param parent - The parent Commander command to attach to.
  * @returns The constructed Commander command.
+ * @example
+ * ```ts
+ * const program = new Command();
+ * buildCommander(myCommandDef, program);
+ * program.parse(process.argv);
+ * ```
  */
 export declare function buildCommander(def: CommandDef, parent: Command): Command;
 /** Extracted documentation for a CLI positional argument. */
@@ -45,5 +51,10 @@ export interface CommandDoc {
  * Extract structured documentation from a CommandDef by introspecting its Zod schemas for args and options.
  * @param def - The command definition to extract docs from.
  * @returns Structured documentation for the command.
+ * @example
+ * ```ts
+ * const docs = extractDocs(validateCommand);
+ * console.log(docs.name, docs.args, docs.opts);
+ * ```
  */
 export declare function extractDocs(def: CommandDef): CommandDoc;

package/dist/src/cli/define-command.js

@@ -82,6 +82,12 @@ function collect(value, previous) {
  * @param def - The command definition to build from.
  * @param parent - The parent Commander command to attach to.
  * @returns The constructed Commander command.
+ * @example
+ * ```ts
+ * const program = new Command();
+ * buildCommander(myCommandDef, program);
+ * program.parse(process.argv);
+ * ```
  */
 export function buildCommander(def, parent) {
     const cmd = parent.command(def.name);
@@ -200,6 +206,11 @@ export function buildCommander(def, parent) {
  * Extract structured documentation from a CommandDef by introspecting its Zod schemas for args and options.
  * @param def - The command definition to extract docs from.
  * @returns Structured documentation for the command.
+ * @example
+ * ```ts
+ * const docs = extractDocs(validateCommand);
+ * console.log(docs.name, docs.args, docs.opts);
+ * ```
  */
 export function extractDocs(def) {
     const args = [];

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

@@ -17,6 +17,11 @@ export declare const noArgs: z.ZodObject<{}, z.core.$strict>;
  * @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"
+ * ```
  */
 export declare function resolveInput(input?: string, cwd?: string): string;
 /** Common output/persistence options for read-only commands. */
@@ -45,6 +50,10 @@ export interface LoadedDoc {
  * Load a document from a CLI input path (auto-resolved if omitted).
  * @param input - Explicit document path, or undefined for auto-detection.
  * @returns The loaded document with format and resolved path.
+ * @example
+ * ```ts
+ * const { doc, format, path } = loadDoc();
+ * ```
  */
 export declare function loadDoc(input?: string): LoadedDoc;
 /**
@@ -52,5 +61,11 @@ export declare function loadDoc(input?: string): LoadedDoc;
  * @param doc - The document to save.
  * @param loaded - The original loaded document (provides format and path).
  * @param opts - Mutation options (e.g. sync-to-markdown flag).
+ * @example
+ * ```ts
+ * const loaded = loadDoc();
+ * const updated = addNodeOp({ doc: loaded.doc, node });
+ * persistDoc(updated, loaded, { syncMd: "./SysProM" });
+ * ```
  */
 export declare function persistDoc(doc: SysProMDocument, loaded: LoadedDoc, opts: MutationOpts): void;

package/dist/src/cli/shared.js

@@ -32,6 +32,11 @@ const pathOpt = z
  * @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"
+ * ```
  */
 export function resolveInput(input, cwd) {
     if (input)
@@ -129,6 +134,10 @@ export const mutationOpts = z.object({
  * Load a document from a CLI input path (auto-resolved if omitted).
  * @param input - Explicit document path, or undefined for auto-detection.
  * @returns The loaded document with format and resolved path.
+ * @example
+ * ```ts
+ * const { doc, format, path } = loadDoc();
+ * ```
  */
 export function loadDoc(input) {
     return loadDocument(resolveInput(input));
@@ -138,6 +147,12 @@ export function loadDoc(input) {
  * @param doc - The document to save.
  * @param loaded - The original loaded document (provides format and path).
  * @param opts - Mutation options (e.g. sync-to-markdown flag).
+ * @example
+ * ```ts
+ * const loaded = loadDoc();
+ * const updated = addNodeOp({ doc: loaded.doc, node });
+ * persistDoc(updated, loaded, { syncMd: "./SysProM" });
+ * ```
  */
 export function persistDoc(doc, loaded, opts) {
     if (!opts.dryRun) {

package/dist/src/io.d.ts

@@ -14,6 +14,10 @@ export interface LoadedDocument {
  * Load a SysProM document from a file (JSON or Markdown).
  * @param input - File path or directory to load from.
  * @returns The loaded document with its detected format and resolved path.
+ * @example
+ * ```ts
+ * const { doc, format } = loadDocument("project.spm.json");
+ * ```
  */
 export declare function loadDocument(input: string): LoadedDocument;
 /**
@@ -21,5 +25,10 @@ export declare function loadDocument(input: string): LoadedDocument;
  * @param doc - The SysProM document to save.
  * @param format - Output format: 'json', 'single-md', or 'multi-md'.
  * @param path - Destination file path or directory.
+ * @example
+ * ```ts
+ * saveDocument(doc, "json", "output.spm.json");
+ * saveDocument(doc, "multi-md", "./SysProM");
+ * ```
  */
 export declare function saveDocument(doc: SysProMDocument, format: Format, path: string): void;

package/dist/src/io.js

@@ -16,6 +16,10 @@ function detectFormat(input) {
  * Load a SysProM document from a file (JSON or Markdown).
  * @param input - File path or directory to load from.
  * @returns The loaded document with its detected format and resolved path.
+ * @example
+ * ```ts
+ * const { doc, format } = loadDocument("project.spm.json");
+ * ```
  */
 export function loadDocument(input) {
     const path = resolve(input);
@@ -48,6 +52,11 @@ export function loadDocument(input) {
  * @param doc - The SysProM document to save.
  * @param format - Output format: 'json', 'single-md', or 'multi-md'.
  * @param path - Destination file path or directory.
+ * @example
+ * ```ts
+ * saveDocument(doc, "json", "output.spm.json");
+ * saveDocument(doc, "multi-md", "./SysProM");
+ * ```
  */
 export function saveDocument(doc, format, path) {
     switch (format) {

package/dist/src/json-to-md.d.ts

@@ -7,12 +7,21 @@ export interface ConvertOptions {
  * Convert a SysProM document to a single Markdown string.
  * @param doc - The SysProM document to convert.
  * @returns The Markdown representation.
+ * @example
+ * ```ts
+ * const md = jsonToMarkdownSingle(doc);
+ * writeFileSync("output.spm.md", md);
+ * ```
  */
 export declare function jsonToMarkdownSingle(doc: SysProMDocument): string;
 /**
  * Convert a SysProM document to a multi-document Markdown folder.
  * @param doc - The SysProM document to convert.
  * @param outDir - Output directory path.
+ * @example
+ * ```ts
+ * jsonToMarkdownMultiDoc(doc, "./SysProM");
+ * ```
  */
 export declare function jsonToMarkdownMultiDoc(doc: SysProMDocument, outDir: string): void;
 /**
@@ -20,5 +29,9 @@ export declare function jsonToMarkdownMultiDoc(doc: SysProMDocument, outDir: str
  * @param doc - The SysProM document to convert.
  * @param output - Output file or directory path.
  * @param options - Conversion options specifying single-file or multi-doc form.
+ * @example
+ * ```ts
+ * jsonToMarkdown(doc, "output.spm.md", { form: "single-file" });
+ * ```
  */
 export declare function jsonToMarkdown(doc: SysProMDocument, output: string, options: ConvertOptions): void;

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

@@ -362,6 +362,11 @@ function generateDocFile(doc, fileName, types, fromIdx) {
  * Convert a SysProM document to a single Markdown string.
  * @param doc - The SysProM document to convert.
  * @returns The Markdown representation.
+ * @example
+ * ```ts
+ * const md = jsonToMarkdownSingle(doc);
+ * writeFileSync("output.spm.md", md);
+ * ```
  */
 export function jsonToMarkdownSingle(doc) {
     const fromIdx = indexRelationshipsFrom(doc.relationships ?? []);
@@ -418,6 +423,10 @@ export function jsonToMarkdownSingle(doc) {
  * Convert a SysProM document to a multi-document Markdown folder.
  * @param doc - The SysProM document to convert.
  * @param outDir - Output directory path.
+ * @example
+ * ```ts
+ * jsonToMarkdownMultiDoc(doc, "./SysProM");
+ * ```
  */
 export function jsonToMarkdownMultiDoc(doc, outDir) {
     mkdirSync(outDir, { recursive: true });
@@ -484,6 +493,10 @@ export function jsonToMarkdownMultiDoc(doc, outDir) {
  * @param doc - The SysProM document to convert.
  * @param output - Output file or directory path.
  * @param options - Conversion options specifying single-file or multi-doc form.
+ * @example
+ * ```ts
+ * jsonToMarkdown(doc, "output.spm.md", { form: "single-file" });
+ * ```
  */
 export function jsonToMarkdown(doc, output, options) {
     if (options.form === "single-file") {

package/dist/src/md-to-json.d.ts

@@ -3,17 +3,29 @@ import { type SysProMDocument } from "./schema.js";
  * Parse a single Markdown file into a SysProM document.
  * @param content - The Markdown content to parse.
  * @returns The parsed SysProM document.
+ * @example
+ * ```ts
+ * const doc = markdownSingleToJson(readFileSync("doc.spm.md", "utf8"));
+ * ```
  */
 export declare function markdownSingleToJson(content: string): SysProMDocument;
 /**
  * Parse a multi-document Markdown folder into a SysProM document.
  * @param dir - Path to the directory containing Markdown files.
  * @returns The parsed SysProM document.
+ * @example
+ * ```ts
+ * const doc = markdownMultiDocToJson("./SysProM");
+ * ```
  */
 export declare function markdownMultiDocToJson(dir: string): SysProMDocument;
 /**
  * Parse Markdown into a SysProM document, auto-detecting single-file or multi-doc format.
  * @param input - File path or directory path to parse.
  * @returns The parsed SysProM document.
+ * @example
+ * ```ts
+ * const doc = markdownToJson("./SysProM");
+ * ```
  */
 export declare function markdownToJson(input: string): SysProMDocument;

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

@@ -430,6 +430,10 @@ function parseRelationshipTable(body) {
  * Parse a single Markdown file into a SysProM document.
  * @param content - The Markdown content to parse.
  * @returns The parsed SysProM document.
+ * @example
+ * ```ts
+ * const doc = markdownSingleToJson(readFileSync("doc.spm.md", "utf8"));
+ * ```
  */
 export function markdownSingleToJson(content) {
     const { front, body } = parseFrontMatter(content);
@@ -461,6 +465,10 @@ export function markdownSingleToJson(content) {
  * Parse a multi-document Markdown folder into a SysProM document.
  * @param dir - Path to the directory containing Markdown files.
  * @returns The parsed SysProM document.
+ * @example
+ * ```ts
+ * const doc = markdownMultiDocToJson("./SysProM");
+ * ```
  */
 export function markdownMultiDocToJson(dir) {
     const readmeContent = readFileSync(join(dir, "README.md"), "utf8");
@@ -536,6 +544,10 @@ export function markdownMultiDocToJson(dir) {
  * Parse Markdown into a SysProM document, auto-detecting single-file or multi-doc format.
  * @param input - File path or directory path to parse.
  * @returns The parsed SysProM document.
+ * @example
+ * ```ts
+ * const doc = markdownToJson("./SysProM");
+ * ```
  */
 export function markdownToJson(input) {
     if (statSync(input).isDirectory()) {

package/dist/src/operations/define-operation.d.ts

@@ -38,5 +38,16 @@ export type DefinedOperation<TInput extends z.ZodType = z.ZodType, TOutput exten
  * @param def - The operation definition with name, schemas, and implementation.
  * @returns A callable function with `.def`, `.inputSchema`, and `.outputSchema` attached.
  * @throws {Error} If the input fails Zod validation.
+ * @example
+ * ```ts
+ * const myOp = defineOperation({
+ *   name: "greet",
+ *   description: "Say hello",
+ *   input: z.object({ name: z.string() }),
+ *   output: z.string(),
+ *   fn: ({ name }) => `Hello, ${name}!`,
+ * });
+ * myOp({ name: "world" }); // => "Hello, world!"
+ * ```
  */
 export declare function defineOperation<TInput extends z.ZodType, TOutput extends z.ZodType>(def: OperationDef<TInput, TOutput>): DefinedOperation<TInput, TOutput>;

package/dist/src/operations/define-operation.js

@@ -7,6 +7,17 @@
  * @param def - The operation definition with name, schemas, and implementation.
  * @returns A callable function with `.def`, `.inputSchema`, and `.outputSchema` attached.
  * @throws {Error} If the input fails Zod validation.
+ * @example
+ * ```ts
+ * const myOp = defineOperation({
+ *   name: "greet",
+ *   description: "Say hello",
+ *   input: z.object({ name: z.string() }),
+ *   output: z.string(),
+ *   fn: ({ name }) => `Hello, ${name}!`,
+ * });
+ * myOp({ name: "world" }); // => "Hello, world!"
+ * ```
  */
 export function defineOperation(def) {
     function execute(input) {

package/dist/src/schema.d.ts

@@ -933,6 +933,11 @@ export declare const NODE_ID_PREFIX: Record<string, string>;
 /**
  * Generate the JSON Schema representation of the SysProM document schema.
  * @returns The JSON Schema object with Draft 2020-12 metadata.
+ * @example
+ * ```ts
+ * const schema = toJSONSchema();
+ * writeFileSync("schema.json", JSON.stringify(schema, null, 2));
+ * ```
  */
 export declare function toJSONSchema(): Record<string, unknown>;
 export {};

package/dist/src/schema.js

@@ -374,6 +374,11 @@ function isRecord(value) {
 /**
  * Generate the JSON Schema representation of the SysProM document schema.
  * @returns The JSON Schema object with Draft 2020-12 metadata.
+ * @example
+ * ```ts
+ * const schema = toJSONSchema();
+ * writeFileSync("schema.json", JSON.stringify(schema, null, 2));
+ * ```
  */
 export function toJSONSchema() {
     const generated = z.toJSONSchema(SysProMDocument, {

package/dist/src/speckit/generate.d.ts

@@ -4,6 +4,10 @@ import type { SysProMDocument } from "../schema.js";
  * @param doc - The SysProM document.
  * @param prefix - ID prefix identifying nodes to include.
  * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateConstitution(doc, "FEAT");
+ * ```
  */
 export declare function generateConstitution(doc: SysProMDocument, prefix: string): string;
 /**
@@ -11,6 +15,10 @@ export declare function generateConstitution(doc: SysProMDocument, prefix: strin
  * @param doc - The SysProM document.
  * @param prefix - ID prefix identifying nodes to include.
  * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateSpec(doc, "FEAT");
+ * ```
  */
 export declare function generateSpec(doc: SysProMDocument, prefix: string): string;
 /**
@@ -18,6 +26,10 @@ export declare function generateSpec(doc: SysProMDocument, prefix: string): stri
  * @param doc - The SysProM document.
  * @param prefix - ID prefix identifying nodes to include.
  * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generatePlan(doc, "FEAT");
+ * ```
  */
 export declare function generatePlan(doc: SysProMDocument, prefix: string): string;
 /**
@@ -25,6 +37,10 @@ export declare function generatePlan(doc: SysProMDocument, prefix: string): stri
  * @param doc - The SysProM document.
  * @param prefix - ID prefix identifying nodes to include.
  * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateTasks(doc, "FEAT");
+ * ```
  */
 export declare function generateTasks(doc: SysProMDocument, prefix: string): string;
 /**
@@ -32,6 +48,10 @@ export declare function generateTasks(doc: SysProMDocument, prefix: string): str
  * @param doc - The SysProM document.
  * @param prefix - ID prefix identifying nodes to include.
  * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateChecklist(doc, "FEAT");
+ * ```
  */
 export declare function generateChecklist(doc: SysProMDocument, prefix: string): string;
 /**
@@ -39,5 +59,9 @@ export declare function generateChecklist(doc: SysProMDocument, prefix: string):
  * @param doc - The SysProM document.
  * @param outputDir - Output directory path.
  * @param prefix - ID prefix identifying nodes to include.
+ * @example
+ * ```ts
+ * generateSpecKitProject(doc, "./output", "FEAT");
+ * ```
  */
 export declare function generateSpecKitProject(doc: SysProMDocument, outputDir: string, prefix: string): void;

package/dist/src/speckit/generate.js

@@ -9,6 +9,10 @@ import { textToString } from "../text.js";
  * @param doc - The document to search.
  * @param id - The node ID to find.
  * @returns The matching node, or null.
+ * @example
+ * ```ts
+ * findNode(doc, "D1")
+ * ```
  */
 function findNode(doc, id) {
     return doc.nodes.find((n) => n.id === id) ?? null;
@@ -18,6 +22,10 @@ function findNode(doc, id) {
  * @param doc - The document to search.
  * @param type - The node type to filter by.
  * @returns Matching nodes.
+ * @example
+ * ```ts
+ * const decisions = findNodesByType(doc, "decision");
+ * ```
  */
 function findNodesByType(doc, type) {
     return doc.nodes.filter((n) => n.type === type);
@@ -28,6 +36,10 @@ function findNodesByType(doc, type) {
  * @param fromId - Source node ID.
  * @param relationType - Optional relationship type filter.
  * @returns Matching relationships.
+ * @example
+ * ```ts
+ * const rels = findRelationshipsFrom(doc, "D1", "affects");
+ * ```
  */
 function findRelationshipsFrom(doc, fromId, relationType) {
     return (doc.relationships ?? []).filter((r) => {
@@ -44,6 +56,10 @@ function findRelationshipsFrom(doc, fromId, relationType) {
  * @param toId - Target node ID.
  * @param relationType - Optional relationship type filter.
  * @returns Matching relationships.
+ * @example
+ * ```ts
+ * const rels = findRelationshipsTo(doc, "INV1", "must_preserve");
+ * ```
  */
 function findRelationshipsTo(doc, toId, relationType) {
     return (doc.relationships ?? []).filter((r) => {
@@ -59,6 +75,10 @@ function findRelationshipsTo(doc, toId, relationType) {
  * Looks for patterns like "P1", "P2", "Priority: P1", etc.
  * @param node - The node to extract priority from.
  * @returns Priority string (e.g. "P1").
+ * @example
+ * ```ts
+ * const priority = extractPriority(node);
+ * ```
  */
 function extractPriority(node) {
     const text = [
@@ -75,6 +95,10 @@ function extractPriority(node) {
  * Extract numeric suffix from an ID (e.g., "PREFIX-SPEC-001" -> "001").
  * @param id - The node ID.
  * @returns The numeric suffix.
+ * @example
+ * ```ts
+ * getIdSuffix("FEAT-SPEC-001"); // => "001"
+ * ```
  */
 function getIdSuffix(id) {
     const parts = id.split("-");
@@ -84,6 +108,10 @@ function getIdSuffix(id) {
  * Parse tasks from a change node's plan array.
  * @param node - The change node.
  * @returns Array of task descriptions and done flags.
+ * @example
+ * ```ts
+ * const tasks = parseTasks(changeNode);
+ * ```
  */
 function parseTasks(node) {
     return (node.plan ?? []).map((task) => ({
@@ -95,6 +123,10 @@ function parseTasks(node) {
  * Format the status for spec output: "proposed" -> "Draft", etc.
  * @param status - The node status string.
  * @returns Formatted status label.
+ * @example
+ * ```ts
+ * formatStatus("proposed"); // => "Draft"
+ * ```
  */
 function formatStatus(status) {
     if (!status)
@@ -114,6 +146,10 @@ function formatStatus(status) {
  * @param doc - The SysProM document.
  * @param prefix - ID prefix identifying nodes to include.
  * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateConstitution(doc, "FEAT");
+ * ```
  */
 export function generateConstitution(doc, prefix) {
     const protocolId = `${prefix}-CONST`;
@@ -192,6 +228,10 @@ export function generateConstitution(doc, prefix) {
  * @param doc - The SysProM document.
  * @param prefix - ID prefix identifying nodes to include.
  * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateSpec(doc, "FEAT");
+ * ```
  */
 export function generateSpec(doc, prefix) {
     const specId = `${prefix}-SPEC`;
@@ -311,6 +351,10 @@ export function generateSpec(doc, prefix) {
  * @param doc - The SysProM document.
  * @param prefix - ID prefix identifying nodes to include.
  * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generatePlan(doc, "FEAT");
+ * ```
  */
 export function generatePlan(doc, prefix) {
     const implProtocolId = `${prefix}-PROT-IMPL`;
@@ -367,6 +411,10 @@ export function generatePlan(doc, prefix) {
  * @param doc - The SysProM document.
  * @param prefix - ID prefix identifying nodes to include.
  * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateTasks(doc, "FEAT");
+ * ```
  */
 export function generateTasks(doc, prefix) {
     const implProtocolId = `${prefix}-PROT-IMPL`;
@@ -512,6 +560,10 @@ export function generateTasks(doc, prefix) {
  * @param doc - The SysProM document.
  * @param prefix - ID prefix identifying nodes to include.
  * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateChecklist(doc, "FEAT");
+ * ```
  */
 export function generateChecklist(doc, prefix) {
     const gateId = `${prefix}-CHK`;
@@ -572,6 +624,10 @@ export function generateChecklist(doc, prefix) {
  * @param doc - The SysProM document.
  * @param outputDir - Output directory path.
  * @param prefix - ID prefix identifying nodes to include.
+ * @example
+ * ```ts
+ * generateSpecKitProject(doc, "./output", "FEAT");
+ * ```
  */
 export function generateSpecKitProject(doc, outputDir, prefix) {
     // Create output directory if it doesn't exist