gitlore/docs/robot-mode-design.md

# 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