@rse/specbook 0.9.2

package/README.md

@@ -0,0 +1,199 @@
+
+<img src="https://raw.githubusercontent.com/rse/specbook/master/etc/specbook-logo.svg" width="400" align="right" alt=""/>
+
+SpecBook
+========
+
+**Markdown-based Specification Format**
+
+About
+-----
+
+**SpecBook** defines a generic, Markdown-based *specification
+format* which can be configured for the specifications of particular
+contexts through a YAML-based *schema configuration*. SpecBook allows
+specifications to be *initialized*, *linted*, *exported* (JSON, JSON5,
+YAML, TOON, HTML, PDF, and normalized Markdown), *described* to LLMs,
+and LLM-assisted *imported* and *edited* -- through an API class with
+methods `<cmd>()`, a CLI with commands `specbook <cmd>`, and an MCP
+service with tools `specbook_<cmd>()`.
+
+**SpecBook** provides the following distinct features:
+
+- hierarchical object structure
+- strict Markdown-based input format
+- complex and concise object to Markdown mappings
+- Wiki-style hierarchy-aware object hyperlinks
+- canonical Markdown output format
+- AST-based JSON, JSON5, YAML, and TOON output formats
+- HTML output format for online reading
+- PDF output format for printing and archiving
+- CLI, MCP, and API interfaces
+
+Specification Format
+--------------------
+
+A specification consists of Markdown *artifact* files, each carrying a
+frontmatter with `Created:` and `Modified:` timestamps and a tree of
+*objects*. Every object has a mandatory *kind*, a mandatory *name*, an
+optional unique anchor *id*, optional *properties* (key/value pairs),
+an optional *description* statement with an optional rationale, and
+optional *child* objects.
+
+Three concrete syntaxes exist:
+
+### Complex Format
+
+Usually used on object hierarchy levels 1-3 (`#`, `##`, `###`).
+
+```
+#   <kind/>: <name/> (<id/>)
+
+-   <key/>: <value/>
+-   [...]
+
+<statement/>, BECAUSE <rationale/>.
+```
+
+### Concise Format
+
+Usually used on level 4 and deeper, with child objects nested as
+indented list items below their parent item:
+
+```
+-   <kind/>: <name/>; <key/>: <value/>; [...];
+    <statement/>, BECAUSE <rationale/>.
+```
+
+### Grouped Format
+
+A heading carrying just a *kind* and no `<kind/>: <name/>` pair opens a
+*grouping container* instead of an object. The list items below it are
+Concise Format items whose kind comes from that heading, so they start
+with the (optionally backquoted) name directly:
+
+```
+### <kinds/>
+
+-   `<name/>`; <key/>: <value/>; [...];
+    <statement/>, BECAUSE <rationale/>.
+```
+
+The heading kind is singularized by stripping one trailing `S`, so both
+`### STATES` and `### STATE` group objects of kind `STATE`. The grouped
+objects become childs of the object the heading is nested under.
+
+When **SpecBook** itself generates specification Markdown, it emits
+the Complex Format on levels 1-3 and the Concise Format from level 4
+upwards. When **SpecBook** edits existing files, it mirrors the format
+each existing object already uses.
+
+Schema Configuration
+--------------------
+
+The YAML schema configuration (see
+[`ase.specbook.yaml`](smp/ase.specbook.yaml) for a comprehensive
+example) defines which domain-specific objects are allowed: the artifact
+kinds with their `file` mapping on the first level, the object kinds of
+the deeper levels, and their properties with optional value constraints:
+regular expressions `/xxx/`, object references `[[xxx]]`, enumerations
+`enum(xxx,yyy)`, tag sets `tags(xxx,yyy)`, and lists `list(xxx[, ...])`
+of such alternatives. The `file` field is only allowed on the first
+(artifact) level.
+
+An object kind can additionally carry a `diagram` field, which derives a
+[Gradia](https://github.com/rse/gradia) diagram for every object of that
+kind. Its `type` selects the diagram shape (`graph`, `hub`, or `grid`),
+`nodes` and `edges` select the participating objects through
+comma-separated `[[xxx]]` reference patterns (`nodes` defaults to the
+object itself plus all objects below it), `center` names the object a
+`hub` is projected onto (default: `self`), `onlyConnected` drops the
+edge-less nodes of a `graph`, `collapse` (default: `true`) omits a
+degenerated diagram consisting of a single node only, `qualified` labels
+every node with its object kind, and `config` passes arbitrary Gradia
+rendering options (e.g. `grid-columns-max: 5`) through to the diagram.
+
+The edges are derived from the `[[xxx]]` references of the node objects
+-- from their property values only, or, with `links: all`, from their
+descriptions as well. As the *nesting* of the objects carries no such
+reference, `hierarchy: true` additionally derives a containment edge
+from every node object to each of its child objects which is part of the
+node set. This is what turns a parent object into the hub of its own
+childs, as the `TIER` objects of the sample schema configuration
+demonstrate:
+
+```yaml
+-   kind: TIER
+    diagram:
+        type: hub
+        center: self
+        hierarchy: true
+```
+
+A `grid` is edge-less by definition and hence accepts neither `edges`
+nor `hierarchy`.
+
+Usage
+-----
+
+### CLI
+
+```
+$ specbook init     [-v] [-c <yaml-file>] [-b <basedir>]
+$ specbook lint     [-v] [-c <yaml-file>] [-b <basedir>]
+$ specbook export   [-v] [-c <yaml-file>] [-b <basedir>] [-o [<format>:]<output-file>] [...]
+                    [--max-table-columns <count>]
+$ specbook describe [-v] [-c <yaml-file>] [-o <markdown-file>]
+$ specbook import   [-v] [-c <yaml-file>] [-b <basedir>] <input-files...>
+$ specbook edit     [-v] [-c <yaml-file>] [-b <basedir>] <query>
+$ specbook mcp      [-v]
+```
+
+The base directory `-b`/`--basedir` (default: `.`) is scanned
+recursively for the specification Markdown files, and generated
+specification Markdown files are placed inside it, too.
+
+The export output option `-o`/`--output` (default: `-` for stdout) can
+occur multiple times. The format (`json`, `json5`, `yaml`, `toon`,
+`html`, `pdf`, or `md`) is inferred from the filename extension, unless
+it is explicitly given as a `<format>:` prefix, and plain `-` (stdout)
+defaults to JSON.
+
+The default value of every CLI option `--xxx` can be overridden by a
+corresponding `SPECBOOK_XXX` environment variable (e.g.
+`SPECBOOK_BASEDIR`, `SPECBOOK_CONFIG`, `SPECBOOK_OUTPUT`,
+`SPECBOOK_VERBOSE`), while an explicitly supplied option always wins.
+
+### API
+
+```ts
+import { SpecBook } from "@rse/specbook"
+
+const specbook = new SpecBook({ verbose: (msg) => console.error(msg) })
+const result   = await specbook.lint({ config: "smp/ase.specbook.yaml", basedir: "smp/broadcast" })
+```
+
+### MCP
+
+Run `specbook mcp` to serve the tools `specbook_init`,
+`specbook_lint`, `specbook_export`, `specbook_describe`,
+`specbook_import`, and `specbook_edit` over stdio.
+
+### AI Configuration
+
+The commands `import` and `edit` use an LLM. The environment variables
+`SPECBOOK_AI_PROVIDER` (`anthropic`, `openai`, `openrouter`, or
+`ollama`) and
+`SPECBOOK_AI_MODEL` provide the defaults, which the CLI options
+`--provider`/`--model` (respectively the MCP/API parameters `provider`/
+`model`) override. The provider API keys come from the standard
+environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+`OPENROUTER_API_KEY`), while `ollama` needs no key and uses the local
+Ollama service.
+
+License
+-------
+
+Copyright &copy; 2026 Dr. Ralf S. Engelschall (http://engelschall.com/)<br/>
+Licensed under Apache 2.0 (https://spdx.org/licenses/Apache-2.0)
+

package/dst/specbook-api.d.ts

@@ -0,0 +1,47 @@
+import { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic } from "./specbook-diagnostic.js";
+import { type LintResult } from "./specbook-cmd-lint.js";
+import { parseOutputSpec, formats, type ExportFormat } from "./specbook-cmd-export.js";
+export { formats, parseOutputSpec, type ExportFormat };
+export { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic };
+export { type LintResult };
+export type { Specification, Artifact, Object, Description, Property } from "./specbook-struct-spec.js";
+export type { SchemaSpecification, SchemaObject, SchemaProperty } from "./specbook-struct-schema.js";
+export interface SpecBookOptions {
+    verbose?: (msg: string) => void;
+}
+export declare class SpecBook {
+    private verbose;
+    constructor(options?: SpecBookOptions);
+    private requireConfig;
+    init(options: {
+        config?: string;
+        basedir?: string;
+    }): Promise<string[]>;
+    lint(options: {
+        config?: string;
+        basedir?: string;
+    }): Promise<LintResult>;
+    export(options: {
+        config?: string;
+        basedir?: string;
+        formats?: ExportFormat[];
+        maxTableColumns?: number;
+    }): Promise<Buffer[]>;
+    describe(options: {
+        config?: string;
+    }): Promise<string>;
+    import(options: {
+        config?: string;
+        basedir?: string;
+        inputs: string[];
+        provider?: string;
+        model?: string;
+    }): Promise<string[]>;
+    edit(options: {
+        config?: string;
+        basedir?: string;
+        query: string;
+        provider?: string;
+        model?: string;
+    }): Promise<string[]>;
+}

package/dst/specbook-api.js

@@ -0,0 +1,77 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { loadConfig } from "./specbook-config.js";
+import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
+import { initSpecification } from "./specbook-cmd-init.js";
+import { lint } from "./specbook-cmd-lint.js";
+import { exportSpecification, parseOutputSpec, formats } from "./specbook-cmd-export.js";
+import { describeConfiguration } from "./specbook-cmd-describe.js";
+import { importSpecification } from "./specbook-cmd-import.js";
+import { editSpecification } from "./specbook-cmd-edit.js";
+/*  re-export the central types for API consumers  */
+export { formats, parseOutputSpec };
+export { renderDiagnostic, renderDiagnosticVerbose };
+/*  the SpecBook API  */
+export class SpecBook {
+    verbose;
+    constructor(options = {}) {
+        this.verbose = options.verbose ?? (() => { });
+    }
+    /*  load a mandatory YAML schema configuration, failing on any problem  */
+    requireConfig(file) {
+        if (file === undefined)
+            throw new Error("YAML schema configuration required");
+        this.verbose(`loading configuration "${file}"`);
+        const { config, diagnostics } = loadConfig(file);
+        if (config === null)
+            throw new Error("invalid configuration:\n" +
+                diagnostics.map(renderDiagnostic).join("\n"));
+        return config;
+    }
+    /*  initialize the configured specification artifact files
+        below the base directory  */
+    async init(options) {
+        return initSpecification({ ...options,
+            config: this.requireConfig(options.config), verbose: this.verbose });
+    }
+    /*  lint the specification Markdown files below the base directory  */
+    async lint(options) {
+        return lint({ config: options.config, basedir: options.basedir ?? ".", verbose: this.verbose });
+    }
+    /*  export the specification Markdown files below the base directory
+        as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown,
+        parsing the input just once and returning one buffer per
+        requested format (best-effort: diagnostics do not prevent the
+        export, as validation is the concern of lint)  */
+    async export(options) {
+        const result = lint({ config: options.config, basedir: options.basedir ?? ".", verbose: this.verbose });
+        for (const diagnostic of result.diagnostics)
+            this.verbose(`diagnostic: ${renderDiagnostic(diagnostic)}`);
+        if (result.specification.artifacts.length === 0)
+            throw new Error("unexportable specification:\n" +
+                result.diagnostics.map(renderDiagnostic).join("\n"));
+        const buffers = [];
+        for (const format of options.formats ?? ["json"])
+            buffers.push(await exportSpecification(result.specification, format, this.verbose, options.maxTableColumns, result.config));
+        return buffers;
+    }
+    /*  describe the configured specification format as Markdown  */
+    async describe(options) {
+        return describeConfiguration(this.requireConfig(options.config));
+    }
+    /*  import foreign sources into the specification artifact files
+        below the base directory  */
+    async import(options) {
+        return importSpecification({ ...options,
+            config: this.requireConfig(options.config), verbose: this.verbose });
+    }
+    /*  apply an edit request to the specification artifact files
+        below the base directory  */
+    async edit(options) {
+        return editSpecification({ ...options,
+            config: this.requireConfig(options.config), verbose: this.verbose });
+    }
+}

package/dst/specbook-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dst/specbook-cli.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import * as fs from "node:fs";
+import { Command } from "commander";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, parseOutputSpec } from "./specbook-api.js";
+import { serveMcp } from "./specbook-mcp.js";
+/*  route verbose messages to stderr, keeping stdout reserved
+    for the command outputs and the MCP protocol  */
+const verboseOf = (opts) => (msg) => {
+    if (opts.verbose)
+        process.stderr.write(`specbook: ${msg}\n`);
+};
+/*  write a buffer to stdout, awaiting the write callback which only
+    fires once the data has been flushed to the underlying pipe, so a
+    subsequent "process.exit" cannot truncate the output  */
+const writeStdout = (data) => {
+    return new Promise((resolve, reject) => {
+        process.stdout.write(data, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+};
+/*  write a command result to the output file or stdout  */
+const writeOutput = async (output, data, verbose) => {
+    if (output === "-")
+        await writeStdout(data);
+    else {
+        await fs.promises.writeFile(output, data);
+        verbose(`wrote "${output}" (${data.length} bytes)`);
+    }
+};
+/*  determine an option default value, overridable via a
+    corresponding SPECBOOK_<OPTION> environment variable  */
+const envDefault = (name, fallback) => process.env[`SPECBOOK_${name.toUpperCase().replace(/-/g, "_")}`] ?? fallback;
+/*  determine a flag option default value, overridable via a
+    corresponding SPECBOOK_<OPTION> environment variable  */
+const envDefaultFlag = (name, fallback) => {
+    const value = process.env[`SPECBOOK_${name.toUpperCase().replace(/-/g, "_")}`];
+    return value !== undefined ? !(/^(?:|0|false|no|off)$/i).test(value) : fallback;
+};
+/*  provide the common options of all sub-commands  */
+const common = (command) => command
+    .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false))
+    .option("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"));
+/*  parse the command line  */
+const program = new Command();
+program.name("specbook")
+    .description("Markdown-based Specification Format")
+    .version("0.9.0")
+    .action(() => {
+    program.help();
+});
+program.command("mcp")
+    .description("run as MCP stdio server")
+    .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false))
+    .action(async (opts) => {
+    verboseOf(opts)("starting MCP server on stdio");
+    await serveMcp(verboseOf(opts));
+});
+common(program.command("init"))
+    .description("initialize the configured specification artifact files below the base directory")
+    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
+    .action(async (opts) => {
+    const specbook = new SpecBook({ verbose: verboseOf(opts) });
+    const created = await specbook.init({ config: opts.config, basedir: opts.basedir });
+    process.stdout.write(created.length > 0 ?
+        `initialized artifact file(s): ${created.join(", ")}\n` :
+        "no artifact files were created\n");
+});
+common(program.command("lint"))
+    .description("lint the specification Markdown files below the base directory")
+    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
+    .action(async (opts) => {
+    const specbook = new SpecBook({ verbose: verboseOf(opts) });
+    const result = await specbook.lint({ config: opts.config, basedir: opts.basedir });
+    for (const diagnostic of result.diagnostics)
+        process.stdout.write(opts.verbose ?
+            renderDiagnosticVerbose(diagnostic, process.stdout.isTTY === true) :
+            `${renderDiagnostic(diagnostic)}\n`);
+    if (result.diagnostics.length > 0)
+        process.exitCode = 1;
+    else
+        verboseOf(opts)("specification valid");
+});
+common(program.command("export"))
+    .description("export the specification Markdown files below the base directory " +
+    "as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown")
+    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
+    .option("-o, --output [<format>:]<output-file>", "output file (\"-\" for stdout, repeatable), with the format inferred " +
+    "from the filename extension unless explicitly prefixed", (value, previous) => previous.concat(value), [])
+    .option("--max-table-columns <count>", "maximum name/property/description columns for the compact table rendering", (value) => parseInt(value, 10), parseInt(envDefault("max-table-columns", "4") ?? "4", 10))
+    .action(async (opts) => {
+    const specbook = new SpecBook({ verbose: verboseOf(opts) });
+    const outputs = (opts.output.length > 0 ? opts.output : [envDefault("output") ?? "-"])
+        .map((spec) => parseOutputSpec(spec));
+    /*  parse the input once and export each distinct format once  */
+    const distinct = Array.from(new Set(outputs.map(({ format }) => format)));
+    const buffers = await specbook.export({ config: opts.config, basedir: opts.basedir,
+        formats: distinct, maxTableColumns: opts.maxTableColumns });
+    for (const { format, output } of outputs)
+        await writeOutput(output, buffers[distinct.indexOf(format)], verboseOf(opts));
+});
+common(program.command("describe"))
+    .description("describe the configured specification format as Markdown")
+    .option("-o, --output <markdown-file>", "output file (\"-\" for stdout)", envDefault("output", "-"))
+    .action(async (opts) => {
+    const specbook = new SpecBook({ verbose: verboseOf(opts) });
+    const text = await specbook.describe({ config: opts.config });
+    await writeOutput(opts.output, text, verboseOf(opts));
+});
+common(program.command("import"))
+    .description("import foreign sources into the specification artifact files below the base directory")
+    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
+    .option("--provider <provider>", "AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")", envDefault("provider"))
+    .option("--model <model>", "AI model", envDefault("model"))
+    .argument("<input-files...>", "foreign source files to import")
+    .action(async (inputs, opts) => {
+    const specbook = new SpecBook({ verbose: verboseOf(opts) });
+    const written = await specbook.import({ config: opts.config, basedir: opts.basedir,
+        inputs, provider: opts.provider, model: opts.model });
+    process.stdout.write(written.length > 0 ?
+        `imported into artifact file(s): ${written.join(", ")}\n` :
+        "no artifact files were changed\n");
+});
+common(program.command("edit"))
+    .description("apply a free-text edit request to the specification artifact files below the base directory")
+    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
+    .option("--provider <provider>", "AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")", envDefault("provider"))
+    .option("--model <model>", "AI model", envDefault("model"))
+    .argument("<query>", "free-text edit request")
+    .action(async (query, opts) => {
+    const specbook = new SpecBook({ verbose: verboseOf(opts) });
+    const written = await specbook.edit({ config: opts.config, basedir: opts.basedir,
+        query, provider: opts.provider, model: opts.model });
+    process.stdout.write(written.length > 0 ?
+        `edited artifact file(s): ${written.join(", ")}\n` :
+        "no artifact files were changed\n");
+});
+try {
+    await program.parseAsync();
+}
+catch (err) {
+    /*  include the cause chain, as e.g. fetch failures
+        carry the underlying error only in the cause  */
+    let msg = err instanceof Error ? err.message : String(err);
+    for (let cause = err instanceof Error ? err.cause : undefined; cause instanceof Error; cause = cause.cause)
+        msg += `: ${cause.message}`;
+    process.stderr.write(`specbook: ERROR: ${msg}\n`, () => process.exit(1));
+}

