@buildinternet/releases-skills 0.13.2 → 0.14.0

package/package.json

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

package/skills/releases-cli/SKILL.md

@@ -0,0 +1,76 @@
+---
+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.
+---
+
+# 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.
+
+## 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"
+```
+
+The CLI talks to `api.releases.sh` by default — no configuration needed for reader commands.
+
+## 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 `RELEASED_API_KEY`.
+
+## Quick Reference
+
+```bash
+# Reader (no auth required)
+releases search "breaking change"            # hybrid FTS + semantic search
+releases latest next-js                      # latest releases from one source
+releases latest --org vercel --count 20      # latest from a whole org
+releases list --category ai                  # browse sources
+releases show vercel                         # dispatch by id or slug
+releases stats                               # registry overview
+releases categories                          # list valid category values
+
+# Admin (requires RELEASED_API_KEY)
+releases admin source add "Linear" --url https://linear.app/changelog
+releases admin source fetch <slug> --max 50
+releases admin org add "Acme" --category cloud
+releases admin product add "CLI" --org acme
+releases admin discovery onboard "Stripe"    # AI-powered discovery agent
+
+# Local stdio MCP bridge (proxies to api.releases.sh)
+releases admin mcp serve
+```
+
+Every reader command accepts `--json` for machine-readable output. IDs (`org_…`, `src_…`, `prod_…`, `rel_…`) are accepted anywhere a slug is.
+
+## 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 RELEASED_API_KEY=your_key
+export RELEASED_API_URL=https://api.releases.sh   # optional, this is the default
+```
+
+These can also go in a `.env` file — Bun auto-loads it when running from source.
+
+## Common Mistakes
+
+- `releases admin …` without `RELEASED_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 edit <slug> --slug new-slug`) require `--confirm-slug-change` because they break web links.
+- `releases admin source fetch` with no slug or filter is blocked in remote mode. Use `--stale`, `--unfetched`, `--retry-errors`, `--changed`, or a source 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.

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

