@adrata/adrata-mcp 1.0.0

package/server.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "com.adrata/adrata-mcp",
+  "description": "Adrata revenue-intelligence MCP server: companies, people, opportunities, actions, buyer groups, enrichment, email, and workspace operations for AI agents.",
+  "status": "active",
+  "version": "1.0.0",
+  "websiteUrl": "https://adrata.com/developers",
+  "repository": {
+    "url": "https://github.com/adrata/adrata",
+    "source": "github",
+    "subfolder": "code/mcp"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@adrata/adrata-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "ADRATA_API_KEY",
+          "description": "Pro-tier API key. Omit for free tier; use OAuth (connect_workspace) for enterprise.",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "ADRATA_OAUTH_TOKEN",
+          "description": "Enterprise OAuth 2.1 access token, audience-bound to the Adrata MCP resource (RFC 8707).",
+          "isRequired": false,
+          "isSecret": true
+        }
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.adrata.com/mcp"
+    }
+  ],
+  "_meta": {
+    "com.adrata": {
+      "authorization": {
+        "spec": "MCP 2025-06-18",
+        "oauth": "2.1 + PKCE (S256)",
+        "resourceIndicators": "RFC 8707",
+        "protectedResourceMetadata": "RFC 9728 at /.well-known/oauth-protected-resource",
+        "tokenPassthrough": "rejected (audience-bound)"
+      }
+    }
+  }
+}

package/skills/backlog-triage/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: backlog-triage
+description: Triage a Starfield backlog board — work the Triage column down, deduplicate against what is already there, tag by the board's own scheme, and route each card. Use when asked to triage, groom, sort, or "clean up" a backlog, or when someone asks what they should work on next.
+---
+
+# Backlog triage
+
+You are working someone's real backlog. Every move you make shows up on their
+board on Monday morning, and a card you mis-tag is a card they stop trusting the
+tag on. Be conservative and leave a trail.
+
+## Before you touch anything
+
+1. `list_work_boards` — get the board id. If there is more than one, ask which,
+   unless the request already names a company or product that identifies it.
+2. `get_work_board` — read the columns AND their staleness policies, and the
+   cards. Note the board's `tagScheme`: it decides the vocabulary you are
+   allowed to tag in.
+
+**Read the whole board before changing one card.** Triage is a comparison
+between cards, not a judgement on each in isolation — you cannot know a card is
+a duplicate, or that it is the fifth report of one bug, without the rest.
+
+## The order of work
+
+Work the board's FIRST column (usually Triage). Do not touch cards further
+along: a card in In review has been looked at by someone who knew more than you
+do about it.
+
+For each card, in this order:
+
+### 1. Is it a duplicate?
+
+Compare against every other card on the board, not just the same column. Two
+cards are duplicates when fixing one closes the other — not merely when they use
+similar words. "Export is slow" and "Export times out at 10k rows" may be one
+bug or two; if you cannot tell, they are two.
+
+Do NOT delete or merge duplicates on your own judgement. Say which cards you
+believe are duplicates and why, and let a human collapse them. A wrongly merged
+card loses its reporter and its evidence, and nobody ever notices.
+
+### 2. Is it actually a card?
+
+Some Triage entries are questions, notifications, or half a thought. A card that
+does not describe a change to make is not ready to be worked. Flag it, propose
+a one-line rewrite that names the change, and leave it in Triage.
+
+### 3. Tag it
+
+Use `set_work_item_tag` with the board's own `tagScheme`. Source is **`model`**
+and you must give a `confidence` — you are a classifier here, not the person
+whose call it is. Claiming `human` would launder your guess as their judgement.
+
+Be conservative upward. The severity scheme's `critical` means *someone is
+broken right now*: an outage, data loss, a security issue, or every customer
+affected. A slow report is not critical. A backlog that cries wolf gets ignored,
+and then the one real critical is missed.
+
+If the card gives you no signal at all, leave it untagged rather than tagging it
+low-confidence — the board falls back to its own deterministic rules, which is
+more honest than a guess with a number on it.
+
+### 4. Route it
+
+Move a card out of Triage only when you can say which column it belongs in and
+why. `move_work_item`, with a `reason` that would satisfy the person who wrote
+the card: "Reproduced on staging, needs a fix" beats "triaged".
+
+The tool refuses a placeholder `reason` — "triaged", "moved", "update" — so the
+line above is a rule the board now enforces rather than advice.
+
+A card you could not tag confidently stays in Triage. That is the correct
+outcome, not a failure.
+
+### 5. Leave the owner alone
+
+Routing a card is not picking it up. Do **not** pass `claim` on these moves, and
+never `force`: an assignee is how two people stay off one card, and triage
+reassigning it is exactly the surprise that makes a board stop being trusted. A
+card that already has an assignee is that person's — route it if it is in the
+wrong column, and say so, but it stays theirs.
+
+Picking work up is a different skill: `ship-the-card`.
+
+## What the ages mean
+
+Every card carries `enteredColumnAt`. Compare it against **its own column's**
+`agingAfterHours` / `staleAfterHours` — a missing bound means the column never
+ages, which is what a Done column wants. Three days in Triage is alarming; three
+days in In review is a Tuesday. Applying one threshold across the board will
+make you report finished work as stale.
+
+Stale cards in Triage are the ones to surface first: they have been waiting for
+a decision nobody made.
+
+## Writes
+
+Every move and tag change is a governed write. Preview first (the tools default
+to `dryRun: true`), show the human the full list of what you intend to do, and
+only then run with `dryRun: false`, `approved: true`, a `reason`, and an
+`idempotencyKey`. Reuse the same key if you retry — a duplicate move makes the
+card read as having bounced between columns, and the board's stage timer is
+derived from exactly those rows.
+
+## What to report
+
+A short list, in this shape:
+
+- **Moved** — card, from → to, why.
+- **Tagged** — card, tag, confidence, the signal you read it from.
+- **Left in Triage** — card, and the specific question that would unblock it.
+- **Possible duplicates** — the pairs, and what would confirm it.
+
+No summary paragraph. The person reading this is about to act on it.

package/skills/board-review/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: board-review
+description: Review a Starfield board or roll-up and report what is actually stuck — what has gone stale, what is unowned, where work is piling up, and which decisions are overdue. Use for a standup, a weekly review, a "how are we doing", or when someone asks what is blocked across their clients.
+---
+
+# Board review
+
+The question behind every board review is *what needs a decision that nobody is
+making*. Card counts do not answer it. Time does.
+
+## Scope
+
+- One team's board → `get_work_board`.
+- Everything, across every client → `get_work_board_rollup` with `rollupId:
+  "all"`. This one has no membership rows, so it always includes a board created
+  five minutes ago.
+- A curated view → `list_work_board_rollups`, then `get_work_board_rollup`.
+
+A roll-up keeps provenance: every card still names its board and its company.
+Use it. "Three cards are stale" is useless; "Acme has three stale cards, all in
+Triage" is a conversation.
+
+## Read the time, not the count
+
+Every card carries `enteredColumnAt`. Compare it against **its own column's**
+policy — `agingAfterHours` and `staleAfterHours` live on the column, and a
+missing bound means that column never ages.
+
+This is the mistake to avoid: applying one threshold to a whole board. Three
+days in Triage means nobody has decided. Three days in In review means it is
+Tuesday. Three days in Done means nothing at all. A review that calls finished
+work stale destroys its own credibility in one line.
+
+On a roll-up, each slice carries the member board's own policy — use the slice's
+policy for its own cards.
+
+## What to look for, in priority order
+
+1. **Stale in an early column.** A card sitting in Triage past its threshold is
+   a decision nobody made. This is the highest-value thing a review surfaces,
+   because it is pure latency — no work is happening and none is blocked on
+   anything real.
+
+2. **Work in progress with no assignee.** `assigneeUserId` absent on a card in
+   an active column means it is nobody's. Cards do not move themselves.
+   `list_my_work_items` with `includeUnassigned: true` returns the unowned pool
+   across every board directly, which is faster than scanning each board — but
+   its `assignedToMe` half answers only for YOU, so it is not a way to report on
+   anybody else's load. For that, read the boards and group by assignee.
+
+3. **A column piling up.** Compare column depths against the board's own
+   history, not against each other — some columns are meant to be deep. A
+   suddenly-deep In review means the reviewers are the bottleneck, not the
+   builders.
+
+4. **Critical cards that are not moving.** Cross the tag against the age. A card
+   tagged `critical` (or `p0`) that has been in one column for days is either
+   mis-tagged or genuinely on fire, and both are worth saying out loud. Use
+   `get_work_item_history` to see whether it has moved at all or has been
+   bouncing.
+
+5. **Cards that have bounced.** `get_work_item_history` shows every transition.
+   A card that has crossed the same boundary three times is not making progress;
+   it is missing information, and the history's `reason` fields usually say
+   which.
+
+## Do not equate tag schemes
+
+Boards can use different vocabularies — severity, priority, kind, impact. A P1
+is not a Critical, and nothing in this product will translate one into the
+other. Rank within each board's own scheme and report them as they are. If you
+need a single ordering across boards, say what you ordered by and that it is
+your own reading, not the boards'.
+
+## This is a read-only skill
+
+A review reports; it does not reorganise. If the review surfaces cards that
+should move, say so and stop — moving them is `backlog-triage`, and it is a
+separate decision the person may not want made for them. Do not call
+`move_work_item` or `set_work_item_tag` here — and in particular do not claim a
+card you noticed is unowned. Reviewing work and taking it are different acts, and
+doing the second while asked for the first is how a review stops being safe to
+ask for.
+
+## What to report
+
+Lead with what is stuck, not with totals:
+
+- **Overdue decisions** — card, board/company, how long it has waited, and the
+  specific question that would unstick it.
+- **Unowned in-flight work** — card, board, column.
+- **Bottleneck** — the column that is piling up, and against what.
+- **Critical and not moving** — card, tag, days in column, whether it has moved.
+
+Then, and only then, one line of totals. If nothing is stuck, say that plainly —
+a clean board is a real result, and padding it with numbers hides it.

