@popoverinstall/cli 0.8.1 → 0.9.0

package/plugin/commands/fork.md

@@ -1,119 +1,119 @@
----
-description: Share this conversation as a fork a teammate can carry on, or open one you were sent
-# 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|open] [code]"
-allowed-tools: Bash(popover fork *), AskUserQuestion
----
-
-# Fork this conversation
-
-The user ran `/popover:fork`. Arguments, which may be empty: **$ARGUMENTS**
-
-This session's id is `${CLAUDE_SESSION_ID}`. You will need it for `create`.
-
-A fork is not an ask. An ask sends a teammate's question to a read-only copy of someone's
-session and brings back one answer. A fork hands over **the whole conversation**, frozen at
-the moment it was made, and the person who opens it gets their own local chat that continues
-from there. Nothing they do in it comes back here.
-
-The first word of the arguments chooses what to do. Follow exactly one of these paths.
-
-## 1. `create` — freeze this conversation and get a code
-
-Run:
-
-```
-popover fork create --session ${CLAUDE_SESSION_ID} --json
-```
-
-On `ok: true`, show the user the code on its own line so it is easy to copy, then tell them,
-briefly and in this order:
-
-- Who it is for and how they open it: `popover fork open <code>`, or
-  `npx @popoverinstall/cli fork open <code>` if they do not have popover yet.
-- That the code stops working in 24 hours, but a chat someone has already opened does not —
-  it is theirs from then on.
-- That it is frozen at `last_turn_at`, so nothing said after this point is included. If they
-  keep working and want the newer state shared, they run `create` again for a new code.
-- That this sends the entire conversation, including the contents of every file read into
-  it. Say it plainly, once. It is a much larger disclosure than an ask and the user should
-  make it deliberately.
-
-On `ok: false`, relay `message` and the `hints` verbatim. Do not retry with different flags.
-
-## 2. `open <code>` — take delivery of a fork
-
-Run:
-
-```
-popover fork open <the code they typed> --json
-```
-
-On `ok: false`, relay `message` and `hints` and stop.
-
-On `ok: true`, tell them what arrived: who shared it, the title if there is one,
-`entry_count` messages, when it was frozen, and which repo it came from. Then surface
-whatever the output flags:
-
-- `repo_match: "different"` — say which repo it came from and which one they are in, and
-  that the conversation will refer to files they may not have.
-- `repo_match: "unknown"` — they are not in a git repository, so paths in it may not resolve.
-- `version_skew` — relay it as a note, not a blocker.
-- `claude_problem` — this one *is* a blocker. Relay it and stop.
-
-Then explain why this needs a window of its own, and offer the choice.
-
-**A fork cannot open inside this chat.** A running Claude Code session cannot become a
-different session — one chat holds one conversation, and this one already has its own. So
-the fork starts as a second session in a new window. If this conversation has real context
-in it already, say that plainly; if the user only just started here, one short line is
-enough.
-
-Then call `AskUserQuestion` with exactly these two options, so Esc cancels:
-
-- **Open a new window** — "Start the fork in its own terminal window"
-- **Print the command** — "Show the command and let me run it myself"
-
-If they choose to open a new window, run:
-
-```
-popover fork launch <stage_id> --json
-```
-
-Then report what happened: `opened: true` means a window is on its way, and it is worth
-adding that the fork may take a moment to appear. `opened: false` is not a failure — it
-happens over SSH, in a container, and anywhere there is no window to open — so show them
-`command` and the `cwd` to run it in.
-
-If they choose to print the command, run the same thing with `--here` instead of no flag,
-and show them the `command` it prints. `--here` writes the fork without trying to open
-anything.
-
-If they press Esc, stop. Nothing has been written to their machine yet, and there is nothing
-to clean up.
-
-## 3. No arguments, or anything else
-
-Say what the two halves do in two lines, and stop:
-
-`/popover:fork create` · `/popover:fork open PQRS-2345-BCDF-7892`
-
-Do not create a fork on the user's behalf just because they ran the command with no
-arguments. Suggesting a fork is fair game, and the popover skill says when — but creating
-one is a disclosure the user has to have chosen. An empty invocation is someone looking, not
-someone choosing.
-
-## Rules
-
-- Never invent or guess at a code. If what they typed is rejected, relay that and let them
-  paste it again — a code is 16 characters in four groups and is easy to truncate.
-- Never print a code the user has not seen; it is the entire credential and the decryption
-  key for the conversation behind it.
-- A fork is one-way. If the user seems to want an answer rather than to hand over the whole
-  conversation, say that `/popover:ask` is the cheaper thing and offer it instead.
-- Do not run `create` and then immediately `open` the result to "test" it. Every open counts
-  against what the sharer sees, and the fork is already verified by the command exiting
-  cleanly.
-- `popover fork revoke <code>` destroys a snapshot early. It cannot recall a copy someone
-  has already opened; if the user is worried about that, say so rather than reassuring them.
+---
+description: Share this conversation as a fork a teammate can carry on, or open one you were sent
+# 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|open] [code]"
+allowed-tools: Bash(popover fork *), AskUserQuestion
+---
+
+# Fork this conversation
+
+The user ran `/popover:fork`. Arguments, which may be empty: **$ARGUMENTS**
+
+This session's id is `${CLAUDE_SESSION_ID}`. You will need it for `create`.
+
+A fork is not an ask. An ask sends a teammate's question to a read-only copy of someone's
+session and brings back one answer. A fork hands over **the whole conversation**, frozen at
+the moment it was made, and the person who opens it gets their own local chat that continues
+from there. Nothing they do in it comes back here.
+
+The first word of the arguments chooses what to do. Follow exactly one of these paths.
+
+## 1. `create` — freeze this conversation and get a code
+
+Run:
+
+```
+popover fork create --session ${CLAUDE_SESSION_ID} --json
+```
+
+On `ok: true`, show the user the code on its own line so it is easy to copy, then tell them,
+briefly and in this order:
+
+- Who it is for and how they open it: `popover fork open <code>`, or
+  `npx @popoverinstall/cli fork open <code>` if they do not have popover yet.
+- That the code stops working in 24 hours, but a chat someone has already opened does not —
+  it is theirs from then on.
+- That it is frozen at `last_turn_at`, so nothing said after this point is included. If they
+  keep working and want the newer state shared, they run `create` again for a new code.
+- That this sends the entire conversation, including the contents of every file read into
+  it. Say it plainly, once. It is a much larger disclosure than an ask and the user should
+  make it deliberately.
+
+On `ok: false`, relay `message` and the `hints` verbatim. Do not retry with different flags.
+
+## 2. `open <code>` — take delivery of a fork
+
+Run:
+
+```
+popover fork open <the code they typed> --json
+```
+
+On `ok: false`, relay `message` and `hints` and stop.
+
+On `ok: true`, tell them what arrived: who shared it, the title if there is one,
+`entry_count` messages, when it was frozen, and which repo it came from. Then surface
+whatever the output flags:
+
+- `repo_match: "different"` — say which repo it came from and which one they are in, and
+  that the conversation will refer to files they may not have.
+- `repo_match: "unknown"` — they are not in a git repository, so paths in it may not resolve.
+- `version_skew` — relay it as a note, not a blocker.
+- `claude_problem` — this one *is* a blocker. Relay it and stop.
+
+Then explain why this needs a window of its own, and offer the choice.
+
+**A fork cannot open inside this chat.** A running Claude Code session cannot become a
+different session — one chat holds one conversation, and this one already has its own. So
+the fork starts as a second session in a new window. If this conversation has real context
+in it already, say that plainly; if the user only just started here, one short line is
+enough.
+
+Then call `AskUserQuestion` with exactly these two options, so Esc cancels:
+
+- **Open a new window** — "Start the fork in its own terminal window"
+- **Print the command** — "Show the command and let me run it myself"
+
+If they choose to open a new window, run:
+
+```
+popover fork launch <stage_id> --json
+```
+
+Then report what happened: `opened: true` means a window is on its way, and it is worth
+adding that the fork may take a moment to appear. `opened: false` is not a failure — it
+happens over SSH, in a container, and anywhere there is no window to open — so show them
+`command` and the `cwd` to run it in.
+
+If they choose to print the command, run the same thing with `--here` instead of no flag,
+and show them the `command` it prints. `--here` writes the fork without trying to open
+anything.
+
+If they press Esc, stop. Nothing has been written to their machine yet, and there is nothing
+to clean up.
+
+## 3. No arguments, or anything else
+
+Say what the two halves do in two lines, and stop:
+
+`/popover:fork create` · `/popover:fork open PQRS-2345-BCDF-7892`
+
+Do not create a fork on the user's behalf just because they ran the command with no
+arguments. Suggesting a fork is fair game, and the popover skill says when — but creating
+one is a disclosure the user has to have chosen. An empty invocation is someone looking, not
+someone choosing.
+
+## Rules
+
+- Never invent or guess at a code. If what they typed is rejected, relay that and let them
+  paste it again — a code is 16 characters in four groups and is easy to truncate.
+- Never print a code the user has not seen; it is the entire credential and the decryption
+  key for the conversation behind it.
+- A fork is one-way. If the user seems to want an answer rather than to hand over the whole
+  conversation, say that `/popover:ask` is the cheaper thing and offer it instead.
+- Do not run `create` and then immediately `open` the result to "test" it. Every open counts
+  against what the sharer sees, and the fork is already verified by the command exiting
+  cleanly.
+- `popover fork revoke <code>` destroys a snapshot early. It cannot recall a copy someone
+  has already opened; if the user is worried about that, say so rather than reassuring them.

