@rse/specbook 1.4.0 → 1.4.2

package/README.md

@@ -324,6 +324,10 @@ 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.
 
+`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.
+
 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`,

package/dst/specbook-api.d.ts

@@ -28,6 +28,10 @@ export interface ProjectOptions {
     basedir?: string;
     cwd?: string;
 }
+export interface InitResult {
+    files: string[];
+    project?: string;
+}
 export interface ExportRequest extends ProjectOptions {
     formats?: ExportFormat[];
     realtime?: boolean;
@@ -46,7 +50,7 @@ export declare class SpecBook {
     private project;
     private configFiles;
     private requireConfig;
-    init(options: ProjectOptions): Promise<string[]>;
+    init(options: ProjectOptions): Promise<InitResult>;
     lint(options: ProjectOptions & {
         gitignore?: boolean;
     }): Promise<LintResult>;

package/dst/specbook-api.js

@@ -8,7 +8,7 @@ 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 { loadProject, writeProject, 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";
@@ -62,6 +62,7 @@ export class SpecBook {
         const given = (value) => options.cwd !== undefined ? path.resolve(cwd, value) : value;
         const derived = (value) => options.cwd !== undefined ? value : path.relative(cwd, value) || ".";
         return {
+            file: project?.file,
             config: config !== undefined && config.length > 0 ?
                 config.map((pattern) => pattern === "std" ? pattern : given(pattern)) :
                 project?.config?.map((pattern) => pattern === "std" ? pattern : derived(pattern)),
@@ -105,13 +106,24 @@ export class SpecBook {
             `and ${literal(stats.links)} link relationship(s)`);
         return config;
     }
-    /*  initialize the configured specification artifact files
-        below the base directory  */
+    /*  initialize the configured specification artifact files below the
+        base directory and persist the effective project options into a
+        new project configuration file in the working directory, unless
+        one already applies (as a new one would shadow it)  */
     async init(options) {
         const verbose = this.verboseOf("init");
         const project = this.project(options, verbose);
-        return initSpecification({ config: this.requireConfig(await this.configFiles(project.config), verbose),
+        const files = initSpecification({ config: this.requireConfig(await this.configFiles(project.config), verbose),
             basedir: project.basedir ?? ".", verbose });
+        if (project.file !== undefined) {
+            verbose(`skipping existing project configuration "${literal(project.file)}"`);
+            return { files };
+        }
+        const cwd = path.resolve(options.cwd ?? ".");
+        const relative = (value) => path.relative(cwd, path.resolve(cwd, value)) || ".";
+        const file = writeProject(cwd, project.config?.map((pattern) => pattern === "std" ? pattern : relative(pattern)) ?? ["std"], relative(project.basedir ?? "."));
+        verbose(`created project configuration "${literal(file)}"`);
+        return { files, project: options.cwd !== undefined ? file : path.relative(process.cwd(), file) };
     }
     /*  lint the specification Markdown files below the base directory,
         where "gitignore" treats an artifact file Git excludes from its

package/dst/specbook-cli.js

@@ -130,15 +130,18 @@ withVerboseOption(program.command("mcp"))
     verboseOf(opts)("mcp", "starting MCP server on stdio", "notice");
     await serveMcp(verboseOf(opts, "mcp"));
 });
-/*  the init command creates the configured artifact files  */
+/*  the init command creates the configured artifact files and,
+    unless one already applies, the project configuration file  */
 withCommonOptions(program.command("init"))
     .description("initialize the configured specification artifact files below the base directory")
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const created = await specbook.init({ config: configOf(opts), basedir: opts.basedir });
-    await writeStdout(created.length > 0 ?
-        `initialized artifact file(s): ${created.join(", ")}\n` :
-        "no artifact files were created\n");
+    const result = await specbook.init({ config: configOf(opts), basedir: opts.basedir });
+    await writeStdout((result.files.length > 0 ?
+        `initialized artifact file(s): ${result.files.join(", ")}\n` :
+        "no artifact files were created\n") +
+        (result.project !== undefined ?
+            `created project configuration file: ${result.project}\n` : ""));
 });
 /*  the lint command reports all diagnostics and fails on any error  */
 withGitignoreOption(withCommonOptions(program.command("lint")))

package/dst/specbook-cmd-init.js

@@ -7,8 +7,22 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { literal } from "./specbook-verbose.js";
 import { formatTimestamp } from "./specbook-export-md.js";
+import { titleProperties } from "./specbook-export-common.js";
+/*  render the property list of the title artifact, seeding the properties
+    the exports interpret themselves with their rendering defaults (as far
+    as the schema configures them, as any other is reported as unknown)  */
+const titleList = (artifact) => {
+    if (artifact.kind !== "META" || artifact.name?.toUpperCase() !== "TITLE")
+        return "";
+    const props = titleProperties.filter((prop) => artifact.props?.some((p) => p.name === prop.name) === true);
+    if (props.length === 0)
+        return "";
+    const width = Math.max(...props.map((prop) => prop.name.length)) + 2;
+    return props.map((prop) => `-   ${`${prop.name}:`.padEnd(width)}${prop.init}`.trimEnd() + "\n").join("") + "\n";
+};
 /*  initialize the configured specification artifact files below the
-    base directory with their frontmatter and artifact headings, where
+    base directory with their frontmatter and artifact headings (plus
+    the title properties), where
     all artifacts configured onto the same file reside in it side by
     side, following each other on level 1  */
 export const initSpecification = (options) => {
@@ -38,7 +52,7 @@ export const initSpecification = (options) => {
         const headings = artifacts.map((artifact) => {
             const name = artifact.name ?? "";
             const paren = artifact.id !== undefined ? ` (${artifact.id})` : "";
-            return `#   ${artifact.kind}: ${name}${paren}\n\n`;
+            return `#   ${artifact.kind}: ${name}${paren}\n\n` + titleList(artifact);
         }).join("");
         const text = "---\n" +
             `Created:  ${now}\n` +

package/dst/specbook-diagram.js

@@ -344,14 +344,10 @@ const deriveCenter = (ctx, object, diagram, nodes, nodeSet, errors) => {
                 return undefined;
             }
             centerUrl = `#${anchors.get(source) ?? source.id}`;
-            if (centerCfg.property !== undefined) {
-                const value = propValue(parenProps, source, centerCfg.property);
-                if (value === undefined) {
-                    errors.push({ reason: `diagram "center" source lacks the property "${centerCfg.property}"` });
-                    return undefined;
-                }
+            const value = centerCfg.property !== undefined ?
+                propValue(parenProps, source, centerCfg.property) : undefined;
+            if (value !== undefined)
                 label = plainText(expandReferences(value, (ref) => resolveUnique(index, ref, source).target?.name ?? ref));
-            }
             else if (label === undefined)
                 label = plainText(source.name);
         }

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

@@ -31,6 +31,10 @@ export declare const paperSizeDefault = "A4";
 export declare const paperSetup: (paper: string) => PaperSetup;
 export declare const paperLength: (setup: PaperSetup, value: number) => string;
 export declare const documentPaperSize: (specification: Spec) => string;
+export declare const titleProperties: {
+    name: string;
+    init: string;
+}[];
 export declare const paperStylesheet: (paper: string) => string;
 export declare const charsetCodepoints: (charset: string) => number[] | undefined;
 export declare const subsetStylesheet: (charset?: string) => Promise<string>;

package/dst/specbook-export-common.js

@@ -6,6 +6,7 @@
 import fs from "node:fs";
 import { embeddingThemes, darkMark } from "./specbook-parse-common.js";
 import { plainText } from "./specbook-link.js";
+import { themeToneDefault } from "./specbook-theme.js";
 /*  escape a text for embedding into template HTML (text and attributes)  */
 export const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
     .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -111,6 +112,21 @@ export const documentPaperSize = (specification) => {
             `(expected ${paperSizes.join(", ")})`);
     return paper;
 };
+/*  the properties of the title object the exports interpret themselves,
+    each with the value "init" seeds it with (its rendering default, an
+    empty value counting as an absent property)  */
+export const titleProperties = [
+    { name: "LOGO", init: "" },
+    { name: "TITLE", init: "Specification" },
+    { name: "SUBTITLE", init: "" },
+    { name: "AUTHOR", init: "" },
+    { name: "VERSION", init: "" },
+    { name: "LANG", init: "en" },
+    { name: "CHARSET", init: "UTF-8" },
+    { name: "THEME-STYLE", init: "Light" },
+    { name: "THEME-TONE", init: themeToneDefault },
+    { name: "PAPER-SIZE", init: paperSizeDefault }
+];
 /*  the vertical room (in rem) the introducing heading of a diagram
     claims above it on the same page: without this reserve a maximally
     sized diagram could not share its page with the heading, which

package/dst/specbook-export-diagram.js

@@ -81,16 +81,18 @@ const mermaidColors = (colors, style) => {
     theme color spreads after the shape of the D2 themes "Neutral
     Default" (light) and "Dark Mauve" (dark): the neutrals "N1" (text)
     to "N7" (background), the base colors "B1" (strokes) to "B6"
-    (fills), and the alternative accents "AA*"/"AB*"  */
+    (fills), and the alternative accents "AA*"/"AB*", where the fills
+    "B4" to "B6" of the nesting levels 1 to 3 are spread far apart and,
+    unlike in D2, recede towards the outer levels (the containers)  */
 const d2Colors = (colors, style) => {
     const [b, a, s] = [colors.base, colors.accent, colors.signal];
     return style === "dark" ? {
         N1: b[28], N2: b[25], N3: b[22], N4: b[13], N5: b[10], N6: b[8], N7: b[6],
-        B1: a[21], B2: a[21], B3: a[13], B4: a[10], B5: a[8], B6: a[7],
+        B1: a[21], B2: a[21], B3: a[13], B4: b[9], B5: a[0], B6: a[5],
         AA2: s[19], AA4: s[10], AA5: s[8], AB4: s[10], AB5: s[8]
     } : {
         N1: b[3], N2: b[13], N3: b[19], N4: b[25], N5: b[27], N6: b[29], N7: b[31],
-        B1: a[7], B2: a[11], B3: a[27], B4: a[28], B5: a[29], B6: a[30],
+        B1: a[7], B2: a[11], B3: a[27], B4: a[31], B5: a[28], B6: a[24],
         AA2: s[13], AA4: s[28], AA5: s[30], AB4: s[28], AB5: s[30]
     };
 };
@@ -128,7 +130,7 @@ const d2Error = (err) => {
 const renderD2 = (source, colors, style) => {
     const overrides = Object.entries(colors).map(([key, color]) => `${key}: "${color}"`).join("; ");
     const request = d2Chain.then(async () => {
-        d2 ??= import("@terrastruct/d2").then((module) => new module.D2())
+        d2 ??= import("@d2lang/d2").then((module) => new module.D2())
             .catch((err) => {
             d2 = null;
             throw err;

package/dst/specbook-export-html-render.js

@@ -8,7 +8,7 @@ import { markedSmartypants } from "marked-smartypants";
 import { resolveUnique, expandReferences } from "./specbook-link.js";
 import { compileValueExpr, splitItems } from "./specbook-parse-value.js";
 import { embeddingRegex, embeddingCount, embeddingThemes, darkMark } from "./specbook-parse-common.js";
-import { escapeHtml, fallbackLogo, imageDark, isTitleObject } from "./specbook-export-common.js";
+import { escapeHtml, fallbackLogo, imageDark, isTitleObject, titleProperties } from "./specbook-export-common.js";
 import { isDocument } from "./specbook-export-image.js";
 import { embeddedSource, fenceLanguage, diagramKey, omittedDiagram } from "./specbook-export-diagram.js";
 import { embeddedListing, fencedListing } from "./specbook-export-code.js";
@@ -680,8 +680,7 @@ export const renderTitlePage = (object, created, modified) => {
         const value = prop(name);
         return value !== undefined && value.trim() !== "" ? inline(value) : "";
     };
-    const rest = object.properties.filter((property) => !["LOGO", "TITLE", "SUBTITLE", "AUTHOR", "VERSION",
-        "LANG", "CHARSET", "PAPER-SIZE", "THEME-STYLE", "THEME-TONE"].includes(property.key));
+    const rest = object.properties.filter((property) => !titleProperties.some((prop) => prop.name === property.key));
     /*  the logo is rendered above the title, from the embedded image content
         of the LOGO property or, for a non-embeddable reference, as its inline
         Markdown; without a (non-empty) LOGO property the built-in SpecBook

package/dst/specbook-format.md

@@ -323,7 +323,8 @@ type SchemaGradiaConfig = Partial<{
 -   `SchemaDiagram.center?: string | SchemaDiagramCenter`:
     object a `hub` diagram is projected onto (default: `self`), or a
     synthetic center node, labeled from a referenced `source` object (or
-    one of its properties, via `property`) or a literal `label`, typed
+    one of its properties, via `property`, falling back onto the `label`
+    or the object name while absent) or a literal `label`, typed
     (under `qualified`) by `kind`, and linked to the `source` object,
     BECAUSE the focus of a hub is not always a specification object --
     the solution itself, e.g., sits in the middle of a context diagram
@@ -572,7 +573,8 @@ Instead of naming an existing object, `center` can also declare a
 *synthetic* center node, which represents something no specification
 object models -- like the solution itself in the middle of a context
 diagram. Such a center is labeled from a referenced `source` object (or
-one of its properties, via `property`) or a literal `label`, and links
+one of its properties, via `property`, falling back onto the `label` or
+the object name while the property is absent) or a literal `label`, and links
 to the `source` object. As the nodes carry no `[[xxx]]` reference to a
 synthetic center, `centerEdges` synthesizes the edges from a direction
 `property` of the node objects: its `inbound` value maps onto a
@@ -1146,7 +1148,7 @@ its own and embedded like an image -- `![<alt/>](<file/>.mmd)`,
 `![<alt/>](<file/>.mermaid)`, or `![<alt/>](<file/>.d2)` -- inside a
 description or property value, where its source is inlined at parse time.
 The HTML/PDF export renders every such diagram (Mermaid through
-`beautiful-mermaid`, D2 through `@terrastruct/d2`) in the theme colors of
+`beautiful-mermaid`, D2 through `@d2lang/d2`) in the theme colors of
 the document, once per color theme, like a theme-aware image. It folds,
 maximizes, and is omitted (`-O diagram:code`, for diagrams as code, or
 by nesting level) like a derived Gradia diagram. A diagram failing to render

package/dst/specbook-format.yaml

@@ -93,7 +93,9 @@
 #
 #   -   All artifacts are optional, so that the schema can back not only
 #       a full specification but also the individual document types of
-#       the modeling coverage matrix above on their own.
+#       the modeling coverage matrix above on their own. Likewise, the
+#       properties and child objects of all artifacts are optional, so
+#       that a freshly initialized specification already lints cleanly.
 #
 #   -   The traditional hard Software Requirements Specification (SRS)
 #       vs. Architecture Description (AD) document split is
@@ -128,6 +130,7 @@
             optional: true
         -   name: TITLE
             desc: The title of the specification.
+            optional: true
         -   name: SUBTITLE
             desc: The subtitle of the specification.
             optional: true
@@ -182,17 +185,21 @@
         -   name: PURPOSE
             desc: >
                 Why the solution exists.
+            optional: true
         -   name: TARGET-AUDIENCE
             desc: >
                 Whom the solution serves.
+            optional: true
         -   name: SOLUTION
             desc: >
                 What the solution is, in a single sentence naming its kind or
                 category (e.g. a self-hosted, browser-based streaming platform).
+            optional: true
         -   name: VALUE-PROPOSITION
             desc: >
                 The benefit the solution offers its target audience, stated in
                 absolute terms without reference to alternatives.
+            optional: true
         -   name: DIFFERENTIATORS
             desc: >
                 How the solution stands apart from the alternatives, naming the
@@ -266,6 +273,7 @@
                 enforces itself is a Domain Rule or a Non-Functional Requirement instead) and
                 states a fact or event, not a decision (a deliberate exclusion is the `SCOPE` of
                 the Solution Vision or a `WONT` requirement instead).
+            optional: true
             format:
                 type: compact
                 maxTableColumns: 5
@@ -341,6 +349,7 @@
                 (the `BROADER` term where one exists) and adds the characteristics delimiting the
                 term from its siblings (e.g. `A Message submitted by an Attendee as ...`), so that
                 the hierarchy and the definitions cross-check each other.
+            optional: true
             format:
                 type: compact
                 maxTableColumns: 5
@@ -438,6 +447,7 @@
                 exactly this part and hold exactly the rights the Authorization Model grants to it
                 (plus those of the roles it `INHERITS`), while a persona holding several roles
                 holds the union of them.
+            optional: true
             format:
                 maxTableColumns: 5
             referenced:
@@ -482,6 +492,7 @@
                 persona's own voice, like a "tagline", "mantra", or "defining statement" -- that
                 captures their core attitude, motivation, frustration, or need in a single memorable
                 line. Non-user stakeholders are modeled as personas of type `Stakeholder`.
+            optional: true
             format:
                 maxTableColumns: 5
             props:
@@ -573,6 +584,7 @@
             desc: >
                 The end-to-end journey of a single persona (or of multiple personas sharing the same
                 experience as role variants), named with a 2-5 word summary of the pursued scenario.
+            optional: true
             props:
                 -   name: ACTORS
                     desc: >
@@ -660,6 +672,7 @@
                 event-driven (`When <trigger>, the system MUST ...`), state-driven (`While <state>,
                 the system MUST ...`), optional-feature (`Where <feature>, the system MUST ...`), or
                 unwanted-behavior (`If <condition>, then the system MUST ...`).
+            optional: true
             format:
                 maxTableColumns: 6
             referenced:
@@ -734,6 +747,7 @@
                 them (a `WONT` requirement, which the architecture rightly ignores, is the tolerated
                 exception the lint warning cannot tell apart) and its hub diagram shows what
                 answers it.
+            optional: true
             referenced:
                 -   "[[TACTIC:*]]"
                 -   "[[DECISION:*]]"
@@ -838,6 +852,7 @@
                 <outcome>` item per case, applied in order with the first matching case winning,
                 and a closing sentence stating the outcome of the remaining cases ("otherwise")
                 and carrying the rationale.
+            optional: true
             format:
                 maxTableColumns: 5
             referenced:
@@ -950,6 +965,7 @@
                 cases, a use case spans several activities, and an activity performed outside the
                 solution is covered by none at all -- so the workflow is no mere sequence of use
                 cases and cannot be assembled from them.
+            optional: true
             automaton:
                 nodes: ACTIVITY
                 edges: HANDOFF
@@ -1123,6 +1139,7 @@
                 relate it n:m to the Domain Workflow activities -- a use case spans several
                 activities and an activity is covered by several use cases -- so the two decompose
                 the same domain independently instead of nesting into each other.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -1295,6 +1312,7 @@
                 A named entity of the data model, carrying a Pascal-cased, 1-3 word long,
                 per-artifact unique name, and described by a 1-sentence description ("what") plus a
                 1-sentence rationale ("why").
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -1462,6 +1480,7 @@
                 state machine: exactly one initial state, at least one final state, every state
                 reachable from the initial state, and some final state reachable from every state
                 (a state from which no final state can be reached anymore is a livelock).
+            optional: true
             automaton:
                 nodes: STATE
                 edges: TRANSITION
@@ -1625,6 +1644,7 @@
                 they are granted, so that the permissions of all roles form the access matrix of
                 roles against entities. Any operation, state, or condition not covered by a
                 permission of the role (or of a role it `INHERITS`) is forbidden.
+            optional: true
             format:
                 type: compact
                 maxTableColumns: 8
@@ -1738,6 +1758,7 @@
                 belongs to, where the kind-specific parts (HTTP method, GraphQL operation, topic
                 direction, command) are carried by the `OPERATION` and `LOCATOR` properties of the
                 endpoints only.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -1993,6 +2014,7 @@
                 Endpoints form a flat list: a hierarchy of sub-commands or sub-resources
                 is expressed by a path-style `LOCATOR` (e.g. `remote add`,
                 `/events/{eventId}/chat`) only.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -2226,6 +2248,7 @@
                 is a Dialog Pattern instead), decides between design alternatives (the alternative
                 it rejects is its `TRADE-OFF`), and is not verifiable by a metric (a measurable
                 quality bound is a Non-Functional Requirement instead).
+            optional: true
             referenced:
                 -   "[[DIALOG-PATTERN:*]]"
             format:
@@ -2325,6 +2348,7 @@
                 solution phrases what it says, not what it does (a behavior is an Interaction
                 Concept principle instead) and not what a term means (a definition is a Domain
                 Glossary term instead).
+            optional: true
             format:
                 type: compact
             diagram:
@@ -2410,6 +2434,7 @@
                 occurring in a single flow is a Dialog Storyboard frame instead) and is bound to a
                 particular kind of screen or flow (a solution-wide rule independent of any screen
                 is an Interaction Concept principle instead).
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -2500,6 +2525,7 @@
                 one flow, as seen by its actors (the intent and the information exchanged are a Use
                 Cases scenario instead, and a structure recurring across flows is a Dialog Pattern
                 instead).
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -2611,6 +2637,7 @@
                 `MOCKUP` or a Dialog Storyboard frame instead), and is a decision rather than a
                 list of token values (the values are in the design system) or a measurable bound
                 (a bound is a Non-Functional Requirement instead).
+            optional: true
             format:
                 type: compact
                 maxTableColumns: 5
@@ -2670,6 +2697,7 @@
                 is a reference rendering of the final look of one screen (a low-fidelity sketch of
                 a screen within its flow is a Dialog Storyboard frame instead) and shows rules
                 applied rather than stating them (a rule is an `ELEMENT` instead).
+            optional: true
             format:
                 type: complex
             diagram:
@@ -2754,6 +2782,7 @@
                 solution deploys and operates itself (e.g. a managed database of its own) is a
                 Deployment View node instead -- only a party or system the solution merely consumes
                 or serves belongs to the system context.
+            optional: true
             format:
                 type: compact
                 maxTableColumns: 5
@@ -2872,6 +2901,7 @@
                 otherwise) and which elaborates how the component fulfills it and collaborates
                 with the components it depends on, plus a 1-sentence rationale ("why") for the
                 component's existence and boundary.
+            optional: true
             format:
                 type: compact
                 maxTableColumns: 5
@@ -2993,6 +3023,7 @@
                                   or a shared module used by client and server), so a product
                                   used on several tiers is a single component here instead of
                                   one per tier; referenced by no Deployment View tier.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -3355,6 +3386,7 @@
                 addressed by a Quality Perspectives tactic referencing the aspect through
                 `AFFECTS`, too, so the hub diagram of an aspect shows the decision and the tactic
                 behind it.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -3415,6 +3447,7 @@
                 Model interface (e.g. of kind `MQTT` or `WebSocket`), and the platform element
                 hosting a managed broker a Deployment View `Managed` node -- only the executing
                 structure itself belongs to the Concurrency View.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -3515,6 +3548,7 @@
                 `TIER`, a location-level tier (e.g. a data center) groups the tiers referencing it
                 via `PART-OF`, and a single deployment unit within a tier is a `NODE` -- only the
                 partition itself belongs here.
+            optional: true
             format:
                 type: concise
             diagram:
@@ -3594,6 +3628,7 @@
                 itself belongs to the Deployment View, with the tier and area the node belongs to
                 and the network segments it is attached to as its `TIER`, `AREA`, and `NETWORK`
                 siblings.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -3764,6 +3799,7 @@
                 deployable artifact is a `Build` aspect of the Development Aspects, and the products
                 used are Technology Stack `Operate-Time` components referenced through `TOOLS` --
                 only the procedure itself, its trigger, and its responsible operator belong here.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -3885,6 +3921,7 @@
                 (e.g. a hosting or budget mandate) protects no quality and is a Design Decisions
                 decision alone -- only the mechanism, the quality it achieves, and the elements it
                 shapes belong here.
+            optional: true
             format:
                 type: compact
             diagram:
@@ -4046,6 +4083,7 @@
                 decision is under-justified. The rationale should make the decision feel earned,
                 not asserted - if you delete the rationale and the decision suddenly looks
                 arbitrary, the rationale was doing its job.
+            optional: true
             format:
                 type: complex
             diagram:
@@ -4253,6 +4291,7 @@
                 `TOOLS`, and the rule about the source layout, build, or process it lives in is a
                 Development Aspects aspect -- only the recurring code shape, the elements written
                 that way, and the deviation ruled out belong here.
+            optional: true
             format:
                 type: complex
             diagram:
@@ -4380,6 +4419,7 @@
                 concurrency unit when its collaboration or contention is exercised, an aspect of
                 the Development Aspects or a Design Decisions decision when its rule is checked by
                 an architectural fitness function (e.g. no dependency edge against the layering).
+            optional: true
             format:
                 type: compact
             diagram:

package/dst/specbook-mcp.js

@@ -46,14 +46,18 @@ export const serveMcp = async (verbose) => {
     server.registerTool("specbook_init", {
         title: "Initialize Specification",
         description: "Initialize the configured specification artifact files below the base directory " +
-            "with their frontmatter and artifact heading, skipping already existing files.",
+            "with their frontmatter and artifact heading, skipping already existing files, and " +
+            `create the project configuration file "${projectFile}" in the working directory, ` +
+            "persisting the effective schema configuration and base directory, unless one already applies.",
         inputSchema: { config, basedir, cwd }
     }, async (args) => {
         try {
-            const created = await specbook.init(args);
-            return { content: [{ type: "text", text: created.length > 0 ?
-                            `initialized artifact file(s): ${created.join(", ")}` :
-                            "no artifact files were created" }] };
+            const result = await specbook.init(args);
+            return { content: [{ type: "text", text: (result.files.length > 0 ?
+                            `initialized artifact file(s): ${result.files.join(", ")}` :
+                            "no artifact files were created") +
+                            (result.project !== undefined ?
+                                `\ncreated project configuration file: ${result.project}` : "") }] };
         }
         catch (err) {
             return errorResult(err);

package/dst/specbook-project.d.ts

@@ -5,3 +5,4 @@ export interface Project {
     basedir?: string;
 }
 export declare const loadProject: (dir: string) => Project | undefined;
+export declare const writeProject: (dir: string, config: string[], basedir: string) => string;

package/dst/specbook-project.js

@@ -5,7 +5,7 @@
 */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { parseDocument, LineCounter } from "yaml";
+import { parseDocument, stringify, LineCounter } from "yaml";
 import * as v from "valibot";
 import { lineColOfPath } from "./specbook-config.js";
 import { renderDiagnostic } from "./specbook-diagnostic.js";
@@ -104,3 +104,12 @@ export const loadProject = (dir) => {
         basedir: basedir !== undefined ? path.resolve(base, basedir) : undefined
     };
 };
+/*  write a new project configuration file into the directory, with the
+    schema configuration patterns and the base directory given relative
+    to it, never overwriting an existing file  */
+export const writeProject = (dir, config, basedir) => {
+    const file = path.join(dir, projectFile);
+    const text = stringify({ config: config.length === 1 ? config[0] : config, basedir });
+    fs.writeFileSync(file, text, { encoding: "utf8", flag: "wx" });
+    return file;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.4.0",
+    "version":                             "1.4.2",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -17,7 +17,7 @@
     },
     "files":                               [ "dst" ],
     "dependencies": {
-        "marked":                          "18.0.14",
+        "marked":                          "18.1.0",
         "marked-smartypants":              "1.1.12",
         "yaml":                            "2.9.1",
         "json5":                           "2.2.3",
@@ -28,18 +28,18 @@
         "@rse/mrcs":                       "0.9.2",
         "@rse/gradia":                     "1.4.2",
         "beautiful-mermaid":               "1.1.3",
-        "@terrastruct/d2":                 "0.1.33",
+        "@d2lang/d2":                      "0.1.34",
         "shiki":                           "4.5.0",
         "pdfjs-dist":                      "6.4.299",
         "@napi-rs/canvas":                 "1.0.10",
-        "@toon-format/toon":               "4.1.1",
+        "@toon-format/toon":               "4.4.0",
         "valibot":                         "1.5.0",
         "nunjucks":                        "3.2.4",
         "@rse/nunjucks-addons":            "2.2.0",
         "textframe":                       "1.2.1",
         "@swc/html":                       "1.16.13",
         "tokenizr":                        "2.2.1",
-        "playwright":                      "1.63.0",
+        "playwright":                      "1.64.0",
         "source-code-error":               "1.2.0",
         "commander":                       "15.0.0",
         "chalk":                           "6.0.1",
@@ -49,14 +49,14 @@
         "es-toolkit":                      "1.52.0",
         "fastify":                         "5.12.5",
         "@fastify/websocket":              "11.3.3",
-        "@modelcontextprotocol/sdk":       "1.32.0",
+        "@modelcontextprotocol/sdk":       "1.32.1",
         "zod":                             "4.6.5"
     },
     "devDependencies": {
         "chokidar-cli":                    "3.0.0",
         "eslint":                          "10.9.0",
         "@eslint/js":                      "10.0.1",
-        "typescript-eslint":               "8.71.0",
+        "typescript-eslint":               "8.71.1",
         "eslint-plugin-promise":           "7.3.0",
         "neostandard":                     "0.14.0-next.1",
         "globals":                         "17.13.0",
@@ -73,7 +73,7 @@
         "source-sans":                     "3.52.0",
         "@fontsource/dejavu-mono":         "5.3.0",
         "@fontsource/noto-sans-symbols":   "5.3.0",
-        "postcss":                         "8.5.28",
+        "postcss":                         "8.5.29",
         "postcss-cli":                     "12.0.0",
         "postcss-url":                     "10.1.4",
         "stylus":                          "0.64.0",