@rse/ase 0.9.65 → 0.9.67

package/dst/ase-hook.js

@@ -473,7 +473,7 @@ export default class HookCommand {
     }
     /*  the edit-capable skills whose active state lets the pre-tool-use
         hook auto-approve subsequent "Edit" invocations  */
-    editCapableSkills = ["ase-code-lint", "ase-docs-proofread"];
+    editCapableSkills = ["ase-code-lint", "ase-docs-shorten", "ase-docs-refine", "ase-docs-proofread"];
     /*  determine whether an ASE tool invocation described by the parsed
         hook input should be auto-approved, and (if so) the human-readable
         reason. The input field names and value shapes differ between

package/dst/ase-metric.js

@@ -0,0 +1,103 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import fs from "node:fs";
+import { z } from "zod";
+import { writeStdout } from "./ase-stdio.js";
+/*  measure the metrics of the text "content", where "words" are the
+    whitespace-separated tokens, "lines" count a trailing line without a
+    final newline as a full line, "chars" are Unicode characters (code
+    points), and "bytes" are the UTF-8 octets of the content itself,
+    overridable with the raw octet size of an underlying file  */
+export const measure = (content, bytes = Buffer.byteLength(content, "utf8")) => {
+    const words = content.split(/\s+/).filter((word) => word !== "").length;
+    const lines = content === "" ? 0 : content.replace(/\n$/, "").split("\n").length;
+    const chars = Array.from(content).length;
+    return { words, lines, chars, bytes };
+};
+/*  measure the metrics of the content of a file, counting its raw
+    octets as "bytes", as the file encoding is not necessarily UTF-8  */
+export const measureFile = (file) => {
+    let buffer;
+    try {
+        buffer = fs.readFileSync(file);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`metric: cannot read file "${file}": ${message}`, { cause: err });
+    }
+    return measure(buffer.toString("utf8"), buffer.length);
+};
+/*  measure the metrics of the mutually exclusive inputs "file" and
+    "text", of which exactly one has to be given  */
+export const measureInput = (file, text) => {
+    if (file !== undefined && text !== undefined)
+        throw new Error("metric: \"file\" and \"text\" are mutually exclusive");
+    else if (file !== undefined)
+        return measureFile(file);
+    else if (text !== undefined)
+        return measure(text);
+    else
+        throw new Error("metric: either \"file\" or \"text\" has to be given");
+};
+/*  CLI command "ase metric"  */
+export default class MetricCommand {
+    /*  register commands  */
+    register(program) {
+        program
+            .command("metric")
+            .description("Measure the words, lines, characters, and bytes of a file or a text")
+            .option("-f, --file <file>", "measure the content of <file> instead of the arguments")
+            .argument("[text...]", "text to measure (mutually exclusive with --file)")
+            .action(async (text, opts) => {
+            const result = measureInput(opts.file, text.length > 0 ? text.join(" ") : undefined);
+            await writeStdout(`${JSON.stringify(result)}\n`);
+        });
+    }
+}
+/*  render a caught error as an MCP tool error result  */
+const mcpToolError = (err) => ({
+    isError: true,
+    content: [{ type: "text", text: `ERROR: ${err instanceof Error ? err.message : String(err)}` }]
+});
+/*  MCP registration entry point for metric tool  */
+export class MetricMCP {
+    register(mcp) {
+        mcp.registerTool("ase_text_metric", {
+            title: "ASE text metric",
+            description: "Measure the length metrics of a text, given either as the path `file` or as the " +
+                "literal `text`, which are mutually exclusive and of which exactly one has to be given. " +
+                "Returns `words` (the whitespace-separated tokens), `lines` (the newline-separated " +
+                "lines, where a trailing line without a final newline still counts as one line), " +
+                "`chars` (the Unicode characters, i.e. code points), and `bytes` (the octets: the raw " +
+                "file size for `file`, the UTF-8 length for `text`). " +
+                "You MUST call this tool whenever a text length is needed, instead of counting or " +
+                "estimating the length yourself.",
+            inputSchema: {
+                file: z.string().optional()
+                    .describe("path of the file whose content is measured (mutually exclusive with `text`)"),
+                text: z.string().optional()
+                    .describe("literal text which is measured (mutually exclusive with `file`)")
+            },
+            outputSchema: {
+                words: z.number().describe("number of whitespace-separated tokens"),
+                lines: z.number().describe("number of lines"),
+                chars: z.number().describe("number of Unicode characters (code points)"),
+                bytes: z.number().describe("number of octets")
+            }
+        }, async (args) => {
+            try {
+                const result = measureInput(args.file, args.text);
+                return {
+                    structuredContent: result,
+                    content: [{ type: "text", text: JSON.stringify(result) }]
+                };
+            }
+            catch (err) {
+                return mcpToolError(err);
+            }
+        });
+    }
+}

