@invariant.guru/cli 0.6.8 → 0.7.0

package/README.md

@@ -46,7 +46,7 @@ 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.
+Packages come from a GitHub repository, from the [skills.sh](https://www.skills.sh) catalogue, or from the registry. Installing caches the package **and** activates its items.
 
 ```bash
 # From GitHub (owner/repo, optional #ref)
@@ -55,6 +55,12 @@ 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 skills.sh — the repository is cached, that one skill is activated
+invariant install skills:vercel-labs/skills/find-skills
+
+# …or the whole catalogue source, activating every skill it ships
+invariant install skills:anthropics/skills
+
 # From the registry (same package, published name)
 invariant install nest-clean-architecture
 ```
@@ -210,18 +216,29 @@ review*. The token is per project: see [docs/spec-review.md](docs/spec-review.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
 
@@ -259,11 +276,13 @@ invariant init --hybrid
 
 ### `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 GitHub, skills.sh or the registry 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 github:invariant-guru/inv-nest-clean-architecture
 invariant install github:invariant-guru/inv-nest-clean-architecture#v1.2.0
+invariant install skills:vercel-labs/skills/find-skills
+invariant install https://www.skills.sh/vercel-labs/skills/find-skills
 invariant install nest-clean-architecture
 invariant install nest-clean-architecture@1.0.0
 
@@ -282,6 +301,38 @@ Source syntax:
 | `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 |
+| `skills:owner/repo` | A skills.sh source, whole. Every skill it ships is cached and activated |
+| `skills:owner/repo/skill` | The same source, cached whole, with **only that skill** activated |
+| `https://www.skills.sh/owner/repo/skill` | The page URL, accepted as-is |
+
+#### Installing from skills.sh
+
+[skills.sh](https://www.skills.sh) indexes ~9,700 agent skills, all of them
+living in public GitHub repositories. Installing from it fetches **the
+repository**, because that is what a package is here — one source, many items —
+and then activates the one skill you asked for. `invariant add` turns the rest
+on later, without a second download.
+
+Two consequences worth knowing before the first install:
+
+- **The package is `@owner/repo`.** Half the catalogue's repositories are called
+  `skills`; the owner is what keeps `@vercel-labs/skills` and
+  `@anthropics/skills` apart.
+- **The skill lands under its package-prefixed name** — `find-skills` from
+  `vercel-labs/skills` installs to
+  `.agents/skills/vercel-labs-skills-find-skills`, mirrored into `.claude/`.
+  That is [ADR-024](docs/ADR.md) working as designed; see
+  [docs/package-naming.md](docs/package-naming.md).
+
+Skill folders are copied whole — `scripts/`, `references/`, licences and all.
+Binary files and anything over 256 KB are skipped and named in the output.
+Nothing is executed at install time.
+
+Two environment variables exist for testing and for self-hosted mirrors:
+`INVARIANT_SKILLS_API_URL` (default `https://www.skills.sh`) and
+`INVARIANT_SKILLS_DOWNLOAD_URL` (default `https://skills.sh`). `GITHUB_TOKEN` /
+`GH_TOKEN`, when set, is used for the repository metadata call that supplies
+star counts.
 
 | Option | Description |
 |--------|-------------|
@@ -518,24 +569,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 |
@@ -544,19 +601,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`.
 
-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,
+```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, `⌘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.
@@ -564,8 +637,15 @@ runs. It never writes `invariant.json` itself.
   like; the bar at the bottom shows what will run, and **Apply** issues one
   `remove` and one `add` for the whole batch. Optionally a `sync` after.
 - **Install** takes a GitHub repository (the default — `owner/repo`, or a pasted
-  URL, plus an optional ref) or a registry name, and previews the exact
-  `invariant install …` line including `--no-add` and `--sync`.
+  URL, plus an optional ref) or a skills.sh skill (search as you type, or paste
+  `owner/repo/skill`), and previews the exact `invariant install …` line
+  including `--no-add` and `--sync`.
+- **Browse skills** opens the catalogue at `/packages/skills`: ranked by
+  Popular / Trending / Hot, searchable, with a preview pane carrying the
+  install count, the weekly trend, the GitHub stars, the licence, the file list
+  and the rendered SKILL.md — plus the path the skill will actually occupy on
+  disk, before you install it. `/` focuses search, `j`/`k` move, `Esc` goes
+  back.
 - **Sync** runs from the top bar, with a **Check only** dry run that reports
   drift the way CI does.
 - **A package the config declares but this checkout never installed** shows as
@@ -573,7 +653,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.
 
@@ -722,18 +802,42 @@ After `init` + `install` + `sync`:
 │   │   └── .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
+│   ├── skills/<pkg>-<name>/SKILL.md
+│   ├── agents/<pkg>-<name>.md
+│   ├── commands/<pkg>-<name>.md
+│   └── rules/<pkg>-<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
+    ├── agents/<pkg>-<name>.md  ->  ../../.agents/agents/<pkg>-<name>.md
+    ├── skills/<pkg>-<name>     ->  ../../.agents/skills/<pkg>-<name>
+    ├── commands/<pkg>-<name>.md
+    └── rules/<pkg>-<name>.md
+```
+
+### Item names carry their package
+
+An item is stored under `<package-slug>-<item>`: the `frontend` skill of package
+`docs` lands at `.agents/skills/docs-frontend`, linked as
+`.claude/skills/docs-frontend`. Two packages can therefore ship a `frontend`
+skill without one clobbering the other, and removing one never touches the
+other's files.
+
+The name is a pure function of the package and the item — never of install order
+— so a package author can write the installed path by hand in an instruction;
+invariant does not rewrite content. An item already named `docs-frontend` inside
+package `docs` stays exactly that.
+
+You keep addressing items by their own name:
+
+```bash
+invariant add skill:docs/frontend      # installs .agents/skills/docs-frontend
+invariant remove skill:docs/frontend
+invariant inspect docs --paths         # prints the installed names and paths
 ```
 
+Full rules, including how the package name itself is resolved for GitHub
+installs: [docs/package-naming.md](docs/package-naming.md).
+
 ### One copy, many views
 
 `.agents/` holds the single physical copy of every activated item. What each
@@ -743,8 +847,8 @@ target gets depends on how it reads skills:
 |---|---|---|
 | `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` |
+| `cursor` | reads `.agents/skills/` — nothing written | `.cursor/rules/<pkg>-<name>.mdc` |
+| `copilot` | reads `.agents/skills/` — nothing written | `.github/instructions/<pkg>-<name>.instructions.md` |
 | `aider` | embedded in `CONVENTIONS.md` | embedded in `CONVENTIONS.md` |
 
 Two consequences worth knowing: