redditapis-mcp 0.9.1 → 0.10.2

package/CHANGELOG.md

@@ -1,5 +1,190 @@
 # Changelog
 
+## 0.10.2 (2026-10-14)
+
+### The 408 upstream_timeout read gets the same one retry
+
+The API now answers `408 {"error":"upstream_timeout"}` when a read did not complete in
+time (the body says it was not billed and names `retry_after`); before this release that
+case was a 500 and the model saw it as a failed tool call. A read answered that way is
+retried once after its `retry_after` (clamped 1..5 s), exactly like the 503
+`upstream_unavailable` retry from 0.10.1, and a 408 that is not retried carries a hint
+naming the retry. A 408 with any other error value, and a 408 on a write, are never
+retried.
+
+## 0.10.1 (2026-10-14)
+
+### One bounded retry on the API's transient 503, and a clearer 429
+
+A read refused by the API with `503 {"error":"upstream_unavailable"}` (the body says it
+was not billed and names `retry_after`) is now retried once after that many seconds
+(clamped 1..5) before the error reaches the model; measured on 2026-10-14, a per-read
+refusal of about 1 in 3 showed up as failed tool calls that one retry turns into slow
+successes. Writes are never retried, any other 503 is never retried, and the gateway
+retries are unchanged. The wait is clamped to 5 s, so the API's 60 s `retry_after`
+(an exhausted-egress 503) costs one 5 s wait before the error is reported, never a loop. A `429` now tells the model to lower concurrency (stay under the per-key limit the
+message names) and wait the `retry_after`, matching the API's
+`too_many_concurrent_reads` answer.
+
+## 0.10.0 (2026-10-02)
+
+### The watch compiler refuses rather than guesses
+
+Seventeen defects were found in this compiler across three review rounds. Every
+single one had the same signature: it consumed part of the description, emitted
+a filter anyway, and said nothing. The worst produced a monitor whose keyword
+was a single `"` character.
+
+Rounds one and two were both fixed by writing better rules, and both shipped a
+suite that pinned the sentences just fixed and could not fail on an input nobody
+had thought of. Round two's rewrite broke nine inputs round one handled. More
+rules was never going to end.
+
+**So the contract is inverted.** Every character of a description must be
+claimed by exactly one thing: a subreddit, a quoted phrase, a keyword, an
+exclusion, a score clause, a delivery clause, or a word with no filter content.
+Anything left over, or counted twice, and the compiler returns **no filter at
+all** and names the words it could not place. A description that both watches
+for and excludes the same phrase is refused too, because that monitor could
+never deliver.
+
+That inverts the failure mode from "a silently wrong monitor that looks fine" to
+"a refusal that says why", which for this feature is the only safe direction:
+every failure here is invisible, and the caller otherwise gets a monitor id, a
+green test delivery and then silence or a firehose.
+
+Also fixed in the same pass, all found by the change above or by the corpus:
+quoted phrases are now taken out of the sentence **before** anything else reads
+it, so a marker word, a subreddit or a kind word inside your own quotes is just
+text (`for "ignore list"`, `for "except this"`, `for "send to production"` were
+all wrecked by this); the match kind is read from the original word positions
+rather than a string with substrings deleted, which had turned `posts and
+comments for "post"` into a comments-only watch; a subreddit inside a keyword or
+exclusion clause ends that clause instead of being swallowed into the term; and
+a bare multi-word keyword is reported in `notes`, because an unquoted keyword is
+a free-text run and absorbs whatever follows it.
+
+**The suite that could not see any of this has been replaced, not extended.**
+`test/watch-invariants.test.mjs` generates 28,511 sentences from pieces chosen
+to collide (marker words inside quotes, subreddits inside quotes, markers before
+the main clause, unicode quotes, conjunctions) and asserts seven structural
+invariants that hold for every input, listed or not. Measured against the two
+previous heads with the same corpus: 20,970 violations on the first, 45,072 on
+the second, 0 now.
+
+### Fixed before release, after the first review
+
+The watch compiler matched every field with its own regular expression over the
+**whole** sentence, so two clauses read the same words and one of them was
+wrong. Four HIGH defects, one cause, each one silent:
+
+- `for pricing except "giveaway"` put the EXCLUDED phrase into `q`, so `q` and
+  `exclude_terms[0]` were the same string and the monitor could never deliver,
+  while the caller got a monitor id, a green test delivery, and then silence.
+- `for posts about pricing`, the most natural sentence there is, watched for the
+  literal phrase "posts about pricing".
+- `for posts with at least 5 upvotes about pricing` dropped the keyword
+  entirely, leaving a firehose of every post over the score floor.
+- `for "comment moderation"` read the word *comment* out of the caller's own
+  keyword and switched the watch to comments only, missing every post.
+- A pasted `reddit.com/r/X` link was not read as a subreddit, so the watch went
+  site-wide and consumed the account's one free site-wide slot.
+
+The sentence is now cut into clauses **once** and every field reads only its own
+span; the match kind is derived last, from what is left after the subreddits,
+the quoted spans and the derived terms are removed, so a keyword can never set
+it. Patching the pairs one at a time had already produced three green suites
+over four live defects, which is why the fix is the structure and not another
+rule.
+
+**And a lossy compile is no longer silent.** Every one of the above reported
+`notes: []`. When the compiler drops or rewrites something the description
+carries, it says so, and that is asserted per case.
+
+Three more in the same family, all "unknown reported as fine":
+
+- The webhook signing secret was read only to set a boolean and then thrown
+  away, while the result asserted the secret was in it. The API returns that
+  secret exactly once and the webhook list never returns it again, so a watch
+  set up this way left its owner permanently unable to verify a delivery
+  signature, and told them otherwise. It is now returned as `delivery.secret`,
+  and the sentence is tied to the value rather than to a flag about it.
+- A test delivery whose body could not be read counted as a SUCCESS
+  (`ok !== false`). It is now tri-state, and an unreadable answer says the
+  target is unconfirmed.
+- When the created monitor came back without an id, the re-point was skipped
+  with no note while the result still reported a registered target.
+
+### Added
+
+- **`reddit_set_watch`: one call where standing up a watch took three.** It compiles a plain-words
+  description into a monitor filter, reads the account's own plan capabilities, creates the monitor,
+  then registers, points and test-fires an optional `deliver_to` webhook. The compiler is a set of
+  regular expressions, not a model, so the same sentence always compiles to the same filter, and
+  everything it derived comes back in `understood` and `compiled_filter` for a person to check. It
+  reads `r/Name` subreddits, quoted phrases as keyword terms (two or more become an any-of set),
+  `comments` / `posts and comments` as the match kind, terms after `except` or `ignoring` as
+  exclusions, and `at least N upvotes` as a score floor.
+  - **The two rules that need no round trip are checked locally.** A description anchored by neither
+    a subreddit nor a keyword is refused with zero network calls, and `r/all` is dropped as Reddit's
+    site-wide listing rather than sent to earn a `subreddit_reserved` 400.
+  - **Plan awareness is a field read, not a guess.** `GET /api/reddit/monitor/list` is free and its
+    `slots` object states the account's capabilities outright (`scoped_allowed`, `comments_allowed`,
+    `sitewide_allowed`, the cadence floor and the distinct-subreddit allowance). On a plan without
+    subreddit-scoped watches, a description that names subreddits and also carries a keyword is
+    built over every subreddit instead, and the swap is reported; a description with no keyword has
+    no equivalent, so it goes as written and the API answers for itself. An unreadable `slots`
+    object rewrites nothing.
+  - **Ordered for the failure mode.** The monitor is created before the webhook, because a monitor
+    with no `webhook_ids` still delivers to every active webhook on the account, so a watch survives
+    a failed webhook registration. The reverse order would strand a webhook pointing at nothing when
+    the monitor hits a slot limit.
+- **Three playbooks as MCP resources**, at `playbook://competitor-mention-watch`,
+  `playbook://subreddit-audit` and `playbook://pain-point-mining`. Resources rather than tools
+  because the protocol makes resources application-driven: a host reads one only when it is asked
+  for by URI, and nothing is prefetched. Each is built only from calls this package already exposes,
+  and a test checks every tool each playbook names against the live catalog, so a recipe cannot
+  quietly start pointing at something that does not exist.
+- **`reddit_explain`: where the rows you are holding came from.** Per completed call, the tool that
+  made it, the endpoint, when the response arrived, how many seconds old that copy now is, the
+  upstream request id and the response size. It reaches no endpoint: the ledger is in memory, holds
+  the 20 most recent calls, starts empty and is scoped to one server, so one caller's endpoints and
+  request ids never reach another's.
+  - **It reports no cache age, because there is no cache.** The read path holds no response cache for
+    customer reads, so every call is served live and the age that exists is the age of this
+    session's copy of the rows, not of a stored row. The result says `response_cache: "none"` rather
+    than implying a freshness guarantee nothing provides, and it points at the published retention
+    table instead of restating a figure that would drift the day the table changes.
+
+### Changed
+
+- The README's monitoring note said monitors were "subreddit-scoped, posts-only" with "no
+  all-of-Reddit keyword watch, no comment monitoring yet", and that a webhook needs an active plan.
+  All three have been untrue since 2026-08-13 and the note ships in the npm tarball. It now
+  describes the free entitlement, site-wide and comment watching, and the full `slots` object.
+- The catalog test allows a `null` path for a local tool that reaches no endpoint, and for nothing
+  else; a red test proves a non-local tool with no path, and a foreign prefix with or without a
+  local handler, are still refused.
+- The description gate audits resource metadata under the full matcher, and resource bodies for
+  hidden text and external links. Full instruction phrasing stays OFF bodies deliberately: a
+  description is injected at connect time and nobody chose it, a resource is read only when its URI
+  is asked for, and a recipe that could not name the calls it is a recipe for would be useless.
+- **A claim about the body gate was withdrawn, because it was measured and was false.** Its
+  "adversarial steering" check shipped with five planted defects that were its own five regular
+  expressions restated in English. An independent corpus of ten attacks, written attacks-first with
+  the patterns never consulted, is caught **0 of 10**. That number is now asserted in the test, so
+  the limit cannot rot into a capability nobody re-measured. The check is kept as a mechanical
+  tripwire for literal subversion and encoded payloads, and the control that actually fits the risk
+  is now in place: each playbook body's content hash is pinned, so no body can change without the
+  test failing and a human reading the diff.
+
+### No tool was added for the credit balance
+
+`reddit_account_me` already returns `credits_remaining`, `credits_used` and `total_requests`, is
+free, is not metered and is already named in the server instructions. A second tool over the same
+endpoint would be a second name for one job and one more entry competing for attention in the
+catalog, so there is none.
+
 ## 0.9.1 (2026-10-02)
 
 - Feedback reports no longer ask for the user's words: `reddit_feedback_send` `details` is three

