ddduck 0.1.0 → 0.2.0

package/README.md

@@ -4,6 +4,8 @@ ddduck defines a small, machine-readable product-spec format. The framework keep
 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.
+For an unsettled product question or a proposed change, use the optional
+[definition-to-planning workflow](docs/definition-workflow.md) and reuse your existing brief.
 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.
 
@@ -14,7 +16,7 @@ Every product renders to a verified graph of its model — the ownership spine
 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)
+![ddduck model graph: the framework's Model, its Domains and owned Concepts, and typed relationships, with a legend](https://raw.githubusercontent.com/diegomarino/ddduck/main/docs/ddd/generated/graph/model-graph.svg)
 
 ## Product layout
 
@@ -40,7 +42,9 @@ docs/ddd/
 `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,
+Repository-local ddduck tool metadata lives outside the product root in `.ddduck/` at the
+enclosing repository root; without one, `ddduck init` writes it inside the new product root
+instead (see [the CLI reference](docs/cli.md#product-root-resolution)). For example,
 this framework repository stores its own model in `docs/ddd/` and records that selection in:
 
 ```json
@@ -57,7 +61,7 @@ and fully editable (see [the CLI reference](docs/cli.md)).
 
 ## Authoring
 
-Install the CLI from npm:
+Install the CLI from npm (requires Node.js 22 or newer):
 
 ```bash
 npm install -g ddduck
@@ -72,9 +76,10 @@ 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
+product root, then `.ddduck/config.json`, then a unique repository candidate (see
+[the CLI reference](docs/cli.md#product-root-resolution) for the full order, including the
+example-candidate fallback), and fails with a diagnostic when the choice is ambiguous. The mutation surface is deliberately narrow —
+`generate`, domain/concept/use-case creation, 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).
 

package/docs/architecture.md

@@ -61,8 +61,11 @@ flowchart LR
 
 ## 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
+Queries are read-only and always emit exactly one JSON document (`--json` is accepted as a
+no-op). A context query returns selected canonical records,
+direct touching edges, one-hop summaries for unselected neighbors, and a source digest. The
+source digest covers the canonical node YAML sources only — `product.yaml` and the files under
+`model/` — so decision records under `decisions/` are outside its scope. It does
 not recursively expand context or write canonical or generated files.
 
 ```mermaid

package/docs/cli.md

@@ -7,7 +7,12 @@ with `--` must use the `--option=value` form. Every command rejects unknown opti
 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.
+command-specific hint. Help exits zero. Exit codes are part of the contract: the one retryable
+failure — a busy product root, whose operation lock is held by a running process — exits 2, so
+retry logic never has to string-match standard error; every other failure exits 1.
+
+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)).
 
 ## Product root resolution
 
@@ -44,51 +49,20 @@ Use `.ddduck/config.json` for a repository default:
 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)).
+file pre-filled when it does not already exist and reports the write in its result
+(`config: <path> (created)` in text, `configPath` in `--json`; omitted when the file
+pre-existed). The config is written at the enclosing repository root (the nearest ancestor
+containing `.git`); without one, at the destination directory itself, so the file then lives
+inside the new product root with `"productRoot": "."`. When the file already exists and selects a different product root, `init` prints a
+standard-error note that the repository default still selects that other root.
 
 ## 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
+mutations regenerate all required views. `check`, `diff`, and every `query` are read-only. A successful
+`check` writes nothing to standard output; when `--root` was omitted, it prints one standard-error
+note naming the validated root so an implicitly resolved (for example config-pinned) root is never
+validated invisibly. Successful product mutations print one concise result line, or one JSON result
 object when `--json` is available.
 
 ## `init`
@@ -103,8 +77,10 @@ ddduck init [destination] --id model:<product-id> [--json]
 | `--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,
+`init` writes the canonical directory layout, `product.yaml`, and the four fresh generated views
+(`generated/docs/model-overview.md`, `generated/graph/model-graph.json`,
+`generated/graph/model-graph.ndjson`, and `generated/graph/model-graph.svg`). 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.
@@ -126,9 +102,12 @@ ddduck check [--root <product-root>] [--base <previous-product-root>] \
 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
+repository-wide gate. Documentation-reference scanning always skips the `docs/audits` and
+`docs/superpowers` directories (paths relative to each scanned root). It writes nothing and keeps standard output empty on success; when `--root`
+was omitted, one standard-error note names the validated root. It exits 2 for a busy root
+(`.ddduck-operation.lock` held by a live ddduck operation — the retryable case), and 1 for
+invalid source, stale views, invalid roots, invalid options, 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.
@@ -145,10 +124,70 @@ ddduck generate [--root <product-root>] [--json]
 | `--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
