> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedino.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Shadow Mode

> Dino's graduated autonomy system earns trust by observing, then progressively hands off more control.

# Shadow Mode

Most API quality approaches start at maximum noise. Dino does the opposite.

Shadow Mode lets Dino earn your trust gradually. Start by watching silently. As confidence grows, increase autonomy.

## The four levels

| Level | Name        | What Dino does                                      | Config                    |
| ----- | ----------- | --------------------------------------------------- | ------------------------- |
| L1    | **Observe** | Watches silently, builds baseline, reports findings | `autonomy.level: observe` |
| L2    | **Suggest** | Ranked findings with confidence scores              | Planned (post–M1.5 REST)  |
| L3    | **Write**   | Creates PRs with human approval                     | Planned (post-M2)         |
| L4    | **Enforce** | Blocks CI on violations                             | `autonomy.level: enforce` |

Today, Dino ships with **Observe** and **Enforce**. **REST (OpenAPI) shipped in M1.5.** Suggest and Write are still on the roadmap.

## How it works

### Observe mode (default)

```yaml theme={null}
autonomy:
  level: observe
```

Dino runs against your API, records findings, and reports them — but never blocks CI. Every scan result is saved to watch history for trend analysis.

```bash theme={null}
dino watch --autonomy observe --interval 300
```

This runs a scan every 5 minutes. Findings accumulate in `.dino/watch-history.jsonl`. You review at your pace.

**Use observe when:** You're evaluating Dino, onboarding a new API, or want to see what it finds before trusting it.

### Enforce mode

```yaml theme={null}
autonomy:
  level: enforce
```

Dino blocks CI when it finds issues. `dino watch` returns exit code 1 on failures. `dino diff --fail-on-breaking` returns exit code 1 on breaking changes.

```bash theme={null}
# In CI: single scan, fail the build on issues
dino watch --autonomy enforce --once
```

**Use enforce when:** Dino has been running in observe mode and you trust its findings. Typically after 2-4 weeks of consistent, accurate results.

## The customer journey

```text theme={null}
Day 1    → dino init, first scan, observe mode
Week 1   → "Found 12 issues across 7 scans. 2 false positives."
Week 2   → Adjust config, reduce false positives to 0
Week 3   → "14 scans, 100% useful findings"
Month 1  → Enable enforce mode in staging CI
Month 2  → Enable enforce mode in production CI
```

## CI integration

### Observe in CI (non-blocking)

```yaml theme={null}
# GitHub Actions
- name: Dino Scan (observe)
  run: dino watch --once --autonomy observe
  continue-on-error: true
```

### Enforce in CI (blocking)

```yaml theme={null}
# GitHub Actions
- name: Dino Scan (enforce)
  run: dino watch --once --autonomy enforce
```

### Breaking change gate

```yaml theme={null}
- name: Schema Gate
  run: dino diff --fail-on-breaking
```

<Tip>
  Start with observe mode in CI using `continue-on-error: true`. Review findings for a few weeks. When you trust them, remove `continue-on-error` and switch to enforce.
</Tip>

## Watch history

Every `dino watch` iteration saves a record to `.dino/watch-history.jsonl`:

```json theme={null}
{
  "timestamp": "2026-03-31T10:00:00Z",
  "duration_ms": 4200,
  "operations": 312,
  "findings": 3,
  "agents": { "input-fuzzer": "pass", "rbac-matrix": "2 findings" }
}
```

This history powers trend analysis: "Are findings increasing? Decreasing? Did a deploy introduce new issues?"

<Info>
  Shadow Mode levels 2 (Suggest) and 3 (Write) remain on the roadmap. L2 adds confidence scoring and ranked recommendations. L3 will create pull requests with fixes, pending human approval.
</Info>