@invariant.guru/cli 0.5.6 → 0.6.0

package/README.md

@@ -151,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
@@ -165,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
 ```
 
 ---
@@ -381,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"
@@ -394,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.
@@ -533,6 +594,7 @@ 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