package/plugin/commands/repos.md

@@ -0,0 +1,107 @@
+---
+description: Show which repos your teams treat as one product, and add the one you are in
+# 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: "[add] [team]"
+# Two narrow permissions rather than `Bash(popover repos *)`, so that `rm` is not reachable
+# from here even by accident. See "What this command will not do".
+allowed-tools: Bash(popover repos --json), Bash(popover repos add *), AskUserQuestion
+---
+
+# Team repos
+
+The user ran `/popover:repos`. Arguments, which may be empty: **$ARGUMENTS**
+
+Two agents can see, ask and tell each other when they share a team **and** share a repo. A
+team's repo list is what makes `backend`, `app` and `firmware` count as one repo for that
+purpose — without it, an agent in one cannot reach an agent in another however obviously they
+are the same product.
+
+Which repo this command is about comes from **the directory you are in**. There is no repo
+argument anywhere, deliberately: registering one proves you hold a clone of it rather than that
+you can spell its name.
+
+## Reporting — always do this first
+
+Run:
+
+```
+popover repos --json
+```
+
+On `ok: false`, relay `message` and the `hints` verbatim and stop. Do not retry with different
+flags, and do not try `popover repos` without `--json` to see if it says something friendlier.
+
+On `ok: true`, read the fields and say, in a few lines:
+
+- `kind` — `repo` means one clone, `workspace` means a directory whose children are repos (the
+  orchestrating case), `none` means there is nothing here to register and `message` says why.
+- `status[]` — for each repo here: `onTeams` are the teams that list it, and `published: false`
+  means popover holds no key for it, so it cannot be registered yet whatever the user's
+  permissions are.
+- `teams[]` — each team, its `listed` repos, and `isAdmin`.
+
+Then say what it means for visibility, once, in the user's terms: who can currently see agents
+here, and what listing this repo would change. Do not print the raw JSON.
+
+## Adding
+
+Only when the user asked to add, or agreed to after you offered. Run:
+
+```
+popover repos add --json
+```
+
+Add the team name when the user named one, or when the report showed more than one team they
+administer: `popover repos add Quolabs --json`.
+
+Success comes back as `ok: true` with `added`, `already` and `unpublished`. Report `added` and
+`already` in one line each. For anything in `unpublished`, say that popover has published no
+session from that clone yet, so there is no key to register — it is not a permissions problem
+and running the command again will not fix it.
+
+### The two refusals you must not paper over
+
+`ok: false` with `error: "needs_confirmation"` means this is a **workspace** and adding would
+register several repos at once. The `hints` list them. **Ask the user with `AskUserQuestion`**
+before re-running with `--yes`. Registering a repo decides who can see whose agents; a list of
+three where the user was thinking of one is not a detail to assume through.
+
+`ok: false` with `error: "ambiguous_team"` means they administer more than one team. Ask which,
+with `AskUserQuestion`, and re-run naming it. Never pick for them.
+
+Every other `ok: false` — `not_admin`, `github_not_linked`, `github_scope_missing`,
+`not_repo_admin`, `not_github`, `github_org_restricted` — is a refusal with an explanation.
+Relay `message` and `hints` as they are. They are worded carefully and three of them are easy
+to garble:
+
+- `github_scope_missing` is **not** "you have no GitHub account". They almost certainly signed
+  in with GitHub. Repository access is a separate, heavier consent that is only asked for when
+  a repo is added.
+- `github_org_restricted` is **not** "that repo does not exist". GitHub answers 404 for a
+  private repo whose organization has not approved popover, and this only ever comes up for a
+  repo the user demonstrably has a clone of. An owner of that GitHub organization has to
+  approve popover.
+- `not_admin` names who to ask. Pass the names on; that is what makes it actionable.
+
+## What this command will not do
+
+**It does not remove a repo.** That is `popover repos rm`, in a terminal, and it is missing
+here on purpose rather than by oversight — removing a repo takes *other people's* agents out of
+scope at the next check, and they will not be told why. It should be a thing a human typed.
+If the user asks to remove one, say that plainly and give them the command:
+
+`popover repos rm Quolabs`
+
+Do not run it through any other tool, and do not talk them out of it either — just make them
+the one who types it.
+
+## Rules
+
+- Never claim a repo is listed unless `--json` said so. The whole feature is a gate; a wrong
+  answer here reads as "popover is broken" the next time somebody cannot see a teammate.
+- Adding is a team-wide decision. Any member in any listed repo can then reach any agent in any
+  listed repo — there are no per-repo permissions. Say so before adding, if the user seems to
+  be reaching for a narrower kind of sharing; the answer to that is a second team.
+- Nothing here is retryable by trying harder. Every refusal names a specific thing to change,
+  and running the same command twice will produce the same refusal.