package/skills/incident-to-card/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: incident-to-card
+description: Turn a live problem — an alert, a failing build, a stack trace, a customer saying "it's down" — into a Starfield card that someone can actually pick up. Use when reporting a bug, filing an incident, or capturing something broken you found while working.
+---
+
+# Incident to card
+
+The gap between "I found a bug" and "someone fixed it" is almost always the
+card. A card that says *Export broken* costs the next person an hour of
+rediscovery. This skill is about spending two minutes now instead.
+
+## What makes a card workable
+
+Five things, and a card missing any of them will bounce:
+
+1. **What you did** — the smallest sequence that shows the problem.
+2. **What happened** — the actual output. Paste the error, the status code, the
+   stack trace. Not your summary of it.
+3. **What you expected** — obvious to you, not to the person picking it up.
+4. **Where** — environment, build SHA or version, workspace/account if it is
+   scoped to one.
+5. **Acceptance criteria** — what would prove this fixed, as outcomes somebody
+   can check. See below; this is the one people leave off.
+
+If you are filing from a conversation or a log you are looking at right now,
+extract these from it. **Do not invent any of them.** A plausible repro that
+does not reproduce is worse than no repro: it sends someone down a path you
+never actually walked. If you do not know the expected behaviour, say "expected
+unknown — reporter did not state it" in the body.
+
+## Acceptance criteria, and where they live
+
+A card is the unit of QA sign-off: it is one judgement, made in one pass against
+a written list. So every card carries that list, and post-AI it has **two**
+readers — it is the build spec the agent works from and the test plan QA
+validates against. The same sentences, doing both jobs. A card without them
+makes the agent guess and gives QA nothing to check, which is how a card gets
+signed off on the wrong thing.
+
+**There is no acceptance-criteria field.** They live in the card's `body`, under
+an `Acceptance criteria` heading, one checkable outcome per line:
+
+```
+Acceptance criteria
+- Exporting 10,000 rows completes without a 504.
+- The export button is disabled until the download starts.
+```
+
+Two rules that decide whether you have written them correctly:
+
+- **One card is one QA judgement.** If your list needs QA to make more than one
+  call — "follows the OS theme" AND "the toggle persists" AND "every surface is
+  restyled" — that is several cards. A bounce from a multi-outcome card names
+  nothing actionable, which is what makes the second QA pass worthless. The
+  count is also the honest size signal: one line is a small card, five is a big
+  one, ten means you should have filed two.
+- **Do not invent them**, on exactly the terms you do not invent a repro. If the
+  reporter never said what "fixed" looks like, write "acceptance criteria
+  unknown — reporter did not state what fixed looks like" and file it. That is a
+  triage problem for a human, and naming it is what gets it triaged; a made-up
+  criterion is worse, because QA will sign the card off against it.
+
+Implementation steps are **not** criteria and never become their own cards:
+"create a React hook", "rename the CSS variables" are lines in this body, in a
+checklist under the criteria. There are deliberately no sub-tasks on this board.
+
+## Writing it
+
+**Title**: the failure, not the area. `Checkout returns 500 for all customers
+since the 14:02 deploy` — not `Checkout issue`. Someone scanning the board must
+be able to tell whether this is theirs without opening it.
+
+**Body**: the five things above, in that order, under plain headings. Keep the
+raw error verbatim in a code block — the exact string is what someone will
+grep for.
+
+## Filing it
+
+1. `list_work_boards` → pick the board. If the problem is scoped to a company
+   the workspace serves, use that company's board.
+2. `get_work_board` → find the Triage column (the first one) and read the
+   board's `tagScheme`.
+3. `create_work_item` with the title, the body, and `product` if you can tell
+   which one it belongs to.
+
+**Leave `assigneeUserId` empty.** Filing a card is not picking it up, and an
+assignee put on at filing time is a name nobody agreed to. An unowned card in the
+first column is the honest state: it shows up in everybody's
+`list_my_work_items` unassigned pool, which is where someone chooses to take it.
+If you are going to work it yourself, file it unassigned and then claim it
+properly — `ship-the-card`, one `move_work_item` with `claim: true`.
+
+Filing it unassigned loses nothing, because **the card records who created it**
+either way: the server stamps the creator from your authenticated session, so
+the card can always be traced back to the person whose terminal it came from.
+You cannot set it, and a body naming a creator is refused rather than ignored —
+an author a tool could name would be a record of what the tool said, not of who
+filed the card. Say "created by" and "assigned to" separately when you report
+back; they are different people and the board keeps them apart.
+
+Then tag it with `set_work_item_tag`, source `model` plus a `confidence`.
+
+**The severity bar, if the board uses the severity scheme:** `critical` means
+someone is broken right now — an outage, data loss, a security issue, or every
+customer affected. A workaround existing usually means it is not critical. Be
+honest about this even when the person reporting it is upset; the board's
+credibility is what makes the next real critical get picked up fast.
+
+If you are filing several cards from one incident, file the *symptom* people
+hit, not one card per log line. Five cards for one root cause is five triage
+decisions someone has to make.
+
+## Writes
+
+`create_work_item` and `set_work_item_tag` are governed writes: they preview by
+default. Show the human the card you are about to file — title, body, tag — and
+file it only after they say yes, with `dryRun: false`, `approved: true`, a
+`reason`, and an `idempotencyKey`. Reuse the same key on retry so a flaky
+connection does not file the same incident twice.
+
+## After filing
+
+Report the card id and its column. If you found something while filing that
+suggests the cause — a recent deploy, a related card already on the board — say
+so as a separate line, clearly marked as your inference rather than as evidence
+from the report.

