archik 0.5.0 → 0.6.1

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.
@@ -33,15 +44,56 @@ The sections below are the detailed reference behind these three
 rules — *when* to consult, *when* to propose, schema, taxonomy,
 relationship vocabulary, and CLI.
 
+## Grounding (do this once per session, before structural work)
+
+The archik file tells you *what* exists. The source tree tells you
+*where* it lives. The mapping between the two is the whole reason
+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.
+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.
+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` /
+   `description` field hints at the location. Note the mismatches
+   — those are the places where moving a folder will outgrow the
+   diagram, and where new code is most likely to need a YAML
+   update too.
+4. **Run `archik check`** if it's available — it walks `src/`,
+   `services/`, `packages/`, and `apps/` and flags nodes that
+   don't have a matching folder (and folders that look like
+   services but aren't in the diagram). Cheap drift detector;
+   worth running before any non-trivial edit.
+
+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.
+
 ## 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 +105,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:
@@ -65,9 +117,14 @@ edges:
 Once you've written the sidecar:
 
 * The canvas shows a **📝 Suggestion pending** banner with `Review`,
-  `Accept`, `Reject` buttons. Review opens a colour-coded SVG diff in
-  a new tab; Accept renames the sidecar over the main file; Reject
-  deletes the sidecar.
+  `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`.
 
 If the user has no canvas open and asks "apply it", run
@@ -112,7 +169,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,10 +238,63 @@ 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
 ```
 
+### 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 |
@@ -464,8 +574,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)
@@ -483,7 +595,7 @@ archik dev                         # open the live editor in the browser (foregr
 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
+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
 ```
 
@@ -493,7 +605,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
 ```
@@ -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
 

package/bin/postinstall.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Friendly post-install banner. npm 10+ stopped echoing the package
+ * version ("added 1 package in 3s" is all the user sees), so this
+ * gives them a confirmation, the version they got, and where to go
+ * next. Stays quiet under CI / non-TTY / inside a parent npm install
+ * so it doesn't pollute logs.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Skip when noise would hurt more than help.
+if (
+  process.env["CI"] !== undefined ||
+  process.env["ARCHIK_NO_BANNER"] !== undefined ||
+  !process.stdout.isTTY ||
+  // Inside `npm install` / yarn / pnpm of a host project — only
+  // show the banner for global installs and direct local installs.
+  process.env["npm_config_global"] !== "true" &&
+    process.env["npm_command"] === "install" &&
+    process.env["npm_config_save"] !== undefined
+) {
+  process.exit(0);
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(resolve(here, "..", "package.json"), "utf8"),
+);
+
+const enabled = process.env["NO_COLOR"] === undefined;
+const c = (open, close) => (s) =>
+  enabled ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+const bold = c("1", "22");
+const dim = c("2", "22");
+const cyan = c("36", "39");
+const green = c("32", "39");
+const magenta = c("35", "39");
+
+const line = dim("─".repeat(56));
+const tick = bold(green("✓"));
+const arrow = cyan("▸");
+
+process.stdout.write(
+  [
+    "",
+    line,
+    `  ${tick} ${bold(magenta("archik"))} ${dim("v" + pkg.version)} ${dim("installed")}`,
+    line,
+    `  ${arrow} ${bold("archik init")}   ${dim("scaffold .archik/main.archik.yaml")}`,
+    `  ${arrow} ${bold("archik dev")}    ${dim("open the live canvas in your browser")}`,
+    `  ${arrow} ${bold("archik --help")} ${dim("full command list")}`,
+    "",
+    `  ${dim("Docs: https://npmjs.com/package/archik")}`,
+    "",
+  ].join("\n"),
+);