package/dst/specbook-cmd-describe.d.ts

@@ -0,0 +1,2 @@
+import { type SchemaSpecification } from "./specbook-struct-schema.js";
+export declare const describeConfiguration: (config: SchemaSpecification) => string;

package/dst/specbook-cmd-describe.js

@@ -0,0 +1,97 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import textframe from "textframe";
+/*  collapse folded YAML prose into a single line  */
+const collapse = (text) => (text ?? "").replace(/\s+/g, " ").trim();
+/*  the static description of the generic Markdown syntax  */
+const syntax = textframe `
+    #   SpecBook Specification Format
+
+    A specification consists of Markdown *artifact* files, each carrying a
+    frontmatter with \`Created:\` and \`Modified:\` timestamps (format
+    \`yyyy-LL-dd HH:mm\`) and a tree of *objects*. Every object has a *kind*,
+    a *name*, a unique anchor *id*, optional *properties* (key/value pairs),
+    an optional *description* statement with an optional rationale, and
+    optional *child* objects. Two concrete syntaxes exist:
+
+    ##  Complex Format (used on levels 1-3)
+
+    \`\`\`
+    #   <kind>: <name> (<id>)
+
+    -   <key>: <value>
+    -   [...]
+
+    <statement>, BECAUSE <rationale>.
+    \`\`\`
+
+    Level 1 (\`#\`) carries the artifact id in parentheses. Levels 2 (\`##\`)
+    and 3 (\`###\`) instead carry an HTML anchor \`<a id="<id>"></a>\` after
+    the name, where the id uses the artifact id as its prefix.
+
+    ##  Concise Format (used on level 4 and deeper)
+
+    \`\`\`
+    -   <kind>: <name>; <key>: <value>; [...]; <statement>, BECAUSE <rationale>.
+    \`\`\`
+
+    Child objects nest as indented list items below their parent item.
+
+    ##  Primary Marker
+
+    In both formats a literal \`(*)\` directly after the \`<name>\` marks the
+    object as *primary* (e.g. the primary attribute of an entity). It is
+    distinct from an id given as \`(<id>)\` and both may be combined.
+
+    ##  Configured Artifacts
+
+    The following artifacts, object kinds, and properties are configured.
+    Object kinds and property names are *case-sensitive* and must be
+    written exactly as configured. Properties marked \`required\` must be
+    present, and property values must match their given constraint (if
+    any, else any value is allowed): \`/xxx/\` requires a match of the
+    regular expression, \`[[xxx]]\` requires exactly one Wiki-style link
+    reference resolving into the (usually wildcard) reference pattern,
+    \`enum(xxx,yyy)\` requires one of the listed members, \`tags(xxx,yyy)\`
+    requires a comma-separated set of the listed members (each at most
+    once), and \`list(xxx[, ...])\` requires a comma-separated list of
+    items, each matching one of the alternative constraints.
+`;
+/*  describe a single configured property  */
+const describeProperty = (prop, indent) => {
+    let line = `${indent}-   property \`${prop.name}\` (${prop.optional === true ? "optional" : "required"}`;
+    if (prop.value !== undefined)
+        line += `, constraint \`${prop.value}\``;
+    line += `): ${collapse(prop.desc)}`;
+    return line;
+};
+/*  describe a single configured object kind (and recursively its childs)  */
+const describeObject = (object, level, indent) => {
+    const lines = new Array();
+    lines.push(`${indent}-   object kind \`${object.kind}\` on level ${level}` +
+        `${object.optional === true ? " (optional)" : ""}: ${collapse(object.desc)}`);
+    for (const prop of object.props ?? [])
+        lines.push(describeProperty(prop, `${indent}    `));
+    for (const child of object.childs ?? [])
+        lines.push(describeObject(child, level + 1, `${indent}    `));
+    return lines.join("\n");
+};
+/*  describe the configured specification format as Markdown  */
+export const describeConfiguration = (config) => {
+    const sections = new Array();
+    for (const artifact of config) {
+        const lines = new Array();
+        lines.push(`### ${artifact.kind}: ${artifact.name} (${artifact.kind}-${artifact.id})`);
+        lines.push("");
+        if (artifact.file !== undefined)
+            lines.push(`-   file: \`${artifact.file}\``);
+        lines.push(`-   description: ${collapse(artifact.desc)}`);
+        for (const child of artifact.childs ?? [])
+            lines.push(describeObject(child, 2, ""));
+        sections.push(lines.join("\n"));
+    }
+    return `${syntax}\n${sections.join("\n\n")}\n`;
+};

