@buildinternet/releases-skills 0.45.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-skills",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "description": "Agent skills bundled with the Releases CLI. Markdown playbooks for changelog ingest, discovery, and analysis.",
   "type": "module",
   "license": "MIT",

package/skills/analyzing-releases/SKILL.md

@@ -13,16 +13,20 @@ description: >
 
 Turn changelog data into competitive intelligence by analyzing release patterns across a cohort of related companies.
 
-## Key Operations
+This is a **reader** workflow — it uses only the public, unauthenticated tools. There is no AI summarize/compare tool on the hosted MCP and no `summary`/`compare` command in the CLI; you fetch the raw release data and synthesize the analysis yourself.
 
-| Operation | CLI | Typed tool |
-|-----------|-----|------------|
-| Check existing sources | `releases list --query <company> --json` | `list_catalog` with query param; `list_sources` is a deprecated alias |
-| Fetch releases | `releases admin source fetch <slug> --max 50` | `manage_source` action "fetch" with identifier (ID or slug) |
-| Get latest releases | `releases tail <slug> --json` | `get_latest_releases` with source/org and limit |
-| Search releases | `releases search <query> --json` | `search` with `type: ["releases"]`; `search_releases` is a deprecated alias |
-| Summarize | `releases summary <slug> --json` | (not available as typed tool) |
-| Compare | `releases compare <slugA> <slugB> --json` | (not available as typed tool) |
+## Tools for each step
+
+| Operation | CLI (reader) | MCP tool |
+|-----------|--------------|----------|
+| Find what's indexed for a company | `releases search <company> --json` | `search` (with `type: ["orgs","catalog"]`) |
+| List a company's sources | `releases list --query <company> --json` | `list_catalog` (scope with `organization`) |
+| Latest releases (source or org) | `releases tail <slug> --json` · `releases tail --org <org> --json` | `get_latest_releases` (`organization` / `product`, `since`/`until`) |
+| Keyword/semantic release search | `releases search <query> --json` | `search` with `type: ["releases"]` |
+| Read one release in full | `releases get <rel_id> --json` | `get_release` |
+| Read a tracked CHANGELOG slice | `releases admin source changelog <slug> --tokens <n>` (key-gated; readers use MCP) | `get_catalog_entry` with `changelog_tokens` / `changelog_offset` (keyless) |
+
+All releases are indexed already — you don't need to (and as a reader can't) trigger fetches. If a company isn't in the registry at all, say so rather than trying to onboard it; onboarding is an operator task.
 
 ## Workflow
 
@@ -30,45 +34,40 @@ Turn changelog data into competitive intelligence by analyzing release patterns
 
 Pick 3-6 companies in the same competitive space. Good cohorts share a common buyer or technical layer (e.g., developer databases, frontend frameworks, observability tools).
 
-### 2. Check existing sources
-
-Search for each company to see what sources are indexed. If a company isn't in the system, it needs to be onboarded first.
-
-### 3. Fetch recent releases
+### 2. See what's indexed
 
-Fetch each source. The system skips unchanged feeds automatically.
+Resolve each company with `search` (or `releases search`). For discovery-style cohorts ("find observability vendors with edge offerings"), `search` with `type: ["orgs","catalog"]` is vector-backed and matches on description and category — better than a slug-substring `list_catalog --query`. If a company isn't found, note it as a gap rather than fabricating data.
 
-### 4. Get latest releases
+### 3. Pull latest releases with dates
 
-Get structured release data with dates for each source. Use a limit (e.g., 50) to cap results. For org-wide views, filter by organization instead of individual source.
+Get structured release data per source or per org. Scope by `organization` for a whole-company view, or by a single source/product for a narrower one. Use a `since` window (e.g. `"6m"`) or a count limit to bound the set. Dates are what you'll count for velocity, so keep them.
 
-### 5. Search and cross-reference
+### 4. Search and cross-reference
 
