@buildinternet/releases 0.82.0 → 0.83.1

package/README.md

@@ -1,16 +1,16 @@
-# Releases CLI
+# Release Notes Index CLI
 
 [![npm](https://img.shields.io/npm/v/@buildinternet/releases?color=cb3837&label=npm&logo=npm)](https://www.npmjs.com/package/@buildinternet/releases)
 [![Release](https://github.com/buildinternet/releases-cli/actions/workflows/release.yml/badge.svg)](https://github.com/buildinternet/releases-cli/actions/workflows/release.yml)
 [![Test](https://github.com/buildinternet/releases-cli/actions/workflows/test.yml/badge.svg)](https://github.com/buildinternet/releases-cli/actions/workflows/test.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![Backend](https://img.shields.io/badge/backend-buildinternet%2Freleases-24292e?logo=github)](https://github.com/buildinternet/releases)
-[![skills.sh](https://skills.sh/b/buildinternet/releases-cli)](https://skills.sh/buildinternet/releases-cli)
+[![skills.sh](https://skills.sh/b/buildinternet/releases)](https://skills.sh/buildinternet/releases)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/buildinternet/releases-cli)
 
-**[releases.sh](https://releases.sh)**  ·  **[Backend monorepo →](https://github.com/buildinternet/releases)**  ·  [Install](#install)  ·  [Usage](#usage)  ·  [Authentication](#authentication)
+**[Release Notes Index](https://releases.sh)**  ·  **[Backend monorepo →](https://github.com/buildinternet/releases)**  ·  [Install](#install)  ·  [Usage](#usage)  ·  [Authentication](#authentication)
 
-The changelog & release-notes registry for developers and AI agents — a lean HTTP client for [releases.sh](https://releases.sh). Search and browse release notes from GitHub, RSS/Atom/JSON feeds, and product changelog pages, with no local infrastructure.
+The command-line client for [Release Notes Index](https://releases.sh), the changelog & release-notes registry for developers and AI agents. It's a lean HTTP client: search and browse release notes from GitHub, RSS/Atom/JSON feeds, and product changelog pages, with no local infrastructure.
 
 This repo is the **CLI** only. The backend that powers `api.releases.sh` — the API worker, MCP server, web frontend, and ingest pipeline — is open source in its own repo: [buildinternet/releases](https://github.com/buildinternet/releases).
 
@@ -98,7 +98,7 @@ releases json validate releases.json              # check a releases.json manife
 
 `json validate` is a read-only manifest check: it validates a [`releases.json`](https://releases.sh/docs/listing) v2 file against the published schema (pass a path or `-` for stdin) and adds `--json` for machine-readable output — no network, no submission.
 
-### MCP & Claude Code
+### MCP & agent plugins
 
 Point any MCP-compatible agent at the hosted server:
 
@@ -106,19 +106,21 @@ Point any MCP-compatible agent at the hosted server:
 npx mcp-remote https://agents.releases.sh/mcp
 ```
 
-This repo is also a Claude Code marketplace with the `releases` plugin — hosted MCP tools, a `/releases` lookup command, and auto-trigger skills:
+This repo also ships the `releases` plugin (`plugins/claude/releases`) — hosted MCP tools, a `/releases` lookup command, and auto-trigger skills — in the common agent-plugin layout. In Claude Code:
 
 ```bash
-/plugin marketplace add buildinternet/releases-cli
+/plugin marketplace add buildinternet/releases
 /plugin install releases@releases
 ```
 
+Other agent marketplaces (Grok Build via the [xAI plugin marketplace](https://github.com/xai-org/plugin-marketplace), and more as they are listed) install the same folder. Per-agent steps are in the [plugin README](plugins/claude/releases/README.md).
+
 Operator/maintainer skills (source onboarding, parsing, playbooks) live with the backend in the [releases monorepo](https://github.com/buildinternet/releases) — its `.claude/skills/` tree is picked up automatically in a checkout.
 
 Or install just the skills into any agent (Cursor, Codex, Gemini CLI, Windsurf, …):
 
 ```bash
-releases skills install        # or, without the CLI: npx skills add buildinternet/releases-cli
+releases skills install        # or, without the CLI: npx skills add buildinternet/releases
 ```
 
 ## Authentication
@@ -132,7 +134,7 @@ releases login --no-browser # print the URL + code to open yourself (headless /
 
 This uses the OAuth 2.0 Device Authorization Grant (RFC 8628): approve a short code at [releases.sh/device](https://releases.sh/device) in a signed-in browser, and a read-only key is saved to `~/.releases/credentials` (`0600`) — **the browser session itself is never saved**, only that key. Manage keys with `releases keys list` / `create` / `revoke`; each of those opens its own fresh browser approval and signs out again once the command finishes, rather than reusing a stored session (add `--no-browser` to print the URL + code instead, same as `login`).
 
-If you've verified ownership of a source's domain, mint a `publish-token` scoped to that one source — used by the [`publish-changelog` GitHub Action](https://releases.sh/docs/integrations/github-actions) as `RELEASES_API_TOKEN`. Like `releases keys`, this opens its own browser approval each time:
+If you've verified ownership of a source's domain, mint a `publish-token` scoped to that one source. The [`publish-changelog` GitHub Action](https://releases.sh/docs/integrations/github-actions) and `releases publish` both read it as `RELEASES_API_TOKEN`. Like `releases keys`, this opens its own browser approval each time:
 
 ```bash
 releases publish-token create --source src_… | gh secret set RELEASES_API_TOKEN
@@ -142,11 +144,45 @@ releases publish-token revoke <id>
 
 Already issued a token (e.g. a write/admin key during the closed beta)? Store it without the browser flow via `releases auth login` (interactive, `--token <token>`, or `--token -` for stdin); it's verified before being saved. `releases auth status` shows the current state (`whoami` is an alias). `RELEASES_API_KEY` in the environment overrides any stored credential — handy for CI.
 
+## Publish from any CI
+
+`releases publish` pushes changelog updates with `POST /v1/sources/…/releases/batch` (`mode: upsert-content`) — the same request as the [publish-changelog GitHub Action](https://releases.sh/docs/integrations/github-actions), for GitLab CI, Buildkite, or a local docs build.
+
+```bash
+releases publish --source src_… --dry-run
+releases publish --source acme/docs --changelog CHANGELOG.md --since "$CI_COMMIT_BEFORE_SHA" \
+  --url-template "https://gitlab.com/acme/app/-/blob/main/CHANGELOG.md#{key}"
+releases publish --source src_… --glob "changelog/**/*.mdx"
+```
+
+`--dry-run` prints the batch body and does not call the API (no token required). A real publish reads `RELEASES_API_TOKEN` and exits if it is missing. `--since <sha>` limits the plan to entries changed since that commit; omit it, or pass an all-zero first-push SHA, to publish every parsed entry. Repeating a publish is safe: unchanged bodies are not written again.
+
+Single-file mode parses versioned `##` headings (Keep a Changelog, conventional-changelog) and `## Month D, YYYY` sections. `--glob` switches to one MDX or Markdown file per release, with metadata in YAML frontmatter (`draft: true` is skipped). Deleted files are reported and left in the index.
+
+The commit you pass to `--since` has to be in the local clone (`fetch-depth: 0` on GitHub, or GitLab's default full clone). `--url-template` accepts `{key}`, `{version}`, `{date}`, `{path}`, and `{slug}`. When `GITHUB_REPOSITORY` is set and the template is omitted, the URL falls back to the file's GitHub blob URL, same as the Action.
+
+```yaml
+# .gitlab-ci.yml
+publish-changelog:
+  image: node:22
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      changes: [CHANGELOG.md]
+  script:
+    - npm install -g @buildinternet/releases
+    - |
+      releases publish \
+        --source "$RELEASES_SOURCE" \
+        --since "$CI_COMMIT_BEFORE_SHA" \
+        --url-template "https://gitlab.com/${CI_PROJECT_PATH}/-/blob/${CI_COMMIT_REF_NAME}/CHANGELOG.md#{key}"
+```
+
 ## Environment
 
 Reader access requires nothing. Useful overrides:
 
 - `RELEASES_API_KEY` — Bearer token for write endpoints; overrides stored credentials.
+- `RELEASES_API_TOKEN` — write-scoped publish token for `releases publish` (see [Publish from any CI](#publish-from-any-ci)).
 - `RELEASES_API_URL` — override the default `https://api.releases.sh` (e.g. staging).
 - `RELEASES_TELEMETRY_DISABLED=1` — opt out of anonymous usage pings (`DO_NOT_TRACK=1` also honored).
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@buildinternet/releases",
-  "version": "0.82.0",
-  "description": "The changelog & release-notes registry for developers and AI agents",
+  "version": "0.83.1",
+  "description": "CLI for Release Notes Index — the changelog & release-notes registry for developers and AI agents",
   "bin": {
     "releases": "bin/releases"
   },
@@ -13,11 +13,11 @@
     "README.md"
   ],
   "optionalDependencies": {
-    "@buildinternet/releases-darwin-arm64": "0.82.0",
-    "@buildinternet/releases-darwin-x64": "0.82.0",
-    "@buildinternet/releases-linux-x64": "0.82.0",
-    "@buildinternet/releases-linux-arm64": "0.82.0",
-    "@buildinternet/releases-windows-x64": "0.82.0"
+    "@buildinternet/releases-darwin-arm64": "0.83.1",
+    "@buildinternet/releases-darwin-x64": "0.83.1",
+    "@buildinternet/releases-linux-x64": "0.83.1",
+    "@buildinternet/releases-linux-arm64": "0.83.1",
+    "@buildinternet/releases-windows-x64": "0.83.1"
   },
   "keywords": [
     "changelog",