Bump

/bump — Version Bump & Release

Perform a full version bump: sync main, write changelog, refresh top-level docs, bump version, and push.

Read references/release-process.md before executing the steps; it owns the detailed release checklist and recovery notes. Paths in this procedure are repository-relative unless marked as skill-relative.

Steps

1. Sync main

Inspect the branch, status, and diff first. Preserve unrelated work. Include the current task's authorized changes in the release; do not ask the user to resolve your own pending edits. Fetch origin and compare the intended release with origin/main. Fast-forward when possible; use an isolated checkout if unrelated edits prevent a safe update. Resolve routine integration issues within scope and ask only when including or changing unrelated work requires a decision.

2. Determine version bump

Review all commits since the last version tag to decide the bump level per Semantic Versioning:

• patch (x.y.Z): bug fixes, minor improvements, doc updates
• minor (x.Y.0): new features, new modes, new API endpoints, new viewer capabilities
• major (X.0.0): breaking changes to contracts, CLI interface, or manifest format

Read the current version from package.json. Compute the new version. If unsure, ask the user.

3. Write CHANGELOG entry

Read CHANGELOG.md and the git log since the last version bump commit. Write a new version section at the top following the existing format:

## [X.Y.Z] - YYYY-MM-DD

### Added
- ...

### Fixed
- ...

### Improved
- ...

Rules:

• Group changes by category (Added / Fixed / Improved / Changed / Removed)
• Each bullet should be a concise, user-facing description — not a commit message copy
• Bold the feature name, then describe what it does
• Omit categories with no entries
• Do NOT include chore/CI/version-bump commits

4. Refresh top-level docs

Review README.md, README.zh.md, AGENTS.md, and docs/reference/project-guide.md against the current codebase state. Fix any contradictions, outdated info, or missing features. This is a holistic review, not just appending — trim stale content, update tables, fix version numbers.

AGENTS.md is the single source of agent instructions; CLAUDE.md is a one-line @AGENTS.md import — never write content into it.

Specifically check:

• AGENTS.md **Version:** line → update to new version
• AGENTS.md mode-catalog link → resolves to the maintained README catalog; public entries match registered manifests and hidden modes stay out
• docs/reference/project-guide.md tech stack table → matches package.json dependencies
• docs/reference/project-guide.md project structure tree → reflects any new/moved directories
• docs/reference/project-guide.md server API reference → includes any new endpoints
• .claude/rules/*.md → keep current constraints and topic routing concise; place longer evidence in linked references and correct or retire stale guidance
• README.md mode table → matches manifest descriptions
• README.md CLI help section → matches actual CLI output
• README.md feature list / roadmap → reflects current state

Do NOT bloat these files — keep them concise and accurate. Remove outdated entries rather than accumulating.

4b. Update mode changelog for any mode whose skill version moved

If this release bumps any mode's manifest.ts version field, you MUST also update that manifest's changelog map with a matching entry — the launcher's skill-update prompt extracts these bullets to tell the user what changed in the skill they're about to reinstall. Skip this step when no mode skill version changed.

For each touched mode:

• Add a key under changelog matching the new version (e.g. "1.3.0": [ ... ]).
• Each bullet is a one-line user-visible summary, no markdown, no trailing period — they render as · bullet in a small UI surface.
• Keep at most ~6 bullets per version. The full prose lives in the project CHANGELOG.md.
• Don't backfill old versions you didn't ship — only annotate the version you're releasing now (and leave any pre-existing entries untouched).

Also grep for the old literal before bumping, in case a test hardcodes it. Tests under server/__tests__/ and the backends/*/[__tests__]/ lifecycle harnesses sometimes pin webcraftManifest.version, slideManifest.version, etc. with a string equality. Before the commit:

# e.g. webcraft going 1.3.0 → 1.4.0
rg -n '"1\.3\.0"' core server backends modes --glob '*.ts' --glob '*.tsx'

Any test hit needs the new string. A miss here is silent locally but fails CI's Release > Test, Build & Release step on push and forces a follow-up commit.

The desktop auto-updater also surfaces highlights in its "Update Available" / "Update Ready" dialogs, but it parses them straight from the project CHANGELOG.md you wrote in step 3 — so a well-formed - **Bold headline** — description bullet there is enough; no extra wiring needed.

5. Bump version

Update all four files in a single commit:

1. package.json — "version": "X.Y.Z"
2. desktop/package.json — the same version
3. AGENTS.md — **Version:** X.Y.Z
4. CHANGELOG.md — new version section (from step 3)

Plus any doc changes from step 4.

Commit message format:

chore: bump version to X.Y.Z — <brief milestone description>

5b. Pre-push sanity — run the test suite

Before pushing, run typecheck, the full test suite, and the production build:

bun run check:guidance
bun run typecheck
bun run test:all --timeout 60000
bun run build

The 60-second per-test timeout matches release.yml; media-processing tests can legitimately exceed Bun's default five seconds. Day-to-day work runs bun run test; test:all is the superset, and the extra time is the backend lifecycle harness spawning real claude / codex / kimi acp processes. Run it here anyway: a release is exactly when "the backends still boot" is worth the wait. .claude/rules/testing.md owns the suite table, timings, and how to read a backend lifecycle failure.

CI runs the same suite as the gate before tagging + publishing — so a local pass is the cheapest way to avoid burning a CI cycle on a hardcoded-version mismatch or a typing slip that only manifests when something downstream re-imports the manifest. Expected output:

 NNNN pass
 NN skip
 0 fail

A non-zero fail count means stop and fix before pushing. The backend lifecycle suites under backends/*/[__tests__]/ count their (skip) ... binary not available lines toward skip, not fail; those are fine. A fail for a hardcoded version expectation usually points back at step 4b's grep — re-run that grep with the previous version string and patch every hit.