archik 0.7.1 → 0.7.3

package/.claude/commands/archik/describe.md

@@ -1,5 +1,5 @@
 ---
-description: Explain a node and its connections
+description: Show a node's connections
 argument-hint: <node-id>
 ---
 

package/.claude/commands/archik/dev.md

@@ -1,5 +1,5 @@
 ---
-description: Start the live canvas in the browser
+description: Open the live canvas
 ---
 
 # /archik:dev — open the archik canvas

package/.claude/commands/archik/evolve.md

@@ -1,6 +1,6 @@
 ---
-description: Propose a cleaner modular architecture
-argument-hint: [optional focus area, e.g. "payments domain"]
+description: Propose a cleaner modular refactor
+argument-hint: [optional focus area]
 ---
 
 # /archik:evolve — propose a cleaner, bounded architecture
@@ -74,9 +74,22 @@ any file under `.archik/`.
    the highest-impact subset and tell the user the rest is round
    two.
 
-4. **Author the full proposed end-state** in a workspace temp file:
-   `/tmp/archik-evolve-<short-id>.yaml`. Constraints:
+4. **Author + stage in one step.** Pipe the full proposed
+   end-state directly into `npx archik suggest set -` via a
+   heredoc — no temp files, no `/tmp/` paths:
+
+   ```bash
+   npx archik suggest set --note "evolve: <one-line summary>" - <<'YAML'
+   version: "1.0"
+   name: My Architecture
+   nodes:
+     # full proposed end-state — every node, not just the delta
+   edges:
+     # ...
+   YAML
+   ```
 
+   Constraints when authoring the YAML:
    - Preserve every existing node id you keep — only add or remove
      ids, never rename. Renames break diff and require the user to
      manually re-link references in code.
@@ -84,14 +97,10 @@ any file under `.archik/`.
      fields the user authored. Carry them over verbatim.
    - Every change should be motivated by step 3, not by aesthetics.
 
-5. **Stage the draft via the CLI**:
-   ```
-   npx archik suggest set --note "evolve: <one-line summary>" /tmp/archik-evolve-<id>.yaml
-   ```
-   Fix and re-run on validation errors. Never patch the sidecar
-   directly.
+   If `suggest set` reports validation errors, re-run with the
+   corrected YAML. Never patch the sidecar directly.
 
-6. **Open the discussion.** Print, in this order:
+5. **Open the discussion.** Print, in this order:
 
    a. The canvas URL with: *"📝 Evolved diagram staged — open
       <URL> and toggle Review to see green / red / amber overlays."*