package/plugin/commands/team.md

@@ -1,60 +1,60 @@
----
-description: Show which of your teammates' Claude Code agents are active in this repo right now
-# No argument-hint: this command takes none. The ask/tell tools are still allowed below
-# because `/popover:team ask …` was the only form before 0.8.0 and is still carried out.
-allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popover__team_ask, mcp__plugin_popover_popover__team_tell, AskUserQuestion
----
-
-# Team agents
-
-The user ran `/popover:team`. Arguments, which are usually empty: **$ARGUMENTS**
-
-This command shows the roster. Asking and telling are their own commands now — `/popover:ask`
-and `/popover:tell` — because they cost different things and deserve to be chosen, not reached
-by a subword.
-
-## The roster
-
-Call `mcp__plugin_popover_popover__team_list`, then print what it returns **verbatim** in a
-fenced block. Do not reformat it, re-sort it, or add agents that are not in it.
-
-Only agents working in **this repo** are visible. A teammate running Claude Code in a different
-repository is neither listed nor reachable, so an empty roster means nobody else is working
-*here* — not that the team is idle. Say it that way; the tool's own text already knows the
-difference, so relay it rather than paraphrasing it into "your team is idle".
-
-Then add one short line showing where to go next:
-
-`/popover:ask B1 why did you rule out redis?` · `/popover:tell B1 the migration is applied`
-
-Stop there. Do not ask or tell anything on the user's behalf.
-
-## If they typed `ask` or `tell` anyway
-
-`/popover:team ask …` and `/popover:team tell …` were the only forms before 0.8.0, so they are
-still muscle memory. Do not answer with a correction and nothing else — carry it out, then
-mention the shorter command once at the end in a single line. The user gets what they asked for
-and learns the new name.
-
-**`ask <handle> <question>`** — call `mcp__plugin_popover_popover__team_ask` with `target` set
-to the handle exactly as typed and `question` set to the rest, rewritten to stand alone: the
-answering agent has none of this conversation, so expand every pronoun and vague reference
-("that bug" → "the token refresh bug in the auth service") and name files by path. Show the
-answer attributed — `> **B1** (Bob Chen, api-server): …` — then say how it bears on the work in
-hand, if it does.
-
-**`tell <handle> <message>`** — call `mcp__plugin_popover_popover__team_tell` with `target` and
-`message`, made self-contained the same way. Nothing comes back; confirm in one line what was
-sent and to whom, and stop. A tell is information, not a directive — if the user is trying to
-hand over work, say so and offer an ask instead.
-
-If the tool errors or times out, relay it plainly rather than retrying or trying another agent.
-
-## Rules
-
-- Never invent a handle. Only use ones `team_list` returned.
-- Asking costs the *teammate* money and runs on *their* machine. Telling costs their attention
-  and notifies them. One agent per request either way.
-- An answer comes from a read-only copy of their session. Their live session is not interrupted
-  and cannot be modified by an ask. A tell **is** delivered into their live session, before its
-  next prompt — that is the one thing in popover that reaches a running agent.
+---
+description: Show which of your teammates' Claude Code agents are active in this repo right now
+# No argument-hint: this command takes none. The ask/tell tools are still allowed below
+# because `/popover:team ask …` was the only form before 0.8.0 and is still carried out.
+allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popover__team_ask, mcp__plugin_popover_popover__team_tell, AskUserQuestion
+---
+
+# Team agents
+
+The user ran `/popover:team`. Arguments, which are usually empty: **$ARGUMENTS**
+
+This command shows the roster. Asking and telling are their own commands now — `/popover:ask`
+and `/popover:tell` — because they cost different things and deserve to be chosen, not reached
+by a subword.
+
+## The roster
+
+Call `mcp__plugin_popover_popover__team_list`, then print what it returns **verbatim** in a
+fenced block. Do not reformat it, re-sort it, or add agents that are not in it.
+
+Only agents working in **this repo** are visible. A teammate running Claude Code in a different
+repository is neither listed nor reachable, so an empty roster means nobody else is working
+*here* — not that the team is idle. Say it that way; the tool's own text already knows the
+difference, so relay it rather than paraphrasing it into "your team is idle".
+
+Then add one short line showing where to go next:
+
+`/popover:ask B1 why did you rule out redis?` · `/popover:tell B1 the migration is applied`
+
+Stop there. Do not ask or tell anything on the user's behalf.
+
+## If they typed `ask` or `tell` anyway
+
+`/popover:team ask …` and `/popover:team tell …` were the only forms before 0.8.0, so they are
+still muscle memory. Do not answer with a correction and nothing else — carry it out, then
+mention the shorter command once at the end in a single line. The user gets what they asked for
+and learns the new name.
+
+**`ask <handle> <question>`** — call `mcp__plugin_popover_popover__team_ask` with `target` set
+to the handle exactly as typed and `question` set to the rest, rewritten to stand alone: the
+answering agent has none of this conversation, so expand every pronoun and vague reference
+("that bug" → "the token refresh bug in the auth service") and name files by path. Show the
+answer attributed — `> **B1** (Bob Chen, api-server): …` — then say how it bears on the work in
+hand, if it does.
+
+**`tell <handle> <message>`** — call `mcp__plugin_popover_popover__team_tell` with `target` and
+`message`, made self-contained the same way. Nothing comes back; confirm in one line what was
+sent and to whom, and stop. A tell is information, not a directive — if the user is trying to
+hand over work, say so and offer an ask instead.
+
+If the tool errors or times out, relay it plainly rather than retrying or trying another agent.
+
+## Rules
+
+- Never invent a handle. Only use ones `team_list` returned.
+- Asking costs the *teammate* money and runs on *their* machine. Telling costs their attention
+  and notifies them. One agent per request either way.
+- An answer comes from a read-only copy of their session. Their live session is not interrupted
+  and cannot be modified by an ask. A tell **is** delivered into their live session, before its
+  next prompt — that is the one thing in popover that reaches a running agent.

