# Feature: Systemmanual (`synops-manual`)

## Konsept

`synops-manual` genererer en komplett teknisk instruksjonsmanual
for hele Synops. Manualen er selvforsynt — gitt en ren server og
dette dokumentet kan hele systemet bygges fra scratch.

## Hvorfor

- **Katastrofegjenoppbygging.** Serveren brenner. Du har manualen.
  Du bygger alt på nytt.
- **Onboarding.** Ny utvikler leser manualen og forstår hele stacken.
- **Revisjon.** Manualen er en snapshot av faktisk tilstand —
  ikke intensjoner, ikke planer, men hva som kjører nå.
- **AI-kontekst.** Claude leser manualen og har komplett bilde
  uten å traversere 90+ filer.

## Hva den inneholder

### 1. Infrastruktur
- Server-spec (OS, IP, DNS-oppføringer, domener)
- Installerte pakker (Rust, Node.js, Docker, Caddy)
- Brukere og rettigheter
- Katalogsstruktur (`/srv/synops/`, `/home/vegard/synops/`)

### 2. Database
- PG-skjema (generert fra faktisk database, ikke docs)
- Alle tabeller, kolonner, typer, indekser, constraints
- Kjente node_kinds og edge_types (fra faktisk data)
- Seed-data (systemkritiske noder: Synops-rot, agent-node,
  arbeidstavle, onboarding)
- Triggers (LISTEN/NOTIFY)

### 3. Tjenester
For hver tjeneste:
- Hva den gjør
- Hvordan den startes (systemd unit / Docker Compose)
- Konfigurasjon (env-variabler, config-filer)
- Porter og kommunikasjon
- Avhengigheter
- Healthcheck

Tjenester: Caddy, vaktmesteren, SvelteKit, PostgreSQL,
Authentik, LiteLLM, faster-whisper, LiveKit.

### 4. CLI-verktøy
For hvert `synops-*`-verktøy (hentet fra cli_tool-noder i PG):
- Navn og beskrivelse
- Usage (--help output)
- Input/output
- Avhengigheter
- Build-instruksjoner (`cargo build --release`)

### 5. Caddy-konfigurasjon
- Komplett Caddyfile (fra faktisk fil, ikke docs)
- Domene → tjeneste-mapping
- TLS-oppsett

### 6. Applikasjonslogikk
- Alle node_kinds med beskrivelse og metadata-skjema
- Alle edge_types med semantikk og metadata
- Traits-katalog med konfigurasjon per trait
- Kanban-kolonner for arbeidstavlen
- Agent-konfigurasjon (node-ID, permissions, rate limits)

### 7. Konvensjoner
- @bot-konvensjonen (chat-interaksjon, work item-fangst)
- n:-referanser (nodelinking, tilgangsprompt)
- Privacy-signalering (🔒/👁)
- Responskvalitet (intelligens/innsats-nivåer, ↑-knapp)
- Generisk dispatch (synops-{job_type} --payload-json)

### 8. Arkitekturprinsipper
Retningene som har formet systemet — ikke bare hva det gjør,
men hvorfor det er bygget slik:

- **Alt er noder og edges.** Ingen separate tabeller. Visninger
  er spørringer mot grafen.
- **Unix-filosofi.** Vaktmesteren orkestrerer, CLI-verktøy gjør
  jobben. Én ting, gjort godt. Delt verktøykasse.
- **Selvdokumenterende system.** Systemet dokumenterer seg selv
  som noder i seg selv. Docs er ikke filer — de er graf-data.
- **Universelle primitiver.** Tre primitiver (input, mottak,
  kommunikasjon). Alt annet er visninger og edges.
- **Privat er default.** Input uten edges er privat. Sikkerhet
  by design, ikke konfigurasjon.
- **Noder er sentrum.** Brukere, team, innhold — alt er noder.
  Tilgang via materialisert tilgangsmatrise fra edges.
- **Vaktmesteren er tynn.** Auth, HTTP-ruting, STDB-synk.
  All logikk i CLI-verktøy og synops-common.
- **Generisk dispatch.** `synops-{job_type} --payload-json`.
  Nytt verktøy = binary i PATH. Ingen rekompilering.
- **@bot er generisk.** Ruterbar, modell-agnostisk. Brukeren
  snakker med "boten", ikke med en spesifikk AI.
- **Responskvalitet er synlig.** Intelligens og innsats vises.
  Én ↑-knapp for "gi bedre svar".

Genereres fra `docs/retninger/`-noder i PG.

### 9. Gjenoppbyggingssteg
Nummerert sekvens fra ren server til kjørende system:

```
1.  Provisjoner server (Ubuntu, brukere, SSH)
2.  Installer pakker (Rust, Node.js, Docker, Caddy)
3.  Konfigurer DNS (domener → IP)
4.  Start Docker-tjenester (PG, Authentik, LiteLLM, Whisper, LiveKit)
5.  Kjør PG-migrasjoner (skjema + seed)
6.  Konfigurer Authentik (OIDC-provider, redirect URIs)
7.  Bygg og deploy vaktmesteren (cargo build, systemd)
8.  Bygg og deploy SvelteKit (npm build, systemd)
9.  Bygg CLI-verktøy (cargo build per tool)
10. Konfigurer Caddy (Caddyfile, reload)
11. Verifiser (healthchecks, test-requests)
12. Seed systemdata (Synops-rot, arbeidstavle, agent-node)
```

## Generering

```bash
synops-manual --format md > manual.md    # Markdown
synops-manual --format html > manual.html  # Standalone HTML
synops-manual --format json               # Maskinlesbar
```

### Datakilder

| Seksjon | Kilde |
|---------|-------|
| Infrastruktur | `uname`, `dpkg`, DNS-oppslag, filsystem |
| Database | `pg_dump --schema-only`, faktiske spørringer |
| Tjenester | systemd-units, docker-compose.yml, .env |
| CLI-verktøy | cli_tool-noder i PG + `--help` per binary |
| Caddy | `/srv/synops/config/caddy/Caddyfile` |
| Applikasjonslogikk | PG-spørringer (node_kinds, edge_types, traits) |
| Konvensjoner | docs/-filer (disse er stabile referanser) |

### Hva den IKKE inkluderer

- Secrets (API-nøkler, passord, tokens) — erstattet med `<REDACTED>`
- Brukerdata (innhold, meldinger, mediefiler)
- Git-historikk
- CAS-innhold (binærfiler)

## Automatisk generering

Manualen regenereres:
- **Daglig** via cron (fanget av `synops-snapshot` eller separat)
- **Ved deploy** (post-hook i systemd)
- **Manuelt** ved behov

Lagres som:
- `docs/MANUAL.md` i repo (committes)
- Synops-noden i PG (som innhold på en `content`-node)

## Diff-modus

```bash
synops-manual --diff
```

Sammenligner nåværende tilstand med sist genererte manual.
Viser hva som har endret seg — nye tjenester, endrede porter,
nye CLI-verktøy, skjemaendringer. Nyttig for review.

## Bygger på
- `docs/concepts/selvdokumenterende_system.md` — docs som noder
- `docs/concepts/arbeidstavlen.md` — synops-snapshot
- `docs/setup/produksjon.md` — eksisterende oppsettdok (input)
- `docs/retninger/unix_filosofi.md` — CLI-verktøy konvensjoner