@invariant.guru/cli 0.5.4 → 0.5.6

package/README.md

@@ -1,112 +1,277 @@
 # Invariant CLI
 
-A package manager for Claude AI specification files. Install, compose, and manage reusable markdown instruction blocks for your `CLAUDE.md` files.
+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
+
+- Node.js `>= 24`
+- `git` on `PATH` (used for GitHub package sources)
 
 ## Installation
 
 ```bash
-yarn global add @invariant--labs/cli
+# npm
+npm install -g @invariant.guru/cli
+
+# yarn
+yarn global add @invariant.guru/cli
+
+# pnpm
+pnpm add -g @invariant.guru/cli
 ```
 
-## Quick Start
+Verify and keep it current:
 
 ```bash
-# Initialize a project
-invariant init
+invariant version
+invariant update --check
+invariant update
+```
 
-# Install a package
-invariant install everything-claude-code
+## Getting Started
 
-# Add items from the package
-invariant add agent:everything-claude-code/planner
+The core loop is **init → install → add → sync**, with `plan` on top when you start a task.
 
-# Generate CLAUDE.md
-invariant claude
+### 1. `invariant init` — set up the project
+
+Run once at the repository root. Creates `invariant.json` (the manifest) and `.invariant/` (cache, contexts, instructions, sessions, codegraph).
+
+```bash
+invariant init                      # defaults to the `claude` target
+invariant init claude cursor        # multiple targets
+invariant init --name my-project
+```
+
+Supported targets: `claude`, `codex`, `cursor`, `aider`, `copilot`.
+
+### 2. `invariant install` — pull a package
+
+Packages come from the registry or straight from GitHub. Installing caches the package **and** activates its items.
+
+```bash
+# From GitHub (owner/repo, optional #ref)
+invariant install github:invariant-guru/inv-nest-clean-architecture
+
+# Pin a branch or tag
+invariant install github:invariant-guru/inv-nest-clean-architecture#main
+
+# From the registry (same package, published name)
+invariant install nest-clean-architecture
+```
+
+This writes the package into `invariant.json`:
+
+```json
+{
+  "packages": {
+    "nest-clean-architecture": {
+      "name": "nest-clean-architecture",
+      "version": "1.0.0",
+      "source": "github",
+      "sourceUrl": "github:invariant-guru/inv-nest-clean-architecture"
+    }
+  }
+}
+```
+
+### 3. `invariant add` — pick what's active
+
+`install` already activates everything. Use `add` to curate: a whole package, one item type, or a single item.
+
+**Add the whole module** — every agent, skill, command, rule, context, and instruction the package ships:
+
+```bash
+invariant add nest-clean-architecture
+```
+
+```
+Adding all items from nest-clean-architecture...
+✓ Added items from nest-clean-architecture
+  agents:
+    - clean-architect
+  skills:
+    - implement-aggregate-root
+    - implement-command
+    - implement-query
+    - ...
+  rules:
+    - aggregate-root
+    - command
+    - ...
+  instructions:
+    - nest-clean-architecture
+```
+
+**Add one type** — e.g. only the skills, or only the rules:
+
+```bash
+invariant add skills:nest-clean-architecture
+invariant add rules:nest-clean-architecture
+```
+
+**Add single items** — one target per item, mixed types allowed:
+
+```bash
+invariant add agent:nest-clean-architecture/clean-architect
+invariant add skill:nest-clean-architecture/implement-command \
+             rule:nest-clean-architecture/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` — reconcile and write the files
+
+`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:
+
+```bash
+invariant install github:invariant-guru/inv-nest-clean-architecture --sync
 ```
 
+### 5. `invariant plan` — start a task
+
+Composes a session file under `.invariant/sessions/` containing your prompt plus the active instructions (and optionally a context), then prints the one-liner to paste into your agent.
+
+```bash
+invariant plan "implement the cargo booking command"
+invariant plan "implement the cargo booking command" --context nest-clean-architecture/dev
+invariant plan "implement the cargo booking command" --full
+```
+
+When the session is done, stamp it:
+
+```bash
+invariant plan:complete <session-id> --summary "Booking command + tests"
+```
+
+### Full walkthrough
+
+```bash
+invariant init claude
+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"
+```
+
+---
+
 ## Commands
 
-### `invariant init`
+### `invariant init [targets...]`
 
-Initialize Invariant in your project. Creates `invariant.json` and `.invariant/` directory.
+Initialize a new invariant project with the given target CLI(s). Defaults to `claude`.
 
 ```bash
 invariant init
