@buildinternet/releases-skills 0.43.0 → 0.45.0

package/package.json

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

@@ -74,6 +74,8 @@ Every command that takes an org / product / source / release identifier accepts
 
 Tabular reader commands fit themselves to the terminal width when stdout is a TTY (column truncation with `…`) and switch to bare TSV (no headers, no color, no truncation) when stdout is piped — so `releases org list | cut -f2` works without parsing ANSI. Set `COLUMNS=<n>` to override the detected width. Use `--json` whenever you need stable, complete output for parsing.
 
+The release readers (`get`, `search`, `tail`/`latest`) return a **slim** JSON shape by default — core fields plus a markdown-stripped `excerpt` and `contentChars`/`contentTokens` size hints — to keep agent token usage down; pass `--full` for the complete payload. (This is the inverse of `list`, which is verbose by default with an opt-in `--compact`.) See `references/reader.md`.
+
 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

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

@@ -2,6 +2,8 @@
 
 Reader commands are unauthenticated — no API key required. They talk to `api.releases.sh` over HTTPS and all support `--json` for machine-readable output.
 
+**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.
+
 ## Search
 
 Unified search across organizations, the catalog (products + standalone sources), and releases.
@@ -20,7 +22,8 @@ Flags:
 - `--limit <n>` — max results per section (default: 10).
 - `--mode <lexical|semantic|hybrid>` — pick the release-retrieval strategy. Server default is hybrid; pass `lexical` for pure FTS ranking.
 - `--kind <platform|sdk|mobile|desktop|docs|integration|tool>` — taxonomy filter. Release hits match `COALESCE(source.kind, product.kind)` (a source with no kind inherits from its product); catalog hits match the row's own kind directly.
-- `--json` — machine output. Release hits include a `kind: "release" | "changelog_chunk"` discriminator. Catalog hits include `entryType: "product" | "source"` (the entity discriminator) plus an optional `kind` field carrying the taxonomy classification.
+- `--json` — machine output (slim release hits by default; `--full` for the complete shape). Release hits include a `kind: "release" | "changelog_chunk"` discriminator. Catalog hits include `entryType: "product" | "source"` (the entity discriminator) plus an optional `kind` field carrying the taxonomy classification.
+- `--full` — with `--json`, return complete unprojected release hits (full `content`, `score`, `sourceType`, `title*` variants, …).
 
 Catalog hits also include the response field `catalog`. Older API deploys will still send the deprecated `products` alias instead — the CLI reads either, but new code should consume `catalog`.
 
@@ -44,7 +47,8 @@ releases tail src_abc123               # one source (typed id)
 releases tail --org vercel --count 20  # whole org (org_…, slug, domain, name, or handle)
 releases tail --product nextjs         # one product (prod_… or slug)
 releases tail --type feature           # filter by release type
-releases tail --json
+releases tail --json                   # slim shape
+releases tail --json --full            # complete payload
 ```
 
 ## List sources