ddduck 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 diegomarino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# ddduck
+
+ddduck defines a small, machine-readable product-spec format. The framework keeps
+schemas, validators, policies, and generators separate from each consumer product.
+
+Start with [the getting-started guide](docs/getting-started.md) for a working first product.
+Then use [the model guide](docs/model.md), [the model reference](docs/model-reference.md),
+[the CLI reference](docs/cli.md), and [the architecture guide](docs/architecture.md) as needed.
+
+## Model graph
+
+Every product renders to a verified graph of its model — the ownership spine
+(Model → Domain → members), reference edges, and a legend decoding shapes and
+line styles. `ddduck generate` produces it as a deterministic SVG. This
+framework's own model:
+
+![ddduck model graph: the framework's Model, its Domains and owned Concepts, Interfaces, Guarantees, and Use Cases, with a legend](https://raw.githubusercontent.com/diegomarino/ddduck/main/docs/ddd/generated/graph/model-graph.svg)
+
+## Product layout
+
+A consumer product owns one product root. Documentation-centric repositories can use `docs/ddd/`;
+small or dedicated product repositories can use `ddd/`:
+
+```text
+docs/ddd/
+  product.yaml
+  model/
+    domains/
+    concepts/
+    relationships/
+    use-cases/
+    interfaces/
+    guarantees/
+  decisions/
+  generated/
+    docs/
+    graph/
+```
+
+`product.yaml` and files under `model/` are canonical source. `generated/` is derived
+output: never edit it by hand.
+
+Repository-local ddduck tool metadata lives outside the product root in `.ddduck/`. For example,
+this framework repository stores its own model in `docs/ddd/` and records that selection in:
+
+```json
+{
+  "schemaVersion": "1",
+  "productRoot": "docs/ddd",
+  "ignore": ["vendor", "target", "build", "dist", "__pycache__"]
+}
+```
+
+`ignore` lists directory names the scanners skip on top of the always-ignored
+dot-directories and `node_modules`; it is written pre-filled by `ddduck init`
+and fully editable (see [the CLI reference](docs/cli.md)).
+
+## Authoring
+
+Install the CLI from npm:
+
+```bash
+npm install -g ddduck
+```
+
+Or run it from a local checkout for contributing (`npm install`, then `npm link` or
+`node <checkout>/scripts/ddduck.mjs` — see
+[Install ddduck](docs/getting-started.md#install-ddduck)). Create a product root with:
+
+```bash
+ddduck init ddd --id model:<product-id>
+```
+
+`--root <path>` is always the explicit override; without it, ddduck resolves the enclosing
+product root, then `.ddduck/config.json`, then a unique repository candidate, and fails with a
+diagnostic when the choice is ambiguous. The mutation surface is deliberately narrow — `check`,
+`generate`, and the `create`/`move`/`split`/`retire` Guarantee lifecycle commands — and every
+successful source mutation regenerates the derived views. The canonical resolution rules and
+command contracts live in [the CLI reference](docs/cli.md#product-root-resolution).
+
+YAML remains the normal human-authored source format, with `ddduck check` as the deterministic
+safety net.
+
+## Agent skill
+
+Install the evidence-backed model maintenance skill in a consumer repository:
+
+```bash
+ddduck install skill update-ddduck-specs --repo <repository-root>
+```
+
+`--repo` defaults to the current directory. See [the CLI reference](docs/cli.md#install-an-agent-skill)
+for the installed layout, host invocation, and plan-only behavior.
+
+## Product queries
+
+The bounded read API — `ddduck query node|neighbors|impact|anchors|spec|context` — emits JSON
+only (`--json` is optional and a no-op) and never writes source or generated output. Default
+queries expose only active Guarantees; pass `--history` to read a retired or split Guarantee's
+historical record instead of its lifecycle redirect. The full query table and response contract
+live in [the CLI reference](docs/cli.md#queries).
+
+### Bounded context packs
+
+`ddduck query context` is the agent-facing bounded read for an explicit selection: full
+canonical records for the selected IDs, every direct edge that touches them, one-hop perimeter
+summaries, and a SHA-256 `sourceDigest` identifying the source snapshot — authoritative only
+for reads that did not race a mutation. Its boundaries and refusal rules are documented in
+[the CLI reference](docs/cli.md#queries); responses conform to
+[`schemas/context-pack.schema.json`](schemas/context-pack.schema.json).
+
+## Agent-readiness evals
+
+Maintainer surface: see
+[Agent-readiness evals in the development guide](https://github.com/diegomarino/ddduck/blob/main/docs/development.md#agent-readiness-evals).
+
+## Revision-scoped FR-to-code audits
+
+Maintainer surface: see
+[Revision-scoped FR-to-code audits in the development guide](https://github.com/diegomarino/ddduck/blob/main/docs/development.md#revision-scoped-fr-to-code-audits).
+
+## Framework contracts
+
+Global `PolicySpec` declarations live in `policies/`, outside any product graph: see
+[Framework contracts in the development guide](https://github.com/diegomarino/ddduck/blob/main/docs/development.md#framework-contracts).

package/docs/architecture.md

@@ -0,0 +1,77 @@
+# Architecture
+
+ddduck keeps product facts separate from framework contracts. Canonical product YAML is the
+source of truth. Schemas, policies, validation, generation, and query code interpret that source;
+they do not become product nodes. Generated views flow outward and are never canonical input.
+
+```mermaid
+flowchart LR
+  subgraph Product[Selected product root]
+    Source[product.yaml and model YAML]
+    Decisions[decisions]
+    Derived[generated views]
+  end
+  subgraph Framework[ddduck framework]
+    Schemas[Schemas and policies]
+    Check[Validation]
+    Generate[Generators]
+    Query[JSON query]
+  end
+  Source --> Check
+  Decisions --> Check
+  Schemas --> Check
+  Check --> Generate
+  Generate --> Derived
+  Source --> Query
+  Decisions --> Query
+```
+
+## Authoring and verification
+
+After manual canonical YAML edits, authors validate source with `ddduck check --source-only`, run
+`ddduck generate`, then run default `ddduck check`. Default `check` verifies source and that
+required generated views are fresh, so it cannot precede generation after a source edit.
+
+```mermaid
+flowchart LR
+  Edit[Author canonical YAML] --> SourceCheck[ddduck check --source-only]
+  SourceCheck -->|valid| Generate[ddduck generate]
+  SourceCheck -->|invalid| Fix[Fix diagnostics]
+  Generate --> FreshCheck[ddduck check]
+  FreshCheck --> Views[Fresh Markdown and graph views]
+  Fix --> Edit
+```
+
+## Staged lifecycle mutation
+
+Guarantee mutations run against a contained staging copy. The CLI validates the complete staged
+product and regenerated views before publication. A rejected operation publishes no intended
+canonical or generated change; filesystem interruption beyond that tested boundary is a recovery
+concern, not a database transaction guarantee.
+
+```mermaid
+flowchart LR
+  Request[create move split or retire] --> Lock[Acquire product lock]
+  Lock --> Stage[Copy canonical source to staging]
+  Stage --> Validate[Transform, validate, generate]
+  Validate -->|valid| Publish[Publish canonical and generated views]
+  Validate -->|invalid| Cleanup[Discard staging and release lock]
+  Publish --> Release[Release lock and report result]
+```
+
+## Query boundary
+
+Queries are read-only and require `--json`. A context query returns selected canonical records,
+direct touching edges, one-hop summaries for unselected neighbors, and a source digest. It does
+not recursively expand context or write canonical or generated files.
+
+```mermaid
+sequenceDiagram
+  participant Caller
+  participant CLI as ddduck query
+  participant Product as Canonical product root
+  Caller->>CLI: query context --id ... --root ... --json
+  CLI->>Product: Load and resolve selected source
+  CLI-->>Caller: Selected records, edges, summaries, digest
+  Note over CLI,Caller: No source or generated output is written
+```

package/docs/cli.md

@@ -0,0 +1,239 @@
+# CLI reference
+
+`ddduck` operates on a selected product root. Run `ddduck --help`, or pass `--help` anywhere
+after a command name (including `ddduck <command> <subcommand> --help`), for the built-in usage
+lines. Option values may be written as `--option value` or `--option=value`; a value that begins
+with `--` must use the `--option=value` form. Every command rejects unknown options, duplicate
+options, missing option values, and unexpected positional arguments. Expected failures write a
+concise diagnostic (multi-error validation reports keep one line per error) plus a safe next
+action to standard error and exit nonzero; errors without a specific next action fall back to a
+command-specific hint. Help exits zero.
+
+## Product root resolution
+
+Product-facing commands accept `--root <product-root>`. When `--root` is omitted, ddduck resolves
+the root in this order:
+
+1. An enclosing product root found by walking upward from the current directory.
+2. `.ddduck/config.json` `productRoot`, when present and the current directory is not inside a
+   product root.
+3. A unique primary `product.yaml` candidate under the repository boundary.
+4. A relevant example candidate only when no primary candidate exists.
+
+Discovery admits a candidate by shape — a ddduck `product.yaml` with a sibling `model/`
+directory — not by full validation, so a broken product still resolves and the command's own
+validation reports its errors. Discovery excludes `.git/`, `.ddduck/`, `node_modules/`,
+`generated/`, `.superpowers/`, `.worktrees/`, `.ddduck-init-stage-*` staging left by an
+interrupted `init` (the next `init` of the same destination sweeps that debris; staging for
+other destinations is never touched), and test fixtures. Multiple
+viable primary roots
+fail and ask for `--root`, listing every candidate and flagging any that fail validation; the
+resolver never uses an arbitrary first match.
+
+Use `.ddduck/config.json` for a repository default:
+
+```json
+{
+  "schemaVersion": "1",
+  "productRoot": "docs/ddd",
+  "ignore": ["vendor", "target", "build", "dist", "__pycache__"]
+}
+```
+
+`ignore` lists extra directory names (basenames only, no globs) that
+every ddduck scanner skips, in addition to the always-skipped dot-directories
+and `node_modules`. Omit the key to accept the defaults shown above; set it to
+`[]` to skip nothing beyond the built-in defaults. `ddduck init` writes this
+file pre-filled when it does not already exist.
+
+## Install an agent skill
+
+```text
+ddduck install skill update-ddduck-specs [--repo <repository-root>]
+```
+
+`--repo` defaults to the current directory. The installer chooses the least intrusive host
+topology from the repository's existing directories:
+
+```text
+no .agents/ or .claude/   -> .agents/skills/update-ddduck-specs/SKILL.md
+.agents/ only             -> .agents/skills/update-ddduck-specs/SKILL.md
+.claude/ only             -> .claude/skills/update-ddduck-specs/SKILL.md
+.agents/ and .claude/     -> .agents/skills/update-ddduck-specs/SKILL.md
+                             .claude/skills/update-ddduck-specs -> ../../.agents/skills/update-ddduck-specs
+```
+
+The installer writes `.ddduck/agent-skills.lock.json` with the selected canonical path, host
+adapters, package version, and installed `SKILL.md` SHA-256. It does not create a host directory
+for a host that is absent from the repository, except for the `.agents/` fallback when no host
+directory exists. On success it prints one result line naming the action (`created`, `upgraded`,
+or `no-op`), the repository, the canonical skill path, and the lock path. It does not accept
+`--json`.
+
+Invoke the skill from the relevant host:
+
+```text
+Codex:  $update-ddduck-specs
+Claude: /update-ddduck-specs
+```
+
+The skill defaults to plan-only; changing a product model requires explicit apply authorization.
+Its workflow behavior is defined by the installed `SKILL.md` (and its packaged
+[canonical source](../skills/update-ddduck-specs/SKILL.md)).
+
+This package is published to npm as `ddduck`; install the CLI globally with `npm install -g ddduck`
+(see [the getting-started guide](getting-started.md#install-ddduck)).
+
+## Common behavior
+
+Product writes are `init`, `generate`, `create`, `move`, `split`, and `retire`; successful
+mutations regenerate all required views. `check` and every `query` are read-only. A successful
+`check` is silent. Successful product mutations print one concise result line, or one JSON result
+object when `--json` is available.
+
+## `init`
+
+```text
+ddduck init [destination] --id model:<product-id> [--json]
+```
+
+| Option or argument | Required | Default                       | Meaning                                           |
+| ------------------ | -------- | ----------------------------- | ------------------------------------------------- |
+| `destination`      | no       | config, then `ddd/` directory | Empty directory to create as the product root.    |
+| `--id`             | yes      | none                          | Root Model ID, matching `model:<lowercase-slug>`. |
+| `--json`           | no       | false                         | Emit one JSON result object instead of text.      |
+
+`init` writes the canonical directory layout, `product.yaml`, and fresh generated docs and graph
+views. It refuses a non-empty destination. On success it reports the Model ID, normalized root,
+`product.yaml`, and all generated paths as one text line or, with `--json`, one object containing
+`operation`, `root`, `affectedIds`, `canonicalPaths`, and `generatedPaths`. On failure it exits
+nonzero without reporting success.
+
+## `check`
+
+```text
+ddduck check [--root <product-root>] [--base <previous-product-root>] \
+  [--docs-root <docs-root> ...] [--source-only]
+```
+
+| Option          | Default       | Meaning                                                                                                                   |
+| --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `--root`        | resolved root | Product root to validate.                                                                                                 |
+| `--base`        | none          | Previous product root used to check historical Guarantee retention.                                                       |
+| `--docs-root`   | product root  | Directory scanned for documentation references; repeatable. Passing it replaces the default product-root scope.           |
+| `--source-only` | false         | Validate canonical source only; skip derived-view freshness checks and skip documentation references inside `generated/`. |
+
+By default, `check` validates canonical source, then requires fresh generated Markdown and graph
+views. Documentation references are validated only inside the product root; pass one or more
+`--docs-root` directories to widen (and replace) that scope, mirroring the framework's own
+repository-wide gate. It writes nothing and is quiet on success. It exits nonzero for invalid source, stale
+views, invalid roots, invalid options, a busy root (`.ddduck-operation.lock` held by a live
+ddduck operation), or leftover state from an interrupted operation
+(`.ddduck-operation.lock`, `.ddduck-operation.reclaim`, or `.ddduck-operation-stage-*` with no
+live owning process); running any mutation, such as `ddduck generate`, reclaims that leftover
+state.
+
+## `generate`
+
+```text
+ddduck generate [--root <product-root>] [--json]
+```
+
+| Option   | Default       | Meaning                                                               |
+| -------- | ------------- | --------------------------------------------------------------------- |
+| `--root` | resolved root | Product root to validate and regenerate.                              |
+| `--json` | false         | Emit one JSON mutation-result object instead of the text result line. |
+
+`generate` validates canonical source before writing `generated/docs/model-overview.md`,
+`generated/graph/model-graph.json`, and `generated/graph/model-graph.ndjson`. A successful text
+result identifies the root, canonical paths (none for generate), and generated paths. It exits
+nonzero without an intended product mutation if validation or contained-output checks fail.
+
+## Guarantee mutations
+
+All mutation results identify the selected root, affected Guarantee IDs, canonical paths, and
+fresh generated paths. Append `--json` to any command below for one JSON result object.
+
+### `create guarantee`
+
+```text
+ddduck create guarantee --origin <origin> --classification <invariant|acceptance-criterion> \
+  --owner <domain-id> --statement <text> [--root <product-root>] [--json]
+```
+
+`--origin`, `--classification`, `--owner`, and `--statement` are required. The root is resolved
+through the common product-root rules. `create` allocates the next stable ID for the origin and
+classification, writes its canonical Guarantee YAML, updates the owning Domain, and regenerates
+views. It exits nonzero if the owner is unknown or any input or staged product is invalid.
+
+### `move guarantee`
+
+```text
+ddduck move guarantee <guarantee-id> --to <domain-id> [--root <product-root>] [--json]
+```
+
+`<guarantee-id>` and `--to` are required. `move` requires an active Guarantee and an existing
+destination Domain. It changes ownership, records the prior owner in `ownershipHistory`, updates
+both Domain records, and regenerates views. It exits nonzero without an intended mutation when
+the Guarantee is inactive, missing, already owned by the destination, or the staged product fails.
+
+### `split guarantee`
+
+```text
+ddduck split guarantee <guarantee-id> --into <successor-id[,successor-id ...]> \
+  --decision ADR-NNN [--root <product-root>] [--json]
+```
+
+`<guarantee-id>`, `--into`, and `--decision` are required. `--into` accepts one or more distinct
+active successor IDs; the decision must resolve in the product decision registry.
+`split` preserves the source ID, marks it `split`, records its successors and lifecycle decision,
+then regenerates views. It exits nonzero without an intended mutation if an active UseCase or
+DomainInterface would retain a reference to the non-effective Guarantee.
+
+### `retire guarantee`
+
+```text
+ddduck retire guarantee <guarantee-id> --decision ADR-NNN [--root <product-root>] [--json]
+```
+
+`<guarantee-id>` and `--decision` are required. `retire` requires an active Guarantee and a
+registered decision, marks the Guarantee `retired`, records `lifecycleDecision`, and regenerates
+views. The same active UseCase and DomainInterface safety gate applies. Invalid input or a failed
+staged validation exits nonzero without an intended mutation.
+
+## Queries
+
+Every query emits exactly one JSON document and writes no source or generated output. While a
+live ddduck mutation holds `.ddduck-operation.lock`, queries and `check` fail with a busy
+diagnostic instead of reading a partially published snapshot. A read racing the very start of a
+mutation, before the lock exists, may still observe a partial snapshot, so `sourceDigest` is
+authoritative only for reads that did not race a mutation. JSON is
+the only output format, so `--json` is optional and accepted as a no-op for compatibility. The
+document contains `schemaVersion`, `query`, `rootModelId`, `result`, and
+`diagnostics`. Non-context query roots are resolved through the common product-root rules.
+`context` requires an explicit `--root`. Non-context queries accept optional `--history`; without it, a split or retired
+Guarantee resolves to its lifecycle redirect rather than its historical contract.
+
+```mermaid
+sequenceDiagram
+  participant Caller
+  participant CLI as ddduck query
+  participant Model as Canonical product root
+  Caller->>CLI: query context --id ... --root ... --json
+  CLI->>Model: Load and resolve selected source
+  CLI-->>Caller: Full selection, direct edges, summaries, digest
+  Note over CLI,Caller: Read-only; no source or generated output is written
+```
+
+| Command                                                                    | Required options | Result                                                                  |
+| -------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------- |
+| `ddduck query node --id <id> [--root <root>] [--history] [--json]`         | `--id`           | Full canonical node and product-relative source path.                   |
+| `ddduck query neighbors --id <id> [--root <root>] [--history] [--json]`    | `--id`           | Deterministically sorted incoming and outgoing edges.                   |
+| `ddduck query impact --id <id> [--root <root>] [--history] [--json]`       | `--id`           | Reverse impact closure over ownership and behavioral references.        |
+| `ddduck query anchors --id <id> [--root <root>] [--history] [--json]`      | `--id`           | Evidence, reachable decisions, policies, and view freshness.            |
+| `ddduck query spec [--id <model-id>] [--root <root>] [--history] [--json]` | none             | Root, domains, view freshness, and verification commands.               |
+| `ddduck query context --id <id> [--id <id> ...] --root <root> [--json]`    | `--id`, `--root` | Selected records, touching edges, one-hop summaries, and source digest. |
+
+`context` accepts one or more distinct, repeatable `--id` options; it rejects `--history`.
+Its selected records are complete, while unselected endpoints appear only as one-hop summaries.
+The command does not recursively expand the perimeter.

package/docs/getting-started.md

@@ -0,0 +1,98 @@
+# Getting started
+
+This executable journey creates a product with one Domain, one Concept, and one Guarantee.
+
+## Install ddduck
+
+Install the published CLI globally from npm:
+
+```sh
+npm install -g ddduck
+ddduck --help
+```
+
+To contribute or run an unreleased revision, work from a local checkout instead. Either put the
+`ddduck` bin on `PATH` with `npm link`:
+
+```sh
+git clone <ddduck-repository-url> ddduck
+cd ddduck
+npm install
+npm link
+ddduck --help
+```
+
+or skip linking and invoke the CLI directly from the checkout:
+
+```sh
+node <checkout>/scripts/ddduck.mjs --help
+```
+
+## Create the first product
+
+Run the complete Bash block from an empty working directory with `ddduck` on `PATH`.
+
+```mermaid
+flowchart LR
+  Source[Manual canonical YAML edit] --> SourceCheck[ddduck check --source-only]
+  SourceCheck -->|valid| Generate[ddduck generate]
+  SourceCheck -->|invalid| Diagnostic[Actionable diagnostic]
+  Generate --> FreshCheck[ddduck check]
+  FreshCheck --> Docs[Generated Markdown is fresh]
+  FreshCheck --> Graph[Generated graph is fresh]
+```
+
+```bash
+ddduck init ddd --id model:library
+
+cat > ddd/model/domains/catalog.yaml <<'YAML'
+schemaVersion: "1"
+kind: Domain
+id: domain:catalog
+model: model:library
+name: Catalog
+purpose: Organize the library catalog.
+concepts:
+  - concept:book
+interfaces: []
+guarantees: []
+YAML
+
+cat > ddd/model/concepts/book.yaml <<'YAML'
+schemaVersion: "1"
+kind: Concept
+id: concept:book
+model: model:library
+ownerDomain: domain:catalog
+name: Book
+purpose: Identify a catalogued book.
+YAML
+
+cat > ddd/product.yaml <<'YAML'
+schemaVersion: "1"
+kind: Model
+id: model:library
+name: library
+purpose: Define the library product.
+domains:
+  - domain:catalog
+useCases: []
+decisions: []
+YAML
+
+ddduck check --root ddd --source-only
+ddduck generate --root ddd
+ddduck check --root ddd
+ddduck create guarantee --origin catalog --classification invariant \
+  --owner domain:catalog --statement "A Book has a stable catalog identity." --root ddd
+ddduck query spec --root ddd --json
+```
+
+Default `check` requires both valid canonical source and fresh generated views. After a manual
+source edit, use `check --source-only`, run `generate`, then use default `check`. Do not edit
+`generated/` by hand.
+
+The successful `create` allocates the first catalog invariant serial, adds it to the Domain, and
+refreshes all generated views. The final query emits one JSON document suitable for a tool or
+agent. See the [model reference](model-reference.md) before adding other node kinds, and use the
+[CLI reference](cli.md) for the complete command contracts.

package/docs/model-reference.md

@@ -0,0 +1,92 @@
+# Model reference
+
+Canonical YAML uses schema version `"1"`. IDs are lowercase, hyphenated after their structural
+prefix, except stable Guarantee IDs and decision IDs such as `ADR-001`. A Guarantee ID is keyed
+to its classification: `<ORIGIN>-INV-<serial>` for an `invariant`, `<ORIGIN>-AC-<serial>` for an
+`acceptance-criterion`.
+The checker requires exactly one Model root.
+
+## Model root
+
+`product.yaml` is the only `Model` node. Unlike every child node, it has no `model` field.
+Required fields are `schemaVersion`, `kind`, `id`, `name`, `purpose`, and `domains`. Optional
+top-level fields include `nameStatus`, `useCases`, `relationships`, `decisions`, and `notes`.
+
+```yaml
+schemaVersion: "1"
+kind: Model
+id: model:<product-slug>
+name: A product name
+purpose: Define the product.
+domains:
+  - domain:<domain-slug>
+useCases: []
+decisions: []
+```
+
+## Child-node fields
+
+All child nodes include `schemaVersion`, `kind`, `id`, and `model`. `model` must name the root
+Model ID. `Domain`, `Concept`, and `DomainInterface` respectively use `domain:`, `concept:`, and
+`interface:` IDs. A child owned by a Domain uses `ownerDomain`; the owning Domain must also list
+the child in the matching collection.
+
+### Domain
+
+Required: `name`, `purpose`. Optional owned lists: `concepts`, `excludedConcepts`, `interfaces`,
+`guarantees`, and `decisions`.
+
+```yaml
+schemaVersion: "1"
+kind: Domain
+id: domain:<domain-slug>
+model: model:<product-slug>
+name: A domain name
+purpose: Describe the domain responsibility.
+concepts: []
+interfaces: []
+guarantees: []
+```
+
+### Concept
+
+Required: `ownerDomain`, `name`, `purpose`. Optional: `decisions`.
+
+```yaml
+schemaVersion: "1"
+kind: Concept
+id: concept:<concept-slug>
+model: model:<product-slug>
+ownerDomain: domain:<domain-slug>
+name: A concept name
+purpose: Describe the concept responsibility.
+```
+
+### Relationship
+
+Required: `from`, `to`, `relationshipType`, `mode`, and `ownedBy` (a Domain ID). Optional:
+`description`, `constraints`, and `decisions`.
+
+### UseCase
+
+Required: `name`, `goal`, `preconditions`, and `success`. `preconditions.requires` is required;
+`success` requires `preserves` and `establishes` lists. Optional: `interfaces` and evidence
+anchors.
+
+### DomainInterface
+
+Required: `ownerDomain`, `name`, and `operationKind` (`command` or `query`). Optional:
+`guarantees` and evidence anchors.
+
+### Guarantee
+
+Required: `ownerDomain`, `classification` (`invariant` or `acceptance-criterion`), `statement`,
+and `status` (`active`, `split`, or `retired`). A split or retired Guarantee also requires a
+`lifecycleDecision`; a split Guarantee names active `successors`. Optional `ownershipHistory`
+records former owning Domains. Evidence anchors are also supported.
+
+Evidence anchors contain a product-relative `path`, `anchor`, and `role` (`source`, `decision`,
+or `verification`). The path must resolve to a regular file inside the selected product root.
+
+For full schema constraints, inspect the shipped files under `schemas/product/`; use
+[the getting-started guide](getting-started.md) for the minimal working path.