+invariant init claude cursor
 invariant init --name my-project
+invariant init --hybrid
 ```
 
-### `invariant install [package...]`
+| Option | Description |
+|--------|-------------|
+| `-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...]`
 
-Install packages from the registry (or GitHub) and activate their items. If the package already has curated `active` entries in `invariant.json`, exactly those are restored; otherwise all items are added.
+Install packages from the registry or GitHub and activate their items. If the package already has curated `active` entries in `invariant.json`, exactly those are restored; otherwise all items are added.
 
 ```bash
-invariant install everything-claude-code
+invariant install github:invariant-guru/inv-nest-clean-architecture
+invariant install github:invariant-guru/inv-nest-clean-architecture#v1.2.0
+invariant install nest-clean-architecture
+invariant install nest-clean-architecture@1.0.0
 
-# Install every package declared in invariant.json (same activation rule per package)
+# Reinstall every package declared in invariant.json
 invariant install
 
-# Only cache the package, don't activate anything (pre-0.5 behavior)
-invariant install everything-claude-code --no-add
-
-# Run `invariant sync` automatically afterwards
-invariant install everything-claude-code --sync
+# Cache only, activate nothing
+invariant install nest-clean-architecture --no-add
 ```
 
+Source syntax:
+
+| Form | Meaning |
+|------|---------|
+| `name` | Registry package, latest version |
+| `name@version` | Registry package, pinned version |
+| `github:owner/repo` | GitHub repo, default branch |
+| `github:owner/repo#ref` | GitHub repo at a branch, tag, or commit |
+
 | Option | Description |
 |--------|-------------|
 | `--no-add` | Only cache the package, do not activate its items |
 | `-s, --sync` | Run `invariant sync` after installing |
 
-### `invariant add <target> [<target>...]`
+### `invariant add [targets...]`
 
-Activate items from installed packages. Accepts one or more targets.
+Activate items from cached packages. Accepts one or more targets.
 
-```bash
-# Add all items from a package
-invariant add everything-claude-code
-
-# Add a specific agent
-invariant add agent:everything-claude-code/planner
+Target formats:
 
-# Add multiple items at once
-invariant add skill:my-pkg/react-expert skill:my-pkg/ts-patterns
+| Form | Meaning |
+|------|---------|
+| `<package>` | All items from the package |
+| `<type>:<package>` | All items of that type |
+| `<type>:<package>/<item>` | One specific item |
+| `<package>/<item>` | One item, searching every type |
 
-# Mix types and packages
-invariant add agent:pkg-a/planner skill:pkg-b/tdd
+Types (singular or plural): `agent`, `skill`, `command`, `rule`, `context`, `instruction`.
 
-# Run `invariant sync` automatically afterwards
-invariant add everything-claude-code --sync
+```bash
+invariant add nest-clean-architecture
+invariant add agent:nest-clean-architecture/clean-architect
+invariant add skill:nest-clean-architecture/implement-query \
+             skill:nest-clean-architecture/implement-repository
+invariant add rules:nest-clean-architecture                    # every rule
+invariant add agent:nest-clean-architecture/clean-architect skill:skills/skill-creator --sync
 ```
 
+Run with no arguments to print usage.
+
 | Option | Description |
 |--------|-------------|
 | `-s, --sync` | Run `invariant sync` after adding |
 
 ### `invariant add-interactive`
 
-Interactively select/unselect what's active — like `yarn upgrade-interactive`. Checked rows reflect the current activation state; checking adds, unchecking removes.
+Interactively select/unselect what's active — like `yarn upgrade-interactive`. Checked rows reflect current activation state; checking adds, unchecking removes.
 
-By default it shows a **hierarchical tree**: package → item type (agents / skills / commands / rules / contexts / instructions) → item. Toggling a package or type **cascades** to all its items. Category rows show a `(selected/total)` count and a tri-state glyph — `◉` all, `◐` some, `◯` none:
+Default view is a **hierarchical tree**: package → item type → item. Toggling a package or type row **cascades** to its items. Category rows show a `selected/total` count and a tri-state glyph — `◉` all, `◐` some, `◯` none:
 
 ```
