archik 0.6.0 → 0.6.2

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

@@ -44,6 +44,41 @@ 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 file is the user's source of truth. You don't get to
@@ -82,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
@@ -555,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
 ```
 

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"),
+);