-Search across all indexed releases to find specific features, breaking changes, or patterns. The unified `search` tool (with `type: ["releases"]`) is hybrid (lexical + semantic) by default — natural-language queries like "auth refresh tokens" or "cold start improvements" work without exact keyword matches. Pass `mode: "lexical"` if you need strict keyword behavior.
+Search across all indexed releases to find a specific feature, breaking change, or pattern. Release search is hybrid (lexical + semantic) by default, so natural-language queries like "auth refresh tokens" or "cold start improvements" work without exact keyword matches. Pass `mode: "lexical"` (CLI `--mode lexical`) when you need strict keyword behavior.
 
 **Result shape:** every hit carries a `kind` discriminator:
-- `kind: "release"` — a normal release row, use as-is.
-- `kind: "changelog_chunk"` — a passage from a stored CHANGELOG.md file. The hit includes `sourceSlug`, `chunkOffset`, and `chunkLength`. Chain into `get_source_changelog({ slug: sourceSlug, offset: chunkOffset, limit: chunkLength * 3 })` to read the surrounding section before quoting it. Chunk hits often surface older or more granular notes than what's in the indexed release rows, so they're useful for "when did X first ship" questions.
 
-For org/product/source discovery (e.g. "find observability vendors with edge offerings"), use `search` with `type: ["orgs", "catalog"]` instead of `list_catalog --query` — it's vector-backed and matches on description and category, not just slug substring.
+- `kind: "release"` — a normal release row; use it directly.
+- `kind: "changelog_chunk"` — a passage from a stored CHANGELOG.md. The hit includes the source id and the chunk's `offset` and `length`. To read the surrounding section before quoting, call `get_catalog_entry` with that source id and `changelog_offset` set to the chunk offset (add `changelog_tokens`, e.g. 2000, for a heading-aligned slice). Chunk hits often surface older or more granular notes than the indexed release rows, so they're useful for "when did X first ship" questions.
 
-### 6. Synthesize
+### 5. Synthesize
 
-Combine summaries and comparisons into a structured analysis:
+Combine the raw data into a structured analysis:
 
-- **Release velocity table** — releases per company, cadence pattern
+- **Release velocity table** — releases per company over the window, cadence pattern
 - **Trends adopted across the board** — features 3+ companies shipped in the same window
 - **Differentiating bets** — what each company is investing in that others aren't
-- **Gaps** — what competitors shipped that a company hasn't
-- **Forecasts** — specific predictions based on pre-release tracks, deprecations, and trajectory
+- **Gaps** — what competitors shipped that a given company hasn't
+- **Forecasts** — predictions grounded in pre-release tracks, deprecations, and trajectory
 
 ## Output
 
-Ask the user where to save the analysis, or use your best judgment based on the project's conventions. Include a "Process Notes" section documenting which CLI commands were used so the analysis is reproducible.
+Ask the user where to save the analysis, or use your best judgment based on the project's conventions. Include a short "Process Notes" section listing the exact commands/tools used, so the analysis is reproducible.
 
 ## Important
 
-- Focus on what companies shipped. If a source has noisy data (blog posts mixed in, missing dates), work around it silently. Don't include source quality commentary in the report unless a company had to be substantially excluded.
-- Fill data gaps with web fetches. List sources to get release URLs, then WebFetch to spot-check pages for missing dates, versions, or feature details.
-- For velocity counting, get the latest releases with dates — CLI: `releases tail <slug> --json`, typed tool: `get_latest_releases`.
-- AI-powered summarize and compare are only available via CLI (`releases summary`, `releases compare`). When using typed tools, synthesize manually from raw release data.
+- Focus on what companies shipped. If a source has noisy data (blog posts mixed in, missing dates), work around it silently — don't pad the report with source-quality commentary unless a company had to be substantially excluded.
+- Fill data gaps with web fetches: list a source to get release URLs, then WebFetch to spot-check pages for a missing date, version, or detail.
+- For velocity counting, lean on the dated rows from `get_latest_releases` / `releases tail --json`.
+- Comparison and summarization are yours to synthesize from raw release data — there is no built-in tool that does it for you.

