onde-cli 0.4.2__tar.gz → 0.4.3__tar.gz

onde_cli-0.4.3/.agents/skills/release/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: release
+description: Use whenever cutting, preparing, tagging, or publishing an onde-cli release — version bumps, release branch, merges, tagging, pushing to trigger the publish pipeline, and verifying it landed. Also use when a release went wrong (wrong tag target, failed crates.io verify, development left behind main, unsigned release commits) and the repo state needs repair. Trigger even if the user only says "release vX.Y.Z", "bump the version", "tag a release", or "publish the new version".
+user-invocable: true
+---
+
+# Release skill
+
+End-to-end release procedure for `onde-cli`. Complements the git skill (merge rules)
+and the distribution skill (channel details) — this skill is the concrete runbook.
+
+## Decide the version
+
+- Look at `git tag -l 'v*' --sort=-v:refname | head -1` for the latest release.
+- Look at the commits since (`git log v<latest>..development --oneline`).
+  Fixes and chores only → patch bump. New user-facing features → minor bump.
+- Check for an abandoned `release/vX.Y.Z` branch — its version is usually the
+  intended next one. If it exists, inspect it (`git log development..release/...`)
+  before deciding to reuse or delete it; do not blindly `branch -D` without looking,
+  and never reuse a branch whose commits were made unsigned or by the wrong identity.
+
+## Version bump surfaces
+
+These files pin the crate version and must all move together:
+
+- `Cargo.toml` — `version = "X.Y.Z"` in `[package]`
+- `pub/onde_cli/pubspec.yaml` — `version: X.Y.Z`
+- `server.json` — three occurrences: top-level `version`, and the npm and NuGet
+  `packages[].version` entries (search for the old version string to catch all)
+
+`docs/mcp-registry.md` and `.github/workflows/release-mcp-registry.yml` mention
+past versions only as historical examples — do not bump those.
+
+The npm wrapper manifests are NOT bump targets: the committed `package.json` files
+are rewritten at release time by `npm/scripts/render-*.cjs` from the tag.
+
+After editing, run `cargo check --locked` (or let the build update `Cargo.lock`)
+so the lockfile carries the new version, and commit it in the same bump commit.
+
+## Sequence
+
+Follow the git skill's branch flow — `release/vX.Y.Z → development → main`,
+`--no-ff` at every hop, tag on the final `main` merge commit. Concretely:
+
+```bash
+git checkout development
+git pull <remote> development          # start from the pushed tip
+git checkout -b release/vX.Y.Z
+# ... edit the bump surfaces ...
+git commit -am "Prepare vX.Y.Z"        # signed, correct identity (see below)
+git checkout development
+git merge --no-ff release/vX.Y.Z -m "Merge release prep for vX.Y.Z"
+git checkout main
+git pull <remote> main
+git merge --no-ff development -m "Merge development for vX.Y.Z"
+git tag vX.Y.Z
+git push <remote> development main vX.Y.Z
+git branch -d release/vX.Y.Z           # only after the merge lands
+```
+
+The remote here is the one whose URL is the sigit.si or GitHub org repo —
+check `git remote -v`; this repo is commonly cloned with per-account remotes
+(`gh-setoelkahfi`, `gh-paydii`, `gh-keypair34`) rather than `origin`.
+
+### What a good result looks like
+
+- The tag sits on the step-3 merge commit on `main` (`git log --graph main`
+  shows a merge commit directly above the previous release).
+- `git log development..main` and `git log main..development` are both empty
+  after the merges — the two branches carry identical trees.
+- Never tag a release-branch tip or a bare bump commit on `main`; if the work
+  somehow already landed on `main` linearly, follow the git skill's fallback
+  (normal commit, tag it) rather than rewriting history.
+
+### Post-push back-merge check
+
+If anything reached `main` without passing through `development` first (hotfix,
+manual push, a fast-forwarded release), bring it back immediately:
+
+```bash
+git checkout development
+git merge --no-ff main -m "Merge main for vX.Y.Z"
+git push <remote> development
+```
+
+A release is not done until the two branches contain the same tree.
+
+## Commits and signatures — read the git-commit-signing skill first
+
+Release commits must be GPG-signed by the maintainer identity that GitHub can
+verify (this repo: `Seto Elkahfi <1797197+setoelkahfi@users.noreply.github.com>`,
+EDDSA key `2B76DF0F04014E36`). The `gh` CLI's active account is independent of
+git config — set both, and verify before pushing:
+
+```bash
+git log -1 --format='%an <%ae> sig:%G? %GK'    # want sig:G and the right key
+gh api repos/<owner>/<repo>/commits/<sha> --jq .commit.verification.verified
+```
+
+Every `git commit` and `git merge` in this flow creates a commit — configure
+signing so merges are signed too, or amend unsigned ones before pushing
+(`git commit --amend --no-edit -S`, only on unpushed commits).
+
+Commit trailer: end release-related commit messages with
+
+```
+Co-Authored-By: siGit Code v1.6.7-acp <noreply@sigit.si>
+```
+
+## The tag push is the release
+
+Pushing `vX.Y.Z` triggers `release-crates.yml`, which verifies the tag against
+`Cargo.toml` and `pubspec.yaml`, publishes the crate, then dispatches the
+wrapper workflows (GitHub Releases, npm, NuGet, PyPI, then Homebrew and pub.dev
+after the GitHub Release assets exist). There is no separate "publish" step.
+
+Watch it land:
+
+```bash
+gh run list --branch vX.Y.Z
+gh run watch <run-id> --exit-status
+```
+
+`CI` also runs on the tag push; both should be green. If `release-crates` fails,
+no wrapper publishes — fix the cause, move the tag only if it has not published
+anything yet (crates.io versions are immutable; a failed verify is safe to retry,
+a published crate is not).
+
+## Verify
+
+After the pipeline finishes, spot-check the fan-out (all idempotent, safe to re-check):
+
+- crates.io: `cargo search onde-cli --limit 1`
+- GitHub Release: `gh release view vX.Y.Z`
+- npm: `npm view onde-cli version`
+- PyPI: `https://pypi.org/pypi/onde-cli/json` → `info.version`
+- NuGet: flat container index for `onde-cli`
+- Homebrew/pub.dev trail the GitHub Release; they may take a few extra minutes
+
+## Failure modes seen before
+
+- Fast-forwarding `main` to the bump commit and tagging it — leaves no merge
+  commit, and leaves `development` behind. Back-merge `main` into `development`
+  right away and prefer merge commits next time.
+- Deleting a leftover `release/` branch that contained unsigned bump commits and
+  redoing the bump fresh — fine, but check it first.
+- Forgetting `Cargo.lock` in the bump commit.
+- Pushing with the wrong `gh` account active — the push works, but PR/issue
+  actions afterwards get attributed to the wrong identity.

