archik 0.1.0 → 0.1.2

package/README.md

@@ -1,106 +1,138 @@
 # Archik
 
-A JSON-native architecture diagram tool. The YAML file is the source of
-truth; the canvas is a stateless projection of it. Both humans and LLMs
-edit the same file. Layout is computed by ELK; coordinates never appear
-in the YAML.
+> An architecture diagram tool where the file is the source of truth — and Claude can edit it alongside you.
 
-## Install once, use in every project
+<p align="center">
+  <img src="docs/hero.svg" alt="Sample Archik diagram of an LLM-assisted support system" width="780">
+</p>
 
-Inside this repo:
+You write a small YAML file describing your nodes (services, databases, queues, agents, LLMs, …) and the edges between them. Archik gives you a live browser canvas, a CLI for CI, and an installable AI skill so Claude Code understands your architecture file the same way you do — no proprietary format, no coordinates in the YAML, no manual layout.
+
+## Quickstart
 
 ```bash
-npm install
-npm link        # exposes the `archik` binary on your PATH
+npx archik init       # scaffold architecture.archik.yaml in cwd
+npx archik start      # canvas at http://localhost:5173 (background)
+npx archik stop       # done
 ```
 
-`npm link` creates a symlink from your global node binaries to
-`bin/archik.js` in this directory. The bin script resolves through the
-symlink (via `realpath`), spawns `tsx` against `src/cli/index.ts`, and
-runs the CLI without a separate build step.
+That's the whole onboarding. The canvas saves edits straight back to the YAML; the file is the truth, the canvas is a projection.
+
+## What you write
+
+```yaml
+version: "1.0"
+name: Support Hub
+nodes:
+  - id: api
+    kind: service
+    name: Support API
+    stack: Go + Postgres
+  - id: agent
+    kind: agent
+    name: Support Agent
+    description: Drafts replies, escalates risky ones.
+  - id: claude
+    kind: llm
+    name: Claude
+edges:
+  - id: api-agent
+    from: api
+    to: agent
+    relationship: invokes
+  - id: agent-claude
+    from: agent
+    to: claude
+    relationship: invokes
+    label: draft reply
+```
 
-If you ever want to remove it:
+No `x` / `y` / `width` — layout is computed by [ELK](https://eclipse.dev/elk/) on every render. The schema rejects coordinates so diffs stay meaningful.
 
-```bash
-npm unlink -g archik
-```
+## 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.
+- **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).
+- **AI skill** — `archik skill --user` installs a Claude Code skill that teaches Claude the schema, the protocol, and the verification workflow.
 
-## Per-project workflow
+## For Claude Code & other LLMs
 
-The YAML lives in your target project, not here. From any project
-directory:
+The whole reason Archik uses YAML instead of a binary format: **the file is the shared map between you and the model**. Run:
 
 ```bash
-cd ~/projects/my-app
-archik init             # only the first time — scaffolds architecture.archik.yaml
-archik dev              # opens the live canvas in your browser
+archik skill --user        # install once into ~/.claude/skills
 ```
 
-`archik dev` starts the Vite dev server from Archik's install dir, but
-points it at the current working directory's `architecture.archik.yaml`
-via the `ARCHIK_DOC_PATH` env var. The browser canvas loads, the file
-watcher sees your edits, the inspector saves back to your project's
-file. Nothing about Archik lives inside your project.
+…and Claude Code in any project gets the right vocabulary automatically. The skill defines a 3-rule protocol:
 