@@ -0,0 +1,184 @@
+# Admin Commands
+
+> **Closed beta.** All commands on this page require `RELEASED_API_KEY` — a Bearer token on write endpoints of `api.releases.sh`. API keys are **not self-serve** at this time. A normal user cannot create one on their own, and the hosted registry does not expose a public signup flow for admin access. If a user asks how to obtain a key, tell them admin access is currently invite-only and point them at the project repo to request access. Do not fabricate a signup URL or recommend sending a request to a specific email unless one is documented in this repo.
+
+If a key is available, set it in the environment:
+
+```bash
+export RELEASED_API_KEY=your_key
+```
+
+Missing or invalid keys fail fast at CLI startup with a clear error; don't retry the same command without fixing the env var.
+
+All admin commands accept an entity ID (`org_…`, `src_…`, `prod_…`, `rel_…`) or a slug wherever an identifier is expected. Prefer IDs — slugs can change, IDs cannot.
+
+## Sources
+
+### Add
+
+```bash
+releases admin source add "Next.js" --url https://github.com/vercel/next.js
+releases admin source add "Linear" --url https://linear.app/changelog
+releases admin source add "My Blog" --url https://example.com/changelog
+```
+
+By default, `add` runs automated pre-checks (provider detection, feed discovery, markdown probing). Override with `--type github|scrape|feed`. Use `--skip-eval` to bypass evaluation. Batch mode (`--batch`) skips evaluation by default for speed.
+
+Provide a feed URL explicitly when it isn't easily discoverable:
+
+```bash
+releases admin source add "Claude Code" --url https://docs.anthropic.com/en/changelog \
+  --feed-url https://docs.anthropic.com/en/changelog/rss.xml
+```
+
+Evaluate without adding:
+
+```bash
+releases admin discovery evaluate https://linear.app/changelog
+```
+
+### Edit
+
+```bash
+releases admin source edit src_abc123 --name "New Name"      # by ID (preferred)
+releases admin source edit next-js --url https://github.com/vercel/next.js/releases
+releases admin source edit my-blog --org acme                 # set organization
+releases admin source edit my-blog --no-org                   # remove organization
+releases admin source edit my-blog --type feed                # change adapter type
+releases admin source edit my-blog --no-feed-url              # clear stored feed URL
+releases admin source edit my-blog --markdown-url https://example.com/changelog.md
+releases admin source edit my-blog --primary                  # mark as org's primary changelog
+releases admin source edit my-blog --slug new-slug --confirm-slug-change
+```
+
+Slug renames require `--confirm-slug-change` because they break existing web links.
+
+### Fetch
+
+```bash
+releases admin source fetch next-js              # one source
+releases admin source fetch --since 2025-01-01 --max 50
+releases admin source fetch --max 500            # override the 200/source default
+releases admin source fetch --all                # no date/count limits
+releases admin source fetch --stale 24           # only stale sources, with backoff
+releases admin source fetch --retry-errors       # retry sources whose last fetch failed
+releases admin source fetch --changed            # sources with upstream changes detected
+releases admin source fetch --unfetched --concurrency 5
+releases admin source fetch next-js --skip-changelog   # skip CHANGELOG.md refresh
+```
+
+Notes:
+
+- Default cap is 200 releases per source (GitHub paginates at ~10K). `--max <n>` or `--all` to override.
+- Remote mode **requires** a filter or slug. Bare `releases admin source fetch` with no args is blocked to prevent accidental bulk work.
+- Remote concurrency defaults to 3, capped at 5. Duplicate source fetches are detected and blocked.
+- Smart fetch backoff: sources returning no changes back off exponentially (1h → 48h); error backoff caps at 72h.
+
+### Poll (cheap change detection)
+
+```bash
+releases admin source poll                  # HEAD-check all feed sources
+releases admin source poll next-js          # one source
+releases admin source poll --changed        # only show sources flagged with changes
+releases admin source poll --json
+```
+
+Pure HEAD-based, no AI or parsing. The hosted cron runs this hourly; `--changed` is mostly useful for ad-hoc checks.
+
+### Fetch history
+
+```bash
+releases admin source fetch-log                   # across all sources
+releases admin source fetch-log next-js           # one source
+```
+
+### Health checks
+
+```bash
+releases admin source check             # all sources
+releases admin source check next-js     # one source
+```
+
+## Organizations
+
+```bash
+releases admin org add "Vercel" --category developer-tools --tags typescript,edge
+releases admin org list                                   # summary view
+releases admin org show vercel                            # full details (accounts, tags, sources, products, aliases)
+releases admin org edit vercel --category developer-tools
+releases admin org link vercel --platform github --handle vercel
+releases admin org tag add vercel react serverless
+releases admin org alias add anthropic claude.ai claude.com
+releases admin org refresh vercel                         # fetch all sources + regenerate overview
+```
+
+`org refresh` flags: `--max <n>` (per-source cap, default 20), `--concurrency <n>`, `--window <days>`, `--dry-run`, `--skip-overview`, `--json`.
+
+## Products
+
+Products group sources under multi-product orgs (e.g. Vercel → Next.js, Turborepo, v0):
+
+```bash
+releases admin product add "Next.js" --org vercel --url https://nextjs.org
+releases admin product list vercel
+releases admin product edit nextjs --description "React framework for production"
+releases admin product tag add nextjs react
+releases admin product alias add nextjs nextjs.org
+releases admin product remove nextjs          # sources become unlinked, not deleted
+releases admin product adopt nextjs --into vercel   # convert an org into a product
+```
+
+## Releases
+
+```bash
+releases admin release show rel_abc123
+releases admin release edit rel_abc123 --title "Fixed title" --version "v2.0.1"
+releases admin release delete rel_abc123
+releases admin release suppress rel_abc123 --reason "promotional content"
+releases admin release unsuppress rel_abc123
+```
+
+Suppressed releases are hidden from all read paths (search, latest, stats, API) but preserved for audit.
+
+## Policies
+
+Ignored URLs are **org-scoped**; blocked URLs are **global**.
+
+```bash
+releases admin policy ignore add https://example.com/blog --org vercel --reason "Not a changelog"
+releases admin policy ignore list --org vercel
+releases admin policy block add medium.com --domain --reason "Aggregator"
+releases admin policy block list
+```
+
+## Discovery
+
+AI-powered onboarding for whole companies:
+
+```bash
+releases admin discovery onboard "Vercel"
+releases admin discovery onboard "Stripe" --domain stripe.com --github-org stripe
+releases admin discovery discover vercel.com --verify --add
+releases admin discovery task list                # in-flight discovery sessions
+releases admin discovery task cancel <sessionId>
+```
+
+## Import
+
+Bulk-import orgs and sources from a JSON manifest:
+
+```bash
+releases admin source import manifest.json
+releases admin source import manifest.json --dry-run
+releases admin source import manifest.json --skip-existing
+```
+
+## MCP bridge
+
+Run a local stdio MCP bridge that proxies the hosted tools:
+
+```bash
+releases admin mcp serve
+```
+
+Useful for clients that only support stdio transport. For native remote MCP support (Claude Code, Codex), connect directly to `https://mcp.releases.sh/mcp` instead.

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

