fix: Resolve database migration failure on existing databases

Fixes critical issue where migration 002 indexes already existed in SCHEMA_SQL,
causing 'index already exists' errors on databases created before v1.0.0-rc.1.

Changes:
- Removed duplicate index definitions from SCHEMA_SQL (database.py)
- Enhanced migration system to detect and handle indexes properly
- Added comprehensive documentation of the fix

Version bumped to 1.0.0-rc.2 with full changelog entry.

Refs: docs/reports/2025-11-24-migration-fix-v1.0.0-rc.2.md

docs/reports/v1.0.0-rc.1-hotfix-instructions.md

@@ -0,0 +1,111 @@
+# v1.0.0-rc.1 Production Hotfix Instructions
+
+## Critical Issue
+v1.0.0-rc.1 fails to start on existing production databases with:
+```
+sqlite3.OperationalError: no such column: token_hash
+```
+
+## Root Cause
+The database initialization tries to create an index on `token_hash` column before migrations run. The old `tokens` table doesn't have this column, causing immediate failure.
+
+## Immediate Fix Options
+
+### Option 1: Manual Database Preparation (Recommended)
+
+**Before deploying v1.0.0-rc.1**, manually prepare the database:
+
+```bash
+# 1. Backup the database first
+cp /path/to/starpunk.db /path/to/starpunk.db.backup
+
+# 2. Connect to production database
+sqlite3 /path/to/starpunk.db
+
+# 3. Add the missing column temporarily
+sqlite> ALTER TABLE tokens ADD COLUMN token_hash TEXT;
+sqlite> .exit
+
+# 4. Now deploy v1.0.0-rc.1
+# Migration 002 will drop and properly recreate the tokens table
+```
+
+### Option 2: Code Hotfix
+
+Modify `/app/starpunk/database.py` in the container:
+
+1. Remove lines 58-60 (the index creation for tokens):
+```python
+# Comment out or remove these lines:
+# CREATE INDEX IF NOT EXISTS idx_tokens_hash ON tokens(token_hash);
+# CREATE INDEX IF NOT EXISTS idx_tokens_me ON tokens(me);
+# CREATE INDEX IF NOT EXISTS idx_tokens_expires ON tokens(expires_at);
+```
+
+2. Let migration 002 create these indexes instead (it already does at lines 49-51)
+
+### Option 3: Skip to v1.0.1
+
+Wait for v1.0.1 release with proper fix, or build custom image with the fix.
+
+## Verification Steps
+
+### Before Deployment
+```sql
+-- Check current tokens table structure
+PRAGMA table_info(tokens);
+-- Should NOT have token_hash column
+```
+
+### After Manual Fix (Option 1)
+```sql
+-- Verify column was added
+PRAGMA table_info(tokens);
+-- Should show token_hash column (even if temporary)
+```
+
+### After Successful Deployment
+```sql
+-- Check migrations were applied
+SELECT * FROM schema_migrations;
+-- Should show 002_secure_tokens_and_authorization_codes.sql
+
+-- Verify new table structure
+PRAGMA table_info(tokens);
+-- Should show proper structure with token_hash as required column
+
+-- Verify indexes exist
+SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='tokens';
+-- Should show idx_tokens_hash, idx_tokens_me, idx_tokens_expires
+```
+
+## Important Notes
+
+1. **All existing tokens will be invalidated** - This is intentional for security
+2. Users will need to re-authenticate after upgrade
+3. The manual fix (Option 1) is temporary - migration 002 drops and recreates the table
+4. Always backup the database before any manual intervention
+
+## Recovery If Something Goes Wrong
+
+```bash
+# Restore from backup
+mv /path/to/starpunk.db /path/to/starpunk.db.failed
+cp /path/to/starpunk.db.backup /path/to/starpunk.db
+
+# Revert to v0.9.5
+docker pull ghcr.io/ai-christianson/starpunk:v0.9.5
+docker run [...] ghcr.io/ai-christianson/starpunk:v0.9.5
+```
+
+## Long-term Solution
+
+A proper architectural fix is being implemented for v1.1.0. See:
+- ADR-031: Database Migration System Redesign
+- Migration failure diagnosis report
+
+## Contact
+
+If you encounter issues with this hotfix, check:
+- `/docs/reports/migration-failure-diagnosis-v1.0.0-rc.1.md`
+- `/docs/decisions/ADR-031-database-migration-system-redesign.md`