package/dst/ase-mint.js

@@ -0,0 +1,106 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { createHash } from "node:crypto";
+import { Option } from "commander";
+import { z } from "zod";
+import UUID from "pure-uuid";
+import { writeStdout } from "./ase-stdio.js";
+/*  the fixed ASE namespace UUID, itself a UUID V5 over the ASE home URL
+    within the standard URL namespace, so that all hint-derived UUIDs
+    stay stable over time and disjoint from those of other applications  */
+const NAMESPACE = new UUID(5, "ns:URL", "https://ase.tools").format("std");
+/*  mint "count" identifiers of "type" out of "hint": an empty hint
+    yields "count" random UUIDs (V4), while a non-empty hint yields
+    exactly one deterministic hash (UUID V5, SHA-1), as hashing is a
+    pure function of the hint and hence cannot produce distinct results
+    for it -- a larger count is clamped and reported back as a warning  */
+export const mint = (type, hint, count) => {
+    if (!Number.isInteger(count) || count < 1)
+        throw new Error("mint: count has to be a positive integer");
+    if (type === "sha1" && hint === "")
+        throw new Error("mint: type \"sha1\" requires a non-empty hint");
+    let warning = "";
+    if (hint !== "" && count > 1) {
+        warning = `WARNING: type "${type}" is deterministic for a non-empty hint, ` +
+            `so the requested count ${count} was reduced to 1`;
+        count = 1;
+    }
+    const ids = [];
+    for (let i = 0; i < count; i++) {
+        if (type === "uuid")
+            ids.push(hint === "" ?
+                new UUID(4).format("std") :
+                new UUID(5, NAMESPACE, hint).format("std"));
+        else
+            ids.push(createHash("sha1").update(hint).digest("hex"));
+    }
+    return { ids, warning };
+};
+/*  CLI command "ase mint"  */
+export default class MintCommand {
+    /*  register commands  */
+    register(program) {
+        program
+            .command("mint")
+            .description("Mint hash-derived identifiers (UUID, SHA-1) out of a hint")
+            .addOption(new Option("-t, --type <type>", "identifier type")
+            .choices(["uuid", "sha1"]).default("uuid"))
+            .option("-c, --count <count>", "number of identifiers to mint (empty hint only)", "1")
+            .argument("[hint...]", "hint the identifiers are derived from")
+            .action(async (hint, opts) => {
+            const count = Number(opts.count);
+            const result = mint(opts.type, hint.join(" "), count);
+            if (result.warning !== "")
+                process.stderr.write(`ase mint: ${result.warning}\n`);
+            await writeStdout(`${result.ids.join("\n")}\n`);
+        });
+    }
+}
+/*  MCP registration entry point for mint tool  */
+export class MintMCP {
+    register(mcp) {
+        mcp.registerTool("ase_mint", {
+            title: "ASE mint",
+            description: "Mint one or more hash-derived identifiers out of a free-text `hint`. " +
+                "For `type` `uuid`, a deterministic UUID V5 within the fixed ASE namespace " +
+                "is derived from the hint, or a random UUID V4 if the hint is empty. " +
+                "For `type` `sha1`, the 40-character hexadecimal SHA-1 digest of the hint " +
+                "is derived, which requires a non-empty hint. " +
+                "Pass `count` to mint more than one random UUID V4 at once, which is " +
+                "possible for an empty hint only, as hashing a non-empty hint is " +
+                "deterministic and hence always yields exactly one identifier. " +
+                "Returns the minted identifiers as `text`, one per line, optionally " +
+                "preceded by a line starting with `WARNING:`.",
+            inputSchema: {
+                type: z.enum(["uuid", "sha1"]).default("uuid")
+                    .describe("identifier type: `uuid` (UUID V5, or V4 for an empty hint) or " +
+                    "`sha1` (SHA-1 hexadecimal digest), default `uuid`"),
+                hint: z.string().default("")
+                    .describe("free-text hint the identifiers are derived from " +
+                    "(an empty hint is allowed for `uuid` only)"),
+                count: z.number().int().positive().max(100).default(1)
+                    .describe("number of identifiers to mint (at most 100, default 1); " +
+                    "honored for an empty hint only, else clamped to 1")
+            }
+        }, async (args) => {
+            try {
+                const result = mint(args.type, args.hint, args.count);
+                const text = (result.warning !== "" ? [result.warning] : [])
+                    .concat(result.ids).join("\n");
+                return {
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `ERROR: ${message}` }]
+                };
+            }
+        });
+    }
+}

