@rse/specbook 1.0.0 → 1.0.2

package/README.md

@@ -22,63 +22,63 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 
 **SpecBook** provides the following distinct features:
 
-- **Hierarchical Object Model**:
-  A specification is a tree of typed objects, each with a kind and
-  name, an optional id, optional properties, optional description, and
-  optional child objects. The allowed object hierarchy is defined per
-  context by the YAML schema configuration.
-
-- **Versatile Object to Markdown Mapping**:
-  Objects are authored as plain Markdown headings, property lists,
-  and description prose. The objects can be mapped to nested sections
-  ("complex" format) or compact bullet point lists ("concise" and
-  "group" format).
-
-- **Wiki-Style Object Linking**:
-  Objects can hierarchically reference each other through Wiki-style
-  `[[xxx]]` references, which are resolved against the locally-unique
-  ids and names of all objects. In the HTML and PDF exports they become
-  navigable links onto precise anchors.
-
-- **Strict Validation with Custom Schema**:
-  The YAML schema configuration strictly defines the allowed object
-  kinds, hierarchies, and properties, whose values are constrained by an
-  expression language (regex, enum, tags, list, and reference). Violations
-  are reported as file- and line-precise diagnostics. A bundled standard
-  schema configuration applies if no particular one is given.
-
-- **Object Model Diagram Visualisation**:
-  Object kinds can declare "graph", "hub", or "grid" diagrams in the
-  schema, whose nodes and edges are automatically derived from the
-  object model and its references. The diagrams are rendered with the
-  sibling project [Gradia](https://github.com/rse/gradia), which is
-  specialized in rendering object models.
-
-- **CLI, MCP, and API Interface**:
-  All commands are implemented once in the API class `SpecBook`, on
-  which both the CLI and the MCP service are just thin wrappers.
-  This way, humans, scripts, and AI agents use exactly the same
-  functionality.
-
-- **AST Exports for AI/LLMs**:
-  The parsed specification Abstract Syntax Tree (AST) can be exported in
-  JSON, JSON5, YAML, or TOON format for machine consumption. Together
-  with the `describe` command, which explains the models and formats,
-  this enables LLMs to both read and write specifications.
-
-- **HTML Export for Developers**:
-  The HTML export is a self-contained single document with a
-  table-of-contents, full-text search, embedded images, and a light/dark
-  theme toggle. It is intended for the day-to-day online reading during
-  development. The HTML export can map all object kinds to nested
-  sections or compact tables, or an automatic mixture which collapses
-  only the deepest level into tables.
-
-- **PDF Export for Customers**:
-  The PDF export prints the HTML rendering via Chromium and post-processes
-  it with page numbers, headers/footers, and a hierarchical PDF outline.
-  It is intended as a polished, paginated offline document for handing
-  over to customers.
+-   **Hierarchical Object Model**:
+    A specification is a tree of typed objects, each with a kind and
+    name, an optional id, optional properties, optional description, and
+    optional child objects. The allowed object hierarchy is defined per
+    context by the YAML schema configuration.
+
+-   **Versatile Object to Markdown Mapping**:
+    Objects are authored as plain Markdown headings, property lists,
+    and description prose. The objects can be mapped to nested sections
+    ("complex" format) or compact bullet point lists ("concise" and
+    "group" format).
+
+-   **Wiki-Style Object Linking**:
+    Objects can hierarchically reference each other through Wiki-style
+    `[[xxx]]` references, which are resolved against the locally-unique
+    ids and names of all objects. In the HTML and PDF exports they become
+    navigable links onto precise anchors.
+
+-   **Strict Validation with Custom Schema**:
+    The YAML schema configuration strictly defines the allowed object
+    kinds, hierarchies, and properties, whose values are constrained by an
+    expression language (regex, enum, tags, list, and reference). Violations
+    are reported as file- and line-precise diagnostics. A bundled standard
+    schema configuration applies if no particular one is given.
+
+-   **Object Model Diagram Visualisation**:
+    Object kinds can declare "graph", "hub", or "grid" diagrams in the
+    schema, whose nodes and edges are automatically derived from the
+    object model and its references. The diagrams are rendered with the
+    sibling project [Gradia](https://github.com/rse/gradia), which is
+    specialized in rendering object models.
+
+-   **CLI, MCP, and API Interface**:
+    All commands are implemented once in the API class `SpecBook`, on
+    which both the CLI and the MCP service are just thin wrappers.
+    This way, humans, scripts, and AI agents use exactly the same
+    functionality.
+
+-   **AST Exports for AI/LLMs**:
+    The parsed specification Abstract Syntax Tree (AST) can be exported in
+    JSON, JSON5, YAML, or TOON format for machine consumption. Together
+    with the `describe` command, which explains the models and formats,
+    this enables LLMs to both read and write specifications.
+
+-   **HTML Export for Developers**:
+    The HTML export is a self-contained single document with a
+    table-of-contents, full-text search, embedded images, and a light/dark
+    theme toggle. It is intended for the day-to-day online reading during
+    development. The HTML export can map all object kinds to nested
+    sections or compact tables, or an automatic mixture which collapses
+    only the deepest level into tables.
+
+-   **PDF Export for Customers**:
+    The PDF export prints the HTML rendering via Chromium and post-processes
+    it with page numbers, headers/footers, and a hierarchical PDF outline.
+    It is intended as a polished, paginated offline document for handing
+    over to customers.
 
 Overview
 --------
@@ -97,73 +97,235 @@ $ npm install -g @rse/specbook
 Usage
 -----
 
-### CLI
+### API
 
-```bash
-$ specbook init     [-v] [-c <yaml-file>] [-b <basedir>]
-$ specbook lint     [-v] [-c <yaml-file>] [-b <basedir>]
-$ specbook export   [-v] [-c <yaml-file>] [-b <basedir>] [-o [<format>:]<output-file>] [...]
-$ specbook describe [-v] [-c <yaml-file>] [-b <basedir>] [-e] [-o <markdown-file>]
-$ specbook mcp      [-v]
+```ts
+/*  the SpecBook API, providing all commands the CLI and MCP service expose  */
+export class SpecBook {
+    constructor (options?: SpecBookOptions)
+
+    /*  initialize the configured specification artifact files below the
+        base directory and return the list of the generated files  */
+    init (options: {
+        config?:  string,          /*  YAML schema configuration (default: bundled standard one)  */
+        basedir?: string           /*  base directory (default: ".")  */
+    }): Promise<string[]>
+
+    /*  parse and validate the specification Markdown files below the base directory  */
+    lint (options: {
+        config?:  string,
+        basedir?: string
+    }): Promise<LintResult>
+
+    /*  export the specification, parsing the input just once and
+        returning one buffer per requested format (strict: any diagnostic
+        rejects the export with an "Error")  */
+    export (options: {
+        config?:  string,
+        basedir?: string,
+        formats?: ExportFormat[]   /*  requested output formats (default: [ "json" ])  */
+    }): Promise<Buffer[]>
+
+    /*  describe the SpecBook models and formats, optionally pointing to
+        the artifacts of the particular project  */
+    describe (options: {
+        config?:  string,
+        basedir?: string,
+        embed?:   boolean,         /*  embed the schema configuration instead of referencing it  */
+        format?:  DescribeFormat,  /*  output format (default: "md")  */
+        part?:    DescribePart     /*  document part (default: "all")  */
+    }): Promise<string>
+}
+
+/*  the constructor options and the sink of the verbose messages,
+    receiving the emitting command and the message  */
+export interface SpecBookOptions {
+    verbose?:      VerboseSink
+}
+export type VerboseSink = (cmd: string, msg: string) => void
+
+/*  the result of the "lint" command and its file- and line-precise diagnostics  */
+export interface LintResult {
+    specification: Spec
+    diagnostics:   Diagnostic[]
+    config?:       Schema
+}
+export interface Diagnostic {
+    file:          string
+    line:          number
+    column:        number
+    message:       string
+}
+
+/*  the supported export formats and describe formats/parts  */
+export const formats:         readonly [ "json", "json5", "yaml", "toon", "html", "pdf", "md" ]
+export const describeFormats: readonly [ "md", "raw" ]
+export const describeParts:   readonly [ "all", "meta", "schema", "spec" ]
+export type  ExportFormat   = typeof formats[number]
+export type  DescribeFormat = typeof describeFormats[number]
+export type  DescribePart   = typeof describeParts[number]
+
+/*  the Abstract Syntax Tree (AST) of a parsed specification  */
+export type Spec = {
+    artifacts:     SpecArtifact[]
+}
+export type SpecArtifact = {
+    created:       Date
+    modified:      Date
+    objects:       SpecObject[]
+}
+export type SpecObject = {
+    kind:          string
+    id:            string
+    anchor?:       string
+    paren?:        string
+    name:          string
+    primary?:      boolean
+    description?:  SpecDescription
+    properties:    SpecProperty[]
+    childs:        SpecObject[]
+}
+export type SpecDescription = {
+    description:   string
+    rationale?:    string
+    embedding?:    string[]
+}
+export type SpecProperty = {
+    key:           string
+    value:         string
+    embedding?:    string[]
+}
+
+/*  the YAML schema configuration, where the nested "diagram" and
+    "format" structures are detailed in the "describe" output  */
+export type Schema = SchemaObject[]
+export type SchemaObject = {
+    kind:          string
+    name?:         string
+    id?:           string
+    file?:         string
+    desc?:         string
+    optional?:     boolean
+    diagram?:      SchemaDiagram
+    format?:       SchemaFormat
+    props?:        SchemaProperty[]
+    childs?:       SchemaObject[]
+}
+export type SchemaProperty = {
+    name:          string
+    desc?:         string
+    value?:        string
+    optional?:     boolean
+}
 ```
 
-The YAML schema configuration `-c`/`--config` (default: 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 artifacts are
-`optional`, and so is an artifact absent from its present file, unless
-it is `optional` itself. Both `lint` and `export` report all
-diagnostics and fail on any of them, so a partial or invalid
-specification is never exported.
-
-The base directory `-b`/`--basedir` (default: `.`) is the directory the
-referenced artifact files are resolved against, and generated
-specification Markdown files are placed inside it, too.
-
-The export output option `-o`/`--output` (default: `-` for stdout) can
-occur multiple times. The format (`json`, `json5`, `yaml`, `toon`,
-`html`, `pdf`, or `md`) is inferred from the filename extension, unless
-it is explicitly given as a `<format>:` prefix, and plain `-` (stdout)
-defaults to JSON.
-
-The `md` format normalizes the entire corpus into a *single* Markdown
-document, whose single frontmatter block carries the earliest `Created:`
-and the latest `Modified:` timestamp of all artifacts, so the
-per-artifact timestamps do not survive this round-trip.
-
-The `describe` command outputs the description of the SpecBook models
-and formats. If the configuration file `-c`/`--config` or the base
-directory `-b`/`--basedir` is given, it additionally appends a *SpecBook
-Project Instantiation* section which points to these artifacts of the
-particular project. With `-e`/`--embed` the YAML schema configuration is
-embedded verbatim instead of just being referenced, so the resulting
-document describes the specification format of the project entirely on
-its own.
-
-The default value of every CLI option `--xxx` can be overridden by a
-corresponding `SPECBOOK_XXX` environment variable (e.g.
-`SPECBOOK_BASEDIR`, `SPECBOOK_CONFIG`, `SPECBOOK_OUTPUT`,
-`SPECBOOK_VERBOSE`), while an explicitly supplied option always wins.
-
-### API
+Example:
 
 ```ts
-import { SpecBook, renderVerbose } from "@rse/specbook"
+import { SpecBook } from "@rse/specbook"
 
 const specbook = new SpecBook({
-    verbose: (cmd, msg) => console.error(`specbook: ${cmd}: ${renderVerbose(msg)}`)
+    verbose: (cmd, msg) => console.error(`specbook: ${cmd}: ${msg}`)
 })
 const result = await specbook.lint({
     basedir: "smp/broadcast"
 })
 ```
 
-### MCP
+### CLI
+
+Commands:
 
-Run `specbook mcp` to serve the tools `specbook_init`, `specbook_lint`,
-`specbook_export`, and `specbook_describe` over stdio.
+```bash
+$ specbook init \
+  [-v|--verbose] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>]
+
+$ specbook lint \
+  [-v|--verbose] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>]
+
+$ specbook export \
+  [-v|--verbose] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>] \
+  [-o|--output [<format>:]<output-file>] [...]
+
+$ specbook describe \
+  [-v|--verbose] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>] \
+  [-e|--embed] \
+  [-f|--format <format>] \
+  [-p|--part <part>] \
+  [-o|--output <output-file>]
+
+$ specbook mcp \
+  [-v|--verbose]
+```
+
+Options:
+
+-   `-v|--verbose`:
+    Enable verbose logging of processing information to `stderr`.
+
+-   `-c|--config <schema-yaml-file>`:
+    The YAML schema configuration (default: 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
+    artifacts are `optional`, and so is an artifact absent from its present
+    file, unless it is `optional` itself. Both `lint` and `export` report
+    all diagnostics and fail on any of them, so a partial or invalid
+    specification is never exported.
+
+-   `-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.
+
+-   `-o|--output [<format>:]<output-file>` (`export` only):
+    The output file (default: `-` for stdout) 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.
+    The `md` export format normalizes the entire corpus into a *single*
+    Markdown document.
+
+-   `-o|--output <output-file>` (`describe` only):
+    The output file (default: `-` for stdout) receives the described
+    Markdown document.
+
+-   `-e|--embed` (`describe` only):
+    Embed the given YAML schema configuration verbatim instead of just
+    referencing it, so the resulting document describes the specification
+    format entirely on its own.
+
+-   `-f|--format <format>` (`describe` only):
+    The output format (default: `md`) switches from the rendered Markdown
+    onto the raw original file content with `raw`, which is available for
+    the file-backed parts `meta` and `schema` only.
+
+-   `-p|--part <part>` (`describe` only):
+    The document part (default: `all`) reduces the output to a single part:
+    `meta` for the description of the generic SpecBook models and formats,
+    `schema` for the YAML schema configuration (the given one, referenced
+    or embedded with `-e|--embed`, else the bundled standard one,
+    embedded), or `spec` for the reference to the base directory.
+
+The default value of every CLI option `--xxx` can be overridden
+by a corresponding `SPECBOOK_XXX` environment variable (e.g.
+`SPECBOOK_BASEDIR`, `SPECBOOK_CONFIG`, `SPECBOOK_OUTPUT`,
+`SPECBOOK_VERBOSE`), while an explicitly supplied option always wins.
+
+Example:
+
+```bash
+$ specbook lint -v -b smp/broadcast
+```
 
 Rendering Examples
 ------------------

