@rse/specbook 1.5.2 → 1.6.1

package/dst/specbook-format.md

@@ -76,11 +76,26 @@ type SchemaObject = {
     referenced?:       string[]
     coverage?:         string[]
     automaton?:        SchemaAutomaton
-    diagram?:          SchemaDiagram
+    badge?:            SchemaBadge
+    multiple?:         SchemaMultiple
+    diagram?:          SchemaDiagram | SchemaDiagram[]
     format?:           SchemaFormat
     props?:            SchemaProperty[]
     children?:         SchemaObject[]
 }
+type SchemaBadge = BadgeIcon | {
+    property:          string
+    map:               Record<string, BadgeIcon>
+    default?:          BadgeIcon
+}
+type SchemaMultiple = {
+    property:          string
+    pattern:           string
+}
+type BadgeIcon =
+    "person" | "team" | "bot" | "device" | "mobile" | "browser" | "service" |
+    "function" | "api" | "code" | "package" | "database" | "cache" | "queue" |
+    "document" | "mail" | "communication" | "clock" | "security" | "cloud" | "network"
 type SchemaAutomaton = {
     nodes:             string
     edges:             string
@@ -103,24 +118,48 @@ type SchemaDiagramCenterEdges = {
     labeled?:          string
     via?:              string
 }
+type SchemaDiagramNest = {
+    properties?:       string[]
+    parent?:           boolean
+    kind?:             boolean
+    layout?:           "graph" | "hub" | "grid"
+    crossing?:         "nodes" | "target" | "both"
+}
 type SchemaDiagram = {
-    type?:             "graph" | "hub" | "grid"
+    type?:             "graph" | "hub" | "grid" | "state" | "layer" |
+                       "slice" | "tree" | "matrix" | "sequence" | "petri" |
+                       "gantt"
     nodes?:            string
     edges?:            string
+    local?:            boolean
     center?:           string | SchemaDiagramCenter
     centerEdges?:      SchemaDiagramCenterEdges
-    links?:            "props" | "all"
+    links?:            "props" | "all" | string[]
     labeled?:          boolean
     edgeSource?:       string
     edgeTarget?:       string
     edgeArity?:        string
+    edgeGuard?:        string
+    edgeKind?:         string
+    edgeDuration?:     string
+    edgeTime?:         string
+    places?:           string
+    tokens?:           string
+    capacity?:         string
+    duration?:         string
+    start?:            string
     hierarchy?:        boolean
     deep?:             boolean
+    descend?:          string[]
+    reverse?:          string[]
     onlyConnected?:    boolean
     collapse?:         boolean
     qualified?:        boolean
+    ordered?:          boolean
+    markUncovered?:    "none" | "referenced" | "coverage" | "all"
+    nest?:             SchemaDiagramNest
     properties?:       string[]
-    config?:           Partial<GradiaConfig>
+    config?:           SchemaGradiaConfig
 }
 type SchemaFormat = {
     type?:             "auto" | "complex" | "compact" | "concise"
@@ -154,13 +193,31 @@ type SchemaGradiaConfig = Partial<{
     "color-node-self-name":      string
     "color-node-self-box":       string
     "color-node-self-border":    string
+    "color-node-lifeline":       string
     "color-group-name":          string
     "color-group-box":           string
     "color-group-border":        string
+    "color-container-name":      string
+    "color-container-box":       string
+    "color-container-border":    string
+    "color-composite-border":    string
+    "color-node-pseudo-name":    string
+    "color-node-pseudo-box":     string
+    "color-node-pseudo-border":  string
+    "color-node-place-name":     string
+    "color-node-place-box":      string
+    "color-node-place-border":   string
     "color-edge-line":           string
     "color-edge-name":           string
     "color-edge-arity":          string
     "color-edge-halo":           string
+    "color-mark-violation":      string
+    "color-mark-critical":       string
+    "size-font-node":            number
+    "size-font-type":            number
+    "size-font-prop":            number
+    "size-font-edge":            number
+    "size-font-arity":           number
     "size-canvas-margin":        number
     "size-node-width-min":       number
     "size-node-width-max":       number
@@ -171,6 +228,7 @@ type SchemaGradiaConfig = Partial<{
     "size-edge-port-gap":        number
     "group-box-padding":         number
     "group-box-gap":             number
+    "container-box-padding":     number
     "graph-columns-max":         number
     "graph-channel-width-max":   number
     "graph-channel-width-min":   number
@@ -183,12 +241,28 @@ type SchemaGradiaConfig = Partial<{
     "hub-channel-width-min":     number
     "hub-node-gap":              number
     "hub-node-degree-max":       number
+    "hub-node-count-max":        number
     "grid-columns-max":          number
     "grid-columns-min":          number
     "grid-gap-horizontal":       number
     "grid-gap-vertical":         number
     "grid-node-width-equal":     boolean
     "grid-node-height-equal":    boolean
+    "sequence-column-gap":       number
+    "sequence-message-gap":      number
+    "tree-level-gap":            number
+    "tree-sibling-gap":          number
+    "tree-row-max":              number
+    "tree-stack-min":            number
+    "tree-stack-double":         boolean
+    "tree-node-width-equal":     boolean
+    "tree-horizontal":           boolean
+    "gantt-unit-width":          number
+    "gantt-unit-name":           string
+    "gantt-critical":            boolean
+    "mark-violation":            boolean
+    "layer-numbered":            boolean
+    "slice-numbered":            boolean
 }>
 ```
 
@@ -206,17 +280,22 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE it discriminates objects and anchors `[[xxx]]` references
 
 -   `SchemaObject.name?: string`:
-    exact artifact name (level 1) or name regex (deeper levels),
-    BECAUSE artifacts are fixed documents, deeper names need a rule only
+    exact artifact name (level 1) or name regex (deeper levels), where a
+    level 1 object kind with neither `name` nor `id` is a *recurring*
+    artifact, which any number (also none) of level 1 objects of its
+    kind match, all in its `file`,
+    BECAUSE artifacts are fixed documents, deeper names need a rule only,
+    while a catalog of equally shaped artifacts knows no fixed names
 
 -   `SchemaObject.id?: string`:
     short locally-unique identifier the object explicitly carries in its heading,
     BECAUSE stable ids keep `[[xxx]]` references free of prose names
 
 -   `SchemaObject.file?: string`:
-    Markdown file the level 1 artifact is generated into and resides in,
+    Markdown file the level 1 artifact is generated into (by `init`),
     optionally shared with the other artifacts carrying the same file,
-    BECAUSE artifacts must map deterministically onto files
+    BECAUSE artifacts must map deterministically onto files when created,
+    while every `.md` file below the base directory is parsed afterwards
 
 -   `SchemaObject.desc?: string`:
     prose description of the object kind,
@@ -253,10 +332,38 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE a lifecycle is only trustworthy when its dead-ends and
     livelocks are ruled out
 
--   `SchemaObject.diagram?: SchemaDiagram`:
-    diagram generated for every object of this kind (left out when the
-    configuration is emitted compressed by level 2 or higher),
-    BECAUSE relations buried in references are graspable only when drawn
+-   `SchemaObject.badge?: SchemaBadge`:
+    badge icon drawn inside the node box of every object of this kind in
+    every diagram (left out when the configuration is emitted compressed
+    by level 2 or higher),
+    BECAUSE the nature of a node is recognized at a glance from an icon,
+    while its type label has to be read
+
+-   `SchemaBadge`:
+    a fixed icon, or the icon the value of the `property` of an object
+    maps onto through `map` (a mapped value of an `enum(...)` valued
+    property has to be one of its members), else the `default` icon,
+    else none,
+    BECAUSE the kind alone does not always tell the nature of an object
+    -- a `Server` node and a `Function` node deserve different icons
+
+-   `SchemaObject.multiple?: SchemaMultiple`:
+    the several instances an object of this kind stands for, drawn as a
+    stack of node boxes in every diagram: whenever the value of the
+    `property` matches the (unanchored) regular expression `pattern`,
+    e.g. `0..n per environment` matched by a pattern for a range with an
+    upper bound beyond 1 (left out when the configuration is emitted
+    compressed by level 2 or higher),
+    BECAUSE a replicated node is a different operational beast than a
+    single one, yet both are specified by one object
+
+-   `SchemaObject.diagram?: SchemaDiagram | SchemaDiagram[]`:
+    diagram, or list of diagrams (rendered in their order), generated for
+    every object of this kind (left out when the configuration is emitted
+    compressed by level 2 or higher), where merged configuration files
+    match the diagrams of a list by their `type`,
+    BECAUSE relations buried in references are graspable only when drawn,
+    and the same relations often tell more than one story
 
 -   `SchemaObject.format?: SchemaFormat`:
     HTML/PDF rendering format of the objects of this kind (left out when
@@ -308,8 +415,19 @@ type SchemaGradiaConfig = Partial<{
     diagram derived for every object of an object kind,
     BECAUSE the relations of a specification are graspable only when drawn
 
--   `SchemaDiagram.type?: "graph" | "hub" | "grid"`:
+-   `SchemaDiagram.type?: "graph" | "hub" | "grid" | "state" | "layer" |
+    "slice" | "tree" | "matrix" | "sequence" | "petri" | "gantt"`:
     diagram shape: `graph` (free), `hub` (centered), `grid` (edge-less),
+    `state` (state machine, with the `automaton` flags as pseudo-states),
+    `layer` (stacked bands, with the `nest` containers as the layers),
+    `slice` (side-by-side bands, with the `nest` containers as the
+    slices), `tree` (tidy tree, with the `nest` containers as the
+    parents), `matrix` (dependency structure matrix, with the `nest`
+    containers as the partitions), `sequence` (sequence diagram, with
+    the edge objects as the messages), `petri` (Petri net, with the
+    `places` objects as the places and all other nodes as the transitions),
+    `gantt` (Gantt chart, with the nodes as the tasks, the edges as their
+    dependencies, and the `nest` containers as the partitions),
     BECAUSE one object set tells different stories as different shapes
 
 -   `SchemaDiagram.nodes?: string`:
@@ -320,6 +438,12 @@ type SchemaGradiaConfig = Partial<{
     comma-separated `[[xxx]]` patterns of the objects acting as edges, not nodes,
     BECAUSE some relations are objects, yet still connect two nodes
 
+-   `SchemaDiagram.local?: boolean`:
+    whether the `nodes` and `edges` patterns match only the object
+    itself and its descendants (default: `false`),
+    BECAUSE the patterns match corpus-wide, while a per-object diagram
+    of a recurring kind shows the own subtree only
+
 -   `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
@@ -341,9 +465,12 @@ type SchemaGradiaConfig = Partial<{
     synthetic center, so their relation to it lives in a direction
     property instead
 
--   `SchemaDiagram.links?: "props" | "all"`:
-    edge source: property values (`props`) or also texts (`all`),
-    BECAUSE prose references are incidental and need an opt-in
+-   `SchemaDiagram.links?: "props" | "all" | string[]`:
+    edge source: property values (`props`), also texts (`all`), or the
+    values of the listed properties only (e.g. `[ DEPENDS-ON ]`, where
+    an empty list derives no reference edges at all),
+    BECAUSE prose references are incidental and need an opt-in, and a
+    diagram about one relation must not mix in the others
 
 -   `SchemaDiagram.labeled?: boolean`:
     whether the edges derived from property values carry the lower-cased
@@ -356,13 +483,35 @@ type SchemaGradiaConfig = Partial<{
 
 -   `SchemaDiagram.edgeTarget?: string`:
     edge property naming the target node (default: the first non-source
-    property whose value is a single reference),
+    property whose value is a single reference), where a `list(...)`
+    of references yields one edge per target,
     BECAUSE the convention breaks on multiple references per object
 
 -   `SchemaDiagram.edgeArity?: string`:
     edge property carrying the edge arity (default: `ARITY`),
     BECAUSE cardinality labels are named domain-specifically
 
+-   `SchemaDiagram.edgeGuard?: string`:
+    edge property whose value follows the edge name in brackets
+    (e.g. `submit [complete]`), rendered italic in a `state` diagram,
+    BECAUSE a transition is only understood together with its condition
+
+-   `SchemaDiagram.edgeKind?: string`:
+    edge property whose value is the message kind of a `sequence`
+    diagram: `Call` (the default), `Signal`, `Return`, `Create`, or
+    `Destroy` (case-insensitive, plus the Gradia names `sync` and `async`),
+    BECAUSE a call, a notification, and a response read differently
+
+-   `SchemaDiagram.edgeDuration?: string`:
+    edge property whose value is the duration constraint of a call of a
+    `sequence` diagram up to its return (e.g. `< 200ms`),
+    BECAUSE response time budgets belong to the interaction they bound
+
+-   `SchemaDiagram.edgeTime?: string`:
+    edge property whose value is the time constraint or observation at
+    the start of a message of a `sequence` diagram (e.g. `t = now`),
+    BECAUSE some interactions are defined by their timing
+
 -   `SchemaDiagram.hierarchy?: boolean`:
     whether containment edges derive from the nesting (default: `false`),
     BECAUSE the nesting carries no reference and would stay invisible
@@ -372,8 +521,54 @@ type SchemaGradiaConfig = Partial<{
     counted as the arity (default: `false`),
     BECAUSE the relations between coarse objects live in their fine parts
 
+-   `SchemaDiagram.descend?: string[]`:
+    child object kinds whose references (and those of their descendants
+    of the listed kinds) count as the uncounted own references of their
+    node, labeled with the lower-cased kind under `labeled` (e.g.
+    `[ MESSAGE ]`, so an interaction references the components its
+    messages involve),
+    BECAUSE a relation can live in a part of an object without the
+    whole object's references being worth counting
+
+-   `SchemaDiagram.reverse?: string[]`:
+    properties whose reference edges point back from the referenced
+    object onto the referencing node (e.g. `[ CONSUMES ]`, so a unit
+    consuming a resource yields the arc from the resource to the unit),
+    BECAUSE a relation drawn against the direction of its reference
+    keeps the references of the specification pointing backward
+
+-   `SchemaDiagram.places?: string`:
+    comma-separated `[[xxx]]` patterns of the node objects acting as the
+    places of a `petri` diagram, all other nodes acting as its
+    transitions (without it, Gradia infers them from the arcs),
+    BECAUSE the kind of an object, not its position in the net, tells
+    whether it holds items or does work
+
+-   `SchemaDiagram.tokens?: string`:
+    property of a place carrying its initial tokens (an integer of at
+    least 0) in a `petri` diagram,
+    BECAUSE the analysis of the net starts from its initial marking
+
+-   `SchemaDiagram.capacity?: string`:
+    property of a place carrying its capacity (an integer of at least 1)
+    in a `petri` diagram, an absent one leaving the place unbounded,
+    BECAUSE a bound decides whether a producer has to wait
+
+-   `SchemaDiagram.duration?: string`:
+    property of a task carrying its duration (a non-negative number of
+    time units) in a `gantt` diagram, an absent one making the task a
+    milestone,
+    BECAUSE the length of a bar is the one fact a schedule rests on
+
+-   `SchemaDiagram.start?: string`:
+    property of a task carrying its earliest start (a non-negative number
+    of time units, default: `0`) in a `gantt` diagram,
+    BECAUSE some tasks start at an agreed time, not when their
+    dependencies allow
+
 -   `SchemaDiagram.onlyConnected?: boolean`:
-    whether a `graph` drops its edge-less nodes (default: `false`),
+    whether a diagram (except a `hub` or `grid`) drops its edge-less
+    nodes (default: `false`),
     BECAUSE isolated nodes dilute a diagram about relationships
 
 -   `SchemaDiagram.collapse?: boolean`:
@@ -391,12 +586,25 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE in a coarse-to-fine specification the references then all
     point backward, i.e. upward
 
+-   `SchemaDiagram.markUncovered?: "none" | "referenced" | "coverage" | "all"`:
+    which uncovered nodes are marked as incomplete, i.e. drawn with a
+    border in the violation (signal) color: none (`none`, the default),
+    the ones lacking the reference coverage their `referenced` kind
+    demands (`referenced`), the ones the `coverage` reports count
+    as unreferenced while no report counts them as referenced
+    (`coverage`, e.g. the requirements no test case references), or
+    both (`all`),
+    BECAUSE a coverage lapse spotted in the overview is fixed sooner
+    than one listed among the lint warnings or coverage ratios only
+
 -   `SchemaDiagram.nest?: SchemaDiagramNest`:
     nesting of the nodes into container nodes,
     BECAUSE a containment drawn as a box beats one drawn as an edge
 
 -   `SchemaDiagramNest.properties?: string[]`:
-    properties whose single referenced object is the container of a node,
+    properties whose single referenced object is the container of a node
+    (in a `tree` diagram the first of several referenced objects, the
+    others becoming further parents),
     BECAUSE a `PART-OF` or `TIER` reference is a containment, not a relation
 
 -   `SchemaDiagramNest.parent?: boolean`:
@@ -419,7 +627,11 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE a bundle of references into a container reads as one edge onto it
 
 -   `SchemaDiagram.properties?: string[]`:
-    property names attached to the nodes as key/value annotations,
+    property names attached to the nodes as key/value annotations, none
+    of which may be a node attribute Gradia reserves (`url`, `type`,
+    `primary`, `group`, `cluster`, `parent`, `container`, `order`,
+    `badge`, `multiple`, `mark`, `layer`, `slice`, `state`, `region`,
+    `petri`, `tokens`, `capacity`, `duration`, or `start`),
     BECAUSE the node name alone rarely makes the nodes comparable
 
 -   `SchemaDiagram.config?: SchemaGradiaConfig`:
@@ -506,15 +718,24 @@ type SchemaGradiaConfig = Partial<{
 
 -   `SchemaGradiaConfig."color-node-*": string`:
     colors of the node boxes in their regular, primary, ghost, and self
-    role,
+    role, of the pseudo-states of a `state` diagram, of the places of a
+    `petri` diagram, and of the lifelines of a `sequence` diagram,
     BECAUSE the role of a node has to be readable at a glance
 
--   `SchemaGradiaConfig."color-group-*", "color-edge-*": string`:
-    colors of the group boxes and of the edges and their labels,
+-   `SchemaGradiaConfig."color-{group,container,composite,edge}-*": string`:
+    colors of the group, container, and composite boxes and of the
+    edges and their labels,
     BECAUSE both have to stay visible yet recede behind the nodes
 
--   `SchemaGradiaConfig."size-*", "group-box-*": number`:
-    geometry of the canvas, the node boxes, and the edge routing,
+-   `SchemaGradiaConfig."color-mark-*": string`:
+    colors of the violation marks and of the critical path of a `gantt`
+    diagram,
+    BECAUSE a flaw or a bottleneck has to stand out from the regular drawing
+
+-   `SchemaGradiaConfig."size-*", "group-box-*", "container-box-*": number`:
+    font sizes of the node names, types, properties, edge names, and
+    arities, and geometry of the canvas, the node, group, and container
+    boxes, and the edge routing,
     BECAUSE the geometry has to fit both the page and the text lengths
 
 -   `SchemaGradiaConfig."graph-*": number`:
@@ -522,32 +743,62 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE a free network needs room for its edges, not just its nodes
 
 -   `SchemaGradiaConfig."hub-*": number`:
-    layout of a `hub`: channel widths, node gap, and node degree,
+    layout of a `hub`: channel widths, node gap, node degree, and the
+    node count of a column before it wraps into two staggered sub-columns,
     BECAUSE a hub grows sideways and has to be bounded per side
 
 -   `SchemaGradiaConfig."grid-*": number | boolean`:
     layout of a `grid`: column bounds, tile gaps, and tile width,
     BECAUSE a catalog reads best as evenly sized tiles in stable columns
 
+-   `SchemaGradiaConfig."sequence-*": number`:
+    layout of a `sequence`: the gap between the lifelines and between
+    the messages,
+    BECAUSE an interaction reads top-down only with room between its steps
+
+-   `SchemaGradiaConfig."tree-*": number | boolean`:
+    layout of a `tree`: level and sibling gaps, the nodes per row, the
+    stacking of leaf siblings, equal node widths, and a horizontal
+    orientation,
+    BECAUSE a wide or deep hierarchy has to fit the page width
+
+-   `SchemaGradiaConfig."gantt-*": number | string | boolean`:
+    layout of a `gantt`: the width and the name of a time unit and the
+    marking of the critical path,
+    BECAUSE the time scale of a schedule is domain-specific
+
+-   `SchemaGradiaConfig."mark-violation", "layer-numbered", "slice-numbered": boolean`:
+    whether violations are marked at all (e.g. the cycles of a `matrix`
+    or the cross links of a `tree`) and whether the bands of a `layer`
+    or `slice` diagram are numbered,
+    BECAUSE a structure which is legitimate in one domain is a flaw in another
+
 ### Links
 
 The edges are derived from the `[[xxx]]` references of the node objects
 -- from their property values only, or, with `links: all`, from their
-descriptions as well. Every referenced object is lifted to its nearest
+descriptions as well, or, with a list of property names, from the
+values of these properties only. Every referenced object is lifted to its nearest
 ancestor-or-self within the node set, so a reference onto the scenario
 of a use case yields an edge onto the use case. With `deep: true` the
 references of all descendants of a node object count as its own and the
 number of references behind an edge becomes its arity, so a diagram of
 coarse objects (like the artifacts of a whole specification) shows the
-relations living in their fine-grained parts. With `labeled: true` an
-edge derived from a property value carries the lower-cased property key
-as its label, telling the edges of different properties apart, while
-the edges derived from descriptions stay unlabeled.
+relations living in their fine-grained parts. With `descend` the
+references of the descendants of the listed kinds alone count as the
+node's own, uncounted, so one edge per target remains. With `labeled:
+true` an edge derived from a property value carries the lower-cased
+property key as its label (or, for a `descend` descendant, its
+lower-cased kind), telling the edges of different properties apart,
+while the edges derived from descriptions stay unlabeled.
 
 An object acting as an edge (`edges`) connects its parent object to the
 object its target property references. Where an edge object is a sibling
 of its own source instead of a child of it, `edgeSource` names the
-property carrying that source.
+property carrying that source, and where the target property named by
+`edgeTarget` carries a `list(...)` of references, the edge object yields
+one edge per resolvable target. With `edgeGuard`, the value of the named
+property follows the name of every such edge in brackets.
 
 As the *nesting* of the objects carries no such reference, `hierarchy:
 true` additionally derives a containment edge from every node object to
@@ -561,14 +812,120 @@ This is what turns a parent object into the hub of its own children. A
 
 An object kind can additionally carry a `diagram` field, which derives
 a [Gradia](https://github.com/rse/gradia) diagram for every object of
-that kind. Its `type` selects the diagram shape (`graph`, `hub`, or
-`grid`), `nodes` and `edges` select the participating objects through
+that kind -- or a list of such diagram configurations, which derives
+all of them, in their order. Its `type` selects the diagram shape
+(`graph`, `hub`, `grid`, `state`, `layer`, `slice`, `tree`,
+`matrix`, `sequence`, `petri`, or `gantt`), `nodes` and
+`edges` select the participating objects through
 comma-separated `[[xxx]]` reference patterns (`nodes` defaults to the
-object itself plus all objects below it), and `center` names the object
+object itself plus all objects below it, and `local: true` restricts the
+matches of both patterns to the object itself plus all objects below it,
+as the patterns match corpus-wide), and `center` names the object
 a `hub` is projected onto (default: `self`). An edge object of the
 center targeting the center itself (a self-reference) places the center
 a second time among its outputs, rendered as a dashed "self" node.
 
+A `state` diagram is laid out like a `graph`, but draws a state machine:
+where its object kind carries an `automaton`, a single initial
+pseudo-state (a dot) leads into every node flagged `initial`, and every
+node flagged `final` leads into a single final pseudo-state (a
+bullseye), so a final node may still have outgoing edges. A `state`
+diagram accepts no `nest`, as every container would be a composite
+state needing an initial state of its own.
+
+A `layer` diagram draws a layered architecture: the `nest` container of
+a node names the band it sits in, the bands stack top-down in the
+document order of their first node and are numbered bottom-up (unless
+`config` sets `layer-numbered: false`), and the containers enclosing a
+container group its band into a cluster column. The containers are no
+nodes there, so the edges ending at a container are dropped, an edge
+pointing upwards against the layering is marked as a violation, and
+neither `nest.layout`, a lifting `nest.crossing`, nor `ordered` apply.
+A `slice` diagram is its side-by-side companion: the bands line up
+left-to-right (numbered only with `config` setting `slice-numbered:
+true`), the nodes of a band stack top-down, the enclosing containers
+group the bands into cluster rows, and an edge pointing back to a left
+band closing a direct cycle is marked as a violation.
+
+A `tree` diagram draws a tidy tree (or a forest of them): the `nest`
+container of a node becomes its parent, so a child-to-parent reference
+like `BROADER` or `PART-OF`, named by `nest.properties`, yields the
+tree, while the containers stay nodes. Where such a property carries
+several references (like a multiple `INHERITS`), the first one names
+the parent and the others further parents. Every other edge (the ones
+from the further parents included) is drawn as a dashed cross link and
+marked as a violation (unless `config` sets `mark-violation: false`, as
+for a legitimate multiple inheritance), so `links: []` derives a pure
+tree (plus its further parents). With
+`ordered: true` the children follow the document order. A `tree`
+diagram accepts neither `nest.layout` nor a lifting `nest.crossing`.
+
+A `matrix` diagram draws a dependency structure matrix: the nodes are
+both its rows and its columns, the cell of a row and a column counts the
+edges from the one to the other (a numeric arity counting as its
+number), and the nodes are ordered topologically (with `ordered: true`
+in document order instead), so all entries lie above the diagonal
+except the ones of the cycles, which are outlined and marked as
+violations (unless `config` sets `mark-violation: false`, as for
+relations where mutual references are regular). A `nest` container
+partitions its members, and the partitions are outlined on the
+diagonal: a container taking part in the relation itself stays a row
+and a column of its own, heading its partition, while a mere grouping
+object (without any edge) names the partition only. `qualified: true`
+puts the shared object kind into the corner. A `matrix` diagram accepts
+no `nest.layout`. It usually restricts the `links` onto the very
+relation it is about, e.g. `links: [ DEPENDS-ON ]`.
+
+A `sequence` diagram draws the edge objects (`edges`) as its messages,
+top-down in document order and never merged, so a repeated message
+stays: `edgeSource` and `edgeTarget` name the sender and the receivers,
+`edgeKind` the message kind (a `Return` answering the latest unanswered
+`Call` of its sender, which activates the callee until then),
+`edgeDuration` a duration constraint of a call, and `edgeTime` a time
+constraint at a message. Its participants are the senders and receivers
+of its messages, lined up in the order the messages first involve
+them (unless `nodes` restricts them), so `local: true` usually
+restricts the messages onto the own subtree. A `sequence` diagram
+derives no reference edges and hence accepts neither `links`,
+`hierarchy`, `deep`, `labeled`, `nest`, nor `ordered`, while `edgeKind`,
+`edgeDuration`, and `edgeTime` apply to it alone. Its messages are
+validated, each violation reported on its edge object: a participant is
+created only by the first message it takes part in, takes part in no
+message after its destruction, and a duration constraint belongs to a
+call answered by a return.
+
+A `petri` diagram draws a Petri net from the reference edges: the node
+objects matching `places` are its places (drawn as circles holding their
+`tokens` and showing their `capacity`), all other nodes its
+transitions, and every edge an arc, where `reverse` turns the edges of
+a consuming property into the arcs from the place to the transition, so
+both arc directions stem from references of the transitions. Gradia
+analyzes the net from its initial marking (within a bounded
+exploration budget) and marks the unbounded places (missing
+backpressure), the places holding a token in a deadlock, and the dead
+and non-live transitions. The net is validated, each violation reported
+on its object: the tokens are an integer of at least 0, the capacity one
+of at least 1 holding them, and an arc connects a place with a
+transition. A `petri` diagram accepts no `nest`, `places`, `tokens`,
+and `capacity` apply to it alone, and `tokens` and `capacity` require
+`places`.
+
+A `gantt` diagram draws a Gantt chart: the node objects are its tasks
+(one row each, a task without a `duration` being a milestone), the
+edges its finish-to-start dependencies (so a property referencing the
+*preceding* tasks is listed under `reverse`, as a dependency arrow runs
+from the predecessor), and the `nest` containers the partitions of its
+rows (like in a `matrix`, the containers themselves being no tasks).
+The `duration` and `start` options name the properties of the tasks
+carrying their duration and earliest start in abstract time units (a
+`gantt-unit-name` in `config` labels them), from which Gradia schedules
+the tasks as early as possible, draws the slack of every task, and
+marks the critical path. The schedule is validated, each violation
+reported on its object: the duration and the start are non-negative
+numbers, and the dependencies form no cycle. A `gantt` diagram accepts
+no `nest` layout or crossing, and `duration` and `start` apply to it
+alone.
+
 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
@@ -592,6 +949,11 @@ rendering options (e.g. `grid-columns-max: 2`) through to the diagram.
 As the Gradia defaults are dimensioned for a stand-alone canvas,
 SpecBook presets a compact geometry for every diagram, which `config`
 overrides: `size-canvas-margin: 8`, `size-node-height-scale: 2`,
+`size-font-type`, `size-font-edge`, and `size-font-arity: 19` (about
+20% over the Gradia defaults, as the diagrams are embedded at half
+their coordinate scale), `size-edge-track-gap: 20` (the parallel edges
+spread further apart), `graph-channel-width-max: 1000` (a capped
+channel squeezes its many edges into an unreadable bundle),
 `hub-node-gap: 10`, `hub-node-count-max: 6` (a `hub` column of more
 nodes wraps into two staggered sub-columns), `grid-gap-horizontal: 24`,
 `grid-gap-vertical: 12`, and `grid-columns-min: 4` (the square
@@ -670,7 +1032,12 @@ one ignores it), `maxCellHeight`
 the height of every other non-empty cell of its row before the HTML
 export folds its remaining text away, and `withUnusedProps`
 (default: `false`) unconditionally renders the defined but unused
-properties of that kind, as property table lines or table columns. In
+properties of that kind, as property table lines or table columns.
+Within a `concise` table, the name column takes a fixed fifth of the
+width, the description column two shares of the rest, and every property
+column one to two and a half shares by its longest word (its header
+included), so a property name or a reference kind label never breaks
+inside a narrow column. In
 the HTML/PDF export, a property absent from an object shows an "empty
 set" marker in place of its value, which tells it apart from a property
 given with an empty value.
@@ -725,7 +1092,7 @@ type SpecProperty = {
     BECAUSE a specification is one corpus of separately authored files
 
 -   `Spec.artifacts: SpecArtifact[]`:
-    all artifacts parsed from the Markdown files the SCHEMA references,
+    all artifacts parsed from the Markdown files below the base directory,
     BECAUSE the corpus is parsed as a whole to resolve references
 
 -   `SpecArtifact`:
@@ -837,16 +1204,20 @@ several such files, merged in order into one schema (the later files
 into the earlier ones, where the objects merge deeply and the elements
 of the lists are matched by their identity). If no particular schema is
 given, the standard schema configuration bundled with **SpecBook**
-applies.
+applies. Beside it (named `std`), **SpecBook** bundles the meta schema
+configuration (named `meta`), which describes a schema configuration
+itself, and the project management schema configuration (named `pm`),
+which plans the delivery of the solution a specification describes.
 
 SpecBook SPEC Model
 -------------------
 
 ### Artifacts
 
-A specification consists of Markdown *artifact* files, which the SCHEMA
-Model references by their `file` fields and which are resolved against
-a base directory. Every file has to start with
+A specification consists of Markdown *artifact* files: every `.md` file
+below a base directory (recursively, except below `.`-prefixed entries),
+whatever its name, while the `file` fields of the SCHEMA Model only tell
+where the generated files are created. Every file has to start with
 a "frontmatter" block carrying the `Created:` and `Modified:` timestamps
 (format `yyyy-LL-dd HH:mm`):
 
@@ -859,10 +1230,11 @@ Modified: 2026-06-18 10:18
 
 Every level 1 heading opens a new *artifact*, so usually each file
 carries exactly one. Several artifacts nevertheless reside in one file
-whenever the schema configures the same `file` for them: they then
-follow each other on level 1, below the single frontmatter block of that
-file. Both ATX headings (`# <text/>`, `## <text/>`, ...) and Setext
-headings (`<text/>` underlined with `===` or `---`) are supported.
+whenever the schema configures the same `file` for them (or the author
+places them so): they then follow each other on level 1, below the
+single frontmatter block of that file. Both ATX headings (`# <text/>`,
+`## <text/>`, ...) and Setext headings (`<text/>` underlined with `===`
+or `---`) are supported.
 
 As the timestamps are a property of the *file* and not of the individual
 artifact, the normalized Markdown export -- which merges the entire
@@ -1027,6 +1399,13 @@ The event is created and configured but not visible to attendees,
 BECAUSE an event needs a private setup phase.
 ```
 
+The `, BECAUSE ` keyword is the source syntax and stays English in every
+document language, while the HTML/PDF export follows the bold `BECAUSE`
+with its non-bold, lower-case translation in parentheses into the
+language of the `LANG` property of the title object (`BECAUSE (weil)`
+for `de`, `BECAUSE (parce que)` for `fr`, and so on, while `en` and an
+unknown language render the bare `BECAUSE`).
+
 The rationale ends with its paragraph: all blocks following it (further
 paragraphs, embedded images, and diagrams) form the *elaboration*, which
 is rendered below the statement and its rationale, so the description
@@ -1043,8 +1422,9 @@ BECAUSE an event needs a private setup phase.
 ### Wiki-Style References
 
 A `[[<reference/>]]` anywhere in a name, property value, description, or
-rationale (except inside a fenced code block, whose code stays verbatim,
-so e.g. a shell test `[[ -f x ]]` is no reference) is a Wiki-style
+rationale (except inside a fenced code block or an inline code span,
+whose code stays verbatim, so e.g. a shell test `[[ -f x ]]` is no
+reference) is a Wiki-style
 reference to another object, which is checked
 for unique resolvability and rendered as a hyperlink in the HTML/PDF
 exports. A reference is a `.`-separated path of segments, where each