docs: document axi-sdk-js release flow

[kunchenguid]

Intent

Release the axi-sdk-js package so the self-update 'update' built-in (already in source: RESERVED_COMMANDS, runUpdate, cli dispatch, help entries, update.ts, update.test.ts) reaches npm, letting downstream *-axi tools inherit ' update' by bumping the dep.

Key finding while doing the work: the repo publishes axi-sdk-js exclusively via release-please. The release-triggering commit (d6560fc, feat(axi-sdk-js): add built-in self-update command #60) already landed, and release-please ALREADY opened release PR #61 'chore(main): release axi-sdk-js 0.1.8', which bumps package.json + .release-please-manifest.json to 0.1.8 and adds the CHANGELOG entry for the update built-in. Merging PR #61 is what tags the release and triggers the CI 'npm publish --access public --provenance' step.

Deliberate decision (important for reviewing the diff scope): I did NOT hand-bump the version/CHANGELOG/manifest. CONTRIBUTING.md and the 'Guard generated files' CI check forbid hand-editing those files; release-please's PR is the only place they may change, so manually bumping would both conflict with PR #61 and fail CI. The actual publish is a captain action (merge PR #61; npm auth/OIDC is owned by the maintainer), so the task is to get to one-step-from-published and flag it - which is already true via PR #61.

I verified the release path locally before reporting: pnpm install --frozen-lockfile, build, 115 tests (incl. 53 update tests), lint, and format:check all green; the built dist carries update.js + RESERVED_COMMANDS + runUpdate; and the currently-published 0.1.7 confirmed to lack update.

The only committable change in this branch is therefore documentation: a new 'Releasing axi-sdk-js' maintainer runbook section in AGENTS.md (root; CLAUDE.md is a symlink to it). It captures the previously-undocumented publish flow - conventional commits drive release-please, merging the generated release PR runs npm publish --provenance, and how to verify with npm view / npm pack. This is durable project knowledge that was missing (CONTRIBUTING only covered the contributor-side conventional-commit rule, not how a publish happens or how to verify it). Plain ASCII dashes used intentionally per repo author's style preference (no em dashes).

What Changed

• Documented the axi-sdk-js release-please publish flow in AGENTS.md, including the generated release PR, provenance publish step, and npm verification commands.
• Clarified the current pre-1.0 release behavior: feat: and fix: commits both produce patch bumps, while generated changelog and manifest updates stay in release-please PRs.
• Added branch release validation notes capturing the checked publish path and related verification context.

Risk Assessment

✅ Low: The HEAD diff is limited to AGENTS.md release-process documentation and its claims match the checked-in release-please config and GitHub workflows, so there is little merge risk.

Testing

Checked the target diff scope, ran the SDK test suite and build, smoke-tested the built CLI update surfaces, verified npm latest and package contents, verified PR #61, the GitHub release, and the successful release-please workflow run, then removed the transient packages/axi-sdk-js/dist build output. An exploratory gh-axi pr list --fields ... command used unsupported fields and was replaced by the direct PR, release, and run checks; it was not a product failure.

• Evidence: Release validation evidence

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed (2) ✅

• ⚠️ AGENTS.md:65 - This says feat: maps to a minor-equivalent bump, but the repo sets bump-patch-for-minor-pre-major: true, which release-please documents as making feat commits bump patch instead of minor for versions below 1.0. Since axi-sdk-js is currently 0.1.7, a feat: release should be documented as 0.1.8-style patch, not minor. Source: https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md#configfile

🔧 Fix: Clarify release-please pre-1.0 patch bumps
1 warning still open:

• ⚠️ AGENTS.md:68 - This says the Guard generated files check fails any PR that hand-edits all files listed above, including packages/axi-sdk-js/package.json, but the workflow only checks packages/axi-sdk-js/CHANGELOG.md and .release-please-manifest.json. Scope this sentence to the guarded files, or add a dedicated guard for package version bumps, so agents do not assume package.json version edits are CI-blocked when they are not.

🔧 Fix: Clarify generated file guard scope
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• git diff --name-status d6560fca9e6dd8fdd9672bb8fa49e740ca86658f..7f62da038241362e320d31dfe99433a8acda1172
• pnpm --dir packages/axi-sdk-js test
• pnpm --dir packages/axi-sdk-js run build
• Built SDK smoke check with runAxiCli({ argv: ["--help"] })
• Built SDK smoke check with runAxiCli({ argv: ["update", "--help"] })
• Built SDK smoke check with runAxiCli({ argv: ["update", "--check"], packageName: "axi-sdk-js", version: "0.1.7" })
• npm view axi-sdk-js version dist-tags.latest
• npm pack --dry-run --json axi-sdk-js@0.1.8
• gh-axi pr view 61 --full
• gh-axi release view axi-sdk-js-v0.1.8 --full
• gh-axi run list --workflow axi-sdk-js-release-please.yml --branch main --limit 5

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.