@buildinternet/releases-skills 0.61.0 → 0.62.1

package/package.json

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

@@ -43,7 +43,8 @@ Two commands built for agents specifically:
 ### Conventions worth knowing (all in the reader reference)
 
 - **IDs and slugs are interchangeable** wherever an identifier is expected (`org_…`, `prod_…`, `src_…`, `rel_…`); IDs are stable across renames. Source/product commands also take an `org/slug` coordinate (e.g. `vercel/vercel-ai-sdk`), which skips a resolver round-trip.
-- **`--json` everywhere** for stable output. Release readers (`get`, `search`, `tail`) return a **slim** shape by default (core fields + markdown-stripped `excerpt` + `contentTokens` hint) to save tokens; pass `--full` for the complete payload. (`list` is the inverse: verbose by default, `--compact` for less.)
+- **`--json` everywhere** for stable output. Release readers (`get`, `search`, `tail`) return a **slim** shape by default (core fields + markdown-stripped `excerpt` + `contentTokens` hint, plus `media[]` with R2 `r2Url` when present and a `contentTruncated` flag) to save tokens; pass `--full` for the complete payload. (`list` is the inverse: verbose by default — and carries a per-source `Releases` count column — `--compact` for less.)
+- **`tail`/`latest` row cap:** `--count` (alias `--limit`, clamped `1–100`) sets how many releases to return. Only the `--product` feed is cursor-paginated (`--cursor <token>`); the org-wide/global feeds are count-capped, so `--cursor` without `--product` errors.
 - **Piped output is bare TSV** (no headers/color/truncation), so `releases list | cut -f2` works without parsing ANSI — but note release rows repeat the title across several columns, so check the layout or just use `--json` before slicing by column number. `COLUMNS=<n>` overrides detected width.
 
 ### Reading a tracked changelog

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

@@ -130,21 +130,23 @@ Slug renames require `--confirm-slug-change` because they break existing web lin
 ### 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 next-js              # one source (slug, src_… id, or org/slug)
+releases admin source fetch --org acme           # all of an org's active sources
 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
+releases admin source fetch --unfetched          # never-fetched sources
+releases admin source fetch next-js --wait       # block until the dispatched session finishes
+releases admin source fetch next-js --dry-run    # probe without writing or billing
+releases admin source fetch next-js --local      # stage a local-ingest handoff (no managed agent)
 ```
 
 Notes:
 
-- Default cap is 200 releases per source (GitHub paginates at ~10K). `--max <n>` or `--all` to override.
+- The server caps each fetch at 200 releases per source (GitHub paginates at ~10K); there is no CLI override flag.
+- A fetch that inserts new releases also triggers a server-side fill pass over the source's missing AI titles/summaries (up to 100 rows) when the org has `auto_generate_content` enabled — no flag, no second step.
 - Remote mode **requires** a filter or slug. Bare `releases admin source fetch` with no args is blocked to prevent accidental bulk work.
+- A source identifier can't be combined with `--org` — pass one source (`src_…`, `org/slug`, or `--source`) or use `--org` alone to fetch the whole org; the CLI errors on the conflict. `--org` skips push-only `agent` sources (they have no fetch adapter).
 - 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.
 
@@ -225,7 +227,7 @@ 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 source fetch --org vercel                  # fetch all of an org's active sources
+releases admin source fetch --org vercel                  # fetch all of an org's active sources (skips push-only agent sources)
 releases admin org delete vercel                          # reversible tombstone soft-delete
 releases admin org delete vercel --hard --yes             # permanent purge + FK cascade
 ```

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

@@ -4,6 +4,8 @@ Reader commands are unauthenticated — no API key required. They talk to `api.r
 
 **Release JSON is slim by default.** `get`, `search`, and `tail`/`latest` return a lean release shape — `id`, `version`, `title`, `summary`, a markdown-stripped `excerpt`, `url`, `publishedAt`, nested `source`/`org`, and `contentChars`/`contentTokens` size hints. This drops storage internals (`contentHash`, `sourceId`, `versionSort`, `fetchedAt`, …) and the redundant `title*` variants to keep token usage low. Add `--full` when you need the complete payload (including the full `content` body). `summary` may be `null`; lean on `excerpt` / `contentChars` to decide whether to pull more.
 
+Two fields survive into the slim shape because they answer common questions without a `--full` round-trip: **`media[]`** is included when the release carries media (each item keeps the R2-mirrored `r2Url`), so you can verify "did this image mirror to R2?" from the default output; and **`contentTruncated: true`** is stamped whenever a full `content` body exists but was projected to `excerpt`, signalling that `--full` will return more. Both are omitted when not applicable.
+
 > **Piping note:** in the default (non-`--json`) TSV output, release rows repeat the title across several columns (raw title, normalized title, version). Don't assume `cut -f2` lands on a unique field — check the row layout first, or just use `--json` for stable parsing.
 
 ## Search
@@ -47,12 +49,18 @@ releases tail                          # across all sources
 releases tail next-js                  # one source (slug)
 releases tail src_abc123               # one source (typed id)
 releases tail --org vercel --count 20  # whole org (org_…, slug, domain, name, or handle)
+releases tail --org vercel --limit 100 # --limit is an alias for --count (both clamp to 1–100)
+releases tail --product nextjs --cursor <token>  # page the product feed (see below)
 releases tail --product nextjs         # one product (prod_… or slug)
 releases tail --type feature           # filter by release type
 releases tail --json                   # slim shape
 releases tail --json --full            # complete payload
 ```
 
+`--count` (alias `--limit`) caps the rows returned and is clamped to `1–100`; a positive integer is required (anything else errors). When a one-shot listing fills the requested window, a truncation hint is printed to **stderr** so `--json` stdout stays clean.
+
+Pagination differs by feed: only the **product** feed (`--product`) is cursor-paginated — pass `--cursor <token>` to fetch the next page, chaining the token from the previous response. The org-wide and global feeds are **count-capped, not cursored**, so `--cursor` without `--product` errors rather than being silently ignored (and `--cursor` can't combine with `--follow`).
+
 ## List sources
 
 ```bash
@@ -69,6 +77,8 @@ releases list --json --compact         # lightweight JSON (id, slug, name, type,
 releases list --json --limit 20 --page 2  # pagination (server-side)
 ```
 
+The text table carries a per-source **`Releases`** count column (a dim `—` when unknown), so you can answer "how many releases does this source have?" without a follow-up call; the `--json` rows expose the same value as `releaseCount`.
+
 Aliased as `releases admin source list` for discoverability within admin workflows.
 
 ## Get any entity
@@ -85,6 +95,8 @@ releases get vercel                       # slug fallthrough (org → product
 
 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.
 
+For a release, `releases get rel_… --json` carries `media[]` (with each item's R2-mirrored `r2Url`) and a `contentTruncated` flag in the slim shape — enough to confirm media mirrored to R2 and whether there's a fuller body behind `--full`, without dropping to the raw API.
+
 ## Stats
 
 ```bash