Begin planning phase 3-5 implementation

.beads/last-touched

@@ -1 +1 @@
-bd-2um
+bd-lcb

AGENTS.md

@@ -17,153 +17,11 @@ Build extensible pieces of logic that can easily be integrated with other pieces
 DRY principles should be loosely held.
 Architecture MUST be clear and well thought-out. Ask the user for clarification whenever ambiguity is discovered around architecture, or you think a better approach than planned exists.
 
-## Beads Rust Workflow Integration
-
-This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in git.
-
-### Essential Commands
-
-```bash
-# View issues (launches TUI - NOT FOR AGENT USE, human only)
-bv
-
-# CLI commands for agents (use --json for machine-readable output)
-br ready --json       # Show issues ready to work (no blockers)
-br list --status=open --json # All open issues
-br show <id> --json   # Full issue details with dependencies
-br create --title="..." --type=task --priority=2
-br update <id> --status=in_progress
-br close <id> --reason="Completed"
-br close <id1> <id2>  # Close multiple issues at once
-br sync               # Commit and push changes
-```
-
-### Robot Mode (Agent-Optimized bv Commands)
-
-Use `bv --robot-*` flags for structured JSON output optimized for AI agents:
-
-```bash
-# Essential robot commands
-bv --robot-triage     # THE MEGA-COMMAND: unified analysis, recommendations, health
-bv --robot-next       # Single top recommendation (minimal output)
-bv --robot-plan       # Dependency-respecting execution plan
-bv --robot-priority   # Priority recommendations with reasoning
-bv --robot-insights   # Deep graph analysis (PageRank, bottlenecks, etc.)
-
-# File impact analysis (check before editing)
-bv --robot-impact <file>           # Risk assessment for modifying files
-bv --robot-file-beads <path>       # What beads have touched this file?
-bv --robot-file-hotspots           # High-churn files (conflict zones)
-bv --robot-related <bead-id>       # Find related beads
-
-# Filtering options (work with most robot commands)
-bv --robot-triage --robot-by-label=backend
-bv --robot-priority --robot-min-confidence=0.7
-bv --robot-insights --label=api    # Scope to label subgraph
-```
-
-Run `bv -robot-help` for complete robot mode documentation.
-
-### Workflow Pattern
-
-1. **Start**: Run `br ready` to find actionable work
-2. **Claim**: Use `br update <id> --status=in_progress`
-3. **Work**: Implement the task
-4. **Complete**: Use `br close <id>`
-5. **Sync**: Always run `br sync` at session end
-
-### Key Concepts
-
-- **Dependencies**: Issues can block other issues. `br ready` shows only unblocked work.
-- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers, not words)
-- **Types**: task, bug, feature, epic, question, docs
-- **Blocking**: `br dep add <issue> <depends-on>` to add dependencies
-
-### Session Protocol
-
-**Before ending any session, run this checklist:**
-
-```bash
-git status              # Check what changed
-git add <files>         # Stage code changes
-br sync                 # Commit beads changes
-git commit -m "..."     # Commit code
-br sync                 # Commit any new beads changes
-git push                # Push to remote
-```
-
-### Best Practices
-
-- Check `br ready` at session start to find available work
-- Update status as you work (in_progress → closed)
-- Create new issues with `br create` when you discover tasks
-- Use descriptive titles and set appropriate priority/type
-- Always `br sync` before ending session
-
-<!-- end-br-agent-instructions -->
-
-<!-- bv-agent-instructions-v1 -->
-
 ---
 
-## Beads Workflow Integration
+## Third-Party Library Usage
 
-This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in git.
+If you aren't 100% sure how to use a third-party library, **SEARCH ONLINE** to find the latest documentation and mid-2025 best practices.
-
-### Essential Commands
-
-```bash
-# View issues (launches TUI - avoid in automated sessions)
-bv
-
-# CLI commands for agents (use these instead)
-bd ready              # Show issues ready to work (no blockers)
-bd list --status=open # All open issues
-bd show <id>          # Full issue details with dependencies
-bd create --title="..." --type=task --priority=2
-bd update <id> --status=in_progress
-bd close <id> --reason="Completed"
-bd close <id1> <id2>  # Close multiple issues at once
-bd sync               # Commit and push changes
-```
-
-### Workflow Pattern
-
-1. **Start**: Run `bd ready` to find actionable work
-2. **Claim**: Use `bd update <id> --status=in_progress`
-3. **Work**: Implement the task
-4. **Complete**: Use `bd close <id>`
-5. **Sync**: Always run `bd sync` at session end
-
-### Key Concepts
-
-- **Dependencies**: Issues can block other issues. `bd ready` shows only unblocked work.
-- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers, not words)
-- **Types**: task, bug, feature, epic, question, docs
-- **Blocking**: `bd dep add <issue> <depends-on>` to add dependencies
-
-### Session Protocol
-
-**Before ending any session, run this checklist:**
-
-```bash
-git status              # Check what changed
-git add <files>         # Stage code changes
-bd sync                 # Commit beads changes
-git commit -m "..."     # Commit code
-bd sync                 # Commit any new beads changes
-git push                # Push to remote
-```
-
-### Best Practices
-
-- Check `bd ready` at session start to find available work
-- Update status as you work (in_progress → closed)
-- Create new issues with `bd create` when you discover tasks
-- Use descriptive titles and set appropriate priority/type
-- Always `bd sync` before ending session
-
-<!-- end-bv-agent-instructions -->
 
 ---
 

docs/robot-mode-design.md

@@ -0,0 +1,239 @@
+# Robot Mode Design
+
+## Overview
+
+Robot mode optimizes the `gi` CLI for AI agent consumption with structured JSON output, meaningful exit codes, and token-efficient responses.
+
+## Activation
+
+```bash
+# Explicit flag
+gi --robot list issues
+
+# Auto-detection (when stdout is not a TTY)
+gi list issues | jq .
+
+# Environment variable
+GI_ROBOT=1 gi list issues
+```
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--robot` | Force JSON output, structured errors |
+| `--quiet` | Suppress progress/spinners (implied by --robot) |
+
+## Exit Codes
+
+| Code | ErrorCode | Meaning |
+|------|-----------|---------|
+| 0 | - | Success |
+| 1 | INTERNAL_ERROR | Unknown/internal error |
+| 2 | CONFIG_NOT_FOUND | Config file missing |
+| 3 | CONFIG_INVALID | Config file malformed |
+| 4 | TOKEN_NOT_SET | GitLab token not configured |
+| 5 | GITLAB_AUTH_FAILED | Authentication failed |
+| 6 | GITLAB_NOT_FOUND | Resource not found |
+| 7 | GITLAB_RATE_LIMITED | Rate limited |
+| 8 | GITLAB_NETWORK_ERROR | Network/connection error |
+| 9 | DB_LOCKED | Database locked by another process |
+| 10 | DB_ERROR | Database error |
+| 11 | MIGRATION_FAILED | Migration failed |
+| 12 | IO_ERROR | File I/O error |
+| 13 | TRANSFORM_ERROR | Data transformation error |
+
+## Error Output Format
+
+When `--robot` is active, errors are JSON on stderr:
+
+```json
+{
+  "error": {
+    "code": "CONFIG_NOT_FOUND",
+    "message": "Config file not found at ~/.config/gi/config.toml",
+    "suggestion": "Run 'gi init' to create configuration"
+  }
+}
+```
+
+## Success Output Format
+
+All commands return consistent JSON structure:
+
+```json
+{
+  "ok": true,
+  "data": { ... },
+  "meta": {
+    "count": 50,
+    "total": 1234,
+    "elapsed_ms": 45
+  }
+}
+```
+
+## Command-Specific Output
+
+### gi list issues --robot
+
+```json
+{
+  "ok": true,
+  "data": {
+    "issues": [
+      {
+        "iid": 123,
+        "project": "group/project",
+        "title": "Bug in login",
+        "state": "opened",
+        "author": "username",
+        "assignees": ["user1"],
+        "labels": ["bug", "priority::high"],
+        "discussions": { "total": 5, "unresolved": 2 },
+        "updated_at": "2024-01-15T10:30:00Z",
+        "web_url": "https://..."
+      }
+    ]
+  },
+  "meta": { "showing": 50, "total": 234 }
+}
+```
+
+### gi show issue 123 --robot
+
+```json
+{
+  "ok": true,
+  "data": {
+    "issue": {
+      "iid": 123,
+      "project": "group/project",
+      "title": "Bug in login",
+      "description": "Full markdown...",
+      "state": "opened",
+      "author": "username",
+      "created_at": "2024-01-10T08:00:00Z",
+      "updated_at": "2024-01-15T10:30:00Z",
+      "discussions": [
+        {
+          "id": "abc123",
+          "resolved": false,
+          "notes": [
+            {
+              "author": "user1",
+              "body": "Comment text...",
+              "created_at": "2024-01-11T09:00:00Z",
+              "system": false
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+### gi ingest --type issues --robot
+
+```json
+{
+  "ok": true,
+  "data": {
+    "resource_type": "issues",
+    "projects": [
+      {
+        "path": "group/project",
+        "issues_synced": 45,
+        "discussions_synced": 123
+      }
+    ],
+    "totals": {
+      "issues": 45,
+      "discussions": 123
+    }
+  },
+  "meta": { "elapsed_ms": 3400 }
+}
+```
+
+### gi count issues --robot
+
+```json
+{
+  "ok": true,
+  "data": {
+    "entity": "issues",
+    "count": 1234,
+    "breakdown": {
+      "opened": 456,
+      "closed": 778
+    }
+  }
+}
+```
+
+### gi doctor --robot
+
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true,
+    "checks": {
+      "config": { "status": "ok", "path": "~/.config/gi/config.toml" },
+      "database": { "status": "ok", "version": 6 },
+      "gitlab": { "status": "ok", "user": "username" },
+      "projects": [
+        { "path": "group/project", "status": "ok" }
+      ]
+    }
+  }
+}
+```
+
+### gi sync-status --robot
+
+```json
+{
+  "ok": true,
+  "data": {
+    "last_sync": {
+      "status": "completed",
+      "resource_type": "issues",
+      "started_at": "2024-01-15T10:00:00Z",
+      "completed_at": "2024-01-15T10:00:45Z",
+      "duration_ms": 45000
+    },
+    "cursors": [
+      {
+        "project": "group/project",
+        "resource_type": "issues",
+        "cursor": "2024-01-15T10:00:00Z"
+      }
+    ]
+  }
+}
+```
+
+## Implementation Plan
+
+### Phase 1: Core Infrastructure
+1. Add `--robot` global flag to Cli struct
+2. Create `RobotOutput` trait for consistent JSON serialization
+3. Add exit code mapping from ErrorCode
+4. Implement TTY detection with `atty` crate
+
+### Phase 2: Command Updates
+1. Update all commands to check robot mode
+2. Add JSON output variants for commands missing them (count, ingest, sync-status)
+3. Suppress progress bars in robot mode
+
+### Phase 3: Error Handling
+1. Update main.rs error handler for robot mode
+2. Add suggestion field to GiError variants
+3. Emit structured JSON errors to stderr
+
+### Phase 4: Documentation
+1. Update AGENTS.md with robot mode commands
+2. Add --robot examples to help text