@invariant.guru/cli 0.6.9 → 0.7.1

package/README.md

@@ -214,20 +214,48 @@ GitLab merge request, anchored on its file and line. Nothing is submitted for
 you and nobody is notified — you read the drafts in GitLab and press *Submit
 review*. The token is per project: see [docs/spec-review.md](docs/spec-review.md) §9.
 
+Publishing is one of the project's **integrations**, configured on the
+Configuration page. The other is **Linear**: link a session to an issue, and one
+block of that session — the human-facing spec, not the plan — syncs in either
+direction. The rest of the session is never sent.
+
+```
+Configuration → GitLab   publish a triaged review to a merge request
+Configuration → Linear   link a session to an issue and sync its spec
+```
+
+Conventions (host, project path, team key, the issue template an agent aims at)
+go into `invariant.json`, so a team shares them. Tokens go into
+`.invariant/integrations.local.json`, `0600` and git-ignored, and never leave
+the daemon. An action an integration does not enable is not shown at all — with
+no GitLab token, the review footer is simply *Plan changes*. See
+[docs/spec-integrations.md](docs/spec-integrations.md).
+
 ### 7. `invariant ui` — see and manage your sessions
 
-Opens a local dashboard for this project: a session board grouped by status,
-rendered markdown, a rich editor, review triage, package management, and a
-command palette.
+Opens a local dashboard: a session list, rendered markdown, a rich editor, review
+triage, package management, 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
+invariant ui status       # the daemon, and the projects it serves
+invariant ui stop         # stop it
+```
+
+**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
+all. Switching is a URL change (`/p/<project>/sessions`), so back, forward,
+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 add [path] # register one (defaults to the current folder)
+invariant projects remove     # forget one — its files are left alone
 ```
 
-Each directory gets its own instance on its own port, so several repositories can
-be open at once without ever mixing sessions.
+The list lives in `~/.invariant/projects.json`.
 
 ### Full walkthrough
 
@@ -558,24 +586,30 @@ See [docs/spec-review.md](docs/spec-review.md) for the document format.
 
 ### `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.
+Start — or attach to — the one local UI server on this machine, then open a
+browser on the project you ran it from. The default port is 4200 and the next
+free port is used when it is taken.
+
+There is exactly one server. Running `invariant ui` again, here or in another
+repository, attaches to it rather than racing a second one onto another port;
+asking for a different port while it runs is refused rather than silently
+ignored. A folder with no `invariant.json` is fine too — the server opens on the
+project list instead.
 
 ```bash
-invariant ui                    # start and open a browser
-invariant ui 4300               # ask for a specific port (fails if it is busy)
+invariant ui                    # start or attach, and open this project
+invariant ui 4300               # ask for a specific port (refused if one is already running)
 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 status --json      # machine-readable status
+invariant ui stop               # stop the server
 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`) |
+| `stop` | Stop the server |
+| `status` | The server and its projects, liveness-checked (`--json`) |
 | `migrate-headers` | Give legacy session files a canonical `<session-meta>` header |
 
 | Option | Description |
@@ -584,19 +618,35 @@ invariant ui migrate-headers    # add <session-meta> headers to legacy sessions
 | `--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.
+token kept in `~/.invariant/ui.json` (mode 0600). Every request names the project
+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 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
+```
+
+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.
 
-In the UI: `⌘K` opens the command palette, `⇧⌘V` toggles rendered preview and
-editing, `N` starts a session, `?` lists every shortcut. On a review session,
+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,
 `j`/`k` move between comments and `s` / `d` / `e` stage, discard, or edit one.
 
 #### The Packages page
 
 The **Packages** section of the UI is a view over the package commands — it runs
 the same `invariant install`, `add`, `remove`, `uninstall` and `sync` you would
-type, in the directory the UI was started in, and shows you the command before it
-runs. It never writes `invariant.json` itself.
+type, in the folder of the project you are currently in, and shows you the
+command before it runs. It never writes `invariant.json` itself.
 
 - **The tree is `invariant inspect`.** Selecting a package lists everything it
   ships, grouped by type, with the active items ticked.
@@ -620,7 +670,7 @@ runs. It never writes `invariant.json` itself.
 
 A change made in a terminal shows up in an open page within a couple of seconds.
 
-To work on the UI itself: start a daemon (`invariant ui --no-open`), then run
+To work on the UI itself: start the server (`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.