sysprom 1.2.1 → 1.2.2

package/README.md

@@ -135,11 +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

@@ -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

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

@@ -11,6 +11,10 @@ export interface ParseResult {
  * @param content - Markdown file content.
  * @param idPrefix - ID prefix for generated nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseConstitution(content, "FEAT");
+ * ```
  */
 export declare function parseConstitution(content: string, idPrefix: string): ParseResult;
 /**
@@ -18,6 +22,10 @@ export declare function parseConstitution(content: string, idPrefix: string): Pa
  * @param content - Markdown file content.
  * @param idPrefix - ID prefix for generated nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseSpec(content, "FEAT");
+ * ```
  */
 export declare function parseSpec(content: string, idPrefix: string): ParseResult;
 /**
@@ -25,6 +33,10 @@ export declare function parseSpec(content: string, idPrefix: string): ParseResul
  * @param content - Markdown file content.
  * @param idPrefix - ID prefix for generated nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const result = parsePlan(content, "FEAT");
+ * ```
  */
 export declare function parsePlan(content: string, idPrefix: string): ParseResult;
 /**
@@ -32,6 +44,10 @@ export declare function parsePlan(content: string, idPrefix: string): ParseResul
  * @param content - Markdown file content.
  * @param idPrefix - ID prefix for generated nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseTasks(content, "FEAT");
+ * ```
  */
 export declare function parseTasks(content: string, idPrefix: string): ParseResult;
 /**
@@ -39,6 +55,10 @@ export declare function parseTasks(content: string, idPrefix: string): ParseResu
  * @param content - Markdown file content.
  * @param idPrefix - ID prefix for generated nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseChecklist(content, "FEAT");
+ * ```
  */
 export declare function parseChecklist(content: string, idPrefix: string): ParseResult;
 /**
@@ -47,5 +67,9 @@ export declare function parseChecklist(content: string, idPrefix: string): Parse
  * @param idPrefix - ID prefix for generated nodes.
  * @param constitutionPath - Path to constitution.md, or undefined.
  * @returns The parsed SysProM document.
+ * @example
+ * ```ts
+ * const doc = parseSpecKitFeature("./features/auth", "AUTH");
+ * ```
  */
 export declare function parseSpecKitFeature(featureDir: string, idPrefix: string, constitutionPath?: string): SysProMDocument;

package/dist/src/speckit/parse.js

@@ -7,6 +7,10 @@ import { join, basename } from "node:path";
  * Parse markdown content into a hierarchical section tree by heading level.
  * @param body - Markdown body text.
  * @returns The result.
+ * @example
+ * ```ts
+ * const sections = parseSections(markdownBody);
+ * ```
  */
 function parseSections(body) {
     const lines = body.split("\n");
@@ -53,6 +57,10 @@ function parseSections(body) {
  * Extract bold key-value pairs from markdown like "**Key**: value" or "**Key**: value text".
  * @param content - Markdown file content.
  * @returns The result.
+ * @example
+ * ```ts
+ * const meta = parseFrontMatterish(content);
+ * ```
  */
 function parseFrontMatterish(content) {
     const result = {};
@@ -70,6 +78,10 @@ function parseFrontMatterish(content) {
  * Parse checkbox lines like "- [x] ID text" or "- [ ] ID text".
  * @param body - Markdown body text.
  * @returns The result.
+ * @example
+ * ```ts
+ * const items = parseCheckboxes(body);
+ * ```
  */
 function parseCheckboxes(body) {
     const items = [];
@@ -92,6 +104,10 @@ function parseCheckboxes(body) {
  * Flatten all sections in the tree into a single array for easier searching.
  * @param sections - Parsed section tree.
  * @returns The result.
+ * @example
+ * ```ts
+ * const flat = flattenSections(sections);
+ * ```
  */
 function flattenSections(sections) {
     const result = [];
@@ -109,6 +125,10 @@ function flattenSections(sections) {
  * @param sections - Parsed section tree.
  * @param predicate - Filter function.
  * @returns The result.
+ * @example
+ * ```ts
+ * const s = findSection(sections, (h) => h.startsWith("Phase"));
+ * ```
  */
 function findSection(sections, predicate) {
     return flattenSections(sections).find((s) => predicate(s.heading));
@@ -117,6 +137,10 @@ function findSection(sections, predicate) {
  * Convert status-like strings to NodeStatus. Recognizes common spec-kit patterns.
  * @param value - Raw status string.
  * @returns The result.
+ * @example
+ * ```ts
+ * mapStatusValue("Draft"); // => "proposed"
+ * ```
  */
 function mapStatusValue(value) {
     const lower = value.toLowerCase().trim();
@@ -146,6 +170,10 @@ function mapStatusValue(value) {
  * @param body - Markdown body text.
  * @param key - Front-matter key to extract.
  * @returns The result.
+ * @example
+ * ```ts
+ * extractValue(body, "Created"); // => "2025-01-01"
+ * ```
  */
 function extractValue(body, key) {
     const pattern = new RegExp(`^\\*\\*${key}\\*\\*:\\s*(.+)$`, "m");
@@ -160,6 +188,10 @@ function extractValue(body, key) {
  * @param content - Markdown file content.
  * @param idPrefix - ID prefix for generated nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseConstitution(content, "FEAT");
+ * ```
  */
 export function parseConstitution(content, idPrefix) {
     const sections = parseSections(content);
@@ -254,6 +286,10 @@ export function parseConstitution(content, idPrefix) {
  * @param content - Markdown file content.
  * @param idPrefix - ID prefix for generated nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseSpec(content, "FEAT");
+ * ```
  */
 export function parseSpec(content, idPrefix) {
     const sections = parseSections(content);
@@ -443,6 +479,10 @@ export function parseSpec(content, idPrefix) {
  * @param content - Markdown file content.
  * @param idPrefix - ID prefix for generated nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const result = parsePlan(content, "FEAT");
+ * ```
  */
 export function parsePlan(content, idPrefix) {
     const sections = parseSections(content);
@@ -541,6 +581,10 @@ export function parsePlan(content, idPrefix) {
  * @param content - Markdown file content.
  * @param idPrefix - ID prefix for generated nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseTasks(content, "FEAT");
+ * ```
  */
 export function parseTasks(content, idPrefix) {
     const sections = parseSections(content);
@@ -652,6 +696,10 @@ export function parseTasks(content, idPrefix) {
  * @param content - Markdown file content.
  * @param idPrefix - ID prefix for generated nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseChecklist(content, "FEAT");
+ * ```
  */
 export function parseChecklist(content, idPrefix) {
     const sections = parseSections(content);
@@ -707,6 +755,10 @@ export function parseChecklist(content, idPrefix) {
  * @param idPrefix - ID prefix for generated nodes.
  * @param constitutionPath - Path to constitution.md, or undefined.
  * @returns The parsed SysProM document.
+ * @example
+ * ```ts
+ * const doc = parseSpecKitFeature("./features/auth", "AUTH");
+ * ```
  */
 export function parseSpecKitFeature(featureDir, idPrefix, constitutionPath) {
     const nodes = [];

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

@@ -77,6 +77,10 @@ export interface TaskCount {
  * @param prefix - Plan prefix.
  * @param name - Name for the new item.
  * @returns The result.
+ * @example
+ * ```ts
+ * const doc = initDocument("PLAN", "My Plan");
+ * ```
  */
 export declare function initDocument(prefix: string, name: string): SysProMDocument;
 /**
@@ -96,6 +100,10 @@ export declare function initDocument(prefix: string, name: string): SysProMDocum
  * @param name - Name for the new item.
  * @param parentId - Parent task ID.
  * @returns The result.
+ * @example
+ * ```ts
+ * const updated = addTask(doc, "PLAN", "Implement auth");
+ * ```
  */
 export declare function addTask(doc: SysProMDocument, prefix: string, name?: string, parentId?: string): SysProMDocument;
 /**
@@ -107,6 +115,10 @@ export declare function addTask(doc: SysProMDocument, prefix: string, name?: str
  *   - All children must be recursively done AND own plan items (if any) must be done
  * @param node - The node to check.
  * @returns The result.
+ * @example
+ * ```ts
+ * isTaskDone(changeNode); // => true if all plan items done
+ * ```
  */
 export declare function isTaskDone(node: Node): boolean;
 /**
@@ -116,6 +128,10 @@ export declare function isTaskDone(node: Node): boolean;
  * subsystem (and their subsystems).
  * @param node - The node to check.
  * @returns The result.
+ * @example
+ * ```ts
+ * const { total, done } = countTasks(changeNode);
+ * ```
  */
 export declare function countTasks(node: Node): TaskCount;
 /**
@@ -124,6 +140,10 @@ export declare function countTasks(node: Node): TaskCount;
  * @param doc - The SysProM document.
  * @param prefix - Plan prefix.
  * @returns The result.
+ * @example
+ * ```ts
+ * const status = planStatus(doc, "PLAN");
+ * ```
  */
 export declare function planStatus(doc: SysProMDocument, prefix: string): PlanStatus;
 /**
@@ -132,6 +152,10 @@ export declare function planStatus(doc: SysProMDocument, prefix: string): PlanSt
  * @param doc - The SysProM document.
  * @param prefix - Plan prefix.
  * @returns The result.
+ * @example
+ * ```ts
+ * const phases = planProgress(doc, "PLAN");
+ * ```
  */
 export declare function planProgress(doc: SysProMDocument, prefix: string): PhaseProgress[];
 /**
@@ -148,5 +172,9 @@ export declare function planProgress(doc: SysProMDocument, prefix: string): Phas
  * @param prefix - Plan prefix.
  * @param phase - Phase number (1-indexed).
  * @returns Gate check result with readiness flag and issues.
+ * @example
+ * ```ts
+ * const result = checkGate(doc, "PLAN", 2);
+ * ```
  */
 export declare function checkGate(doc: SysProMDocument, prefix: string, phase: number): GateResult;

package/dist/src/speckit/plan.js

@@ -7,6 +7,10 @@ import { textToString } from "../text.js";
  * @param doc - The SysProM document.
  * @param id - Node ID to find.
  * @returns The result.
+ * @example
+ * ```ts
+ * const node = findNode(doc, "PLAN-SPEC");
+ * ```
  */
 function findNode(doc, id) {
     return doc.nodes.find((n) => n.id === id) ?? null;
@@ -16,6 +20,10 @@ function findNode(doc, id) {
  * @param subsystem - The subsystem document.
  * @param id - Node ID to find.
  * @returns The result.
+ * @example
+ * ```ts
+ * const node = findNodeInSubsystem(subsystem, "CH1");
+ * ```
  */
 function findNodeInSubsystem(subsystem, id) {
     if (!subsystem)
@@ -27,6 +35,10 @@ function findNodeInSubsystem(subsystem, id) {
  * @param doc - The SysProM document.
  * @param type - Node type to filter by.
  * @returns The result.
+ * @example
+ * ```ts
+ * const changes = findNodesByType(doc, "change");
+ * ```
  */
 function findNodesByType(doc, type) {
     return doc.nodes.filter((n) => n.type === type);
@@ -36,6 +48,10 @@ function findNodesByType(doc, type) {
  * @param subsystem - The subsystem document.
  * @param type - Node type to filter by.
  * @returns The result.
+ * @example
+ * ```ts
+ * const gates = findNodesByTypeInSubsystem(subsystem, "gate");
+ * ```
  */
 function findNodesByTypeInSubsystem(subsystem, type) {
     if (!subsystem)
@@ -48,6 +64,10 @@ function findNodesByTypeInSubsystem(subsystem, type) {
  * @param fromId - Source node ID.
  * @param relationType - Relationship type filter.
  * @returns The result.
+ * @example
+ * ```ts
+ * const rels = findRelationshipsFrom(subsystem, "CH1");
+ * ```
  */
 function findRelationshipsFrom(subsystem, fromId, relationType) {
     if (!subsystem)
@@ -66,6 +86,10 @@ function findRelationshipsFrom(subsystem, fromId, relationType) {
  * @param toId - Target node ID.
  * @param relationType - Relationship type filter.
  * @returns The result.
+ * @example
+ * ```ts
+ * const rels = findRelationshipsTo(subsystem, "CH2");
+ * ```
  */
 function findRelationshipsTo(subsystem, toId, relationType) {
     if (!subsystem)
@@ -83,6 +107,10 @@ function findRelationshipsTo(subsystem, toId, relationType) {
  * Looks for GIVEN/WHEN/THEN patterns (case-insensitive).
  * @param description - Task description text.
  * @returns The result.
+ * @example
+ * ```ts
+ * hasAcceptanceCriteria("Given X When Y Then Z"); // => true
+ * ```
  */
 function hasAcceptanceCriteria(description) {
     if (!description)
@@ -95,6 +123,10 @@ function hasAcceptanceCriteria(description) {
  * @param subsystem - The subsystem document.
  * @param changeNodes - Array of change nodes.
  * @returns The result.
+ * @example
+ * ```ts
+ * const sorted = sortChangesByOrder(subsystem, changeNodes);
+ * ```
  */
 function sortChangesByOrder(subsystem, changeNodes) {
     const subsystemToUse = subsystem ?? { nodes: [], relationships: [] };
@@ -150,6 +182,10 @@ function sortChangesByOrder(subsystem, changeNodes) {
  * @param prefix - Plan prefix.
  * @param name - Name for the new item.
  * @returns The result.
+ * @example
+ * ```ts
+ * const doc = initDocument("PLAN", "My Plan");
+ * ```
  */
 export function initDocument(prefix, name) {
     const nodes = [
@@ -222,6 +258,10 @@ export function initDocument(prefix, name) {
  * @param name - Name for the new item.
  * @param parentId - Parent task ID.
  * @returns The result.
+ * @example
+ * ```ts
+ * const updated = addTask(doc, "PLAN", "Implement auth");
+ * ```
  */
 export function addTask(doc, prefix, name, parentId) {
     const protImpl = findNode(doc, `${prefix}-PROT-IMPL`);
@@ -286,6 +326,10 @@ export function addTask(doc, prefix, name, parentId) {
  * @param parentId - Parent task ID.
  * @param name - Name for the new item.
  * @returns The result.
+ * @example
+ * ```ts
+ * const updated = addTaskToParent(doc, protImpl, "PLAN", "CH1");
+ * ```
  */
 function addTaskToParent(doc, protImpl, prefix, parentId, name) {
     // Find the parent change node in the subsystem tree
@@ -417,6 +461,10 @@ function addTaskToParent(doc, protImpl, prefix, parentId, name) {
  *   - All children must be recursively done AND own plan items (if any) must be done
  * @param node - The node to check.
  * @returns The result.
+ * @example
+ * ```ts
+ * isTaskDone(changeNode); // => true if all plan items done
+ * ```
  */
 export function isTaskDone(node) {
     // If the node has a subsystem with change children, check those recursively
@@ -447,6 +495,10 @@ export function isTaskDone(node) {
  * subsystem (and their subsystems).
  * @param node - The node to check.
  * @returns The result.
+ * @example
+ * ```ts
+ * const { total, done } = countTasks(changeNode);
+ * ```
  */
 export function countTasks(node) {
     let total = 0;
@@ -475,6 +527,10 @@ export function countTasks(node) {
  * @param doc - The SysProM document.
  * @param prefix - Plan prefix.
  * @returns The result.
+ * @example
+ * ```ts
+ * const status = planStatus(doc, "PLAN");
+ * ```
  */
 export function planStatus(doc, prefix) {
     const constitution = findNode(doc, `${prefix}-CONST`);
@@ -576,6 +632,10 @@ export function planStatus(doc, prefix) {
  * @param doc - The SysProM document.
  * @param prefix - Plan prefix.
  * @returns The result.
+ * @example
+ * ```ts
+ * const phases = planProgress(doc, "PLAN");
+ * ```
  */
 export function planProgress(doc, prefix) {
     const protImpl = findNode(doc, `${prefix}-PROT-IMPL`);
@@ -621,6 +681,10 @@ export function planProgress(doc, prefix) {
  * @param prefix - Plan prefix.
  * @param phase - Phase number (1-indexed).
  * @returns Gate check result with readiness flag and issues.
+ * @example
+ * ```ts
+ * const result = checkGate(doc, "PLAN", 2);
+ * ```
  */
 export function checkGate(doc, prefix, phase) {
     if (phase < 1) {

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

@@ -30,12 +30,24 @@ export interface SpecKitFeature {
  * Looks for .specify/ and specs/ subdirectories.
  * @param dir - Directory to scan.
  * @returns Detected project structure.
+ * @example
+ * ```ts
+ * const project = detectSpecKitProject("./my-project");
+ * ```
+ * @example
+ * ```ts
+ * const project = detectSpecKitProject("./my-project");
+ * ```
  */
 export declare function detectSpecKitProject(dir: string): SpecKitProject;
 /**
  * List all features in the specs/ directory, sorted by number.
  * @param project - The detected project.
  * @returns Sorted list of features.
+ * @example
+ * ```ts
+ * const features = listFeatures(project);
+ * ```
  */
 export declare function listFeatures(project: SpecKitProject): SpecKitFeature[];
 /**
@@ -44,11 +56,19 @@ export declare function listFeatures(project: SpecKitProject): SpecKitFeature[];
  * @param project - The detected project.
  * @param idOrName - Feature ID, number, or name.
  * @returns The matching feature, or null.
+ * @example
+ * ```ts
+ * const feature = getFeature(project, "001-auth");
+ * ```
  */
 export declare function getFeature(project: SpecKitProject, idOrName: string): SpecKitFeature | null;
 /**
  * Resolve the constitution.md file, checking .specify/memory/ first, then root.
  * @param project - The detected project.
  * @returns Path to constitution.md, or null.
+ * @example
+ * ```ts
+ * const path = resolveConstitution(project);
+ * ```
  */
 export declare function resolveConstitution(project: SpecKitProject): string | null;

package/dist/src/speckit/project.js

@@ -5,6 +5,14 @@ import { join } from "node:path";
  * Looks for .specify/ and specs/ subdirectories.
  * @param dir - Directory to scan.
  * @returns Detected project structure.
+ * @example
+ * ```ts
+ * const project = detectSpecKitProject("./my-project");
+ * ```
+ * @example
+ * ```ts
+ * const project = detectSpecKitProject("./my-project");
+ * ```
  */
 export function detectSpecKitProject(dir) {
     const specifyDir = checkDir(join(dir, ".specify"));
@@ -34,6 +42,10 @@ export function detectSpecKitProject(dir) {
  * List all features in the specs/ directory, sorted by number.
  * @param project - The detected project.
  * @returns Sorted list of features.
+ * @example
+ * ```ts
+ * const features = listFeatures(project);
+ * ```
  */
 export function listFeatures(project) {
     if (!project.specsDir) {
@@ -70,6 +82,10 @@ export function listFeatures(project) {
  * @param project - The detected project.
  * @param idOrName - Feature ID, number, or name.
  * @returns The matching feature, or null.
+ * @example
+ * ```ts
+ * const feature = getFeature(project, "001-auth");
+ * ```
  */
 export function getFeature(project, idOrName) {
     const features = listFeatures(project);
@@ -92,6 +108,10 @@ export function getFeature(project, idOrName) {
  * Resolve the constitution.md file, checking .specify/memory/ first, then root.
  * @param project - The detected project.
  * @returns Path to constitution.md, or null.
+ * @example
+ * ```ts
+ * const path = resolveConstitution(project);
+ * ```
  */
 export function resolveConstitution(project) {
     return project.constitutionPath;
@@ -100,6 +120,10 @@ export function resolveConstitution(project) {
  * Check if a directory exists, return path or null.
  * @param path - Path to check.
  * @returns The path if it exists as a directory, or null.
+ * @example
+ * ```ts
+ * const dir = checkDir("/path/to/dir");
+ * ```
  */
 function checkDir(path) {
     try {
@@ -115,6 +139,10 @@ function checkDir(path) {
  * @param dir - Directory to search.
  * @param dirName - Subdirectory name pattern.
  * @returns Array of matching directory paths.
+ * @example
+ * ```ts
+ * const feature = parseFeatureDirectory("./specs", "001-auth");
+ * ```
  */
 function parseFeatureDirectory(dir, dirName) {
     // Parse the directory name format: "NNN-feature-name"
@@ -145,6 +173,10 @@ function parseFeatureDirectory(dir, dirName) {
  * @param dir - Directory to search.
  * @param filename - File name to find.
  * @returns Array of matching file paths.
+ * @example
+ * ```ts
+ * const specPath = checkFile("./feature", "spec.md");
+ * ```
  */
 function checkFile(dir, filename) {
     const path = join(dir, filename);

package/dist/src/text.d.ts

@@ -2,18 +2,32 @@
  * Normalise a text field (string | string[]) to a single string, joining with newlines.
  * @param value - The text field to normalise.
  * @returns A single string.
+ * @example
+ * ```ts
+ * textToString(["line 1", "line 2"]) // => "line 1\nline 2"
+ * textToString("hello") // => "hello"
+ * ```
  */
 export declare function textToString(value: string | string[]): string;
 /**
  * Normalise a text field to an array of lines.
  * @param value - The text field to normalise.
  * @returns An array of lines.
+ * @example
+ * ```ts
+ * textToLines("hello") // => ["hello"]
+ * textToLines(["a", "b"]) // => ["a", "b"]
+ * ```
  */
 export declare function textToLines(value: string | string[]): string[];
 /**
  * Format a text field for Markdown output — each line becomes a paragraph.
  * @param value - The text field to format.
  * @returns Markdown-formatted string.
+ * @example
+ * ```ts
+ * textToMarkdown(["para 1", "para 2"]) // => "para 1\npara 2"
+ * ```
  */
 export declare function textToMarkdown(value: string | string[]): string;
 /**
@@ -21,5 +35,10 @@ export declare function textToMarkdown(value: string | string[]): string;
  * Single-line content stays as a string; multiline becomes an array.
  * @param block - The Markdown text block to parse.
  * @returns A string for single-line content, or an array of lines for multiline.
+ * @example
+ * ```ts
+ * markdownToText("single line") // => "single line"
+ * markdownToText("line 1\nline 2") // => ["line 1", "line 2"]
+ * ```
  */
 export declare function markdownToText(block: string): string | string[];

package/dist/src/text.js

@@ -2,6 +2,11 @@
  * Normalise a text field (string | string[]) to a single string, joining with newlines.
  * @param value - The text field to normalise.
  * @returns A single string.
+ * @example
+ * ```ts
+ * textToString(["line 1", "line 2"]) // => "line 1\nline 2"
+ * textToString("hello") // => "hello"
+ * ```
  */
 export function textToString(value) {
     return Array.isArray(value) ? value.join("\n") : value;
@@ -10,6 +15,11 @@ export function textToString(value) {
  * Normalise a text field to an array of lines.
  * @param value - The text field to normalise.
  * @returns An array of lines.
+ * @example
+ * ```ts
+ * textToLines("hello") // => ["hello"]
+ * textToLines(["a", "b"]) // => ["a", "b"]
+ * ```
  */
 export function textToLines(value) {
     return Array.isArray(value) ? value : [value];
@@ -18,6 +28,10 @@ export function textToLines(value) {
  * Format a text field for Markdown output — each line becomes a paragraph.
  * @param value - The text field to format.
  * @returns Markdown-formatted string.
+ * @example
+ * ```ts
+ * textToMarkdown(["para 1", "para 2"]) // => "para 1\npara 2"
+ * ```
  */
 export function textToMarkdown(value) {
     return textToLines(value).join("\n");
@@ -27,6 +41,11 @@ export function textToMarkdown(value) {
  * Single-line content stays as a string; multiline becomes an array.
  * @param block - The Markdown text block to parse.
  * @returns A string for single-line content, or an array of lines for multiline.
+ * @example
+ * ```ts
+ * markdownToText("single line") // => "single line"
+ * markdownToText("line 1\nline 2") // => ["line 1", "line 2"]
+ * ```
  */
 export function markdownToText(block) {
     const lines = block.split("\n");

package/package.json

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