sysprom 1.2.0 → 1.2.2

package/README.md

@@ -135,10 +135,18 @@ SysProM models systems as directed graphs across abstraction layers — intent,
 | [C4](https://c4model.com/) | ✅ | | ✅ | | | | 🔶 | ✅ | | | | | | |
 | [Traceability Matrices](https://en.wikipedia.org/wiki/Traceability_matrix) | ✅ | | ✅ | | | 🔶 | | | | 🔶 | | | | 🔶 |
 | [Spec Kit](https://github.com/github/spec-kit) | ✅ | | ✅ | 🔶 | 🔶 | | 🔶 | | | | | ✅ | ✅ | ✅ |
+| [PRD](https://en.wikipedia.org/wiki/Product_requirements_document) | ✅ | | 🔶 | ✅ | 🔶 | 🔶 | 🔶 | 🔶 | | 🔶 | | | ✅ | 🔶 |
 | [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) | ✅ | | | 🔶 | | 🔶 | | | | | | | | |
+| [GSD-2](https://github.com/gsd-build/gsd-2) | ✅ | 🔶 | ✅ | 🔶 | ✅ | 🔶 | ✅ | | | 🔶 | | ✅ | ✅ | ✅ |
+| [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** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🔶 | | 🔶 | ✅ | ✅ | ✅ | ✅ |
 

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

@@ -17,9 +17,13 @@ export interface FormatOptions {
 }
 /**
  * Serialise a value to canonical JSON with RFC 8785 key ordering.
- *
  * @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

@@ -12,10 +12,14 @@
  */
 /**
  * Serialise a value to canonical JSON with RFC 8785 key ordering.
- *
  * @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

@@ -1,5 +1,6 @@
 import * as z from "zod";
 import { Command } from "commander";
+/** Definition of a CLI command — name, description, Zod schemas for args/opts, optional subcommands, and action handler. */
 export interface CommandDef<TArgs extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOpts extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
     name: string;
     description: string;
@@ -9,13 +10,27 @@ export interface CommandDef<TArgs extends z.ZodObject<z.ZodRawShape> = z.ZodObje
     action?: (args: z.infer<TArgs>, opts: z.infer<TOpts>) => void;
     apiLink?: string;
 }
+/**
+ * Build a Commander.js command tree from a declarative CommandDef, wiring up Zod-validated args, options, and actions.
+ * @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. */
 export interface ArgDoc {
     name: string;
     description: string;
     required: boolean;
     choices?: string[];
 }
+/** Extracted documentation for a CLI option/flag. */
 export interface OptDoc {
     flag: string;
     description: string;
@@ -23,6 +38,7 @@ export interface OptDoc {
     repeatable: boolean;
     choices?: string[];
 }
+/** Extracted documentation for a CLI command, including its arguments, options, and subcommands. */
 export interface CommandDoc {
     name: string;
     description: string;
@@ -31,4 +47,14 @@ export interface CommandDoc {
     subcommands?: CommandDoc[];
     apiLink?: string;
 }
+/**
+ * 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

@@ -77,6 +77,18 @@ function getShape(schema) {
 function collect(value, previous) {
     return [...previous, value];
 }
+/**
+ * Build a Commander.js command tree from a declarative CommandDef, wiring up Zod-validated args, options, and actions.
+ * @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);
     cmd.description(def.description);
@@ -190,6 +202,16 @@ export function buildCommander(def, parent) {
     }
     return cmd;
 }
+/**
+ * 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

@@ -14,6 +14,14 @@ export declare const noArgs: z.ZodObject<{}, z.core.$strict>;
  *  10. *.sysprom.json 11. *.sysprom.md 12. *.sysprom/
  *
  * All matching is case-insensitive. 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"
+ * ```
  */
 export declare function resolveInput(input?: string, cwd?: string): string;
 /** Common output/persistence options for read-only commands. */
@@ -28,14 +36,36 @@ export declare const mutationOpts: z.ZodObject<{
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     sync: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** Inferred type for read-only CLI options (input path, JSON output flag). */
 export type ReadOpts = z.infer<typeof readOpts>;
+/** Inferred type for mutation CLI options (extends ReadOpts with sync-to-markdown). */
 export type MutationOpts = z.infer<typeof mutationOpts>;
+/** A document loaded from a CLI input path with its format and resolved path. */
 export interface LoadedDoc {
     doc: SysProMDocument;
     format: Format;
     path: string;
 }
-/** Load a document from a CLI input path (auto-resolved if omitted). */
+/**
+ * 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;
-/** Persist a document and optionally sync to markdown. */
+/**
+ * Persist a document and optionally sync to markdown.
+ * @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

@@ -29,6 +29,14 @@ const pathOpt = z
  *  10. *.sysprom.json 11. *.sysprom.md 12. *.sysprom/
  *
  * All matching is case-insensitive. 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"
+ * ```
  */
 export function resolveInput(input, cwd) {
     if (input)
@@ -122,11 +130,30 @@ export const mutationOpts = z.object({
         .optional()
         .describe("sync to markdown directory after saving"),
 });
-/** Load a document from a CLI input path (auto-resolved if omitted). */
+/**
+ * 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));
 }
-/** Persist a document and optionally sync to markdown. */
+/**
+ * Persist a document and optionally sync to markdown.
+ * @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) {
         saveDocument(doc, loaded.format, loaded.path);

package/dist/src/index.d.ts

@@ -3,7 +3,6 @@
  *
  * A recursive, decision-driven model for recording where every part of a
  * system came from, what decisions shaped it, and how it reached its current form.
- *
  * @packageDocumentation
  */
 export { SysProMDocument, Node, Relationship, NodeType, NodeStatus, RelationshipType, Text, Option, Operation, Task, ExternalReference, ExternalReferenceRole, Metadata, NODE_TYPE_LABELS, NODE_LABEL_TO_TYPE, RELATIONSHIP_TYPE_LABELS, RELATIONSHIP_LABEL_TO_TYPE, EXTERNAL_REFERENCE_ROLE_LABELS, EXTERNAL_REFERENCE_LABEL_TO_ROLE, NODE_STATUSES, NODE_FILE_MAP, NODE_ID_PREFIX, toJSONSchema, } from "./schema.js";

package/dist/src/index.js

@@ -3,7 +3,6 @@
  *
  * A recursive, decision-driven model for recording where every part of a
  * system came from, what decisions shaped it, and how it reached its current form.
- *
  * @packageDocumentation
  */
 // Schema types and validators

package/dist/src/io.d.ts

@@ -12,16 +12,23 @@ 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;
 /**
  * Save a SysProM document to a file (JSON or Markdown).
- *
  * @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

@@ -14,9 +14,12 @@ 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);
@@ -46,10 +49,14 @@ export function loadDocument(input) {
 }
 /**
  * Save a SysProM document to a file (JSON or Markdown).
- *
  * @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

@@ -5,23 +5,33 @@ 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;
 /**
  * Convert a SysProM document to Markdown, writing to the specified output path.
- *
  * @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

@@ -360,9 +360,13 @@ 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 ?? []);
@@ -417,9 +421,12 @@ 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 });
@@ -483,10 +490,13 @@ export function jsonToMarkdownMultiDoc(doc, outDir) {
 }
 /**
  * Convert a SysProM document to Markdown, writing to the specified output path.
- *
  * @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

@@ -1,22 +1,31 @@
 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

@@ -428,9 +428,12 @@ 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);
@@ -460,9 +463,12 @@ 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,9 +542,12 @@ 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/add-node.d.ts

@@ -1,8 +1,7 @@
 import * as z from "zod";
 /**
  * Add a node to a SysProM document. Returns a new document with the node appended.
- *
- * @throws If a node with the same ID already exists.
+ * @throws {Error} If a node with the same ID already exists.
  */
 export declare const addNodeOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/add-node.js

@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
 import { SysProMDocument, Node } from "../schema.js";
 /**
  * Add a node to a SysProM document. Returns a new document with the node appended.
- *
- * @throws If a node with the same ID already exists.
+ * @throws {Error} If a node with the same ID already exists.
  */
 export const addNodeOp = defineOperation({
     name: "addNode",

package/dist/src/operations/add-plan-task.d.ts

@@ -1,8 +1,7 @@
 import * as z from "zod";
 /**
  * Append a new task to a change node's plan array. Returns a new document with the task added.
- *
- * @throws If the change node is not found.
+ * @throws {Error} If the change node is not found.
  */
 export declare const addPlanTaskOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/add-plan-task.js

@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
 /**
  * Append a new task to a change node's plan array. Returns a new document with the task added.
- *
- * @throws If the change node is not found.
+ * @throws {Error} If the change node is not found.
  */
 export const addPlanTaskOp = defineOperation({
     name: "addPlanTask",

package/dist/src/operations/add-relationship.d.ts

@@ -1,8 +1,7 @@
 import * as z from "zod";
 /**
  * Add a relationship to a SysProM document. Returns a new document with the relationship appended.
- *
- * @throws If either endpoint node does not exist in the document.
+ * @throws {Error} If either endpoint node does not exist in the document.
  */
 export declare const addRelationshipOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/add-relationship.js

@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
 import { SysProMDocument, Relationship } from "../schema.js";
 /**
  * Add a relationship to a SysProM document. Returns a new document with the relationship appended.
- *
- * @throws If either endpoint node does not exist in the document.
+ * @throws {Error} If either endpoint node does not exist in the document.
  */
 export const addRelationshipOp = defineOperation({
     name: "addRelationship",

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

@@ -2,9 +2,8 @@ import * as z from "zod";
 /**
  * Definition of a SysProM operation — a named, typed function with Zod schemas
  * for input validation and output description.
- *
- * @typeParam TInput - Zod schema type for the operation's input.
- * @typeParam TOutput - Zod schema type for the operation's output.
+ * @template TInput - Zod schema type for the operation's input.
+ * @template TOutput - Zod schema type for the operation's output.
  */
 export interface OperationDef<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType> {
     /** Machine-readable operation name (e.g. `"addNode"`). */
@@ -22,9 +21,8 @@ export interface OperationDef<TInput extends z.ZodType = z.ZodType, TOutput exte
  * A callable operation with attached metadata. Can be invoked directly as a
  * function, and also exposes `.def`, `.inputSchema`, and `.outputSchema` for
  * introspection.
- *
- * @typeParam TInput - Zod schema type for the operation's input.
- * @typeParam TOutput - Zod schema type for the operation's output.
+ * @template TInput - Zod schema type for the operation's input.
+ * @template TOutput - Zod schema type for the operation's output.
  */
 export type DefinedOperation<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType> = ((input: z.infer<TInput>) => z.infer<TOutput>) & {
     /** The full operation definition including name, description, and schemas. */
@@ -37,9 +35,19 @@ export type DefinedOperation<TInput extends z.ZodType = z.ZodType, TOutput exten
 /**
  * Create a callable operation from a definition. The returned function validates
  * input against the Zod schema before delegating to the implementation.
- *
  * @param def - The operation definition with name, schemas, and implementation.
  * @returns A callable function with `.def`, `.inputSchema`, and `.outputSchema` attached.
- * @throws If the input fails Zod validation.
+ * @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

@@ -4,10 +4,20 @@
 /**
  * Create a callable operation from a definition. The returned function validates
  * input against the Zod schema before delegating to the implementation.
- *
  * @param def - The operation definition with name, schemas, and implementation.
  * @returns A callable function with `.def`, `.inputSchema`, and `.outputSchema` attached.
- * @throws If the input fails Zod validation.
+ * @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/operations/mark-task-done.d.ts

@@ -1,8 +1,7 @@
 import * as z from "zod";
 /**
  * Mark a task as done within a change node's plan.
- *
- * @throws If the change node is not found or the task index is out of range.
+ * @throws {Error} If the change node is not found or the task index is out of range.
  */
 export declare const markTaskDoneOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/mark-task-done.js

@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
 /**
  * Mark a task as done within a change node's plan.
- *
- * @throws If the change node is not found or the task index is out of range.
+ * @throws {Error} If the change node is not found or the task index is out of range.
  */
 export const markTaskDoneOp = defineOperation({
     name: "markTaskDone",

package/dist/src/operations/mark-task-undone.d.ts

@@ -1,8 +1,7 @@
 import * as z from "zod";
 /**
  * Mark a task as undone (incomplete) within a change node's plan.
- *
- * @throws If the change node is not found or the task index is out of range.
+ * @throws {Error} If the change node is not found or the task index is out of range.
  */
 export declare const markTaskUndoneOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/mark-task-undone.js

@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
 /**
  * Mark a task as undone (incomplete) within a change node's plan.
- *
- * @throws If the change node is not found or the task index is out of range.
+ * @throws {Error} If the change node is not found or the task index is out of range.
  */
 export const markTaskUndoneOp = defineOperation({
     name: "markTaskUndone",