@buildinternet/releases-skills 0.20.0 → 0.20.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-skills",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "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

@@ -17,10 +17,10 @@ Turn changelog data into competitive intelligence by analyzing release patterns
 
 | Operation | CLI | Typed tool |
 |-----------|-----|------------|
-| Check existing sources | `releases list --query <company> --json` | `list_sources` with query param |
+| 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_releases` with query |
+| 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) |
 
@@ -44,13 +44,13 @@ Get structured release data with dates for each source. Use a limit (e.g., 50) t
 
 ### 5. Search and cross-reference
 
-Search across all indexed releases to find specific features, breaking changes, or patterns. `search_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 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.
 
 **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_registry` instead of `list_sources --query` — it's vector-backed and matches on description and category, not just slug substring.
+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.
 
 ### 6. Synthesize
 

package/skills/managing-sources/SKILL.md

@@ -13,13 +13,13 @@ Operations can be performed via CLI commands or typed MCP/agent tools. Use which
 
 | Operation | CLI | Typed tool |
 |-----------|-----|------------|
-| List sources | `releases list [slug] --json [--org <org>] [--query <text>] [--has-feed] [--category <c>] [--compact] [--limit <n>] [--page <n>]` | `list_sources` with query, organization, category, has_feed params |
+| List sources | `releases list [slug] --json [--org <org>] [--query <text>] [--has-feed] [--category <c>] [--compact] [--limit <n>] [--page <n>]` | `list_catalog` (filter `kind: "source"` to exclude products); `list_sources` is a deprecated alias |
 | Add source | `releases admin source add <name> --url <url> [--type <type>] [--org <org>] [--feed-url <url>] [--primary]` | `manage_source` action "add" with name, url, type, organization, feed_url, **is_primary** (type auto-detected if omitted; only pass is_primary=true when the source is the org's primary changelog — see "Primary Sources") |
 | Edit source | `releases admin source edit <identifier> [--primary] [--priority <p>]` | `manage_source` action "edit" with identifier, is_primary, fetch_priority, name, url, type (use only when changing an already-added source; prefer setting flags on "add") |
 | Remove source | `releases admin source remove <slug> [--ignore --reason <reason>]` | `manage_source` action "remove" with identifier |
 | Fetch releases | `releases admin source fetch <slug> [--dry-run] [--max <n>]` | `manage_source` action "fetch" with identifier |
 | Get latest releases | `releases tail [slug] --json [--org <org>]` | `get_latest_releases` with source, organization, limit params |
-| Search releases | `releases search <query> --json` | `search_releases` with query, limit params |
+| Search releases | `releases search <query> --json` | `search` with `type: ["releases"]`; `search_releases` is a deprecated alias |
 | Evaluate URL | `releases admin discovery evaluate <url> --json` | `evaluate_url` with url param |
 | Add org | `releases admin org add <name> [--domain <d>] [--description <t>] [--category <c>] [--tags <t1,t2>]` | `manage_org` action "add" with name, domain, description, category, tags |
 | Edit org | `releases admin org edit <slug> [--category <c>]` | `manage_org` action "edit" with identifier, category |
@@ -67,7 +67,7 @@ When in doubt: would a developer reading this name on its own (with the org alre
 
 ### Organization descriptions
 
-When creating an org, include a brief one-sentence product description. This grounds AI summaries for lesser-known products, and it's also the primary signal for the entity vector index — `search_registry` and the registry side of hybrid search match on description + category, not just name. A good description noticeably improves recall.
+When creating an org, include a brief one-sentence product description. This grounds AI summaries for lesser-known products, and it's also the primary signal for the entity vector index — the unified `search` tool (and the registry side of hybrid search) matches on description + category, not just name. A good description noticeably improves recall.
 
 ### Embedding side effects
 

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

@@ -4,25 +4,23 @@ Reader commands are unauthenticated — no API key required. They talk to `api.r
 
 ## Search
 
-Hybrid lexical + semantic search across releases and CHANGELOG chunks.
+Unified search across organizations, the catalog (products + standalone sources), and releases.
 
 ```bash
 releases search "authentication"
 releases search "vercel" --type releases --limit 5
+releases search "react" --type catalog
 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.
+- `--type <orgs|catalog|releases>` — narrow to one section (default: all three). `products` is accepted as a deprecated alias for `catalog`.
+- `--limit <n>` — max results per section (default: 10).
+- `--mode <lexical|semantic|hybrid>` — pick the release-retrieval strategy. Server default is hybrid; pass `lexical` for pure FTS ranking.
+- `--json` — machine output. Release hits include a `kind: "release" | "changelog_chunk"` discriminator. Catalog hits include `kind: "product" | "source"` so you can route a click to either a product page or a standalone source.
 
-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.
+Catalog hits also include the response field `catalog`. Older API deploys will still send the deprecated `products` alias instead — the CLI reads either, but new code should consume `catalog`.
 
 ## Latest releases
 

package/skills/releases-mcp/SKILL.md

@@ -19,9 +19,11 @@ Activate when the user:
 
 ## How to Look Up Releases
 
-### Step 1: Find the Organization or Product
+### Step 1: Find the Organization or Catalog Entry
 
-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.
+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 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`.)
 
 If the query returns no results, try variations:
 - The company name instead of the product name (e.g., "Vercel" instead of "Next.js")
@@ -31,9 +33,11 @@ If the query returns no results, try variations:
 ### 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
+- **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)
-- **Source or product deep-dive** → Use `get_source`, `get_product`, or `get_organization` for metadata, tags, and linkage
+- **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_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