archik 0.6.21 → 0.7.0

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

@@ -0,0 +1,21 @@
+---
+description: Apply the pending archik suggestion sidecar over the main file
+---
+
+# /archik:accept — apply the pending suggestion
+
+The user wants to accept the pending architecture suggestion.
+
+Run the CLI — do NOT edit any archik file by hand:
+
+```
+npx archik suggest accept
+```
+
+If it exits 0, also run `npx archik validate` to confirm the new main
+file is clean, and tell the user it's applied.
+
+If it exits non-zero (no sidecar present, or the sidecar fails to
+parse), surface the error to the user verbatim and stop. Do not
+attempt to fix the sidecar by editing it; ask the user how they
+want to proceed.

package/.claude/commands/archik/describe.md

@@ -0,0 +1,28 @@
+---
+description: Describe a node in the archik diagram and its incoming/outgoing edges
+argument-hint: <node-id>
+---
+
+# /archik:describe — explain a node from the archik diagram
+
+The user wants details about the node with id **$ARGUMENTS**.
+
+Use the query CLI — do NOT `cat` or read any archik YAML directly:
+
+```
+npx archik q describe $ARGUMENTS
+```
+
+If you need adjacent context, also run:
+
+```
+npx archik q deps $ARGUMENTS
+npx archik q dependents $ARGUMENTS
+```
+
+Summarize what came back in plain prose: the node's kind and stack,
+what it depends on, what depends on it, and any responsibilities or
+notes. Don't dump the raw CLI output unless the user asks for it.
+
+If the CLI exits 1 (unknown id), tell the user and offer to run
+`npx archik q list` to find the right id.

package/.claude/commands/archik/dev.md

@@ -0,0 +1,24 @@
+---
+description: Start the archik live canvas in the browser (detached)
+---
+
+# /archik:dev — open the archik canvas
+
+The user wants the live archik canvas running so they can see the
+diagram and review suggestions visually.
+
+Run the CLI — do NOT spawn dev servers any other way:
+
+```
+npx archik status
+```
+
+If nothing is running for this project, start it detached:
+
+```
+npx archik start
+```
+
+Surface the URL it prints (or the existing URL from `status`) so the
+user can click straight to it. Do not try to open the browser
+yourself.

package/.claude/commands/archik/reject.md

@@ -0,0 +1,16 @@
+---
+description: Discard the pending archik suggestion sidecar
+---
+
+# /archik:reject — discard the pending suggestion
+
+The user wants to throw away the pending architecture suggestion.
+
+Run the CLI — do NOT delete files manually:
+
+```
+npx archik suggest reject
+```
+
+Surface the result to the user. If there was no pending sidecar, the
+command will say so — pass that through unchanged.

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

@@ -0,0 +1,73 @@
+---
+description: Propose architecture changes to the archik diagram from a feature description
+argument-hint: <feature description>
+---
+
+# /archik:suggest — propose architecture changes
+
+The user wants you to capture the structural impact of a feature in
+the archik diagram. The user-facing description is:
+
+**$ARGUMENTS**
+
+This slash command IS the user's confirmation that they want a
+sidecar suggestion. Skip the "want me to update the YAML?" question
+and produce one now.
+
+## CLI-only — do not touch archik files directly
+
+You MUST interact with archik exclusively through the `npx archik`
+CLI. Do NOT use Read, Write, or Edit on any file under `.archik/`,
+on `architecture.archik.yaml`, or on any sidecar. The CLI is the
+sanctioned interface; everything else is a manual edit and breaks
+the contract with the user.
+
+## Steps
+
+1. **Make sure the canvas is running** so the user can review:
+   ```
+   npx archik status
+   ```
+   If nothing is running for this project, start it detached:
+   ```
+   npx archik start
+   ```
+   Note the URL it prints — you'll surface it at the end.
+
+2. **Ground yourself in the current diagram** using the query CLI
+   (do not `cat` the YAML):
+   ```
+   npx archik q stats
+   npx archik q list
+   ```
+   If `$ARGUMENTS` mentions a specific node by name, also run
+   `npx archik q describe <id>` for it.
+
+3. **Author the draft** in a workspace temp file (NOT under
+   `.archik/`). Use the path `/tmp/archik-draft-<short-id>.yaml`.
+   The draft is the *full proposed end-state* of the document — every
+   node and edge, not just the delta. Follow the schema, kinds, and
+   relationships documented in the archik skill.
+
+4. **Stage the draft as the sidecar via the CLI**:
+   ```
+   npx archik suggest set /tmp/archik-draft-<id>.yaml --note "$ARGUMENTS"
+   ```
+   This validates the schema, checks cross-file references, stamps
+   `metadata.suggestion`, and atomically renames it into place. If
+   the command exits non-zero, fix the reported errors in the temp
+   file and re-run — never edit the sidecar directly.
+
+5. **Tell the user how to review**. Surface the canvas URL from
+   step 1 plus the terminal options:
+   - "📝 Suggestion ready — open the canvas at <URL> and use the
+     **Review** banner to see added/removed/changed nodes."
+   - "Or from the terminal: `npx archik suggest show` /
+     `npx archik suggest accept` / `npx archik suggest reject`."
+
+## Notes
+
+- If a sidecar already exists, `suggest set` overwrites it. Mention
+  to the user that you replaced their previous pending suggestion.
+- If `npx archik` is unreachable (offline, sandboxed), STOP and tell
+  the user. Do not fall back to writing YAML by hand.

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

