jackschultz · jackschultz · Jan 19, 2026 · Jan 19, 2026 · Jan 19, 2026 · Jan 19, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,39 @@
 
 ## Unreleased
 
+**Phase 2a: Fix Commands**
+
+Complete the diagnose→fix→verify loop with safe remediation commands.
+
+### New Commands
+
+- **`pgcrate vacuum`**: Table bloat and vacuum health diagnostic
+- **`pgcrate fix sequence`**: Upgrade sequence types (smallint→integer→bigint) to prevent exhaustion
+- **`pgcrate fix index --drop`**: Safely drop unused/duplicate indexes with `DROP INDEX CONCURRENTLY`
+- **`pgcrate fix vacuum`**: Run VACUUM on tables (regular, freeze, full, analyze)
+
+### Fix Command Features
+
+- **Gate system**: `--read-write`, `--primary`, `--yes` flags required based on operation risk
+- **Dry-run mode**: All fix commands support `--dry-run` to preview SQL
+- **SQL preview**: Fix actions include exact SQL that will be executed
+- **Evidence collection**: Detailed context about the issue being fixed
+- **Safety checks**: Block dangerous operations (e.g., cannot drop primary key index)
+- **Verification**: `--verify` flag runs post-fix validation
+
+### Triage Enhancements
+
+- **`--include-fixes` flag**: Returns structured fix actions for detected issues
+- **StructuredAction format**: Each action includes command, args, risk level, gates, evidence, and verify steps
+
+### Index Evidence Improvements
+
+- Added `stats_since` and `stats_age_days` for confidence in usage statistics
+- Added `backing_constraint` field for indexes backing constraints
+- Added `is_replica_identity` field for logical replication safety
+
+---
+
 **Phase 1: JSON Contracts Foundation**
 
 ### Breaking Changes

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -15,7 +15,7 @@ exclude = ["target/", "website/"]
 bytes = "1"
 clap = { version = "4", features = ["derive"] }
 dialoguer = "0.11"
-tokio-postgres = "0.7"
+tokio-postgres = { version = "0.7", features = ["with-chrono-0_4"] }
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "process", "time", "signal"] }
 colored = "2"
 chrono = { version = "0.4", features = ["serde"] }

diff --git a/README.md b/README.md
@@ -135,20 +135,56 @@ Agent-friendly health checks with JSON output for automation:
 
 ```bash
 pgcrate triage                        # Quick health overview (locks, xid, sequences)
-pgcrate triage --json                 # Machine-readable JSON output
+pgcrate triage --include-fixes --json # Include recommended fix actions
 pgcrate context --json                # Connection context, server info, privileges
 pgcrate capabilities --json           # What can this connection do?
 pgcrate locks                         # Blocking locks and long transactions
 pgcrate xid                           # Transaction ID wraparound analysis
 pgcrate sequences                     # Sequence exhaustion check
 pgcrate indexes                       # Missing, unused, duplicate indexes
+pgcrate vacuum                        # Table bloat and vacuum health
 ```
 
 All diagnostic commands support timeout flags for production safety:
 - `--connect-timeout <ms>` - Connection timeout (default: 5000ms)
 - `--statement-timeout <ms>` - Query timeout (default: 30000ms)
 - `--lock-timeout <ms>` - Lock wait timeout (default: 500ms)
 