onde_cli-0.4.3/.agents/skills/release/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "release",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Cut release v0.4.3 for onde-cli. Bump all version pins, follow the repo's release branch flow, tag, and push.",
+      "expected_output": "Agent bumps Cargo.toml, pubspec.yaml, server.json (3 spots), commits signed with Co-Authored-By trailer, creates release/v0.4.3 from development, merges --no-ff into development then main, tags the main merge commit, pushes development+main+tag, and watches the release pipeline.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "We fast-forwarded main to the version bump commit by mistake and tagged it. development is now behind main. Fix the repo state without rewriting pushed history.",
+      "expected_output": "Agent recognizes the git skill's rule (tag belongs on a merge commit; development must carry the release state) and back-merges main into development with --no-ff instead of rewriting main or deleting the pushed tag.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "The v0.4.2 tag push failed the crates.io verify step because pubspec.yaml still said 0.4.1. Nothing was published. Walk me through fixing it and re-releasing.",
+      "expected_output": "Agent fixes the pubspec version on a new release branch or hotfix, re-runs the release flow, deletes and recreates the tag only if crates.io never published, and explains why crates.io versions are immutable so a published 0.4.2 would require 0.4.3 instead.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Update the README install instructions for the npm wrapper and fix the NuGet README badge that points at the wrong package id.",
+      "expected_output": "Should NOT deeply engage the release skill beyond reading it; this is distribution/README work. Agent edits npm/onde-cli/README.md and nuget/onde-cli/README.md without cutting a release, bumping versions, or tagging.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Merge the feature/lora-scheduler branch into development.",
+      "expected_output": "Should NOT trigger the release skill; this is a normal feature merge governed by the git skill (--no-ff into development, no tag).",
+      "files": []
+    }
+  ]
+}

onde_cli-0.4.3/.cargo/config.toml