@@ -1,6 +1,6 @@
 ---
 name: archik
-description: Use whenever .archik/main.archik.yaml or architecture.archik.yaml exists in the project, or the user asks about the system's architecture, services, dependencies, or data flow. The YAML is the shared map of the project between the user and Claude — read it before answering structural questions, and propose updates when work introduces or changes nodes/edges. Also covers the archik CLI for validation and rendering.
+description: Use whenever .archik/main.archik.yaml or architecture.archik.yaml exists in the project, or the user asks about the system's architecture, services, dependencies, or data flow. The YAML is the shared map between the user and Claude. Interact with it ONLY through the `npx archik` CLI — `q` for queries, `suggest set` for proposals, `validate` after every change. Never read, write, or edit archik files manually.
 ---
 
 # Archik — the project's shared map
@@ -20,29 +20,66 @@ The file lives in one of two places, in this order of preference:
 2. `architecture.archik.yaml` — the legacy root location, still
    fully supported.
 
-Run `archik validate` (or check both paths) to find which one the
+Run `npx archik validate` (or check both paths) to find which one the
 project uses. Don't assume — small differences here matter.
 
 Treat the file as a shared vocabulary. It exists so the user and
 you can talk about the system without re-explaining it every time.
 
+## Hard rule: the CLI is the only interface to archik files
+
+You MUST NOT use `Read`, `Write`, `Edit`, or any other file-touching
+tool against `.archik/main.archik.yaml`, `architecture.archik.yaml`,
+any `*.archik.yaml` sub-file, or any sidecar. The `npx archik` CLI is
+the contract — it owns reads, writes, validation, and lifecycle.
+
+| Need                          | Use                                       |
+| ----------------------------- | ----------------------------------------- |
+| Inspect structure             | `npx archik q ...`                        |
+| Validate                      | `npx archik validate <path>`              |
+| Propose a change              | `npx archik suggest set <draft>`          |
+| Apply / discard a suggestion  | `npx archik suggest accept | reject`      |
+| Render or diff                | `npx archik render` / `npx archik diff`   |
+
+`.archik/main.archik.yaml` is the user's source of truth — only
+`npx archik suggest accept` is allowed to mutate it. The sidecar
+`.archik/main.archik.suggested.yaml` is owned by the CLI too — only
+`npx archik suggest set` (writes it) and `accept` / `reject`
+(consumes it) may touch it.
+
+If `npx archik` is unreachable (offline, sandboxed, missing), STOP
+and tell the user. Do NOT fall back to reading or editing YAML by
+hand — that breaks the contract and silently desyncs the canvas.
+
+The user-facing slash commands (`/archik:suggest`,
+`/archik:describe`, `/archik:accept`, `/archik:reject`,
+`/archik:dev`) are thin shims over this same CLI. When a user types
+`/archik:suggest <description>`, treat it as direct authorisation to
+run the sidecar workflow now — skip the "want me to update the YAML?"
+question.
+
 ## Protocol
 
 1. **Before** answering structural questions — *"what does X do?",
