@rse/specbook 0.9.5 → 0.9.6

package/dst/specbook-link.d.ts

@@ -1,4 +1,4 @@
-import type { Specification, Object as SpecObject } from "./specbook-struct-spec.js";
+import type { Spec, SpecObject } from "./specbook-format-spec.js";
 export declare const referenceRegex: RegExp;
 interface LinkNode {
     object: SpecObject;
@@ -9,7 +9,7 @@ export interface LinkTarget {
     target?: SpecObject;
     ambiguous: boolean;
 }
-export declare const buildLinkIndex: (specification: Specification) => LinkIndex;
+export declare const buildLinkIndex: (specification: Spec) => LinkIndex;
 export declare const resolveSet: (index: LinkIndex, reference: string) => SpecObject[];
 export declare const resolveUnique: (index: LinkIndex, reference: string) => LinkTarget;
 export declare const anchorPaths: (index: LinkIndex) => Map<SpecObject, string>;

package/dst/specbook-mcp.d.ts

@@ -1 +1,2 @@
-export declare const serveMcp: (verbose: (msg: string) => void) => Promise<void>;
+import { type VerboseSink } from "./specbook-api.js";
+export declare const serveMcp: (verbose: VerboseSink) => Promise<void>;

package/dst/specbook-mcp.js

@@ -43,10 +43,10 @@ export const serveMcp = async (verbose) => {
     });
     server.registerTool("specbook_lint", {
         title: "Lint Specification",
-        description: "Lint the specification Markdown files below the base directory against the " +
-            "optional YAML schema configuration and return all diagnostics.",
+        description: "Lint the specification Markdown files the YAML schema configuration references " +
+            "below the base directory against this configuration and return all diagnostics.",
         inputSchema: {
-            config: z.string().optional().describe("YAML schema configuration file"),
+            config: z.string().describe("YAML schema configuration file"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")")
         }
     }, async (args) => {
@@ -63,11 +63,12 @@ export const serveMcp = async (verbose) => {
     });
     server.registerTool("specbook_export", {
         title: "Export Specification",
-        description: "Export the specification Markdown files below the base directory as JSON, JSON5, " +
+        description: "Export the specification Markdown files the YAML schema configuration references " +
+            "below the base directory as JSON, JSON5, " +
             "YAML, TOON, HTML, PDF, or normalized Markdown. The result is written to the output file " +
             "if an output path is given, else it is returned directly (PDF as a base64-encoded resource).",
         inputSchema: {
-            config: z.string().optional().describe("YAML schema configuration file"),
+            config: z.string().describe("YAML schema configuration file"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
             format: z.enum(formats).optional().describe("output format (default: json)"),
             output: z.string().optional().describe("output file path")
@@ -94,10 +95,14 @@ export const serveMcp = async (verbose) => {
     });
     server.registerTool("specbook_describe", {
         title: "Describe Specification Format",
-        description: "Describe the specification format configured by the YAML schema configuration " +
-            "as a Markdown document.",
+        description: "Describe the SpecBook models and formats as a Markdown document. If the YAML " +
+            "schema configuration or the base directory is given, the description additionally points " +
+            "to the artifacts of that particular project.",
         inputSchema: {
-            config: z.string().describe("YAML schema configuration file"),
+            config: z.string().optional().describe("YAML schema configuration file"),
+            basedir: z.string().optional().describe("base directory of the specification Markdown files"),
+            embed: z.boolean().optional().describe("embed the YAML schema configuration instead of " +
+                "just referencing it (default: false)"),
             output: z.string().optional().describe("output file path (default: return description)")
         }
     }, async (args) => {
@@ -113,49 +118,5 @@ export const serveMcp = async (verbose) => {
             return errorResult(err);
         }
     });
-    server.registerTool("specbook_import", {
-        title: "Import Foreign Sources",
-        description: "Import the information of foreign source files into the configured specification " +
-            "artifact files below the base directory, using an LLM.",
-        inputSchema: {
-            config: z.string().describe("YAML schema configuration file"),
-            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
-            inputs: z.array(z.string()).describe("foreign source files to import"),
-            provider: z.string().optional().describe("AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")"),
-            model: z.string().optional().describe("AI model")
-        }
-    }, async (args) => {
-        try {
-            const written = await specbook.import(args);
-            return { content: [{ type: "text", text: written.length > 0 ?
-                            `imported into artifact file(s): ${written.join(", ")}` :
-                            "no artifact files were changed" }] };
-        }
-        catch (err) {
-            return errorResult(err);
-        }
-    });
-    server.registerTool("specbook_edit", {
-        title: "Edit Specification",
-        description: "Apply a free-text edit request to the configured specification artifact files " +
-            "below the base directory, using an LLM.",
-        inputSchema: {
-            config: z.string().describe("YAML schema configuration file"),
-            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
-            query: z.string().describe("free-text edit request"),
-            provider: z.string().optional().describe("AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")"),
-            model: z.string().optional().describe("AI model")
-        }
-    }, async (args) => {
-        try {
-            const written = await specbook.edit(args);
-            return { content: [{ type: "text", text: written.length > 0 ?
-                            `edited artifact file(s): ${written.join(", ")}` :
-                            "no artifact files were changed" }] };
-        }
-        catch (err) {
-            return errorResult(err);
-        }
-    });
     await server.connect(new StdioServerTransport());
 };

package/dst/specbook-parse-common.d.ts

@@ -1,4 +1,4 @@
-import { type Specification, type Object as SpecObject, type Property } from "./specbook-struct-spec.js";
+import { type Spec, type SpecObject, type SpecProperty } from "./specbook-format-spec.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
 import { type LinkIndex } from "./specbook-link.js";
 export interface SourceFile {
@@ -6,7 +6,7 @@ export interface SourceFile {
     text: string;
 }
 export interface ParseResult {
-    specification: Specification;
+    specification: Spec;
     diagnostics: Diagnostic[];
 }
 export interface ObjectMeta {
@@ -16,11 +16,13 @@ export interface ObjectMeta {
 export declare class ParseContext {
     diagnostics: Diagnostic[];
     objectMeta: WeakMap<SpecObject, ObjectMeta>;
-    propMeta: WeakMap<Property, {
+    propMeta: WeakMap<SpecProperty, {
         line: number;
     }>;
     linkIndex: LinkIndex;
     diagnose(file: string, line: number, message: string): void;
 }
 export declare const embeddingRegex: RegExp;
+export declare const embeddingThemes: string[];
+export declare const embeddingVariants: (reference: string) => string[];
 export declare const embeddingMimeType: (reference: string) => string | undefined;

package/dst/specbook-parse-common.js

@@ -16,6 +16,14 @@ export class ParseContext {
 }
 /*  the Markdown image embedding syntax ("![alt](file)")  */
 export const embeddingRegex = /!\[([^\]]*)\]\(([^()]+)\)/g;
+/*  the theme variants of a theme-aware image embedding  */
+export const embeddingThemes = ["light", "dark"];
+/*  expand an image embedding reference into its variants: a reference
+    carrying the "{theme}" placeholder yields one variant per theme,
+    while every other reference stays its own single variant  */
+export const embeddingVariants = (reference) => reference.includes("{theme}") ?
+    embeddingThemes.map((theme) => reference.replace(/\{theme\}/g, theme)) :
+    [reference];
 /*  the embeddable file types and their MIME types  */
 const embeddingTypes = {
     svg: "image/svg+xml",

package/dst/specbook-parse-semantic.d.ts

@@ -1,5 +1,5 @@
-import { type Specification } from "./specbook-struct-spec.js";
-import { type SchemaSpecification } from "./specbook-struct-schema.js";
+import { type Spec } from "./specbook-format-spec.js";
+import { type Schema } from "./specbook-format-schema.js";
 import { ParseContext } from "./specbook-parse-common.js";
-export declare const validate: (ctx: ParseContext, specification: Specification, config: SchemaSpecification) => void;
-export declare const validateReferences: (ctx: ParseContext, specification: Specification) => void;
+export declare const validate: (ctx: ParseContext, specification: Spec, config: Schema) => void;
+export declare const validateReferences: (ctx: ParseContext, specification: Spec) => void;

package/dst/specbook-parse-semantic.js

@@ -5,21 +5,11 @@
 */
 import { referenceRegex, resolveUnique, resolveSet } from "./specbook-link.js";
 import { compileValueExpr, splitItems } from "./specbook-parse-value.js";
-/*  strip a trailing parenthesized annotation from a
-    property key (e.g. "WHEN (Context)")  */
-const plainKey = (key) => key.replace(/\s*\([^)]*\)\s*$/, "").trim();
 /*  strip the inline code markup of a name or property value
     (preserved in the AST for rendering) for matching purposes  */
 const plainText = (text) => text.replace(/`/g, "");
 /*  compile a configured pattern into an anchored regular expression  */
 const anchored = (pattern, flags = "") => new RegExp(`^(?:${pattern})$`, flags);
-/*  match a single inline token against a value expression
-    (case-insensitively, as inline tokens are decorations)  */
-const tokenMatches = (expr, token) => expr.kind === "regex" ?
-    anchored(expr.source, "i").test(token) :
-    expr.kind === "enum" ?
-        expr.members.some((member) => member.toLowerCase() === token.toLowerCase()) :
-        false;
 /*  match a full property value directly against a value expression
     (defined for the regex and enum kinds only)  */
 const directMatches = (expr, text) => expr.kind === "regex" ?
@@ -51,56 +41,7 @@ const matchAlternatives = (ctx, alternatives, item) => {
     return false;
 };
 /*  find a property of an object by its key (case-sensitive)  */
-const findProp = (object, name) => object.properties.find((p) => plainKey(p.key) === name);
-/*  distribute the inline tokens split off the multi-token property values
-    of an object across its configured properties and report the
-    unassignable ones (the properties assigned a token are returned)  */
-const assignInlineTokens = (ctx, object, props, meta) => {
-    const tokens = new Array();
-    const tokenAssigned = new Set();
-    /*  explode a multi-token property value whose direct pattern check
-        fails: keep the token matching the own pattern and distribute
-        the remaining tokens across the sibling properties  */
-    for (const prop of props) {
-        if (prop.value === undefined)
-            continue;
-        const expr = compileValueExpr(prop.value);
-        if (expr.kind !== "regex" && expr.kind !== "enum")
-            continue;
-        const match = findProp(object, prop.name);
-        if (match === undefined || directMatches(expr, plainText(match.value)))
-            continue;
-        const parts = plainText(match.value).split(/\s+/);
-        if (parts.length < 2)
-            continue;
-        const idx = parts.findIndex((part) => tokenMatches(expr, part));
-        if (idx < 0)
-            continue;
-        match.value = parts[idx];
-        tokenAssigned.add(prop.name);
-        parts.splice(idx, 1);
-        tokens.push(...parts);
-    }
-    /*  assign the collected tokens to the still unset configured
-        properties whose pattern they match  */
-    for (const prop of props) {
-        if (prop.value === undefined || findProp(object, prop.name) !== undefined)
-            continue;
-        const expr = compileValueExpr(prop.value);
-        if (expr.kind !== "regex" && expr.kind !== "enum")
-            continue;
-        const idx = tokens.findIndex((token) => tokenMatches(expr, token));
-        if (idx >= 0) {
-            object.properties.push({ key: prop.name, value: tokens[idx] });
-            tokenAssigned.add(prop.name);
-            tokens.splice(idx, 1);
-        }
-    }
-    /*  report the tokens which no configured property accepts  */
-    for (const token of tokens)
-        ctx.diagnose(meta.file, meta.line, `unassignable inline token "${token}" on ${object.kind} "${object.name}"`);
-    return tokenAssigned;
-};
+const findProp = (object, name) => object.properties.find((p) => p.key === name);
 /*  check a property value against the compiled value expression of its
     configured schema property  */
 const checkPropValue = (ctx, prop, expr, property, meta) => {
@@ -152,8 +93,6 @@ const validateObject = (ctx, object, schema, level) => {
         input, via either "{{<id>}}" or "(<id>)"  */
     if (schema.id !== undefined && (object.anchor ?? object.paren) !== schema.id)
         ctx.diagnose(meta.file, meta.line, `configured id "${schema.id}" not explicitly specified on ${object.kind} "${object.name}"`);
-    /*  distribute the inline tokens split off the multi-token property values  */
-    const tokenAssigned = assignInlineTokens(ctx, object, props, meta);
     /*  check the configured properties  */
     let parenConsumed = false;
     for (const prop of props) {
@@ -170,12 +109,12 @@ const validateObject = (ctx, object, schema, level) => {
             if (prop.optional !== true)
                 ctx.diagnose(meta.file, meta.line, `required property "${prop.name}" missing on ${object.kind} "${object.name}"`);
         }
-        else if (expr !== undefined && !tokenAssigned.has(prop.name))
+        else if (expr !== undefined)
             checkPropValue(ctx, prop, expr, match, { file: meta.file, line: ctx.propMeta.get(match)?.line ?? meta.line });
     }
     /*  report the properties not configured by the schema  */
     for (const property of object.properties)
-        if (!props.some((p) => p.name === plainKey(property.key)))
+        if (!props.some((p) => p.name === property.key))
             ctx.diagnose(meta.file, ctx.propMeta.get(property)?.line ?? meta.line, `unknown property "${property.key}" on ${object.kind} "${object.name}"`);
     /*  a parenthesized token not consumed as a property value acts as
         the implicit anchor (an explicit "{{...}}" anchor takes precedence)  */
@@ -206,7 +145,7 @@ const validateObject = (ctx, object, schema, level) => {
     };
     object.childs.sort((a, b) => kindPos(a.kind) - kindPos(b.kind));
     const propPos = (key) => {
-        const i = props.findIndex((p) => p.name === plainKey(key));
+        const i = props.findIndex((p) => p.name === key);
         return i >= 0 ? i : props.length;
     };
     object.properties.sort((a, b) => propPos(a.key) - propPos(b.key));

package/dst/specbook-parse-syntax.d.ts

@@ -1,3 +1,3 @@
-import { type Artifact } from "./specbook-struct-spec.js";
+import { type SpecArtifact } from "./specbook-format-spec.js";
 import { ParseContext, type SourceFile } from "./specbook-parse-common.js";
-export declare const parseFile: (ctx: ParseContext, source: SourceFile) => Artifact[];
+export declare const parseFile: (ctx: ParseContext, source: SourceFile) => SpecArtifact[];

package/dst/specbook-parse-syntax.js

@@ -6,7 +6,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { marked } from "marked";
-import { embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
+import { embeddingRegex, embeddingMimeType, embeddingVariants } from "./specbook-parse-common.js";
 /*  split a description text into statement and optional rationale  */
 const splitDescription = (text) => {
     const m = text.match(/,\s*(?:\*\*BECAUSE\*\*|BECAUSE)\s+/);
@@ -101,7 +101,9 @@ const parseFrontmatter = (text) => {
 };
 /*  recursively load the image files embedded via "![alt](file)" into the
     description and the property values of an object (SVG as-is, PNG/JPEG
-    as base64 data: URLs), resolving the references relative to the source file  */
+    as base64 data: URLs), resolving the references relative to the source
+    file and expanding a "{theme}" reference into its theme variants,
+    which are loaded into consecutive embedding entries  */
 const embed = (ctx, object, file) => {
     const load = (target, text, line) => {
         for (const m of text.matchAll(embeddingRegex)) {
@@ -109,15 +111,17 @@ const embed = (ctx, object, file) => {
             const type = embeddingMimeType(reference);
             if (type === undefined)
                 continue;
-            try {
-                const data = fs.readFileSync(path.resolve(path.dirname(file), reference));
-                target.embedding ??= [];
-                target.embedding.push(type === "image/svg+xml" ?
-                    data.toString("utf8") : `data:${type};base64,${data.toString("base64")}`);
-            }
-            catch (err) {
-                ctx.diagnose(file, line, `unreadable embedding file "${reference}": ` +
-                    (err instanceof Error ? err.message : String(err)));
+            for (const variant of embeddingVariants(reference)) {
+                try {
+                    const data = fs.readFileSync(path.resolve(path.dirname(file), variant));
+                    target.embedding ??= [];
+                    target.embedding.push(type === "image/svg+xml" ?
+                        data.toString("utf8") : `data:${type};base64,${data.toString("base64")}`);
+                }
+                catch (err) {
+                    ctx.diagnose(file, line, `unreadable embedding file "${variant}": ` +
+                        (err instanceof Error ? err.message : String(err)));
+                }
             }
         }
     };
@@ -283,13 +287,13 @@ export const parseFile = (ctx, source) => {
             if (heading.malformed !== undefined)
                 ctx.diagnose(source.file, line, `malformed anchor "${heading.malformed}" in heading`);
             if (heading.name === "" && depth > 1) {
-                /*  a grouping container heading (e.g. "### STATES") collects
-                    objects of its singular kind below the parent object  */
+                /*  a grouping container heading (e.g. "### STATE") collects
+                    objects of its kind below the parent object  */
                 const parent = stack[depth - 2];
                 if (parent === undefined)
                     ctx.diagnose(source.file, line, `heading level ${depth} without parent object`);
                 else {
-                    group = { parent, kind: heading.kind.replace(/S$/, "") };
+                    group = { parent, kind: heading.kind };
                     current = parent;
                 }
             }

package/dst/specbook-parse.d.ts

@@ -1,8 +1,8 @@
-import { type SchemaSpecification } from "./specbook-struct-schema.js";
+import { type Schema } from "./specbook-format-schema.js";
 import { type SourceFile, type ParseResult } from "./specbook-parse-common.js";
-export { type SourceFile, type ParseResult, embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
+export { type SourceFile, type ParseResult, embeddingRegex, embeddingMimeType, embeddingThemes, embeddingVariants } from "./specbook-parse-common.js";
 export declare class Parser {
     private ctx;
-    parse(sources: SourceFile[], config?: SchemaSpecification): ParseResult;
+    parse(sources: SourceFile[], config?: Schema): ParseResult;
 }
-export declare const parseSpecification: (sources: SourceFile[], config?: SchemaSpecification) => ParseResult;
+export declare const parseSpecification: (sources: SourceFile[], config?: Schema) => ParseResult;

package/dst/specbook-parse.js

@@ -4,14 +4,14 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import * as v from "valibot";
-import { Specification } from "./specbook-struct-spec.js";
+import { Spec } from "./specbook-format-spec.js";
 import { buildLinkIndex } from "./specbook-link.js";
 import { ParseContext } from "./specbook-parse-common.js";
 import { parseFile } from "./specbook-parse-syntax.js";
 import { validate, validateReferences } from "./specbook-parse-semantic.js";
 import { validateDiagrams } from "./specbook-diagram.js";
 /*  re-export the public parsing types and embedding helpers  */
-export { embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
+export { embeddingRegex, embeddingMimeType, embeddingThemes, embeddingVariants } from "./specbook-parse-common.js";
 /*  parser for a set of specification Markdown files  */
 export class Parser {
     ctx = new ParseContext();
@@ -33,7 +33,7 @@ export class Parser {
             validateReferences(this.ctx, specification);
             if (config !== undefined)
                 validateDiagrams(this.ctx, specification, config);
-            const result = v.safeParse(Specification, specification);
+            const result = v.safeParse(Spec, specification);
             if (!result.success)
                 for (const issue of result.issues) {
                     const path = (issue.path ?? []).map((item) => String(item.key)).join(".");

package/dst/specbook-verbose.d.ts

@@ -0,0 +1,2 @@
+export declare const literal: (value: string | number) => string;
+export declare const renderVerbose: (msg: string, style?: (value: string) => string) => string;

package/dst/specbook-verbose.js

@@ -0,0 +1,16 @@
+/*
+**  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>
+*/
+/*  the sentinel characters delimiting a marked literal value, taken
+    from the Unicode private use area, so they never clash with the
+    regular content of a verbose message  */
+const begin = "\uE000";
+const end = "\uE001";
+/*  mark a literal value (path, number, format, ...) inside a verbose
+    message, so the output sink can style it without having to guess  */
+export const literal = (value) => `${begin}${value}${end}`;
+/*  render a verbose message by either styling its marked literal values
+    with the given styler or just stripping their markers away  */
+export const renderVerbose = (msg, style) => msg.replace(/\uE000([^\uE001]*)\uE001/g, (_, value) => style !== undefined ? style(value) : value);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "0.9.5",
+    "version":                             "0.9.6",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -24,7 +24,7 @@
         "pdf-lib":                         "1.17.1",
         "subset-font":                     "2.5.0",
         "@rse/mrcs":                       "0.9.2",
-        "@rse/gradia":                     "1.0.0",
+        "@rse/gradia":                     "1.1.4",
         "@toon-format/toon":               "4.1.1",
         "valibot":                         "1.4.2",
         "nunjucks":                        "3.2.4",
@@ -33,13 +33,9 @@
         "@swc/html":                       "1.16.1",
         "tokenizr":                        "2.2.1",
         "playwright":                      "1.62.1",
-        "ai":                              "7.0.69",
-        "@ai-sdk/anthropic":               "4.0.39",
-        "@ai-sdk/openai":                  "4.0.43",
-        "@openrouter/ai-sdk-provider":     "3.0.0",
-        "ollama-ai-provider-v2":           "4.0.1",
         "source-code-error":               "1.2.0",
         "commander":                       "15.0.0",
+        "chalk":                           "6.0.0",
         "@modelcontextprotocol/sdk":       "1.30.0",
         "zod":                             "4.4.3"
     },

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

@@ -1,9 +0,0 @@
-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

@@ -1,74 +0,0 @@
-/*
-**  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);
-    /*  ensure a non-empty edit request was given  */
-    if (options.query.trim() === "")
-        throw new Error("no edit request given");
-    /*  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;
-        }
-        const file = path.join(basedir, block.name);
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, block.content, "utf8");
-        options.verbose(`wrote artifact file "${block.name}"`);
-        written.push(block.name);
-    }
-    return written;
-};

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

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

package/dst/specbook-cmd-import.js

@@ -1,78 +0,0 @@
-/*
-**  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 import command  */
-const instruction = (description, now) => textframe `
-    You are the import engine of SpecBook, a Markdown-based specification
-    format. Import the information of the given foreign sources into the
-    Markdown specification artifact files of the project, generating or
-    updating the artifact files so they faithfully reflect the imported
-    information. Strictly honor the following rules:
-
-    -   Faithful reflection: the artifacts must reflect the imported
-        sources exactly -- no more, no less.
-    -   No fabrication: never invent content the sources do not support;
-        leave gaps open instead of guessing.
-    -   Surgical updates: when updating an existing artifact, change only
-        what the imported information actually requires.
-    -   Level-appropriate translation: re-express the imported facts at the
-        artifact's level of abstraction; do not copy verbatim.
-    -   Format conformance: strictly follow the specification format
-        described below.
-    -   Markdown generation: emit the Complex Format on levels 1-3
-        ("#"/"##"/"###") and the Concise Format on level 4 and deeper.
-    -   Timestamps: use "${now}" for the "Created:" and "Modified:"
-        frontmatter of generated files, and refresh "Modified:" to
-        "${now}" on updated files.
-    -   Files: generate or update ONLY the configured artifact files listed
-        in the format description below -- never any other file.
-    -   Output: return ONLY the generated or updated files, each as a block
-        of the exact form below, and no other text at all:
-
-        <<<FILE: <name>>>>
-        <content>
-        <<<END-FILE>>>
-
-    ${description}
-`;
-/*  import foreign sources into the specification artifact files  */
-export const importSpecification = async (options) => {
-    const basedir = options.basedir ?? ".";
-    const files = options.config.map((artifact) => artifact.file).filter((file) => file !== undefined);
-    /*  ensure at least one foreign source was given  */
-    if (options.inputs.length === 0)
-        throw new Error("no foreign sources given to import");
-    /*  gather the existing artifact files and the foreign sources  */
-    const existing = files
-        .filter((file) => fs.existsSync(path.join(basedir, file)))
-        .map((file) => renderFileBlock(file, fs.readFileSync(path.join(basedir, file), "utf8")));
-    const sources = options.inputs
-        .map((input) => renderFileBlock(input, fs.readFileSync(input, "utf8")));
-    /*  let the LLM generate or update the artifact files  */
-    options.verbose(`importing ${options.inputs.length} foreign source(s) into "${basedir}"`);
-    const system = instruction(describeConfiguration(options.config), timestamp());
-    const prompt = "EXISTING ARTIFACT FILES:\n\n" + (existing.length > 0 ? existing.join("\n\n") : "(none)") +
-        "\n\nFOREIGN SOURCES TO IMPORT:\n\n" + sources.join("\n\n");
-    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;
-        }
-        const file = path.join(basedir, block.name);
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, block.content, "utf8");
-        options.verbose(`wrote artifact file "${block.name}"`);
-        written.push(block.name);
-    }
-    return written;
-};