package/dst/specbook-api.d.ts

@@ -1,9 +1,12 @@
 import { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic } from "./specbook-diagnostic.js";
 import { type LintResult } from "./specbook-cmd-lint.js";
 import { parseOutputSpec, formats, type ExportFormat } from "./specbook-cmd-export.js";
+import { describeFormats, describeParts, parseDescribeFormat, parseDescribePart, type DescribeFormat, type DescribePart } from "./specbook-cmd-describe.js";
 import { literal, renderVerbose } from "./specbook-verbose.js";
 export { literal, renderVerbose };
 export { formats, parseOutputSpec, type ExportFormat };
+export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
+export { type DescribeFormat, type DescribePart };
 export { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic };
 export { type LintResult };
 export type { Spec, SpecArtifact, SpecObject, SpecDescription, SpecProperty } from "./specbook-format-spec.js";
@@ -37,5 +40,7 @@ export declare class SpecBook {
         config?: string;
         basedir?: string;
         embed?: boolean;
+        format?: DescribeFormat;
+        part?: DescribePart;
     }): Promise<string>;
 }

package/dst/specbook-api.js

@@ -10,11 +10,12 @@ import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic
 import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
 import { exportSpecification, parseOutputSpec, formats } from "./specbook-cmd-export.js";
