archik 0.12.37 → 0.12.39

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "archik",
+  "owner": {
+    "name": "Bashar",
+    "email": "welcomebachar@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "archik",
+      "source": ".",
+      "description": "Plain-YAML architecture diagrams + Jacobson use cases / actors / sequence diagrams / alphas, all CLI-mediated and validated. The skill enforces CLI-only access; the slash commands wrap the loop.",
+      "homepage": "https://github.com/bacharSalleh/archik#readme",
+      "license": "MIT",
+      "keywords": ["architecture", "diagram", "yaml", "jacobson", "ecb"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "archik",
+  "description": "The shared vocabulary between you and Claude Code, at the engineering level. Plain-YAML architecture diagrams + Jacobson use cases / actors / sequence diagrams / alphas, all CLI-mediated and validated.",
+  "author": {
+    "name": "Bashar",
+    "email": "welcomebachar@gmail.com"
+  },
+  "homepage": "https://github.com/bacharSalleh/archik#readme",
+  "repository": "https://github.com/bacharSalleh/archik",
+  "license": "MIT",
+  "keywords": [
+    "architecture",
+    "diagram",
+    "yaml",
+    "jacobson",
+    "use-case",
+    "ecb",
+    "essence",
+    "documentation"
+  ]
+}

package/README.md

@@ -5,7 +5,8 @@
 <h1 align="center">archik</h1>
 
 <p align="center">
-  <em>The shared vocabulary between you and Claude Code, at the engineering level.</em>
+  <em>Architecture-as-code your AI editor actually reads —<br/>
+  with use cases, sequence diagrams, and tests wired end-to-end.</em>
 </p>
 
 [![npm version](https://badge.fury.io/js/archik.svg)](https://www.npmjs.com/package/archik)
@@ -20,26 +21,30 @@
   <img src="https://cdn.jsdelivr.net/npm/archik/docs/hero.svg?v=2" alt="Sample Archik diagram of an LLM-assisted support system" width="780">
 </p>
 
-archik gives your project — and the AI editing it — *one file* that
-describes what the system actually looks like. Services, databases,
-queues, agents, LLMs, the edges between them. Plain YAML, schema-
-validated, no coordinates, no proprietary format.
+## The problems this fixes
 
-Open it in your browser for a live canvas. Render it in CI for a
-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:
 
-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
-question, and Claude is required to read it before doing structural
-work.
+- Asked an AI agent **"where would I add X?"** and watched it guess from filenames
+- Shipped a feature and realised **the architecture doc hasn't been right since 2023**
+- Tried to answer **"are we done?"** and gotten back vibes instead of evidence
+- Watched a diagram drift from the code because **someone dragged a box and forgot to write it down**
 
-## Quickstart
+…then you know the gap. archik closes it with one YAML file as the spec, a CLI that's the only way to edit it, and a validator that catches every drift before merge.
+
+## What you get
+
+| Layer                | File                                | What it captures                                                          |
+| -------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
+| **Structure**        | `.archik/main.archik.yaml`          | Services, databases, queues, agents, LLMs, the edges between them        |
+| **Actors**           | `*.archik.actors.yaml`              | Who initiates use cases (humans, external systems, schedulers)           |
+| **Requirements**     | `.archik/usecases/*.archik.uc.yaml` | What each actor wants — flows + slices that name **test paths**           |
+| **Behaviour**        | `*.archik.seq.yaml`                 | UML-subset sequence diagrams, ECB-checked when bound to a slice           |
+| **Progress**         | `*.archik.alphas.yaml`              | Essence/SEMAT alphas with **mechanically-verified** state transitions     |
+
+Every link between layers is a YAML cross-reference. The validator rejects breaks at every step — slice with missing test files, seq diagram without a `realizes` block, node whose `sourcePath` no longer resolves on disk, participant node missing a `seqFiles` backref. Orphans are caught at lint time, not in code review.
 
-Two terminal commands, then talk to Claude:
+## Quickstart
 
 ```bash
 npx archik@latest init       # scaffolds .archik/main.archik.yaml +
@@ -47,17 +52,16 @@ npx archik@latest init       # scaffolds .archik/main.archik.yaml +
 npx archik@latest start      # opens the live canvas at http://localhost:5173
 ```
 
-Then in Claude Code, type:
+Then in Claude Code:
 
 ```
-/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
+/archik:spawn                   # mirror your real source tree as the first diagram
+/archik:suggest <feature>       # propose changes for a specific feature
+/archik:usecase <name>          # author a use case with slices + tests
+/archik:trace                   # "am I done?" — the coverage matrix
 ```
 
-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`.
+`/archik:suggest` and `/archik:usecase` stage reviewable artifacts — diff overlay on the canvas, accept or reject. **Claude never edits YAML by hand**; the skill enforces CLI-only access.
 
 <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>
@@ -65,6 +69,23 @@ Done with the canvas? `npx archik stop`.
   </video>
 </p>
 
+## Two install paths, same outcome
+
+**npm** — the canonical install, includes the CLI and the canvas:
+
+```bash
+npx archik@latest init
+```
+
+**Claude Code plugin** — for the marketplace flow:
+
+```
+/plugin marketplace add bacharSalleh/archik
+/plugin install archik@archik
+```
+
+Either path lands the same skill + the same 11 slash commands. The plugin still uses the `archik` npm binary for the actual work, so you need Node available either way. See [Manual install](#manual-install) for adding the integration to projects that don't use `archik init`.
+
 ## What you write
 
 ```yaml
@@ -74,14 +95,19 @@ nodes:
   - id: api
     kind: service
     name: Support API
-    stack: Go + Postgres
+    sourcePath: src/api
+    description: REST API serving the customer support frontend.
+    stereotype: boundary
   - id: agent
     kind: agent
     name: Support Agent
-    description: Drafts replies, escalates risky ones.
+    sourcePath: src/agent
+    description: Drafts replies, escalates risky ones to a human.
+    stereotype: control
   - id: claude
     kind: llm
     name: Claude
+    description: LLM backend for draft generation.
 edges:
   - id: api-agent
     from: api
@@ -94,99 +120,91 @@ edges:
     label: draft reply
 ```
 
-No `x` / `y` / `width` — layout is computed by [ELK](https://eclipse.dev/elk/) on every render. The schema rejects coordinates so diffs stay meaningful.
+No `x`/`y`/`width` — layout is computed by [ELK](https://eclipse.dev/elk/) on every render. The schema rejects coordinates so diffs stay meaningful and diagrams stop drifting because someone moved a box.
 
-## What it gives you
+## The killer feature: the Jacobson chain
 
-- **Live canvas** — `archik dev` (foreground) or `archik start` / `stop` (detached, multi-project).
-- **27 node kinds** across compute, data, messaging, networking, hexagonal, AI/ML, identity, observability, cloud, UI, and external.
-- **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`, `drift` (source-tree gaps), `trace` (coverage matrix with `--fail-on partial|none`).
-- **AI skill + slash commands** — `archik init` installs both automatically. Eleven `/archik:*` commands cover the structural surface (`spawn`, `evolve`, `suggest`, `describe`, `dev`, `accept`, `reject`) plus the requirements layer (`actor`, `usecase`, `trace`, `alpha`).
+The diagram is the start. The thing that actually answers *"are we done?"* is the chain that runs from a stakeholder request all the way down to a passing test:
 
-## Beyond the diagram — use cases, traceability, alphas
+```
+Actor → Use case → Slice → Tests on disk → Seq diagram → Participant nodes → sourcePath on disk
+```
 
-The structural diagram is the start. Above it sits a thin requirements
-layer that closes the Jacobson chain — *who acts → what they want →
-how the system behaves at runtime → which structural nodes participate
-→ which tests prove it*. Every link is a YAML cross-reference and the
-validator rejects breaks at every step.
+Every arrow is a YAML cross-reference. `npx archik trace` walks the chain and prints a coverage matrix:
 
-| Artifact                       | File                                | What it captures                                              |
-| ------------------------------ | ----------------------------------- | ------------------------------------------------------------- |
-| **Actors**                     | `*.archik.actors.yaml`              | Who initiates use cases — humans, external systems, schedulers |
-| **Use cases + slices**         | `.archik/usecases/*.archik.uc.yaml` | What each actor wants, with slim slices that name test paths   |
-| **Sequence diagrams**          | `*.archik.seq.yaml`                 | How a slice plays out at runtime (ECB-checked when bound to a slice via `realizes`) |
-| **Alphas (Essence / SEMAT)**   | `*.archik.alphas.yaml`              | Project-wide progress dials with mechanically-verified states  |
+```
+$ npx archik trace
 
-`npx archik trace` prints the coverage matrix (use case × slice × test
-× seq × ECB) so "are we done?" stops being an opinion. The dev canvas
-surfaces the same information visually: the **Use cases** toolbar
-button shows live trace status (`✓ all traced` / `◐ N to finish` /
-`○ N untraced`), and `/__archik/usecases` is a dedicated page with
-master/detail rail, slice cards with clickable test paths, and direct
-links to each realising sequence diagram.
+    USE CASE / SLICE                   TST  RZ ECB   FILE
+~ drift/clean                        1t   —  —     .archik/usecases/drift.archik.uc.yaml
+~ drift/missing-source               1t   —  —     .archik/usecases/drift.archik.uc.yaml
+~ render/arch-svg                    1t   —  —     .archik/usecases/render.archik.uc.yaml
+~ suggest-accept/happy               1t   ✓  2/4   .archik/usecases/suggest-accept.archik.uc.yaml
+~ suggest-accept/rejected            1t   —  —     .archik/usecases/suggest-accept.archik.uc.yaml
+~ validate/clean                     1t   —  —     .archik/usecases/validate.archik.uc.yaml
 
-The `validate` command enforces the integrity triangle: if a slice
-points at a seq file, the seq must point back; if a seq diagram
-realises a slice, every participant node must list that seq in its
-`seqFiles` array. Orphans get caught at lint time, not in code review.
+totals: 9 slices across 4 use cases — 0 full, 9 partial, 0 untraced
+```
 
-## For Claude Code & other LLMs
+Same data lives on screen — the **Use cases** toolbar button shows live status (`✓ all traced` / `◐ N to finish` / `○ N untraced`), and `/__archik/usecases` is a dedicated page with master/detail rail, slice cards with test paths, and direct links to each realising sequence diagram.
 
-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.
+In CI:
 
-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.
+```bash
+npx archik trace --fail-on partial    # exit 1 if anything's not fully traced
+```
 
-### The slash commands
+## In your workflow
 
-**Structural diagram (the original surface):**
+**Adding a feature.** Type `/archik:suggest add Stripe webhook handler`. Claude grounds in the current diagram, asks 1–3 clarifying questions, and stages a sidecar with the proposed shape. You review the green/red diff overlay on the canvas. Accept and the YAML is updated atomically; the next step is the build plan.
 
-| 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                              |
+**Tracking the work.** `/archik:usecase <name>` writes a `*.archik.uc.yaml` with flows, slices, and test paths. Each active slice's test files must exist on disk — the validator rejects empty promises. As code lands, slices flip from "tests-only" to "fully traced" once their realisation seq exists.
 
-**Requirements + traceability (the Jacobson layer — see below):**
+**Closing the milestone.** `/archik:trace` surfaces what's left. `/archik:alpha promote requirements addressed` runs the criteria check before advancing — over-claiming is a hard error. `npx archik drift` catches sourcePath gaps from the source tree side.
 
-| Command                              | What it does                                                                |
-| ------------------------------------ | --------------------------------------------------------------------------- |
-| `/archik:actor <id>`                 | Add or update an actor in the actor index                                   |
-| `/archik:usecase <name>`             | Author a use case (actors + flows + slices + tests)                         |
-| `/archik:trace`                      | Show the use case × slice × test × seq × ECB coverage matrix                |
-| `/archik:alpha [show \| promote …]`  | Read the project's alpha state, or promote one with a criteria check        |
+## How it differs
 
-A typical first-day flow:
+|                       | archik                | Mermaid / PlantUML | Structurizr      | ADRs               |
+| --------------------- | --------------------- | ------------------ | ---------------- | ------------------ |
+| Diagram source format | Plain YAML            | Custom DSL         | Structurizr DSL  | Markdown prose     |
+| Layout                | Auto (ELK), no coords | Auto               | Auto             | N/A                |
+| Live canvas           | Yes (browser)         | Some renderers     | Yes              | No                 |
+| Headless render to CI | Yes (SVG)             | Yes                | Yes              | No                 |
+| AI-editor integration | **First-class**       | None               | None             | None               |
+| Use cases / slices    | **Yes**               | No                 | No               | Sometimes informal |
+| Sequence diagrams     | **Yes (UML subset)**  | Yes                | No               | No                 |
+| Test ↔ requirement traceability | **Mechanical**  | No                 | No               | No                 |
+| Drift detection       | **Yes (`drift`)**     | No                 | No               | No                 |
+| Validator             | **Schema + cross-file + ECB rules** | Syntax only | Syntax only | None             |
 
-```
-/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
-```
+If all you need is a one-off rendered diagram, Mermaid is faster. If you need the diagram to **stay accurate across an LLM-assisted refactor** and **prove the system does what the requirements say**, that's archik.
 
-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.
+## All slash commands
 
-### Manual install (existing projects without `archik init`)
+**Structural diagram** (the original surface):
 
-If you already have an archik file and just want to add the Claude integration:
+| 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                         |
 
-```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)
-```
+**Requirements + traceability** (the Jacobson layer):
 
-Drop the `--user` flag to scope to the current project only.
+| Command                              | What it does                                                |
+| ------------------------------------ | ----------------------------------------------------------- |
+| `/archik:actor <id>`                 | Add or update an actor in the actor index                   |
+| `/archik:usecase <name>`             | Author a use case (actors + flows + slices + tests)         |
+| `/archik:trace`                      | Show the coverage matrix + the next concrete action         |
+| `/archik:alpha [show \| promote …]`  | Read or move project alphas with a machine-checked criteria |
 
-## Commands
+The skill enforces a hard rule: **Claude talks to archik only through `npx archik`** — never `Read`, `Write`, or `Edit` on a YAML file directly. Queries 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.
+
+## CLI reference
 
 ```
 archik init [path]       Scaffold a starter .archik/main.archik.yaml
@@ -207,12 +225,16 @@ archik validate [path]   Validate against the schema (CI-friendly, exit code 1 o
 archik render [path]     Render to a self-contained SVG file
                          --out <file>     output path (default: diagram.svg)
                          --theme <name>   "dark" (default) or "light"
+                         --seq <path>     render a sequence diagram instead of the structural one
 archik watch [path]      Re-render to SVG on every file change (Ctrl+C to stop)
 
 archik trace [path]      Use case × slice × test × seq × ECB coverage matrix
                          --json              structured rows + summary
                          --fail-on <level>   exit 1 on partial | none (CI gate)
                          --use-case <id>     filter to one use case
+                         --actor <id>        filter to use cases involving an actor
+                         --status <s>        filter slices by status (active|proposed|deprecated)
+                         --coverage <l>      filter rows by level (full|partial|none)
 archik drift [path]      Surface gaps where a node's sourcePath or a slice's
                          tests path no longer resolves on disk
 
@@ -222,12 +244,6 @@ archik alpha [sub]       Project-wide alpha state (Essence / SEMAT)
                                            --note '<text>' captures the rationale
                          demote <a> <s>    walk back to an earlier state on the ladder
 
-archik upgrade           Pull the latest archik via the project's package manager
-                         (auto-detects npm / pnpm / yarn / bun from the lockfile)
-                         then refreshes SKILL.md + slash commands from the new binary
-                         --skip-install    just refresh artifacts; don't reinstall
-                         --user            install to ~/.claude (global skill)
-
 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
@@ -238,49 +254,98 @@ archik suggest [sub]     Manage Claude's pending architecture suggestion
                          accept           apply the sidecar over the main file
                          reject           discard the sidecar
 
+archik q [sub]           Query the diagram (--json supported on every subcommand)
+                         describe <id>    one node, full detail
+                         deps <id>        what does this node depend on?
+                         dependents <id>  what depends on this node?
+                         impact <id>      who breaks if this is removed?
+                         list             all nodes (with --kind / --parent / --status / --search filters)
+                         edges            all edges (with --from / --to / --rel filters)
+                         stats            node + edge counts by kind/relationship
+                         usecases         use case index (--actor filters)
+                         describe-usecase <id>   one use case, full detail
+                         actors           actor index
+                         sequences        sequence diagram index (--node filters)
+
+archik upgrade           Pull the latest archik via the project's package manager
+                         (auto-detects npm / pnpm / yarn / bun from the lockfile)
+                         then refreshes SKILL.md + slash commands from the new binary
+                         --skip-install    just refresh artifacts; don't reinstall
+
 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
+archik schema [variant]  Print the document schema as a reference (--json supported)
+                         (no arg)         architecture document
+                         seq              sequence diagram
+                         uc               use case
+                         actors           actors file
 ```
 
 Without a `[path]` argument, archik resolves the file in this order:
 
-1. `.archik/main.archik.yaml` (preferred new convention — keeps the project root tidy)
+1. `.archik/main.archik.yaml` (preferred — keeps the project root tidy)
 2. `architecture.archik.yaml` (legacy root location — still fully supported)
 
-If both exist the command errors out and asks you to pick one. New projects get the `.archik/` layout from `archik init`; existing projects keep working without any migration.
+If both exist the command errors out and asks you to pick one.
 
-Single instance per file is enforced via a lock file in `$TMPDIR/archik-cli/`, so parallel `dev` and `start` against the same YAML are rejected with a friendly error.
+## Manual install
 
-## Use it in CI
+If you already have an archik file and just want to add the Claude integration to it:
+
+**Via the npm CLI:**
 
 ```bash
-# Fail the build on schema errors
-archik validate
+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.
 
-# Generate a committable SVG of your architecture for the docs site
-archik render --theme light --out docs/architecture.svg
+**Via Claude Code's plugin marketplace:**
+
+```
+/plugin marketplace add bacharSalleh/archik
+/plugin install archik@archik
 ```
 
-## Schema
+Either path leaves the same skill + the same 11 slash commands in the same target directories.
+
+## When to use it (and when not to)
 
-The full schema reference (every node kind, every relationship, common patterns, hard rules) lives in the AI skill. After installing it locally:
+**Use archik when**
+
+- Your project has more than ~5 components and you want the diagram to stay accurate
+- You're using Claude Code (or any AI agent) to author code, and you want the agent to reason about structure instead of guess from filenames
+- You're shipping in milestones and want "are we done?" to be mechanically answerable
+- You have CI and want a gate that fails on architectural drift
+
+**Skip it when**
+
+- It's a one-file script or a throwaway prototype
+- The architecture diagram is for a slide deck (use Mermaid)
+- You don't have a build step or CI
+
+The full schema reference (every node kind, every relationship, common patterns, hard rules) lives in [`skills/archik/SKILL.md`](skills/archik/SKILL.md) — installed automatically by `archik init` so Claude reads it before doing structural work.
+
+## Use it in CI
 
 ```bash
-archik skill --user
-$EDITOR ~/.claude/skills/archik/SKILL.md
+archik validate                                # schema + cross-file integrity
+archik drift                                   # source-tree gaps
+archik trace --fail-on partial                 # block merge on incomplete traceability
+archik render --theme light --out docs/architecture.svg    # commit a static SVG
 ```
 
-Or read it directly in this repo: [`.claude/skills/archik/SKILL.md`](.claude/skills/archik/SKILL.md).
-
 ## Design notes
 
-- The YAML is the only persistent truth. The canvas is a stateless projection that reloads on every file change (live-reload via SSE).
-- Layout is non-negotiable: ELK lays out every render. Putting an `x` / `y` / `width` field at any level fails schema validation. No more "the diagram drifted because someone dragged a box."
-- The published npm package ships only the bundled binary — no source files, no build tooling. Zero runtime dependencies.
+- **The YAML is the only persistent truth.** The canvas is a stateless projection that reloads on every file change (live-reload via SSE).
+- **Layout is non-negotiable.** ELK lays out every render. Putting an `x`/`y`/`width` field at any level fails schema validation. No more "the diagram drifted because someone dragged a box."
+- **Single instance per file** is enforced via a lock file in `$TMPDIR/archik-cli/`, so parallel `dev`/`start` against the same YAML are rejected with a friendly error.
+- **The published npm package** ships only the bundled binary, the canvas assets, the skill, and the 11 slash commands. Zero runtime dependencies.
 
 ## License
 

package/dist/cli/archik.mjs

@@ -371,7 +371,7 @@ Consider installing the package or pass your own 'workerFactory' to ELK's constr
 React keys must be passed directly to JSX without using spread:
   let props = %s;
   <%s key={someKey} {...props} />`,Yo,Wr,Oa,Wr),_a[Wr+Yo]=!0)}if(Wr=null,yi!==void 0&&(d(yi),Wr=""+yi),v(Zn)&&(d(Zn.key),Wr=""+Zn.key),"key"in Zn){yi={};for(var Wl in Zn)Wl!=="key"&&(yi[Wl]=Zn[Wl])}else yi=Zn;return Wr&&k(yi,typeof nn=="function"?nn.displayName||nn.name||"Unknown":nn),P(nn,Wr,yi,f(),Hs,Lo)}function B(nn){G(nn)?nn._store&&(nn._store.validated=1):typeof nn=="object"&&nn!==null&&nn.$$typeof===jn&&(nn._payload.status==="fulfilled"?G(nn._payload.value)&&nn._payload.value._store&&(nn._payload.value._store.validated=1):nn._store&&(nn._store.validated=1))}function G(nn){return typeof nn=="object"&&nn!==null&&nn.$$typeof===de}var K=y3(),de=Symbol.for("react.transitional.element"),ce=Symbol.for("react.portal"),we=Symbol.for("react.fragment"),De=Symbol.for("react.strict_mode"),at=Symbol.for("react.profiler"),kt=Symbol.for("react.consumer"),_e=Symbol.for("react.context"),ht=Symbol.for("react.forward_ref"),Te=Symbol.for("react.suspense"),Wt=Symbol.for("react.suspense_list"),tn=Symbol.for("react.memo"),jn=Symbol.for("react.lazy"),rr=Symbol.for("react.activity"),_r=Symbol.for("react.client.reference"),fn=K.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,ii=Object.prototype.hasOwnProperty,Si=Array.isArray,No=console.createTask?console.createTask:function(){return null};K={react_stack_bottom_frame:function(nn){return nn()}};var bs,Ki={},se=K.react_stack_bottom_frame.bind(K,b)(),Bs=No(g(b)),_a={};DDe.Fragment=we,DDe.jsx=function(nn,Zn,yi){var Yo=1e4>fn.recentlyCreatedOwnerStacks++;return j(nn,Zn,yi,!1,Yo?Error("react-stack-top-frame"):se,Yo?No(g(nn)):Bs)},DDe.jsxs=function(nn,Zn,yi){var Yo=1e4>fn.recentlyCreatedOwnerStacks++;return j(nn,Zn,yi,!0,Yo?Error("react-stack-top-frame"):se,Yo?No(g(nn)):Bs)}})()});var sc=mr((uri,Dft)=>{"use strict";process.env.NODE_ENV==="production"?Dft.exports=tan():Dft.exports=nan()});import{readFileSync as s8r}from"node:fs";import u8r from"node:path";import{access as RRn,mkdir as DRn,readFile as ORn,writeFile as EKt}from"node:fs/promises";import pct from"node:path";var kRn=process.env.FORCE_COLOR==="0"?!1:process.env.FORCE_COLOR!==void 0?!0:process.env.NO_COLOR!==void 0?!1:!!process.stdout.isTTY,Hx=(o,c)=>d=>kRn?`\x1B[${o}m${d}\x1B[${c}m`:d,Mr=Hx("1","22"),tr=Hx("2","22"),MRn=Hx("31","39"),act=Hx("32","39"),Uf=Hx("33","39"),eKr=Hx("34","39"),mKt=Hx("35","39"),ys=Hx("36","39"),V1=Hx("90","39"),Hl=()=>Mr(act("\u2713")),Yr=()=>Mr(MRn("\u2717")),k9=()=>ys("\u25B8");function vKt(o){let c={_:[]};for(let d=0;d<o.length;d++){let g=o[d];if(g.startsWith("--")){let f=g.indexOf("=");if(f!==-1)c[g.slice(2,f)]=g.slice(f+1);else{let b=o[d+1];b===void 0||b.startsWith("--")?c[g.slice(2)]="true":(c[g.slice(2)]=b,d++)}}else c._.push(g)}return c}function Zr(o,c){let d=o[c];return Array.isArray(d)?d[0]:d}import{existsSync as SRn,mkdirSync as _Rn}from"node:fs";import{readFile as CRn,rename as IRn,unlink as LRn,writeFile as ERn}from"node:fs/promises";import MKt from"node:path";import{access as xRn}from"node:fs/promises";import $x from"node:path";var sct=".archik/main.archik.yaml",uct="architecture.archik.yaml";async function lct(o){try{return await xRn(o),!0}catch{return!1}}async function Lu(o,c=process.cwd()){if(o!==void 0&&o!=="")return $x.resolve(c,o);let d=$x.resolve(c,uct),g=$x.resolve(c,sct),[f,b]=await Promise.all([lct(d),lct(g)]);if(f&&b)throw new Error(`Found both ${uct} and ${sct}. Pick one \u2014 keep the file under .archik/ (preferred) and delete the root copy, or vice versa.`);return f?d:g}async function kKt(o,c=process.cwd()){if(o!==void 0&&o!=="")return $x.resolve(c,o);let d=$x.resolve(c,uct);return await lct(d)?d:$x.resolve(c,sct)}function W1(o){let c=$x.dirname(o);return $x.basename(c)===".archik"?$x.dirname(c):c}var hct="runtime.json";function zU(o){return MKt.join(W1(o),".archik",hct)}async function kfe(o,c){let d=zU(o),g=MKt.dirname(d);SRn(g)||_Rn(g,{recursive:!0});let f=`${d}.tmp`;await ERn(f,JSON.stringify(c,null,2)+`
-`,"utf-8"),await IRn(f,d)}async function xKt(o){let c=zU(o);try{let d=await CRn(c,"utf-8"),g=JSON.parse(d);return typeof g.pid!="number"||typeof g.port!="number"||typeof g.host!="string"||typeof g.url!="string"||typeof g.startedAt!="string"?null:g}catch{return null}}function SKt(o){let c=o.urls?.local?.[0];if(c===void 0)return null;let d;try{d=new URL(c)}catch{return null}if(d.port==="")return null;let g=Number.parseInt(d.port,10);return Number.isFinite(g)?{pid:o.pid,port:g,host:d.hostname,url:c,startedAt:o.startedAt}:null}async function GI(o){let c=zU(o);try{await LRn(c)}catch{}}import{copyFile as _Kt,mkdir as CKt,readdir as NRn,stat as dct}from"node:fs/promises";import h3 from"node:path";import IKt from"node:os";import{existsSync as TRn,realpathSync as ARn}from"node:fs";import Mfe from"node:path";import{fileURLToPath as PRn}from"node:url";function U5(){let o=process.env.ARCHIK_PKG_ROOT;if(o)return Mfe.resolve(o);let c=Mfe.dirname(ARn(PRn(import.meta.url))),d=c;for(let g=0;g<10;g++){if(TRn(Mfe.join(d,"package.json")))return d;let f=Mfe.dirname(d);if(f===d)break;d=f}throw new Error(`archik: could not locate package root (start: ${c})`)}async function fct(o){let c=h3.join(U5(),".claude","skills","archik","SKILL.md");try{await dct(c)}catch{return{ok:!1,reason:"missing-source",source:c}}let d=o.scope==="user"?h3.join(IKt.homedir(),".claude","skills"):h3.resolve(".claude","skills"),g=h3.join(d,"archik"),f=h3.join(g,"SKILL.md");if(!o.force)try{return await dct(f),{ok:!1,reason:"exists",target:f}}catch{}return await CKt(g,{recursive:!0}),await _Kt(c,f),{ok:!0,target:f,scope:o.scope}}async function xfe(o){let c=h3.join(U5(),".claude","commands","archik"),d;try{d=(await NRn(c)).filter(v=>v.endsWith(".md"))}catch{return{ok:!1,reason:"missing-source",source:c}}if(d.length===0)return{ok:!1,reason:"missing-source",source:c};let g=o.scope==="user"?h3.join(IKt.homedir(),".claude","commands"):h3.resolve(".claude","commands"),f=h3.join(g,"archik");if(!o.force){let v=[];for(let k of d)try{await dct(h3.join(f,k)),v.push(k)}catch{}if(v.length>0)return{ok:!1,reason:"exists",existing:v,targetDir:f}}await CKt(f,{recursive:!0});let b=[];for(let v of d)await _Kt(h3.join(c,v),h3.join(f,v)),b.push(v);return{ok:!0,targetDir:f,copied:b,scope:o.scope}}async function LKt(o){let c=Zr(o,"user")==="true"?"user":"project",d=Zr(o,"force")==="true",g=await fct({scope:c,force:d});if(!g.ok)return g.reason==="missing-source"?console.error(`\u2717 Source skill not found at ${g.source}`):console.error(`\u2717 ${g.target} already exists. Pass --force to overwrite.`),1;let f=g.scope==="user"?"user-wide":"this project";return console.log(`\u2713 Installed archik skill (${f}) \u2192 ${g.target}`),0}var FRn=`version: "1.0"
+`,"utf-8"),await IRn(f,d)}async function xKt(o){let c=zU(o);try{let d=await CRn(c,"utf-8"),g=JSON.parse(d);return typeof g.pid!="number"||typeof g.port!="number"||typeof g.host!="string"||typeof g.url!="string"||typeof g.startedAt!="string"?null:g}catch{return null}}function SKt(o){let c=o.urls?.local?.[0];if(c===void 0)return null;let d;try{d=new URL(c)}catch{return null}if(d.port==="")return null;let g=Number.parseInt(d.port,10);return Number.isFinite(g)?{pid:o.pid,port:g,host:d.hostname,url:c,startedAt:o.startedAt}:null}async function GI(o){let c=zU(o);try{await LRn(c)}catch{}}import{copyFile as _Kt,mkdir as CKt,readdir as NRn,stat as dct}from"node:fs/promises";import h3 from"node:path";import IKt from"node:os";import{existsSync as TRn,realpathSync as ARn}from"node:fs";import Mfe from"node:path";import{fileURLToPath as PRn}from"node:url";function U5(){let o=process.env.ARCHIK_PKG_ROOT;if(o)return Mfe.resolve(o);let c=Mfe.dirname(ARn(PRn(import.meta.url))),d=c;for(let g=0;g<10;g++){if(TRn(Mfe.join(d,"package.json")))return d;let f=Mfe.dirname(d);if(f===d)break;d=f}throw new Error(`archik: could not locate package root (start: ${c})`)}async function fct(o){let c=h3.join(U5(),"skills","archik","SKILL.md");try{await dct(c)}catch{return{ok:!1,reason:"missing-source",source:c}}let d=o.scope==="user"?h3.join(IKt.homedir(),".claude","skills"):h3.resolve(".claude","skills"),g=h3.join(d,"archik"),f=h3.join(g,"SKILL.md");if(!o.force)try{return await dct(f),{ok:!1,reason:"exists",target:f}}catch{}return await CKt(g,{recursive:!0}),await _Kt(c,f),{ok:!0,target:f,scope:o.scope}}async function xfe(o){let c=h3.join(U5(),"commands"),d;try{d=(await NRn(c)).filter(v=>v.endsWith(".md"))}catch{return{ok:!1,reason:"missing-source",source:c}}if(d.length===0)return{ok:!1,reason:"missing-source",source:c};let g=o.scope==="user"?h3.join(IKt.homedir(),".claude","commands"):h3.resolve(".claude","commands"),f=h3.join(g,"archik");if(!o.force){let v=[];for(let k of d)try{await dct(h3.join(f,k)),v.push(k)}catch{}if(v.length>0)return{ok:!1,reason:"exists",existing:v,targetDir:f}}await CKt(f,{recursive:!0});let b=[];for(let v of d)await _Kt(h3.join(c,v),h3.join(f,v)),b.push(v);return{ok:!0,targetDir:f,copied:b,scope:o.scope}}async function LKt(o){let c=Zr(o,"user")==="true"?"user":"project",d=Zr(o,"force")==="true",g=await fct({scope:c,force:d});if(!g.ok)return g.reason==="missing-source"?console.error(`\u2717 Source skill not found at ${g.source}`):console.error(`\u2717 ${g.target} already exists. Pass --force to overwrite.`),1;let f=g.scope==="user"?"user-wide":"this project";return console.log(`\u2713 Installed archik skill (${f}) \u2192 ${g.target}`),0}var FRn=`version: "1.0"
 name: My Architecture
 description: Initial scaffold \u2014 edit this file to grow your diagram.
 nodes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archik",
-  "version": "0.12.37",
+  "version": "0.12.39",
   "description": "The shared vocabulary between you and Claude Code, at the engineering level. Plain-YAML architecture diagrams with a live browser canvas, headless SVG render in CI, and an installable Claude skill so the model treats the diagram as the spec.",
   "keywords": [
     "architecture",
@@ -33,8 +33,9 @@
     "docs/hero.svg",
     "docs/logo.svg",
     "docs/wordmark.svg",
-    ".claude/skills/archik",
-    ".claude/commands/archik",
+    "skills",
+    "commands",
+    ".claude-plugin",
     "README.md",
     "LICENSE"
   ],