+`generated/graph/model-graph.json`, `generated/graph/model-graph.ndjson`, and
+`generated/graph/model-graph.svg`. 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.
 
+## `diff`
+
+```text
+ddduck diff --base <previous-product-root> [--root <product-root>] [--json]
+```
+
+Compare two independently valid versions of the same Model by stable node ID. `--base` is
+required and `--root` uses normal root resolution. Generated output may be absent or stale.
+The command does not apply historical retention validation first: removing a Guarantee must
+remain visible in the comparison even when a subsequent `check --base` rejects that removal.
+
+The text report shows IDs, field changes, and path relocations. `--json` emits one
+`ModelDiff` version `"1"` document conforming to `schemas/model-diff.schema.json`:
+
+- `before` and `after` contain `modelId` and canonical `sourceDigest`.
+- `added` and `removed` contain full records with their product-relative source paths.
+- `changed` contains field changes keyed by escaped JSON Pointer paths. `beforePresent` and
+  `afterPresent` distinguish absent fields from explicit null values.
+- `relocated` records path changes without treating the same ID as a new record.
+- `scope` is `canonical-yaml-only`; `excludedScopes` names decision content, evidence content,
+  delivery artifacts, and runtime.
+
+Object-key order, comments, and YAML formatting are not record differences. Array order is
+preserved, so a reordered list is reported. Raw canonical-file changes still affect digests.
+Neither the digests nor an empty comparison establish ADR/evidence freshness or semantic
+equivalence. Source reads are not atomic snapshots; run comparisons while neither root is
+being edited. Busy and interrupted roots are refused.
+
+Exit 0 means comparison completed, including when changes exist; it is not an approval.
+Exit 2 means busy, and exit 1 covers invalid or incompatible inputs. Use existing `impact`
+and `neighbors` queries on both roots to inspect changed/removed context, then review meaning
+and run historical retention checking separately.
+
+## Creating domains, concepts, and use cases
+
+```text
+ddduck create domain --id domain:<slug> --name <text> --purpose <text> [--root <product-root>] [--json]
+ddduck create concept --id concept:<slug> --owner domain:<slug> --name <text> --purpose <text> [--root <product-root>] [--json]
+ddduck create use-case --file <yaml-file> [--root <product-root>] [--json]
+```
+
+Domain creation writes the node and adds its ID to the Model's `domains` list. Concept creation
+writes the node and adds its ID to the owning Domain's `concepts` list. These forms require
+every displayed field; they take model identity from the selected product.
+
+Use-case creation reads a complete canonical `UseCase` YAML mapping. Its `model` must match
+the selected product and all Guarantee/interface references must already resolve. It writes
+the new node and adds its ID to the Model's `useCases` list without changing the input file.
+An empty prerequisite or outcome list is allowed; the tool does not invent obligations.
+
+All three forms derive the destination filename from the validated ID. Duplicate IDs,
+occupied canonical paths, unknown fields, invalid references, or validation/generation
+failures reject the operation without intended publication. Successful operations update
+the owning collection and generate all views through the existing staged mutation runner.
+There is no overwrite mode. Existing YAML comments and unrelated parent fields are retained.
+The result has `operation`, `root`, `affectedIds` (new node and parent), `canonicalPaths`, and
+`generatedPaths`; append `--json` for one JSON document. Publication has the filesystem
+interruption limitations described in the [architecture guide](architecture.md#staged-lifecycle-mutation).
+
 ## Guarantee mutations
 
 All mutation results identify the selected root, affected Guarantee IDs, canonical paths, and
@@ -205,13 +244,19 @@ staged validation exits nonzero without an intended mutation.
 
 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
+diagnostic (exit code 2, the retryable case) instead of reading a partially published snapshot.
+Queries also refuse leftover state from an interrupted operation — the same
+`.ddduck-operation.lock`, `.ddduck-operation.reclaim`, or `.ddduck-operation-stage-*` entries
+`check` reports — with exit code 1 and the reclaim next action (run any mutation, such as
+`ddduck generate`, to reclaim), because the snapshot may be partially published. 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
+authoritative only for reads that did not race a mutation. `sourceDigest` covers the canonical
+node YAML sources only — `product.yaml` and the files under `model/` — not decision records:
+editing a file under `decisions/` does not change the digest. 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
+`diagnostics`. Every query root is resolved through the common product-root rules.
+Non-context queries accept optional `--history`; without it, a split or retired
 Guarantee resolves to its lifecycle redirect rather than its historical contract.
 
 ```mermaid
@@ -232,8 +277,45 @@ sequenceDiagram
 | `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. |
+| `ddduck query context --id <id> [--id <id> ...] [--root <root>] [--json]`  | `--id`           | 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.
+
+## 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, installed file manifest, `SKILL.md` SHA-256, and whole-bundle SHA-256.
+It installs `SKILL.md` and its bundled `references/` directory, refuses locally modified managed
+files, and upgrades legacy single-file locks without overwriting extra local files. 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 bundle (see its packaged
+[canonical entrypoint](../skills/update-ddduck-specs/SKILL.md)).

package/docs/definition-workflow.md

@@ -0,0 +1,130 @@
+# From a product question to a planning brief
+
+Start with the question, not a YAML record. Reuse an existing proposal or design brief;
+the [optional change brief](templates/change-brief.md) is a checklist for missing context,
+not a required document. A short note can be enough.
+
+## Explore, decide, then model
+
+1. Identify the actor and problem with concrete success and refusal examples.
+2. Separate observed evidence from accepted intent and open questions. Record alternatives
+   and contradictory evidence with provenance.
+3. Make the semantic decision explicit. Record the decision and rationale in the brief;
+   create an ADR only for a consequential, durable choice that needs its own history.
+4. Update canonical YAML only where accepted meaning changed. Preserve stable IDs and use
+   lifecycle commands for Guarantee transitions. A partial update can encode independent
+   accepted obligations while an unresolved question stays in prose. Zero model change is
+   correct when the existing model suffices, the change is implementation-only, or no
+   decision has been reached.
+5. Validate structure and refresh derived views, then hand selected context to the planner
+   with delivery intent, scope, exclusions, dependencies, and acceptance examples.
+
+**Observed** means evidence was inspected, not endorsed. **Open** means undecided.
+**Accepted** means intended behavior, possibly not implemented. **Rejected** records an
+alternative and rationale. These are prose labels, not new schema fields or Guarantee
+statuses. A passing checker settles none of these semantic decisions.
+
+For example, an admin capability need not be a member role. Existing code that grants one
+from the other establishes observed behavior; whether that coupling is intended remains a
+decision. Likewise, delivering a relay directive does not establish that the recipient
+enacted it. Leave an unanswered question about who may authorize it open rather than
+inventing an authority boundary.
+
+## Model only what helps a decision
+
+| Kind         | Useful meaning                                                             | Counterexample to avoid                            |
+| ------------ | -------------------------------------------------------------------------- | -------------------------------------------------- |
+| Domain       | A distinct product responsibility                                          | A domain for each package or screen                |
+| Concept      | Vocabulary needed to reason about behavior                                 | A concept for every class, queue, or button        |
+| Guarantee    | An observable obligation or invariant                                      | “Best effort delivery” with no concrete commitment |
+| Use case     | An actor's goal and the obligations it requires, preserves, or establishes | An implementation task list                        |
+| Relationship | A connection worth reviewing, with its meaning stated                      | Treating every connection as a causal dependency   |
+
+Interfaces are optional. A useful behavioral model can have none. Empty prerequisite lists
+are not inherently wrong; add a reference when it expresses a real prerequisite, not to
+make the diagram look complete.
+
+For a small relay, introducing separate UI, transport, and receipt domains and
+concepts would obscure the one responsibility under discussion. Three cohesive obligations
+can distinguish authorization/refusal, the limit of delivery, and honest reporting. Do not
+split every clause: split when meaning, change, or verification is independent. Remove an
+extra Guarantee, domain, brief section, or review step when it answers no additional question.
+Consumer practice is inspiration, not proof that its artifact count or boundaries are right.
+
+The [relay walkthrough](https://github.com/diegomarino/ddduck/tree/main/examples/control-relay)
+is a fictional educational scenario. The
+[reminders scenario](https://github.com/diegomarino/ddduck/tree/main/examples/reminders)
+illustrates refusal. Neither specifies a real product or runs an application.
+
+## Author and review with existing tools
+
+After hand edits, `generate` validates the staged source and generated outputs before
+publishing derived views. It is the normal refresh action. Run operations serially against a root.
+
+```bash
+ddduck generate --root <root>
+ddduck check --root <root>
+```
+
+An optional `ddduck check --root <root> --source-only` diagnoses canonical edits before
+generation; `query spec` can inspect individual view freshness when needed.
+`check` is read-only and suitable for CI/final readback. Fresh generated views establish
+consistency with source, not product acceptance or runtime correctness.
+
+For each selected ID, compose the existing reads:
+
+```bash
+ddduck query impact --id <id> --root <root> --json
+ddduck query neighbors --id <id> --root <root> --json
+ddduck query node --id <relationship-id> --root <root> --json
+ddduck query context --id <id> --root <root> --json
+```
+
+Impact follows reverse owns/requires/preserves/establishes/uses/guarantees edges.
+Neighbors exposes direct incoming/outgoing edges, including explicit relationships. Read
+the relationship record for its type, description, and constraints when needed. These are
+review candidates requiring judgment; an empty result does not establish absence of risk.
+To select explicit relationships, filter both edge lists by `edge.kind === 'relationship'`
+and deduplicate by `edge.id`; a self-relationship appears in both lists. If the changed ID
+is itself a Relationship, query its record and inspect its `from` and `to` endpoints:
+neighbors matches endpoint IDs, not the relationship record's ID.
+There is no separate review query. Do not infer transitive effects from relationship names.
+Separate query calls are not an atomic snapshot: keep the source stable during review and
+re-read if it changes. A source digest identifies the read source only when it did not race
+a mutation; it does not make multiple reads transactionally consistent.
+
+Inspect before and after roots when something moves or disappears. In the fictional
+ownership fixture, the same Guarantee moves from Members to Reminders within the small
+reference corpus:
+review its owner, both domains' lists, wording, and use-case references without inventing a
+new ID. Read-only current-root queries alone cannot recover removed context. External feature
+references remain the consumer bridge's responsibility.
+
+The comparison command is:
+
+```text
+ddduck diff --base <root> [--root <root>] [--json]
+```
+
+Its scope is canonical YAML records by stable identity, not decision/evidence
+content, delivery artifacts, or runtime. Keep semantic review separate from structural
+comparison and historical retention checking.
+
+Use the implemented [domain, concept, and use-case creation commands](cli.md#creating-domains-concepts-and-use-cases)
+to create records and update their parent lists coherently. Use-case creation consumes a
+complete canonical YAML mapping; it does not invent obligations or decisions. See that
+reference for syntax and refusal behavior. Schema-guided hand edits remain useful for
+changes outside these helpers; update ownership/reference lists together before generation.
+
+## Hand off intent, not just a graph
+
+Select canonical context explicitly and link it from the receiving plan. Add why the work
+is needed, scope and non-goals, success/refusal examples, dependencies, exclusions, open
+decisions, and the next verification required. Reuse the exploration brief if it already
+answers those questions; do not maintain duplicate requirement prose or a second backlog.
+
+State evidence levels precisely: inspected implementation, declared evidence anchors,
+structural checks, tests actually executed, and observed runtime are different claims.
+An audit verdict is a declared assessment whose anchor integrity is checked; readiness
+roles and valid links do not prove behavioral coverage. Keep anchors inside the supported
+product root, and never create fake executable evidence or bridge documents to fill gaps.

package/docs/getting-started.md

@@ -1,10 +1,12 @@
 # Getting started
 
 This executable journey creates a product with one Domain, one Concept, and one Guarantee.
+For help deciding what belongs in that model, start with the
+[definition workflow](definition-workflow.md).
 
 ## Install ddduck
 
-Install the published CLI globally from npm:
+Requires Node.js 22 or newer. Install the published CLI globally from npm:
 
 ```sh
 npm install -g ddduck
@@ -15,7 +17,7 @@ To contribute or run an unreleased revision, work from a local checkout instead.
 `ddduck` bin on `PATH` with `npm link`:
 
 ```sh
-git clone <ddduck-repository-url> ddduck
+git clone https://github.com/diegomarino/ddduck.git ddduck
 cd ddduck
 npm install
 npm link
@@ -30,13 +32,16 @@ node <checkout>/scripts/ddduck.mjs --help
 
 ## Create the first product
 
-Run the complete Bash block from an empty working directory with `ddduck` on `PATH`.
+Run the complete Bash block from an empty working directory with `ddduck` on `PATH`, normally
+inside a Git repository: `init` records the repository default in `.ddduck/config.json` at the
+repository root, and without one writes it inside the new product root instead (see
+[the CLI reference](cli.md#product-root-resolution)).
 
 ```mermaid
 flowchart LR
-  Source[Manual canonical YAML edit] --> SourceCheck[ddduck check --source-only]
-  SourceCheck -->|valid| Generate[ddduck generate]
-  SourceCheck -->|invalid| Diagnostic[Actionable diagnostic]
+  Create[ddduck create] --> FreshCheck[ddduck check]
+  Source[Manual canonical YAML edit] --> Generate[ddduck generate]
+  Generate -->|invalid source| Diagnostic[Actionable diagnostic]
   Generate --> FreshCheck[ddduck check]
   FreshCheck --> Docs[Generated Markdown is fresh]
   FreshCheck --> Graph[Generated graph is fresh]
@@ -45,54 +50,22 @@ flowchart LR
 ```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 domain --id domain:catalog --name Catalog \
+  --purpose "Organize the library catalog." --root ddd
+ddduck create concept --id concept:book --owner domain:catalog --name Book \
+  --purpose "Identify a catalogued book." --root ddd
 ddduck create guarantee --origin catalog --classification invariant \
   --owner domain:catalog --statement "A Book has a stable catalog identity." --root ddd
+ddduck check --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.
+source edit, `ddduck generate --root ddd` validates the source and refreshes the views;
+use `ddduck check --root ddd` for final readback or CI. To diagnose source without writing
+anything, run `ddduck check --root ddd --source-only`. 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
+Each successful `create` updates the owning collection and refreshes all generated views.
+Guarantee creation allocates the first catalog invariant serial. 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

@@ -11,6 +11,8 @@ The checker requires exactly one 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`.
+`nameStatus` is a free-form string describing how settled the model name is (for example
+`stable` or `provisional`); generated views show it only when it is declared.
 
 ```yaml
 schemaVersion: "1"
@@ -87,6 +89,8 @@ 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 Markdown (`.md`) paths the checker also verifies that the `anchor` string occurs in the
+file content; for non-Markdown paths the anchor is a free-form label and is not content-checked.
 
 For full schema constraints, inspect the shipped files under `schemas/product/`; use
 [the getting-started guide](getting-started.md) for the minimal working path.

package/docs/model.md

@@ -20,6 +20,7 @@ docs/ddd/
     docs/model-overview.md
     graph/model-graph.json
     graph/model-graph.ndjson
+    graph/model-graph.svg
 ```
 
 `product.yaml` and `model/**/*.yaml` are canonical. `generated/` is derived output and

package/docs/templates/change-brief.md

@@ -0,0 +1,48 @@
+# Optional change brief
+
+Reuse an existing proposal, issue, or design brief first. Keep only sections that help a
+decision; a few paragraphs may suffice. This file is not a canonical schema or a second backlog.
+Use Observed, Open, Accepted, and Rejected as prose labels, never YAML lifecycle states.
+
+## Problem and actor
+
+Who needs what outcome, and why now?
+
+## Examples and refusal cases
+
+Describe concrete success, refusal, and uncertainty cases. Label expected behavior separately
+from results actually observed.
+
+## Observed evidence
+
+Cite paths and headings, symbols, or tests; state provenance, inspected scope, and gaps.
+Observed implementation may be a bug rather than intended behavior.
+
+## Accepted constraints
+
+Record accepted intent and its authority. Accepted does not mean implemented.
+
+## Alternatives
+
+Include doing nothing or reusing existing obligations, with tradeoffs and rejected choices.
+
+## Open questions and conflicts
+
+What still needs a decision? Which work depends on it? Keep unresolved assertions out of YAML.
+
+## Affected canonical IDs
+
+Select existing records explicitly; label proposed additions as proposals. Use fenced code
+for IDs from another product when the repository scans documentation references.
+Record partial or zero-model-change outcomes with a reason.
+
+## Decision and rationale
+
+Record who accepted what and why, plus what remains open. Link an ADR only if the durable
+decision warrants a separate artifact.
+
+## Planning handoff
+
+Link the receiving plan and provide intent, scope, non-goals, acceptance/refusal examples,
+dependencies, exclusions, unresolved decisions, and selected canonical context. State what
+was verified, by which commands, and what has not been executed. A graph is not a delivery plan.