package/dst/specbook-cmd-edit.d.ts

@@ -0,0 +1,9 @@
+import { type SchemaSpecification } from "./specbook-struct-schema.js";
+import { type AiOptions } from "./specbook-llm.js";
+export interface EditOptions extends AiOptions {
+    config: SchemaSpecification;
+    basedir?: string;
+    query: string;
+    verbose: (msg: string) => void;
+}
+export declare const editSpecification: (options: EditOptions) => Promise<string[]>;

package/dst/specbook-cmd-edit.js

@@ -0,0 +1,69 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import * as fs from "node:fs";
+import * as path from "node:path";
+import textframe from "textframe";
+import { describeConfiguration } from "./specbook-cmd-describe.js";
+import { complete, timestamp, renderFileBlock, parseFileBlocks } from "./specbook-llm.js";
+/*  the LLM instruction for the edit command  */
+const instruction = (description, now) => textframe `
+    You are the edit engine of SpecBook, a Markdown-based specification
+    format. Apply the given edit request to the Markdown specification
+    artifact files of the project. Strictly honor the following rules:
+
+    -   Surgical changes: change only what the edit request actually
+        demands; do not rewrite unrelated parts of an artifact.
+    -   No fabrication: never invent content the edit request does not
+        support; leave gaps open instead of guessing.
+    -   Format conformance: strictly follow the specification format
+        described below.
+    -   Markdown generation: MIRROR the format each existing object already
+        uses (keep Complex Format objects complex and Concise Format
+        objects concise); for entirely new objects emit the Complex Format
+        on levels 1-3 ("#"/"##"/"###") and the Concise Format on level 4
+        and deeper.
+    -   Timestamps: refresh the "Modified:" frontmatter of every changed
+        file to "${now}"; keep "Created:" untouched.
+    -   Files: update ONLY the configured artifact files listed in the
+        format description below -- never any other file.
+    -   Output: return ONLY the actually changed files, each as a block of
+        the exact form below, and no other text at all:
+
+        <<<FILE: <name>>>>
+        <content>
+        <<<END-FILE>>>
+
+    ${description}
+`;
+/*  apply an edit request to the specification artifact files  */
+export const editSpecification = async (options) => {
+    const basedir = options.basedir ?? ".";
+    const files = options.config.map((artifact) => artifact.file).filter((file) => file !== undefined);
+    /*  gather the existing artifact files  */
+    const existing = files
+        .filter((file) => fs.existsSync(path.join(basedir, file)))
+        .map((file) => renderFileBlock(file, fs.readFileSync(path.join(basedir, file), "utf8")));
+    if (existing.length === 0)
+        throw new Error(`no configured artifact files found in "${basedir}"`);
+    /*  let the LLM apply the edit request  */
+    options.verbose(`editing artifact files in "${basedir}"`);
+    const system = instruction(describeConfiguration(options.config), timestamp());
+    const prompt = "EXISTING ARTIFACT FILES:\n\n" + existing.join("\n\n") +
+        "\n\nEDIT REQUEST:\n\n" + options.query;
+    const response = await complete(options, system, prompt);
+    /*  write back all returned artifact files  */
+    const written = new Array();
+    for (const block of parseFileBlocks(response)) {
+        if (!files.includes(block.name)) {
+            options.verbose(`ignoring unconfigured file "${block.name}"`);
+            continue;
+        }
+        fs.writeFileSync(path.join(basedir, block.name), block.content, "utf8");
+        options.verbose(`wrote artifact file "${block.name}"`);
+        written.push(block.name);
+    }
+    return written;
+};