package/README.md

@@ -100,7 +100,7 @@ Authentication is a Bearer token: the server sends `Authorization: Bearer <REDDI
 
 ## Tools
 
-44 tools: 30 Reddit reads, 10 monitor/webhook management tools, 3 feedback tools, and 1 account tool (`reddit_account_me`). Reddit writes (posting, commenting, voting, DMs) remain a separate authenticated surface and are intentionally out of scope here -- monitor/webhook tools configure your OWN redditapis.com account (an alerting subscription), never Reddit itself, and the feedback tools send a report to the redditapis.com team, never to Reddit. Every read works with just your API key; the 6 monitor/webhook writes additionally need an active monitoring plan (see Monitoring below). The feedback tools are free and need only your key.
+46 tools and 3 playbook resources: 30 Reddit reads, 10 monitor/webhook management tools, `reddit_set_watch` (one call that stands up a whole watch), `reddit_explain` (where the rows you are holding came from), 3 feedback tools, and 1 account tool (`reddit_account_me`, which is also where the credit balance lives). Reddit writes (posting, commenting, voting, DMs) remain a separate authenticated surface and are intentionally out of scope here -- monitor/webhook tools configure your OWN redditapis.com account (an alerting subscription), never Reddit itself, and the feedback tools send a report to the redditapis.com team, never to Reddit. Every read works with just your API key; the 6 monitor/webhook writes additionally need an active monitoring plan (see Monitoring below). The feedback tools are free and need only your key.
 
 A few conventions across the catalog:
 
@@ -163,10 +163,13 @@ A few conventions across the catalog:
 
 ### Monitoring: manage your own monitors and webhooks
 
-v1 monitors are **subreddit-scoped, posts-only** (no all-of-Reddit keyword watch, no comment monitoring yet). Creating or updating a monitor or webhook needs an active plan; reading your own list/health/deliveries never does.
+Monitors watch **named subreddits or all of Reddit**, for **posts or comments** (`kind`). Every account holds a free entitlement of one all-of-Reddit post watch at a 60s cadence; naming a subreddit, matching comments, a faster cadence and any further watch need a paid plan. Registering a webhook does **not** need a paid plan, because the free watch delivers to one exactly like a paid watch does. Reading your own list, health and deliveries never needs a plan.
+
+`reddit_monitor_list` returns a `slots` object that states this account's capabilities outright: `used`, `total`, `tier`, `is_free`, `cadence_s` (the tier's cadence floor), `sitewide_slots`, `distinct_subreddits_used`, `distinct_subreddits_total`, `comments_allowed`, `scoped_allowed` and `sitewide_allowed`. `reddit_set_watch` reads those flags before it builds anything.
 
 | Tool | Endpoint | What it does |
 |---|---|---|
+| `reddit_set_watch` | `POST /api/reddit/monitor/add` (+ webhook create/update/test) | One call instead of three: compiles a plain-words description into a monitor filter, reads this account's plan capabilities, creates the monitor, then registers, points and test-fires the `deliver_to` webhook. Quoted phrases are taken out of the sentence first, then it is cut into clauses, so each part reads only its own words: subreddits as `r/Name` **or a pasted `reddit.com/r/Name` link**, quoted phrases as keyword terms, `except`/`without`/`ignoring` as exclusions, `at least N upvotes` as a score floor, `comments` / `posts and comments` as the match kind. **It never returns a filter it cannot fully account for** (see below). Returns `understood` and `compiled_filter` so you can check it, and `notes` names anything it dropped, rewrote or read as a whole phrase. |
 | `reddit_monitor_add` | `POST /api/reddit/monitor/add` | Create a monitor: subreddits to watch plus an optional filter (keyword, author, domain, include/exclude terms, min score, NSFW). Forward-looking only from creation (or from `baseline_item_id`). |
 | `reddit_monitor_list` | `GET /api/reddit/monitor/list` | List every monitor on your account, plus `slots` ({used, total, tier}). |
 | `reddit_monitor_update` | `POST /api/reddit/monitor/update` | Pause/resume (`active`), re-cadence, or replace a monitor's filter. Passing any filter field REPLACES the whole filter -- resupply everything you want kept. |
@@ -178,6 +181,38 @@ v1 monitors are **subreddit-scoped, posts-only** (no all-of-Reddit keyword watch
 | `reddit_monitor_webhook_test` | `POST /api/reddit/monitor/webhook/test` | Send a one-off test delivery to confirm a webhook is wired up correctly. |
 | `reddit_monitor_webhook_delete` | `POST /api/reddit/monitor/webhook/delete` | Permanently delete a webhook. Does not cascade-pause monitors still pointing at it. |
 
+#### `reddit_set_watch` refuses rather than guesses
+
+Every character of your description has to be claimed by exactly one thing: a subreddit, a quoted phrase, a keyword, an exclusion, a score clause, a delivery clause, or a word that carries no filter content. Anything left over means the compiler did not understand the whole sentence, and it returns **no filter at all** rather than a monitor built from the half it did understand.
+
+| outcome | when | what you get |
+|---|---|---|
+| a filter | every word is accounted for | the monitor, plus `understood`, `compiled_filter` and `notes` |
+| `partial_understanding` | some words could not be placed, or two parts of the filter counted the same words twice | the exact unplaced words, what *was* understood, and nothing created |
+| `contradictory_filter` | the same phrase is both watched for and excluded, so the monitor could never deliver | both halves named, and nothing created |
+| `no_anchor` | neither a subreddit nor a keyword | a refusal, before any request is sent |
+
+This matters because a wrong watch is **invisible**: you get a monitor id, a green test delivery, and then either silence forever or a firehose. A refusal that names the words it could not place is recoverable in seconds; a monitor whose keyword is also its exclusion is not noticed for a week. If a description is refused, quote the exact phrase to watch for, write subreddits as `r/Name`, or build the filter directly with `reddit_monitor_add`.
+
+### Playbooks: three recipes, served as MCP resources
+
+Three reusable recipes ship as MCP **resources** rather than tools, because the protocol makes resources application-driven: a host shows them in a picker or a search box and reads one only when it is asked for by URI. Nothing is prefetched and nothing is injected.
+
+| URI | What it covers |
+|---|---|
+| `playbook://competitor-mention-watch` | Standing up continuous coverage of competitor names and routing every match to a channel, including how to cut the false positives a brand name that is also an ordinary word produces, and how to tell a quiet monitor from a broken one. |
+| `playbook://subreddit-audit` | Profiling one community before posting in it: size against real comment rate, the rules as written and as enforced, the moderator team, what endures versus what is working this month, and whether posts survive. |
+| `playbook://pain-point-mining` | Finding problems in the words people actually use, from comment bodies rather than post titles, ranking them by distinct authors rather than hits, and turning a one-off sweep into a standing feed. |
+
+Each is a short markdown document built only from calls this package already exposes, so a recipe cannot point at something unbuilt. A test checks every tool each playbook names against the live catalog.
+
+The bodies are documentation and name the calls they are recipes for, which is the point of them. That is a deliberate difference from tool **descriptions**, which a client fetches at connect time and nobody chose: those state product facts only and a gate enforces it. A resource is read only when something asks for its URI, so it is a document you opened, not an injection. The bodies are still checked for hidden or encoded text, for any link off our own hosts, and for adversarial steering (overriding your instructions, concealment, exfiltration, or spending your credits in a loop), each with a planted-defect control.
+
+```jsonc
+// resources/list, then
+{ "method": "resources/read", "params": { "uri": "playbook://subreddit-audit" } }
+```
+
 ### Feedback: tell the team what broke, after you review the draft
 
 Modelled on Claude Code's own feedback tool. When a call fails in a way that is not your key, credits or a rate limit, when you ask for something no tool covers, or when a result is plainly wrong, the model can **draft** a report into a local queue (`~/.redditapis/feedback-queue.json`, at most 10 drafts, override the directory with `REDDITAPIS_FEEDBACK_DIR`). Nothing is sent until you ask to review the queue and name the drafts to send. Each report carries the last failing call's endpoint, status and request id, your client name and this package's version, so the team can act on it without a follow-up. Use `reddit_feedback_get` with the returned server id to see whether it was triaged, shipped or declined. Both tools are free.
