archik 0.12.12 → 0.12.14

package/.claude/commands/archik/accept.md

@@ -29,15 +29,45 @@ done at step 1 — the diagram changed; the code probably hasn't.
    non-code-bearing kind, description-only edit, pure metadata),
    skip steps 3–6 and jump straight to step 7.
 
-3. **BUILD — plan (HITL).** Translate the diagram delta into a
-   numbered file-level plan and present it for approval **before**
-   touching code:
+3. **BUILD — behavioral model first, then plan (HITL).**
+
+   **Before writing the plan**, check whether any new or modified
+   slice has behavior that warrants a seq diagram. A slice needs
+   one when it involves branching, async fan-out, cross-context
+   interaction, or three or more nodes in a single user-visible
+   action. Run:
+   ```
+   npx archik q usecases
+   ```
+   For each active slice without a `realization.seqFile` that meets
+   the above criteria:
+   - Author the `.archik.seq.yaml` now (direct-write), including a
+     `realizes: { useCase, slice }` block.
+   - Run `npx archik validate` — catches ECB violations, broken
+     `nodeId` refs, and duplicate step ids.
+   - Show the seq YAML inline and wait for confirmation before
+     writing the plan.
+
+   A slice without a seq diagram has no traceable spec — the build
+   plan for it is guesswork. Author the seq first; trace it in the
+   plan. If the slice is genuinely simple (single node, no
+   branching), skip the seq and note why.
+
+   **Then** translate the diagram delta into a numbered file-level
+   plan and present it for approval **before** touching code:
    - Each new code-bearing node (`service`, `function`, `worker`,
      `module`, `page`, `component`, `store`, `hook`) → its
      `sourcePath` and the concrete files / signatures to land there.
    - Each new edge that requires code → the corresponding code
      change (a new `http_call` needs a client; `subscribes` needs a
      consumer handler; `writes` needs a repository method; etc).
+   - Each seq diagram that realizes a slice → trace it: every
+     message in the seq must map to a concrete function call in this
+     plan. This is the traceability requirement — the seq is the
+     spec, the plan is the contract, the code is the proof.
+   - Each slice's `tests` paths → include scaffolding those test
+     files in the plan; they must exist on disk before the slice
+     can be marked active.
    - Any node still `status: proposed` → flag it; code must land
      before flipping to `active`.
    - Default to **tests-first** when behaviour is clearly bounded.
@@ -72,6 +102,18 @@ done at step 1 — the diagram changed; the code probably hasn't.
    npx archik validate
    ```
    Plus the project's tests / typecheck / lint.
+   ```
+   npx archik drift
+   ```
+   Catches both missing `sourcePath` directories and missing slice
+   test files on disk.
+   If the project has use cases, run the coverage matrix:
+   ```
+   npx archik trace
+   ```
+   No active slice should be untraced at ship time. Partial is a
+   warning; untraced is a gap — add the missing test path or
+   realization seq before declaring the milestone done.
    `superpowers:verification-before-completion` when available.
    If `docs/architecture.svg` is committed, regenerate it:
    ```
@@ -85,3 +127,12 @@ done at step 1 — the diagram changed; the code probably hasn't.
    - *"Want me to schedule a drift check in two weeks?"*
    - *"This left `payments-worker` as `status: proposed` — flip it
      to `active` once deployed."*
+   - If this milestone completed a significant chunk of work, check
+     whether any alpha state can be promoted:
+     ```
+     npx archik alpha show
+     ```
+     If a state is verified and the next rung's criteria are met,
+     offer to promote: *"Requirements is at `acceptable` and all
+     active slices now have tests — want me to promote it to
+     `addressed`?"*

package/.claude/commands/archik/evolve.md

@@ -45,6 +45,27 @@ any file under `.archik/`.
    — there's nothing meaningful to evolve. Suggest `/archik:spawn`
    first.
 