package/skills/log-outreach.md

@@ -0,0 +1,62 @@
+# Log Outreach Skill
+
+Use the Adrata MCP to log sales outreach interactions. This skill replaces manual Airtable logging.
+
+## When to use
+
+When the user says things like:
+- "Log my LinkedIn outreach from today"
+- "I sent a connection request to John Smith at Acme"
+- "Log that I messaged these 5 people on LinkedIn"
+- "Update my CRM with today's outreach"
+
+## How it works
+
+Use the `log_interaction` tool for each interaction. It handles everything in one call:
+1. Finds the person by email or name (or creates them if new)
+2. Finds the company (or creates it if new)
+3. Creates an action with the interaction details and metadata
+4. Optionally updates the person's custom fields
+
+## Examples
+
+### Single interaction
+```
+User: "I sent a LinkedIn connection request to Sarah Chen, VP Engineering at Dataflow Labs. Here's the message I sent: 'Hi Sarah, I noticed Dataflow is scaling their sales team...'"
+
+→ Call log_interaction with:
+  personName: "Sarah Chen"
+  companyName: "Dataflow Labs"
+  type: "linkedin_connection_request"
+  title: "Sent LinkedIn connection request to Sarah Chen"
+  message: "Hi Sarah, I noticed Dataflow is scaling their sales team..."
+  outcome: "pending"
+```
+
+### Batch logging
+```
+User: "Log these LinkedIn messages I sent today:
+1. John Smith at Acme - connection request - 'Hi John...'
+2. Lisa Park at TechCorp - follow-up message - 'Thanks for connecting...'
+3. Mike Johnson at StartupXYZ - connection request - 'Hi Mike...'"
+
+→ Call log_interaction 3 times, once per person
+```
+
+### Connection accepted + meeting booked
+```
+User: "Sarah Chen accepted my connection and we booked a meeting for Friday"
+
+→ Call log_interaction with:
+  personName: "Sarah Chen"
+  type: "meeting"
+  title: "Meeting booked with Sarah Chen"
+  outcome: "meeting_booked"
+  customFields: { "outreach_status": "meeting_scheduled" }
+```
+
+## Tips
+- Always use `log_interaction` — it's the single tool that does find-or-create + action logging in one call
+- For checking past outreach, use `list_actions` with type and person filters
+- For "what did I do this week?", use `get_activity_summary`
+- For finding specific people, use `search_people`