@@ -0,0 +1,7 @@
+# Link the MSVC C runtime statically on Windows. Without this the binary
+# imports VCRUNTIME140.dll and the UCRT api-ms-win-crt-*.dll set, and on a
+# machine without the Visual C++ Redistributable it dies at load time with
+# STATUS_DLL_NOT_FOUND (0xC0000135) before main runs. winget ships onde as a
+# portable exe, so there is no installer to bring the runtime along.
+[target.'cfg(all(windows, target_env = "msvc"))']
+rustflags = ["-C", "target-feature=+crt-static"]

onde_cli-0.4.3/.claude/skills/distribution/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: distribution
+description: Use when adding, fixing, or documenting package distribution for Onde CLI. Covers wrapper-package design across npm, PyPI, NuGet, pub.dev, GitHub Releases, and Homebrew, plus version alignment, artifact staging, README surfaces, and smoke-test strategy.
+---
+
+# Onde CLI distribution
+
+This skill captures how `onde-cli` is distributed today and what to watch when adding new channels.
+
+## Distribution model
+
+`onde-cli` is a native Rust CLI first.
+
+Everything else is packaging.
+
+That means:
+
+- build the Rust binary once per target
+- publish thin wrappers that install or launch that binary
+- keep channel-specific logic small and predictable
+
+This design keeps behavior consistent across ecosystems and avoids re-implementing CLI logic in each language.
+
+## Channel map
+
+### Native source of truth
+
+- Rust crate: `onde-cli`
+- binary name: `onde`
+- root manifest: `Cargo.toml`
+
+### Wrapper channels
+
+- npm: JavaScript launcher + optional platform packages
+- PyPI: `maturin` binary wheels
+- NuGet: .NET global tool launcher
+- pub.dev: Dart launcher package
+
+### Native artifact channels
+
+- crates.io
+- GitHub Releases
+- Homebrew
+
+## Wrapper design patterns
+
+### npm
+
+Use a very small Node launcher that:
+
+- detects OS and architecture
+- resolves the installed platform package
+- spawns the binary with inherited stdio
+
+Good fit for users who already live in npm tooling.
+
+Important release detail:
+
+- the committed `npm/onde-cli/package.json` is a working file, not the publish-time source of truth
+- the release workflow rewrites the base package manifest with `npm/scripts/render-main-package.cjs`
+- platform package manifests are generated on the fly with `npm/scripts/render-platform-package.cjs`
+- the actual npm version comes from the release tag via `RELEASE_VERSION`, not from manually editing the committed npm manifest before publish
+
+### PyPI
+
+Use `maturin` with `bindings = "bin"` so the native executable is what gets installed.
+
+Good fit for Python users who want the CLI but not a Python reimplementation.
+
+### NuGet
+
+Use a `.NET global tool` wrapper.
+
+Important details:
+
+- keep the package as a launcher, not a managed rewrite
+- place native binaries under the tool payload
+- resolve the runtime identifier at startup
+- set Unix execute bits before launch
+
+Good fit for .NET developers and CI environments that already use `dotnet tool install`.
+
+### pub.dev
+
+Use a Dart package with a command entrypoint and a library that launches the native binary.
+
+Important details:
+
+- executable command should stay `onde`
+- keep the runtime-id mapping explicit
+- download the correct binary from GitHub Releases on first run
+- cache downloads under `~/.onde/cli`
+- keep the wrapper thin, the Rust binary is still the product
+- publish the pub.dev package only after the matching GitHub Release exists
+
+Good fit for Dart and Flutter developers who want the same CLI through familiar tooling.
+
+## Runtime identifier mapping
+
+Keep these names aligned anywhere wrappers or workflows refer to native assets:
+
+- `darwin-x64`
+- `darwin-arm64`
+- `linux-x64`
+- `linux-arm64`
+- `windows-x64`
+- `windows-arm64`
+
+If a wrapper uses one naming scheme and a workflow uploads another, the installed package will pass packaging but fail at runtime.
+
+## Release workflow principles
+
+### One tag trigger, then fan out
+
+`release-crates.yml` is the only workflow that reacts to a tag push. It verifies the
+tag against `Cargo.toml` and `pubspec.yaml`, publishes the crate, then dispatches
+`release-github`, `release-npm`, `release-nuget`, and `release-pypi` with the same tag.
+`release-github` in turn dispatches `release-homebrew` and `release-pub` after the
+release assets exist.
+
+```
+tag push
+  └─ release-crates (verify -> publish -> dispatch)
+       ├─ release-github ─┬─ release-homebrew
+       │                  └─ release-pub
+       ├─ release-npm
+       ├─ release-nuget
+       └─ release-pypi
+```
+
+This mirrors `smbcloud-cli`. Two properties matter:
+
+- crates.io is the gate. If verify or publish fails, no wrapper publishes a version
+  that has no crate behind it.
+- every dispatch passes `ref: <tag>`, not `ref: main`, so downstream workflows run the
+  workflow definition from the release state instead of whatever `main` happens to be.
+
+Do not add `push: tags:` to a wrapper workflow. Several workflows racing on the same tag
+is what lets the pub.dev launcher publish before its GitHub Release assets exist.
+
+### Build first, package second
+
+Always build native binaries in a target matrix first.
+
+Then let the wrapper channel jobs package those artifacts.
+
+This avoids rebuilding the product multiple times and makes failures easier to reason about.
+
+### Idempotency
+
+Every publish workflow should check whether the target version already exists before publishing.
+
+Examples:
+
+- npm: `npm view`
+- PyPI: package JSON endpoint
+- NuGet: flat container index
+- pub.dev: package API endpoint
+
+### Smoke tests should match the product shape
+
+Because `onde` is TUI-first, avoid smoke tests that assume a traditional CLI help flow unless you know that code path is stable and non-interactive.
+
+Safer checks:
+
+- install succeeds
+- bundled native binary exists where expected
+- package manager validation passes
+
+## pub.dev-specific notes
+
+pub.dev behaves differently from npm and NuGet in one important way:
+
+- large bundled binaries quickly hit package size limits
+
+That makes the safest design a thin Dart launcher that downloads the right native binary from GitHub Releases at runtime instead of shipping every platform binary inside the package.
+
+Practical consequences:
+
+- `pub/onde_cli/native/` should stay out of the published package
+- do not set `publish_to: https://pub.dev` in `pubspec.yaml`; omit `publish_to` for normal pub.dev publishing
+- use package-level ignore rules so local native staging does not leak into publish input
+- keep release asset names aligned with the GitHub Release workflow, because the launcher depends on them
+- treat `~/.onde/cli` as the local cache root for downloaded binaries
+- do not let the pub.dev workflow race ahead of GitHub Releases; dispatch it after `release-github.yml` has created the assets
+
+Run these during verification:
+
+- `dart pub get --directory pub/onde_cli`
+- `dart analyze pub/onde_cli`
+- `dart pub publish --dry-run --directory pub/onde_cli`
+
+## NuGet-specific notes
+
+NuGet packaging is sensitive to path layout.
+
+The safest pattern is:
+
+- copy native files into the publish output
+- let the .NET tool pack process carry them into the final package
+
+Avoid custom `PackagePath` patterns that can duplicate path segments or create nested native folders by accident.
+
+If the tool installs but cannot find the native binary, inspect the `.nupkg` contents before debugging the launcher.
+
+## README surfaces
+
+Every user-facing channel should document the same product with channel-specific installation instructions.
+
+Main files:
+
+- `README.md`
+- `npm/onde-cli/README.md`
+- `pypi/README.md`
+- `nuget/onde-cli/README.md`
+- `pub/onde_cli/README.md`
+
+Keep these aligned on:
+
+- product description
+- supported platforms
+- install method
+- license and copyright
+- relevant supporting links like the forward-pass explainer
+
+Do not let one channel sound like a different product.
+
+## Version alignment
+
+When cutting a release, update every user-facing distribution version that should move with the CLI.
+
+At minimum, check:
+
+- Rust crate version
+- npm release templates and workflow assumptions
+- npm lockfile version if committed
+- PyPI release version source
+- NuGet package version at pack time
+- pub.dev package version in `pubspec.yaml`
+- workflow example tags and docs that mention concrete versions
+
+## Common failure modes
+
+- wrapper version does not match the Rust release version
+- manually bumping the committed npm manifest and assuming that is what npm publishes
+- staged native binaries land in the wrong directory before packaging
+- package builds successfully but installs without the native binary
+- pub.dev launcher points at the wrong GitHub Release asset name or runtime id
+- pub.dev workflow publishes before the matching GitHub Release assets exist
+- pub.dev package still includes bundled binaries and blows the upload size limit
+- smoke test invokes a TUI-first binary in a way that does not make sense for CI
+- README badges and install commands drift out of sync with real package names
+
+## Rule of thumb
+
+If the native binary works and the wrappers are boring, distribution stays manageable.
+
+If a wrapper starts acting like its own product, complexity grows fast.
+
+Keep it thin.
+Keep it aligned.
+Keep the Rust binary as the source of truth.