-◐ nest-clean-architecture@1.0.0 (1/3)
-  ◯   agents (0/1)
-  ◯     architect
-  ◐   skills (1/2)
-  ◉     qweqwe
-  ◯     sdgsd
+◐ nest-clean-architecture@1.0.0 1/3
+│
+├─ ◯ agents 0/1
+│  └─ ◯ clean-architect
+│
+└─ ◐ skills 1/2
+   ├─ ◉ implement-command
+   └─ ◯ implement-query
 ```
 
-Keys: `↑↓` move · `space` toggle (cascades on a package/type row) · `a` all · `i` invert · `enter` confirm.
+Keys: `↑↓` move · `space` toggle (cascades on a package/type row) · `a` toggle all · `i` invert · `enter` confirm.
 
 ```bash
-# Item-level tree (default)
-invariant add-interactive
-
-# Coarse selection: one checkbox per whole package
-invariant add-interactive --packages
-
-# Apply changes and sync immediately
+invariant add-interactive              # item-level tree (default)
+invariant add-interactive --packages   # one checkbox per whole package
 invariant add-interactive --sync
 ```
 
@@ -118,124 +283,313 @@ In `--packages` mode an already-active package left checked is untouched, so a c
 | `-s, --sync` | Run `invariant sync` after applying changes |
 | `-t, --target <target>` | With `--sync`, sync only to a specific target |
 
-### `invariant remove <target> [<target>...]`
+### `invariant remove [targets...]`
 
-Remove added items (inverse of `add`). The package stays in cache for future use. Accepts one or more targets.
+Deactivate items (inverse of `add`). The package stays in cache. Same target formats as `add`.
 
 ```bash
-# Remove all active items from a package
-invariant remove everything-claude-code
+invariant remove nest-clean-architecture
+invariant remove agent:nest-clean-architecture/clean-architect
+invariant remove rules:nest-clean-architecture
+invariant remove skill:nest-clean-architecture/implement-saga \
+                skill:nest-clean-architecture/implement-saga-test
+```
 
-# Remove a specific agent
-invariant remove agent:everything-claude-code/planner
+### `invariant uninstall <packages...>`
 
-# Remove multiple items at once
-invariant remove skill:my-pkg/react-expert skill:my-pkg/ts-patterns
+Completely remove packages: deletes all added items, drops the cache, and removes them from `invariant.json`.
+
+```bash
+invariant uninstall nest-clean-architecture
+invariant uninstall nest-clean-architecture skills
 ```
 
-### `invariant uninstall <package>`
+### `invariant sync`
 
-Completely remove a package: deletes all added items, removes from cache, and removes from config.
+Sync active instructions, contexts, and items to every configured CLI target (or just one).
 
 ```bash
-invariant uninstall everything-claude-code
+invariant sync
+invariant sync --target cursor
 ```
 
+| Option | Description |
+|--------|-------------|
+| `-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]`
 
 Show package contents with active items highlighted.
 
-**Without a target** — shows only active (added) items across all installed packages:
+**Without a target** — only active items across all installed packages:
 
 ```bash
 invariant inspect
 ```
 
 ```
-everything-claude-code@main
+nest-clean-architecture@1.0.0
 ────────────────────────────────────────
   agents/
-    ✓ planner
+    ✓ clean-architect
   skills/
-    ✓ backend-patterns/SKILL
+    ✓ implement-command
 ```
 
-**With `--details`** — shows all items (active and inactive) across all packages:
+**With `--details`** — all items, active and inactive, across all packages. **With a package name** — always all items for that package.
 
 ```bash
 invariant inspect --details
