Release a New Version

Use this for Nightly builds, stable desktop releases, and requested mobile store distribution. A stable desktop release must come from main, after the changelog and required CLI, MCP, API, agent-package, and documentation updates are accurate, validated, and merged. Desktop and watchOS share the marketing version in release-version.json. iOS and Android use apps/mobile/release-version.json. Platform build numbers and publication schedules remain independent.

Core Rule

Do not trigger a stable release from an unmerged branch. Complete the release surface review and changelog below, merge the required changes to main, then freeze the candidate and release that merged commit through its Nightly tag.

Nightly and Stable Operations

• Existing users and the main download remain on stable. Nightly is an explicit separate-app install, with its own updater feed and CLI command. It opens the same local database as stable; settings, store, and sign-in stay per app.
• The team uses Nightly for daily meetings. Volunteers can join through the announcement in the next stable changelog and product-update newsletter.
• .github/workflows/desktop_nightly.yaml runs daily at 15:00 UTC (midnight KST) and can be dispatched manually from main. It runs desktop JS/i18n and native CI, including source CloudSync rebuilds, before building and publishing all desktop platforms through desktop_cd.yaml with channel=nightly.
• Nightly versions are <shared-version>-nightly.<n>, where <n> counts up from 1 for each base version (1.4.24-nightly.1, 1.4.24-nightly.2, ...) and resets when release-version.json moves to the next stable. Each build snapshots packages/changelog/nightly.md into the app and a GitHub prerelease tagged desktop_nightly_v<nightly-version>. Maintain that file as curated, user-facing changes since the previous stable release; do not generate a raw commit dump. Nightly notes never belong in the website's stable changelog.
• Target weekly ordinary stable releases. Select a published Nightly commit, pin the team's app to it for 2–3 working days, and record real meeting results. Disable automatic updates while testing that candidate. CI or elapsed time alone is not evidence of use. Confirm recording/transcription, saved notes after restart, sync, and stable-to-candidate upgrades on shipped platforms.
• One release owner records the candidate, Nightly release/run, testing results, unresolved issues, and go/no-go decision in the release task. A serious regression postpones publication. Candidate fixes require renewed affected testing; newer main features wait for the next candidate.
• Nightly and stable are separate signed packages. Build stable from the tested commit and verify its install/upgrade behavior before publication; do not present the Nightly binary as byte-identical to the stable artifact.
• For an urgent stable hotfix, start from the latest stable tag, carry the minimal fix into main, and verify the patch. Record the owner's explicit exception to the usual Nightly testing period; do not bundle unrelated work. The candidate must still be merged into main before publication. If main has advanced, dispatch desktop_cd.yaml with channel=nightly on the merged hotfix branch, supplying its exact SHA, then use the resulting Nightly tag for stable verification and publication. This preserves the minimal patch.
• Shared APIs and synced data must stay compatible with existing stable clients. Nightly and stable write the same local database, and the apps refuse to run at the same time. A -- breaking migration published in Nightly locks stable users out of their notes until stable ships it: keep schema changes additive (see the root AGENTS.md), and land a breaking migration only in the candidate that becomes the next stable release, so the lockout ends when that release publishes.

Publish and verify Nightly

gh workflow run desktop_nightly.yaml --ref main
gh run list --workflow desktop_nightly.yaml --limit 5

Verify the exact SHA and all called jobs, not only the aggregate status. A failed run needs a fresh dispatch. Confirm the GitHub prerelease/tag, signed installers, CrabNebula nightly downloads, and every platform's Nightly update response. Install the published build and exercise Nightly-to-Nightly updating, auth, sharing links, and the embedded CLI. Confirm stable remains on the stable feed. The first published Nightly needs this verification before announcing it.

Do not send the newsletter or announce Nightly as available until the Nightly builds, update feed, and https://anarlog.so/download/nightly/ are live and verified. Use the newsletter skill for the announcement. Nightly publication does not publish a website changelog or submit to stores.

Scope Boundary

Establish the exact desktop version and requested mobile destination before dispatching. A desktop release includes its existing Microsoft Store workflow; it does not imply mobile submission. When mobile is requested, distinguish TestFlight and Google Play internal testing from public App Store review and Google Play production rollout. Honor authorization already given in the task; do not ask again for an approved destination.

App Store here means the iOS app. The repository deliberately has no Mac App Store release lane; do not recreate one as part of a desktop or mobile release.

Every desktop release includes the CLI, local and hosted MCP, API, agent-package, and documentation freshness review below, and deploys any hosted service that has unpublished changes this release needs. The CLI and local MCP ship inside the desktop package; hosted services, plugin catalogs, and docs have separate publication paths. Keep their versions independent and record their source SHAs. An unchanged surface needs evidence that its published version still covers the candidate; it does not need an artificial version bump or redeployment.

