@rse/specbook 1.2.15 → 1.2.16

package/README.md

@@ -149,12 +149,14 @@ $ specbook export \
   [-b|--basedir <spec-md-file-basedir>] \
   [-o|--output [<format>:]<output-file>] \
   [-w|--watch] \
+  [-O|--omit <aspect>[,...]] \
   [...]
 
 $ specbook preview \
   [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
+  [-O|--omit <aspect>[,...]] \
   [-a|--addr <ip-addr>] \
   [-p|--port <tcp-port>]
 
@@ -182,8 +184,9 @@ Options:
     of a reference coverage.
 
 -   `-c|--config <schema-yaml-file>`:
-    The YAML schema configuration (default: the bundled standard schema
-    configuration `specbook-format.yaml`) determines the specification:
+    The YAML schema configuration (default: the `config` entry of the
+    project configuration file `.specbook.yaml`, else the bundled standard
+    schema configuration `specbook-format.yaml`) determines the specification:
     exactly the artifact files its `file` fields reference are loaded and
     parsed; all other Markdown files below the base directory are ignored.
     A referenced file which is absent is reported, unless all of its
@@ -210,12 +213,13 @@ Options:
     the schema of the configuration.
 
 -   `-b|--basedir <spec-md-file-basedir>`:
-    The base directory (default: `.`) is the directory the referenced
-    artifact files are resolved against, and generated specification
-    Markdown files are placed inside it, too.
+    The base directory (default: the `basedir` entry of the project
+    configuration file `.specbook.yaml`, else `.`) is the directory the
+    referenced artifact files are resolved against, and generated
+    specification Markdown files are placed inside it, too.
 
 -   `-o|--output [<format>:]<output-file>` (`export` only):
-    The output file (default: `-` for stdout) can be given multiple times.
+    The output file (`-` for stdout) is required and can be given 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.
@@ -234,6 +238,23 @@ Options:
     file itself, as its own write would re-trigger the observation
     endlessly.
 
+-   `-O|--omit <aspect>[,...]` (`export` and `preview` only):
+    Omit content aspects (comma-separated, repeatable) from the HTML and
+    PDF outputs at generation time, instead of just leaving them foldable
+    in the browser. The aspects match the folding controls of the HTML
+    export: `diagram:graph`, `diagram:hub`, and `diagram:grid` omit all
+    diagrams of a type, `diagram:1` (alias: `diagram`), `diagram:2`, and
+    `diagram:3` omit all diagrams from an object tree nesting level on
+    (level 1 hence all, including the "Diagram of Contents" page), and
+    `text:long` cuts every table cell whose estimated number of text
+    lines towers over all other cells of its row (by the `maxCellHeight`
+    percentage of the object kind, default 40) at a word boundary, ending
+    it in a grey `[...]`. An omitted diagram leaves nothing behind and is not even
+    rendered, the folding controls of the omitted aspects leave the brand
+    bar, and the AST outputs (`json`, `json5`, `yaml`, `toon`) drop the
+    `diagram` fields of the omitted diagrams, too, while the `md` output
+    ignores the option.
+
 -   `-a|--addr <ip-addr>`, `-p|--port <tcp-port>` (`preview` only):
     The IP address (default: `127.0.0.1`) and TCP port (default: `12345`)
     the live preview listens on. The HTML export is served on
@@ -262,8 +283,10 @@ Options:
     schema configuration (embedded into the Markdown or emitted as the
     raw file content), so the configuration costs fewer tokens: `0`
     emits it verbatim, `1` re-emits it with 2-space indentation, unwrapped
-    lines, and without comments, `2` additionally leaves out its `refs` fields, and
-    `3` additionally leaves out its `desc` fields of objects and properties.
+    lines, and without comments, `2` additionally leaves out its `refs`,
+    `diagram`, and `format` fields, and `3` additionally leaves out its
+    `desc` fields of objects and properties. The MCP tool `specbook_describe` defaults to
+    `2` instead, as its consumer is an LLM.
 
 -   `-f|--format <format>` (`describe` only):
     The output format (default: `md`) switches from the rendered Markdown
@@ -278,13 +301,35 @@ Options:
     or embedded with `-e|--embed`, else the bundled standard one,
     embedded), or `spec` for the reference to the base directory.
 
