archik 0.4.2 → 0.6.0

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

@@ -1,30 +1,41 @@
 ---
 name: archik
-description: Use whenever 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 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.
 ---
 
 # Archik — the project's shared map
 
-`architecture.archik.yaml` at the project root is **the user's source of
-truth for what the system looks like**. It lists every meaningful node
-(services, databases, queues, frontends, external APIs, …) and the
-edges between them. The canvas in the browser is a stateless projection
-of this file — when the user says "the orders service" or "the events
-queue", they mean the entity with that `id` in the YAML.
+The archik file is **the user's source of truth for what the system
+looks like**. It lists every meaningful node (services, databases,
+queues, frontends, external APIs, …) and the edges between them.
+The canvas in the browser is a stateless projection of this file —
+when the user says "the orders service" or "the events queue", they
+mean the entity with that `id` in the YAML.
 
-Treat this file as a shared vocabulary. It exists so the user and you
-can talk about the system without re-explaining it every time.
+The file lives in one of two places, in this order of preference:
+
+1. `.archik/main.archik.yaml` — the new convention. Keeps the
+   project root tidy and leaves room for sub-architectures (other
+   `.archik/*.archik.yaml` files for individual components).
+2. `architecture.archik.yaml` — the legacy root location, still
+   fully supported.
+
+Run `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.
 
 ## Protocol
 
 1. **Before** answering structural questions — *"what does X do?",
    "what depends on Y?", "where does data flow when …?"* — read
-   `architecture.archik.yaml`. Don't guess from filenames or memory.
+   the archik file. Don't guess from filenames or memory.
 2. **When** work introduces, removes, or rewires components, write
-   the proposed end-state to `architecture.archik.suggested.yaml`
-   (same schema, plus a `metadata.suggestion` block — see "Suggesting
-   changes" below). Don't edit `architecture.archik.yaml` directly;
-   the user reviews and accepts in the canvas or via
+   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`. Fix any
    reported errors before declaring the change done.
@@ -35,13 +46,19 @@ relationship vocabulary, and CLI.
 
 ## Suggesting changes (the sidecar workflow)
 
-The `archik.yaml` is the user's source of truth. You don't get to
+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:
+sidecar file in the same directory, with the same stem plus
+`.suggested`:
 
 ```
-architecture.archik.yaml             ← truth — user owns it
-architecture.archik.suggested.yaml   ← your draft proposal
+# new convention
+.archik/main.archik.yaml             ← truth — user owns it
+.archik/main.archik.suggested.yaml   ← your draft proposal
+
+# legacy layout — same naming rule, just at the root
+architecture.archik.yaml
+architecture.archik.suggested.yaml
 ```
 
 The sidecar is a complete, valid Archik document — same schema as the
@@ -53,7 +70,7 @@ version: "1.0"
 name: My Architecture
 metadata:
   suggestion:
-    from: architecture.archik.yaml
+    from: .archik/main.archik.yaml
     at: 2026-04-26T17:00:00Z
     note: add Stripe payment flow         # optional one-liner
 nodes:
@@ -112,7 +129,7 @@ this file) when the work you're doing changes the structure:
 
 Frame it as: *"This adds a `payments-worker` that reads from the
 `order-events` queue and writes to `payments-db`. Want me to update
-`architecture.archik.yaml` to capture that?"*
+the archik file to capture that?"*
 
 ## When to defer
 
@@ -181,18 +198,71 @@ metadata:               # optional
   notes:                # optional, list of free-text notes
     - "Migrated from monolith in 2024."
   parentId: platform    # optional, must reference a real node