@@ -185,6 +220,7 @@ Modelled on Claude Code's own feedback tool. When a call fails in a way that is
 | Tool | Endpoint | What it does |
 |------|----------|--------------|
 | `reddit_feedback_send` | `POST /feedback` | `action: "draft"` (default) queues a report locally and sends nothing; `"list"` shows the queue; `"send"` posts only the drafts you name; `"discard"` drops them. |
+| `reddit_explain` | none (in-process) | Provenance for the rows already fetched in this session: per completed call, the tool, the endpoint, when the response arrived, how old that copy now is, the upstream request id and the response size. The read path holds no response cache, so the age is the age of your copy, not of a stored row. |
 | `reddit_account_me` | `GET /account/me` | How much credit this key has left, before spending any. Free, never metered. |
 | `reddit_feedback_get` | `GET /feedback/{id}` | Read a sent report's status (`new`, `triaged`, `shipped`, `declined`) and the team's response. |
 
@@ -281,6 +317,8 @@ Reads need nothing but your API key -- no account linking, login, or cookie step
 
 **`HTTP 429 (rate limited)`** Wait a few seconds and retry, or reduce request frequency. For bulk work, space out calls and raise `REDDITAPIS_TIMEOUT_MS`.
 
+**`HTTP 408 (upstream_timeout)`** The read did not finish in time and was not billed. The server already retried once after `retry_after`; call the tool again shortly. A `503 upstream_unavailable` on a read gets the same one retry.
+
 **`Request failed: timed out after 30000ms`** The default timeout is 30 seconds. For large `reddit_deep_comment_search` or paginated fetches, set `REDDITAPIS_TIMEOUT_MS` higher (for example `60000`).
 
 **Tools do not appear in Claude / Cursor** Ensure `npx` is on your PATH and Node.js 18+ is installed (`node --version`). Check your MCP client logs for startup errors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redditapis-mcp",
