@invariant.guru/cli 0.7.1 → 0.8.1

package/README.md

@@ -1,6 +1,47 @@
 # Invariant CLI
 
-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.
+A harness-agnostic workspace for spec-driven AI development. The **session file
+is the unit of work**: what was asked, the plan, and where it has got to, in one
+markdown file your agent reads and reports back into.
+
+It is also a package manager for agent context — agents, skills, commands, rules
+and instructions, stored **once** in `.agents/` (the
+[Agent Skills](https://agentskills.io) standard most harnesses read natively),
+with each CLI target getting a view of it rather than its own copy.
+
+Everything is local. No account, no server, no network.
+
+## We never spend tokens
+
+**Invariant does not call an LLM. Ever.**
+
+You already pay for a harness subscription — Claude Code, Codex, Cursor,
+whatever it is — and you are not going to pay a second time, in tokens, for a
+management layer. So this tool ships no API key, proxies no model traffic, and
+runs no inference. Your agent calls *it*:
+
+```bash
+invariant session next <id>              # what to do now, and the next command
+invariant session status <id> planning   # …and the agent reports back
+```
+
+Those are ordinary shell commands. Any harness that can run one participates,
+and nothing here is coupled to any of them.
+
+## Where your work lives
+
+On your machine, in your repository:
+
+| | |
+|---|---|
+| `.invariant/sessions/` | your sessions, as markdown |
+| `.invariant/events/` | a local journal of what changed, git-ignored |
+| `~/.invariant/` | the daemon's own state: which projects, which port, its log |
+
+Sessions contain code excerpts and architecture plans, which is exactly why none
+of it goes anywhere. When there is a hosted layer for teams it will be opt-in, it
+will relay these same events and nothing else, and it will be self-hostable from
+the day it exists.
 
 ## Requirements
 
@@ -28,6 +69,46 @@ invariant update --check
 invariant update
 ```
 
+## The loop, end to end
+
+```bash
+invariant init claude          # once, at the repository root
+invariant ui                   # the dashboard; leave it running
+invariant plan "add the cargo booking command"
+```
+
+`plan` prints a line to paste into your agent:
+
+```
+execute instructions from /repo/.invariant/sessions/session-01a0….md
+```
+
+From there the agent drives it, and the board follows along:
+
+```bash
+invariant session status <id> planning              # it announces itself
+invariant session status <id> planned --title "…"   # the plan is ready — your turn
+invariant session status <id> in-progress           # you said go
+invariant session step complete <id> 1              # …and it works through the plan
+invariant session status <id> executed --summary "…"
+```
+
+You never type those — the agent does, because `invariant sync` taught it the
+protocol. When it is unsure, it asks:
+
+```bash
+invariant session next <id>
+```
+
+Then have the work read by someone who did not write it:
+
+```bash
+invariant review open --session <id>   # paste into a NEW conversation
+```
+
+Triage the comments in the UI, and either implement the accepted ones or send
+them to the merge request. That is the whole loop.
+
 ## Getting Started
 
 The core loop is **init → install → add → sync**, with `plan` on top when you start a task.
@@ -242,6 +323,21 @@ invariant ui status       # the daemon, and the projects it serves
 invariant ui stop         # stop it
 ```
 
+`invariant ui` is the **daemon** with a browser opened on top of it. The daemon
+is the process that serves every project, watches for changes, and journals
+them; scripts and hooks talk to it by its own name:
+
+```bash
+invariant daemon start    # no browser
+invariant daemon status --json
+invariant daemon logs -f  # ~/.invariant/logs/daemon.log
+invariant daemon compact  # snapshot and purge this project's old events
+```
+
+Leave it running. The verbs work without it — they write the file directly and
+leave the event for the daemon to pick up — but with it running, every change
+reaches every open page as it happens.
+
 **One server, every project.** Running `invariant ui` in a second repository does
 not start a second server — it registers that folder and opens it in the one
 already running. `⌘P` switches between projects; `⇧⌘H` goes to the list of them
@@ -250,9 +346,11 @@ reload, bookmarks and a second tab on a second project all work the way you
 would expect, and nothing from one project survives into the next.
 
 ```bash
-invariant projects            # every registered project
+invariant projects            # every registered project, by group
 invariant projects add [path] # register one (defaults to the current folder)
 invariant projects remove     # forget one — its files are left alone
+invariant projects rename …   # name it on this machine (three folders called `frontend`)
+invariant projects group …    # file it under a group
 ```
 
 The list lives in `~/.invariant/projects.json`.
@@ -622,20 +720,124 @@ token kept in `~/.invariant/ui.json` (mode 0600). Every request names the projec
 it acts on (`/api/p/<project>/…`) and is scoped to that project's directory for
 its whole lifetime, so one project can never read or write another's files.
 
+### `invariant session <subcommand>`
+
+The verb surface an agent drives sessions with. Every verb validates, records
+what it did, and returns an exit code — see
+[docs/spec-session-protocol.md](docs/spec-session-protocol.md).
+
+```bash
+invariant session                              # list
+invariant session next [<id>]                  # what to do now, and the command for it
+invariant session show <id> [--body]
+invariant session path <id>                    # the absolute path, alone
+invariant session status <id> <status> [--summary "…"] [--title "…"]
+invariant session title <id> "A better title"
+invariant session step list <id>
+invariant session step complete <id> 2         # …or part of the step's text, or --all
+invariant session write <id> --section Plan --file plan.md
+invariant session link <id> --parent <session> # give an orphaned review its subject
+invariant session archive <id>
+invariant session migrate --all                # repair legacy headers
+invariant session events <id>                  # what the log says happened
+invariant session reconcile [--dry-run]        # infer what nobody reported
+invariant session protocol                     # the block that teaches an agent this
+```
+
+| Exit | Meaning |
+|---|---|
+| `0` | it worked |
+| `1` | it failed |
+| `2` | usage: a missing argument, an unknown status, an ambiguous step |
+| `3` | not found |
+| `4` | a conflict: a stale etag, a review that is not triaged |
+| `5` | the daemon was required (`INVARIANT_DAEMON=require`) and is not running |
+
+`--json` on any of them prints the same shape the HTTP API returns.
+
+### `invariant validate [sessions...]`
+
+Check this project's sessions against the published format. The point of the
+command is the exit code: `0` clean, `1` findings.
+
+```bash
+invariant validate                  # every session
+invariant validate --reviews        # review documents too
+invariant validate --events         # the event log too
+invariant validate --fix            # rewrite the headers a rewrite can fix
+invariant validate --json --quiet   # for CI
+```
+
+Beyond each file's own rules it checks what no single file can: a `parent` that
+resolves, a review document that exists when the session says it should, two
+sessions claiming the same review. See
+[docs/spec-session-format.md](docs/spec-session-format.md).
+
+### `invariant daemon <subcommand>`
+
+The one local process. It serves every registered project, watches for changes,
+journals them, and hosts the UI.
+
+```bash
+invariant daemon start [port]   # start or attach; no browser
+invariant daemon stop
+invariant daemon status --json
+invariant daemon logs -f
+invariant daemon compact        # snapshot and purge this project's old events
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `start [port]` | Start (or attach to) the daemon. Default port 4200, probing forward |
+| `stop` | Graceful shutdown, then SIGTERM, then SIGKILL |
+| `status` | The daemon and the projects it serves (`--json`). Exit 0 running, 1 not |
+| `logs` | Print `~/.invariant/logs/daemon.log` (`-f` to follow) |
+| `compact` | Fold old events into a snapshot and purge the segments |
+
+`invariant ui` is the same process with a browser opened on top of it.
+
+Environment:
+
+| | |
+|---|---|
+| `INVARIANT_DAEMON` | `auto` (default) \| `require` \| `off` — whether a verb may use the daemon |
+| `INVARIANT_DAEMON_PORT` | The port a spawned daemon binds |
+| `INVARIANT_READ_MODEL` | `fs` turns the event-log projection off |
+| `INVARIANT_HOME` | Relocates all of `~/.invariant` |
+
 ### `invariant projects`
 
 The projects the UI serves, kept in `~/.invariant/projects.json`.
 
 ```bash
-invariant projects                  # list them, with what each is waiting on
-invariant projects add [path]       # register a folder (defaults to the current one)
-invariant projects remove [id|path] # forget one — nothing on disk is touched
+invariant projects                            # list them, by group, with what each is waiting on
+invariant projects add [path]                 # register a folder (defaults to the current one)
+invariant projects remove [id|path]           # forget one — nothing on disk is touched
+invariant projects rename <id|path> <name>    # what this machine calls it
+invariant projects rename <id|path> --clear   # back to the name in invariant.json
+invariant projects group <id|path> <group>    # file it under a group, creating one if needed
+invariant projects group <id|path> --none     # take it out of its group
+invariant projects groups                     # the groups, and how full each one is
+invariant projects groups new <name>          # create an empty group
+invariant projects groups rm <name|id>        # delete a group — its projects survive, ungrouped
 ```
 
 A project must have been initialized (`invariant init`) before it can be added.
 Removing one only edits the list: re-adding the path brings back every session,
 review and setting exactly as they were.
 
+**Names.** Three checkouts whose folders are all called `frontend` are three
+unreadable rows. `rename` gives one a name *on this machine* — it is stored in
+`~/.invariant/projects.json`, never in `invariant.json`, so it does not reach
+anyone who clones the repository. The manifest name stays visible underneath the
+override in the UI, and `--clear` goes back to it. Without an override, a rename
+inside `invariant.json` still shows up on its own.
+
+**Groups.** A group is a collapsible section on the projects screen. Groups are
+machine-local too, names are unique, and deleting one never deletes a project —
+its members simply become ungrouped. `--flat` on `invariant projects` keeps the
+old ungrouped output for anything parsing it.
+
 In the UI: `⌘K` opens the command palette, `⌘P` switches project, `⇧⌘H` goes to
 the project list, `⇧⌘V` toggles rendered preview and editing, `N` starts a
 session, `?` lists every shortcut. On a review session,
@@ -718,42 +920,14 @@ invariant package publish
 
 `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 stats [subcommand]`
 
 Inspect Claude Code token usage and cost.
 
+> **Best effort, Claude Code only.** It reads local transcript files whose
+> format is not a contract, so it may go quiet after a Claude Code release. It
+> reads them and nothing else — no network, no LLM call.
+
 ```bash
 invariant stats
 invariant stats --live