+invariant inspect nest-clean-architecture
 ```
 
+| Option | Description |
+|--------|-------------|
+| `-d, --details` | Show all items including inactive ones |
+
+### `invariant list`
+
+List installed or available packages.
+
+```bash
+invariant list              # installed packages
+invariant list --remote     # available packages from the registry
+invariant list --active     # only packages with active items
 ```
-everything-claude-code@main
-────────────────────────────────────────
-  agents/
-    ✓ planner
-    ○ architect
-    ○ code-reviewer
-  skills/
-    ✓ backend-patterns/SKILL
-    ○ tdd-workflow/SKILL
-  contexts/
-    ○ dev
-    ○ review
+
+| Option | Description |
+|--------|-------------|
+| `-r, --remote` | List available packages from the registry |
+| `-a, --active` | List only active packages |
+
+### `invariant plan <prompt>`
+
+Generate a session file in `.invariant/sessions/` with the task instructions plus active context.
+
+```bash
+invariant plan "implement user authentication"
+invariant plan "implement user authentication" --full
+invariant plan "implement user authentication" --context nest-clean-architecture/dev
 ```
 
-**With a specific package** — always shows all items (active and inactive):
+| Option | Description |
+|--------|-------------|
+| `-c, --context <context>` | Context to include (format: `package/context-name`) |
+| `-f, --full` | Inline full content from active packages instead of referencing the context file |
+
+### `invariant plan:complete <session>`
+
+Stamp a completion header at the top of a finished session file.
 
 ```bash
-invariant inspect everything-claude-code
+invariant plan:complete session-uuid --summary "Auth command + e2e tests"
+invariant plan:complete session-uuid -n "Follow-up: rate limiting" -d 2026-08-19
 ```
 
-| Flag | Description |
-|------|-------------|
-| `-d, --details` | Show all items including inactive ones |
+| Option | Description |
+|--------|-------------|
+| `-s, --summary <summary>` | Short resume of what the session accomplished |
+| `-n, --note <note>` | Extra note line (repeatable) |
+| `-d, --date <date>` | Completion date (`YYYY-MM-DD`), defaults to today |
 
-### `invariant list`
+### `invariant scan`
 
-List installed or available packages.
+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.
 
 ```bash
