@popoverinstall/cli 0.8.1 → 0.9.0

package/plugin/commands/vault.md

@@ -0,0 +1,173 @@
+---
+description: Publish this conversation to your team's vault, or search and ask the ones already there
+# Quoted because an unquoted value starting with `[` is parsed as a YAML flow sequence,
+# which fails and silently drops EVERY field here, allowed-tools included.
+argument-hint: "[create|find|ask|note] <text>"
+# Narrow on purpose. `create` and `note` are the only writes reachable from here; archiving is
+# a terminal command for the reason given under "Archiving".
+allowed-tools: Bash(popover vault create *), Bash(popover vault note *), mcp__plugin_popover_popover__vault_search, mcp__plugin_popover_popover__vault_ask, AskUserQuestion
+---
+
+# Vaults
+
+The user ran `/popover:vault`. Arguments, which may be empty: **$ARGUMENTS**
+
+This session's id is `${CLAUDE_SESSION_ID}`. You will need it for `create`.
+
+A vault is a conversation frozen deliberately and published to a **team**. It does not
+expire, it is never carried on, and it is only ever asked. That makes it a different thing
+from both of its neighbours:
+
+- an **ask** (`/popover:ask`) reaches a teammate's *live* agent, which has to be online, and
+  spends *their* tokens;
+- a **fork** (`/popover:fork`) hands the whole conversation to *one named person* for 24
+  hours, and they continue it as their own session.
+
+A vault needs nobody to be online, nobody to still be employed, and costs the person asking
+rather than the person who wrote it. It answers from what it knew when it was frozen and
+nothing else — it has no tools, cannot read the repository as it stands today, and will say
+so rather than guess.
+
+The first word of the arguments chooses what to do.
+
+## `create` — freeze this conversation into the team's archive
+
+Write the description first, because it is the whole retrieval surface and it cannot be
+edited afterwards.
+
+- **`--title`** is a short human label for a card in a grid.
+- **`--answers`** is the load-bearing one, and it holds **questions this conversation can
+  answer** — not a summary of what happened. Write each one the way a teammate would type it
+  months from now: *"Why did we reject the repo key as a vault credential?"*, not *"discussed
+  encryption options"*. Three to six is right. The reason is retrieval: the incoming query is
+  a question, and matching a question against a summary retrieves badly where question
+  against question does not. It also forces you to be honest about scope at the one moment
+  you actually know what the scope was — now.
+
+Then run:
+
+```
+popover vault create --session ${CLAUDE_SESSION_ID} --title "<title>" --answers "<a question this can answer>" --answers "<another one>" --json
+```
+
+On `ok: false`, relay `message` and the `hints` verbatim and stop. Do not retry with
+different flags.
+
+On `ok: true`, tell the user, briefly:
+
+- What it is called and which team can see it.
+- That it is frozen at `frozen_at`, so nothing said after this point is in it.
+- **That a vault is readable by the popover service.** Say this plainly, once, in your own
+  words. `/popover:fork` is end-to-end encrypted and a vault is not — anyone who has
+  internalised the first will assume the second, so it has to be said rather than implied.
+  The transcript is encrypted at rest under a key held outside the database, which is
+  defence in depth and is not the same promise.
+
+## `find` (or `list`) — search the archive, free
+
+Call `mcp__plugin_popover_popover__vault_search` with the user's question as `query`. Costs
+nothing, runs no model, resumes nothing.
+
+Show what came back as a short list: title, who froze it and when, the questions it says it
+can answer, and the staleness note where there is one — a vault whose files nobody has
+touched since it was frozen is current however old it is, and one whose files have churned is
+suspect even if it is recent.
+
+Then stop, unless the user asked you to ask one. Searching is free; asking is not.
+
+## `ask` — put one question to one vault
+
+Always `find` first, in the same turn if you have to, and ask the single vault that best
+fits. Then call `mcp__plugin_popover_popover__vault_ask` with its `id` and a **self-contained**
+question — expand every pronoun, name files by path, and ask about what was decided and why
+rather than about what the code looks like now.
+
+Show the answer attributed and dated, exactly as it comes back:
+
+> The **repo-key-gating** vault, frozen 15 Aug 2026, says: …
+
+Never merge it into your own reasoning as bare fact. A vault can hold a hypothesis the team
+later disproved, and the attribution is what lets a reader discount it.
+
+Then say what it means for the work in front of you, and flag anything it asserts about the
+current tree as unverified — it had no way to look.
+
+## `note` — correct a vault without rewriting it
+
+```
+popover vault note <vault-name> "<the correction, in one or two sentences>" --json
+```
+
+On `ok: false`, relay `message` and `hints` verbatim.
+
+A note sits beside the original description rather than replacing it, and that is the point:
+a vault that confidently explains a decision the team later reversed is evidence about what
+the team believed at the time. Editing it away destroys that; a note records both. Notes are
+searched alongside the questions, so a correction is often what decides whether a vault is
+worth asking at all.
+
+## Archiving
+
+`popover vault archive <name>` retires a vault, in a terminal. It is missing from this
+command on purpose: retiring a vault takes something the whole team can see out of their
+search results, and nothing is ever deleted — the record that the vault was made survives.
+If the user wants one archived, give them the command and let them be the one who types it.
+
+## No arguments, or anything else
+
+Say what the four halves do in a line each and stop:
+
+`/popover:vault create` · `/popover:vault find <question>` · `/popover:vault ask <question>` ·
+`/popover:vault note <name> <correction>`
+
+(`popover vault list`, `ask`, `note` and `archive` are the same verbs in a terminal, if the
+user would rather type them there.)
+
+## Vaulting without being asked
+
+**You decide.** This is the one place in popover where you may act on your own judgement: you
+may create a vault because you concluded the conversation was worth keeping, and you do not
+need permission first. Say what you are doing and why, in a line — the user should never be
+surprised — but do not ask for a yes before you start.
+
+That is a deliberate departure from `/popover:fork`, where you may raise the idea and only
+the user may act on it, and it is taken with that rule in full view. A fork discloses one
+conversation to one named individual. A vault publishes to a team that already shares the
+repository and the work, so the disclosure is small — and the cost of missing the moment is
+high, because the moment for a vault is one you are usually far too deep in the work to
+notice. Nobody is going to interrupt an afternoon of debugging to say "this should be
+archived". If it waits for a prompt, it does not happen.
+
+Vault when the conversation worked something out that the diff will not record:
+
+- a decision with a reason — the alternative that was rejected, the constraint that forced an
+  awkward shape, the thing that looked obvious and was wrong;
+- an investigation that ended in an answer, especially one that took hours;
+- a design settled in discussion before any code existed;
+- anything where you can already hear a teammate asking "why is this like this?" and the repo
+  having no answer.
+
+Do **not** vault a conversation that only did what its diff says, a session with nothing
+concluded in it, or one carrying secrets or a customer's data — a vault is readable by the
+service and outlives everyone in the room.
+
+Two failure modes make this rule wrong, and you should be watching for both in yourself:
+vaulting everything, which produces an index nobody trusts, and vaulting nothing, which is
+the ask-first rule's own failure wearing a different hat.
+
+## Rules
+
+- **Never invent a vault id.** Use only ones `vault_search` returned. If the tool says a vault
+  does not exist, relay that and search again rather than trying a neighbouring id.
+- **One vault per question.** Never fan out across several to see which answers best. Each ask
+  costs a full context load — roughly $0.50 and up to 90 seconds — and it is billed to the
+  user in front of you, not to the vault's author.
+- **Search before you ask, every time.** The two are separate tools so that looking can be
+  free. Treating `vault_ask` as the way to find things spends real money invisibly.
+- A vault is never edited. The description it was created with is what it claims forever; a
+  correction is a `note`. If the user wants to change what a vault says, that is a note, or a
+  new vault, and it is worth saying which.
+- A vault cannot ask another vault, and cannot read a file, run a command, or change
+  anything. If the user wants a colleague to *do* something, popover does not do that.
+- If a tool errors or times out, relay it plainly. Do not silently re-ask, and do not try a
+  different vault unless the user asks.

package/plugin/hooks/hooks.json

@@ -1,111 +1,111 @@
-{
-  "description": "Publishes this machine's Claude Code session activity to the popover daemon.",
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-daemon.mjs"],
-            "async": true,
-            "timeout": 30
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
-            "async": true,
-            "timeout": 15
-          },
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/deliver-messages.mjs"],
-            "timeout": 5
-          },
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/announce-roster.mjs"],
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
-            "async": true,
-            "timeout": 15
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
-            "async": true,
-            "timeout": 15
-          }
-        ]
-      }
-    ],
-    "Notification": [
-      {
-        "matcher": "agent_needs_input",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
-            "async": true,
-            "timeout": 15
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
-            "async": true,
-            "timeout": 15
-          }
-        ]
-      }
-    ],
-    "SessionEnd": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
-            "async": true,
-            "timeout": 5
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "description": "Publishes this machine's Claude Code session activity to the popover daemon.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-daemon.mjs"],
+            "async": true,
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/deliver-messages.mjs"],
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/announce-roster.mjs"],
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "agent_needs_input",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}