+The defaults of `-c|--config` and `-b|--basedir` are, unless
+`SPECBOOK_CONFIG` and `SPECBOOK_BASEDIR` provide them (see below), taken
+from the optional project configuration file `.specbook.yaml`, which is searched
+in the current working directory and then upwards in all of its parent
+directories (the closest one wins), so SpecBook works from any directory
+below the project root:
+
+```yaml
+config:  docs/spec/schema.yaml
+basedir: docs/spec
+```
+
+The entry `config` is a single file or glob pattern or a list of them
+(exactly like the repeatable `-c|--config`, including the literal
+`std`), and the entry `basedir` is a directory. Relative paths resolve
+against the directory of the `.specbook.yaml` itself, the file is
+validated (an unknown entry or a wrongly typed value fails the command),
+and both an explicitly supplied option and its environment variable
+win over its entry.
+
 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`, `SPECBOOK_ADDR`, `SPECBOOK_PORT`), while an
 explicitly supplied option always wins. As `-c|--config` is repeatable,
 `SPECBOOK_CONFIG` carries a list of patterns separated by the path
-delimiter of the platform (`:` on Unix, `;` on Windows).
+delimiter of the platform (`:` on Unix, `;` on Windows). Unlike all
+others, `SPECBOOK_CONFIG` and `SPECBOOK_BASEDIR` are resolved by the API
+itself, so they apply to the API methods and the MCP tools, too.
 
 Beyond those, the option-less `SPECBOOK_BROWSER` selects the browser
 printing the PDF export: a value carrying a path separator is taken as
@@ -298,6 +343,48 @@ Chrome* (the equivalent of `chrome`). An explicitly configured browser
 failing to launch fails the export instead of falling back onto another
 browser.
 
+Agent Skill
+-----------
+
+For *Claude Code*, SpecBook ships the plugin `specbook`, which registers
+the MCP service `specbook mcp` and provides the skill `/specbook` on top
+of it:
+
+```bash
+$ claude plugin marketplace add rse/specbook
+$ claude plugin install specbook@specbook
+```
+
+```text
+/specbook        [-c|--config <yaml-file>] [-b|--basedir <basedir>] [<query>]
+/specbook init   [-c|--config <yaml-file>] [-b|--basedir <basedir>]
+/specbook lint   [-c|--config <yaml-file>] [-b|--basedir <basedir>] [-g|--gitignore]
+/specbook export [-c|--config <yaml-file>] [-b|--basedir <basedir>] [-g|--gitignore]
+                 [-O|--omit <aspect>[,...]] [-o|--output [<format>:]<output-file>] [...]
+/specbook edit   [-c|--config <yaml-file>] [-b|--basedir <basedir>] [-g|--grill]
+                 [-r|--grill-rounds <n>] [-v|--verify] [-l|--loop] [<query>]
+```
+
+Without a command, the skill *activates* the SpecBook know-how: it
+learns the format and the schema configuration through the MCP tool
+`specbook_describe`, so the specification can be queried and changed
+ad-hoc in plain conversation for the remainder of the session, and it
+directly serves an optional *query*. The agent invokes the skill this
+way on its own, as soon as you want to read or change the specification.
+
+The commands `init`, `lint`, and `export` just pass their options
+through to the corresponding MCP tools. The command `edit` edits the
+specification in one shot from a *query*: it learns the format and the
+schema configuration through the MCP tool `specbook_describe`, reads the
+related specification files, optionally interviews you about the open
+points of the query first (`--grill`, for `--grill-rounds` rounds),
+applies the change set, optionally lints the result and fixes the
+reported diagnostics (`--verify`), and optionally asks for the next
+query (`--loop`). All commands leave an absent `--config` and
+`--basedir` to the MCP service, which resolves them through
+`SPECBOOK_CONFIG` and `SPECBOOK_BASEDIR` and then through the
+`.specbook.yaml` found from the working directory of the session upwards.
+
 Example: Simple
 ---------------
 
@@ -312,7 +399,7 @@ example data model:
 ### Generation
 
 ```bash
