arkaik 0.1.1 → 0.1.2

package/dist/assets/bootstrap-skill/references/fragments.md

@@ -0,0 +1,203 @@
+# The fragment contract
+
+A fragment is the one file a bootstrap agent writes: one JSON object at
+`.arkaik/bootstrap/fragments/<unit>.json`, where `<unit>` is your work-unit
+id from `.arkaik/bootstrap/manifest.json`. The filename **is** the unit id —
+`arkaik bootstrap merge` derives the path from the id and ignores the
+manifest's `fragment` field. A missing fragment just means the unit hasn't
+run yet (the run is resumable); invalid JSON, a top-level array, or a
+non-array value under any of the keys below fails the merge loudly, naming
+your unit.
+
+The top level:
+
+```jsonc
+{
+  "unit": "<your unit id>",
+  "wave": 1,
+  // then one or more of the six keys below, each an array of objects:
+  "nodes": [], "edges": [],                // greenfield anatomy / acceptances
+  "add": [], "update": [], "retire": [],   // brownfield reconcile
+  "events": []                             // story (wave 3)
+}
+```
+
+Merge reads **only** those six keys and ignores everything else. Two
+consequences:
+
+- You may have seen sketches of the wave-3 shape with `deliverables`,
+  `releases`, or `decisions` keys — **they do not exist in the contract**,
+  and anything written under them is silently lost. Deliverables and
+  releases are entries in `events` (`deliverable.shipped`, `release.tagged`);
+  the decisions unit's `DEC-` nodes go in `nodes` (or `add`) with their edges
+  in `edges`, like any other node. Merge never branches on `wave` — every key
+  works in every fragment.
+- One ignored key is used on purpose: **`notes`**, a free-text string where
+  you record judgment calls (e.g. why a PR was judged not user-visible).
+  Merge skips it; the wave reviewer reads it.
+
+## Nodes — `nodes` and `add`
+
+A node as an agent writes it: the bundle's node fields **minus `project_id`**
+(merge stamps it), plus an optional `created_ts`.
+
+| Field | Required | Meaning |
+|---|---|---|
+| `id` | yes | Species-prefixed kebab-case id (`F-`, `V-`, `DM-`, `API-`, `AC-`, `DEC-`) |
+| `species` | yes | `flow`, `view`, `data-model`, `api-endpoint`, `acceptance`, `decision` |
+| `title` | yes | Non-empty; concept titles capitalized, table titles the exact identifier |
+| `created_ts` | no | When this surface first shipped — becomes the `node.created` event's timestamp |
+| anything else | no | `status`, `platforms`, `metadata` (playlists, gherkin, values…) as the species requires |
+
+`created_ts` should be the merge instant of the PR that first shipped the
+surface, straight from your slice. It is consumed, not stored: merge uses it
+to synthesize the `node.created` event and drops it from the node. Absent,
+merge falls back to `project.created_at`. A malformed timestamp fails your
+unit loudly rather than minting a wrong event.
+
+`add` (brownfield) takes exactly the same node shape. Re-declaring a node
+that already exists with the **same title** is a safe no-op — no duplicate
+node, no duplicate `node.created`. The same id with a **different title** is
+a collision, and merge fails naming both titles and both units. That is the
+whole coordination model: ids are derived deterministically from titles, so
+independent agents converge on the same id for the same thing and collide
+loudly on different things.
+
+## Edges — `edges`
+
+| Field | Required | Meaning |
+|---|---|---|
+| `source_id` | yes | A node id — from this fragment, another unit's fragment, or the existing map |
+| `target_id` | yes | Same |
+| `kind` | yes | `composes`, `calls`, `displays`, `queries`, or `covers` (semantics: the `arkaik` skill) |
+
+No edge `id` — merge mints the canonical `e-{source}-{target}`. Endpoints
+resolve across fragments, so you never coordinate with another agent; an
+endpoint **nobody** created is a loud merge error. Two fragments disagreeing
+on one edge's kind is an error naming both; agreeing is a silent no-op.
+
+## Reconcile ops — `update` and `retire` (brownfield)
+
+```jsonc
+"update": [{ "id": "V-x", "patch": { ... }, "changed_ts": "<ISO instant>" }],
+"retire": [{ "id": "V-y", "reason": "why", "changed_ts": "<ISO instant>" }]
+```
+
+- **`update`** — `patch` fields replace the node's. `metadata` is special:
+  its **top-level keys merge** — keys you don't name survive — but a key you
+  **do** name is **replaced whole**, not merged recursively. Patching one
+  nested field means writing the key's full value: all of `platformStatuses`,
+  the whole `playlist`. When the patch **changes** `status` (or
+  `metadata.decision_status`), merge emits the matching `node.status_changed`
+  (or `decision.status_changed`) event at `changed_ts`; a patch restating the
+  same value emits nothing.
+- **`retire`** — never a delete. Merge sets `status: "archived"`, records
+  `metadata.retired_reason`, and emits the status event. The node count is
+  unchanged; a human decides actual removal.
+- Both ops must target a node that exists — an unknown id fails the merge.
+
+**The `changed_ts` one-shot rule.** When a status-changing op omits
+`changed_ts`, merge substitutes one constant fallback timestamp for the whole
+run. One such op per node is safe; a **second** status-changing op for the
+**same node** in the same run that also omits it lands on the identical
+timestamp, and merge refuses rather than guess an order. Give every
+status-changing op past the first, for the same node, its own explicit
+`changed_ts`.
+
+## Story events — `events`
+
+Plain journal event objects: `type`, the type's payload fields, and a real
+`ts`. **No `id`, no `actor`** — merge mints deterministic ids, which is what
+makes a re-run over unchanged fragments byte-identical. The story types:
+
+| Type | Payload |
+|---|---|
+| `deliverable.shipped` | `deliverable_id`, `title`, `summary?`, `url?`, `node_ids?`, `platform?` |
+| `release.tagged` | `version`, `notes?`, `platform?` |
+| `node.status_changed` | `node_id`, `from`, `to`, `platform?` |
+| `decision.status_changed` | `node_id`, `from`, `to` |
+| `idea.proposed` | `title`, `description?`, `node_id?` |
+
+The full vocabulary is the `arkaik` skill's event table. Timestamps come from
+the corpus — PR merge instants, not invented dates. Two **unscoped**
+`node.status_changed` for **one node at the identical `ts`** that disagree on
+`to` are refused (read-back order between them would be undefined);
+platform-scoped events — those carrying `platform` — are exempt. Real merge
+timestamps are full instants, so distinct instants are free — use them.
+
+## Examples
+
+Each example below is a fixture from the CLI's own test suite, copied
+verbatim so the docs and the tested contract cannot drift. If a fixture
+changes, change it here too.
+
+**Greenfield anatomy** (`tests/cli/bootstrap-e2e.test.js`, the `w1-home`
+fragment — note the playlist ↔ `composes` agreement and `created_ts`):
+
+```json
+{
+  "unit": "w1-home",
+  "wave": 1,
+  "nodes": [
+    {
+      "id": "F-notes",
+      "species": "flow",
+      "title": "Notes",
+      "status": "live",
+      "platforms": ["web"],
+      "created_ts": "2026-01-05T10:00:00.000Z",
+      "metadata": { "playlist": { "entries": [{ "type": "view", "view_id": "V-home" }] } }
+    },
+    {
+      "id": "V-home",
+      "species": "view",
+      "title": "Home",
+      "status": "live",
+      "platforms": ["web"],
+      "created_ts": "2026-01-05T10:00:00.000Z"
+    }
+  ],
+  "edges": [{ "source_id": "F-notes", "target_id": "V-home", "kind": "composes" }]
+}
+```
+
+**Brownfield `add`** (`tests/cli/bootstrap-merge.test.js`, the "node.created
+is not duplicated" probe — `V-home` already exists in the map and is a no-op;
+`V-new` is genuinely new):
+
+```json
+{
+  "unit": "w1-a",
+  "wave": 1,
+  "add": [
+    { "id": "V-home", "species": "view", "title": "Home", "status": "live", "platforms": ["web"] },
+    { "id": "V-new", "species": "view", "title": "New", "status": "live", "platforms": ["web"], "created_ts": "2026-03-01T00:00:00.000Z" }
+  ]
+}
+```
+
+**Brownfield `update` + `retire`** (`tests/cli/bootstrap-merge.test.js`, the
+combined reconcile fixture):
+
+```json
+{
+  "unit": "w1-a",
+  "wave": 1,
+  "update": [{ "id": "V-home", "patch": { "status": "live" }, "changed_ts": "2026-02-01T00:00:00.000Z" }],
+  "retire": [{ "id": "V-legacy", "reason": "replaced by V-home", "changed_ts": "2026-02-02T00:00:00.000Z" }]
+}
+```
+
+**Wave-3 story** (`tests/cli/bootstrap-merge.test.js`, the journal de-dup
+fixture — `V-home` is a node that already exists in the map):
+
+```json
+{
+  "unit": "w3-decisions",
+  "wave": 3,
+  "events": [
+    { "type": "deliverable.shipped", "deliverable_id": "pr-1", "title": "Ship it", "ts": "2026-01-05T00:00:00.000Z" },
+    { "type": "node.status_changed", "node_id": "V-home", "from": "backlog", "to": "live", "ts": "2026-01-05T00:00:00.000Z" }
+  ]
+}
+```

