From a16447802c1f3dc2137f61cbb21e5ff2e3209246 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Sat, 27 Dec 2025 19:41:20 -0800
Subject: [PATCH] docs: prepare 0.39.0 changelog and version notes

---
 CHANGELOG.md   | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++
 cmd/bd/info.go | 18 +++++++++++++++
 2 files changed, 81 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 12f8b75c..fa452554 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,69 @@ All notable changes to the beads project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.39.0] - 2025-12-27
+
+### Added
+
+- **`bd orphans` command** (GH#767) - Detect orphaned issues
+  - Finds issues mentioned in git commits that were never closed
+  - DRY refactoring of orphan detection from `bd doctor`
+  - Helps maintain issue hygiene in larger projects
+
+- **`bd admin` parent command** (bd-3u8m) - Consolidated admin tools
+  - `bd admin cleanup` - Clean up unused data
+  - `bd admin compact` - Compact the database
+  - `bd admin reset` - Reset to initial state
+  - Reduces top-level command clutter
+
+- **`--prefix` flag for `bd create`** - Cross-rig issue creation
+  - Create issues in other rigs from any directory
+  - Accepts prefix (`bd-`), short form (`bd`), or rig name (`beads`)
+  - Works with existing routes.jsonl routing
+
+### Changed
+
+- **`bd mol catalog` → `bd formula list`** (bd-ctmg) - Command rename
+  - Aligns with formula-based terminology
+  - `bd formula list` shows available molecule templates
+
+- **`bd info --thanks`** (bd-wb9g) - Relocated thanks command
+  - Contributors list moved under `bd info`
+  - Reduces command namespace pollution
+
+- **Removed unused commands** (bd-x0zl)
+  - `bd pin`, `bd unpin`, `bd hook` removed
+  - Functionality covered by `gt mol` commands in Gas Town
+  - Cleaner separation between beads (data) and gastown (orchestration)
+
+- **`bd doctor --check=pollution`** (bd-kff0) - Integrated test pollution check
+  - Detects test artifacts left in production database
+  - Previously standalone `bd detect-pollution` command
+
+### Fixed
+
+- **macOS codesigning** - Fixed `bump-version.sh --install`
+  - Ad-hoc signing for local installations
+  - Prevents macOS from quarantining the binary
+
+- **Lint errors and Nix vendorHash** (GH#769)
+  - Resolved golangci-lint issues
+  - Updated Nix package hash for reproducible builds
+
+### Documentation
+
+- **Issue Statuses section** (bd-epww) - CLI_REFERENCE.md
+  - Comprehensive status lifecycle documentation
+  - Clear explanations of open, pinned, in_progress, blocked, deferred, closed, tombstone
+
+- **Consolidated UI_PHILOSOPHY files** (GH#745)
+  - Merged duplicate philosophy docs
+  - Single source of truth for UI design principles
+
+- **README and PLUGIN.md fixes** (GH#763)
+  - Corrected installation instructions
+  - Updated plugin documentation
+
 ## [0.38.0] - 2025-12-27
 
 ### Added
diff --git a/cmd/bd/info.go b/cmd/bd/info.go
index bdcf8558..9d80c9c9 100644
--- a/cmd/bd/info.go
+++ b/cmd/bd/info.go
@@ -296,6 +296,24 @@ type VersionChange struct {
 
 // versionChanges contains agent-actionable changes for recent versions
 var versionChanges = []VersionChange{
+	{
+		Version: "0.39.0",
+		Date:    "2025-12-27",
+		Changes: []string{
+			"NEW: bd orphans command (GH#767) - Detect issues mentioned in commits but never closed",
+			"NEW: bd admin parent command (bd-3u8m) - Consolidated cleanup/compact/reset under bd admin",
+			"NEW: --prefix flag for bd create - Create issues in other rigs from any directory",
+			"CHANGED: bd mol catalog → bd formula list (bd-ctmg) - Aligns with formula terminology",
+			"CHANGED: bd info --thanks (bd-wb9g) - Contributors list moved under bd info",
+			"CHANGED: Removed unused bd pin/unpin/hook commands (bd-x0zl) - Use gt mol commands",
+			"CHANGED: bd doctor --check=pollution (bd-kff0) - Test pollution check integrated into doctor",
+			"FIX: macOS codesigning in bump-version.sh --install - Prevents quarantine issues",
+			"FIX: Lint errors and Nix vendorHash (GH#769) - Clean builds on all platforms",
+			"DOCS: Issue Statuses section in CLI_REFERENCE.md (bd-epww) - Comprehensive status docs",
+			"DOCS: Consolidated duplicate UI_PHILOSOPHY files (GH#745) - Single source of truth",
+			"DOCS: README and PLUGIN.md fixes (GH#763) - Corrected installation instructions",
+		},
+	},
 	{
 		Version: "0.38.0",
 		Date:    "2025-12-27",