Document migration inspection commands in user docs

- Add bd migrate --inspect and bd info --schema examples to README.md
- Update QUICKSTART.md migration section with AI agent workflow
- Expand AGENTS.md with migration safety invariants explanation
- Clarify when and why to use inspection before migrating

Makes the new AI-supervised migration features discoverable.

Amp-Thread-ID: https://ampcode.com/threads/T-de7e1141-87ac-4b4a-9cea-1b7bc4d51da9
Co-authored-by: Amp <amp@ampcode.com>

AGENTS.md

@@ -226,12 +226,26 @@ bd merge bd-42 bd-43 --into bd-41 --dry-run            # Preview merge
 bd migrate                                             # Detect and migrate old databases
 bd migrate --dry-run                                   # Preview migration
 bd migrate --cleanup --yes                             # Migrate and remove old files
-bd migrate --inspect --json                            # Show migration plan for AI agents
 
-# Inspect database schema and state (for AI agent analysis)
+# AI-supervised migration (check before running bd migrate)
+bd migrate --inspect --json                            # Show migration plan for AI agents
 bd info --schema --json                                # Get schema, tables, config, sample IDs
+
+# Workflow: AI agents should inspect first, then migrate
+# 1. Run --inspect to see pending migrations and warnings
+# 2. Check for missing_config (like issue_prefix)
+# 3. Review invariants_to_check for safety guarantees
+# 4. If warnings exist, fix config issues first
+# 5. Then run bd migrate safely
 ```
 
+**Migration safety:** The system verifies data integrity invariants after migrations:
+- **required_config_present**: Ensures issue_prefix and schema_version are set
+- **foreign_keys_valid**: No orphaned dependencies or labels
+- **issue_count_stable**: Issue count doesn't decrease unexpectedly
+
+These invariants prevent data loss and would have caught issues like GH #201 (missing issue_prefix after migration).
+
 ### Managing Daemons
 
 bd runs a background daemon per workspace for auto-sync and RPC operations. Use `bd daemons` to manage multiple daemons:

QUICKSTART.md

@@ -129,7 +129,13 @@ You can use project-specific databases:
 After upgrading bd, use `bd migrate` to check for and migrate old database files:
 
 ```bash
-# Check for migration opportunities
+# Inspect migration plan (AI agents)
+./bd migrate --inspect --json
+
+# Check schema and config
+./bd info --schema --json
+
+# Preview migration changes
 ./bd migrate --dry-run
 
 # Migrate old databases to beads.db
@@ -139,6 +145,8 @@ After upgrading bd, use `bd migrate` to check for and migrate old database files
 ./bd migrate --cleanup --yes
 ```
 
+**AI agents:** Use `--inspect` to analyze migration safety before running. The system verifies required config keys and data integrity invariants.
+
 ## Next Steps
 
 - Add labels: `./bd create "Task" -l "backend,urgent"`

README.md

@@ -259,6 +259,12 @@ Hash IDs use **birthday paradox probability** to determine length:
 **Existing databases continue to work** - no forced migration. Run `bd migrate` when ready:
 
 ```bash
+# Inspect migration plan (for AI agents)
+bd migrate --inspect --json
+
+# Check schema and config state
+bd info --schema --json
+
 # Preview migration
 bd migrate --dry-run
 
@@ -269,6 +275,8 @@ bd migrate
 bd info
 ```
 
+**AI-supervised migrations:** The `--inspect` flag provides migration plan analysis for AI agents. The system verifies data integrity invariants (required config keys, foreign key constraints, issue counts) before committing migrations.
+
 **Note:** Hash IDs require schema version 9+. The `bd migrate` command detects old schemas and upgrades automatically.
 
 ### Hierarchical Child IDs