-  "version": "0.9.1",
+  "version": "0.10.2",
   "mcpName": "io.github.redditapis/redditapis-mcp",
   "description": "Official MCP server for redditapis.com. Search Reddit posts, comments, communities, users and media; read subreddits, comment trees, top posts and profiles; create and manage monitors and webhooks. Native tools for Claude, Cursor and any MCP client.",
   "repository": {
@@ -30,8 +30,8 @@
   },
   "scripts": {
     "start": "node src/index.js",
-    "check": "node --check src/index.js && node --check src/tools.js && node --check src/feedback.js",
-    "test": "node test/tools.test.mjs && node test/description-compliance.test.mjs && node test/inline-credentials.test.mjs && node test/feedback.test.mjs && node test/index-lasterror.test.mjs && node test/scannable-without-key.test.mjs && node test/per-caller-state.test.mjs && node test/paywall.test.mjs && node test/remote-host.test.mjs",
+    "check": "node --check src/index.js && node --check src/tools.js && node --check src/feedback.js && node --check src/server.js && node --check src/watch.js && node --check src/watch-text.js && node --check src/provenance.js && node --check src/playbooks.js",
+    "test": "node test/tools.test.mjs && node test/watch.test.mjs && node test/watch-invariants.test.mjs && node test/provenance.test.mjs && node test/playbooks.test.mjs && node test/description-compliance.test.mjs && node test/inline-credentials.test.mjs && node test/feedback.test.mjs && node test/index-lasterror.test.mjs && node test/scannable-without-key.test.mjs && node test/per-caller-state.test.mjs && node test/paywall.test.mjs && node test/remote-host.test.mjs",
     "prepublishOnly": "node scripts/prepublish-tenant-check.mjs",
     "postpublish": "node scripts/registry-drift.mjs --publish",
     "check:registry-drift": "node scripts/registry-drift.mjs"

package/src/playbooks.js

@@ -0,0 +1,156 @@
+// src/playbooks.js, three reusable recipes served as MCP RESOURCES.
+//
+// WHY RESOURCES AND NOT TOOLS. The MCP specification says resources are
+// "application-driven, with host applications determining how to incorporate
+// context": a host shows them in a picker, a search box, or includes them at
+// its own discretion. That is exactly the right primitive for a recipe. A
+// recipe turned into a tool would be a tool whose job is to tell the model what
+// to do, which is both the wrong shape and the thing the connector directory's
+// compliance requirement asks tool descriptions not to be.
+//
+// WHERE THE COMPLIANCE LINE SITS, stated plainly because the two halves of this
+// file are governed by different rules:
+//
+//   RESOURCE METADATA (name, title, description, mimeType) is catalog metadata,
+//   the same class as a tool description, and it is audited by
+//   test/description-compliance.test.mjs under the same matcher. It states what
+//   the recipe is about and nothing more.
+//
+//   RESOURCE CONTENTS are the document itself, fetched only when a host or a
+//   person asks for that exact URI by name. A recipe that could not name the
+//   calls it is a recipe for would be useless, so the contents do name tools.
+//   They carry no hidden or encoded text and no link off our own hosts, and the
+//   compliance test checks both of those over the contents too.
+//
+// NOTHING HERE IS PREFETCHED. A resource is read only on an explicit
+// resources/read for its URI.
+//
+// EVERY RECIPE USES CALLS THAT ALREADY SHIP. No playbook depends on a capability
+// this package does not already expose, so a recipe cannot go stale by pointing
+// at something unbuilt.
+
+export const PLAYBOOK_SCHEME = "playbook";
+
+/**
+ * The three playbooks. `description` is catalog metadata and is held to the
+ * same standard as a tool description; `body` is the document.
+ */
+export const PLAYBOOKS = [
+  {
+    slug: "competitor-mention-watch",
+    name: "competitor_mention_watch",
+    title: "Competitor mention watch",
+    description:
+      "A recipe for standing up a continuous watch on competitor names across Reddit and routing every match to a channel, written against the monitor and webhook calls this server already exposes.",
+    body: `# Competitor mention watch
+
+Continuous coverage of what Reddit says about a set of competitor names, delivered to a channel instead of read by hand.
+
+## What this produces
+
+One monitor per competitor name, each delivering to one webhook, so a match arrives with the post, the subreddit, the author and the permalink already attached.
+
+## Steps
+
+1. **Fix the name list.** One monitor per name beats one monitor with every name in it: deliveries stay attributable, and a noisy name can be paused on its own with \`reddit_monitor_update\` and \`active: false\`.
+2. **Register the destination once.** \`reddit_monitor_webhook_create\` with the channel's incoming-webhook URL. A \`hooks.slack.com\` or \`discord.com/api/webhooks\` URL has its payload shape inferred from the host. The signing secret is returned once and never again, so store it with the webhook id.
+3. **Create each watch.** \`reddit_set_watch\` with a sentence naming the competitor in quotes, and \`deliver_to\` set to the same URL. It compiles the sentence, reads the plan's capabilities, creates the monitor, registers and points the delivery target, and test-fires it in one call.
+4. **Cut the false positives.** A brand name that is also an ordinary word produces noise. Two controls, both on \`reddit_monitor_update\`: \`exclude_terms\` drops matches containing a term, and \`search_in: ["title", "body"]\` stops a term matching only inside a URL slug. On a plan that carries it, \`min_relevance\` scores each match against the monitor's own keywords and records what it withheld rather than discarding it silently.
+5. **Confirm it is actually watching.** \`reddit_monitor_health\` for each monitor. Read \`stream_liveness\` first: a feed that is never polled writes nothing to the poll log and looks identical to a quiet subreddit. Then \`coverage_24h\`. A status of \`unknown\` or \`partial\` means the question went unanswered, not that nothing was missed.
+6. **See what landed.** \`reddit_monitor_deliveries\` returns the actual items sent, each with a relevance score, a sentiment reading and an intent tag.
+
+## Reading a quiet monitor
+
+A delivered count far below a matched count is usually the freshness gate, not a fault: \`suppressed_breakdown\` in monitor health splits \`ceiling\` (the daily cap) from \`stale\` (the item was already old when first seen). A \`stale\` withhold cannot be recovered by retrying.
+
+## Backfill
+
+A monitor is forward-looking from the moment it is created. For what was said before that, \`reddit_search\` with \`sort: "relevance"\` and a \`t\` window, and \`reddit_deep_comment_search\` for the comment bodies rather than their parent posts.
+`,
+  },
+  {
+    slug: "subreddit-audit",
+    name: "subreddit_audit",
+    title: "Subreddit audit",
+    description:
+      "A recipe for profiling one subreddit before posting in it: size and activity, the rules as written, the moderator team, what the top posts look like and how fast the comment feed moves.",
+    body: `# Subreddit audit
+
+A profile of one community, built before anything is posted into it, from the calls this server already exposes.
+
+## Steps
+
+1. **Size and shape.** \`reddit_subreddit_about\` returns subscribers, active users, creation date, type and the NSFW flag. Subscriber count alone says little: a community of 800,000 with a slow comment feed behaves nothing like one of 40,000 with a fast one.
+2. **The rules as written.** \`reddit_subreddit_rules\` returns each rule with what it applies to (posts, comments or all) plus Reddit's site-wide rules. Most self-promotion bans live here in the subreddit's own words.
+3. **The rules as enforced.** \`reddit_subreddit_wiki\` with \`page: "index"\`, and where it exists \`page: "rules"\`. A wiki commonly carries the longer version and the exceptions the short rule list leaves out.
+4. **Who enforces them.** \`reddit_subreddit_moderators\` returns the team with each moderator's permissions and when they joined. A team of one, or a team whose newest member joined years ago, is a different moderation posture from an active rota.
+5. **What does well.** \`reddit_subreddit_top\` with \`t: "month"\` and again with \`t: "year"\`. The month view is the current format; the year view is what endures.
+6. **What is being posted now.** \`reddit_subreddit_posts\` with \`sort: "new"\` for the unfiltered intake, and \`sort: "rising"\` for what the community is picking up this hour.
+7. **How fast the room moves.** \`reddit_subreddit_comments\` streams the newest comments across the whole subreddit. Two calls a few minutes apart give the real comment rate, which decides whether a post has hours of visibility or minutes.
+8. **Whether posts survive.** \`reddit_post_visibility\` on a handful of the newest posts. A removed post still returns when fetched by id, so the post alone does not answer this. A verdict of \`undecidable\` is a real answer.
+
+## Reading the result
+
+A high subscriber count with a slow comment feed and a strict rule list is a read-only community. A moderate count with a fast feed and a short rule list is where a question gets answered.
+
+## Related communities
+
+\`reddit_search_communities\` on the same topic finds the smaller rooms where the same conversation happens with less competition.
+`,
+  },
+  {
+    slug: "pain-point-mining",
+    name: "pain_point_mining",
+    title: "Pain-point mining",
+    description:
+      "A recipe for finding the problems people describe in their own words on Reddit, ranking them by how often they recur, and identifying who keeps raising them.",
+    body: `# Pain-point mining
+
+The problems a market describes in its own words, taken from comment bodies rather than post titles.
+
+## Why comments
+
+A post title is written to attract attention. A comment is written to answer somebody. The sentence that names a real problem is almost always in a comment, which is why this recipe leans on comment search rather than post search.
+
+## Steps
+
+1. **Start from complaint-shaped language, not product names.** Phrases such as "I gave up on", "the worst part of", "is there anything that", "I still do this manually" find problems; a product name finds opinions about a product.
+2. **Read the comments themselves.** \`reddit_deep_comment_search\` returns the matching comment bodies with their score, author and a comment-deep permalink. \`reddit_search_comments\` returns only the parent posts, which loses the sentence. Set \`limit\` to how many parent posts to expand, and \`sort: "relevance"\` with a \`t\` window so old high-score threads do not crowd out current ones.
+3. **Find who keeps saying it.** The same call with \`group_by: "author"\` returns the distinct people ranked by how many of their comments matched, with the subreddits they matched in and their top comment. A problem three hundred people mention once is a different finding from one thirty people mention repeatedly.
+4. **Scope it to a community when the general search is too noisy.** \`reddit_search\` with \`subreddit\` set narrows the matching set itself, which a sort change cannot do.
+5. **Read the whole thread for the best hits.** \`reddit_post_comments\` with the permalink returns the post and its comment tree, which is where the workaround people settled on usually sits.
+6. **Check the person is real.** \`reddit_user_profile\` for account age and karma, \`reddit_user_comments\` for whether this is a recurring subject for them or a one-off.
+7. **Keep it running.** \`reddit_set_watch\` with the complaint phrase in quotes turns a one-off sweep into a standing feed, and \`kind\` set to comments matches where this language actually appears.
+
+## Ranking what comes back
+
+Three signals, in order: how many distinct authors raised it, whether the thread reached a workaround or stopped at the complaint, and whether it recurs across subreddits or lives in one. A problem that appears in several unrelated communities is a market, not a niche.
+
+## A caution on counts
+
+A search result page is bounded by \`limit\` and a null \`after\` does not mean the listing is complete. The response carries \`listing_status\`, and only \`complete\` means nothing is missing. A frequency count taken from a truncated page is a count of that page.
+`,
+  },
+];
+
+export function playbookUri(slug) {
+  return `${PLAYBOOK_SCHEME}://${slug}`;
+}
+
+/**
+ * Register every playbook on an McpServer. Called by createServer, which is
+ * what makes them part of the same catalog every caller receives.
+ */
+export function registerPlaybooks(server) {
+  for (const p of PLAYBOOKS) {
+    server.registerResource(
+      p.name,
+      playbookUri(p.slug),
+      { title: p.title, description: p.description, mimeType: "text/markdown" },
+      async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: "text/markdown", text: p.body }],
+      }),
+    );
+  }
+  return PLAYBOOKS.length;
+}

