archik 0.6.18 → 0.6.21

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

@@ -37,8 +37,12 @@ you can talk about the system without re-explaining it every time.
    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.
+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.
 
 The sections below are the detailed reference behind these three
 rules — *when* to consult, *when* to propose, schema, taxonomy,
@@ -68,11 +72,11 @@ service" but not where to go to read or edit it. So:
    — 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.
+4. **Cross-check the source tree** when answering structural
+   questions: most projects keep one folder per top-level node under
+   `src/` (or `services/` / `packages/`). Mismatches are where
+   moving code will outgrow the diagram and where new code most
+   often needs a YAML update too.
 
 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
@@ -135,9 +139,13 @@ asked).
 
 * Write the *full proposed document*, not a patch. The diff is
   computed by archik between the main file and the sidecar.
-* Run `archik validate architecture.archik.suggested.yaml` after
-  writing. The schema enforces cross-references (no dangling edges,
-  no parent cycles, no duplicate ids); silent failures are not OK.
+* 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.
@@ -264,6 +272,10 @@ Constraints (the schema enforces them):
 
 - The cross-file path follows the same rules as `archikFile` (relative,
   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
+  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
   it inside one of the two referenced files instead.
@@ -282,12 +294,18 @@ Constraints (the schema enforces them):
 - 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).
+- **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`
+  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
   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:
+`main.archik.yaml`, and reference them with the `.archik/` prefix:
 
 ```
 .archik/main.archik.yaml          # entry point
@@ -295,6 +313,16 @@ Conventional layout: keep sub-files under `.archik/` next to
 .archik/payments.archik.yaml      # Payments service internals
 ```
 
+```yaml
+# in .archik/main.archik.yaml
+nodes:
+  - id: orders
+    kind: service
+    name: Orders
+    archikFile: .archik/orders.archik.yaml   # ✅ project-root relative
+    # archikFile: orders.archik.yaml         # ❌ validate fails
+```
+
 ## Node kinds (27 total, grouped by purpose)
 
 | Group       | Kinds |
@@ -590,7 +618,6 @@ 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 check                       # drift: nodes vs source dirs
 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
@@ -605,20 +632,20 @@ archik checkout.
 
 ## Verification workflow
 
-After **every** edit you make to the archik file:
+After **every** edit you make to an archik file (root, sidecar, or
+sub-file):
 
-1. Run `archik validate` — fix any reported errors before declaring
-   the change done. Schema errors include the path of the offending
-   field so you can fix them precisely.
+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.
-4. For nodes whose `kind` implies code (`service`, `function`, `worker`,
-   `agent`, `frontend`, `gateway`, `tool`, `module`), consider
-   `archik check` to flag nodes that don't have a matching source
-   folder under `src/`, `services/`, `packages/`, or `apps/`.
 
 ## Things to avoid
 

package/README.md

@@ -129,7 +129,6 @@ archik render [path]     Render to a self-contained SVG file
                          --out <file>     output path (default: diagram.svg)
                          --theme <name>   "dark" (default) or "light"
 archik watch [path]      Re-render to SVG on every file change (Ctrl+C to stop)
-archik check [path]      Drift detection — flag nodes without matching source dirs
 
 archik skill             Install the Claude skill for AI editing
                          --user           install into ~/.claude/skills (all projects)
@@ -153,9 +152,6 @@ archik validate
 
 # Generate a committable SVG of your architecture for the docs site
 archik render --theme light --out docs/architecture.svg
-
-# Warn when nodes don't have a matching source folder under src/, services/, packages/, or apps/
-archik check
 ```
 
 ## Schema