@invariant.guru/cli 0.5.5 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # Invariant CLI
 
-A package manager for AI coding-agent context. Install, compose, and sync reusable agents, skills, commands, rules, contexts, and instructions into `.claude/`, `.cursor/`, and other CLI target folders.
+A package manager for AI coding-agent context. Install, compose, and sync reusable agents, skills, commands, rules, contexts, and instructions. Every item is stored **once** in `.agents/` — the [Agent Skills](https://agentskills.io) standard most harnesses read natively — and each CLI target gets a view of it rather than its own copy.
 
 ## Requirements
 
@@ -42,7 +42,7 @@ invariant init claude cursor        # multiple targets
 invariant init --name my-project
 ```
 
-Supported targets: `claude`, `codex`, `cursor`, `windsurf`, `aider`, `copilot`.
+Supported targets: `claude`, `codex`, `cursor`, `aider`, `copilot`.
 
 ### 2. `invariant install` — pull a package
 
@@ -119,13 +119,20 @@ invariant add skill:nest-clean-architecture/implement-command \
 
 Check what landed with `invariant inspect nest-clean-architecture`, or use `invariant add-interactive` for a checkbox tree of every installed item.
 
-### 4. `invariant sync` — write the files
+### 4. `invariant sync` — reconcile and write the files
 
-`sync` renders the active set into each configured target: `CLAUDE.md`, `.claude/agents/`, `.claude/skills/<name>/SKILL.md`, `.claude/commands/`, `.claude/rules/`, and the equivalents for other targets.
+`sync` brings the whole tree back in line with `invariant.json`: it rebuilds
+canonical items that went missing, materializes every active item for every
+configured target, prunes what is no longer active, and regenerates the context
+files (`CLAUDE.md`, `AGENTS.md`, …).
+
+Add a target to `invariant.json`, run `sync`, and that target is set up — no need
+to re-run `add`.
 
 ```bash
 invariant sync
 invariant sync --target claude
+invariant sync --check          # CI gate: exits 1 when the tree is stale
 ```
 
 `add`, `install`, and `add-interactive` all accept `-s, --sync` to do this in one shot:
@@ -144,12 +151,30 @@ invariant plan "implement the cargo booking command" --context nest-clean-archit
 invariant plan "implement the cargo booking command" --full
 ```
 
+Every session file starts with a `<session-meta>` header carrying its title and
+status (`draft` → `planned` → `in-progress` → `executed`). The agent updates it
+as the work progresses; the UI reads it.
+
 When the session is done, stamp it:
 
 ```bash
 invariant plan:complete <session-id> --summary "Booking command + tests"
 ```
 
+### 6. `invariant ui` — see and manage your sessions
+
+Opens a local dashboard for this project's sessions: a board grouped by status,
+rendered markdown, a rich editor, and a command palette.
+
+```bash
+invariant ui              # start on 4200 (or the next free port) and open a browser
+invariant ui status       # every running instance on this machine
+invariant ui stop         # stop this project's instance
+```
+
+Each directory gets its own instance on its own port, so several repositories can
+be open at once without ever mixing sessions.
+
 ### Full walkthrough
 
 ```bash
@@ -158,6 +183,7 @@ invariant install github:invariant-guru/inv-nest-clean-architecture
 invariant add nest-clean-architecture   # activate the whole module
 invariant sync
 invariant plan "add the cargo booking command"
+invariant ui                            # follow it through to done
 ```
 
 ---
@@ -179,6 +205,8 @@ invariant init --hybrid
 |--------|-------------|
 | `-n, --name <name>` | Project name (defaults to directory name) |
 | `--hybrid` | Initialize as hybrid mode — project *and* package in one directory |
+| `--copy` | Copy items into each target folder instead of linking them to `.agents/` |
+| `--canonical-dir <dir>` | Canonical store location (default `.agents`) |
 
 ### `invariant install [packages...]`
 
@@ -306,7 +334,9 @@ invariant sync --target cursor
 
 | Option | Description |
 |--------|-------------|
-| `-t, --target <target>` | Sync only to a specific target (`claude`, `codex`, `cursor`, `windsurf`, `aider`, `copilot`) |
+| `-t, --target <target>` | Sync only to a specific target (`claude`, `codex`, `cursor`, `aider`, `copilot`). Skips pruning — the other targets are out of scope |
+| `--check` | Report drift without writing anything; exits `1` when out of sync |
+| `--force` | Replace target files that were hand-edited away from the canonical item |
 
 ### `invariant inspect [package]`
 
@@ -370,7 +400,9 @@ invariant plan "implement user authentication" --context nest-clean-architecture
 
 ### `invariant plan:complete <session>`
 
-Stamp a completion header at the top of a finished session file.
+Mark a session finished: sets `<status>` to `executed` and stamps `<summary>` and
+`<completed>` in the session's `<session-meta>` header. Notes are appended to the
+body as a **Completion notes** section.
 
 ```bash
 invariant plan:complete session-uuid --summary "Auth command + e2e tests"
@@ -383,6 +415,46 @@ invariant plan:complete session-uuid -n "Follow-up: rate limiting" -d 2026-08-19
 | `-n, --note <note>` | Extra note line (repeatable) |
 | `-d, --date <date>` | Completion date (`YYYY-MM-DD`), defaults to today |
 
+### `invariant ui [port]`
+
+Start (or attach to) the local session UI for the current project, then open a
+browser. One instance per directory; the default port is 4200 and the next free
+port is used when it is taken.
+
+```bash
+invariant ui                    # start and open a browser
+invariant ui 4300               # ask for a specific port (fails if it is busy)
+invariant ui --no-open          # start without opening a browser
+invariant ui status --json      # machine-readable status of every instance
+invariant ui stop --all         # stop every instance on this machine
+invariant ui migrate-headers    # add <session-meta> headers to legacy sessions
+```
+
+| Subcommand | Description |
+|--------|-------------|
+| *(none)* / `start [port]` | Start or attach, then open a browser |
+| `stop` | Stop this project's instance (`--all` for every instance) |
+| `status` | Every instance, liveness-checked (`--json`) |
+| `migrate-headers` | Give legacy session files a canonical `<session-meta>` header |
+
+| Option | Description |
+|--------|-------------|
+| `-p, --port <port>` | Port to listen on (default 4200) |
+| `--no-open` | Do not open a browser window |
+
+The server binds `127.0.0.1` only, checks `Host` and `Origin`, and requires a
+per-instance token kept in `~/.invariant/ui.json` (mode 0600). What it can read
+and write is limited to the directory it was started in.
+
+In the UI: `⌘K` opens the command palette, `⇧⌘V` toggles rendered preview and
+editing, `N` starts a session, `?` lists every shortcut.
+
+To work on the UI itself: start a daemon (`invariant ui --no-open`), then run
+`yarn dev:ui` for Vite with hot reload against it — `INVARIANT_UI_PORT=<port>`
+when the daemon landed on something other than 4200.
+
+See [docs/spec-ui.md](docs/spec-ui.md) for the header contract and the HTTP API.
+
 ### `invariant scan`
 
 Scan the codebase with embedded tree-sitter grammars and write a CodeGraph to `.invariant/codegraph/` — a structured inventory of files, languages, and top-level symbols for LLM navigation.
@@ -522,11 +594,64 @@ After `init` + `install` + `sync`:
 │   ├── contexts/            # rendered contexts
 │   ├── instructions/        # rendered instructions
 │   ├── sessions/            # `invariant plan` output
+│   │   └── .archive/        # sessions archived from the UI
 │   └── codegraph/           # `invariant scan` output
+├── .agents/                 # canonical store — the only physical copy
+│   ├── skills/<name>/SKILL.md
+│   ├── agents/<name>.md
+│   ├── commands/<name>.md
+│   └── rules/<name>.md
 ├── CLAUDE.md                # generated by `invariant sync`
-└── .claude/
-    ├── agents/<name>.md
-    ├── skills/<name>/SKILL.md
+└── .claude/                 # symlinks into .agents/
+    ├── agents/<name>.md  ->  ../../.agents/agents/<name>.md
+    ├── skills/<name>     ->  ../../.agents/skills/<name>
     ├── commands/<name>.md
     └── rules/<name>.md
 ```
+
+### One copy, many views
+
+`.agents/` holds the single physical copy of every activated item. What each
+target gets depends on how it reads skills:
+
+| Target | Skills | Agents / commands / rules |
+|---|---|---|
+| `claude` | symlink into `.agents/` | symlink into `.agents/` |
+| `codex` | reads `.agents/skills/` — nothing written | embedded in `AGENTS.md` |
+| `cursor` | reads `.agents/skills/` — nothing written | `.cursor/rules/<name>.mdc` |
+| `copilot` | reads `.agents/skills/` — nothing written | `.github/instructions/<name>.instructions.md` |
+| `aider` | embedded in `CONVENTIONS.md` | embedded in `CONVENTIONS.md` |
+
+Two consequences worth knowing:
+
+- Targets that speak the standard get **no invariant-written skill files**, so
+  they never read the same skill twice.
+- Hand-written items you put in `.claude/skills/` yourself are never touched —
+  invariant only manages what is listed in `invariant.json → active`, plus links
+  that resolve into `.agents/`. A target file you edit by hand is kept, with a
+  warning, until you pass `--force`.
+
+On hosts without symlink support the CLI falls back to a Windows junction, then
+to a physical copy, and says which one it used. `invariant init --copy` (or
+`"materialization": { "mode": "copy" }`) opts out of linking entirely.
+
+### Version control
+
+`.agents/` and the target folders are **generated** — they are rebuilt by
+`invariant add` and `invariant sync`, the way `node_modules` is rebuilt by a
+package manager. `init` and `sync` keep them out of git via a delimited block:
+
+```gitignore
+# --- invariant (generated, do not edit) ---
+.agents/
+.claude/agents/
+.claude/skills/
+.claude/commands/
+.claude/rules/
+CLAUDE.md
+# --- end invariant ---
+```
+
+Only paths invariant owns outright are listed, so a folder you share with it
+(`.cursor/rules/`, which also holds your own rules) is left alone. Commit
+`invariant.json`, run `invariant sync` after a clone.