package/src/provenance.js

@@ -0,0 +1,124 @@
+// src/provenance.js, the local half of reddit_explain.
+//
+// WHAT A ROW'S PROVENANCE ACTUALLY IS ON THIS PRODUCT, measured rather than
+// assumed, because the honest answer turned out to be the opposite of the
+// obvious one.
+//
+// The plan this tool came from specified "cache age" as the field to surface.
+// There is no cache to age. The redditapis.com read path holds no response
+// cache for customer reads: the whole customer read path (routes/reddit.js and
+// services/reddit/client.js on origin/main) carries exactly one `cache`
+// mention and it is about which egress path to use, not about response bodies;
+// there is no Redis, memcached, LRU or keyv dependency in either service. That
+// was re-derived with a positive control in the 2026-09-27 implementation spec,
+// and it is visible from this side too: no response this client receives
+// carries a cache header, an age field or a fetched-at stamp. A "cache hit" and
+// a "cache miss" are the same code: a live fetch.
+//
+// SO THE AGE THAT EXISTS IS REAL, AND IT IS NOT A CACHE AGE. A row an agent is
+// holding was fetched at a particular instant by a particular call in this
+// session, and it has been getting older ever since. That instant is something
+// this process observed directly, so it can be reported without inventing
+// anything: the ledger below records, for every call that succeeded, which tool
+// made it, which endpoint it reached, when the response arrived, the upstream
+// request id and how many bytes came back. reddit_explain reads that back.
+//
+// WHAT IT DELIBERATELY DOES NOT DO: it does not claim a cache age, and it does
+// not restate a retention period. The retention table is published and is the
+// emitting system for that fact; a number copied into a tool description drifts
+// silently the day the table changes, so the description points at the page.
+//
+// SCOPE. The ledger is per server, which is per caller, for the same reason
+// every other piece of state in this package is: served remotely, one process
+// serves many callers, and a shared ledger would hand one caller's endpoints
+// and request ids to another. It lives in memory only and starts empty.
+
+export const LEDGER_CAP = 20;
+
+/** A bounded, newest-first ledger of the calls one server has completed. */
+export function createReadLedger({ cap = LEDGER_CAP, now = () => Date.now() } = {}) {
+  const entries = [];
+  return {
+    record(entry) {
+      if (!entry || typeof entry.tool !== "string") return;
+      entries.unshift({
+        tool: entry.tool,
+        endpoint: entry.path ?? null,
+        method: entry.method || "GET",
+        observed_at_ms: now(),
+        request_id: entry.requestId ?? null,
+        bytes: Number.isFinite(entry.bytes) ? entry.bytes : null,
+      });
+      if (entries.length > cap) entries.length = cap;
+    },
+    list() {
+      return entries.slice();
+    },
+    get size() {
+      return entries.length;
+    },
+  };
+}
+
+// Stated once, used in the result. Each clause is a fact about this product's
+// read path, not advice.
+export const FRESHNESS = Object.freeze({
+  source: "reddit.com, fetched through api.redditapis.com at the moment the call ran",
+  response_cache: "none",
+  response_cache_detail:
+    "The redditapis.com read path holds no response cache for customer reads, so every call is served live and the age below is the age of this session's copy of the rows, not the age of a stored row.",
+  retention_policy_url: "https://www.redditapis.com/privacy-and-data-handling",
+});
+
+/**
+ * Build the reddit_explain handler.
+ *
+ * @param {object} deps
+ * @param {() => Array} deps.listReads  reads the server's ledger
+ * @param {() => number} [deps.now]     injectable clock, for tests
+ */
+export function createExplainHandler({ listReads, now = () => Date.now() }) {
+  return async function explain(args = {}) {
+    const { tool, limit } = args;
+    const t = now();
+    let rows = listReads();
+    if (typeof tool === "string" && tool.length) rows = rows.filter((r) => r.tool === tool);
+    const n = Number.isFinite(limit) ? Math.max(1, Math.min(LEDGER_CAP, Math.trunc(limit))) : 5;
+    rows = rows.slice(0, n);
+
+    const calls = rows.map((r) => ({
+      tool: r.tool,
+      endpoint: r.endpoint,
+      method: r.method,
+      observed_at: new Date(r.observed_at_ms).toISOString(),
+      age_seconds: Math.max(0, Math.round((t - r.observed_at_ms) / 1000)),
+      request_id: r.request_id,
+      response_bytes: r.bytes,
+    }));
+
+    const payload = { calls, call_count: calls.length, ...FRESHNESS };
+
+    const head = calls.length
+      ? calls
+          .map(
+            (c) =>
+              `${c.tool} reached ${c.method} ${c.endpoint} at ${c.observed_at}, ${c.age_seconds}s ago` +
+              `${c.request_id ? `, upstream request id ${c.request_id}` : ""}` +
+              `${c.response_bytes != null ? `, ${c.response_bytes} bytes` : ""}.`,
+          )
+          .join(" ")
+      : tool
+        ? `No completed call by ${tool} is recorded in this session.`
+        : "No completed call is recorded in this session yet; the ledger starts empty and fills as tools run.";
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${head} ${FRESHNESS.response_cache_detail} Retention by category is published at ${FRESHNESS.retention_policy_url}.\n\n${JSON.stringify(payload)}`,
+        },
+      ],
+      structuredContent: payload,
+    };
+  };
+}