archik 0.6.21 → 0.7.1

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,86 @@ 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 are thin shims over this same CLI:
+
+| Command                | Purpose                                       |
+| ---------------------- | --------------------------------------------- |
+| `/archik:spawn`        | Bootstrap a diagram from the source tree       |
+| `/archik:evolve`       | Propose a cleaner bounded-context refactor    |
+| `/archik:suggest <…>`  | Propose changes from a feature description    |
+| `/archik:describe <id>`| Explain a node and its connections            |
+| `/archik:accept`       | Apply the pending suggestion                  |
+| `/archik:reject`       | Discard the pending suggestion                |
+| `/archik:dev`          | Start the live canvas                         |
+
+When a user types `/archik:suggest <description>`, `/archik:spawn`,
+or `/archik:evolve`, treat it as direct authorisation to run the
+sidecar workflow now — skip the "want me to update the YAML?"
+question. Each command's body file under `.claude/commands/archik/`
+has the detailed protocol for that specific verb; follow it.
+
+Three things separate the proposal commands:
+
+- **`spawn`** is *descriptive* — mirror the source tree as it is.
+- **`evolve`** is *prescriptive* — propose a cleaner shape, then
+  wait for the user to discuss before they accept. Never
+  auto-accepts.
+- **`suggest`** is *targeted* — apply one feature-sized change
+  from a user description.
+
 ## 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 +112,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 +143,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 +240,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 +325,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 +348,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 +652,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

@@ -26,10 +26,11 @@ queues, agents, LLMs, the edges between them. Plain YAML, schema-
 validated, no coordinates, no proprietary format.
 
 Open it in your browser for a live canvas. Render it in CI for a
-self-contained SVG. Install the [Claude Code skill](#for-claude-code--other-llms)
-so the model edits the same file you do — *the diagram and the
-codebase stop drifting because Claude treats the diagram as the
-spec*.
+self-contained SVG. The [Claude Code skill and `/archik:*` slash
+commands](#for-claude-code--other-llms) install automatically with
+`archik init`, so the model edits the same file you do — *the
+diagram and the codebase stop drifting because Claude treats the
+diagram as the spec*.
 
 If you've ever asked an AI agent "where would I add X?" and watched
 it guess from filenames, archik is the fix: the YAML answers the
@@ -38,13 +39,25 @@ work.
 
 ## Quickstart
 
+Two terminal commands, then talk to Claude:
+
 ```bash
-npx archik init       # scaffold .archik/main.archik.yaml in cwd
-npx archik start      # canvas at http://localhost:5173 (background)
-npx archik stop       # done
+npx archik@latest init       # scaffolds .archik/main.archik.yaml +
+                             # installs the Claude skill + /archik:* slash commands
+npx archik@latest start      # opens the live canvas at http://localhost:5173
+```
+
+Then in Claude Code, type:
+
+```
+/archik:spawn               # mirror your real source tree as the first diagram
+/archik:evolve              # propose a cleaner bounded-context refactor
+/archik:suggest <feature>   # propose changes for a specific feature
 ```
 
-That's the whole onboarding. The canvas saves edits straight back to the YAML; the file is the truth, the canvas is a projection.
+Each `/archik:*` command stages a suggestion sidecar — **Review** in the canvas, then **Accept** or **Reject**. No manual YAML editing on either side: you click in the browser, Claude drives through the CLI.
+
+Done with the canvas? `npx archik stop`.
 
 <p align="center">
   <video src="https://github.com/bacharSalleh/archik/raw/main/docs/record.mp4" poster="https://cdn.jsdelivr.net/gh/bacharSalleh/archik@main/docs/archik.gif" width="780" controls muted autoplay loop playsinline>
@@ -90,30 +103,57 @@ 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 init` installs both automatically. Seven `/archik:*` commands (`spawn`, `evolve`, `suggest`, `describe`, `dev`, `accept`, `reject`) drive the diagram entirely through the CLI, so Claude never edits YAML by hand.
 
 ## 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:
+The whole reason archik uses YAML instead of a binary format: **the file is the shared map between you and the model**. `npx archik@latest init` drops both the Claude skill and the seven slash commands into your project — no separate setup.
+
+The skill enforces a hard rule: **Claude talks to 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`. You own the file; the CLI is the contract.
+
+### The seven slash commands
+
+| Command                     | What it does                                                |
+| --------------------------- | ----------------------------------------------------------- |
+| `/archik:spawn`             | Bootstrap a diagram by mirroring your real source tree      |
+| `/archik:evolve`            | Propose a cleaner bounded-context refactor                  |
+| `/archik:suggest <feature>` | Propose changes for a specific feature                      |
+| `/archik:describe <id>`     | Explain a node and its connections                          |
+| `/archik:dev`               | Open the live canvas                                        |
+| `/archik:accept`            | Apply the pending suggestion                                |
+| `/archik:reject`            | Discard the pending suggestion                              |
+
+A typical first-day flow:
 
-```bash
-archik skill --user        # install once into ~/.claude/skills
 ```
+/archik:spawn                     # mirror what's there now
+                                  #   → review on the canvas, accept
+/archik:evolve                    # propose a cleaner shape
+                                  #   → discuss with Claude, accept (or iterate)
+/archik:suggest add Stripe webhook handler
+                                  #   → small, targeted change
+```
+
+Each command stages a sidecar via `npx archik suggest set`. The canvas shows a green/red/amber diff overlay; you click Accept or Reject — or `/archik:accept` / `/archik:reject` from the terminal. Same outcome either way.
 
-…and Claude Code in any project gets the right vocabulary automatically. The skill defines a 3-rule protocol:
+### Manual install (existing projects without `archik init`)
 
-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.
+If you already have an archik file and just want to add the Claude integration:
 
-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.
+```bash
+npx archik@latest skill --user        # install skill into ~/.claude/skills (all projects)
+npx archik@latest commands --user     # install /archik:* into ~/.claude/commands (all projects)
+```
+
+Drop the `--user` flag to scope to the current project only.
 
 ## 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 +170,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: