# Grid Configuration Schema

Complete reference for `.grid/config.json` - the master configuration file for all Grid settings.

---

## MASTER CONFIG STRUCTURE

```json
{
  "version": "1.7.x",
  "initialized": "2026-01-23T10:00:00Z",

  "model_tier": "quality",

  "git": {
    "auto_branch": true,
    "branch_prefix": "grid/",
    "auto_push": "wave",
    "auto_pr": true,
    "protected_branches": ["main", "master", "production"],
    "default_base": "main",
    "sync_strategy": "merge",
    "commit_signing": false,
    "wip_commits": true
  },

  "budget": {
    "enabled": true,
    "budget_limit": null,
    "currency": "USD",
    "enforcement": "hard",
    "warning_threshold": 0.75,
    "confirmation_threshold": 0.90
  },

  "daemon": {
    "default_mode": "autopilot",
    "max_runtime_hours": 24,
    "checkpoint_on_wave_complete": true,
    "heartbeat_interval_seconds": 30,
    "stall_threshold_minutes": 30,

    "notifications": {
      "system": true,
      "sound": true,
      "webhook": null
    },

    "notify_on": {
      "start": false,
      "checkpoint": true,
      "complete": true,
      "error": true,
      "stall": true
    },

    "cleanup": {
      "auto_clean_completed_days": 7,
      "keep_audit_logs": true
    }
  },

  "verification": {
    "auto_verify": true,
    "wave_level": true,
    "skip_for_types": []
  },

  "refinement": {
    "auto_refine": true,
    "skip_backend_only": true,
    "persona_count": 3,
    "parallel_execution": true
  },

  "research": {
    "auto_research": true,
    "cache_duration_hours": 24,
    "parallel_searches": true,
    "max_sources_per_query": 10
  },

  "scout": {
    "auto_scout": true,
    "timeout_seconds": 120,
    "max_file_scan": 100,
    "max_depth": 4
  },

  "scratchpad": {
    "mandatory": true,
    "archive_on_wave_complete": true,
    "max_entries_before_archive": 100
  },

  "learnings": {
    "auto_capture": true,
    "load_on_startup": true
  },

  "debug": {
    "persist_sessions": true,
    "max_session_age_days": 30
  },

  "auto_update": {
    "enabled": true,
    "on_build_complete": true,
    "on_manual_trigger": true
  },

  "ui": {
    "progress_updates": "live",
    "emoji": false,
    "color": true,
    "verbose": false
  }
}
```

---

## FIELD REFERENCE

### Top Level

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `version` | string | "1.7.x" | Grid version |
| `initialized` | ISO timestamp | (auto) | When config was created |
| `model_tier` | enum | "quality" | Default model tier: quality/balanced/budget |

---

### Git Section

Controls git operations and branch management.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_branch` | boolean | true | Auto-create feature branches |
| `branch_prefix` | string | "grid/" | Prefix for Grid branches |
| `auto_push` | enum | "wave" | Push timing: wave/block/manual/immediate |
| `auto_pr` | boolean | true | Offer PR creation on completion |
| `protected_branches` | array | ["main",...] | Branches that require PRs |
| `default_base` | string | "main" | Default base branch for PRs |
| `sync_strategy` | enum | "merge" | How to sync: merge/rebase |
| `commit_signing` | boolean | false | GPG sign commits |
| `wip_commits` | boolean | true | Allow WIP commits for long sessions |

**Auto Push Modes:**
- `wave` - Push after each wave completes (default)
- `block` - Push after each block completes
- `manual` - Never auto-push
- `immediate` - Push after every commit

**Sync Strategy:**
- `merge` - git merge origin/main
- `rebase` - git rebase origin/main

---

### Budget Section

Controls cost tracking and spending limits.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | true | Enable budget tracking |
| `budget_limit` | number\|null | null | Max spending (null = unlimited) |
| `currency` | string | "USD" | Currency for display |
| `enforcement` | enum | "hard" | hard=block, soft=warn only |
| `warning_threshold` | number | 0.75 | Warn at 75% usage |
| `confirmation_threshold` | number | 0.90 | Require confirmation at 90% |

**Enforcement Modes:**
- `hard` - Block spawns when budget exceeded
- `soft` - Warn but allow spawns

**Thresholds:**
- 0.0-0.75: Normal operation
- 0.75-0.90: Display warnings
- 0.90-1.0: Require confirmation before spawn
- 1.0+: Block spawns (if hard enforcement)

---

### Daemon Section

Controls background execution mode.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `default_mode` | enum | "autopilot" | Default execution mode |
| `max_runtime_hours` | number | 24 | Max daemon runtime |
| `checkpoint_on_wave_complete` | boolean | true | Checkpoint after each wave |
| `heartbeat_interval_seconds` | number | 30 | Heartbeat frequency |
| `stall_threshold_minutes` | number | 30 | Alert if no heartbeat |

**Notifications:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `system` | boolean | true | System notifications |
| `sound` | boolean | true | Play sound alerts |
| `webhook` | string\|null | null | Webhook URL for notifications |

**Notify On:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `start` | boolean | false | Notify on daemon start |
| `checkpoint` | boolean | true | Notify on checkpoints |
| `complete` | boolean | true | Notify on completion |
| `error` | boolean | true | Notify on errors |
| `stall` | boolean | true | Notify on stalls |

**Cleanup:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_clean_completed_days` | number | 7 | Delete completed daemons after N days |
| `keep_audit_logs` | boolean | true | Keep audit logs even after cleanup |

---

### Verification Section

Controls automatic verification behavior.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_verify` | boolean | true | Auto-spawn Recognizer after SUCCESS |
| `wave_level` | boolean | true | Verify at wave level (vs block level) |
| `skip_for_types` | array | [] | Block types to skip verification |

**Example skip types:**
```json
{
  "skip_for_types": ["prototype", "throwaway", "spike"]
}
```

---

### Refinement Section

Controls refinement swarm behavior.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_refine` | boolean | true | Auto-run refinement after building |
| `skip_backend_only` | boolean | true | Skip refinement for backend-only changes |
| `persona_count` | number | 3 | Number of personas to simulate |
| `parallel_execution` | boolean | true | Run refinement agents in parallel |

---

### Research Section

Controls external research behavior.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_research` | boolean | true | Auto-research unfamiliar tech |
| `cache_duration_hours` | number | 24 | How long to cache research |
| `parallel_searches` | boolean | true | Execute searches in parallel |
| `max_sources_per_query` | number | 10 | Max sources to analyze per query |

---

### Scout Section

Controls codebase reconnaissance behavior.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_scout` | boolean | true | Auto-scout existing codebases |
| `timeout_seconds` | number | 120 | Max scout duration (2 minutes) |
| `max_file_scan` | number | 100 | Max files to scan per type |
| `max_depth` | number | 4 | Max directory depth to scan |

---

### Scratchpad Section

Controls live observability during execution.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mandatory` | boolean | true | Programs MUST write to scratchpad |
| `archive_on_wave_complete` | boolean | true | Archive after each wave |
| `max_entries_before_archive` | number | 100 | Archive threshold |

---

### Learnings Section

Controls institutional memory capture.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_capture` | boolean | true | Capture learnings after completion |
| `load_on_startup` | boolean | true | Load learnings at session start |

---

### Debug Section

Controls debug session persistence.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `persist_sessions` | boolean | true | Keep debug sessions in .grid/debug/ |
| `max_session_age_days` | number | 30 | Delete sessions older than N days |

---

### Auto-Update Section

Controls automatic npm publishing after builds.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | true | Enable auto-update capability |
| `on_build_complete` | boolean | true | Auto-update after successful builds |
| `on_manual_trigger` | boolean | true | Allow manual "update" trigger |

**When Auto-Update Triggers:**
- Build completes successfully (Recognizer verified)
- Changes exist in Grid repo
- Config allows: `enabled: true` AND `on_build_complete: true`
- NOT in daemon mode

**Disabling Auto-Update:**
```json
{
  "auto_update": {
    "enabled": false
  }
}
```

**Note:** Auto-update is for The Grid itself (publishing to npm). This only applies when working in the Grid repo (`/Users/jacweath/grid`).

---

### UI Section

Controls output formatting and display.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `progress_updates` | enum | "live" | Update frequency: live/wave/block/silent |
| `emoji` | boolean | false | Use emoji in output |
| `color` | boolean | true | Use ANSI colors |
| `verbose` | boolean | false | Show detailed internal operations |

**Progress Update Modes:**
- `live` - Show real-time scratchpad updates
- `wave` - Update after each wave
- `block` - Update after each block
- `silent` - No progress updates (status on demand only)

---

## CONFIGURATION COMMANDS

### Initialize Default Config

```bash
/grid:init
```

Creates `.grid/config.json` with defaults.

### Update Config

```bash
/grid:model quality          # Set model tier
/grid:budget set $50         # Set budget limit
/grid:branch --auto-push=block  # Change push timing
```

### View Current Config

```bash
/grid:status --config
```

---

## CONFIGURATION OVERRIDES

### Environment Variables

Environment variables override config file:

```bash
GRID_MODEL_TIER=balanced
GRID_GIT_AUTO_PUSH=manual
GRID_BUDGET_LIMIT=100
GRID_DEBUG_VERBOSE=true
```

### Per-Session Overrides

Specify at invocation:

```bash
/grid --no-verify "build feature"
/grid --budget-check=false "quick fix"
/grid --model=sonnet "simple task"
```

---

## MIGRATION

### From Older Versions

If config is missing fields, defaults are used. Run:

```bash
/grid:init --merge
```

Merges new defaults with existing config without overwriting.

---

## VALIDATION

Config is validated on load. Invalid configs show:

```
CONFIG ERROR
============

Invalid config: .grid/config.json

Issues:
- model_tier must be one of: quality, balanced, budget
- budget.budget_limit must be number or null
- git.auto_push must be one of: wave, block, manual, immediate

Fix the config or run /grid:init --reset to restore defaults.
```

---

## EXAMPLES

### Budget-Conscious Setup

```json
{
  "model_tier": "balanced",
  "budget": {
    "enabled": true,
    "budget_limit": 25.00,
    "enforcement": "hard"
  },
  "verification": {
    "auto_verify": false
  },
  "refinement": {
    "auto_refine": false
  }
}
```

### Team Collaboration Setup

```json
{
  "git": {
    "auto_branch": true,
    "auto_push": "wave",
    "auto_pr": true,
    "commit_signing": true
  },
  "daemon": {
    "notifications": {
      "webhook": "https://hooks.slack.com/services/..."
    }
  }
}
```

### Fast Iteration Setup

```json
{
  "model_tier": "quality",
  "verification": {
    "auto_verify": true
  },
  "refinement": {
    "auto_refine": false
  },
  "research": {
    "auto_research": false
  },
  "git": {
    "auto_push": "immediate"
  }
}
```

---

End of Line.