-   "what depends on Y?", "where does data flow when …?"* — read
-   the archik file. Don't guess from filenames or memory.
-2. **When** work introduces, removes, or rewires components, write
-   the proposed end-state to a sibling `*.suggested.yaml` next to
-   the main file (same schema, plus a `metadata.suggestion` block —
-   see "Suggesting changes" below). Don't edit the main file
-   directly; the user reviews and accepts in the canvas or via
-   `archik suggest accept`.
-3. **After** every edit to a YAML, run `archik validate <path>`
-   against the file you actually wrote — the canonical root file, a
-   sidecar, or any sub-file under `.archik/`. Validate covers schema
-   errors AND cross-file existence (`archikFile` / `fromFile` /
-   `toFile` targets must be on disk). Fix every reported error before
-   declaring the change done.
+   "what depends on Y?", "where does data flow when …?"* — query
+   the diagram with `npx archik q ...` (see CLI section). The CLI
+   walks the root file plus every `.archik/*.archik.yaml` sub-file
+   and returns focused, deterministic answers. Don't guess from
+   filenames or memory, and don't read the YAML directly — see the
+   hard rule above.
+2. **When** work introduces, removes, or rewires components, author
+   the proposed end-state in a workspace temp file (e.g.
+   `/tmp/archik-draft-<id>.yaml`) and stage it as the sidecar with
+   `npx archik suggest set <tmp> --note "<one-liner>"`. Do NOT
+   write `.archik/main.archik.suggested.yaml` directly — the CLI is
+   the only thing allowed to put files in `.archik/`. The user
+   reviews and accepts in the canvas or via
+   `npx archik suggest accept`.
+3. **After** every `suggest set`, the CLI has already validated for
+   you — schema, cross-file existence, the lot. If it exits non-zero,
+   fix the temp draft and re-run; never patch the sidecar directly.
+   For files outside `.archik/` (none, in a normal flow), use
+   `npx archik validate <path>`.
 
 The sections below are the detailed reference behind these three
 rules — *when* to consult, *when* to propose, schema, taxonomy,
@@ -55,16 +92,21 @@ The archik file tells you *what* exists. The source tree tells you
 the file is valuable — without it you just know there's "an Orders
 service" but not where to go to read or edit it. So:
 
-1. **Read the archik file in full.** Use `archik validate` first to
-   find the canonical path (it prefers `.archik/main.archik.yaml`,
-   falls back to `architecture.archik.yaml`). Then `cat` it —
-   don't grep, you want the whole shape in your head.
+1. **Pull the diagram shape from the CLI.** Don't `cat` the YAML —
+   use the query CLI:
+   ```
+   npx archik q stats     # files, node and edge counts, kind histogram
+   npx archik q list      # every node, with kind and parent
+   npx archik q edges     # every edge, with relationship and endpoints
+   ```
+   That gives you the same picture as reading the file, without
+   touching it.
 2. **List the source tree.** A single `ls` of the top-level project
    directory plus the most likely source roots is usually enough:
-   `ls -F . src/ services/ packages/ apps/ 2>/dev/null`. If the
-   project has sub-architectures under `.archik/`, list those too
-   (`ls .archik/`) — they're how the user breaks the diagram up by
-   component.
+   `ls -F . src/ services/ packages/ apps/ 2>/dev/null`. (`ls
+   .archik/` is fine for *finding out which sub-architectures
+   exist*; don't open the YAMLs themselves — query them via
+   `npx archik q list --file <name>`.)
 3. **Build the mapping in your head.** Most projects follow one of
    two patterns: each top-level archik node id matches a folder
    under `src/` (or `services/` / `packages/`), or the `stack` /
@@ -81,74 +123,63 @@ service" but not where to go to read or edit it. So:
 When the user asks "where would I add X?" or "what's the right
 place for Y?", you should already have the answer because step 3
 gave it to you. When they ask "what would `archik render` show?",