-$ specbook lint -v \
+$ specbook export -v \
     -b smp/sample \
     -o smp/sample/sample.html \
     -o smp/sample/sample.pdf
@@ -337,7 +424,7 @@ application, based on **SpecBook**'s built-in "standard" schema:
 ### Generation
 
 ```bash
-$ specbook lint -v \
+$ specbook export -v \
     -b smp/broadcast \
     -o smp/broadcast/broadcast.html \
     -o smp/broadcast/broadcast.pdf

package/dst/specbook-api.d.ts

@@ -1,13 +1,15 @@
+import { projectFile } from "./specbook-project.js";
 import { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic, type DiagnosticSeverity } from "./specbook-diagnostic.js";
 import { type LintResult } from "./specbook-cmd-lint.js";
-import { parseOutputSpec, formats, type ExportFormat } from "./specbook-cmd-export.js";
+import { parseOutputSpec, formats, omitAspects, type ExportFormat } from "./specbook-cmd-export.js";
 import { previewAddr, previewPort } from "./specbook-cmd-preview.js";
 import { describeFormats, describeParts, parseDescribeFormat, parseDescribePart, compressLevels, parseCompressLevel, type DescribeFormat, type DescribePart, type CompressLevel } from "./specbook-cmd-describe.js";
 import { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity, type Verbose, type VerboseLevel, type Verbosity } from "./specbook-verbose.js";
 export { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity };
 export { type Verbose, type VerboseLevel, type Verbosity };
-export { formats, parseOutputSpec, type ExportFormat };
+export { formats, parseOutputSpec, omitAspects, type ExportFormat };
 export { previewAddr, previewPort };
+export { projectFile };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
 export { compressLevels, parseCompressLevel };
 export { type DescribeFormat, type DescribePart, type CompressLevel };
@@ -21,49 +23,48 @@ export type VerboseSink = (cmd: string, msg: string, level: VerboseLevel) => voi
 export interface SpecBookOptions {
     verbose?: VerboseSink;
 }
+export interface ProjectOptions {
+    config?: string[];
+    basedir?: string;
+    cwd?: string;
+}
 export declare class SpecBook {
     private verbose;
     constructor(options?: SpecBookOptions);
     private verboseOf;
+    private project;
     private configFiles;
     private requireConfig;
-    init(options: {
-        config?: string[];
-        basedir?: string;
-    }): Promise<string[]>;
-    lint(options: {
-        config?: string[];
-        basedir?: string;
+    init(options: ProjectOptions): Promise<string[]>;
+    lint(options: ProjectOptions & {
         gitignore?: boolean;
     }): Promise<LintResult>;
     private renderFormats;
-    export(options: {
-        config?: string[];
-        basedir?: string;
+    export(options: ProjectOptions & {
         formats?: ExportFormat[];
         realtime?: boolean;
+        omit?: string[];
         gitignore?: boolean;
+        rebase?: (string | undefined)[];
     }): Promise<Buffer[]>;
+    private rebaseOf;
     private observe;
-    watch(options: {
-        config?: string[];
-        basedir?: string;
+    watch(options: ProjectOptions & {
         formats?: ExportFormat[];
         realtime?: boolean;
+        omit?: string[];
         gitignore?: boolean;
         outputs?: string[];
+        rebase?: (string | undefined)[];
         onExport: (buffers: Buffer[]) => void | Promise<void>;
     }): Promise<void>;
-    preview(options: {
-        config?: string[];
-        basedir?: string;
+    preview(options: ProjectOptions & {
         addr?: string;
         port?: number;
+        omit?: string[];
         gitignore?: boolean;
     }): Promise<void>;
-    describe(options: {
-        config?: string[];
-        basedir?: string;
+    describe(options: ProjectOptions & {
         embed?: boolean;
         compress?: CompressLevel;
         format?: DescribeFormat;

package/dst/specbook-api.js

@@ -8,17 +8,19 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { glob } from "glob";
 import { loadConfig, configStatistics } from "./specbook-config.js";
+import { loadProject, projectFile } from "./specbook-project.js";
 import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
 import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
-import { exportSpecification, watchSpecification, parseOutputSpec, formats, requireBrowser } from "./specbook-cmd-export.js";
+import { exportSpecification, watchSpecification, parseOutputSpec, formats, requireBrowser, parseOmit, omitAspects } from "./specbook-cmd-export.js";
 import { servePreview, previewAddr, previewPort } from "./specbook-cmd-preview.js";
 import { describeFormat, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, compressLevels, parseCompressLevel } from "./specbook-cmd-describe.js";
 import { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity } from "./specbook-verbose.js";
 /*  re-export the central types for API consumers  */
 export { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity };
-export { formats, parseOutputSpec };
+export { formats, parseOutputSpec, omitAspects };
 export { previewAddr, previewPort };
+export { projectFile };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
 export { compressLevels, parseCompressLevel };
 export { renderDiagnostic, renderDiagnosticVerbose };
@@ -39,6 +41,35 @@ export class SpecBook {
     verboseOf(cmd) {
         return (msg, level = "notice") => this.verbose(cmd, msg, level);
     }
+    /*  determine the effective project options: a given option wins over
+        its environment variable (SPECBOOK_CONFIG, a path-delimiter-separated
+        list of patterns, and SPECBOOK_BASEDIR), which in turn wins over
+        its entry in the project configuration file. A given working
+        directory anchors the given relative paths and keeps all paths
+        absolute, else the project ones are rendered relative to ours  */
+    project(options, verbose) {
+        const cwd = path.resolve(options.cwd ?? ".");
+        const project = loadProject(cwd);
+        if (project !== undefined)
+            verbose(`using project configuration "${literal(project.file)}"`);
+        const env = (name) => {
+            const value = process.env[name];
+            return value !== undefined && value !== "" ? value : undefined;
+        };
+        const config = options.config !== undefined && options.config.length > 0 ? options.config :
+            env("SPECBOOK_CONFIG")?.split(path.delimiter).filter((pattern) => pattern !== "");
+        const basedir = options.basedir ?? env("SPECBOOK_BASEDIR");
+        const given = (value) => options.cwd !== undefined ? path.resolve(cwd, value) : value;
+        const derived = (value) => options.cwd !== undefined ? value : path.relative(cwd, value) || ".";
+        return {
+            config: config !== undefined && config.length > 0 ?
+                config.map((pattern) => pattern === "std" ? pattern : given(pattern)) :
+                project?.config?.map((pattern) => pattern === "std" ? pattern : derived(pattern)),
+            basedir: basedir !== undefined ? given(basedir) :
+                project?.basedir !== undefined ? derived(project.basedir) :
+                    options.cwd !== undefined ? cwd : undefined
+        };
+    }
     /*  determine the files of the YAML schema configuration out of the
         glob patterns, in the order of the patterns and alphabetically
         within a pattern, where the literal "std" names the bundled
@@ -78,23 +109,27 @@ export class SpecBook {
         below the base directory  */
     async init(options) {
         const verbose = this.verboseOf("init");
-        return initSpecification({ config: this.requireConfig(await this.configFiles(options.config), verbose),
-            basedir: options.basedir ?? ".", verbose });
+        const project = this.project(options, verbose);
+        return initSpecification({ config: this.requireConfig(await this.configFiles(project.config), verbose),
+            basedir: project.basedir ?? ".", verbose });
     }
     /*  lint the specification Markdown files below the base directory,
         where "gitignore" treats an artifact file Git excludes from its
         project exactly like an absent one  */
     async lint(options) {
-        return lint({ config: await this.configFiles(options.config),
-            basedir: options.basedir ?? ".", gitignore: options.gitignore === true,
-            verbose: this.verboseOf("lint") });
+        const verbose = this.verboseOf("lint");
+        const project = this.project(options, verbose);
+        return lint({ config: await this.configFiles(project.config),
+            basedir: project.basedir ?? ".", gitignore: options.gitignore === true, verbose });
     }
     /*  render an already parsed specification into the requested formats
         (strict: any error diagnostic prevents the export, as a partial or
         invalid specification must never be emitted, while the warnings
-        are just surfaced as notices), where "realtime" injects the
-        client-side script of the live preview into the HTML  */
-    async renderFormats(result, requested, verbose, realtime) {
+        are just surfaced as notices), where "rendering" carries the
+        rendering options (the live preview script, the omitted aspects)
+        and "rebase" names, per requested format, the directory the image
+        references of the normalized Markdown are re-based onto  */
+    async renderFormats(result, requested, verbose, rendering, rebase) {
         if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
             throw new Error("invalid specification:\n" +
                 result.diagnostics.map(renderDiagnostic).join("\n"));
@@ -103,24 +138,38 @@ export class SpecBook {
         if (result.specification.artifacts.length === 0)
             throw new Error("unexportable specification: no artifacts found");
         const buffers = new Array();
-        for (const format of requested)
-            buffers.push(await exportSpecification(result.specification, format, verbose, result.config, realtime));
+        for (const [i, format] of requested.entries()) {
+            const dir = rebase?.[i];
+            buffers.push(await exportSpecification(result.specification, format, verbose, result.config, rendering, dir !== undefined ? { origins: result.origins, dir } : undefined));
+        }
         return buffers;
     }
     /*  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  */
+        requested format, where "rebase" names, per requested format, the
+        directory of the output file, onto which the image references of
+        the normalized Markdown are re-based (an absent one keeps them),
+        and "omit" names the (comma-separated) aspects the HTML, the PDF,
+        and (the diagrams) the AST leave out (see "omitAspects")  */
     async export(options) {
         const verbose = this.verboseOf("export");
         const requested = options.formats ?? ["json"];
+        const omit = parseOmit(options.omit);
+        const project = this.project(options, verbose);
         /*  a missing browser is an environment problem, so let the PDF
             export fail before the specification is even parsed  */
         if (requested.includes("pdf"))
             await requireBrowser(verbose);
-        const result = lint({ config: await this.configFiles(options.config),
-            basedir: options.basedir ?? ".", gitignore: options.gitignore === true, verbose });
-        return this.renderFormats(result, requested, verbose, options.realtime === true);
+        const result = lint({ config: await this.configFiles(project.config),
+            basedir: project.basedir ?? ".", gitignore: options.gitignore === true, verbose });
+        return this.renderFormats(result, requested, verbose, { realtime: options.realtime === true, omit }, this.rebaseOf(options));
+    }
+    /*  anchor the given relative re-basing directories
+        at a given working directory  */
+    rebaseOf(options) {
+        const cwd = options.cwd;
+        return cwd === undefined ? options.rebase : options.rebase?.map((dir) => dir !== undefined ? path.resolve(cwd, dir) : dir);
     }
     /*  keep an export in sync with its sources (the shared core of
         "watch" and "preview"): every change of a configuration file, of an
@@ -132,24 +181,26 @@ export class SpecBook {
         once the initial export is done, while the active watcher keeps the
         process alive afterwards  */
     async observe(options, verbose) {
-        const config = await this.configFiles(options.config);
+        const omit = parseOmit(options.omit);
+        const project = this.project(options, verbose);
+        const config = await this.configFiles(project.config);
         return watchSpecification(async () => {
             /*  the lint result carries the files to observe even for an
                 invalid specification, and the configuration files are
                 observed, too, so a failing export (even one due to an
                 invalid configuration) still keeps the observe loop fed  */
-            const result = lint({ config, basedir: options.basedir ?? ".",
+            const result = lint({ config, basedir: project.basedir ?? ".",
                 gitignore: options.gitignore === true, verbose });
             const files = [...config.map((file) => path.resolve(file)), ...result.files];
             /*  an output which is itself an observed source would re-trigger
                 the observation with its own write and hence feed an endless
                 re-export loop, so refuse it before it is ever written  */
-            const collision = options.outputs?.find((output) => files.includes(path.resolve(output)));
+            const collision = options.outputs?.find((output) => files.includes(path.resolve(options.cwd ?? ".", output)));
             if (collision !== undefined)
                 throw new Error(`the output "${collision}" is an observed source file, ` +
                     "which would re-trigger the observation endlessly");
             try {
-                await options.onExport(await this.renderFormats(result, options.formats, verbose, options.realtime));
+                await options.onExport(await this.renderFormats(result, options.formats, verbose, { realtime: options.realtime, omit }, this.rebaseOf(options)));
             }
             catch (err) {
                 verbose("export failed: " +
@@ -161,7 +212,7 @@ export class SpecBook {
     /*  export the specification like "export" and then keep the export
         in sync with its sources (see "observe"), where "outputs" names the
         files "onExport" writes, so an output which is itself an observed
-        source can be refused  */
+        source can be refused, and "rebase" and "omit" are the ones of "export"  */
     async watch(options) {
         const verbose = this.verboseOf("export");
         const requested = options.formats ?? ["json"];
@@ -174,13 +225,14 @@ export class SpecBook {
         "http://<addr>:<port>/": the export is kept in sync with its
         sources (see "observe") and every fresh export is pushed to the
         connected browsers as an in-place document update, through the
-        client-side script the "realtime" export injects into the HTML  */
+        client-side script the "realtime" export injects into the HTML,
+        where "omit" is the one of "export"  */
     async preview(options) {
         const verbose = this.verboseOf("preview");
         const server = await servePreview({ addr: options.addr ?? previewAddr,
             port: options.port ?? previewPort, verbose });
-        return this.observe({ config: options.config, basedir: options.basedir,
-            formats: ["html"], realtime: true, gitignore: options.gitignore,
+        return this.observe({ config: options.config, basedir: options.basedir, cwd: options.cwd,
+            formats: ["html"], realtime: true, omit: options.omit, gitignore: options.gitignore,
             onExport: ([html]) => server.update(html) }, verbose);
     }
     /*  describe the generic SpecBook models and formats as Markdown (or
@@ -192,14 +244,15 @@ export class SpecBook {
         const verbose = this.verboseOf("describe");
         const format = options.format ?? "md";
         const part = options.part ?? "all";
+        const project = this.project(options, verbose);
         /*  the schema-bearing parts require a schema configuration, so
             they fall back onto the bundled standard one, which is always
             embedded, as its bundled file is no meaningful reference  */
-        const given = options.config !== undefined && options.config.length > 0;
+        const given = project.config !== undefined;
         const standard = !given && (part === "all" || part === "schema");
-        const config = given || standard ? await this.configFiles(options.config) : undefined;
+        const config = given || standard ? await this.configFiles(project.config) : undefined;
         const embed = options.embed === true || standard;
-        const basedir = options.basedir ?? (part === "spec" ? "." : undefined);
+        const basedir = project.basedir ?? (part === "spec" ? "." : undefined);
         const schema = config !== undefined ? this.requireConfig(config, verbose) : undefined;
         verbose(`describing the "${literal(part)}" part of the SpecBook models and formats ` +
             `in the "${literal(format)}" format`);

package/dst/specbook-cli.js

@@ -8,7 +8,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { Command, CommanderError } from "commander";
 import chalk from "chalk";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, previewAddr, previewPort, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, parseCompressLevel, parseVerbosity, verbosityOf, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, previewAddr, previewPort, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, parseCompressLevel, parseVerbosity, verbosityOf, projectFile, omitAspects, version } 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, and qualify every message with
@@ -69,17 +69,23 @@ const withVerboseOption = (command) => command
     "3: also the traces like the unreferenced objects; default: 0, bare flag: 1)", envDefault("verbose", "0"));
 /*  provide the repeatable schema configuration option, whose files or
     glob patterns are merged in order (with "std" naming the bundled
-    standard one), and determine its value, where the environment default
-    carries a path-delimiter-separated list of patterns  */
+    standard one), and determine its value, where an absent one is left
+    to the API, which resolves it through the environment variable
+    SPECBOOK_CONFIG and the project configuration file  */
 const withConfigOption = (command, fallback) => command
     .option("-c, --config <yaml-file>", "YAML schema configuration file or glob pattern " +
     "(repeatable, merged in order, \"std\" for the bundled standard schema configuration; " +
-    `default: ${fallback})`, (value, previous) => previous.concat(value), new Array());
-const configOf = (opts) => opts.config.length > 0 ? opts.config : envDefault("config")?.split(path.delimiter);
+    `default: SPECBOOK_CONFIG, else the "config" entry of "${projectFile}", else ${fallback})`, (value, previous) => previous.concat(value), new Array());
+const configOf = (opts) => opts.config.length > 0 ? opts.config : undefined;
+/*  provide the base directory option, where an absent one is left to
+    the API, which resolves it through the environment variable
+    SPECBOOK_BASEDIR and the project configuration file  */
+const withBasedirOption = (command, fallback) => command
+    .option("-b, --basedir <directory>", "base directory of the specification Markdown files " +
+    `(default: SPECBOOK_BASEDIR, else the "basedir" entry of "${projectFile}", else ${fallback})`);
 /*  provide the common options of the specification processing sub-commands,
     for which the YAML schema configuration falls back onto the standard one  */
-const withCommonOptions = (command) => withConfigOption(withVerboseOption(command), "the bundled standard schema configuration")
-    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."));
+const withCommonOptions = (command) => withBasedirOption(withConfigOption(withVerboseOption(command), "the bundled standard schema configuration"), "\".\"");
 /*  provide the Git exclude option of the specification *reading*
     sub-commands (not of "init", which creates artifact files instead of
     reading them), which treats an artifact file Git excludes from its
@@ -87,6 +93,16 @@ const withCommonOptions = (command) => withConfigOption(withVerboseOption(comman
 const withGitignoreOption = (command) => command
     .option("-g, --gitignore", "skip the artifact files excluded by the Git exclude rules " +
     "(the \".gitignore\" files, \"info/exclude\", and the global excludes file)", envDefaultFlag("gitignore", false));
+/*  provide the repeatable omit option of the HTML-rendering sub-commands,
+    whose aspects are left out of the output instead of being foldable,
+    and determine its value (validated by the API)  */
+const withOmitOption = (command) => command
+    .option("-O, --omit <aspect>[,...]", "omit content aspects from the HTML, the PDF, and (the " +
+    `diagrams) the AST outputs (repeatable): "diagram" (all) or "${omitAspects.join("\", \"")}"`, (value, previous) => previous.concat(value), new Array());
+const omitOf = (opts) => {
+    const fallback = envDefault("omit");
+    return opts.omit.length > 0 ? opts.omit : (fallback !== undefined ? [fallback] : undefined);
+};
 /*  the help, version, and usage-error output Commander produces, which
     is collected instead of written directly, as Commander writes it
     synchronously and then terminates the process, truncating a piped
@@ -131,8 +147,9 @@ withGitignoreOption(withCommonOptions(program.command("lint")))
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const result = await specbook.lint({ config: configOf(opts), basedir: opts.basedir,
         gitignore: opts.gitignore });
+    const detailed = parseVerbosity(opts.verbose) > 0;
     for (const diagnostic of result.diagnostics)
-        await writeStdout(parseVerbosity(opts.verbose) > 0 ?
+        await writeStdout(detailed ?
             renderDiagnosticVerbose(diagnostic, process.stdout.isTTY === true) :
             `${renderDiagnostic(diagnostic)}\n`);
     if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
@@ -141,37 +158,48 @@ withGitignoreOption(withCommonOptions(program.command("lint")))
         verboseOf(opts)("lint", "specification valid", "notice");
 });
 /*  the export command parses the input once and writes every output  */