package/dst/ase-service.js

@@ -29,6 +29,8 @@ import { SleepMCP } from "./ase-sleep.js";
 import { GetoptMCP } from "./ase-getopt.js";
 import { SkillsMCP } from "./ase-skills.js";
 import { WorktreeMCP } from "./ase-worktree.js";
+import { MintMCP } from "./ase-mint.js";
+import { MetricMCP } from "./ase-metric.js";
 import pkg from "../package.json" with { type: "json" };
 /*  shared service host  */
 export const SERVICE_HOST = "127.0.0.1";
@@ -276,6 +278,8 @@ export default class ServiceCommand {
             new GetoptMCP().register(mcp);
             new SkillsMCP().register(mcp);
             new WorktreeMCP().register(mcp);
+            new MintMCP().register(mcp);
+            new MetricMCP().register(mcp);
             new ConfigMCP(this.log).register(mcp);
             return mcp;
         };

package/dst/ase-setup.js

@@ -240,6 +240,87 @@ export default class SetupCommand {
         }
         return 0;
     }
+    /*  handler for "ase setup status"  */
+    async doStatus(tool) {
+        const spec = toolSpecs[tool];
+        await this.ensureTool(spec.cli);
+        this.log.write("info", `setup: status: probing ASE registrations for ${spec.label}`);
+        const table = new Table({
+            head: ["KIND", "ID", "SCOPE", "STATUS"],
+            colWidths: [13, 34, 10, 16],
+            wordWrap: true,
+            chars: { "mid": "", "left-mid": "", "mid-mid": "", "right-mid": "" },
+            style: { head: ["blue"] }
+        });
+        /*  report the ASE plugin registrations, with an absent plugin
+            still rendered as an explicit row instead of being omitted  */
+        const plugins = await this.pluginStatus(tool);
+        if (plugins.length === 0)
+            table.push(["PLUGIN", chalk.bold("ase@ase"), "(n/a)", "not installed"]);
+        else
+            for (const plugin of plugins)
+                table.push(["PLUGIN", chalk.bold("ase@ase"), plugin.scope, plugin.status]);
+        /*  report the registered MCP servers, probed concurrently and
+            silently skipping every server which is not registered at all  */
+        const scopes = await Promise.all(this.mcpServers.map((handle) => this.mcpScope(tool, handle.server)));
+        for (let i = 0; i < this.mcpServers.length; i++) {
+            const scope = scopes[i];
+            if (scope === undefined)
+                continue;
+            table.push(["MCP", chalk.bold(this.mcpServers[i].server), scope, "registered"]);
+        }
+        /*  report the ASE statusline registrations  */
+        for (const statusline of await this.statuslineStatus(tool))
+            table.push(["STATUSLINE", chalk.bold(statusline.file), statusline.scope, statusline.status]);
+        process.stdout.write(`${table.toString()}\n`);
+        return 0;
+    }
+    /*  probe the ASE plugin registrations by scraping the human-readable
+        output of "<cli> plugin list", whose format differs per tool  */
+    async pluginStatus(tool) {
+        const result = await execa(toolSpecs[tool].cli, ["plugin", "list"], { stdio: "pipe", reject: false });
+        const lines = (result.stdout ?? "").split(/\r?\n/);
+        const entries = [];
+        if (tool === "claude") {
+            /*  the Anthropic Claude Code CLI renders one indented block per
+                plugin, carrying an explicit "Scope:" and "Status:" field  */
+            for (let i = 0; i < lines.length; i++) {
+                if (!/(^|\s)ase@ase\s*$/.test(lines[i]))
+                    continue;
+                let scope = "(unknown)";
+                let status = "(unknown)";
+                for (let j = i + 1; j < lines.length; j++) {
+                    const m = lines[j].match(/^\s+(\w+):\s*(.+?)\s*$/);
+                    if (m === null)
+                        break;
+                    /*  strip the leading "✔"/"✘" glyph of the status value  */
+                    const value = m[2].replace(/^[^\p{L}\p{N}]+/u, "");
+                    if (m[1] === "Scope")
+                        scope = value;
+                    else if (m[1] === "Status")
+                        status = value;
+                }
+                entries.push({ scope, status });
+            }
+        }
+        else if (tool === "copilot") {
+            /*  the GitHub Copilot CLI renders a flat bullet list which
+                carries neither a scope nor an enabled/disabled state  */
+            for (const line of lines)
+                if (/(^|\s)ase@ase(\s|\(|$)/.test(line))
+                    entries.push({ scope: "(n/a)", status: "installed" });
+        }
+        else {
+            /*  the OpenAI Codex CLI renders a per-marketplace table whose
+                second column carries the combined installation status  */
+            for (const line of lines) {
+                const m = line.match(/^ase@ase\s+(not installed|installed(?:,\s*\w+)?)/);
+                if (m !== null && m[1] !== "not installed")
+                    entries.push({ scope: "(n/a)", status: m[1] });
+            }
+        }
+        return entries;
+    }
     /*  handler for "ase setup mcp list"  */
     async doMcpList() {
         const table = new Table({
@@ -335,6 +416,19 @@ export default class SetupCommand {
         const result = await execa(toolSpecs[tool].cli, ["mcp", "get", name], { stdio: "ignore", reject: false });
         return result.exitCode === 0;
     }
+    /*  probe the registration scope of an MCP server by scraping the
+        human-readable output of "<cli> mcp get <name>"; returns "undefined"
+        for a server which is not registered with the tool at all  */
+    async mcpScope(tool, name) {
+        const result = await execa(toolSpecs[tool].cli, ["mcp", "get", name], { stdio: "pipe", reject: false });
+        if (result.exitCode !== 0)
+            return undefined;
+        /*  the Anthropic Claude Code CLI reports "Scope: <scope> config (...)",
+            the GitHub Copilot CLI reports "Source: <scope>", and the
+            OpenAI Codex CLI reports no scope information at all  */
+        const m = (result.stdout ?? "").match(/^\s*(?:Scope|Source):\s*(\S+)/m);
+        return m !== null ? m[1].toLowerCase() : "(n/a)";
+    }
     /*  register an MCP server with the tool, supporting both the "stdio"
         (a local subprocess command) and "http" (a remote URL, optionally
         with HTTP headers) transports; the per-tool command line differs
@@ -575,7 +669,7 @@ export default class SetupCommand {
     statuslineFormatDflt = [
         "<blue>%u</blue> <red>%p</red> <black>%T</black> %s",
         "%m %e %t",
-        "%P %h %c"
+        "%P %h %B %c"
     ];
     /*  resolve the tool settings file for a given installation scope  */
     statuslineSettingsFile(tool, scope) {
@@ -785,6 +879,36 @@ export default class SetupCommand {
         this.log.write("info", `setup: statusline: deactivate: removing ASE "statusLine" from ${file}`);
         return 0;
     }
+    /*  probe the ASE statusline registrations by inspecting the tool
+        settings files of all applicable installation scopes  */
+    async statuslineStatus(tool) {
+        /*  the OpenAI Codex CLI has no scriptable statusline mechanism at all  */
+        if (tool === "codex")
+            return [];
+        const home = os.homedir();
+        const scopes = tool === "claude" ? ["user", "project", "local"] : ["user"];
+        const entries = [];
+        for (const scope of scopes) {
+            const file = this.statuslineSettingsFile(tool, scope);
+            let root;
+            try {
+                root = await this.statuslineReadAst(file);
+            }
+            catch {
+                /*  an unparsable settings file carries no usable state  */
+                continue;
+            }
+            const member = this.statuslineFindMember(root);
+            if (member === undefined)
+                continue;
+            entries.push({
+                file: file.startsWith(home + path.sep) ? `~${file.slice(home.length)}` : file,
+                scope: tool === "claude" ? scope : "(n/a)",
+                status: this.statuslineIsOwned(member) ? "activated" : "foreign"
+            });
+        }
+        return entries;
+    }
     /*  parse and validate the --tool option  */
     parseTool(value) {
         if (value !== "claude" && value !== "copilot" && value !== "codex")
@@ -870,6 +994,14 @@ export default class SetupCommand {
             .action(async (opts) => {
             process.exit(await this.doToggle(this.parseTool(opts.tool), this.parseScope(opts.scope), "disable"));
         });
+        /*  register CLI sub-command "ase setup status"  */
+        setupCmd
+            .command("status")
+            .description("report the ASE plugin, MCP server, and statusline registrations for a tool")
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
+            .action(async (opts) => {
+            process.exit(await this.doStatus(this.parseTool(opts.tool)));
+        });
         /*  register CLI sub-command "ase setup mcp"  */
         const mcpCmd = setupCmd
             .command("mcp")

package/dst/ase-spec.js

@@ -8,43 +8,53 @@ import fs from "node:fs";
 import { isScalar } from "yaml";
 import { z } from "zod";
 import sourceCodeError from "source-code-error";
-import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec } from "@rse/specbook";
+import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, previewAddr, previewPort } from "@rse/specbook";
 import { Config, configSchema } from "./ase-config.js";
 import { Task } from "./ase-task.js";
 import { Artifact } from "./ase-artifact.js";
 import { Meta } from "./ase-meta.js";
 import { writeStdout } from "./ase-stdio.js";
-/*  reusable functionality: lint and export the SpecBook-based project
-    specification, located via the "project.artifact.spec.basedir" and
-    "project.artifact.spec.schema" configuration  */
+/*  reusable functionality: lint, export, and preview the SpecBook-based
+    project specification, located via the "project.artifact.spec.basedir"
+    and "project.artifact.spec.schema" configuration  */
 export class Spec {
-    /*  resolve the YAML schema configuration file: the configured
+    /*  resolve the YAML schema configuration files: the configured
         "project.artifact.spec.schema" relative to the project root, or
         the bundled standard "ase-format-specbook.yaml" plugin meta file
         if unset or empty  */
-    static configFile(log) {
+    static configFiles(log) {
         const cfg = new Config("config", configSchema, log);
         cfg.read();
         const val = cfg.get("project.artifact.spec.schema");
         const file = val === undefined ? "" : String(isScalar(val) ? val.value : val);
         if (file === "")
-            return Meta.resolve("ase-format-specbook.yaml");
-        return path.resolve(Task.projectRoot(), file);
+            return [Meta.resolve("ase-format-specbook.yaml")];
+        return [path.resolve(Task.projectRoot(), file)];
     }
+    /*  the ASE log level each SpecBook verbosity level maps onto: the
+        "none" level carries the messages a bare SpecBook CLI run always
+        prints, which are mere progress chatter under ASE and hence are
+        not logged at all, while the regular and detailed processing
+        messages reach the info log and the tracing ones the debug log  */
+    static logLevel = {
+        none: null,
+        notice: "info",
+        detail: "info",
+        trace: "debug"
+    };
     /*  create the SpecBook API instance, routing its verbose processing
-        messages into the info log if requested, else into the debug log,
-        while its "notice" messages always reach the warning log and, for
-        consumers which never see the log, the given collector  */
-    static api(log, verbose, notices) {
+        messages into the log according to their verbosity level, while
+        its "none" level messages, for consumers which never see the log,
+        additionally reach the given collector  */
+    static api(log, notices) {
         return new SpecBook({
             verbose: (cmd, msg, level) => {
                 const text = renderVerbose(msg);
-                if (level === "notice") {
-                    log.write("warning", `specbook: ${cmd}: ${text}`);
+                if (level === "none")
                     notices?.push(text);
-                }
-                else
-                    log.write(verbose ? "info" : "debug", `specbook: ${cmd}: ${text}`);
+                const logLevel = Spec.logLevel[level];
+                if (logLevel !== null)
+                    log.write(logLevel, `specbook: ${cmd}: ${text}`);
             }
         });
     }
@@ -72,9 +82,9 @@ export class Spec {
     }
     /*  lint the specification Markdown files below the "spec" artifact
         base directory against the schema configuration  */
-    static async lint(log, verbose = false) {
-        const result = await Spec.unmarked(Spec.api(log, verbose).lint({
-            config: Spec.configFile(log),
+    static async lint(log) {
+        const result = await Spec.unmarked(Spec.api(log).lint({
+            config: Spec.configFiles(log),
             basedir: Artifact.basedir(log, "spec")
         }));
         return result.diagnostics.map((d) => ({ ...d, file: Spec.relativize(d.file) }));
@@ -94,6 +104,7 @@ export class Spec {
         if (code === "")
             return `${renderDiagnostic(diagnostic)}\n`;
         return sourceCodeError({
+            type: diagnostic.severity === "warning" ? "WARNING" : "ERROR",
             message: diagnostic.message,
             filename: diagnostic.file,
             code,
@@ -105,13 +116,37 @@ export class Spec {
     /*  export the specification Markdown files below the "spec" artifact
         base directory into the requested formats, one buffer per format,
         collecting the emitted environment notices if requested  */
-    static export(log, formats, verbose = false, notices) {
-        return Spec.unmarked(Spec.api(log, verbose, notices).export({
-            config: Spec.configFile(log),
+    static export(log, formats, notices) {
+        return Spec.unmarked(Spec.api(log, notices).export({
+            config: Spec.configFiles(log),
             basedir: Artifact.basedir(log, "spec"),
             formats
         }));
     }
+    /*  export the specification like "export" and then keep the export
+        in sync with its sources, handing every fresh set of buffers to
+        "onExport", where "outputs" names the files "onExport" writes,
+        so an output which is itself an observed source can be refused  */
+    static watch(log, formats, outputs, onExport) {
+        return Spec.unmarked(Spec.api(log).watch({
+            config: Spec.configFiles(log),
+            basedir: Artifact.basedir(log, "spec"),
+            formats,
+            outputs,
+            onExport
+        }));
+    }
+    /*  serve the HTML export of the specification as a live preview,
+        kept in sync with its sources and pushed into the connected
+        browsers as an in-place document update  */
+    static preview(log, addr, port) {
+        return Spec.unmarked(Spec.api(log).preview({
+            config: Spec.configFiles(log),
+            basedir: Artifact.basedir(log, "spec"),
+            addr,
+            port
+        }));
+    }
 }
 /*  CLI command "ase spec"  */
 export default class SpecCommand {
@@ -124,7 +159,7 @@ export default class SpecCommand {
         /*  register CLI top-level command "ase spec"  */
         const spec = program
             .command("spec")
-            .description("Lint and export the SpecBook-based project specification")
+            .description("Lint, export, and preview the SpecBook-based project specification")
             .action(() => {
             spec.outputHelp();
             process.exit(1);
@@ -133,14 +168,14 @@ export default class SpecCommand {
         spec
             .command("lint")
             .description("Lint the specification Markdown files against the SpecBook schema configuration")
-            .option("-v, --verbose", "print verbose processing information and each diagnostic with its affected source snippet")
+            .option("-v, --verbose", "print each diagnostic with its affected source snippet")
             .action(async (opts) => {
-            const diagnostics = await Spec.lint(this.log, opts.verbose === true);
+            const diagnostics = await Spec.lint(this.log);
             for (const diagnostic of diagnostics)
                 await writeStdout(opts.verbose === true ?
                     Spec.render(diagnostic, process.stdout.isTTY === true) :
                     `${renderDiagnostic(diagnostic)}\n`);
-            if (diagnostics.length > 0)
+            if (diagnostics.some((diagnostic) => diagnostic.severity === "error"))
                 process.exitCode = 1;
         });
         /*  register CLI sub-command "ase spec export"  */
@@ -150,21 +185,47 @@ export default class SpecCommand {
             .option("-o, --output <[format:]file>", "output file (\"-\" for stdout, repeatable), with the format inferred " +
             "from the filename extension unless explicitly prefixed " +
             "(default: \"index.html\" inside the specification base directory)", (value, previous) => previous.concat(value), new Array())
-            .option("-v, --verbose", "print verbose processing information")
+            .option("-w, --watch", "keep the outputs in sync by re-exporting on every source change")
             .action(async (opts) => {
             const outputs = (opts.output.length > 0 ? opts.output :
                 [path.join(Artifact.basedir(this.log, "spec"), "index.html")]).map(parseOutputSpec);
+            /*  a re-export has to land somewhere it can be picked up again,
+                which a one-shot stdout stream cannot provide  */
+            if (opts.watch === true && outputs.some(({ output }) => output === "-"))
+                throw new Error("the watch mode requires regular output files " +
+                    "(\"-\" for stdout is not supported)");
+            /*  parse the input once and export each distinct format once  */
             const distinct = Array.from(new Set(outputs.map(({ format }) => format)));
-            const buffers = await Spec.export(this.log, distinct, opts.verbose === true);
-            for (const { format, output } of outputs) {
-                const data = buffers[distinct.indexOf(format)];
-                if (output === "-")
-                    await writeStdout(data);
-                else {
-                    await fs.promises.writeFile(output, data);
-                    this.log.write("info", `spec: exported specification into "${output}" (${data.length} bytes)`);
+            const write = async (buffers) => {
+                for (const { format, output } of outputs) {
+                    const data = buffers[distinct.indexOf(format)];
+                    if (output === "-")
+                        await writeStdout(data);
+                    else {
+                        await fs.promises.writeFile(output, data);
+                        this.log.write("info", `spec: exported specification into "${output}" (${data.length} bytes)`);
+                    }
                 }
+            };
+            if (opts.watch === true) {
+                await Spec.watch(this.log, distinct, outputs.map(({ output }) => output), write);
+                await new Promise(() => { });
             }
+            else
+                await write(await Spec.export(this.log, distinct));
+        });
+        /*  register CLI sub-command "ase spec preview"  */
+        spec
+            .command("preview")
+            .description("Serve the HTML export of the specification Markdown files as a live preview")
+            .option("-a, --addr <ip-addr>", "IP address to listen on", previewAddr)
+            .option("-p, --port <tcp-port>", "TCP port to listen on", String(previewPort))
+            .action(async (opts) => {
+            const port = Number(opts.port);
+            if (!Number.isInteger(port) || port < 1 || port > 65535)
+                throw new Error(`invalid TCP port "${opts.port}"`);
+            await Spec.preview(this.log, opts.addr, port);
+            await new Promise(() => { });
         });
     }
 }
@@ -186,11 +247,13 @@ export class SpecMCP {
             description: "Lint the SpecBook specification Markdown files of the project (located via the " +
                 "`project.artifact.spec.basedir` configuration) against the SpecBook YAML schema " +
                 "configuration (`project.artifact.spec.schema`, defaulting to the bundled `ase-format-specbook.yaml`). " +
-                "Returns a `diagnostics` array of `{ file, line, column, message }` objects (with " +
-                "project-relative `file`), rendered as bullet points in `text`. With `verbose`, " +
+                "Returns a `diagnostics` array of `{ file, line, column, severity, message }` objects (with " +
+                "project-relative `file` and a `severity` of `error` or `warning`), rendered as bullet " +
+                "points in `text`. With `verbose`, " +
                 "each diagnostic additionally carries a multi-line `snippet` rendering with the " +
                 "affected source lines, which is also used for `text`. An empty array " +
-                "(`text` of `specification valid`) means the specification is valid.",
+                "(`text` of `specification valid`) means the specification is valid; only " +
+                "diagnostics of `error` severity make an export fail.",
             inputSchema: {
                 verbose: z.boolean().optional()
                     .describe("if true, render each diagnostic with its affected source snippet (default: false)")
@@ -200,6 +263,7 @@ export class SpecMCP {
                     file: z.string().describe("project-relative file path"),
                     line: z.number().describe("line number (1-based)"),
                     column: z.number().describe("column number (1-based)"),
+                    severity: z.enum(["error", "warning"]).describe("diagnostic severity"),
                     message: z.string().describe("diagnostic message"),
                     snippet: z.string().optional()
                         .describe("multi-line rendering with the affected source snippet (with `verbose` only)")
@@ -251,7 +315,7 @@ export class SpecMCP {
                 const spec = args.format !== undefined || args.output === undefined ?
                     { format: args.format ?? "json", output: args.output } :
                     parseOutputSpec(args.output);
-                const [data] = await Spec.export(this.log, [spec.format], false, notices);
+                const [data] = await Spec.export(this.log, [spec.format], notices);
                 if (spec.output !== undefined && spec.output !== "-") {
                     await fs.promises.writeFile(path.resolve(Task.projectRoot(), spec.output), data);
                     return {