feat: Add agent upgrade awareness documentation and tooling

Implements bd-hwmp and bd-5otr (part of epic bd-nxgk) to help AI agents
automatically detect and adapt to bd upgrades.

## Changes

### Documentation (bd-hwmp)
- Added "After Upgrading bd" section to AGENTS.md with step-by-step workflow
- Enhanced "Pro Tips for Agents" with upgrade detection guidance
- Documents bd info --whats-new and bd hooks install commands
- References GitHub Discussion #239

### Startup Hook (bd-5otr)
- Created examples/startup-hooks/bd-version-check.sh
  - Auto-detects bd version changes via .beads/metadata.json
  - Shows bd info --whats-new when upgrade detected
  - Auto-updates outdated git hooks
  - Handles edge cases (no jq, not in beads project, etc.)
- Created examples/startup-hooks/README.md with integration examples
  - Claude Code, GitHub Copilot, Cursor integration patterns
  - Comprehensive usage and troubleshooting guide
- Updated examples/README.md with new startup-hooks section

## Impact

Agents can now:
- Automatically detect bd upgrades at session start
- See what changed without re-reading all documentation
- Keep git hooks in sync automatically
- Adapt workflows based on new features

Works today with zero bd code changes required!

Related: #239

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.beads/metadata.json

@@ -1,4 +1,5 @@
 {
   "database": "beads.db",
-  "jsonl_export": "beads.jsonl"
+  "jsonl_export": "beads.jsonl",
+  "last_bd_version": "0.24.2"
 }

AGENTS.md

@@ -27,6 +27,25 @@ This shows the last 3 versions with workflow-impacting changes, avoiding the nee
 
 **Why this matters:** bd releases weekly with major versions. This command helps you quickly understand what changed without parsing the full CHANGELOG.
 
+### 🔄 After Upgrading bd
+
+When bd is upgraded to a new version, follow this workflow:
+
+```bash
+# 1. Check what changed
+bd info --whats-new
+
+# 2. Update git hooks to match new bd version
+bd hooks install
+
+# 3. Check for any outdated hooks (optional)
+bd info  # Shows warnings if hooks are outdated
+```
+
+**Why update hooks?** Git hooks (pre-commit, post-merge, pre-push) are versioned with bd. Outdated hooks may miss new auto-sync features or bug fixes. Running `bd hooks install` ensures hooks match your bd version.
+
+**Related:** See GitHub Discussion #239 for background on agent upgrade workflows.
+
 ## Human Setup vs Agent Usage
 
 **IMPORTANT:** If you need to initialize bd, use the `--quiet` flag:
@@ -475,6 +494,8 @@ See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for detailed instructions on:
 
 - Always use `--json` flags for programmatic use
 - **Always run `bd sync` at end of session** to flush/commit/push immediately
+- **Check `bd info --whats-new` at session start** if bd was recently upgraded
+- **Run `bd hooks install`** if `bd info` warns about outdated git hooks
 - Link discoveries with `discovered-from` to maintain context
 - Check `bd ready` before asking "what next?"
 - Auto-sync batches changes in 30-second window - use `bd sync` to force immediate flush

examples/README.md

@@ -4,16 +4,22 @@ This directory contains examples of how to integrate bd with AI agents and workf
 
 ## Examples
 
+### Agent Integration
 - **[python-agent/](python-agent/)** - Simple Python agent that discovers ready work and completes tasks
   - **[AGENT_MAIL_EXAMPLE.md](python-agent/AGENT_MAIL_EXAMPLE.md)** - Multi-agent coordination with Agent Mail
 - **[bash-agent/](bash-agent/)** - Bash script showing the full agent workflow
+- **[startup-hooks/](startup-hooks/)** - Session startup scripts for automatic bd upgrade detection
+- **[claude-desktop-mcp/](claude-desktop-mcp/)** - MCP server for Claude Desktop integration
+- **[claude-code-skill/](claude-code-skill/)** - Claude Code skill for effective beads usage patterns
+
+### Tools & Utilities
 - **[monitor-webui/](monitor-webui/)** - Standalone web interface for real-time issue monitoring and visualization
 - **[markdown-to-jsonl/](markdown-to-jsonl/)** - Convert markdown planning docs to bd issues
 - **[github-import/](github-import/)** - Import issues from GitHub repositories
 - **[git-hooks/](git-hooks/)** - Pre-configured git hooks for automatic export/import
 <!-- REMOVED (bd-4c74): branch-merge example - collision resolution no longer needed with hash IDs -->