-withGitignoreOption(withCommonOptions(program.command("export")))
+withOmitOption(withGitignoreOption(withCommonOptions(program.command("export"))))
     .description("export the specification Markdown files below the base directory " +
     "as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown")
     .option("-w, --watch", "keep the outputs in sync by re-exporting on every source change", envDefaultFlag("watch", false))
     .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), new Array())
     .action(async (opts) => {
-    const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const outputs = (opts.output.length > 0 ? opts.output : [envDefault("output") ?? "-"])
-        .map(parseOutputSpec);
+    const verbose = verboseOf(opts);
+    const specbook = new SpecBook({ verbose });
+    const fallback = envDefault("output");
+    const given = opts.output.length > 0 ? opts.output : (fallback !== undefined ? [fallback] : []);
+    if (given.length === 0)
+        throw new Error("the export requires at least one output " +
+            "(use option \"-o [<format>:]<output-file>\", with \"-\" for stdout)");
+    const outputs = given.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 && 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)));
+    /*  parse the input once and export each distinct format once, the
+        normalized Markdown once per output directory, as its image
+        references are re-based onto it (but never for stdout)  */
+    const rebaseOf = ({ format, output }) => format === "md" && output !== "-" ? path.dirname(path.resolve(output)) : undefined;
+    const keyOf = (spec) => `${spec.format}:${rebaseOf(spec) ?? ""}`;
+    const distinct = outputs.filter((spec, i) => outputs.findIndex((other) => keyOf(other) === keyOf(spec)) === i);
     const write = async (buffers) => {
-        for (const { format, output } of outputs)
-            await writeOutput(output, buffers[distinct.indexOf(format)], "export", verboseOf(opts));
+        for (const spec of outputs)
+            await writeOutput(spec.output, buffers[distinct.findIndex((other) => keyOf(other) === keyOf(spec))], "export", verbose);
     };