package/skills/ship-the-card/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: ship-the-card
+description: Take a Starfield card from its column through to a change that is ready for review — read the card and its history, do the work, and move it with a reason a human can audit. Use when asked to pick up a card, work the backlog, or "do the next thing" on a board.
+---
+
+# Ship the card
+
+This is the loop a coding agent actually runs: read a card, do the work, move
+the card. The part people get wrong is the last step — work that lands with the
+board untouched is work nobody can see.
+
+## Pick up
+
+1. `list_my_work_items` — **start here.** It answers "what is mine", across every
+   board, already ordered the way you would pick: escalated first, then the
+   board's own left-to-right flow, then longest-waiting. You do not have to pull
+   a board and eyeball it, and you cannot accidentally read somebody else's
+   queue — "me" comes from the token, and the tool has no parameter that could
+   name anyone else.
+2. If your queue is empty, call it again with `includeUnassigned: true`. Those
+   are the cards nobody owns, and they are the ones you may take. **A card
+   assigned to someone else is theirs** — do not work it, do not claim it. Say
+   you saw it if it is on fire, and leave it alone.
+3. `get_work_board` for the card's board when you need the target column id —
+   `move_work_item` moves to a column id, and only `get_work_board` has them.
+4. `get_work_item` for the full body, `get_work_item_history` for how it got
+   here, and `get_work_item_comments` for what people have SAID about it.
+   **Read both before starting.** A card that has bounced out of a review column
+   twice was rejected for a reason: the history says WHEN it bounced, the
+   comments say WHY. Repeating a rejected approach is the most expensive mistake
+   available here, and the reviewer's comment is usually the one thing that
+   would have stopped you.
+
+**A card carrying a `flag` is not workable.** The flag means somebody has already
+found a problem with the card ITSELF — unclear scope, no repro, a blocked
+dependency, a question waiting on an answer — and its `reason` says which. It is
+a different claim from the tag, which is only about urgency: a flagged Critical
+card is still not something to start on. Read the comments for the surrounding
+argument and pick a different card, unless you are the person who can answer it.
+If you resolve it, clear the flag with `flag_work_item` (`flagged: false`) and
+say what resolved it. Anyone may clear one, which is exactly why every clear is
+recorded as a comment.
+
+If the card is not workable — no repro, no expected behaviour, ambiguous scope —
+**flag it** with `flag_work_item` and the one question that would unblock it,
+then stop. Do not invent the missing half. Flagging is what turns "I could not
+work this" into something the next person sees before they pick it up, rather
+than a sentence in your report that nobody reads. An unworkable card is a triage
+problem, not a coding problem.
+
+## Claim it, in the same move, FIRST
+
+Before you write code, move the card to the board's active column **with
+`claim: true`**. One call, not two:
+
+```
+move_work_item(itemId, toColumnId: <the active column>, claim: true,
+               dryRun: false, approved: true,
+               reason: "Picked up — reproducing against staging first",
+               idempotencyKey: "claim-<itemId>")
+```
+
+Three reasons, and the third is the real one:
+
+- claiming stops someone else picking up the same card;
+- moving it now starts the stage timer honestly. Moving it at the end backdates
+  the work to zero and quietly corrupts the board's cycle-time history;
+- doing both in ONE call is what makes it true. A separate "assign" step is the
+  step that gets skipped, and a card sitting in an active column with nobody's
+  name on it is exactly what the board's unassigned glyph exists to shout about.
+
+Reuse the same `idempotencyKey` if the call fails and you retry. The server
+replays rather than appending a second transition.
+
+**If the claim is refused**, the card already belongs to somebody: pick a
+different one. `force: true` exists — it takes the card over and demands a reason
+saying why — but it is for a card whose owner is genuinely gone, not for working
+around a refusal. Taking someone's card because it was convenient is the one move
+on this board that costs trust permanently. If you use it, say so in your report,
+not only in the reason field.
+
+## Do the work
+
+Ordinary engineering. Follow the repository's own conventions and its
+`CLAUDE.md` / `AGENTS.md`. Nothing about this skill overrides the project's
+rules — it only governs the board.
+
+Two things to carry back to the card:
+
+- if what you find contradicts the card, say so on the card rather than silently
+  fixing something else — `comment_on_work_item` is where that goes. A card that
+  says "export is slow" and turns out to be an auth timeout is a different card.
+  **Do not edit the card's body to make the point:** the body is the original
+  request, and overwriting it destroys the evidence of what was actually asked
+  for. A comment sits beside it and keeps both.
+- if the comment needs a specific person's attention, @-mention them by writing
+  `<@userId>` in the body — the id comes from the card's assignee, its history,
+  or `list_my_work_items`. Writing `@noah` mentions nobody; that is deliberate,
+  so nothing you merely type can notify somebody by accident. Mention the person
+  who can answer, not everyone who might care: a mention means "see this" and
+  nothing else, and a thread that pings four people to reach one is how a team
+  learns to ignore them.
+- if the fix is bigger than the card, do not quietly expand scope. Finish what
+  the card asked for and report the rest as a card that should exist. If you
+  file it yourself, file it the way `incident-to-card` says: a title, a body
+  carrying **acceptance criteria** — what would prove it done, one checkable
+  outcome per line — and no assignee. A card you file from here arrives
+  attributed to you automatically (the server stamps the creator from your
+  session), so the next person at aligning can ask you what you meant; what it
+  must not arrive with is a list of outcomes nobody can check.
+
+## Submit it
+
+When the change is ready for review, `move_work_item` it onward — no `claim`
+this time, you already own it — with a `reason` that carries something a human
+can audit:
+
+- a branch name, or
+- a PR link, or
+- one line naming what changed and how it was verified.
+
+> "Fixed the N+1 in the export query on `fix/export-n1`; added a test at 10k
+> rows, full suite green."
+
+That reason is the whole audit trail. Someone will read it in three weeks when
+they are asking why this card took a week, and the card id will not tell them.
+The tool refuses placeholder reasons — "moved", "update", "Moved to another
+column" — on purpose: a history full of those looks like an audit trail, so
+nobody goes looking for the real answer, which is worse than no history at all.
+
+**Do not move a card into the terminal column** — `Production` on a default
+board, or whatever the last column is called on this one. That is a human's call:
+the person who reported it, or the reviewer. An agent marking its own work
+complete is the one move on this board that nobody can trust. Stop at the review
+or QA column and say it is ready.
+
+## Writes
+
+Comments and flags are governed writes too, on the same contract as a move, and
+the idempotency key matters there for a quieter reason: a replayed comment posts
+the same paragraph twice, which reads as you being emphatic rather than as a
+retry.
+
+Every move is governed: preview first, then `dryRun: false`, `approved: true`, a
+`reason`, and an `idempotencyKey`. Reuse the same key on retry. A duplicate
+transition makes the card read as having bounced, and the stage timer is derived
+from exactly those rows — so a retry without a key does not just add noise, it
+rewrites how long the work appears to have taken.
+
+## What to report
+
+- the card, where it is now, and whether you left it flagged;
+- what changed, and how it was verified;
+- anything you found that should be its own card, stated as a title someone
+  could file as-is.