docs(release): RELEASE.md runbook + ADR-031 (pipeline PR 6/6)

[aterrylu]

Summary

PR 6 of 6 (docs portion). The written release runbook the pipeline was missing — releasing is no longer in anyone's head.

What's here

• docs/RELEASE.md — the runbook:
  • Mental model: changesets → "Version Packages" PR → auto-tag → release.yml
  • Day-to-day changeset ritual + bump guidance
  • How to cut a release (TL;DR: merge the Version Packages PR)
  • Beta/pre-release, rollback strategy, local DMG builds
  • The GitHub secrets table (incl. the Apple signing secrets for the upcoming PRs)
  • Troubleshooting
• docs/DECISIONS.md → ADR-031 — the decision record: context (version drift + hand-built unvalidated DMG), the 6-PR design, scope decisions (macOS-only desktop, universal2 from day one, changesets over release-please), rationale, alternatives, implications, validation.

Notes

• ADR-031 is team-lead-owned — drafted here, flagged for your review/edit.
• Numbering: ADR-030 informally forward-referenced "ADR-031" for named profiles (unbuilt, speculative). This ADR claims ADR-031 for the release pipeline — the decision actually being made. Noted in the entry; named profiles take a later number if ever built.
• SLSA provenance (the other half of PR feat: project-based session view + responsive sidebar #6) edits release.yml, which lives in unmerged PR feat: migrate dashboard to React + Zustand + Tailwind #3 — deferred to a small follow-up once feat: migrate dashboard to React + Zustand + Tailwind #3 lands, to avoid a conflict.

Scope

Docs-only. No code, no version impact (empty changeset). make check 353/353, biome clean.

Pipeline status

PR	State
#1 changesets	✅ merged
#2 lefthook + commitlint	✅ merged
#3 universal DMG in CI	🟢 open (#183)
#4 signing	⏳ Apple key
#5 auto-update	⏳ after #4
#6 docs (this)	🟢 open

🤖 Generated with Claude Code

[nox-0x]

Approving — clear, accurate runbook and a well-structured ADR; references and changeset config check out.

Spot-checks I ran:

• .changeset/config.json matches the described fixed group + @changesets/changelog-github + aterrylu/autonomOS repo.
• Root scripts changeset and version exist as documented; empty-changeset format used here is valid.
• Referenced paths exist: packages/app/scripts/bundle-node.sh, build-dmg.sh, validate-dmg.sh, build-resources/entitlements.mac.plist.
• version.yml matches the described "merge Version PR → auto-tag" flow; release.yml currently only builds server tarballs, with DMG/validate-intel/CHANGELOG-body stages coming in PR #3 — acknowledged in the PR body.

Non-blocking follow-ups (land later, no need to gate this PR):

• The release.yml table (build-dmg / validate-intel / CHANGELOG body) describes the post-#3 state. A one-line "current vs. target state" callout near the top of RELEASE.md would save a future reader the confusion of comparing the runbook to main's release.yml — but this is polish, not a blocker.
• stage-universal-server.sh is referenced but not yet in the tree (it ships with #3). Same comment — fine as forward reference, can revisit when #3 lands.