-the answer is in step 1.
+run `npx archik render --out /tmp/preview.svg` and describe it.
 
 ## Suggesting changes (the sidecar workflow)
 
-The archik file is the user's source of truth. You don't get to
-mutate it directly. Instead, write your proposed end-state to a
-sidecar file in the same directory, with the same stem plus
-`.suggested`:
+The archik file is the user's source of truth. You don't mutate it
+directly, and you don't write the sidecar directly either — both are
+under `.archik/` and only the CLI is allowed to touch that
+directory (see the hard rule).
 
-```
-# new convention
-.archik/main.archik.yaml             ← truth — user owns it
-.archik/main.archik.suggested.yaml   ← your draft proposal
+The flow is always the same:
 
-# legacy layout — same naming rule, just at the root
-architecture.archik.yaml
-architecture.archik.suggested.yaml
-```
+1. Author the *full proposed end-state* document in a workspace temp
+   file outside `.archik/`. Pick a path like
+   `/tmp/archik-draft-<short-id>.yaml`.
+2. Run `npx archik suggest set <tmp> --note "<one-liner>"`. The CLI
+   parses, schema-validates, checks cross-file references, stamps
+   `metadata.suggestion`, and atomically renames the draft into
+   place as `.archik/main.archik.suggested.yaml` (or the legacy
+   `architecture.archik.suggested.yaml`).
+3. If `set` exits non-zero, fix the temp file based on the reported
+   errors and re-run. Never patch the sidecar with `Edit`/`Write`.
 
-The sidecar is a complete, valid Archik document — same schema as the
-main file, plus a `metadata.suggestion` block that marks it as a
-proposal:
+A minimal draft looks exactly like a normal archik document — the
+CLI fills in the suggestion marker for you, so you don't have to:
 
 ```yaml
 version: "1.0"
 name: My Architecture
-metadata:
-  suggestion:
-    from: .archik/main.archik.yaml
-    at: 2026-04-26T17:00:00Z
-    note: add Stripe payment flow         # optional one-liner
 nodes:
   # ... entire proposed end-state, not just the delta
 edges:
   # ...
 ```
 
-Once you've written the sidecar:
+Once `suggest set` has succeeded:
 
 * The canvas shows a **📝 Suggestion pending** banner with `Review`,
   `Accept`, `Reject` buttons. Review **toggles an in-canvas overlay
   on the same page** — added nodes/edges get green frames, removed
   ones get red dashed frames and dim out, changed ones get amber
-  frames, and each gets a `+` / `−` / `~` badge. The button label
-  flips to "Hide diff" while the overlay is on; click again to drop
-  back to the regular view. Accept renames the sidecar over the main
-  file; Reject deletes the sidecar. Both also clear review mode so
-  the canvas snaps back to the new truth.
-* From the terminal: `archik suggest show | accept | reject`.
+  frames, and each gets a `+` / `−` / `~` badge. Accept renames the
+  sidecar over the main file; Reject deletes the sidecar.
+* From the terminal: `npx archik suggest show | accept | reject`.
 
 If the user has no canvas open and asks "apply it", run