@@ -0,0 +1,97 @@
+# Reader Commands
+
+Reader commands are unauthenticated — no API key required. They talk to `api.releases.sh` over HTTPS and all support `--json` for machine-readable output.
+
+## Search
+
+Hybrid lexical + semantic search across releases and CHANGELOG chunks.
+
+```bash
+releases search "authentication"
+releases search "vercel" --type releases --limit 5
+releases search "breaking change" --json
+releases search "retry" --org stripe
+```
+
+Flags:
+
+- `--type <releases|sources|all>` — narrow result kind (default: `all`).
+- `--org <slug>` — scope to one organization.
+- `--product <slug>` — scope to one product.
+- `--limit <n>` — default 20.
+- `--mode <lexical|semantic|hybrid>` — default `hybrid`. Use `lexical` for pure FTS ranking.
+- `--json` — machine output; each hit includes a `kind: "release" | "changelog_chunk"` discriminator.
+
+Chunk hits carry `sourceSlug`, `chunkOffset`, and `chunkLength` so you can chain into `releases admin source changelog <slug> --offset N` (or the MCP `get_source_changelog` tool) to read surrounding context.
+
+## Latest releases
+
+```bash
+releases latest                          # across all sources
+releases latest next-js                  # one source (by slug)
+releases latest --org vercel --count 20  # whole org
+releases latest --product nextjs         # one product
+releases latest --type feature           # filter by release type
+releases latest --json
+```
+
+## List sources
+
+```bash
+releases list                          # all sources
+releases list next-js                  # detail for one source (by slug or id)
+releases list --org sentry             # filter by organization
+releases list --product nextjs         # filter by product
+releases list --query shadcn           # name / slug / url substring
+releases list --has-feed               # sources with a discovered feed URL
+releases list --category ai            # filter by category
+releases list --json                   # machine-readable output
+releases list --json --compact         # lightweight JSON (id, slug, name, type, org, date)
+releases list --json --limit 20 --page 2  # pagination (server-side)
+```
+
+Aliased as `releases admin source list` for discoverability within admin workflows.
+
+## Show any entity
+
+Top-level `show` dispatches by ID prefix, and falls back to slug lookup:
+
+```bash
+releases show rel_XqbzLaOqBFz7VSAIqx2zs   # release (rel_)
+releases show src_abc123                   # source (src_)
+releases show org_abc123                   # organization (org_)
+releases show prod_abc123                  # product (prod_)
+releases show vercel                       # slug fallthrough (org → product → source)
+```
+
+Use this when you have an ID from another tool output (search results, MCP tool responses, etc.) and want to inspect it without caring what kind of entity it is.
+
+## Stats
+
+```bash
+releases stats              # index overview, source health, recent fetch activity
+releases stats --days 7     # adjust the activity window
+releases stats --json
+```
+
+## Categories
+
+```bash
+releases categories          # list the canonical category values
+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)
+
+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:
+
+```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
+```
+
+`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.

package/skills/releases-mcp/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: releases-mcp
+description: Use when the user asks about recent releases, changelogs, what's new in a library, breaking changes, version updates, or wants to compare products. Activates for questions like "what changed in Next.js 15?", "latest Tailwind releases", "compare Bun vs Deno releases".
+---
+
+# 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 to Use This Skill
+
+Activate when the user:
+
+- Asks what's new or changed in a library/product ("What changed in Next.js 15?")
+- 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
+
+## How to Look Up Releases
+
+### Step 1: Find the Organization or Product
+
+Call `list_organizations` with the library/product name as the `query` parameter. Multi-product orgs (e.g. Vercel → Next.js, Turborepo) are exposed via `list_products` and `get_product` — use those when the user's question is product-specific rather than company-wide.
+
+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")
+
+### Step 2: Choose the Right Tool
+
+- **"What's new?" / "Latest releases"** → Use `get_latest_releases` with the organization or product slug
+- **Specific feature or keyword** → Use `search_releases` with a descriptive query and organization filter
+- **Single release by id** → Use `get_release` when you already have a `rel_` id (search results include ids)
+- **Source or product deep-dive** → Use `get_source`, `get_product`, or `get_organization` for metadata, tags, and linkage
+- **Canonical CHANGELOG.md from a GitHub repo** → Use `get_source_changelog` when the user wants the full maintained file, not just the tagged releases (refreshed on every fetch). For large files, pass `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** → Use `compare_products` with an array of two product slugs
+- **Summarize recent activity** → Use `summarize_changes` with the product slug
+
+### Step 3: 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
+
+## 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` or `summarize_changes`
+- 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