-import { describeFormat } from "./specbook-cmd-describe.js";
+import { describeFormat, describeFormats, describeParts, parseDescribeFormat, parseDescribePart } from "./specbook-cmd-describe.js";
 import { literal, renderVerbose } from "./specbook-verbose.js";
 /*  re-export the central types for API consumers  */
 export { literal, renderVerbose };
 export { formats, parseOutputSpec };
+export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
 export { renderDiagnostic, renderDiagnosticVerbose };
 /*  our own version, taken from the package manifest, which resides one
     level above both the source and the compiled module directory  */
@@ -79,16 +80,27 @@ export class SpecBook {
             buffers.push(await exportSpecification(result.specification, format, verbose, result.config));
         return buffers;
     }
-    /*  describe the generic SpecBook models and formats as Markdown,
-        optionally pointing to the artifacts of the particular project,
-        whose YAML schema configuration is validated if given  */
+    /*  describe the generic SpecBook models and formats as Markdown (or
+        as the raw original file content), either entirely or reduced to
+        a single part, optionally pointing to the artifacts of the
+        particular project, whose YAML schema configuration is validated
+        before use  */
     async describe(options) {
         const verbose = this.verboseOf("describe");
-        if (options.config !== undefined)
-            this.requireConfig(options.config, verbose);
-        else if (options.embed === true)
-            throw new Error("YAML schema configuration required for embedding");
-        verbose("describing the SpecBook models and formats");
-        return describeFormat(options);
+        const format = options.format ?? "md";
+        const part = options.part ?? "all";
+        /*  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 standard = options.config === undefined
+            && (part === "all" || part === "schema" || options.embed === true);
+        const config = options.config ?? (standard ? standardConfig : undefined);
+        const embed = options.embed === true || standard;
+        const basedir = options.basedir ?? (part === "spec" ? "." : undefined);
+        if (config !== undefined)
+            this.requireConfig(config, verbose);
+        verbose(`describing the "${literal(part)}" part of the SpecBook models and formats ` +
+            `in the "${literal(format)}" format`);
+        return describeFormat({ ...options, config, basedir, embed, standard, format, part });
     }
 }

package/dst/specbook-cli.js

@@ -7,7 +7,7 @@
 import * as fs from "node:fs";
 import { Command } from "commander";
 import chalk from "chalk";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, 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
@@ -120,13 +120,17 @@ withCommonOptions(program.command("export"))
     formats alone, so its YAML schema configuration stays optional  */
 withVerboseOption(program.command("describe"))
     .description("describe the SpecBook models and formats as Markdown")
-    .option("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"))
+    .option("-c, --config <yaml-file>", "YAML schema configuration file " +
+    "(default: the bundled standard schema configuration, embedded verbatim)", envDefault("config"))
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir"))
-    .option("-e, --embed", "embed the YAML schema configuration instead of just referencing it", envDefaultFlag("embed", false))
+    .option("-e, --embed", "embed the given YAML schema configuration instead of just referencing it", envDefaultFlag("embed", false))
+    .option("-f, --format <format>", `output format (${describeFormats.join(", ")})`, envDefault("format", "md"))
+    .option("-p, --part <part>", `document part (${describeParts.join(", ")})`, envDefault("part", "all"))
     .option("-o, --output <markdown-file>", "output file (\"-\" for stdout)", envDefault("output", "-"))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const text = await specbook.describe({ config: opts.config, basedir: opts.basedir, embed: opts.embed });