Honor existing authorization for service and documentation publication. If a required external action is not authorized, finish preparing and validating the concrete change before asking for that action. When a hosted service has unpublished changes this release needs, dispatch its CD workflow during the release; do not leave the deploy as a follow-up. Do not call the complete release finished while a required surface is stale or awaiting publication.

Release and QA are separate, explicitly requested workflows. Do not read or run qa-critical-ux or qa-cli-mcp-api solely because the user asked for a release. A release does not require a report from either optional QA skill. The Nightly candidate testing and final stable package verification above are part of this release operation; report their actual evidence separately. The contract, packaging, and publication checks in this skill are required release verification; they do not invoke either optional QA workflow.

If the user explicitly asks for both release and QA, follow the requested order and report the outcomes separately. Do not infer that a QA result approves or blocks the release.

Release Workflow Requirements

The desktop path covers macOS, Windows, and Linux. Requested mobile distribution follows the separate native-build and store steps below. The patched CloudSync vendor bundle is rebuilt from source and cancellation-tested on every desktop lane: rebuild-macos.sh for Apple Silicon and Intel, rebuild-windows.sh under UCRT64 in windows_ci, and rebuild-linux.sh in linux_ci for x86_64 and aarch64. Each lane then runs cargo test -p cloudsync and cargo test -p db-core cloudsync:: against that freshly built library, covering the stalled-network, logout, configuration cleanup/init, worker-drain, and immediate-local-write cancellation gates.

The rebuild steps run on workflow_dispatch or the Nightly caller with rebuild_cloudsync=true, so a routine pull-request run does not prove them. Dispatch desktop_ci.yaml against the candidate SHA and confirm the cloudsync-windows-* and cloudsync-linux-* artifacts before treating a desktop lane as approved. Do not treat macOS artifacts or Rust-only tests as cross-platform approval. Check the mobile coverage separately; its current Android job does not provide the iOS cancellation-test coverage.

Preflight

1. Inspect the workflow before assuming release behavior:

cat .github/workflows/desktop_cd.yaml
cat .github/workflows/desktop_ci.yaml
cat .github/workflows/desktop_publish.yaml
cat .github/workflows/desktop_store_publish.yaml
cat .github/workflows/cli_ci.yaml
cat .github/workflows/api_ci.yaml
cat .github/workflows/api_cd.yaml
cat .github/workflows/stripe_cd.yaml
cat .github/workflows/db_cd.yaml
cat .github/workflows/web_ci.yaml
cat .github/workflows/web_cd.yaml

2. Validate the explicit stable version requested by the user:

VERSION=<version>
[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
node scripts/release-version.mjs "$VERSION"
node scripts/release-version.mjs --check "$VERSION"
test -f "packages/changelog/content/$VERSION.md"

Stable desktop releases never infer a version. The workflow requires the exact stable semantic version to match release-version.json and a changelog file. The version command also regenerates apps/watch/apple/Version.xcconfig; commit both desktop version files with the release preparation changes. Expo reads apps/mobile/release-version.json. A desktop bump does not change or authorize mobile publication.

3. Identify the latest stable desktop tag and the commits that will ship:

gh release list --limit 20
gh api repos/fastrepl/anarlog/compare/<latest-desktop-tag>...main
git log --oneline <latest-desktop-tag>..<candidate-sha>

Verify the latest published, non-prerelease desktop_v<semver> tag through GitHub. GitHub's compare file list can be truncated; use local history and diffs for the complete changelog review. Use read-only git commands for inspection. Use the but skill for local version control, and GitHub tools for PR metadata and merges. Do not force-fetch tags or force-push to prepare a release.

Release Surface Review

Complete this before freezing the candidate, including when only preparing a release. Review the full product diff since the last stable desktop tag, not just CLI/API paths. Also compare each independently published surface with its last published source SHA so previously unshipped changes are not missed.

For each user-facing change, record the affected surfaces, required updates, validation, and publication status in the release task or PR. Use unchanged or not applicable only with a concrete reason. Check that supported agent workflows expose the new or changed product behavior. Fix drift before release; an intentional capability difference must be documented. A missing capability that needs a product decision requires an explicit deferral, not a silent skip.

Surface	Review against the candidate
CLI and shared agent access	apps/cli, crates/agent-access, and CLI contract snapshots: commands, flags, JSON fields/errors, pagination, exports, local/cloud selection, and supported data formats. Trace changed product behavior through these implementations; rebuilding alone does not establish coverage.
Local and hosted MCP	apps/cli/src/mcp.rs, crates/api-cloud/src/mcp.rs, and crates/mcp: tool/resource schemas, output, protocol compatibility, and authentication. Derive expectations from current source and snapshots, never a hardcoded historical tool count. Preserve documented local proposal approval and hosted read-only boundaries.
API and generated client	apps/api, crates/api-cloud, and affected auth/sync crates; apps/api/openapi.gen.json and packages/api-client/src/generated. Check routes, payloads, errors, auth scopes, and compatibility with already shipped desktop/mobile/CLI clients.
Agent skills and plugins	Authored skills/anarlog, generated agent-plugins/anarlog and docs/skill.md, native manifests, and repository marketplace entries. Update instructions and examples, bump the plugin's own version when its package changes, and keep manifests and their tests aligned.
Documentation and discovery	Read docs/AGENTS.md; review affected product guides, installation/upgrade instructions, CLI/MCP/Cloud references, examples, troubleshooting, screenshots, docs/docs.json, and apps/web/public/llms.txt. Include the public skill, Mintlify's llms.txt/llms-full.txt, and the website changelog in publication verification. Document shipped behavior and actual platform availability.
Hosted services	Compare each independently deployed service with its last published SHA/tag: API/hosted MCP (api_cd.yaml, api_v*), Stripe (stripe_cd.yaml, stripe_v*), hosted Postgres (db_cd.yaml), website (web_cd.yaml, web_v*), and Mintlify docs. Record whether the candidate needs a redeploy.

Review related release dependencies when affected: SQLite/CloudSync and hosted schema migrations, downgrade compatibility, native bindings, mobile/watch consumers, billing/auth configuration, installer/updater and package channels, and release version attribution in error reporting. Record backend-first rollout and rollback requirements before publishing a client that depends on them. Follow each component's instructions; this review does not authorize mobile submission or unrelated infrastructure changes.

Validate and synchronize

Run the full locally reproducible jobs from cli_ci.yaml and api_ci.yaml for affected code, plus consumer checks from root AGENTS.md. CLI CI includes command/MCP contract snapshots, documentation coverage, Linux/Windows smoke tests, plugin checks, and Mintlify validation. API CI checks hosted MCP/auth and OpenAPI generation. A passing snapshot or docs check does not prove that a new product feature was considered; retain the surface review above.

When the API contract changes, regenerate the spec and client, review the diff, and typecheck the client and affected consumers:

cargo test -p api gen_openapi_json
pnpm -F @anlg/api-client openapi
pnpm -F @anlg/api-client typecheck

Edit the authored agent skill and references, then generate their mirrors with node scripts/publish-anarlog-skill.mjs. The script writes repository files; it does not publish a website or install a plugin. Before every release, run:

node scripts/publish-anarlog-skill.mjs --check
node --test scripts/publish-anarlog-skill.test.mjs

Use the Mintlify version pinned in cli_ci.yaml to run validate and broken-links --check-anchors --check-redirects from docs/. Run affected web checks when changing website content or discovery files. Regenerate again to confirm generated output is stable, and include all intended generated changes before freezing the candidate.

Changelog Gate

The changelog is required alongside the release surface review. Before releasing either channel:

1. Open packages/changelog/content/AGENTS.md and follow its instructions.
2. For stable, confirm packages/changelog/content/<version>.md exists. For Nightly, use packages/changelog/nightly.md.
3. Compare the file against the desktop user-facing changes since the latest desktop_v* tag.
4. If the changelog is missing or incomplete, update it before release.

Changelog entries should be worth reading for app users. Exclude internal-only refactors, CI changes, infra noise, and implementation details unless they explain a user-visible change. If a user-facing change came from a pull request by someone outside the Fastrepl org, that item must credit them. See packages/changelog/content/AGENTS.md.

Each changelog file must include:

---
date: "YYYY-MM-DD"
summary: "One concise, user-facing sentence for the changelog index preview."
---

After editing the changelog, run:

pnpm exec dprint fmt --allow-no-files packages/changelog/content/<version>.md
pnpm exec dprint check --allow-no-files packages/changelog/content/<version>.md
pnpm -F @anlg/changelog typecheck

Merge to Main

Only after the changelog and required release surface updates are accurate and validation passes:

1. Commit the changelog and surface updates in coherent commits.
2. Open or update their PRs.
3. Wait for CI and required review state to be clear.
4. Merge the release preparation PRs to main.
5. Verify main contains the changelog and all required surface updates.
6. Record the resulting main SHA, publish a Nightly from it, and retain its immutable desktop_nightly_v<nightly-version> tag as CANDIDATE_REF.
7. Complete the Nightly candidate testing period before building stable. Keep development on main; do not replace the candidate with its latest head.

If using GitButler, prefer:

but diff
but commit -b chore/release-changelog -m "Update desktop release changelog

Refresh the desktop changelog for the next stable release." <file-or-hunk-ids>
but pr new chore/release-changelog -t

Use actual IDs from but diff / but status -fv; do not invent IDs.

Deploy Hosted Services

This is a required release action, not optional follow-up. After the candidate is on main, decide for each independently published service and then deploy the ones that need it before publishing the desktop client.

For each service:

1. Find the last successful CD run and, when one exists, the published tag (api_v*, stripe_v*, web_v*). Hosted Postgres has no version tag; use the last successful db_cd.yaml run SHA.
2. Diff that SHA against the candidate for that service's source. Re-read the workflow if the checkout, image context, or migration path is unclear.
3. Dispatch the CD workflow on main when the candidate contains unpublished changes this release needs, or that users would otherwise miss. Reuse a live deployment only when its SHA already includes those changes.
4. An unchanged service needs that live SHA/version recorded. Do not dispatch a no-op redeploy to make the checklist look complete.
5. Confirm the target is Anarlog before any service access; never access *-char. Check the run's headSha against the intended SHA and wait for the job and tag (when the workflow creates one).

gh workflow run api_cd.yaml --ref main
gh workflow run stripe_cd.yaml --ref main
gh workflow run db_cd.yaml --ref main
gh workflow run web_cd.yaml --ref main
gh run list --workflow api_cd.yaml --limit 3
gh run view <run-id> --json headSha,url

Service	Workflow	Deploy when	Live check
API and hosted MCP	api_cd.yaml	Unpublished API, hosted MCP, auth, or related proxy changes	/health reports the new api_v* version; MCP discovery and an authenticated read succeed when credentials exist
Stripe billing	stripe_cd.yaml	Unpublished apps/stripe or image-context changes	CD succeeded and tagged stripe_v*; /health on the Anarlog Stripe app returns ok
Hosted Postgres	db_cd.yaml	Unpublished supabase/ migrations this release needs	Linked Anarlog project only; supabase db push completed. Run db_ci.yaml coverage first when migrations changed
Website	web_cd.yaml	Unpublished website, changelog, or download-page changes not already covered by the Linux APT web deploy	Live anarlog.so URLs show the candidate content
Docs	Mintlify connected deploy (no GitHub CD)	Unpublished docs/ or public skill content after merge	Live https://docs.anarlog.so pages, skill.md, and LLM indexes

If the desktop client depends on new server or schema behavior, those deploys must succeed before desktop_publish.yaml. Independent website or docs updates can finish in parallel, but the release is incomplete until they are live or explicitly deferred.

Trigger Stable Release

Dispatch desktop, CLI, and API verification from the candidate Nightly tag, then identify each run and verify headSha equals the recorded candidate before accepting any job. Reuse an existing successful run only if it covers the exact SHA and all required jobs; path-filtered or skipped jobs are not coverage:

CANDIDATE_REF=desktop_nightly_v<nightly-version>
gh workflow run desktop_ci.yaml --ref "$CANDIDATE_REF"
gh workflow run cli_ci.yaml --ref "$CANDIDATE_REF"
gh workflow run api_ci.yaml --ref "$CANDIDATE_REF"

Verify every native job and the source-rebuilt CloudSync artifacts, including both macOS architectures, Windows, and both Linux architectures. Pull-request runs skip the desktop native jobs. Require both CLI jobs and the API job to pass for this candidate as well. Keep the candidate fixed through publication.

After candidate testing, verify the candidate remains an ancestor of main, then build the stable candidate without publishing:

gh workflow run desktop_cd.yaml \
  --ref "$CANDIDATE_REF" \
  -f channel=stable \
  -f candidate_sha=<40-character-main-sha> \
  -f include_windows=true \
  -f include_linux=true \
  -f version=<version>

Watch the dry-run build:

gh run list --workflow desktop_cd.yaml --limit 5
gh run view <run-id> --json headSha,url
gh run watch <run-id>

The run's headSha must equal the recorded release-candidate SHA. A mismatch blocks acceptance even if the workflow succeeds.

Do not use GitHub's rerun button for a failed stable candidate or optional Linux audio QA run. Dispatch a fresh run instead; publication only accepts first-attempt run IDs so evidence cannot be mixed across attempts.

The dry-run workflow must:

• use the exact explicit stable version
• build both Apple Silicon and Intel macOS artifacts
• build the signed Windows and Linux artifacts for the same version and commit
• upload a draft CrabNebula release without publishing it
• upload desktop-release-provenance-<version>-<sha>, including the exact artifact hashes and pinned CrabNebula CLI version, asset ID, and SHA-256

Verify the bundled CLI in the candidate artifacts on every shipped platform, using the platform runner when necessary. Confirm APP_VERSION reached the CLI build and the packaged executable's --version reports the explicit desktop version. Check its help and a real stdio MCP initialize/discovery exchange against the reviewed contract, using an isolated fixture database. Keep stdout protocol-only and verify clean shutdown. A developer binary on PATH is not evidence for the packaged CLI. After updating, verify the supported CLI installer resolves to the new bundled executable; record unavailable platform checks.