From 9486480ebe685d3a2bdc161cac42fc4fa38e2951 Mon Sep 17 00:00:00 2001
From: vegard <vnotnes@pm.me>
Date: Wed, 18 Mar 2026 01:49:48 +0000
Subject: [PATCH] =?UTF-8?q?Retning:=20Unix-filosofi=20=E2=80=94=20maskinro?=
 =?UTF-8?q?mmet=20orkestrerer,=20verkt=C3=B8y=20gj=C3=B8r=20jobben?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Maskinrommet og Claude deler samme CLI-verktøykasse. Maskinrommet
kaller dem fra jobbkøen, Claude fra terminalen. Alt maskinrommet
gjør kan Claude simulere — nyttig for debugging, testing og utvikling.

Nye features bygges som CLI-verktøy fra start. Eksisterende kode
brytes ut gradvis.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                       |   1 +
 docs/retninger/unix_filosofi.md | 100 ++++++++++++++++++++++++++++++++
 2 files changed, 101 insertions(+)
 create mode 100644 docs/retninger/unix_filosofi.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 60edfee..220a404 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -35,6 +35,7 @@ CLAUDE.md er eneste startdokument. Alt annet ligger under `docs/`:
   - `bruker_ikke_workspace.md` — Noder er sentrum: brukere, team, innhold er noder. Tilgangsmatrise fra edges.
   - `datalaget.md` — PG(+AGE) som graf og arkiv, SpacetimeDB som sanntidslag
   - `arbeidsflaten.md` — Spatial canvas med verktøy-paneler, drag-and-drop, kompatibilitetsmatrise
+  - `unix_filosofi.md` — Maskinrommet som orkestrator, arbeid i CLI-verktøy, Claude og maskinrommet deler verktøykasse
 - `docs/primitiver/` — Spesifikasjoner for kjerneprimitivene:
   - `nodes.md` — Node-skjema, node_kind, visibility, CAS-noder, eierskap
   - `edges.md` — Edge-skjema, typer, metadata, systemedges
diff --git a/docs/retninger/unix_filosofi.md b/docs/retninger/unix_filosofi.md
new file mode 100644
index 0000000..f0ff97b
--- /dev/null
+++ b/docs/retninger/unix_filosofi.md
@@ -0,0 +1,100 @@
+# 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