-`archik suggest accept` for them (only after they've explicitly
+`npx archik suggest accept` for them (only after they've explicitly
 asked).
 
 **Key rules:**
 
 * Write the *full proposed document*, not a patch. The diff is
   computed by archik between the main file and the sidecar.
-* Run `archik validate <sidecar-path>` after writing — that's
-  `.archik/main.archik.suggested.yaml` under the new layout, or
-  `architecture.archik.suggested.yaml` under the legacy one. Validate
-  catches schema errors (dangling edges, parent cycles, duplicate
-  ids) AND missing cross-file targets (`archikFile` / `fromFile` /
-  `toFile` resolved against the project root). Silent failures are
-  not OK — re-edit and re-run until it passes.
-* If a suggestion sidecar already exists, treat it as your previous
-  proposal — extend or replace it. Don't write a new sidecar with a
-  different name.
+* Don't call `Write`/`Edit` against `.archik/main.archik.suggested.yaml`
+  or any peer file under `.archik/`. The CLI owns that directory.
+* If a suggestion sidecar already exists, `npx archik suggest set`
+  overwrites it. Tell the user you're replacing their previous
+  pending suggestion.
 
 ## When to consult the YAML
 
@@ -189,7 +220,7 @@ The YAML tracks **shape**, not implementation detail.
 
 ## Hard rules for editing
 
-The schema enforces these — `archik validate` will reject the file
+The schema enforces these — `npx archik validate` will reject the file
 if you break any of them, so don't bother trying.
 
 - **Never put coordinates** (`x`, `y`, `width`, `height`, `viewport`) in
@@ -274,7 +305,7 @@ Constraints (the schema enforces them):
   forward slashes, no `..`, ends in `.archik.yaml`).
 - The path is resolved against the **project root** (parent of
   `.archik/` under the new layout, the doc's own directory under the
-  legacy one) — same rule as `archikFile`. `archik validate` exits
+  legacy one) — same rule as `archikFile`. `npx archik validate` exits
   1 if the file isn't on disk.
 - The *local* endpoint id must still match a node in this file.
 - An edge with **both** `fromFile` and `toFile` is rejected — author
@@ -297,7 +328,7 @@ Constraints (the schema enforces them):
 - **Resolved against the project root**, not the file's own
   directory. With the new layout the project root is the parent of
   `.archik/`, so a sibling sub-file is `.archik/orders.archik.yaml`
-  (with the prefix), NOT `orders.archik.yaml`. `archik validate`
+  (with the prefix), NOT `orders.archik.yaml`. `npx archik validate`
   exits 1 if the target file isn't on disk — catch it there instead
   of as a 404 in the canvas.
 - Cycles aren't checked at parse time (each file validates on its
@@ -601,51 +632,106 @@ edges:
 
 ## CLI
 
-These commands are available globally if archik was installed via
-`npm link`. Without a positional path, each command resolves the
-archik file in this order: `.archik/main.archik.yaml` (preferred),
-then `architecture.archik.yaml` (legacy). If both exist the
-command errors and asks the user to pick one.
+The CLI is the agent-friendly bridge to archik. Prefer it over
+re-reading the YAML when answering structural questions — the answers
+are deterministic, focused, and don't pollute your context with the
+whole diagram.
+
+### Running the CLI
+
+The CLI ships as the `archik` npm package. Two equivalent ways to
+invoke any command:
 
 ```
-archik validate                    # schema check (run after every edit)
-archik validate path/to/file.yaml
-archik render --out diagram.svg    # headless layout → SVG
-archik render --theme light --out diagram-light.svg
-archik diff a.yaml b.yaml          # text + colour-coded SVG diff
-archik diff a.yaml b.yaml --out diff.svg
-archik suggest show                # summary of pending sidecar (default)
-archik suggest accept              # apply the sidecar over the main file
-archik suggest reject              # discard the sidecar
-archik watch                       # re-render SVG on save
-archik dev                         # open the live editor in the browser (foreground)
-archik start                       # same as dev, detached — returns the prompt
-archik stop                        # stop the background server
-archik status                      # list running archik instances
-archik init                        # scaffold a starter file (also installs this skill into ./.claude/skills/archik/ unless --no-skill)
-archik skill                       # install/refresh this skill in cwd
+npx archik <command>      # works without installing — caches after first use
+archik <command>          # if the user has run `npm i -g archik`
 ```
 
