From a96c60a3ef6e94431ea98fef14c3d5833f759e3a Mon Sep 17 00:00:00 2001
From: Stefan Steiner <ssteiner@tableau.com>
Date: Wed, 13 May 2026 20:12:47 -0700
Subject: [PATCH] chore: set up release-please, bump Node to >=21, disable
 darwin-x64 npm builds
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wires up release-please as the release-management system, raises the
Node.js floor to v21, and turns off the currently-unreliable
darwin-x64 npm publishing path. No package versions change in this
commit — everything stays at 0.1.1. The merge commit prefix is `chore:`
so release-please will not auto-open a release PR after this lands; the
first release PR will appear after the next `feat:` or `fix:` commit
hits main.
---
 .github/workflows/release-please.yml          |  37 +++
 .github/workflows/release.yml                 |  27 +-
 .release-please-manifest.json                 |  17 ++
 CONTRIBUTING.md                               |  80 +++---
 DEVELOPMENT.md                                |   2 +-
 README.md                                     |  36 ++-
 docs/GITHUB_OPERATIONS.md                     | 251 +++++++++++-------
 hyperdb-api-core/CHANGELOG.md                 |   2 +
 hyperdb-api-node/AGENTS.md                    |   7 +-
 hyperdb-api-node/CHANGELOG.md                 |   2 +
 hyperdb-api-node/DEVELOPMENT.md               |  44 +--
 hyperdb-api-node/README.md                    |   9 +-
 .../examples/hyper-explorer/README.md         |   2 +-
 hyperdb-api-node/index.js                     |   4 +-
 .../npm/darwin-arm64/package.json             |   2 +-
 hyperdb-api-node/npm/darwin-x64/package.json  |   2 +-
 .../npm/linux-arm64-gnu/package.json          |   2 +-
 .../npm/linux-x64-gnu/package.json            |   2 +-
 .../npm/linux-x64-musl/package.json           |   2 +-
 .../npm/win32-x64-msvc/package.json           |   2 +-
 hyperdb-api-node/package.json                 |   4 +-
 hyperdb-api-salesforce/CHANGELOG.md           |   2 +
 hyperdb-api/CHANGELOG.md                      |   2 +
 hyperdb-bootstrap/CHANGELOG.md                |   2 +
 hyperdb-mcp/CHANGELOG.md                      |   2 +
 hyperdb-mcp/README.md                         |  63 ++++-
 hyperdb-mcp/npm/bin.js                        |   4 +-
 hyperdb-mcp/npm/darwin-arm64/package.json     |   2 +-
 hyperdb-mcp/npm/darwin-x64/package.json       |   2 +-
 hyperdb-mcp/npm/linux-x64-gnu/package.json    |   2 +-
 hyperdb-mcp/npm/package.json                  |   3 +-
 hyperdb-mcp/npm/win32-x64-msvc/package.json   |   2 +-
 release-please-config.json                    |  93 ++++++-
 sea-query-hyperdb/CHANGELOG.md                |   2 +
 34 files changed, 485 insertions(+), 232 deletions(-)
 create mode 100644 .github/workflows/release-please.yml
 create mode 100644 .release-please-manifest.json

diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
new file mode 100644
index 0000000..e682444
--- /dev/null
+++ b/.github/workflows/release-please.yml
@@ -0,0 +1,37 @@
+name: release-please
+
+# Maintains a single open "release PR" on main that bumps all workspace
+# versions, updates per-crate CHANGELOG.md files, and updates the
+# .release-please-manifest.json based on Conventional Commits since the
+# last release. Merging that PR creates a GitHub Release and a v{X.Y.Z}
+# tag.
+#
+# The downstream workflows trigger off the GitHub Release publish event
+# (release.yml → crates.io, npm-build-publish.yml → npm) rather than the
+# tag push. This avoids the GitHub Actions limitation where tags pushed
+# by GITHUB_TOKEN don't fire `on: push: tags:` workflows — which would
+# otherwise require a custom PAT.
+#
+# Maintainers don't run anything by hand:
+#   1. Land conventional-commit PRs into main.
+#   2. Merge the release-please PR when ready to ship.
+#
+# See docs/GITHUB_OPERATIONS.md → "Cutting a release" for details.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 5207cce..d96a827 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,8 +1,16 @@
 name: release
 
-# Tag-triggered publish to crates.io. Stable tags (v0.1.0) mark the
-# GitHub release as latest; pre-release tags (v0.1.0-rc.1) mark it as
-# prerelease so it doesn't show as "Latest release" on the repo home.
+# Publish to crates.io.
+#
+# Triggered by:
+#   - a GitHub Release published event (release-please drives this on
+#     merge of the release PR), or
+#   - a direct `git push origin v0.X.Y` tag push (emergency releases),
+#   - or a manual workflow_dispatch with an explicit existing tag.
+#
+# Stable tags (v0.1.0) mark the GitHub release as latest; pre-release
+# tags (v0.1.0-rc.1) mark it as prerelease so it doesn't show as
+# "Latest release" on the repo home.
 #
 # Publishing is destructive — version numbers on crates.io are
 # permanent. This workflow re-runs the full test matrix before
@@ -11,6 +19,12 @@ name: release
 # consistent for downstream crates.
 
 on:
+  # release-please drives most releases by merging the release PR and
+  # publishing a GitHub Release; that fires the `release: published`
+  # event below. Direct `git push origin v0.X.Y` tag pushes also work
+  # (e.g. for emergency releases that bypass release-please).
+  release:
+    types: [published]
   push:
     tags:
       - "v*.*.*-rc.*"
@@ -37,7 +51,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: ${{ github.event.inputs.tag || github.ref }}
+          ref: ${{ github.event.inputs.tag || github.event.release.tag_name || github.ref }}
 
       - name: Install system libraries
         run: sudo apt-get update -q && sudo apt-get install -y libfontconfig1-dev mold protobuf-compiler
@@ -80,7 +94,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: ${{ github.event.inputs.tag || github.ref }}
+          ref: ${{ github.event.inputs.tag || github.event.release.tag_name || github.ref }}
 
       - name: Install system libraries
         run: sudo apt-get update -q && sudo apt-get install -y libfontconfig1-dev mold protobuf-compiler