onde_cli-0.4.3/.claude/skills/git/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: git
+description: Git workflow rules for this repository.
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion
+user-invocable: true
+---
+
+# Git skill
+
+## Core rule
+
+- Use `--no-ff`. Important.
+
+## What this means in practice
+
+- Do not fast-forward merge feature branches, release branches, or hotfix branches.
+- Prefer explicit merge commits so the branch history stays visible.
+- Release prep goes through `development` on its way to `main`, with `--no-ff` at every hop.
+- Tag the merge commit that contains the final release state.
+
+## Branch flow
+
+Feature branches merge into `development`. Releases go:
+
+```
+release/vX.Y.Z -> development -> main
+```
+
+Never merge a release branch straight into `main` — `development` has to carry the
+release state too, or the next feature branch starts from a base that is missing it.
+
+## Release guidance
+
+```bash
+# 1. cut the release branch from development, commit the version bumps
+git checkout development
+git checkout -b release/vX.Y.Z
+git commit -am "Prepare vX.Y.Z"
+
+# 2. release branch -> development
+git checkout development
+git merge --no-ff release/vX.Y.Z -m "Merge release prep for vX.Y.Z"
+
+# 3. development -> main
+git checkout main
+git merge --no-ff development -m "Merge development for vX.Y.Z"
+
+# 4. tag the main merge commit, then push
+git tag vX.Y.Z
+git push origin development
+git push origin main
+git push origin vX.Y.Z
+```
+
+The tag belongs on the step-3 merge commit on `main`, not on the release branch and not
+on `development`. Pushing the tag is what triggers the wrapper publish workflows, which
+read the version from the tag.
+
+If the work is already on `main`, make a normal commit and tag that commit. Do not rewrite history just to avoid a merge commit.
+
+## Avoid
+
+- `git merge --ff`
+- `git pull --ff-only` as a default recommendation for this repo's merge policy
+- Tagging a branch tip that has not been merged into `main` when the intended release source of truth is `main`
+- Merging a release branch directly into `main`, skipping `development`
+
+## Why
+
+The repo wants explicit history. Release commits should be easy to find, easy to audit, and clearly connected to the branch that introduced them.