package/dist/assets/bootstrap-skill/references/waves.md

@@ -0,0 +1,120 @@
+# Waves & gates
+
+A bootstrap run is four waves, each fanning out over work units that
+`arkaik bootstrap plan` writes to `.arkaik/bootstrap/manifest.json`:
+
+| Wave | Units | Emits |
+|---|---|---|
+| 0 · Recon | `w0-recon` (one agent) | `.arkaik/bootstrap/profile.json` |
+| 1 · Anatomy / Reconcile | `w1-<area>`, one per area | `{nodes, edges}` (greenfield) or `{add, update, retire}` (brownfield) |
+| 2 · Acceptances + values | `w2-<area>`, one per area (+ a values-balance reviewer role — not a unit) | acceptances with gherkin, values, `covers` edges, platform scoping |
+| 3 · Story | `w3-<era>` per era, plus `w3-decisions` and `w3-status-arcs` | `events` (deliverables, releases, arcs) and `DEC-` nodes |
+
+Working a unit is always the same loop: `arkaik bootstrap slice <unit>` →
+judge → write the fragment → set the unit's status to `done` in
+`.arkaik/bootstrap/manifest.json`. **Resumability is structural:** statuses
+(`pending` / `done` / `rejected`) live in the manifest and output lives in
+fragment files, so a killed session resumes at the first `pending` unit, and
+re-running `plan` preserves the status of any unit whose slice is unchanged.
+
+**Every wave ends the same way:** an adversarial reviewer — checking against
+the product, not just the schema — then `arkaik bootstrap merge` (preview
+with `--dry-run`), then `arkaik validate` on the bundle, **warning-clean**.
+Merge itself blocks only on errors; warnings never block the write, so
+warning-clean is the reviewer's gate to enforce, not the CLI's. A wave that
+does not gate green does not advance.
+
+## Wave 0 · Recon
+
+One agent reads the corpus and the repo (`slice` gives it the docs manifest)
+and writes `.arkaik/bootstrap/profile.json`: `products`, the `platforms`
+axis, `areas` (id, title, code paths — typically 8–12 for a real product),
+and `eras` (slug, title, date window). Then re-run `arkaik bootstrap plan` to
+expand waves 1–3.
+
+**Reviewer checklist — wave 0:**
+
+- [ ] Area ids and era slugs are lowercase kebab-case (they become fragment
+      filenames — `plan` rejects anything else).
+- [ ] Every area has at least one real path, and the areas together cover the
+      product's code. An area with wrong paths starves its agents of exactly
+      the PRs and surfaces they need.
+- [ ] Every era has at least one date bound; windows are half-open, so
+      adjacent eras may share a boundary date but must never overlap. Two
+      eras with only a `from` always overlap — give the earlier one a `to`.
+- [ ] The eras cover the PR timeline. A PR falling inside no era is silently
+      absent from the story.
+- [ ] The platform axis matches how the product actually ships; `products`
+      is declared only when the repo really is a family of apps.
+
+## Wave 1 · Anatomy / Reconcile
+
+One unit per area. Greenfield: map the area's flows, views, data models, API
+endpoints, and the edges between them. Brownfield: reconcile the existing map
+against the code — `add` what's missing, `update` what drifted, `retire`
+what's gone. Never delete.
+
+**Reviewer checklist — wave 1:**
+
+- [ ] Species are right: the route handler is `API-`, the page it feeds is
+      `V-`, the journey between pages is `F-`, the stored thing is `DM-`.
+- [ ] No `DM-` concept/table collisions; concept titles are capitalized
+      words, table titles the exact DB identifier.
+- [ ] Every flow has a real playlist that agrees with its `composes` edges,
+      and no flow contains itself.
+- [ ] Edge kinds match their semantics (`composes` / `calls` / `displays` /
+      `queries`) — spot-check a few against the actual code.
+- [ ] `created_ts` values come from the PRs that first shipped each surface,
+      not from today.
+- [ ] **Churn guard (brownfield): a unit proposing `retire` or `update` on
+      more than 20% of the existing nodes stops for human review.** Churn at
+      that scale is usually a wrong slice or a misread map, not a real
+      product change.
+- [ ] Nothing is deleted; every `retire` carries a reason a human could act
+      on.
+
+## Wave 2 · Acceptances + values
+
+One unit per area writes acceptances for its surfaces; one values-balance
+reviewer then reads the whole wave.
+
+**Reviewer checklist — wave 2:**
+
+- [ ] Exactly one Given/When/Then per acceptance — a second scenario is a
+      second acceptance.
+- [ ] Every `covers` edge points at an id that exists (`arkaik bootstrap
+      index`), and each acceptance anchors inside a single product.
+- [ ] Platform scoping is the fewest platforms that are true; no unscoped
+      promotion claiming every platform.
+- [ ] Values are 1–3 per acceptance, from the table, most specific element
+      first — or omitted where unsure. (Skipped entirely if the repo has no
+      values reference.)
+- [ ] **Values balance: if more than half the acceptances land on one value
+      element, the wave is rejected and re-run.** An unchecked acceptance
+      wave collapses into ~90% `simplifies`; the pyramid must show real
+      spread.
+
+## Wave 3 · Story
+
+Era units (`w3-<era>`) turn each era's user-visible PRs into
+`deliverable.shipped` events and tag the era's `release.tagged`.
+`w3-decisions` mines the design docs into `DEC-` nodes, their edges, and
+their events. `w3-status-arcs` gives each anatomy node an honest 1–3 event
+arc ending at its snapshot status.
+
+**Reviewer checklist — wave 3:**
+
+- [ ] The user-visible filter held: every PR with a Lab Note became a
+      deliverable; chores, CI, and refactors did not; borderline calls are
+      explained in the fragment's `notes`.
+- [ ] Deliverable and release timestamps are real merge instants from the
+      corpus, never invented dates.
+- [ ] Every decision traces to a real document in the corpus — decisions are
+      mined, not imagined.
+- [ ] Every arc ends at the node's snapshot status, contains no transition
+      that did not happen, and gives same-node events distinct instants.
+- [ ] Nothing project-shaped was deleted or rewritten — story only ever adds.
+
+After wave 3 gates green, the run is done: the bundle and its journal are the
+product. Landing them (and removing this skill) is the operator's move, not a
+wave.

