@buildinternet/releases-skills 0.12.1

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@buildinternet/releases-skills",
+  "version": "0.12.1",
+  "description": "Agent skills bundled with the Releases CLI. Markdown playbooks for changelog ingest, discovery, and analysis.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zachdunn/releases-cli.git",
+    "directory": "packages/skills"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "rm -rf skills && cp -R ../../skills ./skills"
+  }
+}

package/skills/analyzing-releases/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: analyzing-releases
+description: >
+  Analyze release trends across multiple companies to produce competitive
+  intelligence. Use when asked to compare companies, analyze a market segment,
+  identify industry trends, forecast upcoming releases, or answer questions
+  like "what is X shipping lately" or "how does X compare to Y." Also triggers
+  on requests for competitive landscape analysis, feature gap analysis, or
+  release velocity comparisons.
+---
+
+# Analyzing Releases
+
+Turn changelog data into competitive intelligence by analyzing release patterns across a cohort of related companies.
+
+## Key Operations
+
+| Operation | CLI | Typed tool |
+|-----------|-----|------------|
+| Check existing sources | `releases list --query <company> --json` | `list_sources` with query param |
+| Fetch releases | `releases admin source fetch <slug> --max 50` | `fetch_source` with identifier (ID or slug) |
+| Get latest releases | `releases latest <slug> --json` | `get_latest_releases` with source/org and limit |
+| Search releases | `releases search <query> --json` | `search_releases` with query |
+| Summarize | `releases summary <slug> --json` | (not available as typed tool) |
+| Compare | `releases compare <slugA> <slugB> --json` | (not available as typed tool) |
+
+## Workflow
+
+### 1. Define the cohort
+
+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
+
+Fetch each source. The system skips unchanged feeds automatically.
+
+### 4. Get latest releases
+
+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.
+
+### 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.
+
+**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.
+
+### 6. Synthesize
+
+Combine summaries and comparisons into a structured analysis:
+
+- **Release velocity table** — releases per company, 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
+
+## 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.
+
+## 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 latest <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.