-invariant list              # List installed packages
-invariant list --remote     # List available packages from registry
-invariant list --active     # List only packages with active items
+invariant scan
+invariant scan --scope apps/cli src/core/auth
+invariant scan --include "src/**/*.ts" --exclude "**/*.spec.ts"
+invariant scan --max-files 2000
 ```
 
-### `invariant claude`
+| Option | Description |
+|--------|-------------|
+| `-i, --include <globs...>` | Include globs (default: `**/*`) |
+| `-e, --exclude <globs...>` | Extra exclude globs (on top of sensible defaults) |
+| `-s, --scope <scopes...>` | Scope the scan to specific paths |
+| `--max-files <count>` | Cap total scanned files (default: 5000) |
+| `--max-size <bytes>` | Skip files larger than this (default: 1 MB) |
 
-Generate a `CLAUDE.md` file from all active package items.
+Supported languages: TypeScript, JavaScript, Python, Go, Rust, JSON, Markdown, HTML, CSS.
+
+### `invariant package <subcommand>`
+
+Package authoring — for repositories that *are* an invariant package.
+
+```bash
+invariant package create --name my-pkg --version 1.0.0 --author "Me"
+invariant package refresh
+invariant package validate
+invariant package publish
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `create` | Scan the current folder and add package metadata to `invariant.json` |
+| `refresh` | Rescan items on disk and update `invariant.json` |
+| `validate` | Validate the items declared in `invariant.json` against disk |
+| `publish` | Validate, bundle, and publish the package to the registry |
+
+`package create` options: `-n, --name`, `--version`, `-d, --description`, `-a, --author`, `-l, --license`, `-r, --repository`.
+
+### `invariant proxy <subcommand>`
+
+Shared local LLM proxy daemon. Routes a repo's agent traffic through a local proxy by writing a managed env block (`ANTHROPIC_BASE_URL`) into `.claude/settings.json`.
+
+```bash
+invariant proxy start
+invariant proxy status
+invariant proxy status --json
+invariant proxy on           # route the current repo (or `on <dir>`)
+invariant proxy off          # revert the managed env block
+invariant proxy stop
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `start` | Start the shared proxy daemon |
+| `stop` | Stop the daemon (token is preserved) |
+| `status` | Daemon status, routes, and per-repo activations (`--json`) |
+| `on [dir]` | Route a repo through the proxy |
+| `off [dir]` | Revert the managed env block (daemon keeps running) |
+
+Agents read `ANTHROPIC_BASE_URL` once at launch — restart running sessions after `proxy on`.
+
+### `invariant claude [args...]`
+
+Launch Claude Code through the proxy, auto-starting the daemon. All arguments pass through untouched.
 
 ```bash
 invariant claude
+invariant claude -- --resume
 ```
 
-### `invariant plan "<instructions>"`
+### `invariant stats [subcommand]`
 
-Create a session file with task instructions.
+Inspect Claude Code token usage and cost.
 
 ```bash
-invariant plan "implement user authentication"
-invariant plan "implement user authentication" --full
-invariant plan "implement user authentication" --context everything-claude-code/dev
+invariant stats
+invariant stats --live
+invariant stats --since 7d --format table
+invariant stats cost
+invariant stats models
+invariant stats sessions
+invariant stats projects
 ```
 
-### `invariant scan [options]`
+| Subcommand | Description |
+|------------|-------------|
+| `cost` | Cost drill-down with cache savings |
+| `models` | Per-model token and cost aggregate |
+| `sessions` | Per-session breakdown (sorted by cost) |
+| `projects` | Per-project aggregate (implies `--all-projects`) |
+
+| Option | Description |
+|--------|-------------|
+| `--live` | Open the interactive dashboard |
+| `--since <duration>` | Start of window (e.g. `7d`, `24h`, `today`) |
+| `--until <duration>` | End of window (default: now) |
+| `--format <format>` | `markdown`, `json`, or `table` |
+| `--project <path>` | Absolute path to scope to |
+| `--all-projects` | Aggregate across every project |
+| `--model <id>` | Filter by model id |
+| `--include-turns` | (JSON only) include per-turn records |
+| `--verbose` | Print parse warnings and diagnostics |
+
+### `invariant version`
+
+Display the CLI version.
+
+### `invariant update`
 
-Scan the current codebase with embedded tree-sitter grammars. Produces `.invariant/scan/scan-report.json` and `.invariant/scan/scan-report.md` — a structured inventory of files, languages, and top-level symbols.
+Update the CLI to the latest version, using the package manager it was installed with.
 
 ```bash
-invariant scan
-invariant scan --language typescript --language python
-invariant scan --format json --max-files 2000
+invariant update
+invariant update --check
+invariant update --version 0.5.4
 ```
 
-| Flag | Description |
-|------|-------------|
-| `-i, --include <globs...>` | Include globs (default: `**/*`) |
-| `-e, --exclude <globs...>` | Extra exclude globs (in addition to sensible defaults) |
-| `-l, --language <langs...>` | Restrict to specific languages |
-| `-f, --format <format>` | `json`, `markdown`, or `both` (default: `both`) |
-| `--max-files <n>` | Cap total scanned files (default: 5000) |
-| `--max-size <bytes>` | Skip files larger than this (default: 1 MB) |
+| Option | Description |
+|--------|-------------|
+| `-v, --version <version>` | Update to a specific version |
+| `-c, --check` | Only check whether an update is available |
 
-Supported languages: TypeScript, JavaScript, Python, Go, Rust, JSON, Markdown, HTML, CSS.
+---
+
+## Project layout
+
+After `init` + `install` + `sync`:
+
+```
+.
+├── invariant.json           # manifest: targets, packages, active items
+├── .invariant/
+│   ├── cache/               # downloaded packages
+│   ├── contexts/            # rendered contexts
+│   ├── instructions/        # rendered instructions
+│   ├── sessions/            # `invariant plan` output
+│   └── 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/                 # 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.