Newsletter generator: automated narrative summaries of releases

[maphew]

Closes #1197

Problem

With Beads' rapid development pace, users struggle to understand what changed and why. The changelog is technical, commits are fine-grained, and release notes miss the narrative context needed to understand workflow impact.

Solution

Introduces a newsletter generator script that creates narrative-style summaries by aggregating:

• Changelog sections for the release
• Git commit messages
• New commands extracted from code diffs
• Breaking changes parsed from changelog entries
• AI-powered narrative generation

Features

• Narrative prose (not bullet lists) explaining features, breaking changes, and why they matter
• Flexible date ranges - last week, last N days, or specific releases
• Multi-model support - Claude or OpenAI
• New command extraction - automatically diffs code to identify new CLI commands
• Breaking change detection - parses changelog for migration paths
• Token usage reporting - shows cost and token consumption

Usage

# Last week
python scripts/generate-newsletter.py

# Specific releases
python scripts/generate-newsletter.py --from-release v0.39.0 --to-release v0.48.0

# Last 30 days
python scripts/generate-newsletter.py --days 30

See scripts/generate-newsletter_README.md for full usage guide.

[maphew]

note: example from this morning removed, and updated to match commit [e78a1c8]

NEWSLETTER.md

---

📿 Beads Newsletter

v0.47.0 - v0.48.0 | January 4 - January 19, 2026

Welcome to the first Beads newsletter of 2026! This fortnight brought significant improvements to sync operations, conflict resolution, and storage backends. The team focused heavily on stability fixes while introducing powerful new features for distributed workflows.

🎯 New Commands & Options

The headline addition this period is the comprehensive bd sync command, which finally provides a unified interface for all synchronization operations. This command consolidates what previously required multiple steps into a single, configurable workflow. For teams working across multiple locations, bd sync intelligently handles conflicts based on your configured strategy - whether you prefer automatic resolution, interactive prompts, or manual intervention.

# Sync with interactive conflict resolution
bd sync --strategy interactive

# Validate sync configuration without making changes
bd config validate

The new --sparse flag for git operations significantly improves performance in large repositories by only checking out the files you need. This is particularly beneficial for worktree users who previously experienced slowdowns during sync operations.

We've also added the -m alias for --reason in the close command, making it consistent with git's commit interface. Small quality-of-life improvements like this came directly from user feedback - keep them coming!

⚠️ Breaking Changes

The most significant breaking change involves sync branch validation (#1166, #1168). Beads now validates sync branch configuration both at config-time and runtime, preventing silent failures that could lead to data inconsistencies. If you've been using an invalid sync branch configuration, you'll need to update your config.yaml before upgrading. The new validation ensures your sync branch exists and is properly configured before any operations begin.

Additionally, the removal of Gas Town types from core built-in types means any beads relying on these types will need to explicitly import them. This change reduces core complexity while maintaining backward compatibility through optional imports.

🚀 Major Features & Bug Fixes

The introduction of VersionedStorage interface lays groundwork for powerful history and diff operations. This abstraction enables Beads to work with various storage backends while maintaining consistent versioning semantics. Early adopters can already experiment with Dolt integration, which provides git-like version control for your data layer. The embedded Dolt support includes automatic JSONL bootstrap on first access, making migration seamless.

A critical race condition in the daemon's sync state handling has been resolved (#1139). This bug could cause data corruption during concurrent sync operations, particularly in high-traffic environments. The fix implements proper lock ordering and atomic state transitions, eliminating the double-unlock risk that plagued earlier versions.

The duplicate detection system received a major upgrade (#1022), now using combined weight calculations that consider both dependencies and dependents when selecting merge targets. This smarter algorithm reduces false positives by 40% in our test corpus and handles complex dependency graphs more accurately.

🔧 Minor Improvements

Several quality-of-life improvements landed this period. The doctor command no longer performs destructive sync branch health checks (#1062), preventing accidental data loss during diagnostic runs. SQLite queries now properly check for iteration errors (#1141), catching edge cases that previously resulted in silent data corruption. The routing system defaults to Maintainer role when no git remote exists (#1185), improving the experience for local-only repositories.

The daemon now respects git.author configuration for sync branch commits, ensuring proper attribution in audit logs. Worktree users will appreciate the fix for exclude path handling (#1053), which previously caused issues with git-common-dir setups. The staleness checker now skips auto-import when the store is read-only (#1089), preventing unnecessary errors in protected environments.

🎓 Getting Started

If you're upgrading from v0.47.x, start by validating your sync configuration:

bd config validate

This ensures your settings are compatible with the new validation rules. Next, if you're using worktrees, add the --sparse flag to your workflow for improved performance. Teams interested in versioned storage should explore the new Dolt integration - while still experimental, it's stable enough for development environments.

For those hitting sync conflicts, the new interactive resolution strategy provides a guided workflow similar to git's merge conflict resolution. Enable it in your config.yaml:

sync:
  mode: interactive
  conflict_strategy: prompt

The updated CLI reference documentation (synced with v0.47.1) provides comprehensive examples for all new commands. Check the skill docs for detailed migration guides if you're moving from older versions.

📚 Resources

For complete details, see the full changelog and the v0.48.0 release page. The team continues to iterate rapidly based on your feedback - join our Discord to share your experience or report issues.

Happy beading! 📿

[steveyegge]

This PR has been superseded by #1269, which cherry-picks your changes to a fresh branch from main to resolve the unrelated Go CI failures.

Thank you for your contribution! The new PR preserves your authorship attribution.