package/dist/assets/bootstrap-skill/skill.md

@@ -0,0 +1,190 @@
+---
+name: arkaik-bootstrap
+version: 1.0.0
+description: >
+  Bootstrap the Arkaik product graph map for {{PRODUCT_NAME}} from its
+  repository history — map this repo, bootstrap the map, retro-populate or
+  backfill the map from merged PRs, design docs, and code surfaces. Use this
+  skill when working a unit of an `arkaik bootstrap` run: reading a slice,
+  writing a fragment, or reviewing a wave. One-time onboarding only — ongoing
+  map maintenance belongs to the `arkaik` skill, not this one.
+---
+
+# Arkaik Bootstrap — the judgment half
+
+The bootstrap method has two halves. The `arkaik bootstrap` CLI owns
+everything deterministic: mining the corpus, planning work units, slicing
+what you read, merging what you write, validating the result. This skill owns
+what code cannot decide: which species a thing is, what a flow's playlist
+really contains, what a PR actually shipped, which value an acceptance
+genuinely earns. You are the judgment half.
+
+Two references ship beside this file:
+
+- [references/fragments.md](references/fragments.md) — the exact shape of the
+  file you write
+- [references/waves.md](references/waves.md) — the wave catalog and the
+  reviewer checklist each wave gates on
+
+> **Template parameters.** Like the maintenance skill, this file is rendered
+> by `arkaik init`. If you are reading an unrendered copy, treat the defaults
+> in parentheses as the values:
+>
+> | Parameter | Meaning | Default |
+> |---|---|---|
+> | `{{PRODUCT_NAME}}` | The product being mapped | the current product |
+> | `{{BUNDLE_PATH}}` | Where the merged map lands | `docs/arkaik/bundle.json` |
+
+## When this skill applies
+
+This skill drives a **one-time onboarding run**: building the map for
+{{PRODUCT_NAME}} out of the repository's own history. Greenfield (no bundle
+yet, or an `arkaik init` stub with zero nodes) means mapping from scratch;
+brownfield (a bundle that already carries nodes) means reconciling the
+existing map against the code. Same method either way — only the wave-1
+fragment shape differs.
+
+Ongoing edits belong to the **`arkaik` skill installed beside this one**
+(`../arkaik/SKILL.md`): if you are updating the map as a side-effect of a
+code change, that is its job, not this skill's. Once the bootstrap run has
+landed, this skill has done its one job and can be removed:
+
+```bash
+arkaik init --remove-bootstrap
+```
+
+## The contract you work under
+
+**You never read the bundle. You never write the bundle. You never write
+merge logic.** You read a slice, you write a fragment:
+
+```bash
+arkaik bootstrap slice <unit> > slice.json   # what to read
+arkaik bootstrap index                        # existing node ids, when you need to reference them
+```
+
+The slice is exactly the corpus subset your unit needs — matching PRs,
+matching surfaces, and the docs manifest when your unit asks for it — instead
+of the whole repository. The index is one tab-separated line per existing
+node (`id`, `species`, `title`, `product`): how you reference real nodes
+without loading their bodies.
+
+Your output is one JSON file at `.arkaik/bootstrap/fragments/<unit>.json`,
+in the shape defined by [references/fragments.md](references/fragments.md).
+`arkaik bootstrap merge` owns everything after that — ID-collision detection,
+cross-fragment edge resolution, journal event synthesis, validation, landing
+the result at `{{BUNDLE_PATH}}` with its journal sidecar — and a malformed
+fragment fails with your unit's name attached rather than corrupting the
+map. Never edit another unit's fragment. When yours is
+written, set your unit's status to `done` in
+`.arkaik/bootstrap/manifest.json`.
+
+## Species discrimination
+
+Four anatomy species, one question each:
+
+- **Flow (`F-`)** — a journey the user moves through. It has a playlist.
+- **View (`V-`)** — one surface the user looks at: a screen, page, or panel.
+- **Data model (`DM-`)** — a thing the product stores or reasons about.
+- **API endpoint (`API-`)** — a callable contract across a boundary: a route
+  handler, an RPC, a webhook.
+
+A route file is usually one `API-` node; the page it feeds is a `V-`; the
+navigation between pages is the `F-`. Later waves add **acceptances (`AC-`)**
+— testable promises — and **decisions (`DEC-`)** mined from design docs.
+
+**The `DM-` rule — concept vs physical table.** A conceptual model takes the
+singular concept name: the concept "Project" is `DM-project`. A physical
+table or DB view takes its exact identifier: the table `projects` is
+`DM-projects`. Both may legitimately exist in one map; they must never
+kebab-case into the same id. Full ID and title rules live in the `arkaik`
+skill beside this one and its `../arkaik/references/schema.md`.
+
+## Playlists
+
+Every flow ships a **real** `metadata.playlist` — actual entries referencing
+actual views and sub-flows, never a placeholder. Two invariants:
+
+- The playlist and the flow's `composes` edges **agree**: every view or flow
+  in the playlist has a `composes` edge from the flow, and every `composes`
+  edge appears in the playlist.
+- **No cycles** — a flow cannot contain itself, directly or through
+  sub-flows.
+
+Entry shapes — including the branching `condition` and `junction` entries —
+are in `../arkaik/references/schema.md`.
+
+## Acceptances
+
+An acceptance is a testable promise. When you write one:
+
+- **Exactly one Given/When/Then** in `metadata.gherkin`. A second scenario is
+  a second acceptance.
+- **`covers` edges to real anchors** — views or flows whose ids exist in the
+  index or in your own fragment. An acceptance covering nothing is an intake
+  idea, not mapped behavior.
+- **Single-product anchoring** — its `covers` edges may span several views
+  and flows, but they must all resolve to the same product. A promise that
+  genuinely spans two products is two acceptances.
+
+The full doctrine (per-platform statuses, anchorless intake, the parity
+layer) is the `arkaik` skill's "Acceptances" section — follow it, don't
+reinvent it.
+
+## Values
+
+Assign **1–3 Bain value elements** in `metadata.values` per acceptance. The
+**most specific element wins**; claim a higher tier of the pyramid **only
+when the acceptance genuinely operates there**. The 30-element table with
+one-line definitions is `../arkaik/references/values.md` in the skill beside
+this one. If that file is absent (the maintenance skill was installed with
+`--no-values`), value mapping is out of scope for this repo — skip it
+entirely. When unsure, omit: a wrong value is worse than a missing one, and
+the wave-2 balance check (see [references/waves.md](references/waves.md))
+rejects a lopsided wave anyway.
+
+## Platform scoping
+
+Per-platform truth lives on acceptances (`metadata.platformStatuses`), and
+history is full of platform-scoped shipping — a PR that says `AC-x@ios`, or
+that only touched the iOS target, shipped iOS and nothing else.
+
+**An unscoped promotion claims every platform.** Moving an acceptance's base
+`status` asserts the behavior everywhere the acceptance's platforms reach —
+exactly like an unscoped `AC-x` mention in a PR. When the evidence says one
+platform, write that one platform's status. **Scope to the fewest platforms
+that are true**, and keep `platforms` itself to where the behavior is
+actually expected — mobile-only behavior is `["ios", "android"]`, not
+backlog-on-web.
+
+## What counts as user-visible
+
+Wave 3 turns PRs into story. The filter:
+
+- **A PR with a Lab Note is user-visible by definition** — and the note is a
+  benefit-first title and summary already written for you. Use it.
+- **Chores, CI, refactors, dependency bumps, and docs-only changes are not.**
+- **Judge the rest** — pre-pipeline PRs carry no note. Ask: could a user of
+  {{PRODUCT_NAME}} notice the difference? Record the judgment and the reason
+  in your fragment's `notes` so the reviewer can check it.
+
+## Status arcs
+
+Every anatomy node gets an honest arc of **1–3 events ending at its snapshot
+status**: the `node.created` that merge synthesizes from `created_ts`, plus
+**0–2 `node.status_changed` written by you** — one per transition that
+actually happened, the final one landing on the node's snapshot status.
+**Never invent a transition that did not happen.** A born-live node's arc is
+its `node.created` alone — write no status event for it, not a fabricated
+idea → development → live staircase. Build the arc from evidence: the PR
+that first shipped the surface, the era it was built in. Timestamp mechanics
+(distinct instants, `changed_ts`) are in
+[references/fragments.md](references/fragments.md).
+
+## Never delete
+
+Bootstrap never deletes. In a brownfield reconcile, a node that exists in
+the map but no longer in the product is **retired** — a `retire` op with a
+`reason` — and merge archives it with the reason on record. Removal stays a
+human decision, made outside this run. If you find yourself wanting to
+delete, you are holding the wrong tool.

