@buildinternet/releases-skills 0.52.0 → 0.54.0

package/package.json

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

package/skills/managing-sources/SKILL.md

@@ -16,6 +16,7 @@ Operations can be performed via CLI commands or typed MCP/agent tools. Use which
 | 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 create <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") |
 | Add App Store source | `releases admin source create-appstore <url-or-id> [--platform ios\|macos] [--org <slug>] [--product <slug>] [--storefront <code>]` | _(no typed tool yet — CLI only)_ |
+| Add video source | `releases admin source create-video <channel-or-playlist-url> --org <slug> [--product <slug>]` | _(no typed tool yet — CLI only)_ |
 | Edit source | `releases admin source update <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 delete <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 |
@@ -48,7 +49,7 @@ 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). App Store apps (`appstore` type) are **not** created this way — use `create-appstore` (below); `source create` rejects `--type appstore` and pasted `apps.apple.com` URLs with a pointer to it.
+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). App Store apps (`appstore` type) are **not** created this way — use `create-appstore` (below); `source create` rejects `--type appstore` and pasted `apps.apple.com` URLs with a pointer to it. YouTube channels/playlists (`video` type) are likewise **not** created this way — use `create-video` (below); `source create` rejects `--type video` and pasted `youtube.com`/`youtu.be` URLs.
 
 On slug collision the API auto-suffixes (`changelog` → `changelog-2`, `-3`, …) and the created row in the response tells you the resolved slug — no rename-and-retry needed.
 
@@ -71,6 +72,19 @@ releases admin source create-appstore <url-or-id> [--platform ios|macos] [--org
 - **Keep writes serial.** The endpoint resolves the listing on the fly; concurrent creates for a brand-new org/product race on the org/product slug uniqueness constraint. Add one app at a time.
 - The command is idempotent on the app's track ID — re-running reports the existing source instead of creating a duplicate.
 
+### Video sources
+
+YouTube channels and playlists need a dedicated command because the create flow resolves the channel/playlist to its Atom feed, mints a `video` source, and backfills current videos as releases (description-only, summarizer-cleaned, marketing-filtered):
+
+```
+releases admin source create-video <channel-or-playlist-url> --org <slug> [--product <slug>]
+```
+
+- `<channel-or-playlist-url>` is a YouTube channel (`youtube.com/@handle`, `/channel/<id>`) or playlist (`/playlist?list=<id>`) URL.
+- **`--org` is required and must already exist** — unlike `create-appstore`, no org is derived from the channel. Pass a slug or a typed `org_…` id. `--product <slug>` optionally attaches the source to an existing product.
+- The command is idempotent on the resolved feed URL — re-running reports the existing source.
+- **Never use generic `source create` for a YouTube URL.** It builds a `feed` source whose parser drops `media:group/media:description`, leaving a source with titles and dates but **empty release bodies** — a silent failure that needs deleting and re-creating to fix. `create` rejects YouTube URLs with a pointer to `create-video`.
+
 ### 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.

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

@@ -40,7 +40,7 @@ releases admin source create "Linear" --url https://linear.app/changelog --dry-r
 
 `--dry-run` still runs the URL dedup and exclusion checks (so you'll see "already exists" or "blocked URL" outcomes), but skips the write — including the auto-create-org side effect when `--org <name>` doesn't resolve.
 
-By default, `create` runs automated pre-checks (provider detection, feed discovery, markdown probing). Override with `--type github|scrape|feed|agent`. Batch mode (`--batch`) skips evaluation by default for speed. App Store apps use the dedicated `source create-appstore` verb (below) — `create` rejects `--type appstore` and pasted `apps.apple.com` URLs with a pointer to it.
+By default, `create` runs automated pre-checks (provider detection, feed discovery, markdown probing). Override with `--type github|scrape|feed|agent`. Batch mode (`--batch`) skips evaluation by default for speed. App Store apps use the dedicated `source create-appstore` verb (below) — `create` rejects `--type appstore` and pasted `apps.apple.com` URLs with a pointer to it. YouTube channels/playlists use `source create-video` (below) — `create` likewise rejects `--type video` and pasted `youtube.com`/`youtu.be` URLs.
 
 Provide a feed URL explicitly when it isn't easily discoverable:
 
@@ -60,6 +60,12 @@ releases admin source create "Acme" --url https://acme.dev/changelog \
 
 Do this rather than a follow-up `source update --metadata-set`: `create` triggers the onboard workflow's auto-fetch, which reads the source's metadata **before** any post-create edit lands. Setting a feed filter on create keeps that first ingest filtered; setting it afterward races the auto-fetch and ingests the whole unfiltered feed.
 
+Mark the org's primary changelog in one step with `--primary` (sets `isPrimary` on create — no follow-up `source update --primary` needed). Only pass it when the source is the org's main, company-wide changelog:
+
+```bash
+releases admin source create "Vitest" --url https://github.com/vitest-dev/vitest --org vitest --primary
+```
+
 Evaluate without adding:
 
 ```bash
