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/auto-compact.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# Smart auto-compaction with thresholds
+# Only compacts if there are enough eligible issues
+#
+# Usage: ./auto-compact.sh [--threshold N] [--tier 1|2]
+
+# Default configuration
+THRESHOLD=10  # Minimum eligible issues to trigger compaction
+TIER=1
+DRY_RUN=false
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --threshold)
+      THRESHOLD="$2"
+      shift 2
+      ;;
+    --tier)
+      TIER="$2"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1"
+      echo "Usage: $0 [--threshold N] [--tier 1|2] [--dry-run]"
+      exit 1
+      ;;
+  esac
+done
+
+# Check API key
+if [ -z "$ANTHROPIC_API_KEY" ]; then
+  echo "❌ Error: ANTHROPIC_API_KEY not set"
+  exit 1
+fi
+
+# Check bd is installed
+if ! command -v bd &> /dev/null; then
+  echo "❌ Error: bd command not found"
+  exit 1
+fi
+
+# Check eligible issues
+echo "Checking eligible issues (Tier $TIER)..."
+ELIGIBLE=$(bd compact --dry-run --all --tier "$TIER" --json 2>/dev/null | jq '. | length' || echo "0")
+
+if [ -z "$ELIGIBLE" ] || [ "$ELIGIBLE" = "null" ]; then
+  ELIGIBLE=0
+fi
+
+echo "Found $ELIGIBLE eligible issues (threshold: $THRESHOLD)"
+
+if [ "$ELIGIBLE" -lt "$THRESHOLD" ]; then
+  echo "⏭️  Below threshold, skipping compaction"
+  exit 0
+fi
+
+if [ "$DRY_RUN" = true ]; then
+  echo "🔍 Dry run mode - showing candidates:"
+  bd compact --dry-run --all --tier "$TIER"
+  exit 0
+fi
+
+# Run compaction
+echo "🗜️  Compacting $ELIGIBLE issues (Tier $TIER)..."
+bd compact --all --tier "$TIER"
+
+# Show stats
+echo
+echo "📊 Statistics:"
+bd compact --stats
+
+echo
+echo "✅ Auto-compaction complete"
+echo "Remember to commit: git add .beads/issues.jsonl issues.db && git commit -m 'Auto-compact'"