+  archikFile: .archik/orders.archik.yaml   # optional drill-down
   metadata:             # optional, free record
     team: fulfillment
 ```
 
-## Node kinds (26 total, grouped by purpose)
+### Cross-file edges (`fromFile` / `toFile`)
+
+Edges can also point at a node that lives in a peer file. Set
+`toFile` (or `fromFile`) to that file's relative path; the canvas
+won't draw the edge itself but will hang an "↗" badge on the local
+endpoint, with the target file in the tooltip. Click → navigate.
+
+```yaml
+edges:
+  - id: api-pays
+    from: api                              # local node
+    to: charge-handler
+    toFile: .archik/payments.archik.yaml   # peer file
+    relationship: http_call
+    label: charge
+```
+
+Constraints (the schema enforces them):
+
+- The cross-file path follows the same rules as `archikFile` (relative,
+  forward slashes, no `..`, ends in `.archik.yaml`).
+- The *local* endpoint id must still match a node in this file.
+- An edge with **both** `fromFile` and `toFile` is rejected — author
+  it inside one of the two referenced files instead.
+
+### Drilling into a sub-architecture (`archikFile`)
+
+A node can point at *its own* archik file via `archikFile`. The
+canvas shows a small "↓ open" badge on those nodes; clicking it
+loads the linked file and adds a breadcrumb so the user can come
+back. Use it when a component is meaty enough to deserve its own
+diagram (a service with internal modules, a frontend with several
+panes, etc.).
+
+Constraints (the schema enforces them):
+- Relative path only — no leading `/`, no Windows drive letter.
+- Must use forward slashes; `..` segments are rejected.
+- Must end in `.archik.yaml` (the suggestion sidecar is derived
+  automatically as `<stem>.suggested.yaml` next to it).
+- Cycles aren't checked at parse time (each file validates on its
+  own); if you wire a loop the canvas just lets the user navigate
+  in and out.
+
+Conventional layout: keep sub-files under `.archik/` next to
+`main.archik.yaml`. Example:
+
+```
+.archik/main.archik.yaml          # entry point
+.archik/orders.archik.yaml        # Orders service internals
+.archik/payments.archik.yaml      # Payments service internals
+```
+
+## Node kinds (27 total, grouped by purpose)
 
 | Group       | Kinds |
 | ----------- | --------------------------------- |
 | Compute     | `service`, `function`, `worker`, `agent` |
 | Data        | `database`, `cache`, `vectordb`, `storage` |
 | Messaging   | `queue`, `topic`, `stream` |
-| Networking  | `gateway`, `cdn` |
+| Networking  | `gateway`, `cdn`, `route` |
 | Hexagonal   | `interface`, `adapter`, `port` |
 | AI / ML     | `llm`, `prompt`, `tool` |
 | Identity    | `auth` |
@@ -217,6 +287,7 @@ Picking the right kind:
 - Kafka / Kinesis stream-of-events → `stream`
 - API gateway, ingress, edge proxy → `gateway`
 - CloudFront / Fastly → `cdn`
+- A specific HTTP route / URL endpoint (e.g. `POST /v1/orders`) → `route`
 - An abstract contract → `interface`
 - A concrete impl of an interface → `adapter`
 - A hexagonal-architecture port → `port`
@@ -463,8 +534,10 @@ edges:
 ## CLI
 
 These commands are available globally if archik was installed via
-`npm link`. Each defaults to `architecture.archik.yaml` in the current
-directory unless given a positional path.
+`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.
 
 ```
 archik validate                    # schema check (run after every edit)
@@ -492,7 +565,7 @@ archik checkout.
 
 ## Verification workflow
 
-After **every** edit you make to `architecture.archik.yaml`:
+After **every** edit you make to the archik file:
 
 1. Run `archik validate` — fix any reported errors before declaring
    the change done. Schema errors include the path of the offending

package/README.md

@@ -11,7 +11,7 @@ You write a small YAML file describing your nodes (services, databases, queues,
 ## Quickstart
 
 ```bash
-npx archik init       # scaffold architecture.archik.yaml in cwd
+npx archik init       # scaffold .archik/main.archik.yaml in cwd
 npx archik start      # canvas at http://localhost:5173 (background)
 npx archik stop       # done
 ```
@@ -52,7 +52,7 @@ No `x` / `y` / `width` — layout is computed by [ELK](https://eclipse.dev/elk/)
 ## What it gives you
 
 - **Live canvas** — `archik dev` (foreground) or `archik start` / `stop` (detached, multi-project).
-- **26 node kinds** across compute, data, messaging, hexagonal, AI/ML, identity, observability, cloud, UI, and external.
+- **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`, `check` (drift between YAML and source dirs).
@@ -77,7 +77,7 @@ So conversations like *"add a payments worker that subscribes to the orders queu
 ## Commands
 
 ```
-archik init [path]       Scaffold a starter architecture.archik.yaml
+archik init [path]       Scaffold a starter .archik/main.archik.yaml
                          (also installs the Claude skill by default)
                          --no-skill       skip installing the Claude skill
 
@@ -102,7 +102,14 @@ archik skill             Install the Claude skill for AI editing
                          --force          overwrite an existing skill
 ```
 
-Default path is `architecture.archik.yaml` in the current directory. 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.
+Without a `[path]` argument, archik resolves the file in this order:
+
+1. `.archik/main.archik.yaml` (preferred new convention — 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.
+
+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.
 
 ## Use it in CI