@@ -95,9 +109,10 @@ jobs:
         env:
           REF_NAME: ${{ github.ref_name }}
           INPUT_TAG: ${{ github.event.inputs.tag }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
         run: |
           set -euo pipefail
-          TAG="${INPUT_TAG:-$REF_NAME}"
+          TAG="${INPUT_TAG:-${RELEASE_TAG:-$REF_NAME}}"
           # Defense in depth: tags coming from workflow_dispatch are
           # user-supplied. Enforce a strict `vX.Y.Z` / `vX.Y.Z-rc.N`
           # shape before letting the name flow into cargo/git commands.
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
new file mode 100644
index 0000000..fdaa443
--- /dev/null
+++ b/.release-please-manifest.json
@@ -0,0 +1,17 @@
+{
+  "hyperdb-api-core": "0.1.1",
+  "hyperdb-api": "0.1.1",
+  "hyperdb-api-salesforce": "0.1.1",
+  "hyperdb-mcp": "0.1.1",
+  "hyperdb-bootstrap": "0.1.1",
+  "sea-query-hyperdb": "0.1.1",
+  "hyperdb-api-node": "0.1.1",
+  "hyperdb-mcp/npm/darwin-arm64": "0.1.1",
+  "hyperdb-mcp/npm/linux-x64-gnu": "0.1.1",
+  "hyperdb-mcp/npm/win32-x64-msvc": "0.1.1",
+  "hyperdb-api-node/npm/darwin-arm64": "0.1.1",
+  "hyperdb-api-node/npm/linux-arm64-gnu": "0.1.1",
+  "hyperdb-api-node/npm/linux-x64-gnu": "0.1.1",
+  "hyperdb-api-node/npm/linux-x64-musl": "0.1.1",
+  "hyperdb-api-node/npm/win32-x64-msvc": "0.1.1"
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4f93e09..a4756a7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -53,23 +53,23 @@ When a lint genuinely cannot be satisfied for a given site, suppress it with `#[
 
 # Contribution Checklist
 
-- [x] Clean, simple, well styled code — conforms to [docs/RUST_GUIDELINES.md](docs/RUST_GUIDELINES.md)
-- [x] Commits should be atomic and messages must be descriptive. Related issues should be mentioned by Issue number.
-- [x] Comments
+- [ ] Clean, simple, well styled code — conforms to [docs/RUST_GUIDELINES.md](docs/RUST_GUIDELINES.md)
+- [ ] Commits should be atomic and messages must be descriptive. Related issues should be mentioned by Issue number.
+- [ ] Comments
   - Module-level & function-level comments.
   - Comments on complex blocks of code or algorithms (include references to sources).
-- [x] Tests
+- [ ] Tests
   - The test suite, if provided, must be complete and pass
   - Increase code coverage, not versa.
   - See `hyperdb-api/tests/` for integration test patterns and `hyperdb-api/tests/common/mod.rs` for shared test helpers. Borrow inspiration from existing tests.
-- [x] Dependencies
+- [ ] Dependencies
   - Minimize number of dependencies.
   - Prefer MIT, Apache-2.0, BSD-3-Clause, ISC, and MPL-2.0 licenses (consistent with this project's dual MIT/Apache-2.0 license). Enforced by `cargo deny check`; see [deny.toml](deny.toml).
-- [x] Documentation
+- [ ] Documentation
   - Public API items have `///` doc comments with examples
   - README.md and DEVELOPMENT.md updated if behavior changes
   - New features include an example in `hyperdb-api/examples/` when applicable
-- [x] Reviews
+- [ ] Reviews
   - Changes must be approved via peer code review
 
 # Signed Commits
@@ -85,6 +85,11 @@ git config --global commit.gpgsign true
 git config --global tag.gpgsign true
 ```
 
+> If you have **multiple GitHub accounts** (e.g. work + personal) on the same
+> machine, swap `--global` for `--local` and run the commands from inside
+> this repo's checkout. That keeps the signing key + email scoped to this
+> clone instead of overriding your global identity for every other repo.
+
 If the key is not already registered on your GitHub account, add it under **Settings → SSH and GPG keys → New SSH key** with **Key type: Signing Key**. If it's already there as an Authentication Key, you don't need to add it again — GitHub verifies SSH signatures against every key on your account regardless of the type label. Trying to add the same key twice will fail with "Key is already in use"; that's fine.
 
 Verify with `git commit --allow-empty -m "test" && git log --show-signature -1` — you should see `Good "git" signature for <your email>`. After pushing, the commit shows a green **Verified** badge on GitHub.
@@ -165,45 +170,42 @@ chore: update arrow dependency to 56
 
 # Release Process
 
-> **Current state:** changelogs and version bumps are maintained **manually**
-> today. A [`release-please-config.json`](release-please-config.json) is checked
-> in for the future, but no GitHub Actions workflow currently invokes Release
-> Please — the maintainer-facing recipe in
-> [`docs/GITHUB_OPERATIONS.md`](docs/GITHUB_OPERATIONS.md) is authoritative.
-> When/if Release Please is wired up, this section will be revised.
-
-## Authoring changes (every contributor)
+This repo uses [release-please](https://github.com/googleapis/release-please)
+to fully automate version bumps, changelog generation, tagging, and the
+crates.io / npm publish dance.
 
-When a PR adds, changes, or removes any public API surface in a publishable
-crate (see the [Published Crates](#published-crates) table below), append a
-bullet to the `## [Unreleased]` section of that crate's `CHANGELOG.md` under
-the appropriate [Keep a Changelog](https://keepachangelog.com/) heading:
+## What contributors do
 
-- `### Added` — new public APIs, modules, tools, features.
-- `### Changed` — behavior changes that aren't breaking.
-- `### Deprecated` — APIs scheduled for removal.
-- `### Removed` — APIs removed in this release.
-- `### Fixed` — bug fixes that affect behavior.
-- `### Security` — security-relevant fixes.
+**Use [Conventional Commits](https://www.conventionalcommits.org/) for every
+PR title.** That's it. release-please reads the merged commits to figure out
+the next version and generate the changelog automatically. Commit-message
+prefixes drive the version bump per the table in
+[Commit Types and Version Impact](#commit-types-and-version-impact) above.
 
-Internal refactors that do not change the public API surface do not require a
-changelog entry. The `## [Unreleased]` section is promoted to a dated
-`## [X.Y.Z] - YYYY-MM-DD` section by the maintainer at release time.
+Contributors do **not** edit `CHANGELOG.md` files by hand and do **not** bump
+versions in `Cargo.toml` / `package.json` manually. Both are regenerated by
+release-please on every push to `main`.
 
-## Cutting a release (maintainer)
+## What maintainers do
 
-The end-to-end recipe lives in [`docs/GITHUB_OPERATIONS.md`](docs/GITHUB_OPERATIONS.md).
+The end-to-end flow lives in
+[`docs/GITHUB_OPERATIONS.md` → Cutting a release](docs/GITHUB_OPERATIONS.md#cutting-a-release).
 Summary:
 
-1. Bump every publishable crate's `Cargo.toml` `version` (and `package.json`
-   for `hyperdb-api-node`) to the new tag in lockstep.
-2. In each crate's `CHANGELOG.md`, keep an empty `## [Unreleased]` heading
-   at the top, then add `## [X.Y.Z] - YYYY-MM-DD` below it with all bullets
-   that accumulated under `[Unreleased]` since the last release.
-3. Open a release PR, merge to `main`, then tag the merge commit
-   (e.g. `v0.2.0`).
-4. CI publishes Rust crates to crates.io and `hyperdb-api-node` to npm via the
-   tag-triggered workflows.
+1. Land conventional-commit PRs into `main`.
+2. release-please opens (or updates) a single PR titled
+   `chore(main): release X.Y.Z` containing the version bumps and CHANGELOG
+   updates.
+3. Review and **merge** that PR when ready to ship. release-please tags the
+   merge commit and creates the GitHub Release.
+4. The tag triggers [`release.yml`](.github/workflows/release.yml)
+   (crates.io publish) and the GitHub Release triggers
+   [`npm-build-publish.yml`](.github/workflows/npm-build-publish.yml) (npm publish).
+   No further maintainer action is required.
+
+For pre-releases (`-rc.N`, `-alpha.N`, `-beta.N`), include a `Release-As:`
+footer in a commit on `main` — see
+[`docs/GITHUB_OPERATIONS.md`](docs/GITHUB_OPERATIONS.md#pre-releases).
 
 ## Published Crates
 
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index d3320cf..cfd87bc 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -91,7 +91,7 @@ graph LR
 
 The `hyperdb-api` crate has **zero feature flags** — all capabilities (TLS, pooling, geography,
 transactions, chrono) are always enabled. This simplifies dependency management and matches
-the C++/Python/Java APIs. Domain-specific functionality lives in companion crates instead.
+the C++/Python/Java APIs. Domain-specific functionality lives in companion crates instead. This may change before 1.0.0 if it's found that certain feature flags can greatly reduce the number of dependencies for users who don't need them, reduce the overall binary size and build time.
 
 ---
 
diff --git a/README.md b/README.md
index 18625d3..a23a471 100644
--- a/README.md
+++ b/README.md
@@ -89,38 +89,32 @@ Add to your `Cargo.toml`:
 hyperdb-api = { path = "hyperdb-api" }
 ```
 
-#### Pre-built binaries
+#### Installing the CLIs
 
-Release archives for the `hyperdb-mcp` and `hyperdb-bootstrap` CLIs are
-attached to every tagged release on the
-[Releases page](https://github.com/tableau/hyper-api-rust/releases).
-Supported targets: `x86_64-unknown-linux-gnu`, `aarch64-apple-darwin`,
-`x86_64-apple-darwin`, `x86_64-pc-windows-msvc`.
+`hyperdb-mcp` and `hyperdb-bootstrap` ship two ways:
 
-Linux / macOS:
+**Via npm** (recommended for `hyperdb-mcp`; bundles a matching `hyperd`):
 
 ```bash
-TAG=v0.1.0
-TARGET=x86_64-unknown-linux-gnu   # or aarch64-apple-darwin, x86_64-apple-darwin
-BIN=hyperdb-mcp                   # or hyperdb-bootstrap
-curl -fsSL "https://github.com/tableau/hyper-api-rust/releases/download/${TAG}/${BIN}-${TAG}-${TARGET}.tar.gz" \
-  | tar -xz -C /tmp
-sudo install "/tmp/${BIN}-${TAG}-${TARGET}/${BIN}" /usr/local/bin/
+npm install -g hyperdb-mcp
 ```
 
-Windows: download the `.zip` from the Releases page and extract the
-`.exe` to somewhere on `%PATH%`.
+Supported platforms: macOS ARM64 (Apple Silicon), Linux x64 (glibc),
+Windows x64. Intel macOS is built-from-source only at the moment — see
+the platform table in [`hyperdb-mcp/README.md`](hyperdb-mcp/README.md#installation).
 
-Verify downloads against the `SHA256SUMS.txt` attached to the release:
+**Via crates.io** (compiles from source; no bundled `hyperd`):
 
 ```bash
-sha256sum -c SHA256SUMS.txt
+cargo install hyperdb-mcp
+cargo install hyperdb-bootstrap
 ```
 
-**macOS Gatekeeper:** these binaries are unsigned. `curl | tar` extraction
-does not set the quarantine xattr, so the one-liner above works cleanly.
-If a `.tar.gz` downloaded via browser gets quarantined, clear it once with
-`xattr -d com.apple.quarantine <binary>`.
+`hyperdb-bootstrap` will then download a compatible `hyperd` for you:
+
+```bash
+hyperdb-bootstrap download
+```
 
 ### Environment Setup
 
diff --git a/docs/GITHUB_OPERATIONS.md b/docs/GITHUB_OPERATIONS.md
index 1e79d2c..397b25b 100644
--- a/docs/GITHUB_OPERATIONS.md
+++ b/docs/GITHUB_OPERATIONS.md
@@ -23,7 +23,8 @@ Four GitHub Actions workflows live under [`.github/workflows/`](../.github/workf
 | Workflow | File | Triggers | Purpose |
 |---|---|---|---|
 | `ci` | [ci.yml](../.github/workflows/ci.yml) | `push` to `main`, all PRs, manual | fmt, clippy, full test matrix, `cargo deny`, `cargo audit`, `cargo publish --dry-run` |
-| `release` | [release.yml](../.github/workflows/release.yml) | tag push matching `v*.*.*` / `v*.*.*-rc.*`, manual | re-run tests, build per-platform binaries, publish 6 Rust crates to crates.io (`hyperdb-api-node` is published separately to npm), attach archives to the GitHub Release |
+| `release-please` | [release-please.yml](../.github/workflows/release-please.yml) | `push` to `main`, manual | open/update the release PR; on merge, create the `vX.Y.Z` tag + GitHub Release |
+| `release` | [release.yml](../.github/workflows/release.yml) | tag push matching `v*.*.*` / `v*.*.*-rc.*`, manual | re-run tests, publish the 6 Rust crates to crates.io (`hyperdb-api-node` is published separately to npm) |
 | `npm-build-publish` | [npm-build-publish.yml](../.github/workflows/npm-build-publish.yml) | GitHub Release published, manual | build npm platform packages with bundled hyperd, publish to npm registry |
 | `verify-hyperd-pin` | [verify-hyperd-pin.yml](../.github/workflows/verify-hyperd-pin.yml) | changes to `hyperdb-bootstrap/hyperd-version.toml` or its source, weekly cron, manual | `HEAD` every pinned hyperd release URL to catch Tableau yanks / typos |
 
@@ -44,45 +45,30 @@ the PR. Main-branch runs always complete. This is set via the
 
 ### Release (`release.yml`)
 
-Runs on **tag push** (e.g. `git push origin v0.2.0`) or via manual
-`workflow_dispatch` with an explicit tag input. Structure:
+Runs on the **`release: published`** event (release-please publishes
+the GitHub Release after merging the release PR), on direct **tag push**
+matching `v*.*.*` (emergency releases that bypass release-please), or
+via manual `workflow_dispatch` with an explicit tag input. Structure:
 
 ```
 verify          ← full test suite + hyperd URL check, single-platform
    │
-   ├─► build-binaries (matrix × 4 targets)
-   │      build release binaries for hyperdb-mcp + hyperdb-bootstrap
-   │      package as .tar.gz / .zip, compute per-archive .sha256
-   │      upload as per-target GitHub Actions artifacts
-   │
-   └─► (gate) ──┐
-                ▼
-              publish          ← crates.io publish in dependency order,
-                                 then combine sha256 sidecars, then
-                                 create/update GitHub Release with
-                                 archives + SHA256SUMS.txt attached
+   └─► publish          ← crates.io publish in dependency order
 ```
 
-**Targets built** (binary archives only — the crates themselves are
-architecture-independent source on crates.io):
-
-| Target | Runner | Archive format |
-|---|---|---|
-| `x86_64-unknown-linux-gnu` | `ubuntu-latest` | `.tar.gz` |
-| `aarch64-apple-darwin` | `macos-14` | `.tar.gz` |
-| `x86_64-apple-darwin` | `macos-14` (cross) | `.tar.gz` |
-| `x86_64-pc-windows-msvc` | `windows-latest` | `.zip` |
-
-Other `hyperdb-api-node` triples (aarch64 Linux, musl Linux) are intentionally
-**not** built — `hyperd` itself is not supported on those platforms today,
-so a `hyperdb-bootstrap` binary for them would be a trap.
+There is no per-platform binary-archive build today. Users on supported
+platforms install via crates.io (`cargo install hyperdb-mcp`) or via npm
+(`npm install -g hyperdb-mcp`, which delivers prebuilt binaries through
+`npm-build-publish.yml`). The crates themselves are
+architecture-independent source on crates.io.
 
 **Dependency-ordered crates.io publish** (per-crate `sleep 45` between
 each so the crates.io index has time to settle before the next crate's
 verification step resolves the just-published dep):
 
-1. `hyperdb-api-core`
-2. `hyperdb-api-salesforce`
+1. `hyperdb-api-salesforce` (no workspace runtime deps; published first to
+   break the optional cycle with `hyperdb-api-core`)
+2. `hyperdb-api-core`
 3. `hyperdb-api`
 4. `hyperdb-mcp`
 5. `hyperdb-bootstrap`
@@ -135,17 +121,21 @@ verify-ci       ← checks that CI passed for this commit (gh api commit status)
 | Platform | Runner | Rust target | hyperd source |
 |---|---|---|---|
 | `darwin-arm64` | `macos-14` | `aarch64-apple-darwin` | `macos-arm64` |
-| `darwin-x64` | `macos-13` | `x86_64-apple-darwin` | `macos-x86_64` |
 | `linux-x64-gnu` | `ubuntu-latest` | `x86_64-unknown-linux-gnu` | `linux-x86_64` |
 | `win32-x64-msvc` | `windows-latest` | `x86_64-pc-windows-msvc` | `windows-x86_64` |
 
+`darwin-x64` (Intel macOS) is currently disabled — `macos-13` GHA
+runners have been unreliable. The matrix entry is commented out in
+[`npm-build-publish.yml`](../.github/workflows/npm-build-publish.yml)
+and will be re-enabled when runner availability stabilizes. Until then,
+Intel-Mac users must build from source.
+
 **npm packages published:**
 
 | Package | Type | Contents |
 |---|---|---|
 | `hyperdb-mcp` | Main (bin shim) | `bin.js` — detects platform, sets `HYPERD_PATH`, spawns native binary |
 | `hyperdb-mcp-darwin-arm64` | Platform | `hyperdb-mcp` + `hyperd` + `LICENSE-HYPERD` |
-| `hyperdb-mcp-darwin-x64` | Platform | same, Intel macOS |
 | `hyperdb-mcp-linux-x64-gnu` | Platform | same, Linux x64 |
 | `hyperdb-mcp-win32-x64-msvc` | Platform | same, Windows x64 |
 | `hyperdb-api-node` | Main (napi-rs) | JS bindings + `getHyperdPath()` helper |
@@ -198,83 +188,143 @@ still resolve (via `hyperdb-bootstrap verify`). Runs:
 
 ## Cutting a release
 
-End-to-end recipe for a maintainer:
-
-1. **Bump workspace versions to match the tag.** All 7 publishable crates
-   (6 Rust + `hyperdb-api-node` on npm) are kept in lockstep via their
-   `Cargo.toml` `version = ...` field (and `package.json` `version` for
-   `hyperdb-api-node`). The `publish` job fails fast if `hyperdb-api-core`'s
-   version doesn't match the tag, so CI will catch a forgotten bump.
-2. **Promote each crate's `## [Unreleased]` section to a dated `## [X.Y.Z] - YYYY-MM-DD`
-   section** in its `CHANGELOG.md`. The recommended pattern: keep an empty
-   `## [Unreleased]` heading at the top, then add `## [X.Y.Z] - YYYY-MM-DD`
-   below it with all the bullets that accumulated under `[Unreleased]` since
-   the last release. Contributors maintain `[Unreleased]` per the
-   [Authoring changes](../CONTRIBUTING.md#authoring-changes-every-contributor)
-   guide. (A [release-please-config.json](../release-please-config.json)
-   exists but is not currently wired to a workflow — this step is manual today.)
-3. **Open a PR and merge to `main`.** CI must be green.
-4. **Tag the merge commit:**
-   ```bash
-   git fetch origin
-   git tag -a v0.2.0 -m "v0.2.0" origin/main
-   git push origin v0.2.0
-   ```
-   For pre-releases, use `v0.2.0-rc.1` etc.
-5. **Watch the `release` workflow run.** Expected time: ~30-50 min total
-   (verify + 4 parallel binary builds + publish with 45 s gaps ×7).
-6. **Verify the release page.** Once the workflow goes green:
-   - https://github.com/tableau/hyper-api-rust/releases should list the
-     new tag with 8 `.tar.gz` / `.zip` archives (4 targets × 2 binaries)
-     plus `SHA256SUMS.txt`.
-   - Each crate should appear on crates.io under its new version.
+Releases are driven by [release-please](https://github.com/googleapis/release-please).
+Maintainers don't bump versions, edit changelogs, or push tags by hand — those
+steps are automated based on [Conventional Commits](https://www.conventionalcommits.org/).
+
+### How it flows
+
+1. Contributors land PRs into `main` with conventional-commit titles
+   (`feat:`, `fix:`, `chore:`, etc. — see
+   [CONTRIBUTING.md](../CONTRIBUTING.md#commit-message-format)).
+2. The [release-please workflow](../.github/workflows/release-please.yml)
+   runs on every push to `main`. It opens (or updates) a single
+   **release PR** titled `chore(main): release X.Y.Z`. That PR contains:
+   - All 7 workspace crates' versions bumped (Cargo.toml + package.json).
+   - The `optionalDependencies` and inter-crate version pins updated.
+   - A new dated section in each crate's `CHANGELOG.md` summarizing the
+     conventional commits that landed since the last release.
+   - An updated `.release-please-manifest.json`.
+3. A maintainer reviews the release PR. Adjust the version manually if a
+   different bump is needed (e.g., promote a `0.x.0` patch to a minor) by
+   editing the PR or by tagging commits with
+   [`Release-As: X.Y.Z`](https://github.com/googleapis/release-please?tab=readme-ov-file#how-can-i-fix-release-notes).
+4. **Merge the release PR.** release-please then:
+   - Creates a `vX.Y.Z` git tag on the merge commit.
+   - Creates a GitHub Release with the auto-generated changelog.
+5. The tag push fires [release.yml](../.github/workflows/release.yml),
+   which publishes the 6 Rust crates to crates.io.
+6. The GitHub Release publication fires
+   [npm-build-publish.yml](../.github/workflows/npm-build-publish.yml),
+   which builds and publishes `hyperdb-mcp` and `hyperdb-api-node` (plus
+   their per-platform packages) to npm.
+
+### How commits drive version bumps
+
+release-please reads the [Conventional Commits](https://www.conventionalcommits.org/)
+prefix on each commit since the last release tag and picks the largest
+bump implied. Mark a commit as a breaking change by either appending `!`
+after the type (e.g. `feat!:`) or by adding a `BREAKING CHANGE:` footer
+in the commit body.
+
+**Important pre-1.0 caveat:** while the workspace is on a `0.x.y`
+version, semver treats the entire `0.x` line as unstable, and
+release-please follows suit — a breaking change bumps the **minor**
+component, not the major. The major component stays at `0` until you
+explicitly opt into `1.0.0`.
+
+| Commit prefix on `main` | Bump from `0.1.0` to |
+|---|---|
+| `fix:`, `fix(scope):` | `0.1.1` (patch) |
+| `feat:`, `feat(scope):` | `0.2.0` (minor) |
+| `feat!:` / `fix!:` / `BREAKING CHANGE:` footer | `0.2.0` (still minor — no major bump while pre-1.0) |
+| `chore:`, `docs:`, `refactor:`, `test:`, `style:`, `ci:`, `perf:`, `build:` | no release |
+| Manual `Release-As: 1.0.0` footer | `1.0.0` (forces the major bump) |
+
+After the workspace is on `1.x.y`, the same prefixes follow normal
+semver: `feat!:` will bump `1.2.3` → `2.0.0` as expected. To stabilize
+the API and cut `1.0.0`, add a `Release-As: 1.0.0` footer to a
+conventional-commit on `main`:
+
+```
+feat: stabilize public API
+
+Release-As: 1.0.0
+```
+
+### Pre-releases
+
+For an `-rc.N` / `-alpha.N` / `-beta.N` release, add a footer to a
+commit on `main`:
+
+```
+Release-As: 0.2.0-rc.1
+```
+
+release-please will produce a release PR with that exact version on the
+next run. Pre-release tags flow through `release.yml` and
+`npm-build-publish.yml` exactly as stable releases do; the GitHub
+Release is auto-flagged as `prerelease: true`, and the npm `dist-tag` is
+set to `rc` / `alpha` / `beta` instead of `latest` so `npm install
+hyperdb-mcp` doesn't pull a pre-release by default.
+
+### Lockstep versioning
+
+All 7 workspace crates share a single version number, enforced by the
+`linked-versions` plugin in
+[release-please-config.json](../release-please-config.json). When any
+crate's commits trigger a bump, every crate moves together. This keeps
+`cargo publish`'s strict inter-crate version pins (`= "X.Y.Z"`) in sync
+without manual edits.
+
+### Verifying a release
+
+Once both `release.yml` and `npm-build-publish.yml` go green:
+
+- https://github.com/tableau/hyper-api-rust/releases should list the
+  new tag with auto-generated release notes.
+- Each crate appears on crates.io under the new version: e.g.
+  https://crates.io/crates/hyperdb-api/X.Y.Z.
+- `npm view hyperdb-mcp version` and
+  `npm view hyperdb-api-node version` report the new version.
 
 ### Re-running a partial failure
 
 The `release` workflow is mostly idempotent but there are two sharp edges:
 
-- **crates.io is append-only.** If the workflow publishes `hyperdb-api-core v0.2.0`
-  and then fails on `hyperdb-api`, you cannot republish `hyperdb-api-core v0.2.0`
-  — that version is burned. Bump the patch version, re-tag, and run again.
-  This is why `build-binaries` runs **before** `publish` — if the binary
-  build fails, nothing has hit crates.io yet and you can fix and re-tag
-  without a version bump.
-- **`softprops/action-gh-release@v2` appends assets.** If an asset was
-  uploaded on a failed run, the re-run will **not** overwrite it with the
-  new one. Delete stale assets by hand first:
-  ```bash
-  gh release delete-asset v0.2.0 <filename> --yes
-  ```
-  Then re-run the failed workflow from the GitHub Actions UI.
-
-### Manual release dispatch
-
-For a release where the tag already exists in `origin` (e.g. you want to
-rerun the release workflow after a CI fix that didn't change the tag
-contents), use the Actions UI:
+- **crates.io is append-only.** If the workflow publishes `hyperdb-api-core
+  v0.2.0` and then fails on `hyperdb-api`, you cannot republish
+  `hyperdb-api-core v0.2.0` — that version is burned. The fix is to land a
+  follow-up `fix:` commit on `main`, let release-please open a release PR
+  for `0.2.1`, and merge that.
+- **rate limits during the first publish of a brand-new crate.** crates.io
+  caps "new crate" creations at one per ~10 minutes. The first time we
+  publish a fresh crate name, the workflow may 429 partway through the
+  `Publish in dependency order` step. Wait for the cooldown printed in the
+  error and rerun via Actions → `release` → "Run workflow", entering the
+  same tag name in the `tag` input. Already-published crates fail loudly
+  with "already uploaded" and the run will continue past them via the
+  per-crate retry below.
+
+### Re-running release.yml against an existing tag
+
+For cases where the tag already exists in `origin` (e.g. you want to
+rerun `release.yml` after a transient infra failure), use the Actions UI:
 
 1. Actions → `release` → "Run workflow".
 2. Enter the existing tag name in the `tag` input (e.g. `v0.2.0`).
 3. Click Run.
 
-The workflow's same regex validator rejects malformed tag names, and
-`concurrency: release` still prevents racing with an in-flight run.
+The workflow's regex validator rejects malformed tag names, and
+`concurrency: release` prevents racing with an in-flight run.
 
 ## Secrets
 
 | Secret | Used by | Scope |
 |---|---|---|
-| `CRATES_IO_TOKEN` | [release.yml](../.github/workflows/release.yml) `publish` job | `cargo publish` to crates.io |
+| `CARGO_REGISTRY_TOKEN` | [release.yml](../.github/workflows/release.yml) `publish` job | `cargo publish` to crates.io |
 | `NPM_TOKEN` | [npm-build-publish.yml](../.github/workflows/npm-build-publish.yml) `publish-npm` job | `npm publish` to npmjs.org |
-| `GITHUB_TOKEN` | Every workflow | Auto-provided by GitHub Actions; used to fetch protoc, post releases, download artifacts, verify CI status |
-
-No Apple Developer ID cert is configured today — macOS binaries are
-unsigned. See the "macOS Gatekeeper" note in the README's
-[Pre-built binaries](../README.md#pre-built-binaries) section for the
-user-side workaround. Proper `codesign` + `notarytool` would require a
-`APPLE_DEVELOPER_ID_CERT` + `APPLE_DEVELOPER_ID_CERT_PASSWORD` +
-`APPLE_API_KEY_ID` / `APPLE_API_KEY_ISSUER_ID` / `APPLE_API_KEY` set of
-secrets and is a future task.
+| `GITHUB_TOKEN` | Every workflow | Auto-provided by GitHub Actions; used to post releases, download artifacts, verify CI status |
 
 ## Issue & PR templates
 
@@ -302,12 +352,15 @@ Check the actual live settings under
 - **CI failures on `main`:** investigate and fix forward. The cancel-on-new-push
   concurrency only applies to PRs; main-branch runs always complete, so a
   broken main is a real signal.
-- **`release` workflow failure before `publish`:** fix and re-tag
-  (deleting the stale tag locally and on `origin` first,
-  `git push origin :v0.2.0-rc.1`).
-- **`release` workflow failure during `publish`:** do *not* re-tag — the
-  already-published crates are burned. Bump to the next patch version
-  and try again.
+- **`release` workflow failure during `verify`:** the tag already exists,
+  so manual re-tagging isn't needed. Land the fix on `main`, then re-run
+  `release.yml` against the same tag from the Actions UI (`Run workflow`
+  → enter tag → run). Or, if the fix changes the tag contents, let the
+  next release-please PR mint a fresh patch tag.
+- **`release` workflow failure during `publish`:** the already-published
+  crates are burned (crates.io is append-only). Land a `fix:` commit on
+  `main` and merge the next release-please PR. Don't try to retag the
+  partially-published version.
 - **`verify-hyperd-pin` failure:** the pinned hyperd release URL 404'd.
   Check the Tableau releases page, update
   [`hyperdb-bootstrap/hyperd-version.toml`](../hyperdb-bootstrap/hyperd-version.toml)
@@ -322,4 +375,4 @@ Check the actual live settings under
 - [docs/RUST_GUIDELINES.md](RUST_GUIDELINES.md) — coding standards enforced by `ci.yml`.
 - [AGENTS.md](../AGENTS.md) — codebase architecture and build commands for contributors.
 - [deny.toml](../deny.toml) — `cargo deny` policy (licenses, advisories).
-- [README.md#pre-built-binaries](../README.md#pre-built-binaries) — user-side install snippet for the binaries this workflow produces.
+- [README.md → Installing the CLIs](../README.md#installing-the-clis) — user-side install paths (npm + cargo install).
diff --git a/hyperdb-api-core/CHANGELOG.md b/hyperdb-api-core/CHANGELOG.md
index 33eda4d..10449b0 100644
--- a/hyperdb-api-core/CHANGELOG.md
+++ b/hyperdb-api-core/CHANGELOG.md
@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-05-13
+
 ### Added
 
 `types` module — SQL type system, binary encoding, OIDs:
diff --git a/hyperdb-api-node/AGENTS.md b/hyperdb-api-node/AGENTS.md
index f7a766f..c5b2ab4 100644
--- a/hyperdb-api-node/AGENTS.md
+++ b/hyperdb-api-node/AGENTS.md
@@ -50,7 +50,7 @@ For documentation conventions specific to JavaScript/TypeScript, see the [Docume
 
 ## Build and Test Commands
 
-**Prerequisites:** Rust toolchain, Node.js >= 18, `HYPERD_PATH` set.
+**Prerequisites:** Rust toolchain, Node.js >= 21, `HYPERD_PATH` set.
 
 ```bash
 cd hyperdb-api-node
@@ -124,13 +124,14 @@ Uses napi-rs platform packages for cross-platform prebuilt binaries:
 | Platform | Package |
 |----------|---------|
 | macOS ARM64 | `hyperdb-api-node-darwin-arm64` |
-| macOS x64 | `hyperdb-api-node-darwin-x64` |
 | Linux x64 (glibc) | `hyperdb-api-node-linux-x64-gnu` |
 | Linux x64 (musl) | `hyperdb-api-node-linux-x64-musl` |
 | Linux ARM64 | `hyperdb-api-node-linux-arm64-gnu` |
 | Windows x64 | `hyperdb-api-node-win32-x64-msvc` |
 
-CI builds all platforms on push. Publishing is triggered by a `release:` commit on `main`.
+macOS x64 (Intel) is currently disabled — `macos-13` GHA runners are unreliable.
+
+CI builds all enabled platforms on push. Publishing is driven by release-please.
 
 ## Common Development Scenarios
 
diff --git a/hyperdb-api-node/CHANGELOG.md b/hyperdb-api-node/CHANGELOG.md
index 775759e..2915532 100644
--- a/hyperdb-api-node/CHANGELOG.md
+++ b/hyperdb-api-node/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-05-13
+
 ### Added
 
 - `HyperProcess` for managing local `hyperd` server instances
diff --git a/hyperdb-api-node/DEVELOPMENT.md b/hyperdb-api-node/DEVELOPMENT.md
index 9c59aad..03fc3c5 100644
--- a/hyperdb-api-node/DEVELOPMENT.md
+++ b/hyperdb-api-node/DEVELOPMENT.md
@@ -254,7 +254,7 @@ classDiagram
 ### Prerequisites
 
 1. **Rust toolchain** — install via [rustup](https://rustup.rs/)
-2. **Node.js** >= 18
+2. **Node.js** >= 21
 3. **npm** >= 9
 4. **`hyperd` binary** — set `HYPERD_PATH` environment variable
 
@@ -326,50 +326,34 @@ columnar query, Arrow query, filtered queries, and aggregation.
 ## Publishing to npm
 
 The package uses [napi-rs](https://napi.rs/) to publish prebuilt native
-binaries for each platform. A GitHub Actions workflow
-(`.github/workflows/hyperdb-api-node.yml`) automates the build, test, and
-publish pipeline.
+binaries for each platform. Releases are driven by **release-please** —
+contributors don't bump versions or push tags by hand. See
+[CONTRIBUTING.md → Release Process](../CONTRIBUTING.md#release-process)
+and [docs/GITHUB_OPERATIONS.md → Cutting a release](../docs/GITHUB_OPERATIONS.md#cutting-a-release)
+for the end-to-end flow.
 
 ### Platform packages
 
 | Platform | Package |
 |----------|---------|
 | macOS ARM64 | `hyperdb-api-node-darwin-arm64` |
-| macOS x64 | `hyperdb-api-node-darwin-x64` |
 | Linux x64 (glibc) | `hyperdb-api-node-linux-x64-gnu` |
 | Linux x64 (musl) | `hyperdb-api-node-linux-x64-musl` |
 | Linux ARM64 | `hyperdb-api-node-linux-arm64-gnu` |
 | Windows x64 | `hyperdb-api-node-win32-x64-msvc` |
 
-### Setup (one-time)
+macOS x64 (Intel) builds are currently disabled — see [`npm-build-publish.yml`](../.github/workflows/npm-build-publish.yml)
+matrix; we'll re-enable once `macos-13` runner availability is reliable.
 
-1. Create an npm access token: `npm token create`
-2. Add it as a GitHub repo secret named `NPM_TOKEN` (Settings > Secrets > Actions)
-
-### How it works
-
-- On every push to `main` or `ssteiner/**` branches, CI builds native binaries
-  for all 6 platforms
-- Tests run on macOS (ARM64 + x64), Linux, and Windows
-- Publishing is triggered when a commit on `main` starts with `release:`
-
-```bash
-# Bump version in package.json and all npm/*/package.json
-npm version patch   # or minor / major
-git push origin main
-
-# Then merge a commit with this message format:
-git commit --allow-empty -m "release: v0.1.1"
-git push origin main
-```
-
-CI publishes:
-1. Platform packages (`hyperdb-api-node-darwin-arm64`, etc.)
-2. Main package (`hyperdb-api-node`) — users install this, npm auto-downloads the
-   right binary
+The build/publish pipeline lives in
+[`.github/workflows/npm-build-publish.yml`](../.github/workflows/npm-build-publish.yml);
+it triggers off the GitHub Release event that release-please publishes.
 
 ### Manual publish (without CI)
 
+For local one-off testing only — production releases always go through
+release-please + CI.
+
 ```bash
 # Build for your current platform
 npm run build
diff --git a/hyperdb-api-node/README.md b/hyperdb-api-node/README.md
index 7dbc6c8..2de0bd4 100644
--- a/hyperdb-api-node/README.md
+++ b/hyperdb-api-node/README.md
@@ -33,7 +33,7 @@ For a detailed class diagram with all methods and properties, see
 
 ## Requirements
 
-- **Node.js** >= 18
+- **Node.js** >= 21
 - **Hyper server binary** (`hyperd`) — set `HYPERD_PATH` env var or place in standard location
 
 ## Installation
@@ -49,17 +49,20 @@ npm will automatically install the correct prebuilt binary for your platform via
 | Platform | Architecture | Package |
 |---|---|---|
 | macOS | ARM64 (Apple Silicon) | `hyperdb-api-node-darwin-arm64` |
-| macOS | x64 (Intel) | `hyperdb-api-node-darwin-x64` |
 | Linux | x64 (glibc) | `hyperdb-api-node-linux-x64-gnu` |
 | Linux | x64 (musl/Alpine) | `hyperdb-api-node-linux-x64-musl` |
 | Linux | ARM64 (glibc) | `hyperdb-api-node-linux-arm64-gnu` |
 | Windows | x64 (MSVC) | `hyperdb-api-node-win32-x64-msvc` |
 
+> **macOS x64 (Intel) is not currently published** while we wait for `macos-13`
+> GitHub Actions runners to become reliably available. Build from source for
+> Intel Macs in the meantime.
+
 ### Build from source
 
 To build from the workspace source instead, you'll need:
 
-- Node.js >= 18
+- Node.js >= 21
 - Rust stable (install via [rustup](https://rustup.rs/))
 - `protoc` — `brew install protobuf` (macOS), `apt-get install protobuf-compiler` (Debian/Ubuntu), or `choco install protoc` (Windows)
 - The `hyperd` binary (`make download-hyperd` from the repo root, or set `HYPERD_PATH` to an existing copy)
diff --git a/hyperdb-api-node/examples/hyper-explorer/README.md b/hyperdb-api-node/examples/hyper-explorer/README.md
index 41fae89..412564f 100644
--- a/hyperdb-api-node/examples/hyper-explorer/README.md
+++ b/hyperdb-api-node/examples/hyper-explorer/README.md
@@ -6,7 +6,7 @@ The UI is a React SPA (Vite + Tailwind). The API is Express + TypeScript, backed
 
 ## Prerequisites
 
-- **Node.js** >= 18  
+- **Node.js** >= 21  
 - **Rust toolchain** (stable) — required to build `hyperdb-api-node` from the workspace when using `file:../../`  
 - **`hyperdb-api-node` built** — from the `hyperdb-api-node/` directory:
   - Release: `npm run build` (faster runtime)
diff --git a/hyperdb-api-node/index.js b/hyperdb-api-node/index.js
index 58473e9..6fd953d 100644
--- a/hyperdb-api-node/index.js
+++ b/hyperdb-api-node/index.js
@@ -31,7 +31,9 @@ function isMusl() {
 function getPlatformPackage() {
   switch (platform) {
     case 'darwin':
-      return arch === 'arm64' ? 'hyperdb-api-node-darwin-arm64' : 'hyperdb-api-node-darwin-x64'
+      // darwin-x64 builds are disabled until macos-13 GHA runners are
+      // reliable again — see npm-build-publish.yml matrix.
+      return arch === 'arm64' ? 'hyperdb-api-node-darwin-arm64' : null
     case 'linux':
       if (arch === 'arm64') return isMusl() ? 'hyperdb-api-node-linux-arm64-musl' : 'hyperdb-api-node-linux-arm64-gnu'
       return isMusl() ? 'hyperdb-api-node-linux-x64-musl' : 'hyperdb-api-node-linux-x64-gnu'
diff --git a/hyperdb-api-node/npm/darwin-arm64/package.json b/hyperdb-api-node/npm/darwin-arm64/package.json
index 28f45b5..87af42d 100644
--- a/hyperdb-api-node/npm/darwin-arm64/package.json
+++ b/hyperdb-api-node/npm/darwin-arm64/package.json
@@ -16,6 +16,6 @@
   "description": "hyperdb-api-node native binding for macOS ARM64 (Apple Silicon)",
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   }
 }
\ No newline at end of file
diff --git a/hyperdb-api-node/npm/darwin-x64/package.json b/hyperdb-api-node/npm/darwin-x64/package.json
index 5719431..54e1f27 100644
--- a/hyperdb-api-node/npm/darwin-x64/package.json
+++ b/hyperdb-api-node/npm/darwin-x64/package.json
@@ -16,6 +16,6 @@
   "description": "hyperdb-api-node native binding for macOS x64 (Intel)",
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   }
 }
\ No newline at end of file
diff --git a/hyperdb-api-node/npm/linux-arm64-gnu/package.json b/hyperdb-api-node/npm/linux-arm64-gnu/package.json
index e7ed40f..d92f889 100644
--- a/hyperdb-api-node/npm/linux-arm64-gnu/package.json
+++ b/hyperdb-api-node/npm/linux-arm64-gnu/package.json
@@ -14,7 +14,7 @@
   "description": "hyperdb-api-node native binding for Linux ARM64 (glibc)",
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   },
   "libc": [
     "glibc"
diff --git a/hyperdb-api-node/npm/linux-x64-gnu/package.json b/hyperdb-api-node/npm/linux-x64-gnu/package.json
index e168538..3d0d0cf 100644
--- a/hyperdb-api-node/npm/linux-x64-gnu/package.json
+++ b/hyperdb-api-node/npm/linux-x64-gnu/package.json
@@ -16,7 +16,7 @@
   "description": "hyperdb-api-node native binding for Linux x64 (glibc)",
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   },
   "libc": [
     "glibc"
diff --git a/hyperdb-api-node/npm/linux-x64-musl/package.json b/hyperdb-api-node/npm/linux-x64-musl/package.json
index 4484025..7241bc8 100644
--- a/hyperdb-api-node/npm/linux-x64-musl/package.json
+++ b/hyperdb-api-node/npm/linux-x64-musl/package.json
@@ -14,7 +14,7 @@
   "description": "hyperdb-api-node native binding for Linux x64 (musl/Alpine)",
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   },
   "libc": [
     "musl"
diff --git a/hyperdb-api-node/npm/win32-x64-msvc/package.json b/hyperdb-api-node/npm/win32-x64-msvc/package.json
index 28737b4..67469dc 100644
--- a/hyperdb-api-node/npm/win32-x64-msvc/package.json
+++ b/hyperdb-api-node/npm/win32-x64-msvc/package.json
@@ -16,6 +16,6 @@
   "description": "hyperdb-api-node native binding for Windows x64 (MSVC)",
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   }
 }
\ No newline at end of file
diff --git a/hyperdb-api-node/package.json b/hyperdb-api-node/package.json
index 981731c..b45ce1b 100644
--- a/hyperdb-api-node/package.json
+++ b/hyperdb-api-node/package.json
@@ -8,7 +8,6 @@
     "binaryName": "hyperdb-api-node",
     "targets": [
       "aarch64-apple-darwin",
-      "x86_64-apple-darwin",
       "x86_64-unknown-linux-gnu",
       "x86_64-unknown-linux-musl",
       "aarch64-unknown-linux-gnu",
@@ -32,7 +31,6 @@
   },
   "optionalDependencies": {
     "hyperdb-api-node-darwin-arm64": "0.1.1",
-    "hyperdb-api-node-darwin-x64": "0.1.1",
     "hyperdb-api-node-linux-arm64-gnu": "0.1.1",
     "hyperdb-api-node-linux-x64-gnu": "0.1.1",
     "hyperdb-api-node-linux-x64-musl": "0.1.1",
@@ -56,7 +54,7 @@
     "directory": "hyperdb-api-node"
   },
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   },
   "files": [
     "index.js",
diff --git a/hyperdb-api-salesforce/CHANGELOG.md b/hyperdb-api-salesforce/CHANGELOG.md
index 05adda0..417c645 100644
--- a/hyperdb-api-salesforce/CHANGELOG.md
+++ b/hyperdb-api-salesforce/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-05-13
+
 ### Added
 
 - `SalesforceAuthConfig` for configuring Data Cloud OAuth credentials
diff --git a/hyperdb-api/CHANGELOG.md b/hyperdb-api/CHANGELOG.md
index 186d992..6ba303b 100644
--- a/hyperdb-api/CHANGELOG.md
+++ b/hyperdb-api/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-05-13
+
 ### Added
 
 Connections and process management:
diff --git a/hyperdb-bootstrap/CHANGELOG.md b/hyperdb-bootstrap/CHANGELOG.md
index 3eacfe7..4cd4044 100644
--- a/hyperdb-bootstrap/CHANGELOG.md
+++ b/hyperdb-bootstrap/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-05-13
+
 ### Added
 
 - `install()` library function and `hyperdb-bootstrap` CLI binary
diff --git a/hyperdb-mcp/CHANGELOG.md b/hyperdb-mcp/CHANGELOG.md
index fd493e4..482b254 100644
--- a/hyperdb-mcp/CHANGELOG.md
+++ b/hyperdb-mcp/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-05-13
+
 ### Added
 
 MCP tools — query and execute:
diff --git a/hyperdb-mcp/README.md b/hyperdb-mcp/README.md
index 39383d0..f0418d3 100644
--- a/hyperdb-mcp/README.md
+++ b/hyperdb-mcp/README.md
@@ -8,16 +8,16 @@ Built on the pure-Rust [`hyperdb-api`](../hyperdb-api/) crate for maximum perfor
 
 ## Why
 
-LLMs are powerful at reasoning but cannot natively crunch millions of rows. This plugin bridges that gap: another MCP tool produces data, the LLM passes it to `hyperdb-mcp`, Hyper ingests it and makes it SQL-queryable, the LLM runs analytical SQL, and results come back as JSON. Optionally export to CSV, Parquet, Arrow IPC, or `.hyper` (opens directly in **Tableau Desktop**).
+LLMs are powerful at reasoning but cannot natively crunch millions of rows. This plugin bridges that gap: another MCP tool produces data, the LLM passes it to `hyperdb-mcp`, Hyper ingests it and makes it SQL-queryable, the LLM runs analytical SQL, and results come back as JSON. Optionally export to CSV, Parquet, Apache Iceberg, Arrow IPC, or `.hyper` (opens directly in **Tableau Desktop**).
 
 ---
 
 ## Features
 
 - **Zero setup** — `HyperProcess` auto-starts the Hyper server
-- **Any data in** — JSON, CSV, Parquet, Arrow IPC; schema inferred or exact
+- **Any data in** — JSON, CSV, Parquet, Arrow IPC, Apache Iceberg; schema inferred or exact
 - **SQL at scale** — thousands to billions of rows
-- **Data out** — export to CSV, Parquet, Arrow IPC, or `.hyper` (Tableau Desktop-ready)
+- **Data out** — export to CSV, Parquet, Apache Iceberg, Arrow IPC, or `.hyper` (Tableau Desktop-ready)
 - **One-shot queries** — `query_file("/tmp/sales.csv", "SELECT ...")` — single call, zero management
 - **Persistent workspace** — load multiple tables, JOIN across them, persist across sessions
 - **Read-only safe mode** — `--read-only` flag for safe deployment
@@ -39,12 +39,42 @@ LLMs are powerful at reasoning but cannot natively crunch millions of rows. This
 
 ### From npm
 
+> **Requirement:** Node.js **v21 or later**. Earlier versions ship an
+> older `npx` whose argument parsing is incompatible with the
+> `npx -y hyperdb-mcp` invocation in the MCP config below. If you're
+> on an older Node, see [Upgrading Node.js with nvm](#upgrading-nodejs-with-nvm)
+> below.
+
 ```bash
 npm install -g hyperdb-mcp
 ```
 
 The npm package bundles both the `hyperdb-mcp` binary and the `hyperd` database server — no additional setup required.
 
+### Upgrading Node.js with nvm
+
+`nvm` (Node Version Manager) makes it easy to install and switch between Node.js versions.
+
+**macOS / Linux** ([nvm-sh/nvm](https://github.com/nvm-sh/nvm)):
+```bash
+# install nvm if you don't have it
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+
+# install and use the latest LTS (>= 21)
+nvm install --lts
+nvm use --lts
+node --version    # should report v22.x.x or newer
+```
+
+**Windows** ([coreybutler/nvm-windows](https://github.com/coreybutler/nvm-windows)): download the installer, then in a new shell:
+```powershell
+nvm install lts
+nvm use lts
+node --version
+```
+
+After upgrading, restart your MCP client so it picks up the new Node binary on `PATH`.
+
 ### Building from Source
 
 ```bash
@@ -88,6 +118,7 @@ For a **persistent workspace** (tables survive across sessions), add `"args"`:
 ```json
 "args": ["--workspace", "/path/to/my-project.hyper"]
 ```
+This is still **experimental** and will only work with only one session at a time since the Hyper database is locked by Hyper. Each session is isolated and has its own Hyper instance running. Future work will allow multiple sessions to share the same database but requires work to spin up a shared Hyper instance.
 
 #### Claude Code / AI Suite
 
@@ -184,6 +215,28 @@ When you're unsure of the right types — or recovering from a previous
 exact schema `load_file` would use plus per-column `min` / `max` / `null_count`
 so you can build a minimal, correct override in one shot.
 
+#### `load_iceberg`
+
+Load an [Apache Iceberg](https://iceberg.apache.org/) table into a named
+workspace table. Pass the absolute path to the Iceberg table root (the
+directory containing `metadata/` and `data/`); hyperd's native Iceberg
+reader derives the schema and resolves the snapshot.
+
+```
+load_iceberg(table: 'sales', path: '/lake/warehouse/db/sales')
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `table` | string | yes | Target Hyper table name |
+| `path` | string | yes | Absolute path to the Iceberg table root directory |
+| `mode` | string | no | `"replace"` (default) or `"append"` |
+| `metadata_filename` | string | no | Pin a specific snapshot, e.g. `"v2.metadata.json"`. Omit for latest. |
+| `version_as_of` | integer | no | Pin a snapshot by version number |
+
+Schema overrides are not accepted — hyperd derives the schema from the
+Iceberg table metadata.
+
 #### `query`
 
 Run a **read-only** SQL query against the workspace. Accepts `SELECT`, `WITH`, `EXPLAIN`, `SHOW`, `VALUES`. For DDL/DML use `execute`.
@@ -323,7 +376,7 @@ export(sql: 'SELECT ...', path: '~/Desktop/analysis.hyper', format: 'hyper')
 | `sql` | string | no | Query to export (if omitted, exports whole table) |
 | `table` | string | no | Table name (used if `sql` omitted) |
 | `path` | string | yes | Output file path |
-| `format` | string | yes | `"csv"`, `"parquet"`, `"arrow_ipc"`, or `"hyper"` |
+| `format` | string | yes | `"csv"`, `"parquet"`, `"iceberg"`, `"arrow_ipc"`, or `"hyper"` |
 
 The `"hyper"` format produces a `.hyper` file that opens directly in **Tableau Desktop**.
 
@@ -365,7 +418,7 @@ unwatch_directory(path: '/tmp/inbox')
 
 **Producer protocol (`.ready` sentinel):**
 
-1. Write data file atomically (e.g. `foo.csv.tmp` then rename to `foo.csv`).
+1. Write data file (e.g. `foo.csv`) and close it.
 2. Create a zero-byte companion `foo.csv.ready` — this is the atomic signal.
 3. Poll for the absence of `foo.csv.ready` to confirm the watcher is done.
 
diff --git a/hyperdb-mcp/npm/bin.js b/hyperdb-mcp/npm/bin.js
index 47d3bb5..4a574de 100644
--- a/hyperdb-mcp/npm/bin.js
+++ b/hyperdb-mcp/npm/bin.js
@@ -11,7 +11,9 @@ const { platform, arch } = process
 function getPlatformPackage() {
   switch (platform) {
     case 'darwin':
-      return arch === 'arm64' ? 'hyperdb-mcp-darwin-arm64' : 'hyperdb-mcp-darwin-x64'
+      // darwin-x64 builds are disabled until macos-13 GHA runners are
+      // reliable again — see npm-build-publish.yml matrix.
+      return arch === 'arm64' ? 'hyperdb-mcp-darwin-arm64' : null
     case 'linux':
       return 'hyperdb-mcp-linux-x64-gnu'
     case 'win32':
diff --git a/hyperdb-mcp/npm/darwin-arm64/package.json b/hyperdb-mcp/npm/darwin-arm64/package.json
index e65a58c..f486aae 100644
--- a/hyperdb-mcp/npm/darwin-arm64/package.json
+++ b/hyperdb-mcp/npm/darwin-arm64/package.json
@@ -11,7 +11,7 @@
   ],
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   },
   "repository": {
     "type": "git",
diff --git a/hyperdb-mcp/npm/darwin-x64/package.json b/hyperdb-mcp/npm/darwin-x64/package.json
index 1ebec1d..a46ced4 100644
--- a/hyperdb-mcp/npm/darwin-x64/package.json
+++ b/hyperdb-mcp/npm/darwin-x64/package.json
@@ -11,7 +11,7 @@
   ],
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   },
   "repository": {
     "type": "git",
diff --git a/hyperdb-mcp/npm/linux-x64-gnu/package.json b/hyperdb-mcp/npm/linux-x64-gnu/package.json
index 9b3371b..207bbde 100644
--- a/hyperdb-mcp/npm/linux-x64-gnu/package.json
+++ b/hyperdb-mcp/npm/linux-x64-gnu/package.json
@@ -12,7 +12,7 @@
   ],
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   },
   "repository": {
     "type": "git",
diff --git a/hyperdb-mcp/npm/package.json b/hyperdb-mcp/npm/package.json
index 5eaed23..ed94a4c 100644
--- a/hyperdb-mcp/npm/package.json
+++ b/hyperdb-mcp/npm/package.json
@@ -7,7 +7,6 @@
   },
   "optionalDependencies": {
     "hyperdb-mcp-darwin-arm64": "0.1.1",
-    "hyperdb-mcp-darwin-x64": "0.1.1",
     "hyperdb-mcp-linux-x64-gnu": "0.1.1",
     "hyperdb-mcp-win32-x64-msvc": "0.1.1"
   },
@@ -33,6 +32,6 @@
   },
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   }
 }
diff --git a/hyperdb-mcp/npm/win32-x64-msvc/package.json b/hyperdb-mcp/npm/win32-x64-msvc/package.json
index b23865a..ed17be7 100644
--- a/hyperdb-mcp/npm/win32-x64-msvc/package.json
+++ b/hyperdb-mcp/npm/win32-x64-msvc/package.json
@@ -11,7 +11,7 @@
   ],
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 21"
   },
   "repository": {
     "type": "git",
diff --git a/release-please-config.json b/release-please-config.json
index 5a1e2da..9f44038 100644
--- a/release-please-config.json
+++ b/release-please-config.json
@@ -1,33 +1,56 @@
 {
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "rust",
+  "include-component-in-tag": false,
+  "separate-pull-requests": false,
+  "plugins": [
+    {
+      "type": "linked-versions",
+      "groupName": "hyper-api-rust",
+      "components": [
+        "hyperdb-api-core",
+        "hyperdb-api",
+        "hyperdb-api-salesforce",
+        "hyperdb-mcp",
+        "hyperdb-bootstrap",
+        "sea-query-hyperdb",
+        "hyperdb-api-node",
+        "hyperdb-mcp-darwin-arm64",
+        "hyperdb-mcp-linux-x64-gnu",
+        "hyperdb-mcp-win32-x64-msvc",
+        "hyperdb-api-node-darwin-arm64",
+        "hyperdb-api-node-linux-arm64-gnu",
+        "hyperdb-api-node-linux-x64-gnu",
+        "hyperdb-api-node-linux-x64-musl",
+        "hyperdb-api-node-win32-x64-msvc"
+      ]
+    }
+  ],
   "packages": {
     "hyperdb-api-core": {
-      "release-type": "rust",
       "component": "hyperdb-api-core",
       "changelog-path": "CHANGELOG.md"
     },
     "hyperdb-api": {
-      "release-type": "rust",
       "component": "hyperdb-api",
       "changelog-path": "CHANGELOG.md"
     },
     "hyperdb-api-salesforce": {
-      "release-type": "rust",
       "component": "hyperdb-api-salesforce",
       "changelog-path": "CHANGELOG.md"
     },
     "hyperdb-mcp": {
-      "release-type": "rust",
       "component": "hyperdb-mcp",
-      "changelog-path": "CHANGELOG.md"
+      "changelog-path": "CHANGELOG.md",
+      "extra-files": [
+        "npm/package.json"
+      ]
     },
     "hyperdb-bootstrap": {
-      "release-type": "rust",
       "component": "hyperdb-bootstrap",
       "changelog-path": "CHANGELOG.md"
     },
     "sea-query-hyperdb": {
-      "release-type": "rust",
       "component": "sea-query-hyperdb",
       "changelog-path": "CHANGELOG.md"
     },
@@ -35,6 +58,62 @@
       "release-type": "node",
       "component": "hyperdb-api-node",
       "changelog-path": "CHANGELOG.md"
+    },
+    "hyperdb-mcp/npm/darwin-arm64": {
+      "release-type": "node",
+      "component": "hyperdb-mcp-darwin-arm64",
+      "skip-github-release": true,
+      "skip-github-pull-request": false,
+      "changelog-path": false
+    },
+    "hyperdb-mcp/npm/linux-x64-gnu": {
+      "release-type": "node",
+      "component": "hyperdb-mcp-linux-x64-gnu",
+      "skip-github-release": true,
+      "skip-github-pull-request": false,
+      "changelog-path": false
+    },
+    "hyperdb-mcp/npm/win32-x64-msvc": {
+      "release-type": "node",
+      "component": "hyperdb-mcp-win32-x64-msvc",
+      "skip-github-release": true,
+      "skip-github-pull-request": false,
+      "changelog-path": false
+    },
+    "hyperdb-api-node/npm/darwin-arm64": {
+      "release-type": "node",
+      "component": "hyperdb-api-node-darwin-arm64",
+      "skip-github-release": true,
+      "skip-github-pull-request": false,
+      "changelog-path": false
+    },
+    "hyperdb-api-node/npm/linux-arm64-gnu": {
+      "release-type": "node",
+      "component": "hyperdb-api-node-linux-arm64-gnu",
+      "skip-github-release": true,
+      "skip-github-pull-request": false,
+      "changelog-path": false
+    },
+    "hyperdb-api-node/npm/linux-x64-gnu": {
+      "release-type": "node",
+      "component": "hyperdb-api-node-linux-x64-gnu",
+      "skip-github-release": true,
+      "skip-github-pull-request": false,
+      "changelog-path": false
+    },
+    "hyperdb-api-node/npm/linux-x64-musl": {
+      "release-type": "node",
+      "component": "hyperdb-api-node-linux-x64-musl",
+      "skip-github-release": true,
+      "skip-github-pull-request": false,
+      "changelog-path": false
+    },
+    "hyperdb-api-node/npm/win32-x64-msvc": {
+      "release-type": "node",
+      "component": "hyperdb-api-node-win32-x64-msvc",
+      "skip-github-release": true,
+      "skip-github-pull-request": false,
+      "changelog-path": false
     }
   }
 }
diff --git a/sea-query-hyperdb/CHANGELOG.md b/sea-query-hyperdb/CHANGELOG.md
index de41d9f..36ba181 100644
--- a/sea-query-hyperdb/CHANGELOG.md
+++ b/sea-query-hyperdb/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-05-13
+
 ### Added
 
 - `HyperQueryBuilder` implementing `sea_query::QueryBuilder` for HyperDB SQL dialect