@buildinternet/releases-skills 0.63.0 → 0.65.0

package/package.json

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

package/skills/releases-cli/SKILL.md

@@ -43,9 +43,11 @@ 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, 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.)
+- **`--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.) Narrow further with **`--fields id,version,source.slug`** (comma-separated, dot-notation for nested keys) to project the JSON down to just the leaves you need — on `get`/`search`/`tail`, composes with `--full`.
 - **`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.
+- **`--page-all` for the whole list at once:** on the page-based list readers (`list`, `org list`, `admin product list`), `--json --page-all` walks every page and streams one item per line as NDJSON, so you don't have to loop `--page`/`--limit` or react to the truncation warning. Pipe it to `jq -c` or a stream parser. It's `--json`-only and can't be combined with `--page`.
 - **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.
+- **Errors are structured under `--json`.** When a command run with `--json` fails, it prints a parseable `{ "error": { "kind", "message", "status?", "method?", "path?", "field?" } }` to stdout (not a stderr text dump) and exits non-zero — so you can branch on `kind` (`"api"` / `"invalid_input"` / `"error"`) instead of string-matching. Identifiers are also validated before any request: control characters, `..` traversal, `%`/`?`/`#`, and whitespace are rejected with an `invalid_input` error.
 
 ### Reading a tracked changelog
 
@@ -62,6 +64,24 @@ Two commands built for agents specifically:
 - There is **no** `summary` or `compare` command in this CLI, and **no** AI summarization tools on the hosted MCP (`summarize_changes` / `compare_products` do not exist). To summarize or compare, read each entity with `releases get` / `releases tail` (or `--json`) and synthesize the answer yourself.
 - Don't reach for `admin` commands to do reads — every read above is keyless. `admin` is only for registry maintenance and requires a key (below).
 
+## Signed-in user commands (`releases login`)
+
+After `releases login` (device flow) or with a stored `relu_` key, you can manage your own account state — no admin key required:
+
+```bash
+releases follow vercel              # follow an org or product
+releases following                # list follows
+releases feed                     # personalized release timeline
+
+releases webhook list             # your outbound webhook subscriptions
+releases webhook add --scope follows --url https://your.app/hook
+releases webhook add --org vercel --url https://your.app/hook
+releases webhook test <id>        # enqueue a signed test delivery
+releases webhook verify --key …   # local HMAC check (no auth)
+```
+
+Org-scoped webhooks: up to 10 per account (`--org`, optional `--source`, `--product`, `--type feature|rollup`). Follows-scoped: one webhook that tracks your current follow graph (real-time sibling to `feed` + digest email); optional `--type` narrows delivery. `webhook edit` can update filters (`--clear-source`, `--clear-product`, `--clear-type`). Signing keys are shown once on `add` / `rotate-secret`. Operator/admin webhooks (`releases admin webhook …`) are a separate root-key surface.
+
 ## Admin surface (invite-only — reads never need it)
 
 `releases admin <noun> <verb>` manages the registry (create/update sources, orgs, products; fetch; discovery; policies). It requires `RELEASES_API_KEY`, and **keys are not self-serve** — there's no public signup. Admin commands fail fast at startup without a key, so don't retry them unauthenticated, and don't fall back to them for read tasks. If a user asks how to get a key, tell them access is currently invite-only and point them at the project repo; don't invent a signup URL. Full operator reference: **[references/admin.md](references/admin.md)**.

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

@@ -66,6 +66,16 @@ Mark the org's primary changelog in one step with `--primary` (sets `isPrimary`
 releases admin source create "Vitest" --url https://github.com/vitest-dev/vitest --org vitest --primary
 ```
 
+#### Raw JSON payload (`--input`)
+
+Instead of reverse-mapping a payload onto individual flags, send one source as a JSON body with `--input`. The body mirrors the `--batch` element shape (`name`, `url`, `type`, `slug`, `org`, `product`, `feedUrl`, `keywordAllow`, `metadataSet`, `primary`) and runs the same dedup / metadata-packing / validation as the flag path — it is **not** forwarded raw to the API. Pass a literal JSON string, `@<path>` for a file, or `-` for stdin; `--strict`/`--dry-run`/`--json` still apply. Mutually exclusive with `--batch` (use `--batch` for an array).
+
+```bash
+releases admin source create --input '{"name":"Astro","url":"https://astro.build/blog","type":"scrape"}'
+releases admin source create --input @source.json
+echo '{"name":"Astro","url":"https://astro.build/blog"}' | releases admin source create --input -
+```
+
 Evaluate without adding:
 
 ```bash
@@ -125,6 +135,13 @@ releases admin source update my-blog --slug new-slug --confirm-slug-change
 
 Slug renames require `--confirm-slug-change` because they break existing web links.
 
+Send a batch of field updates as one JSON body with `--input` instead of stacking flags. Keys mirror the flags (`name`, `url`, `type`, `org`, `product`, `kind`, `priority`, `discovery`, `primary`, …); a nested `metadata` object sets source-metadata keys directly (a `null` value deletes a key — the ergonomic equivalent of repeated `--metadata-set`/`--metadata-unset`). Accepts a literal JSON string, `@<path>`, or `-` for stdin. The body wins over any flags; `--json`/`--dry-run` still apply.
+
+```bash
+releases admin source update src_abc123 --input '{"kind":"sdk","priority":"low","metadata":{"crawlEnabled":true}}'
+releases admin source update src_abc123 --input @patch.json
+```
+
 `--kind` sets the source's taxonomy. In **release feeds** and **search release hits**, a source with no kind of its own inherits its parent product's kind — so filtering by `kind=sdk` returns content from any source that's either marked SDK or sits under an SDK product. In **catalog listings** and **source lists** (`releases list`, `admin product list`, `search` catalog hits), the filter matches the row's *own* kind field directly with no inheritance — so the same `kind=sdk` filter only returns rows explicitly classified as SDK.
 
 ### Fetch

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

@@ -75,10 +75,13 @@ releases list --kind sdk               # filter by taxonomy (platform|sdk|mobile
 releases list --json                   # machine-readable output
 releases list --json --compact         # lightweight JSON (id, slug, name, type, org, date)
 releases list --json --limit 20 --page 2  # pagination (server-side)
+releases list --json --page-all        # stream every page as NDJSON (one source per line)
 ```
 
 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`.
 
+`--page-all` walks every page for you and streams the result as newline-delimited JSON — one source per line — so you can grab the full list in one command instead of looping `--page`. It's `--json`-only (warns and falls through to the table otherwise) and can't be combined with `--page`; `--limit` still tunes the per-request page size. The same flag is on `releases org list` and `releases admin product list`. Pipe it straight to `jq -c` or any stream parser.
+
 Aliased as `releases admin source list` for discoverability within admin workflows.
 
 ## Get any entity
@@ -159,6 +162,26 @@ releases submit https://acme.dev/changelog --dry-run --json # preview the payloa
 
 `--note` carries extra context (product name, GitHub repo, feed quirks); `--contact` is an optional email to notify once it's reviewed. With no URL argument in an interactive terminal, `submit` prompts for the URL (and the optional note/contact); otherwise pass it inline or pipe via stdin. Index pages, changelogs, GitHub releases, and feed URLs are all ideal.
 
+## Signed-in account commands (`releases login`)
+
+These act on **your** account via `/v1/me/*` — sign in first (`releases login` or `RELEASES_API_KEY`):
+
+```bash
+releases follow vercel
+releases following
+releases feed
+
+releases webhook list
+releases webhook add --scope follows --url https://your.app/hook
+releases webhook add --org vercel --url https://your.app/hook
+releases webhook add --org vercel --product next-js --type feature --url https://your.app/hook
+releases webhook edit <id> --type rollup
+releases webhook test <id>
+releases webhook verify --key <hex> --signature … --timestamp … --body-file -
+```
+
+`webhook verify` is local (no auth). Admin webhooks (`releases admin webhook …`) are a separate root-key operator surface.
+
 ## Agent self-discovery
 
 ```bash