synops/docs/features/systemmanual.md

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, portvokteren, 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. Portvokteren 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.
• Portvokteren 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 portvokteren (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

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

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