-If `archik` isn't on PATH (the user hasn't run `npm link` yet), fall
-back to the in-repo form: `npm run archik -- <command>` from the
-archik checkout.
+**Default to `npx archik` in your suggestions and shell calls.** It
+just works in fresh repos, doesn't require a global install, and
+falls through to the cached binary on subsequent runs. Suggest
+`npm i -g archik` only when the user wants the live canvas
+(`archik dev`) on a fast keystroke.
+
+If neither form is reachable (offline, sandboxed shell), fall back to
+reading the YAML directly with the same schema documented above —
+the file is always the source of truth.
+
+### Without a positional path
+
+Every read command resolves the archik file in this order:
+`.archik/main.archik.yaml` (preferred), then
+`architecture.archik.yaml` (legacy). If both exist the command errors
+and asks the user to pick one.
+
+### Querying the diagram (use this for structural questions)
+
+```
+npx archik q describe <id>          # node + its incoming/outgoing edges
+npx archik q deps <id>              # outgoing edges (what this node uses)
+npx archik q dependents <id>        # incoming edges (what uses this node)
+npx archik q list                   # all nodes
+                  --kind <k>        #   filter by kind (service, function, …)
+                  --parent <id>     #   filter by container
+                  --file <p>        #   filter by file (substring match)
+npx archik q edges                  # all edges
+                  --from <id>       #   filter by source
+                  --to <id>         #   filter by target
+                  --rel <name>      #   filter by relationship
+npx archik q impact <id>            # what would break if this node were removed
+npx archik q stats                  # files, nodes, edges, kind histogram
+```
+
+Add `--json` to any `q` subcommand for a stable machine-readable
+shape (object on stdout). Exit codes: `0` found, `1` empty / unknown
+id, `2` could not load. Walks the root file plus every
+`.archik/*.archik.yaml` sub-file. Cross-file id collisions error
+rather than silently picking — surface the ambiguity.
+
+### Authoring & lifecycle
+
+```
+npx archik validate                # schema + cross-file existence (CI-friendly, exit 1 on error)
+npx archik validate --json         # structured { ok, file, nodes, edges, errors }
+npx archik render --out diagram.svg
+                  --theme light    # "dark" (default) or "light"
+npx archik diff a.yaml b.yaml      # text summary
+npx archik diff a.yaml b.yaml --out diff.svg
+npx archik diff a.yaml b.yaml --json
+npx archik suggest show            # summary of pending sidecar (default)
+                  --json           #   structured output
+npx archik suggest set <draft>     # validate a draft YAML and stage it as the sidecar
+                  --note '<text>'  #   set metadata.suggestion.note
+                  --main <path>    #   override main file detection
+                  --json           #   structured output
+                  -                #   draft path "-" reads from stdin
+npx archik suggest accept          # apply the sidecar over the main file
+npx archik suggest reject          # discard the sidecar
+npx archik watch                   # re-render SVG on save
+npx archik dev                     # open the live editor in the browser
+npx archik start | stop | status   # detached canvas server lifecycle
+npx archik init                    # scaffold a starter file + install skill + slash commands
+npx archik skill                   # install/refresh the Claude skill in cwd
+npx archik commands                # install/refresh the /archik:* slash commands in cwd
+```
 
 ## Verification workflow
 
-After **every** edit you make to an archik file (root, sidecar, or
-sub-file):
-
-1. Run `archik validate <path>` against the file you wrote. Validate
-   covers schema errors (with the field path so you can fix them
-   precisely) AND cross-file existence — `archikFile`, `fromFile`,
-   and `toFile` are resolved against the project root and the
-   command exits 1 if the target file isn't on disk. Fix every
-   reported error before declaring the change done.
-2. If the project has an `archik dev` server running, the file watcher
-   broadcasts the change automatically — no restart needed.
-3. If the project commits a rendered SVG (e.g. `docs/architecture.svg`),
-   regenerate it with `archik render --out docs/architecture.svg` so
-   the committed picture matches the YAML.
+After **every** `npx archik suggest set` or `npx archik suggest
+accept`:
+
+1. The CLI has already validated the schema and cross-file references
+   for you — `set` refuses to write a broken sidecar, `accept` runs
+   over a sidecar that was validated when it was staged. If `set`
+   reported errors, fix them in the temp draft and re-run; never
+   reach for `Write`/`Edit` on the sidecar.
+2. If the project has an `archik dev` server running, the file
+   watcher broadcasts the change to the canvas automatically — no
+   restart needed. Surface the URL so the user can click through.
+3. If the project commits a rendered SVG (e.g.
+   `docs/architecture.svg`), regenerate it with `npx archik render
+   --out docs/architecture.svg` so the committed picture matches the
+   YAML.
 
 ## Things to avoid
 

package/README.md

