Add comprehensive compaction documentation

- Updated README.md with Tier 1/2 info, restore command, cost analysis
- Created COMPACTION.md with full guide covering:
  - How compaction works (architecture, two-tier system)
  - CLI reference and examples
  - Eligibility rules and configuration
  - Cost analysis with detailed tables
  - Automation examples (cron, workflows)
  - Safety, recovery, and troubleshooting
  - FAQ and best practices
- Added examples/compaction/ with 3 scripts:
  - workflow.sh: Interactive compaction workflow
  - cron-compact.sh: Automated monthly compaction
  - auto-compact.sh: Smart threshold-based compaction
  - README.md: Examples documentation

Closes bd-265

Amp-Thread-ID: https://ampcode.com/threads/T-8113e88e-1cd0-4a9e-b581-07045a3ed31e
Co-authored-by: Amp <amp@ampcode.com>

examples/compaction/workflow.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Interactive compaction workflow
+# Run this manually when you want to compact old issues
+
+set -e
+
+echo "=== BD Compaction Workflow ==="
+echo "Date: $(date)"
+echo
+
+# Check API key
+if [ -z "$ANTHROPIC_API_KEY" ]; then
+  echo "❌ Error: ANTHROPIC_API_KEY not set"
+  echo
+  echo "Set your API key:"
+  echo "  export ANTHROPIC_API_KEY='sk-ant-...'"
+  echo
+  exit 1
+fi
+
+# Check bd is installed
+if ! command -v bd &> /dev/null; then
+  echo "❌ Error: bd command not found"
+  echo
+  echo "Install bd:"
+  echo "  curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash"
+  echo
+  exit 1
+fi
+
+# Preview candidates
+echo "--- Preview Tier 1 Candidates ---"
+bd compact --dry-run --all
+
+echo
+read -p "Proceed with Tier 1 compaction? (y/N) " -n 1 -r
+echo
+if [[ $REPLY =~ ^[Yy]$ ]]; then
+  echo "--- Running Tier 1 Compaction ---"
+  bd compact --all
+  echo "✅ Tier 1 compaction complete"
+else
+  echo "⏭️  Skipping Tier 1"
+fi
+
+# Preview Tier 2
+echo
+echo "--- Preview Tier 2 Candidates ---"
+bd compact --dry-run --all --tier 2
+
+echo
+read -p "Proceed with Tier 2 compaction? (y/N) " -n 1 -r
+echo
+if [[ $REPLY =~ ^[Yy]$ ]]; then
+  echo "--- Running Tier 2 Compaction ---"
+  bd compact --all --tier 2
+  echo "✅ Tier 2 compaction complete"
+else
+  echo "⏭️  Skipping Tier 2"
+fi
+
+# Show stats
+echo
+echo "--- Final Statistics ---"
+bd compact --stats
+
+echo
+echo "=== Compaction Complete ==="
+echo
+echo "Next steps:"
+echo "  1. Review compacted issues: bd list --json | jq '.[] | select(.compaction_level > 0)'"
+echo "  2. Commit changes: git add .beads/issues.jsonl issues.db && git commit -m 'Compact old issues'"
+echo "  3. Push to remote: git push"