+    const text = await specbook.describe({ config: opts.config, basedir: opts.basedir,
+        embed: opts.embed, format: parseDescribeFormat(opts.format), part: parseDescribePart(opts.part) });
     await writeOutput(opts.output, text, "describe", verboseOf(opts));
 });
 /*  run the command line program  */

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

@@ -1,5 +1,14 @@
+export declare const describeFormats: readonly ["md", "raw"];
+export declare const describeParts: readonly ["all", "meta", "schema", "spec"];
+export type DescribeFormat = typeof describeFormats[number];
+export type DescribePart = typeof describeParts[number];
+export declare const parseDescribeFormat: (value: string) => DescribeFormat;
+export declare const parseDescribePart: (value: string) => DescribePart;
 export declare const describeFormat: (options: {
     config?: string;
     basedir?: string;
     embed?: boolean;
+    standard?: boolean;
+    format?: DescribeFormat;
+    part?: DescribePart;
 }) => string;

package/dst/specbook-cmd-describe.js

@@ -5,31 +5,94 @@
 */
 import * as fs from "node:fs";
 import textframe from "textframe";
+/*  the supported description output formats and document parts  */
+export const describeFormats = ["md", "raw"];
+export const describeParts = ["all", "meta", "schema", "spec"];
+/*  parse and validate an output format or document part specification  */
+const parseChoice = (choices, kind, value) => {
+    if (!choices.includes(value))
+        throw new Error(`unknown describe ${kind} "${value}" ` +
+            `(supported: ${choices.join(", ")})`);
+    return value;
+};
+export const parseDescribeFormat = (value) => parseChoice(describeFormats, "format", value);
+export const parseDescribePart = (value) => parseChoice(describeParts, "part", value);
 /*  provide the build-time bundled description of the generic
     SpecBook models and formats  */
 const description = () => fs.readFileSync(new URL("specbook-format.md", import.meta.url), "utf8");