onde_cli-0.4.3/.claude/skills/release/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: release
+description: Use whenever cutting, preparing, tagging, or publishing an onde-cli release — version bumps, release branch, merges, tagging, pushing to trigger the publish pipeline, and verifying it landed. Also use when a release went wrong (wrong tag target, failed crates.io verify, development left behind main, unsigned release commits) and the repo state needs repair. Trigger even if the user only says "release vX.Y.Z", "bump the version", "tag a release", or "publish the new version".
+user-invocable: true
+---
+
+# Release skill
+
+End-to-end release procedure for `onde-cli`. Complements the git skill (merge rules)
+and the distribution skill (channel details) — this skill is the concrete runbook.
+
+## Decide the version
+
+- Look at `git tag -l 'v*' --sort=-v:refname | head -1` for the latest release.
+- Look at the commits since (`git log v<latest>..development --oneline`).
+  Fixes and chores only → patch bump. New user-facing features → minor bump.
+- Check for an abandoned `release/vX.Y.Z` branch — its version is usually the
+  intended next one. If it exists, inspect it (`git log development..release/...`)
+  before deciding to reuse or delete it; do not blindly `branch -D` without looking,
+  and never reuse a branch whose commits were made unsigned or by the wrong identity.
+
+## Version bump surfaces
+
+These files pin the crate version and must all move together:
+
+- `Cargo.toml` — `version = "X.Y.Z"` in `[package]`
+- `pub/onde_cli/pubspec.yaml` — `version: X.Y.Z`
+- `server.json` — three occurrences: top-level `version`, and the npm and NuGet
+  `packages[].version` entries (search for the old version string to catch all)
+
+`docs/mcp-registry.md` and `.github/workflows/release-mcp-registry.yml` mention
+past versions only as historical examples — do not bump those.
+
+The npm wrapper manifests are NOT bump targets: the committed `package.json` files
+are rewritten at release time by `npm/scripts/render-*.cjs` from the tag.
+
+After editing, run `cargo check --locked` (or let the build update `Cargo.lock`)
+so the lockfile carries the new version, and commit it in the same bump commit.
+
+## Sequence
+
+Follow the git skill's branch flow — `release/vX.Y.Z → development → main`,
+`--no-ff` at every hop, tag on the final `main` merge commit. Concretely:
+
+```bash
+git checkout development
+git pull <remote> development          # start from the pushed tip
+git checkout -b release/vX.Y.Z
+# ... edit the bump surfaces ...
+git commit -am "Prepare vX.Y.Z"        # signed, correct identity (see below)
+git checkout development
+git merge --no-ff release/vX.Y.Z -m "Merge release prep for vX.Y.Z"
+git checkout main
+git pull <remote> main
+git merge --no-ff development -m "Merge development for vX.Y.Z"
+git tag vX.Y.Z
+git push <remote> development main vX.Y.Z
+git branch -d release/vX.Y.Z           # only after the merge lands
+```
+
+The remote here is the one whose URL is the sigit.si or GitHub org repo —
+check `git remote -v`; this repo is commonly cloned with per-account remotes
+(`gh-setoelkahfi`, `gh-paydii`, `gh-keypair34`) rather than `origin`.
+
+### What a good result looks like
+
+- The tag sits on the step-3 merge commit on `main` (`git log --graph main`
+  shows a merge commit directly above the previous release).
+- `git log development..main` and `git log main..development` are both empty
+  after the merges — the two branches carry identical trees.
+- Never tag a release-branch tip or a bare bump commit on `main`; if the work
+  somehow already landed on `main` linearly, follow the git skill's fallback
+  (normal commit, tag it) rather than rewriting history.
+
+### Post-push back-merge check
+
+If anything reached `main` without passing through `development` first (hotfix,
+manual push, a fast-forwarded release), bring it back immediately:
+
+```bash
+git checkout development
+git merge --no-ff main -m "Merge main for vX.Y.Z"
+git push <remote> development
+```
+
+A release is not done until the two branches contain the same tree.
+
+## Commits and signatures — read the git-commit-signing skill first
+
+Release commits must be GPG-signed by the maintainer identity that GitHub can
+verify (this repo: `Seto Elkahfi <1797197+setoelkahfi@users.noreply.github.com>`,
+EDDSA key `2B76DF0F04014E36`). The `gh` CLI's active account is independent of
+git config — set both, and verify before pushing:
+
+```bash
+git log -1 --format='%an <%ae> sig:%G? %GK'    # want sig:G and the right key
+gh api repos/<owner>/<repo>/commits/<sha> --jq .commit.verification.verified
+```
+
+Every `git commit` and `git merge` in this flow creates a commit — configure
+signing so merges are signed too, or amend unsigned ones before pushing
+(`git commit --amend --no-edit -S`, only on unpushed commits).
+
+Commit trailer: end release-related commit messages with
+
+```
+Co-Authored-By: siGit Code v1.6.7-acp <noreply@sigit.si>
+```
+
+## The tag push is the release
+
+Pushing `vX.Y.Z` triggers `release-crates.yml`, which verifies the tag against
+`Cargo.toml` and `pubspec.yaml`, publishes the crate, then dispatches the
+wrapper workflows (GitHub Releases, npm, NuGet, PyPI, then Homebrew and pub.dev
+after the GitHub Release assets exist). There is no separate "publish" step.
+
+Watch it land:
+
+```bash
+gh run list --branch vX.Y.Z
+gh run watch <run-id> --exit-status
+```
+
+`CI` also runs on the tag push; both should be green. If `release-crates` fails,
+no wrapper publishes — fix the cause, move the tag only if it has not published
+anything yet (crates.io versions are immutable; a failed verify is safe to retry,
+a published crate is not).
+
+## Verify
+
+After the pipeline finishes, spot-check the fan-out (all idempotent, safe to re-check):
+
+- crates.io: `cargo search onde-cli --limit 1`
+- GitHub Release: `gh release view vX.Y.Z`
+- npm: `npm view onde-cli version`
+- PyPI: `https://pypi.org/pypi/onde-cli/json` → `info.version`
+- NuGet: flat container index for `onde-cli`
+- Homebrew/pub.dev trail the GitHub Release; they may take a few extra minutes
+
+## Failure modes seen before
+
+- Fast-forwarding `main` to the bump commit and tagging it — leaves no merge
+  commit, and leaves `development` behind. Back-merge `main` into `development`
+  right away and prefer merge commits next time.
+- Deleting a leftover `release/` branch that contained unsigned bump commits and
+  redoing the bump fresh — fine, but check it first.
+- Forgetting `Cargo.lock` in the bump commit.
+- Pushing with the wrong `gh` account active — the push works, but PR/issue
+  actions afterwards get attributed to the wrong identity.