-## All commands
+1. **Read** `architecture.archik.yaml` before answering structural questions.
+2. **Propose** YAML updates whenever new work introduces or rewires components.
+3. **Run `archik validate`** after every edit to fail fast on schema errors.
+
+So conversations like *"add a payments worker that subscribes to the orders queue"* end with both the code change **and** the matching YAML diff — kept in sync without anyone having to remember.
+
+## Commands
 
 ```
-archik init              Scaffold a starter architecture.archik.yaml
-archik dev [path]        Open the canvas in your browser (foreground)
-                         --port <n>       dev server port
-                         --host <addr>    bind to host
-                         --no-open        don't auto-open the browser
+archik init [path]       Scaffold a starter architecture.archik.yaml
+                         --skill          also install the Claude skill into ./.claude/skills
+
+archik dev [path]        Open the canvas in your browser (foreground, Ctrl+C to stop)
 archik start [path]      Same as dev, but detached — prompt returns immediately
-                         --port <n>       dev server port
-                         --host <addr>    bind to host
 archik stop [path]       Stop the background server started with `archik start`
-archik status            List running archik instances (across all projects)
-archik validate [path]   Validate a document against the schema
+archik status            List running archik instances across all projects
+                         (dev / start share these flags)
+                         --port <n>       dev server port (default 5173)
+                         --host <addr>    bind address (default 127.0.0.1)
+                         --no-open        don't auto-open the browser
+
+archik validate [path]   Validate against the schema (CI-friendly, exit code 1 on error)
 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 file changes
-archik check [path]      Drift detection — flag nodes without source dirs
-```
+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
 
-Use `archik dev` for an interactive session you'll Ctrl+C to end, and
-`archik start` / `archik stop` when you want the canvas running in the
-background while you keep working in the same terminal. State is kept in
-`$TMPDIR/archik-cli/` keyed by the YAML path, so you can run several
-projects' canvases at once.
+archik skill             Install the Claude skill for AI editing
+                         --user           install into ~/.claude/skills (all projects)
+                         --force          overwrite an existing skill
+```
 
-Default path is `architecture.archik.yaml` in the current directory.
+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.
 
-## CI usage
+## Use it in CI
 
 ```bash
-# Fail the build if the diagram has schema errors:
+# Fail the build on schema errors
 archik validate
 
-# Generate an SVG of your architecture for the docs:
+# Generate a committable SVG of your architecture for the docs site
 archik render --theme light --out docs/architecture.svg
 
-# Compare nodes to source dirs and warn about drift:
+# Warn when nodes don't have a matching source folder under src/, services/, packages/, or apps/
 archik check
 ```
 
-## Directory layout (this repo)
+## Schema
 
+The full schema reference (every node kind, every relationship, common patterns, hard rules) lives in the AI skill. After installing it locally:
+
+```bash
+archik skill --user
+$EDITOR ~/.claude/skills/archik.md
 ```
-src/
-  domain/      Pure schema + commands (no React, no ELK)
-  layout/      ELK adapter behind a LayoutEngine interface
-  render/      Pure SVG renderer (DiagramSvg, per-kind shapes, edges)
-  io/          YAML/JSON, exporters, file adapter, live-reload
-  ui/          React app — toolbar, inspectors, modals, popovers
-  cli/         The `archik` binary you just installed
-vite/          Vite plugin that watches + serves the YAML over HTTP/WS
-.claude/skills/  archik.md — schema + patterns for AI editors
-```
 
-## For AI editors
+Or read it directly in this repo: [`.claude/skills/archik.md`](.claude/skills/archik.md).
+
+## Design notes
+
+- The YAML is the only persistent truth. The canvas is a stateless projection that reloads on every file change (live-reload via SSE).
+- Layout is non-negotiable: ELK lays out every render. Putting an `x` / `y` / `width` field at any level fails schema validation. No more "the diagram drifted because someone dragged a box."
+- The published npm package ships only the bundled binary — no source files, no build tooling. Zero runtime dependencies.
+
+## License
 
-`.claude/skills/archik.md` documents the schema, all 26 node kinds, all
-12 relationships, common editing patterns, and the verification
-workflow. Claude Code in this repo (or any project that copies the
-skill) gets the right vocabulary automatically.
+MIT © [Bashar](https://github.com/bacharSalleh)