@rse/specbook 1.5.2 → 1.6.1

package/README.md

@@ -1,5 +1,6 @@
 
-<img src="https://raw.githubusercontent.com/rse/specbook/master/etc/specbook-logo-blue-light.svg" width="400" align="right" alt=""/>
+<img src="https://raw.githubusercontent.com/rse/specbook/master/etc/specbook-logo-blue-light.svg"
+     width="400" align="right" alt=""/>
 
 SpecBook
 ========
@@ -8,8 +9,13 @@ SpecBook
 
 [specbook.tools](https://specbook.tools)
 
-[![github (author stars)](https://img.shields.io/github/stars/rse?logo=github&label=author%20stars&color=%233377aa)](https://github.com/rse)
-[![github (author followers)](https://img.shields.io/github/followers/rse?label=author%20followers&logo=github&color=%234477aa)](https://github.com/rse)
+[![github (author stars)][badge-stars]](https://github.com/rse)
+[![github (author followers)][badge-followers]](https://github.com/rse)
+
+[badge-stars]:
+    https://img.shields.io/github/stars/rse?logo=github&label=author%20stars&color=%233377aa
+[badge-followers]:
+    https://img.shields.io/github/followers/rse?label=author%20followers&logo=github&color=%234477aa
 
 About
 -----
@@ -19,7 +25,8 @@ format* which can be configured for the specifications of particular
 contexts through a YAML-based *schema configuration*. SpecBook allows
 specifications to be *initialized*, *linted*, *exported* (JSON, JSON5,
 YAML, TOON, HTML, PDF, and normalized Markdown), *previewed* (HTML, live
-in the browser), and *described* to LLMs.
+in the browser), *queried* (ASTq selectors on the AST), and *described*
+to LLMs.
 
 **SpecBook** ships with an API class with methods `<xxx>()`, a
 CLI with commands `specbook <xxx>`, and an MCP service with tools
@@ -29,7 +36,7 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 
 -   **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
+    name, an optional id, optional properties, an optional description, and
     optional child objects. The allowed object hierarchy is defined per
     context by the YAML schema configuration.
 
@@ -41,7 +48,7 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 
 -   **Wiki-Style Object Linking**:
     Objects can hierarchically reference each other through Wiki-style
-    `[[xxx]]` references, which are resolved against the locally-unique
+    `[[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.
 
@@ -58,9 +65,10 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
     demands is reported as a warning only. 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 Diagram Visualization**:
+    Object kinds can declare one or more "graph", "hub", "grid", "state",
+    "layer", "slice", "tree", "matrix", "sequence", "petri", or "gantt" 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.
@@ -84,11 +92,15 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
     a table-of-contents (also as a slide-in side panel for quick navigation),
     a diagram-of-contents, a fuzzy full-text search, embedded images,
     embedded Mermaid and D2 diagrams (inline or as files, in the theme colors),
-    embedded PDF pages,
+    embedded PDF pages, syntax-highlighted code listings (fenced or as
+    files, with line numbers and marked lines),
     reference coverage tables (e.g. the share of the use cases, scenarios,
     requirements, and rules the test cases verify), a
     scroll progress meter (which also scrolls back to the top on click),
     diagram maximization (into the viewport or the fullscreen),
+    folding of the diagrams and over-long table cells, an artifact
+    filter (which shows only the objects the selected artifacts reach
+    through their references),
     description popups (which show the schema and corpus description of
     an object kind, property, or object instance on hover), and a
     light/dark theme toggle. It is intended for the day-to-day online
@@ -108,7 +120,8 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
     The title object of the specification drives the entire document:
     its title, subtitle, author, version, and logo fill the title page
     (with an optional light/dark variant of the logo), its language
-    selects the smart typography quote style, its color tone seeds the
+    selects the smart typography quote style and the translation of the
+    rationale keyword (like `BECAUSE (weil)`), its color tone seeds the
     theme color spreads of both the light and the dark theme, and its
     character set subsets the embedded fonts down to the actually needed
     glyphs.
@@ -138,40 +151,67 @@ Commands:
 $ specbook init \
   [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
-  [-b|--basedir <spec-md-file-basedir>]
+  [-b|--basedir <spec-md-file-basedir>] \
+  [-F|--fetch <mode>] \
+  [-s|--sample]
 
 $ specbook lint \
   [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
-  [-b|--basedir <spec-md-file-basedir>]
+  [-b|--basedir <spec-md-file-basedir>] \
+  [-F|--fetch <mode>] \
+  [-g|--gitignore]
 
 $ specbook export \
   [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
-  [-o|--output [<format>:]<output-file>] \
+  [-F|--fetch <mode>] \
+  [-g|--gitignore] \
+  [-S|--schema] \
+  [-o|--output [<format>:]<output-file>] [...] \
   [-w|--watch] \
-  [-O|--omit <aspect>[,...]] \
-  [...]
+  [-O|--omit <aspect>[,...]]
 
 $ specbook preview \
   [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
+  [-F|--fetch <mode>] \
+  [-g|--gitignore] \
+  [-S|--schema] \
   [-O|--omit <aspect>[,...]] \
   [-a|--addr <ip-addr>] \
   [-p|--port <tcp-port>]
 
+$ specbook query \
+  [-v|--verbose [<level>]] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>] \
+  [-F|--fetch <mode>] \
+  [-g|--gitignore] \
+  [-S|--schema] \
+  [-P|--param <name>=<value>] [...] \
+  [-f|--format <format>] \
+  [-o|--output [<format>:]<output-file>] \
+  <selector>
+
 $ specbook describe \
   [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
+  [-F|--fetch <mode>] \
   [-e|--embed] \
   [-z|--compress [<level>]] \
   [-f|--format <format>] \
   [-p|--part <part>] \
   [-o|--output <output-file>]
 
+$ specbook search \
+  [-v|--verbose [<level>]] \
+  [-F|--fetch <mode>] \
+  [<term> ...]
+
 $ specbook mcp \
   [-v|--verbose [<level>]]
 ```
@@ -180,7 +220,8 @@ Options:
 
 -   `-v|--verbose [<level>]`:
     Enable verbose logging of processing information to `stderr` at the
-    given verbosity level: `0` (the default) logs the notices only, `1`
+    given verbosity level: `0` (the default) logs the warnings and the
+    environment problems only, `1`
     (the bare flag) also the regular processing information, `2` also
     the reference coverage ratios, and `3` also the unreferenced objects
     of a reference coverage.
@@ -188,12 +229,11 @@ Options:
 -   `-c|--config <schema-yaml-file>`:
     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
-    artifacts are `optional`, and so is an artifact absent from its present
-    file, unless it is `optional` itself. Both `lint` and `export` report
+    schema configuration `specbook-format.yaml`) determines the artifacts
+    of the specification, while its `file` fields drive `init` only: every
+    `.md` file below the base directory is loaded and parsed, whatever its
+    name. A base directory without any `.md` file is reported, and so is an
+    artifact absent from all of them, unless it is `optional`. Both `lint` and `export` report
     all diagnostics and fail on any error among them (a warning, like a
     lapse of the reference coverage a `referenced` object kind demands,
     is reported only), so a partial or invalid specification is never
@@ -204,7 +244,11 @@ Options:
     The option accepts glob patterns and can be given multiple times: the
     matching files (in the order of the patterns and alphabetically within
     a pattern, where the literal `std` names the bundled standard schema
-    configuration, and where a pattern matching no file is an error) are
+    configuration, the literal `meta` the bundled meta one, which
+    describes a schema configuration itself, and the literal `pm` the
+    bundled project management one, which plans the delivery of a
+    solution in a handbook beside its specification, and where a pattern matching
+    no file is an error) are
     merged in order into one effective schema configuration, the later
     files into the earlier ones. The objects merge deeply, while the
     elements of the lists are matched by identity (artifacts by `kind`
@@ -213,12 +257,61 @@ Options:
     counterpart, an unmatched one is appended. Every file has to be valid
     YAML on its own, while the merged result alone is validated against
     the schema of the configuration.
+    Instead of a local file, the option also accepts a *remote reference*
+    (see "Remote References" below): `npm:<pkg>[@<range>][/<path>]`,
+    `github:<user>/<repo>[/<path>][#<ref>]`, or an `http://` or `https://`
+    URL of a single file, which is fetched into the download cache and then merged
+    exactly like a local file.
 
 -   `-b|--basedir <spec-md-file-basedir>`:
     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.
+    configuration file `.specbook.yaml`, else `.`) is the directory
+    whose `.md` files (recursively, except below `.`-prefixed entries)
+    make up the specification, and generated specification Markdown
+    files are placed inside it, too. A normalized Markdown export written
+    into it is refused, as it would be parsed as a specification file.
+
+-   `-F|--fetch <mode>`:
+    When to fetch the remote references of the schema configuration
+    through the network: `never` (the download cache only, where a
+    reference which is not cached is an error), `auto` (the default:
+    whenever the download cache lacks a reference or it is no longer
+    fresh), or `always` (ignoring the download cache).
+
+-   `-g|--gitignore` (`lint`, `export`, `preview`, and `query` only):
+    Set aside every specification file the Git exclude rules (the global
+    excludes file, the repository-local `info/exclude`, and the
+    `.gitignore` files, with Git's own precedence) exclude from its
+    project, as it is no part of the project: silently if all of its
+    artifacts are optional, else as the error `artifact file excluded by
+    Git`. A base directory outside any Git working tree excludes nothing.
+
+-   `-S|--schema` (`export`, `preview`, and `query` only):
+    Export (or preview, or query) the *effective schema configuration itself* --
+    the one `-c|--config` selects, merged out of its local, bundled, or
+    remote files -- as a SpecBook document, instead of the specification
+    below the base directory (which is not applicable then, so an
+    explicit `-b|--basedir` is an error, and `--watch` and `preview`
+    observe the configuration files only). The document is generated in
+    memory against the bundled meta schema configuration (`meta`) and
+    rendered like any other specification, in every export format: a
+    title page with the configuration references, the SpecBook version,
+    and the counts of the artifact kinds, artifacts, object kinds, and
+    reference relationships, an artifact-level overview graph as the
+    "Diagram of Contents", and one top-level `ARTIFACT-KIND` artifact per
+    artifact kind (with a graph of its artifacts and object kinds),
+    every artifact and object kind
+    (with its file, name pattern, optionality, `referenced`/`coverage`
+    patterns, `automaton`, `badge`, `multiple`, `diagram`, and `format`
+    configuration, its
+    description and literature references, and a hub diagram of its
+    references, every artifact also with a Mermaid UML class diagram of
+    it and its object kinds, omittable via `-O diagram:code` and left out
+    without relationships), and every property (with its value constraint and
+    flags, a reference-valued one additionally naming its target
+    artifacts and object kinds and its cardinality, and acting as an edge
+    of the diagrams). When several configuration files are merged, every
+    object also names the files contributing it.
 
 -   `-o|--output [<format>:]<output-file>` (`export` only):
     The output file (`-` for stdout) is required and can be given multiple times.
@@ -230,8 +323,9 @@ Options:
 
 -   `-w|--watch` (`export` only):
     Keep the outputs in sync with their sources: after the regular export,
-    the YAML schema configuration files, the referenced artifact files, and
-    all assets they embed are observed, and every change re-exports the
+    the YAML schema configuration files, the specification files, all
+    assets they embed, and the base directory itself (for added and removed
+    `.md` files) are observed, and every change re-exports the
     specification once the sources stayed silent for one second. A failed
     re-export is reported and leaves the observe loop intact, so a
     transiently invalid specification (or configuration) does not end the
@@ -244,9 +338,12 @@ Options:
     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`, `diagram:grid`,
-    `diagram:code` (Mermaid/D2), and `diagram:image` (images and PDF pages) omit all
-    diagrams of a type, `diagram:1` (alias: `diagram`), `diagram:2`, and
+    export: `diagram:graph`, `diagram:hub`, `diagram:grid`, `diagram:state`,
+    `diagram:layer`, `diagram:slice`, `diagram:tree`, `diagram:matrix`,
+    `diagram:sequence`, `diagram:petri`, `diagram:gantt`, `diagram:code`
+    (Mermaid/D2), `diagram:image` (images and PDF pages), and
+    `diagram:listing` (code listings) 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
@@ -272,6 +369,28 @@ Options:
     the connection state: its plug icon carries the search highlight
     color while disconnected and blinks for 2s after every update.
 
+-   `-P|--param <name>=<value>`, `<selector>` (`query` only):
+    Query the specification (strictly validated like `export`) with the
+    XPath-like selector of [ASTq](https://github.com/rse/astq) and write
+    the matched nodes as an array (their subtrees included, the embedded
+    file contents dropped), where `-P|--param` (repeatable) gives the
+    value of a `{name}` parameter of the selector.
+    The root node is of type `specification`, its children are of type
+    `artifact` (attributes `created`, `modified`, and `file`), and the
+    objects below are typed by their kind (attributes `kind`, `id`,
+    `anchor`, `paren`, `name`, `primary`, `description`, `rationale`,
+    `elaboration`, and one per property key), e.g.
+    `specbook query "// USE-CASE [ @ACTOR == '[[ROLE:attendee]]' ]"`. The
+    query function `refs()` yields the objects the references of an object
+    resolve to, e.g. `specbook query "// REQUIREMENT [ count(refs()) == 0 ]"`.
+
+-   `-f|--format <format>`, `-o|--output [<format>:]<output-file>` (`query` only):
+    The output file (default: `-` for stdout) receives the matched nodes
+    in the format `json`, `json5`, `yaml`, or `toon`, where an explicit
+    `-f|--format` wins and the format is otherwise inferred exactly like
+    for an `export` output (a `<format>:` prefix, else the filename
+    extension, while plain `-` defaults to JSON).
+
 -   `-o|--output <output-file>` (`describe` only):
     The output file (default: `-` for stdout) receives the described
     Markdown document.
@@ -287,7 +406,8 @@ Options:
     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`,
-    `diagram`, and `format` fields, and `3` additionally leaves out its
+    `badge`, `multiple`, `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.
 
@@ -317,8 +437,8 @@ 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
+(exactly like the repeatable `-c|--config`, including the literals
+`std`, `meta`, and `pm`), 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
@@ -326,7 +446,12 @@ win over its entry.
 
 `specbook init` creates such a file in the current working directory
 (unless one already applies), so the options of the initialization
-stick for all subsequent commands.
+stick for all subsequent commands. With `-s|--sample` it scaffolds a
+small sample into the created artifact files instead of the bare
+headings -- one object per allowed object kind, with every configured
+property carrying a placeholder value satisfying the schema and the
+first sentence of the schema description of the kind as its statement
+-- so the format is learnable from the generated files alone.
 
 The default value of every CLI option `--xxx` can be overridden
 by a corresponding `SPECBOOK_XXX` environment variable (e.g.
@@ -345,11 +470,102 @@ an executable path and any other one as a Playwright channel name
 `chrome-dev`, `chrome-canary`, `msedge`, `msedge-beta`, `msedge-dev`,
 or `msedge-canary`). The variable itself has no default value: when it
 is unset, the downloaded Playwright Chromium is used (the equivalent of
-`chromium`) and only if that one is absent a system-installed *Google
+`chromium`) and, only if that one is absent, a system-installed *Google
 Chrome* (the equivalent of `chrome`). An explicitly configured browser
 failing to launch fails the export instead of falling back onto another
 browser.
 
+### API
+
+Third-party scripts generating foreign documents out of a specification
+load it (strictly validated like `export`) and query its AST through the
+very same ASTq selectors as `specbook query`, retrieving the *original*
+AST nodes:
+
+```ts
+import { SpecBook, type SpecObject } from "@rse/specbook"
+
+const specbook = new SpecBook()
+const document = await specbook.load({ basedir: "docs/spec" })
+
+/*  register a custom query function (beside the built-in "refs()")  */
+document.func("contains", (_adapter, _node, list, item) =>
+    Array.isArray(list) && list.includes(item))
+
+/*  emit the roles with the use cases referencing them as Markdown  */
+for (const role of document.query("// ROLE") as SpecObject[]) {
+    console.log(`## ${document.plain(role.name)}\n`)
+    for (const useCase of document.query("// USE-CASE [ contains(refs(), {role}) ]",
+        { role }) as SpecObject[])
+        console.log(`-   ${document.plain(useCase.name)}`)
+}
+```
+
+The `SpecBookDocument` returned by `load()` (options like `lint`, plus
+`schema`) carries the `specification`, its `config`, and the warning
+`diagnostics`, and provides `query(selector, params?)`, `parent(node)`
+(the AST nodes carrying no parent references), `func(name, fn)`, and the
+text helpers `plain(text, from?)` and `html(text, from?)`, which render
+a Markdown text (a description part or property value) into plain text
+resp. an HTML fragment, replacing every `[[...]]` reference by the name
+of its target object.
+
+Remote References
+-----------------
+
+Useful schema configurations should not stay buried in individual
+project repositories. SpecBook hence resolves *remote references*
+wherever a schema configuration is expected (`-c|--config`, the `config`
+entry of `.specbook.yaml`, `SPECBOOK_CONFIG`):
+
+-   `npm:<pkg>[@<range>][/<path>]`: a package of the npm registry (the
+    package perhaps scoped, the version a semver range or dist-tag,
+    default `latest`), resolved and fetched through the npm registry
+    client itself, so the `registry`, the scoped `@scope:registry`, and
+    the `//host/:_authToken` credentials of your `.npmrc` files (and the
+    `npm_config_*` environment variables) are honored, while none of the
+    scripts of the package is ever run.
+
+-   `github:<user>/<repo>[/<path>][#<ref>]`: a GitHub repository at a
+    branch, tag, or commit (default: `HEAD`), fetched as its tarball,
+    where `GITHUB_TOKEN` (or `SPECBOOK_GITHUB_TOKEN`) authenticates the
+    private repositories.
+
+-   `http[s]://<host>[:<port>]/<path>/<file>`: a single schema
+    configuration file.
+
+The `<path>` inside a package names a schema configuration file, a glob
+pattern of such files, or a named building block of the
+`"specbook": { "schema": { "<name>": "<file>", ... } }` map of the
+`package.json` of the package. An absent path resolves through the
+`"specbook": { "schema": "<file>" }` entry of the `package.json`, then
+through the `config` entries of the `.specbook.yaml` of the package
+(whose remote entries resolve transitively, a cycle being an error),
+and finally through its `index.yaml`. A package may
+declare the SpecBook versions it supports through
+`"engines": { "specbook": "<range>" }` of its `package.json`, which is
+checked. The artifacts several schema configuration files define (and
+hence merge) are reported at verbosity level `2`, and unconditionally
+if two remote files collide, as such a merge is hardly intended.
+
+The downloads are cached under `SPECBOOK_CACHE` (default: the native
+cache location of the platform, like `~/Library/Caches/specbook` on
+macOS, `%LOCALAPPDATA%\specbook\Cache` on Windows, and
+`$XDG_CACHE_HOME/specbook` or `~/.cache/specbook` elsewhere): an exact
+npm version or a commit hash is immutable and stays cached forever,
+while a floating reference (a range, a branch, a tag, a URL) is
+fetched again after five minutes. With `-F|--fetch never` (or
+`SPECBOOK_FETCH=never`), only the cache is consulted, and a reference
+which is not cached is an error, while `-F|--fetch always` fetches every
+reference again.
+
+To share a schema configuration of your own, publish it as a plain npm
+package carrying the keyword `specbook-schema` (or push it to a GitHub
+repository carrying the same topic), so `specbook search [<term> ...]`
+(and the MCP tool `specbook_search`) finds it, right after the bundled
+schema configurations `std`, `meta`, and `pm`, which it always
+lists first (and which are all it lists under `--fetch never`).
+
 Agent Skill
 -----------
 
@@ -364,10 +580,13 @@ $ 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 init   [-c|--config <yaml-file>] [-b|--basedir <basedir>] [-F|--fetch <mode>]
+                 [-s|--sample]
+/specbook lint   [-c|--config <yaml-file>] [-b|--basedir <basedir>] [-F|--fetch <mode>]
+                 [-g|--gitignore]
+/specbook export [-c|--config <yaml-file>] [-b|--basedir <basedir>] [-F|--fetch <mode>]
+                 [-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>]
 ```
@@ -395,7 +614,7 @@ query (`--loop`). All commands leave an absent `--config` and
 Example: Simple
 ---------------
 
-Check out the *simple* specification of simple
+Check out the *simple* specification of a simple
 example data model:
 
 ### Sources
@@ -446,6 +665,32 @@ $ specbook export -v \
 
 ![screenshot-broadcast-print](etc/screenshot-broadcast-print.png)
 
+Example: Project Management
+---------------------------
+
+Check out the *project management handbook* of the Broadcast
+project, based on **SpecBook**'s built-in "pm" schema, which plans the
+delivery of a solution (the project charter with its objectives,
+constraints, assumptions, and budget, the team, the deliverables, the
+work breakdown, the project plan as a Gantt chart, the risks and
+opportunities, the governance, and the change log of the issues) in a
+handbook of its own beside the specification:
+
+### Sources
+
+-   [Specification](smp/pm/)
+-   [Schema](src/specbook-format-schema.d/)
+
+### Generation
+
+```bash
+$ specbook export -v \
+    -c pm \
+    -b smp/pm \
+    -o smp/pm.html \
+    -o smp/pm.pdf
+```
+
 See Also
 --------
 
@@ -458,7 +703,7 @@ Support
 **SpecBook** is developed in the experience context of industrial Software
 Engineering at the [*msg group*](https://www.msg.group) and in the
 educational context of the *Software Engineering Academy (SEA)*. **SpecBook**
-development is supported by *msg Research* and *Software Engineering
+development is supported by *msg Research* and the *Software Engineering
 Academy (SEA)*.
 
 License

package/dst/specbook-api.d.ts

@@ -1,7 +1,9 @@
 import { projectFile } from "./specbook-project.js";
+import { version, standardConfig, metaConfig, pmConfig, cacheDir, fetchModes, parseFetchMode, type SearchHit, type FetchMode } from "./specbook-remote.js";
 import { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic, type DiagnosticSeverity } from "./specbook-diagnostic.js";
 import { type LintResult } from "./specbook-cmd-lint.js";
 import { parseOutputSpec, formats, omitAspects, type ExportFormat } from "./specbook-cmd-export.js";
+import { SpecBookDocument, renderNodes, queryFormats, parseQueryOutput, type SpecNode, type SpecQueryFunc, type SpecQueryAdapter, type QueryFormat } from "./specbook-cmd-query.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";
@@ -15,10 +17,10 @@ export { compressLevels, parseCompressLevel };
 export { type DescribeFormat, type DescribePart, type CompressLevel };
 export { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic, type DiagnosticSeverity };
 export { type LintResult };
+export { SpecBookDocument, renderNodes, queryFormats, parseQueryOutput, type SpecNode, type SpecQueryFunc, type SpecQueryAdapter, type QueryFormat };
+export { version, standardConfig, metaConfig, pmConfig, cacheDir, fetchModes, parseFetchMode, type FetchMode, type SearchHit };
 export type { Spec, SpecArtifact, SpecObject, SpecDescription, SpecProperty } from "./specbook-format-spec.js";
 export type { Schema, SchemaObject, SchemaProperty } from "./specbook-format-schema.js";
-export declare const version: string;
-export declare const standardConfig: string;
 export type VerboseSink = (cmd: string, msg: string, level: VerboseLevel) => void;
 export interface SpecBookOptions {
     verbose?: VerboseSink;
@@ -27,16 +29,23 @@ export interface ProjectOptions {
     config?: string[];
     basedir?: string;
     cwd?: string;
+    fetch?: FetchMode;
 }
 export interface InitResult {
     files: string[];
     project?: string;
 }
+export interface SearchRequest {
+    term?: string;
+    cwd?: string;
+    fetch?: FetchMode;
+}
 export interface ExportRequest extends ProjectOptions {
     formats?: ExportFormat[];
     realtime?: boolean;
     omit?: string[];
     gitignore?: boolean;
+    schema?: boolean;
     rebase?: (string | undefined)[];
 }
 export interface WatchRequest extends ExportRequest {
@@ -48,14 +57,24 @@ export declare class SpecBook {
     constructor(options?: SpecBookOptions);
     private verboseOf;
     private project;
+    private remoteOptions;
     private configFiles;
     private requireConfig;
-    init(options: ProjectOptions): Promise<InitResult>;
+    init(options: ProjectOptions & {
+        sample?: boolean;
+    }): Promise<InitResult>;
     lint(options: ProjectOptions & {
         gitignore?: boolean;
     }): Promise<LintResult>;
+    load(options: ProjectOptions & {
+        gitignore?: boolean;
+        schema?: boolean;
+    }): Promise<SpecBookDocument>;
+    search(options: SearchRequest): Promise<SearchHit[]>;
     private renderFormats;
     private rebaseOf;
+    private guardRebase;
+    private parseSource;
     export(options: ExportRequest): Promise<Buffer[]>;
     private observe;
     watch(options: WatchRequest): Promise<void>;
@@ -64,6 +83,7 @@ export declare class SpecBook {
         port?: number;
         omit?: string[];
         gitignore?: boolean;
+        schema?: boolean;
     }): Promise<void>;
     describe(options: ProjectOptions & {
         embed?: boolean;