package/dist/assets/skill/references/schema.md

@@ -18,10 +18,10 @@ block below — run `npm run generate`.
 
 <!-- GENERATED:SCHEMA:START -->
 ```typescript
-type SpeciesId = "flow" | "view" | "data-model" | "api-endpoint" | "acceptance";
-type StatusId = "idea" | "backlog" | "prioritized" | "development" | "releasing" | "live" | "archived" | "blocked";
+type SpeciesId = "flow" | "view" | "data-model" | "api-endpoint" | "acceptance" | "decision";
+type StatusId = "idea" | "discovery" | "backlog" | "development" | "releasing" | "live" | "archived";
 type PlatformId = "web" | "ios" | "android";
-type EdgeTypeId = "composes" | "calls" | "displays" | "queries" | "covers";
+type EdgeTypeId = "composes" | "calls" | "displays" | "queries" | "covers" | "supersedes" | "generates" | "impacts";
 
 type PlaylistEntry =
   | { type: "view"; view_id: string }
@@ -72,6 +72,8 @@ interface Ref {
 
 interface NodeMetadata extends Record<string, unknown> {
   stage?: string;
+  /** Non-empty = the node is blocked at its current status. A node id (rendered as a link) or free text. */
+  blocked_by?: string;
   playlist?: FlowPlaylist;
   platformNotes?: PlatformNotesMap;
   platformStatuses?: PlatformStatusMap;
@@ -81,6 +83,16 @@ interface NodeMetadata extends Record<string, unknown> {
   gherkin?: string;
   /** Acceptance nodes: value elements served — the Why (spec §3.2). */
   values?: ValueId[];
+  /** Product membership; meaningful on flow, view, and acceptance only. */
+  product?: string;
+  /** Decision nodes: the decision's own status (spec §2). Not a lifecycle status. */
+  decision_status?: DecisionStatusId;
+  /** Decision nodes: Context — the Why (markdown). */
+  context?: string;
+  /** Decision nodes: Consequences — the How (markdown). */
+  consequences?: string;
+  /** Decision nodes: ISO 8601 date the decision was actually made (backfill-friendly; node.created events carry the write date, not this). */
+  decided_at?: string;
 }
 
 interface Node {
@@ -103,9 +115,65 @@ interface Edge {
   metadata?: Record<string, unknown>;
 }
 
+type MapKind = "journey" | "system";
+
+interface MapLayoutHints extends Record<string, unknown> {
+  direction?: "DOWN" | "RIGHT" | (string & {});
+  /**
+   * Canvas layout algorithm: `"organic"` (force-directed with overlap
+   * removal) or `"layered"` (hierarchical tiers). Renderers fall back to the
+   * kind's default for unknown values (docs/spec/maps.md § MapDefinition).
+   */
+  algorithm?: "layered" | "organic" | (string & {});
+}
+
+type MapFlowPlatformsMode = "rings" | "bars";
+
+type MapViewPlatformsMode = "chips" | "rows";
+
+interface MapDisplayOptions extends Record<string, unknown> {
+  /** Screenshot (or cover) art on view cards. */
+  images?: boolean;
+  /** A flow card's platform delivery: the Pyramid's rings, or stacked bars. */
+  flow_platforms?: MapFlowPlatformsMode | (string & {});
+  /** A view card's platform availability: circular chips, or labelled rows. */
+  view_platforms?: MapViewPlatformsMode | (string & {});
+  /** What a minimap node's fill encodes: its status, or its species. */
+  minimap_color?: MapMinimapColorMode | (string & {});
+}
+
+interface MapDefinition extends Record<string, unknown> {
+  /** Kebab-case, unique within the project; built-in ids are reserved. */
+  id: string;
+  title: string;
+  description?: string;
+  /** Selects the renderer and the selection defaults below. */
+  kind: MapKind | (string & {});
+  /** Node filter; defaults by kind (docs/spec/maps.md § MapDefinition). */
+  species?: (SpeciesId | (string & {}))[];
+  /** Edge filter; defaults by kind. */
+  edge_types?: (EdgeTypeId | (string & {}))[];
+  /** Scope anchor; the journey renderer falls back to `project.root_node_id`. */
+  root_node_id?: string;
+  /** Product scope; absent = every product (docs/spec/bundle-format.md § Products). */
+  product?: string;
+  /** Traversal bound from the root; absent = unbounded. */
+  depth?: number;
+  layout?: MapLayoutHints;
+  /** Card rendering; the human twin is `project.metadata.map_display[id]`. */
+  display?: MapDisplayOptions;
+}
+
 interface ProjectMetadata extends Record<string, unknown> {
+  /**
+   * @deprecated Superseded by the per-map `map_display` below. Still parsed,
+   * validated, and round-tripped; no renderer reads it.
+   */
   view_card_variant?: "compact" | "large";
   maps?: MapDefinition[];
+  /** Per-map display overrides keyed by map id — built-ins included. */
+  map_display?: Record<string, MapDisplayOptions>;
+  products?: ProductDefinition[];
 }
 
 interface Project {
@@ -229,10 +297,12 @@ type KnownJournalEvent =
   | NodeCreatedEvent
   | NodeUpdatedEvent
   | NodeStatusChangedEvent
+  | DecisionStatusChangedEvent
   | NodeDeletedEvent
   | EdgeAddedEvent
   | EdgeRemovedEvent
   | ReleaseTaggedEvent
+  | DeliverableShippedEvent
   | IdeaProposedEvent
   | RequestFiledEvent
   | RefAddedEvent
@@ -282,8 +352,11 @@ exist in the bundle's `nodes` array.
 | `calls` | view → api-endpoint | View calls this API |
 | `calls` | flow → api-endpoint | Flow calls this API |
 | `calls` | api-endpoint → api-endpoint | Endpoint calls another (internal or third-party) API — e.g. a server action / BFF route fanning out to external APIs |
+| `calls` | api-endpoint → view | The server initiates: a webhook, an SSE stream, a push landing on this view (the View card's inbound/read affordance) |
 | `displays` | view → data-model | View displays data from this model |
 | `queries` | api-endpoint → data-model | API reads or writes this model |
+| `covers` | acceptance → view | Acceptance anchors a testable promise to this view |
+| `covers` | acceptance → flow | Acceptance anchors a testable promise to this flow |
 
 Any other source → target combination for a given edge type is invalid.