package/plugin/commands/tell.md

@@ -1,66 +1,66 @@
----
-description: Send a short heads-up into a teammate's live session — no answer comes back, and they are notified
-# 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: "[agent-handle] <message>"
-allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popover__team_tell, AskUserQuestion
----
-
-# Tell a teammate's agent
-
-The user ran `/popover:tell`. Arguments, which may be empty: **$ARGUMENTS**
-
-A tell is the one thing in popover that reaches a **running** agent: it is delivered into a
-teammate's live session before its next prompt, and their user is notified. It costs a
-colleague's attention rather than their tokens, which is why it is its own command and why the
-bar for sending one is higher than for an ask.
-
-Only agents working in **this repo** are reachable.
-
-## No arguments
-
-Call `mcp__plugin_popover_popover__team_list`, print what it returns **verbatim** in a fenced
-block, and show the form:
-
-`/popover:tell B1 the repo_keys migration is applied on prod`
-
-Stop there. Do not send anything on the user's behalf.
-
-## A handle and a message
-
-Call `mcp__plugin_popover_popover__team_tell` with:
-
-- `target`: the handle or name they used, exactly as typed
-- `message`: the rest of their message, made **self-contained** — it arrives with no context of
-  its own, so name the thing rather than referring to it. One or two sentences.
-
-Nothing comes back. Confirm what was sent and to whom, in one line, and stop:
-
-> Told **B1** (Bob Chen): the repo_keys migration is applied on prod.
-
-## A message with no handle
-
-Call `mcp__plugin_popover_popover__team_list`, then **confirm the recipient with
-`AskUserQuestion` before sending** — up to 4 candidates, label = the handle, description =
-owner, repo, and what it is doing. Do this even when only one agent plausibly fits.
-
-Naming a handle is how the user says *which colleague to interrupt*; if they did not name one,
-that choice has not been made yet and it is not yours to make. This is the one place a tell
-differs from an ask, which may pick its own target because the only thing it spends is tokens.
-
-If none fit, show the roster instead. Never broadcast to several agents.
-
-## Rules
-
-- **What a tell is for:** facts about shared state that would otherwise cause a collision — a
-  migration you just applied, a branch you force-pushed, a file you are about to rewrite that
-  their agent is working in right now.
-- **What it is not for:** instructions or handing over work. The receiving agent is explicitly
-  told to treat the message as information rather than a directive. If the user is trying to
-  give another agent a task, say so and offer `/popover:ask` instead — or suggest they message
-  the human.
-- **Never invent a handle**, and do not fan out to several agents unless asked in as many words.
-- Rate limited to 10 messages an hour to any one agent, which is a hint about its intended
-  frequency. If the limit is hit, relay that rather than retrying.
-- If it is genuinely ambiguous whether the user meant to ask or tell, prefer **`/popover:ask`**
-  — it interrupts nobody.
+---
+description: Send a short heads-up into a teammate's live session — no answer comes back, and they are notified
+# 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: "[agent-handle] <message>"
+allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popover__team_tell, AskUserQuestion
+---
+
+# Tell a teammate's agent
+
+The user ran `/popover:tell`. Arguments, which may be empty: **$ARGUMENTS**
+
+A tell is the one thing in popover that reaches a **running** agent: it is delivered into a
+teammate's live session before its next prompt, and their user is notified. It costs a
+colleague's attention rather than their tokens, which is why it is its own command and why the
+bar for sending one is higher than for an ask.
+
+Only agents working in **this repo** are reachable.
+
+## No arguments
+
+Call `mcp__plugin_popover_popover__team_list`, print what it returns **verbatim** in a fenced
+block, and show the form:
+
+`/popover:tell B1 the repo_keys migration is applied on prod`
+
+Stop there. Do not send anything on the user's behalf.
+
+## A handle and a message
+
+Call `mcp__plugin_popover_popover__team_tell` with:
+
+- `target`: the handle or name they used, exactly as typed
+- `message`: the rest of their message, made **self-contained** — it arrives with no context of
+  its own, so name the thing rather than referring to it. One or two sentences.
+
+Nothing comes back. Confirm what was sent and to whom, in one line, and stop:
+
+> Told **B1** (Bob Chen): the repo_keys migration is applied on prod.
+
+## A message with no handle
+
+Call `mcp__plugin_popover_popover__team_list`, then **confirm the recipient with
+`AskUserQuestion` before sending** — up to 4 candidates, label = the handle, description =
+owner, repo, and what it is doing. Do this even when only one agent plausibly fits.
+
+Naming a handle is how the user says *which colleague to interrupt*; if they did not name one,
+that choice has not been made yet and it is not yours to make. This is the one place a tell
+differs from an ask, which may pick its own target because the only thing it spends is tokens.
+
+If none fit, show the roster instead. Never broadcast to several agents.
+
+## Rules
+
+- **What a tell is for:** facts about shared state that would otherwise cause a collision — a
+  migration you just applied, a branch you force-pushed, a file you are about to rewrite that
+  their agent is working in right now.
+- **What it is not for:** instructions or handing over work. The receiving agent is explicitly
+  told to treat the message as information rather than a directive. If the user is trying to
+  give another agent a task, say so and offer `/popover:ask` instead — or suggest they message
+  the human.
+- **Never invent a handle**, and do not fan out to several agents unless asked in as many words.
+- Rate limited to 10 messages an hour to any one agent, which is a hint about its intended
+  frequency. If the limit is hit, relay that rather than retrying.
+- If it is genuinely ambiguous whether the user meant to ask or tell, prefer **`/popover:ask`**
+  — it interrupts nobody.