package/skills/classify-media-relevance/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: classify-media-relevance
+description: Decide whether an image or video found on a release page is editorial content (screenshots, demos, diagrams, product shots) or site chrome (avatars, logos, tracking pixels, decorative badges). Used during parsing to populate a release's media array.
+---
+
+# Classifying Media Relevance
+
+Release pages contain two kinds of media: **editorial content** that belongs in the release (screenshots of the feature, demo videos, diagrams explaining a change) and **site chrome** that doesn't (author avatars, nav logos, tracking pixels, decorative separators). This skill governs which items end up in a release's `media[]` array.
+
+The goal is precision-over-recall: a dropped editorial image is recoverable (users click through to the source page), but a kept junk image pollutes the UI and wastes storage.
+
+## When this runs
+
+- During the parse pipeline, after the AI extracts release content from a fetched page.
+- During crawl-mode fetches, when the extractor reads full-page markdown from a linked article and produces a fresh `media[]`.
+- Not during feed fetches where the feed already scoped media to per-entry content (trust the feed).
+
+## Cheap pre-checks (keep in code, don't spend AI tokens)
+
+These checks are deterministic, free, and catch the overwhelming majority of obvious junk. Always run them **before** invoking this skill. If a pre-check drops an item, no AI call is needed.
+
+1. **Tracking domains** — URL host matches a known tracking/analytics domain (`px.ads.linkedin.com`, `t.co`, `www.facebook.com/tr`, `analytics.twitter.com`, `bat.bing.com`). Drop with reason `tracking domain: <host>`.
+2. **Unsupported content-type** — after HEAD/GET, content-type isn't in the uploadable set (`image/png|jpeg|gif|webp|svg+xml|avif`, `video/mp4|webm`). Drop with reason `unsupported type`.
+3. **Size bounds** — body < 5 KB (tracking pixels, spacers) or > 10 MB (won't upload anyway). Drop.
+4. **Streaming embeds** — YouTube, Vimeo, Loom URLs are kept as `type: "video"` references without downloading. Never route through R2 upload or this skill.
+5. **ETag / content hash seen before** — if the R2 key derived from content hash already exists, reuse it and skip reclassification.
+
+Everything else — the ambiguous middle where URL patterns overlap between chrome and content — goes through the skill.
+
+## Heuristic nudges (optional, low-confidence)
+
+The old code treated path substrings like `/avatar`, `/logo`, `/icon`, `/badge`, `/favicon`, `1x1` as hard drops. That was wrong often enough to matter: a post titled "New icon set" shipped images under `/icons/` that were the actual product. **Do not hard-drop on path substrings.** Pass them through as weak negative signals and let the classifier weigh them against context.
+
+The one exception: `/favicon.ico` and exact `/favicon*` at the site root are always chrome. Keep that single check in code.
+
+## Classification rules
+
+For each remaining media item, decide **keep** or **drop** based on these signals, in rough order of importance:
+
+**Strong keep signals**
+- Image or video appears in the middle of release body content (not header/footer of the page).
+- Alt text describes a feature, UI state, code, or demo ("New dashboard showing filters", "Architecture diagram", "CLI output").
+- Filename suggests editorial content (`screenshot-*`, `demo-*`, `feature-*`, `*-hero.png`, version numbers in name).
+- Dimensions consistent with screenshots/diagrams (wider than 400px, aspect ratio not 1:1 perfect square).
+- Hosted on the org's CDN *under a posts/releases/blog path* (e.g., `cdn.example.com/posts/2026/new-thing.png`).
+
+**Strong drop signals**
+- Alt text is a person's name, a company name alone, or empty and the URL contains `avatar|profile|author|contributor`.
+- Filename is generic site chrome (`logo.svg`, `wordmark.png`, `header-bg.jpg`, `footer-icon.svg`).
+- Perfect 1:1 square under 200×200 with no contextual link to release content (likely avatar/badge).
+- URL path includes `/wp-content/plugins/` or `/_next/static/media/` with no posts path — usually framework chrome.
+- Appears in every release on the source (detectable by callers passing a frequency hint) — site-wide chrome bleeding into parses.
+
+**Weak / context-dependent**
+- `/icon`, `/icons/` paths — only chrome if the release isn't about icons; keep if the release announces icon/design updates.
+- `/badge`, `/badges/` — drop if it's a shields.io CI badge, keep if the release is about achievements/credentials.
+- SVGs at the top of the page — usually logos, but can be diagrams. Use surrounding alt text and position.
+
+## Output format
+
+Return a JSON array, one entry per input item, in the same order:
+
+```json
+[
+  { "url": "https://...", "decision": "keep", "confidence": "high", "reason": "screenshot of new dashboard, alt text describes feature" },
+  { "url": "https://...", "decision": "drop", "confidence": "high", "reason": "author avatar, 80x80 square at top of post" }
+]
+```
+
+`confidence` is `high` when signals align, `low` when it's a judgment call. Callers treat `low` drops conservatively — they may keep low-confidence drops on high-value sources.
+
+## Anti-patterns
+
+- **Don't** build a new substring blocklist inside the skill — that's what we're replacing.
+- **Don't** drop based on URL alone without considering alt text, position, and release context.
+- **Don't** request the image bytes to classify — work from URL + alt + surrounding content only. The byte-level decisions happen in the cheap pre-checks.
+- **Don't** keep "just in case" — over-keeping pollutes the grid view more than under-keeping hurts individual releases.

package/skills/finding-changelogs/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: finding-changelogs
+description: How to find, evaluate, and recommend the best ingestion method for changelog URLs — covers feed discovery, provider detection, GitHub API, markdown sources, and scraping fallback
+---
+
+# Finding Changelogs
+
+Determine the best way to get structured release data from a changelog or release notes page.
+
+Many pages have better-structured data sources behind them — RSS feeds, raw markdown files, or API endpoints. Finding those avoids the complexity of parsing rendered HTML.
+
+## Content Verification
+
+After discovering a feed or structured source, always spot-check the entries before accepting it. Sample a few entries and verify they are actual changelog or release content — not blog posts, marketing articles, tutorials, or unrelated editorial content.
+
+Red flags that a feed is wrong:
+- Entry URLs point to `/blog/` paths rather than `/changelog/` or `/releases/` paths
+- Titles read like articles or tutorials (e.g., "Choosing a logging library: The definitive guide")
+- No version numbers, semver patterns, or feature/fix language anywhere in the entries
+- The feed URL is site-wide (e.g., `/feed.xml`) rather than section-specific (e.g., `/changelog/feed.xml`)
+- Entry content discusses opinions, comparisons, or industry trends rather than product changes
+
+If the entries don't look like releases, the feed is likely the wrong one. Look for a more specific feed, or fall back to a different ingestion method.
+
+**Watch for redirects.** A URL like `blog.example.com/changelog/` may redirect to `example.com/changelog/`, but feed discovery may have already found the blog's site-wide feed before the redirect. Always check whether the discovered feed is scoped to the changelog section, not the entire site.
+
+## Priority Order
+
+Well-known files > Link relations > Feeds > GitHub Releases API > raw markdown > page scraping.
+
+For `github` sources, the fetch pipeline ingests tagged releases **and** the repo's canonical `CHANGELOG.md` (or `CHANGES.md` / `HISTORY.md` / `RELEASES.md` / `NEWS.md` at the repo root) on every fetch pass — the file is surfaced in the web UI as a separate tab, exposed via the `get_source_changelog` MCP tool, and is often the richer source when a project ships entries that never became tagged releases. The refresh piggybacks on each GitHub fetch with a content-hash short-circuit, so stored files stay in sync with tagged releases. You don't need to add a second source for the CHANGELOG file; the github adapter handles both.
+
+### Reading a tracked CHANGELOG
+
+Once a github source is tracked, its CHANGELOG is readable via `GET /v1/sources/:slug/changelog` (REST), the `get_source_changelog` MCP tool, or `releases admin source changelog <slug>` (CLI). All three support heading-aligned slicing in two modes:
+
+- **Token mode** (preferred for agent context budgeting) — pass `tokens` / `--tokens` with a cl100k_base budget. The response carries `sliceTokens` (actual count of the returned chunk) and `totalTokens` (whole file) so you can plan context precisely. Recommended brackets: 2000 / 5000 / 10000 / 20000.
+- **Char mode** — pass `limit` / `--limit` for character budgets. Same snap/overshoot rules.
+
+`tokens` wins when both are passed. Chain successive calls via the returned `nextOffset` to page through big files (e.g. Apollo Client's 700KB CHANGELOG) without pulling the whole thing at once. Every response includes `totalTokens` upfront, so you can budget the number of calls before you start reading.
+
+## Well-Known Files & Link Relations
+
+The discovery pipeline checks for standardized changelog metadata before falling back to heuristic methods.
+
+### Well-known files (highest priority)
+
+Checked in cascade — stops as soon as a tier produces results:
+1. `/.well-known/changelog.json` — JSON manifest (primary)
+2. `/.well-known/releases.json` — JSON manifest (alias)
+3. `/.well-known/changelog.txt` — text format (security.txt-style fallback)
+4. `/AGENTS.md`, `/AGENTS.txt` — AI agent instruction files with changelog references
+5. `/changelog.md`, `/changelog.txt`, `/releases.md`, `/releases.txt` (and uppercase variants) — root-level files
+
+**JSON manifest format** (`/.well-known/changelog.json`):
+
+Single product:
+```json
+{
+  "version": 1,
+  "url": "https://example.com/changelog",
+  "feed": "https://example.com/changelog/feed.xml"
+}
+```
+
+Multi-product:
+```json
+{
+  "version": 1,
+  "changelogs": [
+    { "name": "Platform", "url": "https://example.com/changelog", "feed": "https://example.com/changelog.rss" },
+    { "name": "API", "url": "https://example.com/api/changelog" }
+  ]
+}
+```
+
+**Text manifest format** (`/.well-known/changelog.txt`):
+```
+# Changelog discovery — see https://releases.sh/well-known
+Changelog: https://example.com/changelog
+Feed: https://example.com/changelog/feed.xml
+```
+
+Lines starting with `#` are comments. Keys are `Changelog:` and `Feed:`, one per line.
+
+**AGENTS.md / AGENTS.txt** — AI agent instruction files may reference changelogs. The parser detects:
+- Key-value lines: `Changelog: https://example.com/changelog`
+- Markdown links: `[Our Changelog](https://example.com/changelog)`
+- Bare URLs on lines mentioning "changelog", "release notes", etc.
+
+**Root changelog/releases files** — `/changelog.md`, `/changelog.txt`, `/releases.md`, `/releases.txt` (and uppercase variants) are probed via HEAD request. Only accepted if the server returns text content (not an HTML error page).
+
+### Link relations
+
+The discovery pipeline detects these `<link>` tags in the HTML `<head>`:
+
+```html
+<link rel="changelog" href="/changelog">
+<link rel="releases" href="/releases">
+<link rel="release-notes" href="/docs/release-notes">
+```
+
+If the tag includes a feed `type` attribute, the URL is treated as a feed source:
+```html
+<link rel="changelog" type="application/atom+xml" href="/changelog.atom">
+```
+
+These are distinct from standard feed autodiscovery (`rel="alternate"`) — they point directly to changelog pages or feeds, not generic site feeds.
+
+### Discovery method labels
+
+Sources found via these mechanisms are tagged:
+- `method: "well-known"` — from `/.well-known/` manifest files
+- `method: "link-rel"` — from HTML `<link rel="changelog|releases|release-notes">`
+
+Both carry `confidence: "high"` since they represent explicit publisher intent.
+
+## Evaluation
+
+Evaluate a URL to determine the best ingestion method. CLI: `releases admin discovery evaluate <url> --json`. Typed tool: `evaluate_url` with url param.
+
+Key fields in output:
+- `recommendedMethod`: `feed`, `github`, `markdown`, `scrape`, or `crawl`
+- `recommendedUrl`: The URL to use (may differ from the input URL)
+- `feedUrl` / `feedType`: If a feed was found
+- `githubRepo`: In `owner/repo` format, if applicable
+- `pageStructure`: `single-page`, `index`, or `unknown`
+- `confidence`: `high` (structured source found), `medium` (clear page structure), `low` (unclear)
+- `alternatives`: Other viable sources found
+
+## Checking Existing Sources
+
+Search with a domain or company name query to check what sources already exist. CLI: `releases list --query <text> --json`. Typed tool: `list_sources` with query param. Use as a starting point when you don't know where a company's changelogs live.
+
+## Pre-checks (automated)
+
+The evaluate operation runs these before returning:
+
+- **Provider fingerprinting** — identifies the hosting platform (Mintlify, ReadMe, Docusaurus, Ghost, etc.) via DNS CNAME, HTTP headers, and HTML patterns. Each provider has known capabilities.
+- **Feed discovery** — probes ~15 well-known feed paths and HTML `<link rel="alternate">` tags.
+- **Provider-specific probes** — if a provider is detected, tries its known feed paths and markdown suffix.
+
+## When to Evaluate Manually
+
+If evaluation returns `confidence: low` or `recommendedMethod: scrape`, you may want to investigate the page yourself:
+
+1. **Fetch the page** with `WebFetch` and look at the HTML source.
+2. **Look for feeds** — feed URLs embedded in JavaScript, non-standard paths, or links to RSS/Atom.
+3. **Look for GitHub repos** — "View on GitHub", "CHANGELOG.md on GitHub", or repository links.
+4. **Look for raw markdown** — links to source `.md` files.
+5. **Classify the page structure** — is it a single-page changelog or an index of links to individual release pages?
+
+## Primary Changelogs
+
+When evaluating multiple changelog sources for an org, identify which one is the company's **primary changelog** — the top-level, platform-wide changelog that covers the product as a whole. This is typically a website changelog page (e.g., `example.com/changelog`) rather than individual GitHub repos or product-specific pages.
+
+After adding sources, mark the primary one. CLI: `releases admin source edit <identifier> --primary`. Typed tool: `edit_source` with identifier (ID or slug) and is_primary: true. Only one source per org should be primary. If there's no clear top-level changelog, don't mark any as primary.
+
+## When to Use Crawl
+
+Use `--crawl` (or set `crawlEnabled` in source metadata) when:
+- The page is an **index** linking to individual release pages (e.g., `/changelog/2024-03-15`)
+- Single-page scraping only gets titles/dates but not full content
+- The provider is known to use per-release pages (Intercom, Notion, some custom sites)
+
+Do NOT use crawl for single-page changelogs or feeds.
+
+## Known Provider Capabilities
+
+Detected automatically in pre-checks. Listed for reference:
+
+| Provider | Feed Paths | Markdown Suffix | Static | Notes |
+|----------|-----------|-----------------|--------|-------|
+| Mintlify | `/rss.xml` | Yes (`.md`) | Yes | — |
+| Fern | `/changelog.rss`, `/docs/changelog.rss` | — | No | RSS contains `fve-mdx-b64` attributes (noise, stripped automatically). `<generator>` tag = `buildwithfern.com`. |
+| ReadMe | `/changelog.rss` | — | No | — |
+| Docusaurus | `/blog/rss.xml`, `/blog/atom.xml`, `/blog/feed.json` | — | Yes | — |
+| Ghost | `/rss/` | — | Yes | — |
+| WordPress | `/feed/` | — | Yes | — |
+| Productboard | `/changelog.rss`, `/changelog/feed` | — | No | — |
+| Headway | `/feed` | — | No | — |
+| Beamer | `/feed` | — | No | — |
+| LaunchNotes | `/rss` | — | No | — |
+| GitBook, Notion, Intercom, Zendesk, etc. | — | — | No | No feeds; use crawl or scrape. Some may expose a title-only RSS feed (no content body) — these are auto-detected as `summary-only` and fall through to scrape |
+
+## Rendering Optimization
+
+When a source uses the `scrape` type and falls through to the single-page Cloudflare path, the adapter checks whether the provider serves pre-rendered HTML. Static providers (Docusaurus, VitePress, WordPress, Ghost, Mintlify, etc.) don't need a headless browser — the content is already in the HTML response.
+
+For static providers, the adapter automatically uses Cloudflare's crawl API with `render: false`, which is ~10-30x faster than headless browser rendering and currently free.
+
+**When evaluating a new scrape source**, note the provider in the playbook. If the provider isn't in the table above but you can see from the page source that content is in the initial HTML (no loading spinners, no `<div id="root"></div>` shells), set `--no-render` on the source to enable the fast path.
+
+**If a fast fetch returns incomplete content**, the adapter falls back to full rendering automatically. If you notice this happening repeatedly for a source, set `--render` to force headless rendering and note the reason in the playbook.
+
+The agent's role is to evaluate content completeness after the first fetch — check that releases have titles, dates, and content. If they do, the fast path is working. If releases are empty or missing, the page likely needs JS rendering.
+
+## Source Selection and Scope
+
+Prefer **3–5 high-signal sources per org** over exhaustive coverage. More sources means more noise, more maintenance, and diminishing returns. Every source you add should justify itself — if you wouldn't want to read its releases, don't add it.
+
+### Core products vs ecosystem
+
+Only index an org's **own products**, not their ecosystem or community plugins. For example:
+
+- **Terraform** (core product) — yes
+- `terraform-provider-aws` (ecosystem plugin maintained by a different team) — no
+- **Next.js** (Vercel's own framework) — yes
+- `next-auth` (community library) — no
+
+Signs that a repo is ecosystem, not core:
+- Maintained by a different team or community contributors
+- One of hundreds of similar repos (providers, plugins, extensions, adapters)
+- Ships independently of the org's main release cycle
+- The org wouldn't mention it in their own changelog
+
+### Staleness signals — when to skip
+
+Skip sources that show signs of being inactive or low-value:
+- **Maintenance mode:** No meaningful releases in 6+ months, or only dependency bumps
+- **Pre-release only:** Recent "releases" are all dev/alpha/RC builds with no stable versions
+- **Superseded:** The product has been replaced by a successor (e.g., Vagrant → dev containers)
+- **Winding down:** The org has announced deprecation or deprioritization
+- **Low adoption:** The product exists but has minimal real-world usage
+
+When in doubt, add and pause rather than skip entirely. A focused index with 3 core sources is more useful than 11 sources where half are noise.
+
+### Add and pause, don't omit
+
+When you find a source that matches the staleness or ecosystem criteria above, **still add it to the database** but immediately set it to `--priority paused`. This prevents future onboard runs from rediscovering the same source and re-evaluating it. The source record serves as documentation that "we know about this, and we decided not to track it."
+
+Add the source and immediately set it to paused priority. CLI: `releases admin source add <name> --url <url> --org <org> --type github` then `releases admin source edit <identifier> --priority paused`. Typed tools: `add_source` then `edit_source` with identifier (ID or slug) and fetch_priority: "paused".
+
+Do the same for ecosystem plugins, deprecated products, and low-value repos. The goal is to capture the discovery decision, not to lose the knowledge.
+
+## Products, Categories, and Tags
+
+Organizations can have multiple distinct products (e.g., Vercel → Next.js, Turborepo, v0). When discovering sources for an org, consider whether they belong to separate products.
+
+Use product and org management operations to organize what you find. CLI: `releases admin product add`, `releases admin org tag add`, `releases categories`. Typed tools: `manage_product`, `manage_org`, `list_categories`. The full list of valid categories is provided in your system prompt.
+
+Don't force product groupings when sources are ambiguous — leave them at the org level and note suggestions in the state file.

package/skills/managing-sources/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: managing-sources
+description: How to add, remove, list, validate, and manage changelog sources — covers ignored/blocked URLs, duplicate detection, and the validation workflow
+---
+
+# Managing Sources
+
+Operational guide for managing changelog sources.
+
+## Tool Reference
+
+Operations can be performed via CLI commands or typed MCP/agent tools. Use whichever interface is available in your context.
+
+| 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 |
+| Add source | `releases admin source add <name> --url <url> [--type <type>] [--org <org>] [--feed-url <url>]` | `add_source` with name, url, type, organization, feed_url params |
+| Edit source | `releases admin source edit <identifier> [--primary] [--priority <p>]` | `edit_source` with identifier (ID or slug), is_primary, fetch_priority params |
+| Remove source | `releases admin source remove <slug> [--ignore --reason <reason>]` | `remove_source` with identifier (ID or slug) param |
+| Fetch releases | `releases admin source fetch <slug> [--dry-run] [--max <n>]` | `fetch_source` with identifier (ID or slug) param |
+| Get latest releases | `releases latest [slug] --json [--org <org>]` | `get_latest_releases` with source, organization, limit params |
+| Search releases | `releases search <query> --json` | `search_releases` with query, limit params |
+| 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 |
+| Show org | `releases admin org show <slug> --json` | `get_organization` with identifier |
+| Add tags to org | `releases admin org tag add <slug> <tags...>` | `manage_org` action "tag_add" with identifier, tags |
+| Link account | `releases admin org link <slug> --platform <p> --handle <h>` | `manage_org` action "link_account" with identifier, platform, handle |
+| Add product | `releases admin product add <name> --org <org> [--category <c>] [--tags <t>]` | `manage_product` action "add" with name, organization, category, tags |
+| Ignore URL | `releases admin policy ignore add --org <org> <url>` | `exclude_url` action "ignore" with url, organization |
+| Block URL | `releases admin policy block add <url>` | `exclude_url` action "block" with url |
+| List categories | `releases categories --json` | `list_categories` |
+| Get playbook | `releases admin content playbook <org>` | `get_playbook` with organization param |
+| Update playbook notes | `releases admin content playbook <org> --notes "..."` | `update_playbook_notes` with organization, notes params |
+
+## Listing Sources
+
+Search for existing sources with optional filters:
+- **query** — filter by name, slug, or URL
+- **organization** — filter by org ID or slug
+- **product** — filter by product ID or slug
+- **category** — filter by category
+- **has_feed** — only sources with a discovered feed URL
+
+Use `--json` (CLI) for structured output. Typed tools always return JSON.
+
+## Adding Sources
+
+Required: **name** and **url**. Optional: **type** (github, scrape, feed, agent — auto-detected from URL if omitted), **organization** (org ID or slug to associate with), **feed_url** (direct feed URL if known).
+
+### Naming sources and products
+
+**Don't prefix names with the org name.** The org is already shown as context on every page — repeating it in each child source produces noise like "Datadog › Datadog dd-trace-py". Pick the bare, recognizable name instead.
+
+Rules, in priority order:
+
+1. **GitHub sources → use the repo name.** `DataDog/dd-trace-py` → `dd-trace-py`, `vercel/next.js` → `next.js`. That's the name devs already recognize; the `owner/repo` byline underneath disambiguates.
+2. **Website/feed sources → strip the org name if present.** `Datadog Browser SDK` → `Browser SDK`, `Stripe API Changelog` → `API Changelog`.
+3. **Keep the org prefix only when it's part of the canonical product name.** `Claude Code`, `GitHub Actions`, `Google Cloud Run`, `Amazon S3` — people say them that way. If you strip the prefix and what's left is the actual name people use, strip. If stripping produces something nobody would recognize on its own, keep the prefix.
+4. **Org-level content sources keep the prefix.** `Datadog Blog`, `Vercel Engineering Blog` — "Blog" alone is meaningless, and org-prefix is the standard convention. Same for "Newsroom", "Announcements".
+5. **Products follow the same rules.** A product under Vercel should be `Next.js`, not `Vercel Next.js`. A product under Datadog whose actual name is `Agent` stays `Agent` — the org context above it already says Datadog.
+
+When in doubt: would a developer reading this name on its own (with the org already shown above) recognize what it is? If yes, strip. If no, keep the prefix.
+
+### 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.
+
+### Embedding side effects
+
+Adding or editing an org, product, or source triggers an entity embedding into the registry vector index in the background (fire-and-forget on the worker, never blocks the write). PATCHes are gated on the embed-relevant fields (name, description, category, domain, url) actually changing, so cosmetic edits and poll-driven metadata bumps don't re-embed. There's no manual step — if a write succeeds, treat the embedding as in-flight. If you ever need to verify or backfill, run `releases admin embed status` and then `releases admin embed entities` (remote mode only).
+
+## Removing Sources
+
+When removing discovery results, also ignore the URL to prevent re-discovery. In CLI: `releases admin source remove <slug> --ignore --reason "..."`. With typed tools: call `remove_source` then `exclude_url` with action "ignore".
+
+## Ignored URLs (org-scoped)
+
+A URL ignored for one org can still be valid for another org. Always scope ignores to the relevant organization.
+
+## Blocked URLs (global)
+
+For spam domains and known-bad URLs that should never be added for any org. Use block_type "domain" to block an entire domain.
+
+## Validation Workflow
+
+After adding a source, validate it:
+
+1. **Add the source** — provide name and URL
+2. **Fetch** — trigger a fetch (CLI: `--dry-run` for preview, then real fetch; typed tools: `fetch_source`)
+3. **Check results** — get latest releases and verify they have titles, dates, content
+4. **If bad:** remove the source and ignore the URL
+5. **If good:** the source is ready for production fetches
+
+## Primary Sources
+
+An org can have one source marked as its **primary changelog** — the main, company-wide changelog. Mark it with `--primary` (CLI) or `is_primary: true` (typed tool).
+
+When onboarding an org, if you find a single top-level changelog alongside product-specific or GitHub sources, mark the top-level one as primary.
+
+## Playbooks
+
+Each org has a **playbook** — a README that tells any agent how to efficiently work with that org's changelog sources. The playbook has two layers:
+
+- **Header** — auto-generated from source metadata. Shows source types, URLs, priorities, parseInstructions, and product groupings. Regenerates automatically on every source mutation. You never edit this directly.
+- **Agent notes** — free-form markdown that you fully control. This is the most important part of the playbook. Write it like a README for a teammate who needs to fetch releases from this org without asking questions.
+
+**Always read the playbook before fetching or working with an org's sources.** Typed tool: `get_playbook` with organization param. CLI: `releases admin content playbook <org>`. If no playbook exists yet, one will be auto-generated on the next source mutation (add/edit/remove).
+
+### Writing good agent notes
+
+Write notes like a **skill for the agent that will fetch from this org** — imperative, action-oriented, concise. The reader is an agent about to do work; tell it what to do and what to watch for, not what things are.
+
+Organize notes under these headings:
+
+**`### Fetch instructions`** — One paragraph per source. Use imperative voice:
+- What to do: "Set version=null", "Parse `<h2>` elements as version boundaries", "No filtering needed"
+- What to expect: cadence, content quality, whether rendering is needed
+- When to skip or deprioritize: "Only fetch when looking for launch announcements specifically"
+- Cite version format examples where useful (e.g., "semver like 2.1.98")
+
+**`### Traps`** — Concise warnings with **bolded trigger labels**:
+- Each trap is a bullet with a bold label and a one-sentence explanation
+- Example: `**Doubled paths on Platform**: Relative doc links get prefixed with the source URL, producing doubled paths.`
+- Include disabled sources with "Don't re-discover" warnings so agents don't re-evaluate them
+- Only include traps that would cause wasted work or bad data — skip informational notes
+
+**`### Coverage`** — Two or three sentences max:
+- Which sources are canonical vs supplementary
+- Whether active sources cover the org's full release surface
+- Any known gaps worth noting
+
+**`### Release cadence`** — Call out rollup publishers explicitly. Some orgs don't ship incremental changelog entries at all — they publish seasonal, quarterly, or annual **rollup** pages that collect many features into one banner post or microsite (e.g. Shopify Editions, Brex Fall Release, Ramp quarterly blog). When this is the case, say so in the notes and tell the parser to classify matching pages as `type: rollup`. Example:
+
+> Ramp publishes quarterly rollups at `/blog/new-on-ramp-q*-*` and monthly editions at `/blog/new-on-ramp-*-edition`. Classify all entries from this source as `type: rollup` — individual features within a rollup are not separately indexed.
+
+The `parsing-changelogs` skill ("Classifying Rollups" section) covers what rollups look like and when to set the `type` field. Your job in the playbook is to capture the org-specific signal so future fetches don't have to re-derive it from the page.
+
+### Levels of playbook quality
+
+**Compilation** (fast, from metadata only): Write notes based on source metadata — URL, type, priority, parseInstructions. Good for bulk coverage but claims about page structure, cadence, and version format are inferred, not verified. Suitable for initial scaffolding or low-priority orgs.
+
+**Verified** (thorough, from actual data): Before writing, query release data and fetch logs to ground every claim in observation:
+
+1. `releases list <slug> --json` — Check actual version formats, titles, content length, publishedAt patterns
+2. `releases admin source fetch-log <slug> --json` — Check for errors, success rates, stale data
+3. Analyze: calculate real cadence from dates, identify empty content or null fields, spot date drift
+4. Write notes citing specific data points, not general assumptions
+
+Use the verified approach for high-value orgs, when onboarding new orgs with scrape sources, or when refreshing stale compilation-only playbooks. The difference: "this source likely needs JS rendering" (compilation) vs "all 50 releases have empty content — the RSS feed delivers summaries only, needs crawl mode on per-release pages" (verified).
+
+Write notes during onboarding after you've fetched and validated sources. Update them when you discover new quirks or when source behavior changes. If notes are empty or stale, write them before doing fetch work — future agents (including yourself in later sessions) will benefit.
+
+**Updating notes:** Use `update_playbook_notes` with the complete notes content — it replaces the entire notes section. You can rewrite, reorganize, or clear notes at any time.
+
+**Changing source configuration:** The header reflects current source metadata. To change things like `parseInstructions`, `fetchPriority`, or `crawlEnabled`, use `edit_source` with metadata — the header updates automatically.
+
+**Product context:** Playbooks group sources by product when products are configured. Some sources (like an org's engineering blog) aren't tied to a specific product but may contain content relevant to any product under that org — the playbook calls these out as "Organization-Level Sources" with a note about which products they may cover.
+
+## Rendering Control
+
+The scrape adapter can fetch pages with or without a headless browser. Static-site providers (Docusaurus, VitePress, WordPress, Ghost, Mintlify) are fetched without rendering by default — this is ~10-30x faster.
+
+To override the default for a specific source:
+- `releases admin source edit <identifier> --no-render` — force fast fetch (no headless browser)
+- `releases admin source edit <identifier> --render` — force headless browser rendering
+
+Use `--render` when you know a source needs JavaScript execution. Use `--no-render` when you've verified the content is in the initial HTML for a provider not yet in the static list.
+
+After adding a new scrape source with an unknown provider, check the first fetch results. If content is complete, consider setting `--no-render` and noting the provider behavior in the playbook.
+
+## Duplicate Detection
+
+Before adding sources, search for overlapping URLs.
+
+Common duplicates:
+- Same repo via GitHub URL vs changelog page (the GitHub source is usually better)
+- RSS feed URL vs the page it feeds from (keep the feed)
+- With and without trailing slash or `www.` prefix

package/skills/parsing-changelogs/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: parsing-changelogs
+description: How the Releases fetch and parse pipeline works — covers feed vs scrape adapters, incremental vs bulk parsing, dry-run testing, crawl mode, content hashing, and enrichment
+---
+
+# Parsing Changelogs
+
+How the Releases fetch pipeline converts changelog pages into structured release data.
+
+## Pipeline Overview
+
+The fetch pipeline follows this priority order:
+
+1. **Feed adapter** — if the source has a known feed URL (in `metadata.feedUrl`), fetch and parse the feed directly. Fastest and most reliable.
+2. **Markdown fetch** — if `metadata.markdownUrl` is set, fetch raw markdown instead of rendered HTML.
+3. **Fast fetch (static providers)** — for providers known to serve pre-rendered HTML (Docusaurus, VitePress, WordPress, Ghost, Mintlify), fetch without headless browser rendering. Uses Cloudflare crawl API with `render: false`. ~10-30x faster than full rendering. Controlled by provider `staticContent` hint or per-source `renderRequired` metadata.
+4. **Cloudflare rendering** — for JS-heavy pages (React SPAs, Notion, etc.), use Cloudflare's browser rendering API to get the fully-rendered HTML. Fallback when fast fetch returns no content.
+
+After fetching content, the pipeline parses it:
+- **Incremental parsing** — if the source already has releases in the database, extract only new ones by comparing against known releases. This is the default for subsequent fetches.
+- **Bulk parsing** — parse the entire page into releases. Used on first fetch or when `--full` is specified.
+
+## Fetching
+
+Trigger a fetch for a source by ID or slug. CLI: `releases admin source fetch <slug> [--dry-run] [--max <n>]`. Typed tool: `fetch_source` with identifier (ID or slug) param.
+
+Key CLI flags (not available via typed tool — the typed tool always does a full server-side fetch):
+- `--dry-run` — parse but don't persist. Essential for validation.
+- `--max <n>` — limit releases to extract (default: 200).
+- `--full` — bypass incremental parsing, force full re-parse.
+- `--crawl` / `--no-crawl` — enable/disable crawl mode.
+
+### Checking results
+
+After fetching, verify releases were persisted. CLI: `releases latest <slug> --json` or `releases admin source fetch-log <slug>`. Typed tool: `get_latest_releases` with source param. Use `get_organization` (or `releases admin org show <slug> --json`) to see the full picture of an org's sources.
+
+## Incremental vs Bulk Parsing
+
+- **Incremental** (default for sources with existing releases): The parser receives a list of known release titles/versions and extracts only releases that don't match any known ones. Much faster and cheaper for sources that add releases incrementally.
+- **Bulk** (first fetch or `--full`): Parses the entire page content into releases. Used when no releases exist yet or when you suspect the incremental parser missed something.
+
+## Content Hashing
+
+Each fetch computes a SHA-256 hash of the page content. If the hash matches the previous fetch, parsing is skipped entirely (no AI calls). This prevents redundant processing when a page hasn't changed.
+
+## Crawl Mode
+
+For index-style pages that link to individual release pages:
+
+1. The crawler follows links matching the crawl pattern (auto-detected or from provider hints).
+2. Each linked page is fetched and parsed individually.
+3. Results are aggregated into releases.
+
+Enable with `--crawl` flag or by setting `metadata.crawlEnabled: true` on the source.
+
+## Feed Content Depth Assessment
+
+**Automatic detection:** The feed adapter now auto-detects title-only feeds — if every item has fewer than 20 characters of content, the feed is marked `feedContentDepth: "summary-only"` and `fetchViaFeed` returns null, causing the scrape adapter to fall through to crawl or single-page extraction. This handles the worst case (feeds like Notion, Apollo, LangChain, LaunchDarkly that carry only `<title>` + `<link>` with no `<description>` or `<content:encoded>`) without manual intervention. Once marked, the flag persists and subsequent fetches skip the feed entirely.
+
+**Manual assessment is still required for partial-content feeds.** Auto-detection only catches completely empty content. Many feeds provide decent text summaries but the actual pages have significantly richer content — product screenshots, video demos, detailed code examples, and inline media that the feed strips out.
+
+**The anti-pattern to avoid:** fetching the bare changelog index, seeing that content came back, and declaring success without ever checking whether each release has a dedicated article page with more detail. A paragraph of feed text is not evidence that the page is equally thin.
+
+**When to check:** After every feed fetch where `feedContentDepth` is not already set. Do not skip this because feed entries have multiple sentences. The question is not "does the feed have some content?" but "does the actual page have substantially more?"
+
+**How to check:** Dispatch a bulk-worker subagent to sample 2-3 release URLs. Prompt the subagent:
+
+> "Fetch these URLs with WebFetch and compare the page content against these feed summaries. For each URL, report: (1) how much content is on the page vs the feed summary, (2) whether there are images, screenshots, or embedded videos (YouTube, Vimeo, Loom), (3) whether there are code examples or detailed explanations not in the feed. Summarize your findings."
+
+Do NOT fetch release URLs in the parent agent — always delegate to a subagent to keep your context window clean.
+
+**What to do based on the result:**
+
+If pages are richer than feed content (more text, images, videos, or code examples):
+1. Record the assessment and enable crawl mode. CLI: `releases admin source edit <identifier> --metadata '{"feedContentDepth":"summary-only","crawlEnabled":true}'`. Typed tool: `edit_source` with the same metadata. Subsequent fetches will follow links to per-release pages and extract full content in one pass.
+2. Re-fetch the source once to backfill. CLI: `releases admin source fetch <slug> --full`. Typed tool: `fetch_source`.
+3. Verify results. CLI: `releases list <slug> --json` or `releases latest <slug>`. Typed tool: `get_latest_releases` — check content is richer after the re-fetch.
+
+If feed already provides full content with no meaningful additions on the page:
+1. Record `feedContentDepth: "full"` so future sessions skip the sampling step.
+
+Once `feedContentDepth` is set, skip the sampling step on future encounters. Crawl mode handles the rest during normal fetches — there is no separate enrichment phase.
+
+**Per-source AI instructions:** If a source has unique content patterns (e.g., videos always embedded, unusual changelog format), note this in the discovery state so parseInstructions can be set later via the CLI.
+
+## Blog-Style Sources
+
+Engineering blogs and news pages mix product announcements with educational content, opinion pieces, and corporate news. They can be useful supplementary sources but require aggressive filtering via `parseInstructions` to avoid noise.
+
+**Before working with blog sources:** Check the org's playbook (`releases admin content playbook <org>`) for notes about how existing blog sources perform, what filtering works, and which products they cover.
+
+**When to add a blog source:**
+- The org's primary changelogs don't cover major product announcements (new models, new services)
+- The blog has engineering/product content not found elsewhere
+- The blog is a secondary signal source — primary coverage should come from dedicated changelogs
+
+**How to configure:**
+1. Add as `--type scrape` with `--priority low` (blog pages change infrequently)
+2. Set `parseInstructions` that tell the AI what to include and — more importantly — what to skip
+3. Always dry-run first: `releases admin source fetch <slug> --dry-run` to check signal-to-noise ratio
+4. Iterate on instructions: tighten if too many irrelevant posts, loosen if genuine announcements are being filtered
+
+**Writing effective parseInstructions for blogs:**
+
+- Be explicit about what to SKIP — blogs have more noise categories than changelogs
+- Use concrete signals: "titles containing 'Introducing'" is better than "posts about new features"
+- Add a default-skip rule: "When in doubt, skip the post"
+- Name the noise categories: "best practices guides, benchmark analyses, eval methodology, postmortems, partnership announcements, policy statements"
+- For corporate news pages: skip partnerships, MOUs, office openings, funding, acquisitions, research papers, safety reports
+
+**Example parseInstructions for an engineering blog:**
+```
+ONLY extract posts that announce a NEW product, feature, tool, service, or capability.
+Signals: titles containing "Introducing", "launching", or describing something new.
+SKIP: best practices guides, benchmark analyses, eval methodology, postmortems,
+technical deep-dives, and educational content. When in doubt, skip.
+```
+
+**Example parseInstructions for a corporate news page:**
+```
+ONLY extract posts about: (1) new model launches, (2) major new product features or services,
+(3) significant platform capability announcements. Skip all: partnerships, MOUs, policy statements,
+office openings, funding, acquisitions, research publications, safety reports, and opinion pieces.
+```
+
+**Versioning:** Blog posts don't have traditional version strings. Set `parseInstructions` to tell the AI that dates are not versions (same as for date-headed changelogs like Claude's consumer release notes).
+
+**Content depth:** Blog index pages typically show card summaries, not full post content. The extracted releases will have thin content. Enable crawl mode (`--crawl`) to follow links to full posts if richer content is needed, but this is expensive — only enable for high-value sources.
+
+## Dates
+
+Every release should get a `publishedAt` if one can be recovered from the page, even an approximate one — sources with no dates drop out of the release feed's time-based views entirely.
+
+- **Full dates** ("March 3, 2026", "2026-03-03"): use the exact ISO date — `2026-03-03`.
+- **Month-only headings** ("April 2026", "March 2026"): use the **first of the month** — `2026-04-01`. Many API changelogs (e.g. Brex Developer API) group entries by month; this is the right call, not "omit date."
+- **Quarter or season** ("Q3 2025", "Fall 2025"): use the first day of the quarter/season (Q3 → `2025-07-01`, Fall → `2025-09-01`).
+- **Year only** ("2025"): use `2025-01-01`.
+- **Nothing recoverable**: omit `publishedAt`. Only do this if there truly is no date signal anywhere — check adjacent headings, breadcrumbs, and the URL slug before giving up.
+
+Approximation is better than omission. A release with an approximate month-start date still surfaces in sort orders, "last 30 days" windows, and monthly groupings.
+
+## Classifying Rollups
+
+Most releases are **features** — individual version bumps, single product announcements, or tight incremental changelog entries. Some are **rollups** — seasonal, quarterly, or annual catch-all pages that collect many already-shipped features into a single banner post. The parser assigns each release a `type` field so agents and the web UI can treat them differently.
+
+**When to set `type: "rollup"`:**
+
+- The title names a season, quarter, or year range: "Fall Release 2025", "Spring 2026", "Q3 2025", "Summer '25 Edition", "New on Ramp January Edition", "Year in Review 2025", "What Shipped This Summer".
+- The page re-announces many shipped features under section headings, rather than describing a single change.
+- The post is published once, rarely updates, and anchors a date range (not a single `publishedAt` moment).
+- The destination may be a full microsite or editorial landing page (not just a blog post) — rollups often get custom design treatment because they're marketing moments as well as product updates.
+- Common examples: Shopify Editions (`shopify.com/editions/summer2025`, twice-yearly microsite with 100+ features), Brex Fall Release, Ramp quarterly blog posts, Vercel Ship recaps, Stripe Sessions roundups, AWS re:Invent summaries.
+
+**When NOT to set rollup:**
+
+- Single version releases (v2.0.0, v15.1), even when they bundle multiple fixes — those are features.
+- Dated changelog entries like "March 3, 2026" that cover one day's changes.
+- Blog posts announcing a single new product.
+- Named platform launches (Next.js 15, Node 22 LTS) — those are version-anchored features, not rollups.
+
+**How to recognize rollup sources:**
+
+Before parsing, **always read the playbook** (CLI: `releases admin content playbook <org>`, typed tool: `get_playbook` with organization param). If a company publishes rollups as its primary cadence — quarterly, seasonal, "every few months" — the playbook notes should say so explicitly. Example notes:
+
+- "Brex publishes quarterly seasonal rollup pages at `/product-announcements/{fall,spring,summer,winter}-release-YYYY`. Treat each as `type: rollup`."
+- "Ramp's blog series `/blog/new-on-ramp-*-edition` and `/new-on-ramp-q*-*` are quarterly/monthly rollups. Classify as `type: rollup`; individual features within are not separately indexed."
+- "Shopify publishes twice-yearly Editions as standalone microsites at `/editions/{summer,winter}YYYY` — index page at `/editions` lists all of them. Each Edition is a `type: rollup` with 100+ features under themed sections; crawl mode needed to pull the full page."
+
+When you encounter a new rollup source during discovery or fetch, update the playbook notes so future fetches classify correctly without re-deriving the pattern. See the `managing-sources` skill for how to update notes.
+
+**Leave `type` unset or `"feature"` by default.** Only mark rollup when the signals are clear.
+
+## Validation Workflow
+
+When adding a new source, always validate before committing:
+
+1. **Fetch** — CLI: `releases admin source fetch <slug> --dry-run` then `releases admin source fetch <slug>`. Typed tool: `fetch_source` with identifier (ID or slug).
+2. **Verify** — CLI: `releases latest <slug> --json` or `releases admin source fetch-log <slug>`. Typed tool: `get_latest_releases` with source identifier.
+3. **If poor results** — try a different URL or type. CLI: `releases admin source edit <identifier> --type feed`. Typed tool: `edit_source` with identifier.
+4. **If no usable releases** — remove the source. CLI: `releases admin source remove <slug> --ignore --reason "..."`. Typed tool: `remove_source` with identifier, then `exclude_url`.

package/skills/seeding-playbooks/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: seeding-playbooks
+description: Coordinate bulk playbook writing using parallel sub-agents — covers org discovery, prompt templates, model selection, batch dispatch, verification, and the parent-saves pattern for working around subagent permission limits. Local-only (Claude Code CLI) — managed agents do not yet support spawning sub-agents.
+---
+
+# Seeding Playbooks
+
+Coordinate bulk creation or enrichment of playbook agent notes across many orgs using parallel sub-agents.
+
+**Local-only**: This skill requires Claude Code's Agent tool to dispatch sub-agents. Managed agents (discovery worker, Haiku worker) cannot spawn sub-agents — that capability is behind a private beta and not yet available. When sub-agent support ships for managed agents, this skill can be adapted into a managed session mode.
+
+## When to Use
+
+- Batch-populating playbooks for orgs that have sources but no notes
+- Re-running the verified workflow on existing playbooks to enrich them with data-grounded observations
+- After a wave of new orgs are onboarded and need initial playbook scaffolding
+
+## Step 1: Identify Targets
+
+Find orgs that need playbooks. Run this to check coverage:
+
+```bash
+bun -e "
+const orgs = JSON.parse(Bun.spawnSync(['bun', 'src/index.ts', 'admin', 'org', 'list', '--json'], { stderr: 'ignore' }).stdout.toString());
+const active = orgs.filter(o => o.sourceCount > 0).sort((a,b) => b.releaseCount - a.releaseCount);
+for (const org of active) {
+  const playbook = JSON.parse(Bun.spawnSync(['bun', 'src/index.ts', 'admin', 'content', 'playbook', org.slug, '--json'], { stderr: 'ignore' }).stdout.toString());
+  const status = playbook.notes?.length > 100 ? 'has notes (' + playbook.notes.length + ' chars)' : 'NEEDS PLAYBOOK';
+  console.log(org.slug.padEnd(25) + ' sources=' + String(org.sourceCount).padStart(2) + '  ' + status);
+}
+" 2>/dev/null
+```
+
+This produces a ranked list of orgs with their playbook status. Target orgs showing "NEEDS PLAYBOOK".
+
+## Step 2: Gather Source Details
+
+Before dispatching agents, collect source metadata for the target orgs. Each agent needs to know the org's sources, types, URLs, and product structure. Gather this in bulk:
+
+```bash
+for org in <slugs>; do
+  echo "=== $org ==="
+  bun src/index.ts admin org show "$org" --json 2>/dev/null | bun -e "
+    const d = JSON.parse(await Bun.stdin.text());
+    const products = d.products?.map(p => p.name + ' (' + p.slug + ')').join(', ') || 'none';
+    console.log('Products:', products);
+    d.sources?.forEach(s => {
+      const meta = s.metadata || {};
+      const parts = [s.slug, 'url=' + s.url, 'type=' + s.type];
+      if (meta.feedUrl) parts.push('feed=' + meta.feedUrl);
+      if (s.fetchPriority !== 'normal') parts.push('priority=' + s.fetchPriority);
+      if (meta.parseInstructions) parts.push('parseInstructions=YES');
+      console.log('  ' + parts.join(' | '));
+    });
+  " 2>/dev/null
+done
+```
+
+## Step 3: Choose Workflow and Model
+
+### Compilation workflow (fast, metadata-only)
+- Agent writes notes from source metadata without querying release data
+- Good for: bulk scaffolding, low-priority orgs, initial coverage
+- Notes are educated guesses — claims about page structure and cadence are inferred, not verified
+
+### Verified workflow (thorough, data-grounded)
+- Agent queries release data (`list <slug> --json`) and fetch logs (`admin source fetch-log <slug> --json`) before writing
+- Good for: high-value orgs, scrape sources, orgs with known data quality issues
+- Every claim is backed by observed data — version formats, actual cadence, content quality, fetch errors
+
+### Model selection
+
+| Model | Cost/playbook | Best for |
+|-------|-----------|----------|
+| Opus | ~$0.07 (compilation) / ~$0.13 (verified) | Top-10 orgs, complex source sets, first-time verified runs |
+| Sonnet | ~$0.01 / ~$0.03 | Sweet spot for quality/cost. Most thorough output. Use for top-20 verified runs |
+| Haiku | ~$0.008 / ~$0.009 | Bulk coverage (orgs 20+). Output is usable but may include filler. Cheapest even with higher token count (extra tokens are cached input) |
+
+## Step 4: Dispatch Sub-Agents
+
+Launch one agent per org, in parallel. Use batches of 10 to avoid overwhelming the system.
+
+### Compilation prompt template
+
+```
+Write playbook agent notes for the org "{slug}" and save them using the CLI.
+
+Playbooks are **skills for agents that will fetch from this org**. Write in imperative voice — tell the agent what to do, not what things are.
+
+Notes have three headings: `### Fetch instructions`, `### Traps`, `### Coverage`.
+
+**{Org name}'s sources:**
+{list each source with: slug, type, url, and any notable metadata}
+
+Products: {product list or "none"}
+
+**Fetch instructions**: One paragraph per source in imperative voice. Tell the agent what to do ("Set version=null", "Parse <h2> as version boundaries", "No filtering needed"), what to expect (cadence, content quality), and when to skip.
+
+**Traps**: Bullet list with **bolded trigger labels**. Only include things that would cause wasted work or bad data. Include "Don't re-discover" warnings for disabled sources.
+
+**Coverage**: 2-3 sentences. Which sources are canonical, whether there are gaps.
+
+Save by running:
+bun src/index.ts admin content playbook {slug} --regenerate 2>/dev/null
+bun src/index.ts admin content playbook {slug} --notes "$(cat <<'NOTES'
+YOUR NOTES HERE
+NOTES
+)" 2>/dev/null
+
+Verify with: bun src/index.ts admin content playbook {slug} 2>/dev/null | tail -20
+```
+
+### Verified prompt template
+
+```
+Write a **verified** playbook for the org "{slug}".
+Unlike a basic playbook, you must do actual research first.
+
+Playbooks are **skills for agents that will fetch from this org**. Write in imperative voice — tell the agent what to do, not what things are.
+
+## Step 1: Gather data (run all of these)
+
+bun src/index.ts admin org show {slug} --json 2>/dev/null
+{for each source:}
+bun src/index.ts list {source-slug} --json 2>/dev/null
+bun src/index.ts admin source fetch-log {source-slug} --json 2>/dev/null
+
+## Step 2: Analyze what you found
+
+Before writing, answer these questions from the data:
+- What version format does each source actually use? Cite examples.
+- What's the real publish cadence? Count releases per month from dates.
+- Are there fetch errors in the logs? What kind?
+- Are there releases with missing dates, empty content, or data quality issues?
+
+## Step 3: Write skill-style notes grounded in data
+
+Structure: `### Fetch instructions`, `### Traps`, `### Coverage`.
+
+**Fetch instructions**: One paragraph per source in imperative voice. Tell the agent what to do ("Set version=null", "Parse <h2> as version boundaries"), what to expect (cadence, content quality), and when to skip. Cite version format examples from actual data.
+
+**Traps**: Bullet list with **bolded trigger labels**. Only include things backed by evidence from fetch logs or release data. Include "Don't re-discover" warnings for disabled sources.
+
+**Coverage**: 2-3 sentences. Which sources are canonical, whether there are gaps.
+
+Every claim must cite observed data. If uncertain, say so explicitly.
+
+## Step 4: Save
+
+bun src/index.ts admin content playbook {slug} --regenerate 2>/dev/null
+bun src/index.ts admin content playbook {slug} --notes "$(cat <<'NOTES'
+YOUR NOTES HERE
+NOTES
+)" 2>/dev/null
+
+Verify with: bun src/index.ts admin content playbook {slug} 2>/dev/null | tail -20
+```
+
+### Dispatch pattern
+
+```typescript
+// Launch up to 10 agents in parallel per batch
+Agent({
+  description: "Write playbook: {slug}",
+  model: "sonnet",  // or "haiku" for bulk
+  prompt: compiledPromptTemplate,
+  run_in_background: true,
+})
+```
+
+## Step 5: Handle the Parent-Saves Pattern
+
+Sub-agents may be blocked from saving notes via Bash (heredoc permission issues). When this happens:
+
+1. The agent completes analysis and reports its findings in the result
+2. The parent agent (you) saves the notes manually:
+
+```bash
+bun src/index.ts admin content playbook {slug} --regenerate 2>/dev/null
+bun src/index.ts admin content playbook {slug} --notes "$(cat <<'NOTES'
+{paste notes from agent result}
+NOTES
+)" 2>/dev/null
+```
+
+This is a known limitation of subagent permissions. Plan for it — check each agent's result and save manually if needed.
+
+## Step 6: Verify Results
+
+After all agents complete, verify coverage in bulk:
+
+```bash
+bun -e "
+const orgs = [{target slugs}];
+for (const org of orgs) {
+  const proc = Bun.spawnSync(['bun', 'src/index.ts', 'admin', 'content', 'playbook', org, '--json'], { stderr: 'ignore' });
+  try {
+    const d = JSON.parse(proc.stdout.toString());
+    const len = d.notes?.length ?? 0;
+    console.log(org.padEnd(25) + (len > 100 ? 'OK (' + len + ' chars)' : 'MISSING'));
+  } catch { console.log(org.padEnd(25) + 'ERROR'); }
+}
+" 2>/dev/null
+```
+
+**Important**: Do not pipe `bun | bun` in shell for-loops — stdin contention causes silent failures. Use `Bun.spawnSync` in a single process as shown above.
+
+## Tracking Notes
+
+When coordinating a batch run, keep notes on:
+
+- **Failure modes**: Which agents failed to save? Was it permissions, timeouts, or bad output?
+- **Data quality issues found**: Verified runs surface broken feeds, empty content, stale data. Collect these for follow-up fixes.
+- **Model quality at this tier**: Did Haiku produce usable output or did it need manual cleanup?
+- **Coverage gaps identified**: Agents often note missing sources — collect these as onboarding candidates.
+
+Write findings to `.context/` for future reference.

package/src/index.ts

@@ -0,0 +1,21 @@
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the bundled skills directory. Resolves to the sibling
+ * `skills/` folder when installed from npm (via the `files` field) and falls
+ * back to the repo-root `skills/` directory during local development.
+ */
+export function skillsDir(): string {
+  const packaged = resolve(here, "..", "skills");
+  if (existsSync(packaged)) return packaged;
+  const repoRoot = resolve(here, "..", "..", "..", "skills");
+  return repoRoot;
+}
+
+export function skillPath(name: string): string {
+  return join(skillsDir(), name);
+}