@@ -87,6 +93,20 @@ releases admin source create-appstore https://apps.apple.com/us/app/shopify/id71
 
 Add one app at a time — the listing is resolved on the fly, and concurrent creates for a brand-new org/product race on slug uniqueness.
 
+### Create Video
+
+YouTube channels and playlists have a dedicated verb because the create flow resolves the channel/playlist to its Atom feed, mints a `video` source, and backfills current videos as releases (description-only, summarizer-cleaned, marketing-filtered):
+
+```bash
+releases admin source create-video https://www.youtube.com/@AnthropicAI --org anthropic
+releases admin source create-video https://www.youtube.com/playlist?list=PLf2m23nhTg1P --org anthropic --product claude
+releases admin source create-video https://www.youtube.com/@AnthropicAI --org anthropic --dry-run
+```
+
+`--org` is **required** and must already exist — unlike `create-appstore`, no org is derived from the channel. Pass a slug or a typed `org_…` id. `--product <slug>` (optional) attaches the source to an existing product. The verb is idempotent on the resolved feed URL — re-running reports the existing source.
+
+Do not point generic `source create` at a YouTube URL. It builds a `feed` source whose parser drops `media:group/media:description`, producing a source with titles and dates but **empty release bodies** — a silent failure. `create` rejects `--type video` and pasted `youtube.com`/`youtu.be` URLs with a pointer to this verb.
+
 ### Update
 
 ```bash
@@ -205,12 +225,12 @@ releases admin org update 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
+releases admin source fetch --org vercel                  # fetch all of an org's active sources
 releases admin org delete vercel                          # reversible tombstone soft-delete
 releases admin org delete vercel --hard --yes             # permanent purge + FK cascade
 ```
 
-`org refresh` flags: `--max <n>` (per-source cap, default 20), `--concurrency <n>`, `--window <days>`, `--dry-run`, `--skip-overview`, `--json`.
+There is no `org refresh` command. To refresh an org: fetch its sources with `releases admin source fetch --org <slug>` (see **Fetch** above), then regenerate the overview with the `overview` subcommands — `releases admin overview inputs <slug>` → generate the body → `releases admin overview update <slug>` (or `releases admin overview batch` for a server-side sweep). Overview generation is agent-driven; no single command does both.
 
 `org delete` soft-deletes by default (a reversible tombstone). `--hard` purges the row and cascade-deletes every dependent source, release, fetch-log, changelog file/chunk, summary, media asset, and webhook subscription; it prompts for a slug typeback unless `--yes` is passed (required in non-TTY/scripted contexts). You can pass a slug or an `org_…` ID either way — the CLI resolves to the typed ID the destructive path requires.
 
@@ -223,6 +243,8 @@ releases admin product create "Next.js" --org vercel --url https://nextjs.org
 releases admin product create "Stripe Node" --org stripe --kind sdk
 releases admin product list vercel
 releases admin product list openai --kind sdk           # filter by taxonomy
+releases admin product list                             # every product, all orgs (adds an Org column)
+releases admin product list --kind sdk --json           # cross-org kind audit (CLI↔MCP list_catalog parity)
 releases admin product update nextjs --description "React framework for production"
 releases admin product update stripe-node --kind sdk    # classify
 releases admin product update stripe-node --no-kind     # clear