@@ -110,9 +119,9 @@ any file under `.archik/`.
 ## Iterating
 
 If the user pushes back on specific items ("keep the orders
-service whole; only fix the Stripe integration"), update the
-draft in the same temp file and re-run `npx archik suggest set` —
-it overwrites the previous sidecar. Acknowledge what you changed
+service whole; only fix the Stripe integration"), re-run
+`npx archik suggest set -` with the revised YAML — it overwrites
+the previous sidecar. Acknowledge what you changed
 since the last round so the user doesn't have to re-read the
 whole diff.
 

package/.claude/commands/archik/spawn.md

@@ -1,5 +1,5 @@
 ---
-description: Bootstrap the diagram from the source tree
+description: Mirror the source tree as a diagram
 ---
 
 # /archik:spawn — mirror the codebase as an archik diagram
@@ -102,27 +102,47 @@ archik suggest set` stages it.
    When in doubt, leave the edge out. The user will add it via
    `/archik:suggest` later.
 
-7. **Stage the draft.** Write the full proposed end-state to
-   `/tmp/archik-spawn-<short-id>.yaml`. If you generated sub-files,
-   write each one to its own temp file (`/tmp/archik-spawn-<sub>-<id>.yaml`)
-   and `suggest set` them too — but only the main file becomes a
-   sidecar. The sub-files need to live at their final
-   `.archik/<id>.archik.yaml` paths *before* you stage the main
-   draft, otherwise cross-file validation fails. So:
-
-   a. For each `archikFile: .archik/<id>.archik.yaml` you reference,
-      stage that sub-file first with its own
-      `npx archik suggest set` … then accept it immediately
-      (`npx archik suggest accept`) so the file is on disk under
-      `.archik/<id>.archik.yaml`. Yes, this is a chain of
-      micro-commits — that's the only CLI-blessed way to land
-      sub-files.
-   b. After all sub-files exist, stage the main draft:
+7. **Stage the draft.** Pipe the YAML straight into `npx archik
+   suggest set -` via a heredoc — no temp files, no `/tmp/` paths.
+   Sub-files come first because the main draft references them via
+   `archikFile`, and `suggest set` validates that those targets
+   exist on disk.
+
+   a. **Each sub-file**: the parent file doesn't exist yet, so
+      pass `--allow-orphan` to opt in to writing a sidecar for a
+      missing main. Then accept it so the file lands at
+      `.archik/<id>.archik.yaml`:
+      ```bash
+      npx archik suggest set --main .archik/<id>.archik.yaml \
+                             --allow-orphan \
+                             --note "spawn: <id> internals" - <<'YAML'
+      version: "1.0"
+      name: <Id> Internals
+      nodes: [ ... ]
+      edges: [ ... ]
+      YAML
+      npx archik suggest accept .archik/<id>.archik.yaml
       ```
-      npx archik suggest set --note "spawn: mirror source tree" /tmp/archik-spawn-<id>.yaml
+      Repeat for every sub-file. The `accept` step is what makes
+      the file real on disk — without it the orphan sidecar lingers
+      and the canvas shows it as "(pending)" rather than rendering it.
+
+   b. **Main draft**: once all sub-files exist (i.e. their
+      `accept`s succeeded), stage the main one. No `--allow-orphan`
+      needed because the main file already exists from `archik init`:
+      ```bash
+      npx archik suggest set --note "spawn: mirror source tree" - <<'YAML'
+      version: "1.0"
+      name: My Architecture
+      nodes:
+        # full proposed end-state, with archikFile pointers
+      edges:
+        # ...
+      YAML
       ```
-   c. If `suggest set` reports validation errors, fix the temp
-      file and re-run. Never edit the sidecar by hand.
+
+   c. If `suggest set` reports validation errors, re-run with the
+      corrected YAML. Never edit the sidecar by hand.
 
 8. **Tell the user how to review.** Surface the canvas URL plus:
    - "📝 Initial diagram staged from source tree — open the

package/.claude/commands/archik/suggest.md

@@ -1,5 +1,5 @@
 ---
-description: Propose diagram changes from a feature description
+description: Propose a diagram change
 argument-hint: <feature description>
 ---
 
@@ -43,22 +43,28 @@ the contract with the user.
    If `$ARGUMENTS` mentions a specific node by name, also run
    `npx archik q describe <id>` for it.
 
-3. **Author the draft** in a workspace temp file (NOT under
-   `.archik/`). Use the path `/tmp/archik-draft-<short-id>.yaml`.
-   The draft is the *full proposed end-state* of the document — every
-   node and edge, not just the delta. Follow the schema, kinds, and
-   relationships documented in the archik skill.
+3. **Author + stage in one step.** Pipe the draft straight into
+   `npx archik suggest set -` via a heredoc — no temp file, no
+   `/tmp/` paths. The CLI validates the schema, checks cross-file
+   references, stamps `metadata.suggestion`, and atomically writes
+   `.archik/main.archik.suggested.yaml`:
 
-4. **Stage the draft as the sidecar via the CLI**:
+   ```bash
+   npx archik suggest set --note "$ARGUMENTS" - <<'YAML'
+   version: "1.0"
+   name: My Architecture
+   nodes:
+     # full proposed end-state — every node, not just the delta
+   edges:
+     # full proposed end-state — every edge, not just the delta
+   YAML
    ```
-   npx archik suggest set /tmp/archik-draft-<id>.yaml --note "$ARGUMENTS"
-   ```
-   This validates the schema, checks cross-file references, stamps
-   `metadata.suggestion`, and atomically renames it into place. If
-   the command exits non-zero, fix the reported errors in the temp
-   file and re-run — never edit the sidecar directly.
 
-5. **Tell the user how to review**. Surface the canvas URL from
+   If the command exits non-zero, re-run with the corrected YAML.
+   Never write a draft file under `.archik/` and never edit the
+   sidecar directly.
+
+4. **Tell the user how to review**. Surface the canvas URL from
    step 1 plus the terminal options:
    - "📝 Suggestion ready — open the canvas at <URL> and use the
      **Review** banner to see added/removed/changed nodes."