+   Also check the Jacobson-chain artifacts so you can surface
+   ECB and coverage smells alongside structural ones:
+   ```
+   npx archik q actors
+   npx archik q usecases
+   npx archik trace --json
+   ```
+   (These are non-fatal if no UC/actor files exist — note that
+   and skip the UC smells below; focus on structural smells only.)
+
+   **Identify nodes at risk of seq breakage.** As you read the
+   node list, mentally note which nodes you're likely to remove,
+   split, or merge. For each such node, run:
+   ```
+   npx archik q sequences --node <id>
+   ```
+   This returns the seq files whose participants reference that
+   node ID. Collect these — you'll need the list in step 6 to
+   warn the user. If the list is empty for all affected nodes,
+   no seq diagrams are at risk.
+
 3. **Identify smells and missing structure.** Don't propose change
    for change's sake — every modification should fix one of:
 
@@ -68,6 +89,26 @@ any file under `.archik/`.
    - **Anaemic queues.** Two services connected by `http_call`
      for what's clearly an async fire-and-forget → introduce a
      `queue` or `topic` and rewire to `publishes` / `subscribes`.
+   - **Missing ECB stereotypes.** Only applies when actor/UC files
+     exist (`npx archik q usecases` returns results). Nodes that
+     appear in active UC slices (visible in `archik trace` output),
+     or that have user-facing relationships (`http_call` from a
+     gateway, `writes`/`reads` to a domain DB) but no `stereotype`
+     field → classify each as `boundary`, `control`, or `entity`.
+     This is a prerequisite for ECB validation on seq diagrams.
+     Evolve may **add** a stereotype to nodes spawn left blank, but
+     only when this smell is triggered. Never invent stereotypes on
+     a pure structural diagram with no UC files.
+   - **UC coverage gaps.** Only applies when UC files exist and
+     `archik trace --json` returns rows. Active slices that are
+     `partial` (tests exist but no seq realization) usually signal
+     a missing seq diagram or a missing port/adapter in the
+     structural model. Active slices that are `none` (no tests, no
+     realization) signal untested behaviour — propose a test
+     scaffold or a seq diagram, and flag any architectural gap that
+     makes the slice hard to realize (e.g. missing adapter for an
+     external call). If trace output is empty or all slices are
+     `full`, skip this smell.
 
    Aim for 3–8 changes — enough to be meaningful, few enough that
    the user can reason about each. If you'd need more, propose
@@ -102,8 +143,9 @@ any file under `.archik/`.
    - Preserve every existing node id you keep — only add or remove
      ids, never rename. Renames break diff and require the user to
      manually re-link references in code.
-   - Don't drop `description`, `responsibilities`, `notes`, or
-     `sourcePath` fields the user authored. Carry them over verbatim.
+   - Don't drop `description`, `responsibilities`, `notes`,
+     `sourcePath`, or `stereotype` fields the user authored. Carry
+     them over verbatim.
    - Every new code-bearing node (`service`, `function`, `worker`,
      `module`, `page`, `component`, `store`, `hook`) needs a
      `sourcePath:` that exists on disk — the validator rejects
@@ -117,6 +159,9 @@ any file under `.archik/`.
      until the code lands.
    - Every node MUST have a non-empty `description` explaining
      what it does. Don't introduce a node without one.
+   - When adding a `stereotype` to address the ECB smell, use only
+     `boundary`, `control`, or `entity`. Don't add `stereotype` to
+     purely infra nodes (`database`, `queue`, `external`, `cloud`).
    - Every change should be motivated by step 3, not by aesthetics.
 
    If `suggest set` reports validation errors, re-run with the
