# Brain Reorg — Extract to Browser, Vario to Top-Level

**Date**: 2026-02-21

## Motivation

"brain" is doing too much and also too little. It's three unrelated tools (Extract, Vario, Reduce) sharing a directory, but "brain" promises something grander. The tools don't depend on each other and deserve their own identities.

## Proposed Changes

### 1. Move Extract → browser/

Extract (`brain/ingest.py`, `brain/analyze/`) is URL fetching + content parsing. That's browser's domain.

| Current | Proposed |
|---|---|
| `brain/ingest.py` | `browser/extract.py` |
| `brain/analyze/` | `browser/analyze/` |
| `from brain.ingest import fetch` | `from browser.extract import fetch` |

**fetch_escalate** is already documented as the standard way to fetch URLs. Moving it to browser/ makes the dependency direction clearer — jobs depend on browser for fetching, not on "brain".

### 2. Raise Vario to top-level

Vario is a standalone multi-model tool. No dependency on brain.

| Current | Proposed |
|---|---|
| `brain/vario/` | `vario/` |
| `brain/vario/reduce.py` | `vario/reduce.py` |
| `brain/ui_studio.py` | `vario/app.py` (Gradio UI) |
| `from brain.vario.api import run_prompt` | `from vario.api import run_prompt` |
| `brain.localhost` | `vario.localhost` (port TBD from conventions) |

### 3. Unify Vario + Reduce in CLI

Studio UI already merges Vario + Reduce (generate → synthesize in one flow). The CLI should too.

**Current state**: `vario gen` generates, no reduce step. Reduce only available in Studio UI.

**Proposed CLI**:
```bash
vario gen "prompt" -c maxthink                    # generate only (as today)
vario gen "prompt" -c maxthink --reduce           # generate → synthesize best parts
vario gen "prompt" -c maxthink --reduce sonnet    # reduce with specific model
vario gen "prompt" -c maxthink --reduce --iterate 3  # gen → reduce → re-gen → reduce (N rounds)
```

The `--reduce` flag adds a synthesis step after all variants complete. Uses the existing `stream_reduce()` from `reduce.py`. `--iterate N` loops: generate variants → reduce → feed synthesis back as context → generate again → reduce again.

This is the map-reduce loop: Vario fans out (map), Reduce converges (reduce), repeat.

### 4. Reserve brain/ for future

"brain" should be reserved for something that earns the name. Candidates:
- The doctor/self-healing intelligence layer (error classification, autonomous repair)
- An orchestration layer that chains Extract → Vario → Reduce as pipelines
- A reasoning/planning agent that decides what tools to use

For now: empty or minimal, with a README explaining the name is reserved.

## What Breaks

| Consumer | Current Import | Fix |
|---|---|---|
| `/brain` skill | References brain.vario | Update skill |
| `brain.localhost` server | Port 7910 | Move to `vario.localhost`, new port |
| `jobs/handlers/*.py` | `from brain.ingest import fetch` | `from browser.extract import fetch` |
| `brain/vario/` files | `sys.path` hacks with `parent.parent.parent` | Clean up — top-level vario/ doesn't need them |
| `brain/app.py` | Composes Extract + Studio tabs | Split: browser gets extract UI, vario gets studio UI |
| `brain/cards.py` | CardStore shared between Extract and Studio | Move to shared lib or keep in browser |
| `brain/engine/` | Used by Extract for parallel prompts | Stays with Extract → moves to browser |
| `brain/strategies/` | Benchmark configs | Stays with Vario or moves to vario/strategies |

## Migration Strategy

1. Create `vario/` top-level, copy files, update imports
2. Move extract to `browser/extract.py`, update imports
3. Add import shims in `brain/` for backwards compat (temporary)
4. Update all consumers (grep for `from brain.`)
5. Update skills, server configs, port allocations
6. Remove shims after confirming nothing uses old paths
7. Update CLAUDE.md files

## Risks

- Many consumers of `from brain.ingest import fetch` across jobs handlers
- Server config (caddy, launchd) references brain.localhost
- `sys.path` hacks in vario files may break in new location (but should get simpler)
- CardStore is shared state between Extract UI and Studio UI — needs careful separation