# CAI — 5-minute tour

A real failure → diagnosis → fix loop, end to end.

## Setup

```bash
npm i -g @temroi/cai
cd your-project
cai setup --dry-run
```

## First drift detection

Suppose your project's `CLAUDE.md` got out of date and references a file that no longer exists:

```md
# My project
- Source lives in src/legacy/server.ts
- Run `npm run test:slow` to verify
```

Run `cai check`:

```bash
$ cai check
Score: 72/100

error   path       CLAUDE.md references src/legacy/server.ts, but the file is missing
warning command    CLAUDE.md mentions `npm run test:slow`, but the script is not defined in package.json
info    scaffold   1 stale entry in .cai/ROUTER.md (last_updated older than 30 days)
```

Score: **72/100** — below the typical 90 gate.

## Auto-fix

`cai fix` handles deterministic repairs (missing files, stale timestamps, drift history). It will not rewrite your prose.

```bash
$ cai fix
[fix] path: removed stale reference src/legacy/server.ts from CLAUDE.md
[fix] scaffold: refreshed last_updated on .cai/ROUTER.md
[fix] no-op: 0 errors, 0 changes
Done. Re-run `cai check` to confirm.
```

`CLAUDE.md` after the repair:

```md
# My project
- Run `npm run test:slow` to verify
```

The `<!-- cai:start -->` / `<!-- cai:end -->` markers around CAI-managed blocks are preserved. Run `cai check` again:

```bash
$ cai check
Score: 88/100

warning command    CLAUDE.md mentions `npm run test:slow`, but the script is not defined in package.json
```

The remaining issue needs a human decision (rename the script or update the doc). That's where `cai sync` comes in.

## AI-assisted sync

`cai sync` does **not** edit files directly. It emits a targeted prompt you can paste into your coding agent.

```bash
$ cai sync
[sync] wrote .cai/sync/prompt.md (1 unresolved item)
[sync] run: cat .cai/sync/prompt.md
```

```md
<!-- .cai/sync/prompt.md -->
Update CLAUDE.md to match package.json.

- CLAUDE.md says: `npm run test:slow`
- package.json scripts: test, test:unit, lint, build
- Suggestion: rename `npm run test:slow` → `npm run test:unit` in CLAUDE.md,
  or add a `test:slow` script to package.json.
```

You review the prompt, paste it into Claude/Cursor, and apply the change yourself.

## Verifying in CI

Wire `cai check --min-score 90` into CI to fail when drift exceeds the bar.

```yaml
# .github/workflows/cai.yml
- name: Drift check
  run: npx @temroi/cai check --min-score 90
```

While score is 88, CI fails:

```bash
$ cai check --min-score 90
Score: 88/100
error   drift      score 88 is below minimum 90
exit code 1
```

After `cai sync` + human fix + `cai check`:

```bash
$ cai check --min-score 90
Score: 100/100
exit code 0
```

That's the loop. Drift detected → deterministic repair → AI-assisted prompt → CI gate.