@buildinternet/releases-skills 0.28.0 → 0.29.0

package/package.json

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

@@ -54,6 +54,8 @@ releases admin mcp serve
 
 Every command that takes an org / product / source / release identifier accepts the typed ID (`org_…`, `prod_…`, `src_…`, `rel_…`) interchangeably with the slug — including `--org`, `--product`, `--source` flags. IDs are stable across renames; slugs are friendlier to type. Source and product commands also accept an `org/slug` coordinate (e.g. `vercel/vercel-ai-sdk`); coordinates and typed IDs are unambiguous and skip an extra resolver round-trip that bare slugs require. Every reader command accepts `--json` for machine-readable output.
 
+Every mutating admin command accepts `--dry-run` to print the planned write (with all validations applied) without calling the API. Pair with `--json` for a machine-readable plan. See `references/admin.md` for the full coverage list.
+
 ## Authentication
 
 Reader access is unauthenticated and may be rate-limited per IP.

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

@@ -12,6 +12,21 @@ Missing or invalid keys fail fast at CLI startup with a clear error; don't retry
 
 All admin commands accept an entity ID (`org_…`, `src_…`, `prod_…`, `rel_…`) or a slug wherever an identifier is expected. Source and product commands also accept an `org/slug` coordinate (e.g. `vercel/vercel-ai-sdk`). Prefer IDs or coordinates — slugs can change, IDs cannot, and coordinates typically skip an extra resolver round-trip that bare slugs require under the hood (#698).
 
+## Previewing changes (`--dry-run`)
+
+Most mutating admin verbs accept `--dry-run`. The command resolves identifiers, runs validation (category, URL exclusion, existing-record dedup, etc.), and prints the planned write without calling the API. Pair with `--json` for a machine-readable plan.
+
+Coverage:
+
+- **source**: `create`, `update`, `delete`, `import`
+- **org**: `create`, `update`, `delete`, `link`, `unlink`
+- **product**: `create`, `update`, `delete`, `adopt`
+- **release**: `update`, `delete`, `suppress`, `unsuppress`
+- **policy**: `ignore add`, `block add`
+- **embed**: write paths
+
+Tag and alias `add` / `remove` on org/product are intentionally left without a preview — they're trivially reversible joins.
+
 ## Sources
 
 ### Create
@@ -20,8 +35,11 @@ All admin commands accept an entity ID (`org_…`, `src_…`, `prod_…`, `rel_
 releases admin source create "Next.js" --url https://github.com/vercel/next.js
 releases admin source create "Linear" --url https://linear.app/changelog
 releases admin source create "My Blog" --url https://example.com/changelog
+releases admin source create "Linear" --url https://linear.app/changelog --dry-run --json
 ```
 
+`--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.
 
 Provide a feed URL explicitly when it isn't easily discoverable:
@@ -103,6 +121,7 @@ releases admin source check next-js     # one source
 
 ```bash
 releases admin org create "Vercel" --category developer-tools --tags typescript,edge
+releases admin org create "Vercel" --tags typescript,edge --dry-run    # preview, no write
 releases admin org list                                   # summary view
 releases admin org get vercel                             # full details (accounts, tags, sources, products, aliases)
 releases admin org update vercel --category developer-tools