-- **[claude-desktop-mcp/](claude-desktop-mcp/)** - MCP server for Claude Desktop integration
-- **[claude-code-skill/](claude-code-skill/)** - Claude Code skill for effective beads usage patterns
+
+### Workflow Patterns
 - **[contributor-workflow/](contributor-workflow/)** - OSS contributor setup with separate planning repo
 - **[team-workflow/](team-workflow/)** - Team collaboration with shared repositories
 - **[multi-phase-development/](multi-phase-development/)** - Organize large projects by phases (planning, MVP, iteration, polish)

examples/startup-hooks/README.md

@@ -0,0 +1,118 @@
+# Startup Hooks for AI Agents
+
+This directory contains startup hook scripts that help AI agents automatically detect and adapt to changes in their environment.
+
+## bd-version-check.sh
+
+**Purpose:** Automatically detect bd (beads) upgrades and show what changed
+
+**Features:**
+- ✅ Detects when bd version changes between sessions
+- ✅ Shows `bd info --whats-new` output automatically
+- ✅ Auto-updates outdated git hooks
+- ✅ Persists version tracking in `.beads/metadata.json`
+- ✅ Works today - no bd code changes required!
+
+**Usage:**
+
+```bash
+# Source the script at session start (recommended)
+source examples/startup-hooks/bd-version-check.sh
+
+# Or execute it directly
+bash examples/startup-hooks/bd-version-check.sh
+```
+
+### Integration Examples
+
+#### Claude Code
+
+If Claude Code supports startup hooks:
+```bash
+# Add to .claude/hooks/session-start
+source examples/startup-hooks/bd-version-check.sh
+```
+
+Alternatively, manually run at the start of each coding session.
+
+#### GitHub Copilot
+
+Add to your shell initialization file:
+```bash
+# ~/.bashrc or ~/.zshrc
+# Run bd version check when entering a beads project
+if [ -d ".beads" ]; then
+  source /path/to/beads/examples/startup-hooks/bd-version-check.sh
+fi
+```
+
+#### Cursor
+
+Add to workspace settings or your shell init file following the same pattern as GitHub Copilot.
+
+#### Generic Integration
+
+Any AI coding environment that allows custom startup scripts can source this file.
+
+### Requirements
+
+- **bd (beads)**: Must be installed and in PATH
+- **jq**: Required for JSON manipulation (`brew install jq` on macOS, `apt-get install jq` on Ubuntu)
+- **.beads directory**: Must exist in current project
+
+### How It Works
+
+1. **Version Detection**: Reads current bd version and compares to `.beads/metadata.json`
+2. **Change Notification**: If version changed, displays upgrade banner with what's new
+3. **Hook Updates**: Checks for outdated git hooks and auto-updates them
+4. **Persistence**: Updates `metadata.json` with current version for next session
+
+### Example Output
+
+```
+🔄 bd upgraded: 0.23.0 → 0.24.2
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🆕 What's New in bd (Current: v0.24.2)
+=============================================================
+
+## v0.24.2 (2025-11-23)
+  • New feature X
+  • Bug fix Y
+  • Performance improvement Z
+
+[... rest of what's new output ...]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+💡 Review changes above and adapt your workflow accordingly
+
+🔧 Git hooks outdated. Updating to match bd v0.24.2...
+✓ Git hooks updated successfully
+```
+
+### Edge Cases Handled
+
+- **Not in a beads project**: Silently exits (safe to include in global shell init)
+- **bd not installed**: Silently exits
+- **jq not installed**: Shows warning but doesn't break
+- **metadata.json missing**: Auto-creates it
+- **First run**: Sets version without showing upgrade message
+- **bd command fails**: Silently exits
+
+### Troubleshooting
+
+**Q: Script doesn't detect version change**
+A: Check that `.beads/metadata.json` exists and contains `last_bd_version` field
+
+**Q: "jq not found" warning**
+A: Install jq: `brew install jq` (macOS) or `apt-get install jq` (Ubuntu)
+
+**Q: Git hooks not auto-updating**
+A: Ensure you have write permissions to `.git/hooks/` directory
+
+### Related
+
+- **GitHub Discussion #239**: "Upgrading beads: how to let the Agent know"
+- **Parent Epic**: bd-nxgk - Agent upgrade awareness system
+- **AGENTS.md**: See "After Upgrading bd" section for manual workflow