+/*  render the reference to (or the embedding of) the YAML schema configuration,
+    where the bundled standard one is embedded without its leading comment block  */
+const schemaSection = (config, embed, standard) => {
+    if (!embed)
+        return textframe(`
+            The **SpecBook SCHEMA Model** is the YAML schema configuration in file:
+            @${config}
+        `);
+    let yaml = fs.readFileSync(config, "utf8");
+    if (standard)
+        yaml = yaml.replace(/^(?:[ \t]*##.*\n)+\s*/, "");
+    return textframe(`
+        The **SpecBook SCHEMA Model** is the following YAML schema configuration:
+    `) + "\n```yaml\n" + yaml.replace(/\n*$/, "\n") + "```\n\n";
+};
+/*  render the reference to the specification Markdown files  */
+const specSection = (basedir) => textframe(`
+        The **SpecBook SPEC Model** is the set of Markdown specification files in directory:
+        @${basedir}
+    `) + "\n";
 /*  describe the generic SpecBook models and formats as Markdown,
     optionally extended by the references to (or the embeddings of) the
-    artifacts of the particular project instantiation  */
+    artifacts of the particular project instantiation, and optionally
+    reduced to a single part or to the raw original file content, where
+    "standard" marks the configuration as the bundled standard one,
+    which still belongs to the generic description  */
 export const describeFormat = (options) => {
+    const format = options.format ?? "md";
+    const part = options.part ?? "all";
+    if (!describeFormats.includes(format))
+        throw new Error(`unknown describe format "${format}"`);
+    if (!describeParts.includes(part))
+        throw new Error(`unknown describe part "${part}"`);
+    /*  the raw format emits the original file content of a single part,
+        so it is available for the file-backed parts only  */
+    if (format === "raw") {
+        if (part === "all" || part === "spec")
+            throw new Error(`format "raw" is not available for part "${part}", ` +
+                "as this part is not backed by a single original file");
+        else if (part === "meta")
+            return description();
+        else if (options.config === undefined)
+            throw new Error("format \"raw\" for part \"schema\" requires a YAML schema configuration");
+        else
+            return fs.readFileSync(options.config, "utf8");
+    }
+    /*  the md format renders a single part standalone  */
+    if (part === "meta")
+        return description();
+    else if (part === "schema") {
+        if (options.config === undefined)
+            throw new Error("part \"schema\" requires a YAML schema configuration");
+        return schemaSection(options.config, options.embed === true, options.standard === true);
+    }
+    else if (part === "spec") {
+        if (options.basedir === undefined)
+            throw new Error("part \"spec\" requires a base directory");
+        return specSection(options.basedir);
+    }
+    /*  the md format renders all parts as a single coherent document,
+        where the schema configuration and the base directory are the
+        artifacts of the project instantiation and hence are always
+        placed under their own section  */
     const sections = [description()];
-    if (options.config !== undefined || options.basedir !== undefined) {
+    const schema = options.config !== undefined ?
+        schemaSection(options.config, options.embed === true, options.standard === true) : undefined;
+    if (schema !== undefined || options.basedir !== undefined) {
         sections.push("SpecBook Project Instantiation\n" +
             "==============================\n");
-        if (options.config !== undefined && options.embed === true)
-            sections.push(textframe(`
-                The **SpecBook SCHEMA Model** is the following YAML schema configuration:
-            `) + "\n```yaml\n" +
-                fs.readFileSync(options.config, "utf8").replace(/\n*$/, "\n") +
-                "```\n");
-        else if (options.config !== undefined)
-            sections.push(textframe(`
-                The **SpecBook SCHEMA Model** is the YAML schema configuration in file \`${options.config}\`.
-            `));
+        if (schema !== undefined)
+            sections.push(schema);
         if (options.basedir !== undefined)
-            sections.push(textframe(`
-                The **SpecBook SPEC Model** is the set of Markdown specification files in directory \`${options.basedir}\`.
-            `));
+            sections.push(specSection(options.basedir));
     }
     return sections.join("\n");
 };

package/dst/specbook-export-html.js

@@ -249,7 +249,7 @@ const inline = (text) => safe(marked.parseInline(linker !== null ? linker(text)
     constructs (lists, quotes, code blocks, tables) intact  */
 const block = (text) => safe(marked.parse(linker !== null ? linker(text) : text, { async: false }));
 /*  check whether a text carries any block-level Markdown, i.e. is
-    anything else than the single paragraph a description usually is  */
+    anything other than the single paragraph a description usually is  */
 const isBlock = (text) => {
     const tokens = marked.lexer(text).filter((token) => token.type !== "space");
     return tokens.length > 0 && !(tokens.length === 1 && tokens[0].type === "paragraph");

package/dst/specbook-export-md.js

@@ -66,7 +66,7 @@ const renderConciseMd = (object, depth = 0) => {
     level 4 upwards in the Concise Format -- unless a descendant carries
     a description no concise item can carry, so all childs (as siblings
     have to share the format) stay in the Complex Format down to heading
-    level 6 --, and the optionally derived Gradia diagram spec embedded
+    level 6 -- and the optionally derived Gradia diagram spec embedded
     as a "gradia" fenced code block below the heading  */
 const renderObjectMd = (object, level, diagrams) => {
     const heading = `${"#".repeat(level)}${" ".repeat(Math.max(1, 4 - level))}` +

package/dst/specbook-format.md

@@ -19,7 +19,7 @@ SpecBook Models and Formats
 ```
 
 **SpecBook** deals with four distinct object models and their particular
-format, each represented in a formal language and serving a particular
+formats, each represented in a formal language and serving a particular
 task:
 
 -   **SpecBook SCHEMA Meta Model**:

package/dst/specbook-mcp.js

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { SpecBook, renderDiagnostic, formats, parseOutputSpec, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, formats, parseOutputSpec, describeFormats, describeParts, version } from "./specbook-api.js";
 /*  render an error with its cause chain into a tool error result  */
 const errorResult = (err) => {
     let msg = err instanceof Error ? err.message : String(err);
@@ -105,14 +105,23 @@ export const serveMcp = async (verbose) => {
     });
     server.registerTool("specbook_describe", {
         title: "Describe Specification Format",
-        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.",
+        description: "Describe the SpecBook models and formats as a Markdown document, which embeds the " +
+            "bundled standard YAML schema configuration as long as no particular one is given. If the " +
+            "YAML schema configuration or the base directory is given, the description additionally " +
+            "points to the artifacts of that particular project. The description can be reduced to a " +
+            "single part and emitted as the raw original file content instead of Markdown.",
         inputSchema: {
-            config: z.string().optional().describe("YAML schema configuration file"),
+            config: z.string().optional().describe("YAML schema configuration file " +
+                "(default: the bundled standard schema configuration, embedded verbatim)"),
             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)"),
+            embed: z.boolean().optional().describe("embed the given YAML schema configuration instead " +
+                "of just referencing it (default: false; the bundled standard one is always embedded)"),
+            format: z.enum(describeFormats).optional().describe("output format: \"md\" for Markdown or " +
+                "\"raw\" for the raw original file content of the part (default: \"md\")"),
+            part: z.enum(describeParts).optional().describe("document part: \"all\" for the entire " +
+                "description, \"meta\" for the generic models and formats, \"schema\" for the YAML schema " +
+                "configuration, or \"spec\" for the specification files (default: \"all\"; \"raw\" is " +
+                "available for \"meta\" and \"schema\" only)"),
             output: z.string().optional().describe("output file path (\"-\" or omitted returns the description directly)")
         }
     }, async (args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.0.0",
+    "version":                             "1.0.2",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",