# Channel Insights → moving readings between machines (export / import)

## What it does

Readings (`lead_channel_insights`, the ten per-lead AI readings) can be made on a machine that holds
a **copy** of production. That machine can only *read* production, so the readings travel as a
folder and are replayed on production:

```bash
# on the machine that made them
php artisan leads:export-analysis --model=claude-opus-5-5          # → storage/app/lead-analysis-export/<timestamp>/

# copy the folder to the server, OUTSIDE the web root, then on the server
php artisan leads:import-analysis <folder>             # dry run: what WOULD happen, per lead
php artisan leads:import-analysis <folder> --apply     # write
```

The first use (2026-10-12) was readings written by hand by Claude Code from the exact prompts, with
no AI provider called: the A-grade leads of the [signal grade](/docs/modules_handbook/manage/leads/signal-grade.md).
Those readings are stamped `claude-opus-5-5`. Production therefore marks them stale with reason
`model`, and its own Analyse button re-reads on Gemini.

## How it works

### The bundle

- `manifest.json` holds:
  - `format`;
  - `as_of`: when the copy of production was taken;
  - `model`, `leads`, `readings`, `per_channel`;
  - `source_commit`;
  - the sha256 of `readings.ndjson`.
- `readings.ndjson` has one line per reading:
  - `lead_uuid`, which the import matches on;
  - `channel`, `conversation_ids`, `ai_insights`, `ai_insights_model`, `ai_insights_hash` and
    `ai_insights_count`, which the import writes;
  - `local_lead_id`, `local_user_id` and `analysed_at_local`, which the import never reads. They are
    there so a person can cross-check a line against the copy it came from. Ids differ between
    machines.
- The export takes the rows of `--model` made **on or after `as_of`**: the readings made from this
  copy, never production's own rows that the copy brought along.
- `as_of` defaults to `storage/app/db-sync/last-sync.json` (`ExportLeadAnalysis::AS_OF_MARKER`).
  The command that makes the copy writes that file. That sync command lives only on the machine that
  makes the copy and is **not in this repository**. With a copy made any other way, pass
  `--as-of="Y-m-d H:i:s"`, which is the moment the copy was taken, in the app's timezone.
- ⚠️ The bundle holds customer quotes. Keep it outside any web root, and delete it on both machines
  once it is imported.

### The import rules, per reading (lead + channel)

| Outcome | When |
|---|---|
| `lead gone` | No lead with that uuid here: deleted, or merged away. Never recreated |
| `same` | This site already holds the identical reading (same `ai_insights_hash`) |
| `newer here` | This site made its own reading **after** `as_of`. Kept |
| `source gone` | A record the reading was read from (`conversation_ids`) no longer exists here |
| `channel kept` | Overall / Summary, when one of the lead's channel readings was `newer here` or `source gone`: they are read from the channels, so they stay with them |
| `import` | Everything else |

- **Writes go through `LeadChannelInsightRepository::saveForLead`.** It creates this site's own
  pending action proposals (`syncFromInsight`, with assignees resolved against this site's staff)
  and recomputes the readiness cache, exactly as an Analyse click would.
- **Each reading is stamped `ai_insights_at = as_of`**, never the import time. The channels' stale
  rules ask "did a record change after `ai_insights_at`?". Stamping the import time would hide every
  message that arrived between the copy and the import. `saveForLead` accepts an explicit
  `ai_insights_at` for exactly this; a normal reading leaves it out and gets `now()`.
- **It is safe to re-run.** What was imported reads as `same` the second time.
- The manifest hash is checked first, so a file changed or cut short in transit is refused.

### Keep the window short

Every day between the copy and the import, more WhatsApp threads move on production, and those
readings arrive already stale. That is honest (the panel says so), but the work is wasted. Do not
re-sync the copy between making the readings and exporting them: a sync rewrites
`lead_channel_insights` from production and deletes them locally.

## Related files

- [app/Console/Commands/ExportLeadAnalysis.php](/app/Console/Commands/ExportLeadAnalysis.php)
- [app/Console/Commands/ImportLeadAnalysis.php](/app/Console/Commands/ImportLeadAnalysis.php)
- [src/Lead/Repositories/LeadChannelInsightRepository.php](/src/Lead/Repositories/LeadChannelInsightRepository.php) (`saveForLead`, optional `ai_insights_at`)
- [tests/Feature/Lead/LeadAnalysisBundleTest.php](/tests/Feature/Lead/LeadAnalysisBundleTest.php)