examples/startup-hooks/bd-version-check.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+#
+# bd-version-check.sh - Automatic bd upgrade detection for AI agent sessions
+#
+# This script detects when bd (beads) has been upgraded and automatically shows
+# what changed, helping AI agents adapt their workflows without manual intervention.
+#
+# FEATURES:
+# - Detects bd version changes by comparing to last-seen version
+# - Shows 'bd info --whats-new' output when upgrade detected
+# - Auto-updates git hooks if outdated
+# - Persists version in .beads/metadata.json
+# - Zero bd code changes required - works today!
+#
+# INTEGRATION:
+# Add this script to your AI environment's session startup:
+#
+# Claude Code:
+#   Add to .claude/hooks/session-start (if supported)
+#   Or manually source at beginning of work
+#
+# GitHub Copilot:
+#   Add to your shell initialization (.bashrc, .zshrc)
+#   Or manually run at session start
+#
+# Cursor:
+#   Add to workspace settings or shell init
+#
+# Generic:
+#   source /path/to/bd-version-check.sh
+#
+# USAGE:
+#   # Option 1: Source it (preferred)
+#   source examples/startup-hooks/bd-version-check.sh
+#
+#   # Option 2: Execute it
+#   bash examples/startup-hooks/bd-version-check.sh
+#
+# REQUIREMENTS:
+# - bd (beads) installed and in PATH
+# - jq for JSON manipulation
+# - .beads directory exists in current project
+#
+
+# Exit early if not in a beads project
+if [ ! -d ".beads" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Check if bd is installed
+if ! command -v bd &> /dev/null; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Check if jq is installed (required for JSON manipulation)
+if ! command -v jq &> /dev/null; then
+  echo "⚠️  bd-version-check: jq not found. Install jq to enable automatic upgrade detection."
+  return 0 2>/dev/null || exit 0
+fi
+
+# Get current bd version
+CURRENT_VERSION=$(bd --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+
+if [ -z "$CURRENT_VERSION" ]; then
+  # bd command failed, skip
+  return 0 2>/dev/null || exit 0
+fi
+
+# Path to metadata file
+METADATA_FILE=".beads/metadata.json"
+
+# Initialize metadata.json if it doesn't exist
+if [ ! -f "$METADATA_FILE" ]; then
+  echo '{"database": "beads.db", "jsonl_export": "beads.jsonl"}' > "$METADATA_FILE"
+fi
+
+# Read last-seen version from metadata.json
+LAST_VERSION=$(jq -r '.last_bd_version // "unknown"' "$METADATA_FILE" 2>/dev/null)
+
+# Detect version change
+if [ "$CURRENT_VERSION" != "$LAST_VERSION" ] && [ "$LAST_VERSION" != "unknown" ]; then
+  echo ""
+  echo "🔄 bd upgraded: $LAST_VERSION → $CURRENT_VERSION"
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Show what's new
+  bd info --whats-new 2>/dev/null || echo "⚠️  Could not fetch what's new (run 'bd info --whats-new' manually)"
+
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "💡 Review changes above and adapt your workflow accordingly"
+  echo ""
+fi
+
+# Check for outdated git hooks (works even if version didn't change)
+if bd hooks list 2>&1 | grep -q "outdated"; then
+  echo "🔧 Git hooks outdated. Updating to match bd v$CURRENT_VERSION..."
+  if bd hooks install 2>/dev/null; then
+    echo "✓ Git hooks updated successfully"
+  else
+    echo "⚠️  Failed to update git hooks. Run 'bd hooks install' manually."
+  fi
+  echo ""
+fi
+
+# Update metadata.json with current version
+# Use a temp file to avoid corruption if jq fails
+TEMP_FILE=$(mktemp)
+if jq --arg v "$CURRENT_VERSION" '.last_bd_version = $v' "$METADATA_FILE" > "$TEMP_FILE" 2>/dev/null; then
+  mv "$TEMP_FILE" "$METADATA_FILE"
+else
+  # jq failed, clean up temp file
+  rm -f "$TEMP_FILE"
+fi
+
+# Clean exit for sourcing
+return 0 2>/dev/null || exit 0