docs(blog): add retrospective on five broken releases before v0.3.2

[Wirasm]

Summary

Adds a new blog post under packages/docs-web/src/content/docs/blog/ — a retrospective on the six bugs that broke every Archon binary release from v0.2.13 through v0.3.1, why dev mode hid all of them, and the smoke test (test-release skill) that finally caught them all.

Also adds a Blog section to the Astro sidebar config so the new directory is discoverable.

Why write this post

Over the past day we shipped v0.2.14 → v0.3.0 → v0.3.1 → v0.3.2 in rapid succession, each chasing a bug the previous release had that was hidden by an even earlier bug. This is a case study in how subtle differences between a contributor's dev environment and the user's installed environment can hide entire classes of bugs, and how a test that lives in the user's environment (a smoke test against the actual released binary on a clean machine) is the only thing that catches seam bugs between components.

Worth publishing because:

• It's a good story with a clear technical arc (each fix reveals the next)
• The lesson is useful beyond Archon — any project shipping compiled binaries has this class of risk
• It's honest about the mistakes (including ones I made in PR fix(build): use build-time constants for binary detection and pretty stream logger #982's architectural choices)
• It gives external contributors credit (specifically @leex279's work on fix(paths): skip pino-pretty transport in compiled binaries #962/fix(workflows): detect compiled binaries via execPath fallback #963 that catalyzed the fix(build): use build-time constants for binary detection and pretty stream logger (replaces #962/#963) #979 refactor)
• It documents decisions that would otherwise live only in git history and issue threads

What's in the post

• The bug onion metaphor — why stacked bugs along the same code path are particularly hard to debug
• Six bug writeups with root cause and fix PR for each:
  • Compiled CLI binary crashes: pino-pretty transport unresolvable in bun --compile bundle #960 pino-pretty transport crash in compiled binaries
  • isBinaryBuild() misdetects compiled binary, version command falls into dev-only package.json read #961 / fix(build): use build-time constants for binary detection and pretty stream logger (replaces #962/#963) #979 isBinaryBuild runtime detection fragility
  • bug(release): release workflow bypasses scripts/build-binaries.sh — v0.2.13 and v0.3.0 binaries are broken #986 / fix(release): wire release workflow to scripts/build-binaries.sh (#986) #987 release workflow bypassing scripts/build-binaries.sh
  • fix(sqlite): add allow_env_keys column to codebases schema + migration #988 SQLite schema missing allow_env_keys column
  • fix(claude): embed SDK cli.js via /embed entry point for compiled binaries #990 Claude SDK cli.js path baked in at build time
  • bug(env-leak-gate): pre-spawn check fires for unregistered cwd paths, blocks title generation and codebase-less workflows #991 / fix(env-leak-gate): skip pre-spawn scan for unregistered cwd paths (#991) #992 env-leak gate firing on unregistered cwd paths
• Why dev mode hid all of this — the structural reason contributors never saw any of these bugs
• Why locally-built binaries "worked" for the person who built them but not for anyone else — the most insidious bit
• The smoke test that broke the pattern — origin story of the test-release skill
• What changed — release skill additions, CI smoke test plan (feat(ci): add workflow run smoke test to release pipeline — the missing guardrail #996), build-time constants pattern, Hetzner VPS for test-release runs
• What's still open — bug(orchestrator): multiple code paths call sendQuery with unregistered cwd, violating pre-spawn check assumptions #993 / investigation: @openai/codex-sdk does not work from compiled bun binaries (no embed equivalent, native binary dependency) #995 / feat(ci): add workflow run smoke test to release pipeline — the missing guardrail #996 with brief context
• A note on blame — honest framing: the lesson isn't "be more careful", it's "test the actual artifact in the actual user environment"

Changes

File	Change
packages/docs-web/src/content/docs/blog/five-broken-releases.md	new — the post, ~3000 words
packages/docs-web/astro.config.mjs	modified — adds Blog sidebar section between Getting Started and Guides

Things worth reviewing

1. Factual accuracy of the bug-by-bug timeline — I wrote it from memory of the PRs and investigation flow. Worth a skim for anything misremembered.
2. External contributor attribution — the post mentions "a community contributor" for PRs fix(paths): skip pino-pretty transport in compiled binaries #962 / fix(workflows): detect compiled binaries via execPath fallback #963 but doesn't name @leex279. Decide whether to name him explicitly or keep it generic.
3. Tone of the "A note on blame" section — the frame is honest self-criticism (my PR fix(build): use build-time constants for binary detection and pretty stream logger #982 refactor introduced bug(release): release workflow bypasses scripts/build-binaries.sh — v0.2.13 and v0.3.0 binaries are broken #986's release workflow gap). Alternative is more neutral "these bugs were subtle and we eventually built the right test". I think the honest framing lands better because the lesson is structural, but second opinion welcome.
4. Length — ~3000 words. Fine for a post-mortem, could be trimmed to ~2000 if you want a shorter read.
5. Sidebar placement — I put Blog between Getting Started and Guides. Could go between Book and Getting Started (higher prominence) or after Contributing (lower). Current position is a guess.
6. Front matter — used category: blog, audience: [user, contributor], sidebar.order: 1. Matches the pattern from reference/security.md. Astro Starlight will autogenerate the section so new posts just land in the directory.
7. Date format — date: 2026-04-08 in the front matter. Starlight doesn't use this natively for sorting — if we want posts ordered chronologically, we'd need to either use numeric order values OR set up a proper blog integration. For one post, order: 1 is fine.

What's NOT in this PR

• The planned future blog posts (release announcements, architecture deep dives, etc.) — scaffolding is set up for them via the new blog/ directory + sidebar entry, but no content added
• A dedicated blog landing page with a "recent posts" list — Starlight's autogenerated sidebar handles navigation for now; if the blog grows, worth adding an index.md in blog/
• RSS / feed — not configured. Add via @astrojs/rss later if desired
• Social card / OG image — the post inherits the site's default. If we want per-post social cards, needs Starlight OG config

These are all optional polish that can ship in follow-up PRs once the blog has more content.

Preview

After merge, the post will be live at https://archon.diy/blog/five-broken-releases/ (or similar — Starlight's URL scheme depends on the section structure). The Blog sidebar entry will appear between Getting Started and Guides.

Want to see it locally before merging? Run bun --filter @archon/docs-web dev and navigate to the preview URL.

Related

• Compiled CLI binary crashes: pino-pretty transport unresolvable in bun --compile bundle #960 through feat(ci): add workflow run smoke test to release pipeline — the missing guardrail #996 — all the bug PRs referenced in the post
• The .claude/skills/test-release/SKILL.md skill that's the hero of the story
• The .claude/skills/release/SKILL.md skill updates that added Steps 10-12 for Homebrew sync and post-release verification

Summary by CodeRabbit

• Documentation
  • Introduced a new "Blog" section to the documentation site for sharing project updates and development insights
  • Published the inaugural blog post detailing improvements to the release workflow, enhanced quality assurance measures, and expanded testing procedures designed to strengthen product reliability and stability

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b81919da-dba0-4fc7-beb7-c8138e186794

📥 Commits

Reviewing files that changed from the base of the PR and between 1a8a1db and b3ff6ed.

📒 Files selected for processing (2)

• packages/docs-web/astro.config.mjs
• packages/docs-web/src/content/docs/blog/five-broken-releases.md

---

📝 Walkthrough

Walkthrough

Added a blog section to Starlight documentation configuration and published a new blog post detailing the release issues and fixes for Archon v0.3.2, including build pipeline failures, schema mismatches, and process improvements.

Changes

Cohort / File(s)	Summary
Starlight Configuration packages/docs-web/astro.config.mjs	Added a new "Blog" sidebar section with autogenerate pointing to the blog directory.
Blog Content packages/docs-web/src/content/docs/blog/five-broken-releases.md	New blog post documenting the multi-bug chain affecting Archon v0.3.2, including pino-pretty crashes, version detection failures, schema mismatches, and CI path embedding issues, along with applied fixes and process improvements.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 A blog post hops into view,
With tales of bugs fixed anew,
From Homebrew to SQLite,
The release journey takes flight,
Configuration and docs shine through!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description provides detailed context but deviates significantly from the required template structure, lacking key sections like UX Journey, Architecture Diagram, Label Snapshot, Validation Evidence, Security Impact, and Rollback Plan.	Restructure the description to follow the repository template: add Label Snapshot section (risk, size, scope, module), Validation Evidence section showing bun run validate output, and Security Impact confirming no new permissions or network calls. Other template sections (UX Journey, Architecture, Rollback) are not applicable to a docs-only change; note this explicitly.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a blog post retrospective on the release issues before v0.3.2.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/blog-five-broken-releases

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}