@@ -130,7 +175,13 @@ any file under `.archik/`.
       grouped by motivation (e.g. *"1. Extract a `payments`
       bounded context from `orders`. Why: payment logic was leaking
       into order placement…"*). Keep each item to 2–3 sentences.
-   c. An explicit invitation: *"Tell me what you'd like to keep,
+   c. **Seq diagram impact warning** — if any seq file discovered
+      in step 2 references a node that this proposal removes or
+      renames, list them explicitly:
+      *"⚠️ These seq diagrams reference nodes this refactor
+      changes — they will need updating after accept: `<list>`."*
+      If no seq files are affected, skip this bullet.
+   d. An explicit invitation: *"Tell me what you'd like to keep,
       drop, or rework before you accept. I can re-stage with
       changes — `/archik:accept` is whenever you're ready."*
 

package/.claude/commands/archik/spawn.md

@@ -87,11 +87,29 @@ archik suggest set` stages it.
    - **Frontends**: `apps/web`, `apps/mobile`, `client/`,
      `packages/ui` apps that ship a UI → `frontend`.
 
-5. **Choose the kind for each node.** Default: `service`. Use the
-   taxonomy from the skill — `function` for serverless, `worker`
-   for background consumers, `agent` for LLM-driven agents, etc.
-   When unsure, pick the closest fit and add a `notes:` entry
-   explaining the inference rather than picking `custom`.
+5. **Choose the kind and ECB stereotype for each node.** Default
+   kind: `service`. Use the taxonomy from the skill — `function`
+   for serverless, `worker` for background consumers, `agent` for
+   LLM-driven agents, etc. When unsure, pick the closest fit and
+   add a `notes:` entry explaining the inference.
+
+   For every node that faces a user or external system, also infer
+   its ECB `stereotype`:
+   - `stereotype: boundary` — accepts requests from actors / external
+     systems: API handlers, gateways, adapters, webhook endpoints,
+     BFF layers. Rule of thumb: the first thing an actor touches.
+   - `stereotype: control` — orchestrates use-case logic: services
+     that coordinate domain objects, use-case handlers, workflow
+     engines. Rule of thumb: knows *what* to do but delegates *how*.
+   - `stereotype: entity` — stores or represents domain data:
+     repositories, domain models, DB-backed modules, caches.
+     Rule of thumb: knows the data and its invariants.
+
+   If a node's role is purely infrastructure (`database`, `queue`,
+   `external`, `cloud`, etc.) or genuinely ambiguous, omit
+   `stereotype` — don't guess. The field is optional and the
+   validator only enforces ECB transition rules on seq diagrams
+   that carry a `realizes` block.
 
 6. **Attach `sourcePath` to every code-bearing node.** This is
    non-negotiable in a normal/suggested file — the validator rejects
@@ -205,6 +223,28 @@ archik suggest set` stages it.
      `/archik:evolve` after accepting if you want a cleaner
      bounded-context version."
 
+   **Offer the Jacobson-chain follow-up at the end of this step**
+   (not after accept — you won't be there). Check what's missing
+   before framing the offer:
+   ```
+   npx archik q actors
+   npx archik q usecases
+   ```
+   Then close with one of these follow-up lines, whichever fits:
+   - No actors, diagram has boundary nodes / user-facing components:
+     *"Once you accept, ask me to author a `*.archik.actors.yaml`
+     — that's the starting point for use-case coverage."*
+   - Actors exist but no use cases:
+     *"Once you accept, ask me to stub `*.archik.uc.yaml` files for
+     the key flows."*
+   - Both exist already:
+     *"Run `/archik:evolve` after accepting for ECB and coverage
+     gap suggestions."*
+
+   Do NOT author actors or use cases here — that requires the
+   structural diagram to be accepted first and is a separate ask
+   from the user. This note is a prompt, not an action.
+
 ## Notes
 
 - Spawn is descriptive, not prescriptive. Don't reorganize, split,

package/.claude/commands/archik/suggest.md

@@ -37,6 +37,10 @@ start Build phase here; that's gated on accept.
 0. **Frame + clarify (entering DESIGN).** Before any CLI call, restate
    the user's intent in one sentence and list 1–3 sharp clarifying
    questions if any of these are ambiguous in `$ARGUMENTS`:
+   - **Actor + use case** — which actor initiates this? Does an
+     existing use case cover it, or is this a new user-visible
+     behaviour? (Check `npx archik q actors` and `q usecases` in
+     step 2 before asking if the answer isn't obvious from the brief.)
    - **Boundary** — which existing context owns this, or is it a new
      one? (data ownership = bounded context)
    - **Sync vs async** — request/response (`http_call`) or
@@ -53,6 +57,15 @@ start Build phase here; that's gated on accept.
    don't ask questions for the sake of asking.** When in doubt, ask
    the user "you decide?" so they can defer back if they want.
 
+   **Before the structural sidecar, check if the feature needs
+   requirements artifacts first:**
+   - New human-facing flow or actor? Create/update
+     `*.archik.actors.yaml` (direct-write) before staging the sidecar.
+   - New user-visible behaviour? Author a `*.archik.uc.yaml` under
+     `.archik/usecases/` (direct-write) with the flow and at least one
+     slice before staging the sidecar. The structural model references
+     what the use case requires.
+
 1. **Make sure the canvas is running** so the user can review:
    ```
    npx archik status
@@ -63,7 +76,7 @@ start Build phase here; that's gated on accept.
    ```
    Note the URL it prints — you'll surface it at the end.
 
-2. **Ground yourself in the current diagram** using the query CLI
+2. **Ground yourself in the current models** using the query CLI
    (do not `cat` the YAML):
    ```
    npx archik q stats
@@ -72,6 +85,23 @@ start Build phase here; that's gated on accept.
    If `$ARGUMENTS` mentions a specific node by name, also run
    `npx archik q describe <id>` for it.
 
+   If the change is **non-trivial** (new actor, new user-visible
+   behaviour, boundary impact, more than one node affected) also
+   ground in the requirements model:
+   ```
+   npx archik q actors
+   npx archik q usecases
+   ```
+   If any use case looks related, run
+   `npx archik q describe-usecase <id>` to see its slices and
+   check whether the proposed change extends, modifies, or
+   introduces a UC — that determines whether you need to update
+   a `*.archik.uc.yaml` before staging the structural sidecar.
+
+   If step 0 already determined the change is trivially small
+   (one node, one edge, no boundary or UC impact), skip the
+   actor/UC queries and go straight to step 3.
+
 3. **Lock in the schema.** Run this before drafting any YAML —
    the prose in this file describes the workflow, not the field
    shapes. The CLI is the schema:
@@ -104,6 +134,18 @@ start Build phase here; that's gated on accept.
    not just its kind or name. Empty / missing descriptions are
    rejected by the validator.
 
+   **For nodes that participate in a use case flow**, add a
+   `stereotype` field to classify their role in the ECB model:
+   - `stereotype: boundary` — accepts requests from actors / external
+     systems (adapters, gateways, API handlers)
+   - `stereotype: control` — orchestrates the use case logic (services,
+     use-case handlers, orchestrators)
+   - `stereotype: entity` — stores or represents domain data (repos,
+     domain models, DB-backed modules)
+
+   The validator enforces ECB transition rules on seq diagrams that
+   carry a `realizes` block — tag the nodes now so the rules can fire.
+
    ```bash
    npx archik suggest set --note "$ARGUMENTS" - <<'YAML'
    version: "1.0"

package/.claude/skills/archik/SKILL.md

@@ -39,6 +39,12 @@ These are the verbs you reach for during the loop. Default to `npx archik` (no g
 | Inspect the current diagram       | `npx archik q list \| edges \| stats`         |
 | Look up one node                  | `npx archik q describe <id>`                  |
 | Find dependencies / impact        | `npx archik q deps \| dependents \| impact <id>` |
+| List use cases (filter by actor)  | `npx archik q usecases [--actor <id>]`        |
+| Describe one use case             | `npx archik q describe-usecase <id>`          |
+| List actors                       | `npx archik q actors`                         |
+| Use case coverage matrix          | `npx archik trace [--json] [--fail-on partial\|none]` |
+| Alpha state snapshot              | `npx archik alpha show [--json]`              |
+| Promote / demote an alpha state   | `npx archik alpha promote\|demote <alpha> <state>` |
 | Validate a file                   | `npx archik validate <path>`                  |
 | Stage a proposed change           | `npx archik suggest set --note '…' - <<'YAML' … YAML` |
 | Show / accept / reject pending    | `npx archik suggest show \| accept \| reject` |
@@ -55,7 +61,11 @@ You MUST NOT use `Read`, `Write`, or `Edit` against any file under `.archik/`, a
 
 If `npx archik` is unreachable (offline, sandboxed, missing), STOP and tell the user. Do NOT fall back to reading or editing YAML by hand.
 
-**Exception:** sequence diagrams (`*.archik.seq.yaml`) have **no sidecar workflow** — create or edit them directly with `Write` / `Edit`, then validate via `npx archik validate`. See "Sequence diagrams" below.
+**Exception:** four file types have **no sidecar workflow** — create or edit them directly with `Write` / `Edit`, then validate via `npx archik validate`:
+- `*.archik.seq.yaml` — sequence diagrams (see "Sequence diagrams" below)
+- `*.archik.actors.yaml` — actor definitions (see "Actors" below)
+- `*.archik.uc.yaml` — use cases (see "Use cases and slices" below)
+- `*.archik.alphas.yaml` — Essence alpha snapshot (see "Alpha state" below)
 
 ## The engineering loop (how archik fits into delivering work)
 
@@ -88,11 +98,11 @@ Every structural change runs the loop. Don't skip phases; don't silently retry o
 
 | Phase    | Driver        | Tool you reach for                                  |
 | -------- | ------------- | --------------------------------------------------- |
-| Discover | Claude        | `npx archik q ...` + source-tree `ls`               |
-| Design   | Claude → User | sidecar via `suggest set`, after 1–3 clarifying Qs  |
+| Discover | Claude        | `npx archik q ...` + `q usecases` + `q actors` + `ls` |
+| Design   | Claude → User | actors / uc files (direct-write) + sidecar via `suggest set` |
 | Decide   | User          | `/archik:accept` or `/archik:reject` (HITL gate)    |
 | Build    | Claude → User | numbered plan (HITL approval), then small commits   |
-| Verify   | Claude        | `npx archik validate` + tests + `drift` + SVG regen |
+| Verify   | Claude        | `npx archik validate` + `archik trace` + tests + `drift` + SVG regen |
 
 **Two non-obvious feedback edges:**
 
@@ -247,6 +257,9 @@ The seq schema (UML subset) is documented at the bottom of this file under "Sequ
 | `*.archik.yaml`             | **normal**    | The canonical architecture of code that exists.                                     |
 | `*.archik.suggested.yaml`   | **suggested** | A pending change to a normal file. Owned by `suggest set`. Becomes normal on accept. |
 | `*.archik.seq.yaml`         | **sequence**  | A runtime flow diagram. Direct-write. No sidecar.                                   |
+| `*.archik.actors.yaml`      | **actors**    | Who acts on the system (human / external-system / time / device). Direct-write.     |
+| `*.archik.uc.yaml`          | **use case**  | One use case: flows + slices + test paths. Lives under `.archik/usecases/`. Direct-write. |
+| `*.archik.alphas.yaml`      | **alphas**    | Project-wide Essence alpha state snapshot. Direct-write.                            |
 
 There is no separate "discussion" file mode. Greenfield / exploratory work is expressed via `status: proposed` on the affected nodes and edges (see Lifecycle below). The diagram stays canonical.
 
@@ -286,6 +299,18 @@ Both **nodes and edges** carry an optional `status`. Same enum, same defaults, s
 
 For edges, `status: proposed` expresses "this dependency is planned" (e.g. *"orders-api will start subscribing to `payments.completed` next sprint"*). `archik drift` and the validator both respect lifecycle so proposed nodes don't trigger missing-source warnings before they're built.
 
+### Node stereotype — ECB classification
+
+Nodes that participate in a use case flow may carry an optional `stereotype` field:
+
+```yaml
+stereotype: boundary   # accepts requests from actors / external systems
+stereotype: control    # orchestrates; implements the use case logic
+stereotype: entity     # stores data; domain model
+```
+
+The validator enforces the ECB transition rules on **seq diagrams that carry a `realizes` block**: actors call boundaries, boundaries call controls, controls call entities or other controls. Direct actor→entity or entity→boundary messages are errors. Untagged nodes are silently skipped so adoption is incremental.
+
 ### Other rules worth pre-empting
 
 - **No duplicate edges by `(from, to, relationship)`.** The validator rejects the second occurrence and points at the first by id. If you genuinely need two concerns between the same pair (e.g. `service → db` for both `reads` and `writes`), use distinct relationships.
@@ -306,6 +331,7 @@ Run a candidate through this checklist before staging a sidecar. Each item is a
 - **Ports & adapters at the edge.** External integrations sit behind an `external` node, never inline in a service. Port (interface) + adapter (concrete) is preferred when the integration could swap.
 - **Public traffic → gateway/auth upstream.** Anything user-facing routes through a `gateway`/`auth` node, not directly to a service.
 - **Failure modes.** Async producers imply DLQ/retry on the consumer; `http_call` implies timeout + circuit. Don't draw the happy path alone.
+- **Use case participation → ECB classification.** If a node appears in any active use case slice (check `npx archik q usecases` or trace output), it needs a `stereotype: boundary | control | entity` before the seq diagram is authored. An unclassified node in a `realizes`-linked seq passes structurally but defeats ECB rule enforcement. Classify now; the validator will catch violations at seq-authoring time, not at code-review time.
 - **Lifecycle honesty.** Code-bearing node without code on disk → `status: proposed`. About to be removed → `status: deprecated`.
 
 ## When to propose, when to defer
@@ -360,6 +386,97 @@ The loop is self-contained, but these sharpen specific phases when the user has
 |         | `superpowers:requesting-code-review`           |
 | Verify  | `superpowers:verification-before-completion`   |
 
+## Actors
+
+Actors live in `.archik/actors.archik.actors.yaml` (one file per project). Direct-write — no sidecar. Schema: `npx archik schema actors`.
+
+```yaml
+version: "1.0"
+actors:
+  - id: customer
+    kind: human              # human | external-system | time | device
+    description: End-user buying products.
+    goals: [place-orders, view-history]   # optional free text
+  - id: payments-gw
+    kind: external-system
+    description: Stripe — charges cards and issues refunds.
+```
+
+Use cases reference actors by `id`. The validator rejects a use case whose `primaryActor` isn't in the actor index.
+
+## Use cases and slices
+
+One file per use case under `.archik/usecases/<id>.archik.uc.yaml`. Direct-write — no sidecar. Schema: `npx archik schema uc`.
+
+```yaml
+version: "1.0"
+id: place-order
+kind: useCase
+name: Place an order
+status: active
+primaryActor: customer
+secondaryActors: [payments-gw]
+goal: Customer pays for items in cart and receives confirmation.
+flows:
+  basic:
+    steps:
+      - Customer submits cart.
+      - System reserves inventory.
+      - System charges payment method.
+      - System persists order and emits OrderPlaced.
+  alternates:
+    - id: payment-declined
+      branchFrom: basic.3
+      steps: [Payment gateway returns decline, System releases inventory.]
+slices:
+  - id: happy-path
+    description: Full successful purchase.
+    flows: [basic]
+    tests: [tests/e2e/place-order.happy.spec.ts]   # must exist on disk for active slices
+    realization:
+      seqFile: .archik/place-order.happy.archik.seq.yaml
+  - id: declined
+    description: Payment gateway declines.
+    flows: [basic, payment-declined]
+    tests: [tests/e2e/place-order.declined.spec.ts]
+```
+
+**Validation rules:**
+- `primaryActor` and `secondaryActors` must resolve in the actor index.
+- Active slice `tests` paths must exist on disk (same discipline as `sourcePath`).
+- If `realization.seqFile` is set, the named seq file must exist AND carry a matching `realizes` block (bidirectional).
+- `flows.basic` is required; `alternates[].branchFrom` must reference an existing flow + step number.
+
+Query: `npx archik q usecases [--actor <id>]` | `npx archik q describe-usecase <id>`
+
+## Alpha state
+
+One file per project: `<name>.archik.alphas.yaml`. Direct-write. Tracks four Essence alphas that archik can directly evidence: **stakeholders**, **requirements**, **softwareSystem**, **work**.
+
+```yaml
+version: "1.0"
+alphas:
+  stakeholders:
+    state: represented     # conceived | recognised | represented | involved | in-agreement | satisfied
+    evidence: ["developer (human) + claude (external-system) in actors file"]
+  requirements:
+    state: acceptable      # conceived | bounded | coherent | acceptable | addressed | fulfilled
+    note: "All active slices test-backed; rejected slice still needs a realization seq."
+  softwareSystem:
+    state: usable          # architecture-selected | demonstrable | usable | ready | operational | retired
+  work:
+    state: under-control   # initiated | prepared | started | under-control | concluded | closed
+```
+
+Manage states with:
+```bash
+npx archik alpha show                              # verification badges: ✓ verified | ✗ over-claimed | ? subjective
+npx archik alpha promote requirements addressed    # runs machine check before writing
+npx archik alpha demote softwareSystem usable      # no check on demote
+```
+
+The validator checks machine-checkable states (e.g. `requirements.acceptable` requires every active slice to have on-disk tests). Over-claimed states are flagged `✗` — downgrade or fix the artifacts.
+
 ## Sequence diagram schema reference
 
 ```yaml
@@ -367,6 +484,12 @@ version: "1.0"          # required, literal
 name: "Login flow"      # required, non-empty
 description: "..."      # optional
 
+realizes:               # optional — links this seq to a use case slice
+  useCase: place-order  # use case id (must exist in .archik/usecases/)
+  slice: happy-path     # slice id within that use case
+                        # validator enforces bidirectional integrity:
+                        # the slice's realization.seqFile must name THIS file
+
 participants:           # required, at least one
   - id: browser         # participant ref id (used in steps)
     nodeId: frontend    # architecture node id this participant maps to
@@ -453,12 +576,28 @@ Run `npx archik <cmd> --help` for the per-command surface.
 npx archik schema                       # the document shape (start here when authoring)
                   --json                #   structured shape for piping into jq
                   --seq                 #   seq diagram schema instead of arch schema
+                  uc                    #   use case schema
+                  actors                #   actors schema
 
 npx archik q describe <id> | deps <id> | dependents <id>
                   list | edges | impact <id> | stats
                   sequences [--node <id>]   # list seq diagrams; --node filters to flows involving a node
+                  usecases [--actor <id>]   # list use cases; filter by actor
+                  describe-usecase <id>     # one use case in detail
+                  actors                    # list actors
                   --json                #   stable machine-readable shape
 
+npx archik trace [--json]               # coverage matrix: use case × slice × test × seq × ECB
+                  --use-case <id>       #   filter to one use case
+                  --actor <id>          #   filter by actor
+                  --status active|proposed|deprecated
+                  --coverage full|partial|none
+                  --fail-on partial|none    # exit 1 for CI gates
+
+npx archik alpha show [--json]          # alpha state snapshot with verification badges
+              alpha promote <alpha> <state> [--note <text>]   # runs machine check first
+              alpha demote <alpha> <state>
+
 npx archik validate <path> [--json]     # schema + cross-file check (CI-friendly)
 npx archik render --out diagram.svg --theme light|dark
               render --seq <path> --out seq.svg --theme light|dark