package/skills/releases-cli/SKILL.md

@@ -1,102 +1,62 @@
 ---
 name: releases-cli
-description: Use the `releases` CLI to search, inspect, and manage the Releases.sh changelog registry from the terminal. Activate when the user mentions "releases CLI", runs a `releases` command, asks how to install the CLI, or wants to add/edit/fetch sources or organizations programmatically.
+description: Use the `releases` CLI to search, browse, and read the Releases.sh changelog registry from the terminal — the keyless, agent-friendly peer of the Releases MCP. Activate when the user mentions "releases CLI", runs a `releases` command, asks how to install it, or wants to look up releases, sources, orgs, collections, or changelogs from a shell.
 ---
 
 # releases CLI
 
-The `releases` CLI does two things: lets anyone search and browse the public changelog registry at [releases.sh](https://releases.sh), and lets API-key holders manage orgs, products, sources, and releases through `releases admin` subcommands.
+The `releases` CLI is a first-class, **keyless** way to query the public changelog registry at [releases.sh](https://releases.sh) — the terminal peer of the Releases MCP. Anyone can search, tail, list, and inspect releases with no account and no API key; it talks to `api.releases.sh` by default with zero configuration. (A separate, invite-only `admin` surface exists for maintainers — see the short note at the end — but reads never need it.)
+
+Reach for the CLI when the user is working in a shell or wants piped/scriptable output; reach for the MCP when you're answering conversationally with typed tools. They cover the same registry.
 
 ## Install
 
 ```bash
 brew install buildinternet/tap/releases    # recommended on macOS / Linux
-npm install -g @buildinternet/releases     # or via npm
-```
-
-Or run one-off without installing:
-
-```bash
-npx @buildinternet/releases search "react"
+npm install -g @buildinternet/releases      # or via npm
+npx @buildinternet/releases search "react"  # one-off, no install
 ```
 
-The CLI talks to `api.releases.sh` by default — no configuration needed for reader commands.
-
-### Refreshing this skill
+## Reader commands (no auth, no key)
 
-To install or refresh the bundled releases skills (this one + `releases-mcp`, `finding-changelogs`, etc.) for any supported agent:
+Full reference: **[references/reader.md](references/reader.md)**. The shape is verb-first, and every command takes `--json`.
 
 ```bash
-releases skills install        # detected agent (auto), current project
-releases skills install -g     # user-wide install instead
+releases search "breaking change"      # unified search: orgs, catalog, collections, releases
+releases tail next-js                  # latest releases from one source (slug or src_…)
+releases tail --org vercel --count 20  # latest across a whole org
+releases list --category ai            # browse sources (alias: `releases sources`)
+releases list --query shadcn           # name / slug / url substring
+releases get vercel                    # inspect any entity by id or slug
+releases lookup domain vercel.com      # resolve a domain/URL to its registry entry
+releases collection list               # browse curated cross-org playlists
+releases collection releases frontier-ai-labs   # the feed for one collection
+releases stats                         # registry overview
+releases categories                    # valid --category values (fixed taxonomy)
 ```
 
-Skills are symlinked by default — re-running `releases skills install` refreshes everything atomically.
+Two commands built for agents specifically:
 
-## Command shape
+- `releases agent-context` — emits a versioned JSON document describing every command, argument, and option. When in doubt about exact flags, call this instead of guessing; it's the CLI's machine-readable source of truth.
+- `releases skills install` — installs/refreshes the bundled skills (`-g` for user-wide). Symlinked by default, so re-running refreshes atomically.
 
-- **Reads (verb-first):** `releases list` · `releases search` · `releases tail` · `releases get` · `releases stats`
-- **Writes (`admin <noun> <verb>`):** `releases admin source update` · `releases admin source create` · `releases admin product create` · `releases admin org create`
-- List sources with `releases list` (also `releases sources` — alias). Do NOT guess `releases sources list`; that path does not exist.
-- Writes live under `releases admin <noun> <verb>`, not at the top level.
+### Conventions worth knowing (all in the reader reference)
 
-## What this skill covers
-
-- **[Reader commands](references/reader.md)** — Search, inspect, and export changelog data. No API key required.
-- **[Admin commands](references/admin.md)** — Add/edit sources, manage orgs and products, fetch releases, run policies. Requires `RELEASES_API_KEY`.
-
-## Quick Reference
-
-```bash
-# Reader (no auth required)
-releases search "breaking change"               # hybrid FTS + semantic search
-releases tail next-js                           # latest releases from one source
-releases tail src_abc123                        # IDs work anywhere a slug does
-releases tail --org vercel --count 20           # latest from a whole org
-releases list --category ai                     # browse sources
-releases get vercel                             # dispatch by id or slug
-releases get org_abc123                         # typed IDs are accepted
-releases stats                                  # registry overview
-releases categories                             # list valid category values
-
-# Admin (requires RELEASES_API_KEY)
-releases admin source create "Linear" --url https://linear.app/changelog
-releases admin source fetch <source> --max 50   # source = src_… or slug
-releases admin org create "Acme" --category cloud
-releases admin product create "CLI" --org acme  # --org accepts org_…, slug, domain, name, or handle
-releases admin discovery onboard "Stripe"       # AI-powered discovery agent
-
-# Local stdio MCP bridge (proxies to api.releases.sh)
-releases admin mcp serve
-```
+- **IDs and slugs are interchangeable** wherever an identifier is expected (`org_…`, `prod_…`, `src_…`, `rel_…`); IDs are stable across renames. Source/product commands also take an `org/slug` coordinate (e.g. `vercel/vercel-ai-sdk`), which skips a resolver round-trip.
+- **`--json` everywhere** for stable output. Release readers (`get`, `search`, `tail`) return a **slim** shape by default (core fields + markdown-stripped `excerpt` + `contentTokens` hint) to save tokens; pass `--full` for the complete payload. (`list` is the inverse: verbose by default, `--compact` for less.)
+- **Piped output is bare TSV** (no headers/color/truncation), so `releases list | cut -f2` works without parsing ANSI — but note release rows repeat the title across several columns, so check the layout or just use `--json` before slicing by column number. `COLUMNS=<n>` overrides detected width.
 
-Every command that takes an org / product / source / release identifier accepts the typed ID (`org_…`, `prod_…`, `src_…`, `rel_…`) interchangeably with the slug — including `--org`, `--product`, `--source` flags. IDs are stable across renames; slugs are friendlier to type. Source and product commands also accept an `org/slug` coordinate (e.g. `vercel/vercel-ai-sdk`); coordinates and typed IDs are unambiguous and skip an extra resolver round-trip that bare slugs require. Every reader command accepts `--json` for machine-readable output.
+### Reading a tracked changelog
 
-Tabular reader commands fit themselves to the terminal width when stdout is a TTY (column truncation with `…`) and switch to bare TSV (no headers, no color, no truncation) when stdout is piped — so `releases org list | cut -f2` works without parsing ANSI. Set `COLUMNS=<n>` to override the detected width. Use `--json` whenever you need stable, complete output for parsing.
+`releases get <source> --json` reports `hasChangelogFile` and the `changelogUrl` keyless, so you can tell whether a source maintains a checked-in CHANGELOG.md. To read the **sliced content** keyless, use the MCP's `get_catalog_entry` (with `changelog_tokens` / `nextOffset`) or fetch the `changelogUrl` directly — the CLI's `releases admin source changelog` wrapper is key-gated and won't run without auth.
 
-The release readers (`get`, `search`, `tail`/`latest`) return a **slim** JSON shape by default — core fields plus a markdown-stripped `excerpt` and `contentChars`/`contentTokens` size hints — to keep agent token usage down; pass `--full` for the complete payload. (This is the inverse of `list`, which is verbose by default with an opt-in `--compact`.) See `references/reader.md`.
-
-Every mutating admin command accepts `--dry-run` to print the planned write (with all validations applied) without calling the API. Pair with `--json` for a machine-readable plan. See `references/admin.md` for the full coverage list.
-
-## Authentication
-
-Reader access is unauthenticated and may be rate-limited per IP.
-
-**Admin access is closed beta.** `releases admin …` commands require a Bearer token, but the hosted registry does not currently expose a self-serve flow for generating keys — an external user cannot create one on their own. If the user asks how to get an API key, explain this and point them at the project repo to request access. Don't invent a signup URL.
-
-If a key is available:
-
-```bash
-export RELEASES_API_KEY=your_key
-export RELEASES_API_URL=https://api.releases.sh   # optional, this is the default
-```
+## Common Mistakes
 
-These can also go in a `.env` file — Bun auto-loads it when running from source.
+- `releases list` lists sources (alias `releases sources`). Do NOT write `releases sources list` — it reads `list` as a source slug and fails with "Source not found: list".
+- Default read cap is 200 releases per source; use `--max <n>` or `--all` to override.
+- There is **no** `summary` or `compare` command in this CLI, and **no** AI summarization tools on the hosted MCP (`summarize_changes` / `compare_products` do not exist). To summarize or compare, read each entity with `releases get` / `releases tail` (or `--json`) and synthesize the answer yourself.
+- Don't reach for `admin` commands to do reads — every read above is keyless. `admin` is only for registry maintenance and requires a key (below).
 
-## Common Mistakes
+## Admin surface (invite-only — reads never need it)
 
-- `releases admin …` without `RELEASES_API_KEY` set fails fast with a clear error — don't retry the same command. Note that keys are not self-serve yet (see Authentication).
-- Slug renames (`admin source update <identifier> --slug new-slug`) require `--confirm-slug-change` because they break web links.
-- `releases admin source fetch` with no source or filter is blocked in remote mode. Use `--stale`, `--unfetched`, `--retry-errors`, `--changed`, or a source identifier (src_… or slug).
-- Default fetch cap is 200 releases per source (GitHub pagination limits). Use `--max <n>` or `--all` to override.
-- `summary` and `compare` are *not* in this CLI. Those commands require AI provider calls and live in the private maintainer tooling. Use the hosted MCP tools `summarize_changes` / `compare_products` at `mcp.releases.sh` instead.
+`releases admin <noun> <verb>` manages the registry (create/update sources, orgs, products; fetch; discovery; policies). It requires `RELEASES_API_KEY`, and **keys are not self-serve** — there's no public signup. Admin commands fail fast at startup without a key, so don't retry them unauthenticated, and don't fall back to them for read tasks. If a user asks how to get a key, tell them access is currently invite-only and point them at the project repo; don't invent a signup URL. Full operator reference: **[references/admin.md](references/admin.md)**.

package/skills/releases-cli/references/reader.md

@@ -4,6 +4,8 @@ Reader commands are unauthenticated — no API key required. They talk to `api.r
 
 **Release JSON is slim by default.** `get`, `search`, and `tail`/`latest` return a lean release shape — `id`, `version`, `title`, `summary`, a markdown-stripped `excerpt`, `url`, `publishedAt`, nested `source`/`org`, and `contentChars`/`contentTokens` size hints. This drops storage internals (`contentHash`, `sourceId`, `versionSort`, `fetchedAt`, …) and the redundant `title*` variants to keep token usage low. Add `--full` when you need the complete payload (including the full `content` body). `summary` may be `null`; lean on `excerpt` / `contentChars` to decide whether to pull more.
 
+> **Piping note:** in the default (non-`--json`) TSV output, release rows repeat the title across several columns (raw title, normalized title, version). Don't assume `cut -f2` lands on a unique field — check the row layout first, or just use `--json` for stable parsing.
+
 ## Search
 
 Unified search across organizations, the catalog (products + standalone sources), and releases.
@@ -100,15 +102,40 @@ releases categories --json
 
 The category list is fixed — adding a new category requires a code change in `@buildinternet/releases-core`.
 
-## Changelog slicing (admin CLI, reader endpoint)
+## Reading a tracked changelog
+
+`releases get <source> --json` reports `hasChangelogFile` and `changelogUrl` keyless, so you can detect whether a source maintains a checked-in CHANGELOG.md. This only exists for **sources that track one** — tag-only repos (e.g. Next.js, which ships GitHub releases but no CHANGELOG file) and products report `hasChangelogFile: false`.
+
+To read the **sliced content** without a key, use one of:
+
+- The MCP tool `get_catalog_entry` with `changelog_tokens` (heading-aligned; recommended brackets 2000 / 5000 / 10000 / 20000) and chain via the returned `nextOffset`. Every response reports `totalTokens` so you can budget calls upfront.
+- Fetch the `changelogUrl` directly (it points at the raw file on GitHub).
+
+> The CLI also has a `releases admin source changelog <slug>` wrapper, but it lives under `admin` and is **key-gated** — it fails with `"admin" requires an API key` for keyless users. Prefer the two keyless paths above unless you already hold an admin key.
+
+## Collections
+
+Curated cross-org "playlists" (e.g. Frontier AI Labs, Coding Agents), keyless:
+
+```bash
+releases collection list                       # all collections
+releases collection get frontier-ai-labs       # members of one collection
+releases collection releases frontier-ai-labs  # interleaved cross-org release feed (--limit <n>, --json)
+```
+
+## Domain lookup
+
+Resolve a domain or URL to the org/product that owns it (keyless):
+
+```bash
+releases lookup domain vercel.com
+releases lookup domain https://tailwindcss.com/blog
+```
 
-The stored CHANGELOG.md for a GitHub source can be sliced from the reader API. The CLI wrapper lives under admin for discoverability but the endpoint itself is public:
+## Agent self-discovery
 
 ```bash
-releases admin source changelog apollo-client                      # full file
-releases admin source changelog apollo-client --limit 10000        # first 10k chars, heading-aligned
-releases admin source changelog apollo-client --tokens 5000        # first ~5k cl100k_base tokens
-releases admin source changelog apollo-client --offset 10000 --json
+releases agent-context        # versioned JSON: every command, argument, and option
 ```
 
-`tokens` and `limit` are both heading-aware; `tokens` wins when both are passed. Chain successive calls via the returned `nextOffset` to reconstruct the file exactly. Recommended token brackets: 2000 / 5000 / 10000 / 20000.
+When unsure of exact flags or subcommands, call `agent-context` rather than guessing — it's the CLI's own machine-readable contract, versioned via `schemaVersion`.

package/skills/releases-mcp/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user asks about recent releases, changelogs, what's ne
 
 # Releases.sh — Changelog Lookup
 
-When the user asks about releases, changelogs, or version updates, use the Releases.sh MCP tools to fetch current data instead of relying on training data.
+When the user asks about releases, changelogs, or version updates, use the Releases.sh MCP tools to fetch current data instead of relying on training data. Training data is stale for fast-moving libraries; these tools read the live registry.
 
 ## When to Use This Skill
 
@@ -15,43 +15,57 @@ Activate when the user:
 - Wants recent releases or changelogs ("Show me the latest Tailwind releases")
 - Asks about breaking changes or migration ("Were there breaking changes in Prisma 6?")
 - Wants to compare release activity between products ("Compare Bun vs Deno releases")
-- Mentions version updates, release notes, or changelogs in the context of a specific product
+- Mentions version updates, release notes, or changelogs for a specific product
+- Asks about a curated topic feed ("what's new across the AI labs?")
+
+## The Tools
+
+The hosted server exposes these tools. There is no AI summarization or comparison tool — you synthesize those yourself from the data below.
+
+- `search` — unified search across four sections: orgs, catalog (products + standalone sources), collections, and releases. Your default entry point.
+- `get_latest_releases` — recent releases, optionally scoped by `organization` or `product`. Use `since` / `until` for time windows.
+- `list_organizations` / `get_organization` — browse and inspect orgs.
+- `list_catalog` / `get_catalog_entry` — browse and inspect catalog entries. Each entry carries `entryType: "product" | "source"`. `get_catalog_entry` also serves CHANGELOG slices (see below).
+- `get_release` — fetch one release in full by its `rel_` id (ids come from `search` / `get_latest_releases`).
+- `list_collections` / `get_collection` / `get_collection_releases` — curated cross-org "playlists" (e.g. "Frontier AI Labs", "Coding Agents") independent of the category taxonomy.
+- `lookup_domain` — resolve a URL/domain to the org that owns it. Use when you have a URL-shaped input rather than a name.
 
 ## How to Look Up Releases
 
-### Step 1: Find the Organization or Catalog Entry
+### Step 1: Resolve the entity
+
+Start with `search` and the product or company name — it returns orgs, catalog, collections, and releases in one call, so you usually don't need a separate lookup. Narrow with `type` (e.g. `type: ["catalog"]` for a fast registry-only lookup, `type: ["releases"]` for pure release content).
+
+If a name doesn't resolve, try variations:
 
-Call `list_organizations` with the library/product name as the `query` parameter. For product-specific questions, browse the catalog (products + standalone sources) with `list_catalog` and fetch detail with `get_catalog_entry` — these replaced the older `list_products` / `get_product` / `list_sources` / `get_source` tools, which still exist as deprecated aliases.
+- The company instead of the product ("Vercel" rather than "Next.js")
+- The GitHub org ("supabase")
+- A domain — or use `lookup_domain` directly (e.g. "tailwindcss.com")
+- A `{org}/{repo}` GitHub coordinate ("vercel/next.js"). When nothing matches a coordinate-shaped query, the registry probes GitHub on demand and the response carries a `lookup` field with status `indexed` / `existing` / `empty` / `not_found` / `deferred`. Coordinate matching is case-insensitive.
 
-The unified `search` tool is also available — it returns `orgs`, `catalog`, and `releases` sections in one call. Catalog hits carry a `kind: "product" | "source"` discriminator, so you can route a click to either a product page or a standalone source. (Older API responses send the same array under a deprecated `products` alias; new clients should consume `catalog`.)
+### Step 2: Pick the right follow-up
 
-If the query returns no results, try variations:
-- The company name instead of the product name (e.g., "Vercel" instead of "Next.js")
-- The GitHub org name (e.g., "supabase")
-- A domain (e.g., "tailwindcss.com")
-- A `{org}/{repo}` GitHub coordinate (e.g., "vercel/next.js" or "github:vercel/next.js"). When `search` finds no entity match for a coordinate-shaped query, the registry probes GitHub on demand and the response includes a `lookup` field with status `indexed` / `existing` / `empty` / `not_found` / `deferred`. Coordinate matching is case-insensitive, so `Shopify/toxiproxy` and `shopify/toxiproxy` resolve identically.
+- **"What's new?" / "Latest releases"** → `get_latest_releases` with `organization` or `product`. Add `since` (e.g. `"30d"`, `"6m"`, or an ISO date) for "last month" / "since v4" style asks.
+- **Keyword across the whole registry** → `search` with a descriptive query; narrow with `type`.
+- **One release in full** (to quote a note verbatim) → `get_release` with the `rel_` id from search results.
+- **Entity metadata** → `get_catalog_entry` (products/sources) or `get_organization` (orgs, with an AI overview preview; `include_overview: true` for the full briefing).
+- **Full maintained CHANGELOG.md** → `get_catalog_entry` with `include_changelog: true`. This only applies to **source** entries that track a checked-in CHANGELOG.md — products and tag-only repos (e.g. Next.js, which ships GitHub releases but no CHANGELOG file) return none. For large files, pass `changelog_tokens` (recommended brackets: 2000 / 5000 / 10000 / 20000) to get a heading-aligned slice, then chain via the returned `nextOffset`. Every response reports `totalTokens` so you can budget calls upfront.
+- **A curated topic feed** → `list_collections` to discover, `get_collection_releases` for the interleaved cross-org feed.
 
-### Step 2: Choose the Right Tool
+### Step 3: Compare products (no built-in tool)
 
-- **"What's new?" / "Latest releases"** → Use `get_latest_releases` with the organization or product identifier (typed ID like `org_…` / `prod_…` / `src_…`, slug, or `org/slug` coordinate)
-- **Specific feature or keyword across orgs + catalog + releases** → Use `search` (unified) with a descriptive query; narrow via `type: ["releases"]` etc.
-- **Releases-only search** → Use `search_releases` (kept for back-compat) when you only want release rows
-- **Single release by id** → Use `get_release` when you already have a `rel_` id (search results include ids)
-- **Catalog deep-dive (product or standalone source)** → Use `get_catalog_entry` for metadata, tags, and linkage
-- **Organization detail** → Use `get_organization`
-- **Canonical CHANGELOG.md from a GitHub repo** → Use `get_catalog_entry` with `include_changelog: true` when the user wants the full maintained file, not just the tagged releases (refreshed on every fetch). For large files, pass `changelog_tokens` (cl100k_base budget, e.g. 5000 or 10000) to get a heading-aligned slice that fits a known context window; chain via the returned `nextOffset`. Every response reports `totalTokens` so you can plan how many calls you need upfront.
-- **Compare two products** → Fetch each product separately with `get_catalog_entry` (and `get_latest_releases` for recent activity), then synthesize the comparison from the returned data. The hosted MCP server does not expose AI summarization tools.
+There is no `compare_products` or `summarize_changes` tool on the hosted server. To compare, fetch each product separately (`get_catalog_entry` for metadata, `get_latest_releases` for recent activity) and synthesize the comparison yourself. Both products must be indexed — if one isn't found, say which is missing rather than guessing.
 
-### Step 3: Present Results
+### Step 4: Present results
 
-- Lead with the most relevant information for the user's question
-- Include version numbers and dates when available
-- Quote key changes directly from the release notes
-- If results are sparse, mention that the product may not be fully indexed yet
+- Lead with what answers the user's question.
+- Include version numbers and dates when available.
+- Quote key changes from the release notes (keep quotes short).
+- If results are sparse, say the product may not be fully indexed yet — don't fabricate release info.
 
 ## Guidelines
 
-- Pass the user's full question context into query parameters for better relevance
-- When the user mentions a time range ("last month", "since v4"), use the `days` parameter on `get_latest_releases`
-- If a product isn't found, say so clearly — don't fabricate release information
-- For comparison questions, both products must be indexed; if one isn't found, explain which is missing
+- Pass the user's full question into query parameters for better relevance.
+- For time windows, use `since` / `until` on `get_latest_releases` and `search` (relative shorthand like `"90d"` or ISO dates).
+- The `kind` filter (`platform|sdk|mobile|desktop|docs|integration|tool`) behaves differently by surface: on **release** results a source inherits its parent product's kind, so `kind: "sdk"` returns content under any SDK product; on **catalog** results it matches the row's own kind only. Reach for it when a query is explicitly scoped to one kind ("which SDKs shipped this week").
+- If a product isn't found, say so clearly — don't invent releases.