@@ -90,30 +90,36 @@ No `x` / `y` / `width` — layout is computed by [ELK](https://eclipse.dev/elk/)
 - **12 relationships** with distinct visual styling — `http_call`, `invokes`, `reads`, `writes`, `publishes`, `subscribes`, `streams_to`, `routes_to`, `implements`, `depends_on`, `has_a`, `uses`.
 - **Drag-to-connect, multi-select, undo/redo, compact view, themed (dark / light), notes per node, color overrides on edges.**
 - **CI-ready CLI** — `validate`, `render` (headless SVG), `watch`, `check` (drift between YAML and source dirs).
-- **AI skill** — `archik skill --user` installs a Claude Code skill that teaches Claude the schema, the protocol, and the verification workflow.
+- **AI skill + slash commands** — `archik skill --user` installs the Claude Code skill; `archik commands --user` installs `/archik:suggest`, `/archik:accept`, `/archik:reject`, `/archik:describe`, and `/archik:dev` so Claude drives the diagram entirely through the CLI.
 
 ## For Claude Code & other LLMs
 
 The whole reason Archik uses YAML instead of a binary format: **the file is the shared map between you and the model**. Run:
 
 ```bash
-archik skill --user        # install once into ~/.claude/skills
+archik skill --user        # install the skill into ~/.claude/skills
+archik commands --user     # install the /archik:* slash commands into ~/.claude/commands
 ```
 
-…and Claude Code in any project gets the right vocabulary automatically. The skill defines a 3-rule protocol:
+(Or just `archik init` in a fresh project — both land automatically.)
 
-1. **Read** `architecture.archik.yaml` before answering structural questions.
-2. **Propose** YAML updates whenever new work introduces or rewires components.
-3. **Run `archik validate`** after every edit to fail fast on schema errors.
+The skill enforces a hard rule: **Claude interacts with archik only through the `npx archik` CLI** — never `Read`, `Write`, or `Edit` on a YAML directly. Queries go through `npx archik q`, suggestions through `npx archik suggest set`, lifecycle through `npx archik suggest accept | reject`. The user owns the file; the CLI is the contract.
 
-So conversations like *"add a payments worker that subscribes to the orders queue"* end with both the code change **and** the matching YAML diff — kept in sync without anyone having to remember.
+Day-to-day this looks like:
+
+```
+/archik:suggest add a payments worker that subscribes to the orders queue
+```
+
+Claude grounds itself with `npx archik q stats`, drafts a full proposal in a temp file, runs `npx archik suggest set` to stage it as the canonical sidecar, and surfaces the canvas URL so you can review the diff overlay and Accept/Reject in the browser. No manual YAML edits, no chance of the canvas and the file disagreeing.
 
 ## Commands
 
 ```
 archik init [path]       Scaffold a starter .archik/main.archik.yaml
-                         (also installs the Claude skill by default)
+                         (also installs the Claude skill + /archik:* slash commands by default)
                          --no-skill       skip installing the Claude skill
+                         --no-commands    skip installing the /archik:* slash commands
 
 archik dev [path]        Open the canvas in your browser (foreground, Ctrl+C to stop)
 archik start [path]      Same as dev, but detached — prompt returns immediately
@@ -130,9 +136,22 @@ archik render [path]     Render to a self-contained SVG file
                          --theme <name>   "dark" (default) or "light"
 archik watch [path]      Re-render to SVG on every file change (Ctrl+C to stop)
 
+archik suggest [sub]     Manage Claude's pending architecture suggestion
+                         show             summarise the pending sidecar (default; --json supported)
+                         set <draft>      validate a draft YAML and stage it as the sidecar
+                                          --note '<text>'  set metadata.suggestion.note
+                                          --main <path>    override main file detection
+                                          --json           structured output
+                                          -                read draft from stdin
+                         accept           apply the sidecar over the main file
+                         reject           discard the sidecar
+
 archik skill             Install the Claude skill for AI editing
                          --user           install into ~/.claude/skills (all projects)
                          --force          overwrite an existing skill
+archik commands          Install the /archik:* slash commands for Claude Code
+                         --user           install into ~/.claude/commands (all projects)
+                         --force          overwrite existing commands
 ```
 
 Without a `[path]` argument, archik resolves the file in this order: