# State File Schemas

This document defines the JSON schemas for all state files in `~/.claude/state/`.

## Personal Assistant State

### session-context.json

Path: `~/.claude/state/personal-assistant/session-context.json`
Writer: user/CLI
Purpose: Session-level context override (ephemeral)

```json
{
  "version": "1.0",
  "current_context_level": "minimal" | "moderate" | "comprehensive" | "none" | null,
  "set_at": "ISO8601 timestamp" | null,
  "set_by": "user" | null
}
```

| Field | Type | Description |
|-------|------|-------------|
| `version` | string | Schema version |
| `current_context_level` | string\|null | Active context level, null if unset |
| `set_at` | string\|null | When the override was set |
| `set_by` | string\|null | Who set it (always "user") |

### general-instructions.json

Path: `~/.claude/state/personal-assistant/general-instructions.json`
Writer: personal-assistant
Purpose: User memory/instructions optimized for agent consumption

```json
{
  "version": "1.0",
  "description": "User instructions optimized for agent consumption",
  "items": [
    {
      "id": "uuid",
      "text": "Instruction text",
      "scope": "global",
      "tags": ["tag1", "tag2"],
      "created": "ISO8601 timestamp",
      "status": "active" | "deprecated"
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `version` | string | Schema version |
| `description` | string | File description |
| `items` | array | List of instruction items |
| `items[].id` | string | UUID for the item |
| `items[].text` | string | The instruction text |
| `items[].scope` | string | Scope of instruction (e.g., "global") |
| `items[].tags` | array | Optional categorization tags |
| `items[].created` | string | ISO8601 creation timestamp |
| `items[].status` | string | "active" or "deprecated" (soft delete) |

Notes:
- Items are append-only; use `status: "deprecated"` for soft delete
- PA generates UUIDs for new items
- Never remove items from the array

### personal-assistant-preferences.json

Path: `~/.claude/state/personal-assistant-preferences.json`
Writer: master-orchestrator
Purpose: Persistent PA configuration

```json
{
  "version": "1.0",
  "description": "Persistent PA configuration",
  "context_gathering": {
    "default_level": "moderate"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `version` | string | Schema version |
| `description` | string | File description |
| `context_gathering.default_level` | string | Default context level |

Valid context levels: `none`, `minimal`, `moderate`, `comprehensive`

## Knowledge Base State

### kb.json (Shared)

Path: `~/.claude/state/kb.json`
Writer: personal-assistant
Purpose: Shared knowledge base for infrastructure facts (all agents can read)

```json
{"infra":{},"svc":{},"net":{},"hw":{}}
```

| Category | Purpose | Example facts |
|----------|---------|---------------|
| `infra` | Cluster/platform | cluster type, node count, architecture |
| `svc` | Services/tools | gitops, monitoring, alerting |
| `net` | Network | domain, ingress controller, DNS |
| `hw` | Hardware | device models, RAM, storage |

Notes:
- Values should be primitives (string, number, boolean) or flat arrays
- Avoid nested objects beyond category level
- All state JSON files use minified format (single-line)

### kb.json (PA-Private)

Path: `~/.claude/state/personal-assistant/kb.json`
Writer: personal-assistant
Purpose: PA-private knowledge base for personal/non-tech facts

Same format as shared KB. Categories TBD based on use cases.

## System State

### system-instructions.json

Path: `~/.claude/state/system-instructions.json`
Writer: master-orchestrator
Purpose: Central process definitions

See `system-instructions.json` for current schema.

### future-considerations.json

Path: `~/.claude/state/future-considerations.json`
Writer: master-orchestrator
Purpose: Deferred features and decisions

See `future-considerations.json` for current schema.

### model-policy.json

Path: `~/.claude/state/model-policy.json`
Writer: master-orchestrator
Purpose: Model selection rules

See `model-policy.json` for current schema.

### autonomy-levels.json

Path: `~/.claude/state/autonomy-levels.json`
Writer: master-orchestrator
Purpose: Autonomy level definitions

See `autonomy-levels.json` for current schema.

## Sysadmin State

### session-autonomy.json

Path: `~/.claude/state/sysadmin/session-autonomy.json`
Writer: user/CLI
Purpose: Per-session autonomy overrides

See `session-autonomy.json` for current schema.