+    const formats = distinct.map(({ format }) => format);
+    const rebase = distinct.map(rebaseOf);
     if (opts.watch)
         await specbook.watch({ config: configOf(opts), basedir: opts.basedir,
-            formats: distinct, gitignore: opts.gitignore,
+            formats, rebase, omit: omitOf(opts), gitignore: opts.gitignore,
             outputs: outputs.map(({ output }) => output), onExport: write });
     else
         await write(await specbook.export({ config: configOf(opts), basedir: opts.basedir,
-            formats: distinct, gitignore: opts.gitignore }));
+            formats, rebase, omit: omitOf(opts), gitignore: opts.gitignore }));
 });
 /*  the preview command serves the HTML export live in the browser  */
-withGitignoreOption(withCommonOptions(program.command("preview")))
+withOmitOption(withGitignoreOption(withCommonOptions(program.command("preview"))))
     .description("serve the HTML export of the specification Markdown files below the base " +
     "directory as a live preview, re-exported and reloaded on every source change")
     .option("-a, --addr <ip-addr>", "IP address to listen on", envDefault("addr", previewAddr))
@@ -182,17 +210,16 @@ withGitignoreOption(withCommonOptions(program.command("preview")))
         throw new Error(`invalid TCP port "${opts.port}"`);
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     await specbook.preview({ config: configOf(opts), basedir: opts.basedir, addr: opts.addr, port,
-        gitignore: opts.gitignore });
+        omit: omitOf(opts), gitignore: opts.gitignore });
 });
 /*  the describe command also describes the generic SpecBook models and
     formats alone, so its YAML schema configuration stays optional  */
-withConfigOption(withVerboseOption(program.command("describe")), "the bundled standard schema configuration, embedded")
+withBasedirOption(withConfigOption(withVerboseOption(program.command("describe")), "the bundled standard schema configuration, embedded"), "none")
     .description("describe the SpecBook models and formats as Markdown")
-    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir"))
     .option("-e, --embed", "embed the given YAML schema configuration instead of just referencing it", envDefaultFlag("embed", false))
     .option("-z, --compress [level]", "compression level of the emitted YAML schema configuration " +
     "(0: verbatim, 1: re-emitted with 2-space indentation and without comments, " +
-    "2: also without \"refs\" fields, " +
+    "2: also without \"refs\", \"diagram\", and \"format\" fields, " +
     "3: also without \"desc\" fields; default and bare flag: 1)", envDefault("compress", "1"))
     .option("-f, --format <format>", `output format (${describeFormats.join(", ")})`, envDefault("format", "md"))
     .option("-p, --part <part>", `document part (${describeParts.join(", ")})`, envDefault("part", "all"))