# Unix-filosofi: Maskinrommet som orkestrator, verktøy som binaries

## Tese

Maskinrommet skal ikke *gjøre* arbeid — det skal *koordinere* arbeid.
Selve arbeidet gjøres av spesialiserte CLI-verktøy som maskinrommet
kaller. Claude har tilgang til de samme verktøyene og kan simulere
alt maskinrommet gjør.

## Prinsipp

1. **Én jobb, gjort godt.** Hvert verktøy gjør én ting — transkriberer,
   rendrer, prosesserer lyd, genererer RSS. Ikke alt i én binær.

2. **Delt verktøykasse.** Maskinrommet og Claude bruker *samme* CLI-verktøy.
   Maskinrommet kaller dem fra jobbkøen, Claude kaller dem fra terminalen.
   Ingen hemmelig logikk som bare lever inne i maskinrommet.

3. **Orkestratoren er frontendens interface.** Frontend snakker med
   maskinrommet via HTTP. Maskinrommet validerer, autoriserer, legger i
   jobbkø, og delegerer til CLI-verktøy. Maskinrommet *eier* auth og
   edges — men *delegerer* prosessering.

4. **Claude kan simulere alt.** Fordi maskinrommet gjør alt via CLI,
   kan Claude kjøre de samme kommandoene manuelt. Nyttig for:
   - Debugging ("hvorfor feiler transkripsjonen?")
   - Testing ("hva skjer om jeg rendrer denne artikkelen?")
   - Utvikling ("la meg prøve den nye FFmpeg-filteren direkte")
   - Feilretting ("la meg re-kjøre RSS-genereringen for denne samlingen")

## Arkitektur

```
Frontend (SvelteKit)
  │
  ▼ HTTP
Maskinrommet (Rust)
  ├── Auth + tilgangskontroll
  ├── Intentions (validering, edge-logikk)
  ├── Jobbkø (PG-basert)
  │     │
  │     ▼ spawn
  │   CLI-verktøy (tools/)
  │     ├── synops-transcribe   (Whisper)
  │     ├── synops-render       (Tera → CAS)
  │     ├── synops-audio        (FFmpeg)
  │     ├── synops-tts          (ElevenLabs)
  │     ├── synops-ai           (LiteLLM)
  │     ├── synops-rss          (RSS-generering)
  │     ├── synops-context      (graf-oppslag)
  │     ├── synops-search       (fulltekstsøk)
  │     └── ...
  │
  ▼ direkte
PG, STDB, CAS
```

Claude har tilgang til hele `tools/`-katalogen og kan kjøre alt direkte:
```bash
# Maskinrommet gjør dette via jobbkøen:
synops-transcribe --cas-hash abc123 --model medium

# Claude kan gjøre det samme fra terminalen:
synops-transcribe --cas-hash abc123 --model medium
```

## Konvensjoner for CLI-verktøy

- **Input:** args + stdin + env-variabler (DATABASE_URL, CAS_ROOT)
- **Output:** stdout (strukturert — JSON eller markdown)
- **Feilhåndtering:** stderr for feilmeldinger, exit-kode != 0 ved feil
- **Ingen tilstandsendring uten flagg:** lesing er default, skriving krever
  `--write` eller `--apply` (sikkerhetsnett for Claude)
- **Idempotent der mulig:** kan kjøres flere ganger uten sideeffekter

## Migrasjonsstrategi

Ikke en big-bang refaktor. Gradvis utbryting:

1. **Nye features** bygges som CLI-verktøy fra start (fase 19+)
2. **Eksisterende kode** brytes ut når den berøres — naturlig refaktor
3. **Maskinrommet** beholder auth, intentions, jobbkø og edge-logikk
4. **Jobbkø-handlere** endres fra inline-kode til `Command::new("synops-X")`

## Hva maskinrommet *beholder*

Kjernen som ikke bør brytes ut:
- Auth-middleware (JWT-validering, node-oppslag)
- Intentions (validering, STDB+PG-skriving, edge-logikk)
- Jobbkø (polling, retry, dead letter)
- Tilgangskontroll (node_access, recompute_access)
- Health-endepunkt

Alt annet — prosessering, rendering, generering — er kandidater for
CLI-verktøy.

## Bygger på
- `docs/retninger/maskinrommet.md` — orkestratorrollen
- `docs/infra/agent_api.md` — Claude sitt grensesnitt
- `tools/README.md` — verktøykatalogen