@popoverinstall/cli 0.8.1 → 0.9.0

package/README.md

@@ -1,141 +1,142 @@
-# popover
-
-**Ask your teammates' agents, not your teammates.**
-
-When a teammate's agent has already worked out why the retry logic lives where it does, you
-should be able to ask it — without interrupting your teammate. popover shows you everyone's
-running Claude Code agents in the repo you are working in, and answers from a read-only fork
-of the agent's full accumulated context.
-
-Full documentation: **[popover.to/docs](https://www.popover.to/docs)**.
-
-## Install
-
-```bash
-npm install -g @popoverinstall/cli && popover welcome
-```
-
-Requires **Node.js 20+** and **Claude Code 2.1.229+**. The same two commands on macOS, Linux
-and Windows.
-
-`npm install -g` only places files. `popover welcome` is the rest of a first run: it registers
-the Claude Code plugin, records where the daemon lives, and offers to connect this machine. It
-prints a short code to confirm in your browser; the device token it stores is generated locally
-and never transmitted.
-
-Both halves are available on their own — `popover setup` for the wiring, `popover login` for the
-connection — and `welcome` is re-runnable, so it is also the way back if either needs redoing.
-
-## Use
-
-Inside Claude Code, `/popover:team` prints the roster: every agent your team is running in the
-repo you are in, and what each one is doing right now. Each gets a short handle.
-
-```
-*You*
-  A1  ad pipeline    idle 34m             — Wiring Kling into the ad pipeline
-  A2  popover        editing main.py      — Team agent communication
-
-*Bob Chen*
-  B1  api-server     reading config.json  — Fixing OAuth token refresh
-  B2  api-server     creating plan.md     — Postgres connection pooling
-```
-
-Three things to do with one:
-
-```
-/popover:ask B1 why did you rule out redis?
-/popover:tell B1 the migration is applied on prod
-/popover:fork create
-```
-
-**Ask** is answered by a read-only fork of that agent, running on its owner's machine. Their
-session is never interrupted and their source never leaves their laptop — only the answer
-does. The fork has no tools, so a question about something the agent never looked at gets
-"I don't know" rather than an investigation, and the answer is billed to their account.
-
-**Tell** drops a heads-up into a running agent's context before its next prompt. No answer
-comes back. It is for facts that would otherwise cause a collision, and it is the one thing
-here that reaches a live session: the database caps a sender at ten messages an hour to any
-one recipient, and the recipient's human is always notified.
-
-**Fork** hands over the whole conversation. `/popover:fork create` returns a code that works
-for 24 hours; whoever you send it to runs `popover fork open <code>` and carries on in their
-own local chat. Opening one needs no popover account — `npx @popoverinstall/cli fork open
-<code>` is enough.
-
-Claude Code namespaces plugin commands, so it is `/popover:team`, not `/team`.
-
-## Who can see what
-
-Agents are only visible to each other **inside the same repo**, so the directory you run from
-is what scopes the roster. Repos are identified by their git remotes, so two clones match
-however they were cloned; a directory with no shared remote is private to you. The boundary is
-enforced by row-level security in Postgres, not by the client.
-
-## Commands
-
-```
-popover welcome                 Set up and log in — the whole of a first run
-popover login / logout          Connect this machine, or forget its credentials
-popover setup                   Re-register the Claude Code plugin
-popover status                  This machine's sessions and connection
-popover team                    Print the roster for the repo you are in
-popover fork <create|open|launch|list|revoke>
-popover log                     Questions and messages your agents received
-popover changelog [--all]       What the last update changed
-popover update                  Upgrade and restart the daemon
-popover doctor                  Diagnose setup problems
-popover daemon <start|stop|restart|status|logs>
-popover uninstall               Stop the daemon, unhook Claude Code
-```
-
-Asking and telling are not in that list on purpose: they live in the session, where the agent
-doing them has the context to write a question worth answering and to do something with the
-answer.
-
-## How it works
-
-Three pieces install together:
-
-- **the CLI** — the `popover` command
-- **the daemon** — a detached background process that publishes this machine's sessions and
-  answers teammates' questions. It stores state in `~/.popover/`.
-- **the Claude Code plugin** — provides `/popover:team`, `/popover:fork`, and the MCP tools
-  agents use to reach each other. Registered by `popover setup`.
-
-## What leaves your machine
-
-- An **ask** exports one answer. A teammate can learn whatever is already in that agent's
-  context, including the contents of files it read earlier in the session — that is what it
-  answers from. Every ask is logged with its cost.
-- A **fork** exports the entire conversation: every message, every tool result, the contents
-  of every file read into it. It is sealed before it leaves, with a key derived from the code,
-  so the server holds something it cannot read — but anyone holding the code can open it.
-  Treat it the way you would treat pasting the transcript into a chat window.
-- The device token is generated here and never transmitted; the server only ever sees its
-  SHA-256.
-
-## Troubleshooting
-
-`popover doctor` diagnoses setup problems in root-cause order and is the right first move for
-most things. `popover status` says whether this machine is connected; `popover daemon logs` is
-the detail underneath. A teammate missing from the roster is usually running a version too old
-to publish a repo identity — the roster counts them and says so.
-
-## Uninstall
-
-```bash
-popover uninstall          # stop the daemon, unhook Claude Code
-npm uninstall -g @popoverinstall/cli
-```
-
-Credentials and logs are left in `~/.popover/`; delete the directory to remove those too.
-
-## Links
-
-- [Documentation](https://www.popover.to/docs)
-- [Changelog](https://www.popover.to/changelog)
-- [popover.to](https://www.popover.to) — dashboard, team and activity
-
-MIT · Quo Labs, Inc.
+# popover
+
+**Ask your teammates' agents, not your teammates.**
+
+When a teammate's agent has already worked out why the retry logic lives where it does, you
+should be able to ask it — without interrupting your teammate. popover shows you everyone's
+running Claude Code agents in the repo you are working in, and answers from a read-only fork
+of the agent's full accumulated context.
+
+Full documentation: **[popover.to/docs](https://www.popover.to/docs)**.
+
+## Install
+
+```bash
+npm install -g @popoverinstall/cli && popover welcome
+```
+
+Requires **Node.js 20+** and **Claude Code 2.1.229+**. The same two commands on macOS, Linux
+and Windows.
+
+`npm install -g` only places files. `popover welcome` is the rest of a first run: it registers
+the Claude Code plugin, records where the daemon lives, and offers to connect this machine. It
+prints a short code to confirm in your browser; the device token it stores is generated locally
+and never transmitted.
+
+Both halves are available on their own — `popover setup` for the wiring, `popover login` for the
+connection — and `welcome` is re-runnable, so it is also the way back if either needs redoing.
+
+## Use
+
+Inside Claude Code, `/popover:team` prints the roster: every agent your team is running in the
+repo you are in, and what each one is doing right now. Each gets a short handle.
+
+```
+*You*
+  A1  ad pipeline    idle 34m             — Wiring Kling into the ad pipeline
+  A2  popover        editing main.py      — Team agent communication
+
+*Bob Chen*
+  B1  api-server     reading config.json  — Fixing OAuth token refresh
+  B2  api-server     creating plan.md     — Postgres connection pooling
+```
+
+Three things to do with one:
+
+```
+/popover:ask B1 why did you rule out redis?
+/popover:tell B1 the migration is applied on prod
+/popover:fork create
+```
+
+**Ask** is answered by a read-only fork of that agent, running on its owner's machine. Their
+session is never interrupted and their source never leaves their laptop — only the answer
+does. The fork has no tools, so a question about something the agent never looked at gets
+"I don't know" rather than an investigation, and the answer is billed to their account.
+
+**Tell** drops a heads-up into a running agent's context before its next prompt. No answer
+comes back. It is for facts that would otherwise cause a collision, and it is the one thing
+here that reaches a live session: the database caps a sender at ten messages an hour to any
+one recipient, and the recipient's human is always notified.
+
+**Fork** hands over the whole conversation. `/popover:fork create` returns a code that works
+for 24 hours; whoever you send it to runs `popover fork open <code>` and carries on in their
+own local chat. Opening one needs no popover account — `npx @popoverinstall/cli fork open
+<code>` is enough.
+
+Claude Code namespaces plugin commands, so it is `/popover:team`, not `/team`.
+
+## Who can see what
+
+Agents are only visible to each other **inside the same repo**, so the directory you run from
+is what scopes the roster. Repos are identified by their git remotes, so two clones match
+however they were cloned; a directory with no shared remote is private to you. The boundary is
+enforced by row-level security in Postgres, not by the client.
+
+## Commands
+
+```
+popover welcome                 Set up and log in — the whole of a first run
+popover login / logout          Connect this machine, or forget its credentials
+popover setup                   Re-register the Claude Code plugin
+popover status                  This machine's sessions and connection
+popover team                    Print the roster for the repo you are in
+popover rename <who> [name]     Name one of your own agents, or clear its name
+popover fork <create|open|launch|list|revoke>
+popover log                     Questions and messages your agents received
+popover changelog [--all]       What the last update changed
+popover update                  Upgrade and restart the daemon
+popover doctor                  Diagnose setup problems
+popover daemon <start|stop|restart|status|logs>
+popover uninstall               Stop the daemon, unhook Claude Code
+```
+
+Asking and telling are not in that list on purpose: they live in the session, where the agent
+doing them has the context to write a question worth answering and to do something with the
+answer.
+
+## How it works
+
+Three pieces install together:
+
+- **the CLI** — the `popover` command
+- **the daemon** — a detached background process that publishes this machine's sessions and
+  answers teammates' questions. It stores state in `~/.popover/`.
+- **the Claude Code plugin** — provides `/popover:team`, `/popover:fork`, and the MCP tools
+  agents use to reach each other. Registered by `popover setup`.
+
+## What leaves your machine
+
+- An **ask** exports one answer. A teammate can learn whatever is already in that agent's
+  context, including the contents of files it read earlier in the session — that is what it
+  answers from. Every ask is logged with its cost.
+- A **fork** exports the entire conversation: every message, every tool result, the contents
+  of every file read into it. It is sealed before it leaves, with a key derived from the code,
+  so the server holds something it cannot read — but anyone holding the code can open it.
+  Treat it the way you would treat pasting the transcript into a chat window.
+- The device token is generated here and never transmitted; the server only ever sees its
+  SHA-256.
+
+## Troubleshooting
+
+`popover doctor` diagnoses setup problems in root-cause order and is the right first move for
+most things. `popover status` says whether this machine is connected; `popover daemon logs` is
+the detail underneath. A teammate missing from the roster is usually running a version too old
+to publish a repo identity — the roster counts them and says so.
+
+## Uninstall
+
+```bash
+popover uninstall          # stop the daemon, unhook Claude Code
+npm uninstall -g @popoverinstall/cli
+```
+
+Credentials and logs are left in `~/.popover/`; delete the directory to remove those too.
+
+## Links
+
+- [Documentation](https://www.popover.to/docs)
+- [Changelog](https://www.popover.to/changelog)
+- [popover.to](https://www.popover.to) — dashboard, team and activity
+
+MIT · Quo Labs, Inc.

package/dist/config-command.d.ts

@@ -0,0 +1,2 @@
+export declare function configCommand(args: string[]): number;
+//# sourceMappingURL=config-command.d.ts.map

package/dist/config-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-command.d.ts","sourceRoot":"","sources":["../src/config-command.ts"],"names":[],"mappings":"AAmDA,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAqDpD"}

package/dist/config-command.js

@@ -0,0 +1,80 @@
+import { DEFAULT_CONFIG, WorkspaceScanSchema, configPath, loadConfig, saveConfig, } from "@popoverinstall/shared";
+import { bad, c, dim, info, ok } from "./ui.js";
+const SETTINGS = [
+    {
+        name: "workspace-scan",
+        key: "workspaceScan",
+        describe: "Whether a directory that is not itself a repo, but contains repos, publishes them",
+        values: WorkspaceScanSchema.options,
+        validate: (raw) => WorkspaceScanSchema.safeParse(raw).success,
+        effect: (value) => value === "children"
+            ? "An agent in a folder above several repos is visible to teammates in each of them."
+            : "An agent in a folder that is not itself a repo is private to you again.",
+    },
+];
+export function configCommand(args) {
+    const [name, value] = args;
+    if (!name || name === "--help" || name === "-h" || name === "help") {
+        return list();
+    }
+    const setting = SETTINGS.find((s) => s.name === name);
+    if (!setting) {
+        bad(`No setting called \`${name}\`.`);
+        dim(`Known settings: ${SETTINGS.map((s) => s.name).join(", ")}`);
+        return 1;
+    }
+    // No value: report this one rather than assuming the user meant to clear it. A settings
+    // command where `config foo` unsets `foo` is a settings command that loses data to a
+    // typo.
+    if (value === undefined) {
+        const current = loadConfig()[setting.key];
+        info(`${c.bold(setting.name)}  ${current}`);
+        dim(`${setting.describe}.`);
+        dim(`Values: ${setting.values.join(", ")} (default ${DEFAULT_CONFIG[setting.key]})`);
+        return 0;
+    }
+    if (!setting.validate(value)) {
+        bad(`\`${value}\` is not a valid ${setting.name}.`);
+        dim(`Values: ${setting.values.join(", ")}`);
+        return 1;
+    }
+    const before = loadConfig()[setting.key];
+    if (before === value) {
+        // Said plainly rather than reported as a change, because "it was already that" and "I
+        // just changed it" should not read identically when someone is checking their work.
+        ok(`${setting.name} is already ${value}.`);
+        return 0;
+    }
+    try {
+        saveConfig({ [setting.key]: value });
+    }
+    catch (err) {
+        bad(`Could not write ${configPath()}.`);
+        dim(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    ok(`${setting.name}: ${before} → ${value}`);
+    dim(setting.effect(value));
+    // The daemon re-reads this file rather than caching it, which is what makes the promise
+    // below true. See `loadConfig` for why it is deliberately not memoized.
+    dim("The daemon picks this up within a minute; no restart needed.");
+    return 0;
+}
+function list() {
+    const current = loadConfig();
+    console.log(`
+${c.bold("popover config")} — settings for this machine
+
+  ${c.dim(configPath())}
+`);
+    for (const setting of SETTINGS) {
+        info(`${c.bold(setting.name.padEnd(16))} ${current[setting.key]}`);
+        dim(`${setting.describe}.`);
+        dim(`Values: ${setting.values.join(", ")} (default ${DEFAULT_CONFIG[setting.key]})`);
+        console.log();
+    }
+    dim("popover config <setting>          show one");
+    dim("popover config <setting> <value>  change it");
+    return 0;
+}
+//# sourceMappingURL=config-command.js.map

package/dist/config-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-command.js","sourceRoot":"","sources":["../src/config-command.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,UAAU,EACV,UAAU,EACV,UAAU,GACX,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AA6BhD,MAAM,QAAQ,GAAuB;IACnC;QACE,IAAI,EAAE,gBAAgB;QACtB,GAAG,EAAE,eAAe;QACpB,QAAQ,EACN,mFAAmF;QACrF,MAAM,EAAE,mBAAmB,CAAC,OAAO;QACnC,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,mBAAmB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,OAAO;QAC7D,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAChB,KAAK,KAAK,UAAU;YAClB,CAAC,CAAC,mFAAmF;YACrF,CAAC,CAAC,yEAAyE;KAChF;CACF,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC;IAE3B,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACnE,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACtD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,GAAG,CAAC,uBAAuB,IAAI,KAAK,CAAC,CAAC;QACtC,GAAG,CAAC,mBAAmB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,wFAAwF;IACxF,qFAAqF;IACrF,QAAQ;IACR,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QAC5C,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QAC5B,GAAG,CAAC,WAAW,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,KAAK,KAAK,qBAAqB,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC;QACpD,GAAG,CAAC,WAAW,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC5C,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,sFAAsF;QACtF,oFAAoF;QACpF,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,eAAe,KAAK,GAAG,CAAC,CAAC;QAC3C,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,CAAC;QACH,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,EAAsC,CAAC,CAAC;IAC3E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,mBAAmB,UAAU,EAAE,GAAG,CAAC,CAAC;QACxC,GAAG,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACtD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,KAAK,MAAM,MAAM,KAAK,EAAE,CAAC,CAAC;IAC5C,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3B,wFAAwF;IACxF,wEAAwE;IACxE,GAAG,CAAC,8DAA8D,CAAC,CAAC;IACpE,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,IAAI;IACX,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,OAAO,CAAC,GAAG,CAAC;EACZ,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC;;IAEtB,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;CACtB,CAAC,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnE,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QAC5B,GAAG,CAAC,WAAW,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrF,OAAO,CAAC,GAAG,EAAE,CAAC;IAChB,CAAC;IACD,GAAG,CAAC,4CAA4C,CAAC,CAAC;IAClD,GAAG,CAAC,6CAA6C,CAAC,CAAC;IACnD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/cursor-hooks.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Add popover's Cursor hooks to `~/.cursor/hooks.json`, without touching anything already
+ * there.
+ *
+ * Unlike Claude Code's plugin-scoped hook file, `~/.cursor/hooks.json` is one file shared
+ * by every tool a user has configured Cursor hooks for — so this always reads the existing
+ * file, appends only popover's own entries (skipping any it already added, so re-running
+ * `setup`/`update` is idempotent), and never removes or replaces anything else in it.
+ *
+ * Whether Cursor actually *runs* every entry in a multi-entry event array, as opposed to
+ * only the first, is not yet confirmed — see the note above `setup()`. This writes the
+ * structurally-correct merge regardless; that question only affects whether Cursor honors
+ * it, not whether this code is right to write it this way.
+ *
+ * A no-op, not an error, if Cursor isn't installed on this machine (no `~/.cursor`).
+ */
+export declare function installCursorHooks(): number;
+//# sourceMappingURL=cursor-hooks.d.ts.map

package/dist/cursor-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-hooks.d.ts","sourceRoot":"","sources":["../src/cursor-hooks.ts"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAmD3C"}

package/dist/cursor-hooks.js

@@ -0,0 +1,105 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { bad, dim, info, ok } from "./ui.js";
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Which Cursor hook event runs which of our scripts.
+ *
+ * A single source of truth kept in code rather than a template JSON file: unlike Claude
+ * Code's `${CLAUDE_PLUGIN_ROOT}`-templated `hooks/hooks.json`, Cursor's hook config has no
+ * confirmed placeholder-substitution mechanism of its own, so *we* have to resolve the
+ * scripts' absolute path and merge it in ourselves — a JS map does that more directly than
+ * a JSON file that would still need string substitution before use.
+ *
+ * `stop` carries two entries deliberately: detection (status) and tell delivery
+ * (followup_message), confirmed as the right event for both empirically — see the plan.
+ */
+const EVENT_SCRIPTS = {
+    sessionStart: ["ensure-daemon.mjs"],
+    beforeSubmitPrompt: ["cursor-emit-event.mjs"],
+    preToolUse: ["cursor-emit-event.mjs"],
+    postToolUse: ["cursor-emit-event.mjs"],
+    stop: ["cursor-emit-event.mjs", "cursor-deliver-messages.mjs"],
+    sessionEnd: ["cursor-emit-event.mjs"],
+};
+function cursorHooksPath() {
+    return path.join(os.homedir(), ".cursor", "hooks.json");
+}
+/**
+ * The directory holding the plugin's `scripts/`, resolved the same way
+ * `resolveMarketplaceRoot` in setup.ts finds the plugin root — published layout first,
+ * dev-checkout fallback second.
+ */
+function resolveScriptsDir() {
+    const candidates = [
+        path.join(HERE, "..", "plugin", "scripts"), // <pkg>/plugin/scripts — published layout
+        path.join(HERE, "..", "..", "..", "plugin", "scripts"), // repo root — dev checkout
+    ];
+    return candidates.find((d) => existsSync(d)) ?? null;
+}
+/**
+ * Add popover's Cursor hooks to `~/.cursor/hooks.json`, without touching anything already
+ * there.
+ *
+ * Unlike Claude Code's plugin-scoped hook file, `~/.cursor/hooks.json` is one file shared
+ * by every tool a user has configured Cursor hooks for — so this always reads the existing
+ * file, appends only popover's own entries (skipping any it already added, so re-running
+ * `setup`/`update` is idempotent), and never removes or replaces anything else in it.
+ *
+ * Whether Cursor actually *runs* every entry in a multi-entry event array, as opposed to
+ * only the first, is not yet confirmed — see the note above `setup()`. This writes the
+ * structurally-correct merge regardless; that question only affects whether Cursor honors
+ * it, not whether this code is right to write it this way.
+ *
+ * A no-op, not an error, if Cursor isn't installed on this machine (no `~/.cursor`).
+ */
+export function installCursorHooks() {
+    const cursorHome = path.join(os.homedir(), ".cursor");
+    if (!existsSync(cursorHome)) {
+        dim("Cursor not found on this machine; skipping its hooks.");
+        return 0;
+    }
+    const scriptsDir = resolveScriptsDir();
+    if (!scriptsDir) {
+        bad("Could not find the bundled Cursor hook scripts.");
+        dim("This install looks incomplete — reinstall with: npm install -g @popoverinstall/cli");
+        return 1;
+    }
+    const file = cursorHooksPath();
+    let config = { version: 1, hooks: {} };
+    if (existsSync(file)) {
+        try {
+            config = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch (err) {
+            bad(`Could not parse ${file} — leaving it untouched.`);
+            dim(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
+    }
+    config.hooks ??= {};
+    config.version ??= 1;
+    let added = 0;
+    for (const [event, scripts] of Object.entries(EVENT_SCRIPTS)) {
+        const existing = (config.hooks[event] ??= []);
+        for (const script of scripts) {
+            const command = `node "${path.join(scriptsDir, script)}"`;
+            const alreadyPresent = existing.some((h) => typeof h === "object" && h !== null && h.command === command);
+            if (alreadyPresent)
+                continue;
+            existing.push({ command, timeout: script === "ensure-daemon.mjs" ? 30 : 5 });
+            added += 1;
+        }
+    }
+    if (added === 0) {
+        ok("Cursor hooks already installed.");
+        return 0;
+    }
+    mkdirSync(cursorHome, { recursive: true });
+    writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    info(`Added ${added} Cursor hook${added === 1 ? "" : "s"} to ${file}.`);
+    return 0;
+}
+//# sourceMappingURL=cursor-hooks.js.map

package/dist/cursor-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-hooks.js","sourceRoot":"","sources":["../src/cursor-hooks.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAsCA;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAE,MAEb,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAyCA;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAE,MAEb,CAAC"}

package/dist/index.js

@@ -12,9 +12,12 @@ import { execTool } from "./exec.js";
 import { askDaemon, daemonIsRunning } from "./ipc-client.js";
 import { login } from "./login.js";
 import { rename } from "./rename.js";
+import { reposCommand } from "./repos.js";
+import { configCommand } from "./config-command.js";
 import { setup } from "./setup.js";
 import { forkCommand } from "./snapshot.js";
 import { bad, c, dim, info, ok, warn } from "./ui.js";
+import { vaultCommand } from "./vaults.js";
 import { welcome } from "./welcome.js";
 /**
  * This package's own version, read from the manifest npm installed beside us.
@@ -55,10 +58,25 @@ async function main() {
             return team();
         case "rename":
             return rename(rest);
+        // Deliberately takes no repo argument at any depth: which repo it means comes from the
+        // working directory, because registering one is a claim of possession rather than a
+        // name. See packages/cli/src/repos.ts.
+        case "repos":
+            return reposCommand(rest);
+        // Machine-local settings, not team ones. The only key today changes who can see an
+        // agent, so it needs a way to be read and turned off that is not hand-editing JSON.
+        case "config":
+            return configCommand(rest);
         case "daemon":
             return daemonCommand(rest[0] ?? "status");
         case "fork":
             return forkCommand(rest);
+        // A vault is the other half of `fork`, and the difference is worth knowing before you
+        // reach for either: a fork goes to one named person, expires in a day, and is carried on
+        // as their own session; a vault is published to a team, never expires, is never carried
+        // on, and is readable by the service. See packages/cli/src/vaults.ts and docs/vaults.md.
+        case "vault":
+            return vaultCommand(rest);
         case "log":
             return showLog(Number(flag(rest, "--lines") ?? 20));
         case "uninstall":
@@ -128,35 +146,38 @@ function gettingStarted() {
             ? `    ${c.green(marker)} ${c.dim(name)}${c.dim(what)}`
             : `    ${c.bold(marker)} ${c.bold(name)}${what}`;
     });
-    return `  ${c.bold("Finish installing")} — npm placed the files, these connect them:
-
-${lines.join("\n")}
-
-  ${c.dim("Then run")} ${c.cyan("/popover:team")} ${c.dim("inside Claude Code to see your teammates' agents.")}
+    return `  ${c.bold("Finish installing")} — npm placed the files, these connect them:
+
+${lines.join("\n")}
+
+  ${c.dim("Then run")} ${c.cyan("/popover:team")} ${c.dim("inside Claude Code to see your teammates' agents.")}
 `;
 }
 function usage() {
     const next = gettingStarted();
-    console.log(`
-${c.bold("popover")} — connect this machine, and see what your team's agents are doing
-${next ? `\n${next}` : ""}
-  Asking and telling happen inside a session, where the agent doing them has the
-  context to be worth reading: ${c.bold("/popover:ask B1 …")} and ${c.bold("/popover:tell B1 …")}
-
-  ${c.bold("popover login")} [--api URL]   Connect this machine to your team
-  ${c.bold("popover logout")}              Forget this machine's credentials
-  ${c.bold("popover setup")} [--force]     Re-register the Claude Code plugin
-  ${c.bold("popover welcome")}             Set up and log in — the whole of a first run
-  ${c.bold("popover update")}              Upgrade to the newest version and restart the daemon
-  ${c.bold("popover changelog")} [--all]   What the last update changed
-  ${c.bold("popover status")}              Show this machine's sessions and connection
-  ${c.bold("popover team")}                Print the team roster
-  ${c.bold("popover rename")} [handle]     Name an agent, so your team can tell them apart
-  ${c.bold("popover fork")} <create|open|launch|list|revoke>
-  ${c.bold("popover doctor")}              Diagnose setup problems
-  ${c.bold("popover daemon")} <start|stop|restart|status|logs>
-  ${c.bold("popover log")} [--lines N]     Recent questions and messages your agents received
-  ${c.bold("popover uninstall")}           Remove popover from this machine
+    console.log(`
+${c.bold("popover")} — connect this machine, and see what your team's agents are doing
+${next ? `\n${next}` : ""}
+  Asking and telling happen inside a session, where the agent doing them has the
+  context to be worth reading: ${c.bold("/popover:ask B1 …")} and ${c.bold("/popover:tell B1 …")}
+
+  ${c.bold("popover login")} [--api URL]   Connect this machine to your team
+  ${c.bold("popover logout")}              Forget this machine's credentials
+  ${c.bold("popover setup")} [--force]     Re-register the Claude Code plugin
+  ${c.bold("popover welcome")}             Set up and log in — the whole of a first run
+  ${c.bold("popover update")}              Upgrade to the newest version and restart the daemon
+  ${c.bold("popover changelog")} [--all]   What the last update changed
+  ${c.bold("popover status")}              Show this machine's sessions and connection
+  ${c.bold("popover team")}                Print the team roster
+  ${c.bold("popover rename")} [handle]     Name an agent, so your team can tell them apart
+  ${c.bold("popover repos")} <add|rm>      Which repos your team treats as one product
+  ${c.bold("popover config")} [key] [value] Settings for this machine
+  ${c.bold("popover fork")} <create|open|launch|list|revoke>
+  ${c.bold("popover vault")} <create|list|ask|note|archive>
+  ${c.bold("popover doctor")}              Diagnose setup problems
+  ${c.bold("popover daemon")} <start|stop|restart|status|logs>
+  ${c.bold("popover log")} [--lines N]     Recent questions and messages your agents received
+  ${c.bold("popover uninstall")}           Remove popover from this machine
 `);
 }
 /**