+### Fix Commands
+
+Safe remediation for issues found by diagnostics:
+
+```bash
+# Sequence fixes (prevent exhaustion)
+pgcrate fix sequence public.order_seq --upgrade-to bigint --dry-run
+pgcrate fix sequence public.order_seq --upgrade-to bigint --yes
+
+# Index fixes (remove unused indexes)
+pgcrate fix index --drop public.idx_unused --dry-run
+pgcrate fix index --drop public.idx_unused --yes
+
+# Vacuum fixes (reclaim space)
+pgcrate fix vacuum public.orders --dry-run
+pgcrate fix vacuum public.orders --yes
+pgcrate fix vacuum public.orders --full --yes    # ACCESS EXCLUSIVE lock
+pgcrate fix vacuum public.orders --analyze --yes # Update statistics
+```
+
+**Gate flags required for fix commands:**
+- `--read-write` - Required for all fix operations
+- `--primary` - Required for database-modifying operations
+- `--yes` - Required for medium/high risk operations
+
+**Risk levels:**
+- **Low:** `ALTER SEQUENCE`, regular `VACUUM`
+- **Medium:** `DROP INDEX CONCURRENTLY` (requires `--yes`)
+- **High:** `VACUUM FULL` (requires `--yes`, takes exclusive lock)
+
+Fix commands include evidence collection, safety checks, and optional verification:
+```bash
+pgcrate --read-write --primary fix sequence public.order_seq --upgrade-to bigint --yes --verify
+```
+
 ### Data Operations
 
 ```bash
@@ -272,6 +308,10 @@ DROP TABLE users;
 | `pgcrate xid` | Transaction ID wraparound analysis |
 | `pgcrate sequences` | Sequence exhaustion check |
 | `pgcrate indexes` | Missing, unused, duplicate indexes |
+| `pgcrate vacuum` | Table bloat and vacuum health |
+| `pgcrate fix sequence` | Upgrade sequence type to prevent exhaustion |
+| `pgcrate fix index` | Drop unused/duplicate indexes |
+| `pgcrate fix vacuum` | Run VACUUM on tables |
 | `pgcrate doctor` | Run health checks |
 | `pgcrate bootstrap` | Setup environment with anonymized data from source |
 | `pgcrate snapshot <cmd>` | Save (with profiles), restore, list, or delete snapshots |

diff --git a/llms.txt b/llms.txt
@@ -736,6 +736,75 @@ CREATE TABLE IF NOT EXISTS pgcrate.schema_migrations (
 - **Schema versioning**: Table is created with IF NOT EXISTS for compatibility
 - **Timestamps**: Uses TIMESTAMPTZ with UTC for consistency
 
+## DIAGNOSTICS
+
+### Health Check Commands
+
+```bash
+# Quick triage (locks, xid, sequences)
+pgcrate triage
+pgcrate triage --json
+pgcrate triage --include-fixes --json  # Include recommended fix actions
+
+# Individual diagnostics
+pgcrate locks                    # Blocking locks and long transactions
+pgcrate xid                      # Transaction ID wraparound analysis
+pgcrate sequences                # Sequence exhaustion check
+pgcrate indexes                  # Missing, unused, duplicate indexes
+pgcrate vacuum                   # Table bloat and vacuum health
+
+# Connection context
+pgcrate context --json           # Connection info, server version, privileges
+pgcrate capabilities --json      # What can this connection do?
+```
+
+**Timeout Flags (for production safety):**
+- `--connect-timeout <ms>` - Connection timeout (default: 5000ms)
+- `--statement-timeout <ms>` - Query timeout (default: 30000ms)
+- `--lock-timeout <ms>` - Lock wait timeout (default: 500ms)
+
+**Exit Codes:**
+- `0` = healthy
+- `1` = warning
+- `2` = critical
+- `10+` = operational failure
+
+### Fix Commands
+
+Safe remediation for issues found by diagnostics:
+
+```bash
+# Sequence fixes (prevent exhaustion)
+pgcrate --read-write --primary fix sequence public.order_seq --upgrade-to bigint --dry-run
+pgcrate --read-write --primary fix sequence public.order_seq --upgrade-to bigint --yes
+
+# Index fixes (remove unused indexes)
+pgcrate --read-write --primary fix index --drop public.idx_unused --dry-run
+pgcrate --read-write --primary fix index --drop public.idx_unused --yes
+
+# Vacuum fixes (reclaim space)
+pgcrate --read-write --primary fix vacuum public.orders --dry-run
+pgcrate --read-write --primary fix vacuum public.orders --yes
+pgcrate --read-write --primary fix vacuum public.orders --full --yes    # ACCESS EXCLUSIVE lock
+pgcrate --read-write --primary fix vacuum public.orders --analyze --yes # Update statistics
+```
+
+**Gate Flags (required for fix operations):**
+- `--read-write` - Required for all fix operations
+- `--primary` - Required for database-modifying operations
+- `--yes` - Required for medium/high risk operations
+
+**Risk Levels:**
+- **Low:** `ALTER SEQUENCE`, regular `VACUUM`
+- **Medium:** `DROP INDEX CONCURRENTLY` (requires `--yes`)
+- **High:** `VACUUM FULL` (requires `--yes`, takes exclusive lock)
+
+**Verification:**
+```bash
+# Run post-fix verification
+pgcrate --read-write --primary fix sequence public.order_seq --upgrade-to bigint --yes --verify
+```
+
 ## GLOBAL FLAGS
 
 - `-d, --database-url <URL>`: Override database connection
@@ -760,6 +829,17 @@ Currently, `--json` is supported for these commands:
 - `snapshot info` - Snapshot details
 - `sql` - SQL query results
 - `status` - Migration status (alias for `migrate status`)
+- `triage` - Health overview with actions
+- `context` - Connection context and server info
+- `capabilities` - Permission discovery
+- `locks` - Blocking locks and transactions
+- `xid` - Transaction ID wraparound
+- `sequences` - Sequence exhaustion check
+- `indexes` - Index health analysis
+- `vacuum` - Table bloat analysis
+- `fix sequence` - Sequence upgrade result
+- `fix index` - Index drop result
+- `fix vacuum` - Vacuum result
 
 For unsupported commands, `--json` returns a JSON error: `"--json not supported for '<cmd>' yet"`.