# struere doctor

> Run diagnostic checks on your Struere project

The `doctor` command runs a suite of diagnostic checks against your project and environment, surfacing configuration issues, stuck threads, unhealthy triggers, and sync drift.

## Usage

```bash
bunx struere doctor
bunx struere doctor --env production
bunx struere doctor --json
```

## Flags

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output results as JSON |

## Checks

The doctor runs 7 diagnostic checks:

| Check | What it does |
|-------|-------------|
| WhatsApp connection | Checks if any agents use WhatsApp tools and verifies a connection exists |
| Template approvals | Checks if any agents use template tools and verifies templates are approved |
| Entity type references | Validates that all trigger entity type references exist locally |
| Model config | Validates agent model configurations: temperature (0-2) and maxTokens (>0) |
| Stuck threads | Detects threads with >500 messages or empty agent responses |
| Trigger health | Computes per-trigger failure rates. Warns above 20%, errors above 50% |
| Sync drift | Compares local resource definitions against remote state |

## Output

Each check displays a colored status icon:

| Icon | Meaning |
|------|---------|
| `●` (green) | Passed |
| `●` (yellow) | Warning |
| `✖` (red) | Error |

The command exits with code `1` if any checks report an error.

## Example Output

```
Struere Doctor  (development)

  ● WhatsApp connection      No WhatsApp tools used
  ● Template approvals       No template tools used
  ● Entity type references   All triggers reference valid types
  ● Model config             All agent model configs valid
  ● Stuck threads            No stuck threads detected
  ✖ Trigger health           "my-trigger" 57% failure rate
  ● Sync drift               Local and remote are in sync

  Summary: 6 passed, 1 error
```

## JSON Output

Use `--json` for machine-readable output:

```bash
bunx struere doctor --json
```

Returns a JSON object with an array of check results, each containing `name`, `status` (`pass`, `warn`, or `error`), and `message`.

```json
{
  "environment": "development",
  "checks": [
    { "name": "WhatsApp connection", "status": "pass", "message": "No WhatsApp tools used" },
    { "name": "Template approvals", "status": "pass", "message": "No template tools used" },
    { "name": "Entity type references", "status": "pass", "message": "All triggers reference valid types" },
    { "name": "Model config", "status": "pass", "message": "All agent model configs valid" },
    { "name": "Stuck threads", "status": "pass", "message": "No stuck threads detected" },
    { "name": "Trigger health", "status": "error", "message": "\"my-trigger\" 57% failure rate" },
    { "name": "Sync drift", "status": "pass", "message": "Local and remote are in sync" }
  ],
  "summary": { "passed": 6, "warnings": 0, "errors": 1 }
}
```

## When to Use Doctor

- **Before deploying** -- Catch configuration issues before they hit production
- **After setting up integrations** -- Verify WhatsApp connections and template approvals
- **Debugging trigger failures** -- Identify triggers with high failure rates
- **Routine health checks** -- Run periodically to detect sync drift or stuck threads