synops/docs/concepts/selvdokumenterende_system.md

Konsept: Selvdokumenterende system

Filsti: docs/concepts/selvdokumenterende_system.md

1. Konsept

Synops dokumenterer seg selv som noder i seg selv. Arkitektur, features, CLI-verktøy, retninger og erfaringer er noder i grafen — ikke bare markdown-filer i et repo. En offentlig synlig Synops-node er roten, og alt systemrelevant henger under den via edges.

2. Hvorfor

Markdown-filer i docs/ har tre problemer:

1. Rotner. Koden endres, docs oppdateres ikke. Ingen kobling mellom spec og implementasjon.
2. Frakoblet. Docs kan ikke lenkes fra chat, work items eller andre noder via n:-referanser.
3. Dobbeltvedlikehold. Samme informasjon lever i docs-filer OG i kode/database. Endring ett sted glemmes det andre.

Løsningen: docs er noder. De deltar i grafen, lenkes med n:-referanser, traverseres av bot og brukere, og oppdateres der de lever.

3. Synops-noden

Én rot-node som er inngangspunkt til alt systemrelevant:

Synops (collection, visibility: readable)
│
├── Synops CLI (collection)
│     ├── synops-transcribe     (cli_tool)
│     ├── synops-render         (cli_tool)
│     ├── synops-audio          (cli_tool)
│     ├── synops-tasks          (cli_tool)
│     ├── synops-snapshot       (cli_tool)
│     └── ...
│
├── Synops Arkitektur (collection)
│     ├── Portvokteren          (content)
│     ├── Datalaget             (content)
│     ├── Noder og edges        (content)
│     ├── Trait-systemet        (content)
│     └── ...
│
├── Synops Features (collection)
│     ├── Nodereferanser        (content)
│     ├── Kanban                (content)
│     ├── Lydstudio             (content)
│     ├── Universell overføring (content)
│     └── ...
│
├── Synops Retninger (collection)
│     ├── Unix-filosofi         (content)
│     ├── Arbeidsflaten         (content)
│     ├── Noder er sentrum      (content)
│     └── ...
│
├── Arbeidstavlen (collection, kanban-trait)
│     └── (work_items)
│
└── Synops Erfaringer (collection)
      ├── SpacetimeDB-integrasjon  (content, historisk)
      ├── Authentik OIDC           (content)
      └── ...

visibility: readable — alle autentiserte brukere kan se systemdokumentasjonen. Skrivetilgang via admin-edge.

4. Hva dette gir

For Claude

synops-context --node-id <synops-uuid>
  → Hele systemdokumentasjonen via grafen
  → Traverserer edges til CLI-verktøy, arkitektur, features
  → Alltid oppdatert — leser fra PG, ikke stale filer

For ny utvikler

Åpner Synops-noden i web → navigerer alt via klikkbare n:-referanser. Ingen "les CLAUDE.md, deretter docs/arkitektur.md, deretter docs/retninger/README.md" — bare én node som rot.

For CLAUDE.md

Krymper til:

## Systemkontekst
Synops-noden er n:<uuid>. Start der.
Bruk `synops-context --node-id <uuid>` for full oversikt.
Resten av denne filen er fallback ved PG-nedetid.

CLAUDE.md beholder arkitektur-oversikten som fallback (jf. synops-snapshot), men den autoritative kilden er grafen.

For oppdateringer

Endre en feature-spec → oppdater noden. Alle n:-referanser til den fra chat, work items og andre docs peker til oppdatert versjon. Ingen stale lenker.

5. Innholdsformat

Dokumentasjonsnoder bruker content for ren tekst (søkbar) og metadata.document for strukturert innhold (TipTap JSON). Samme format som artikler og notater — redigerbart i editoren på web, lesbart via CLI.

For lange spesifikasjoner: noden er dokumentet. Ingen separat fil å vedlikeholde.

6. Edge-modell

Edge	Source → Target	Betydning
belongs_to	child → Synops	Del av systemdokumentasjonen
belongs_to	cli_tool → Synops CLI	Verktøy i verktøykassen
belongs_to	feature → Synops Features	Feature-spec
mentions	work_item → feature	Arbeid relatert til feature
mentions	chat-melding → cli_tool	Diskusjon om verktøy
source_material	feature → retning	Feature bygger på retning

7. Migrering fra docs/

Fase 1: Seed fra markdown

Script leser docs/-filene, oppretter noder med innholdet, bygger edge-strukturen. Deterministiske UUID-er (uuid5 fra filsti) for idempotent kjøring.

Fase 2: Dobbeltliv

Markdown-filer og noder lever parallelt. synops-snapshot genererer markdown fra noder — docs-filene blir output, ikke input.

Fase 3: Noder er kilden

Docs-filer fjernes eller erstattes med genererte snapshots. Redigering skjer i grafen. CLAUDE.md beholder kun bootstrap-info og fallback.

8. Avgrensning

• CLAUDE.md forsvinner ikke. Den er bootstrap-loader for Claude Code — lastes automatisk og må være en fil i repo. Men den krymper til en peker + fallback.
• Git-historikk bevares. Markdown-filer i docs/ har verdifull git-historikk. De slettes ikke — de fryses og erstattes av genererte snapshots.
• Ikke alt er noder. Kode er kode (Rust, Svelte, SQL). Bare dokumentasjon, spesifikasjoner og prosjektstyring migreres til noder.

9. Utviklingsfaser

1. Opprett Synops rot-node og undersamlinger (CLI, Arkitektur, Features, Retninger, Erfaringer).
2. Seed cli_tool-noder fra eksisterende verktøy.
3. Seed dokumentasjonsnoder fra docs/-filene.
4. Oppdater synops-context til å traversere Synops-noden.
5. Oppdater synops-snapshot til å generere docs/ fra noder.
6. Oppdater CLAUDE.md til minimal bootstrap + fallback.

10. Komponenter

Feature	Rolle
Synops-noden	Rot for all systemdokumentasjon
n:-referanser	Lenking mellom docs, verktøy, work items
synops-context	CLI-traversering av dokumentasjonsgrafen
synops-snapshot	Genererer fallback-filer fra noder
Editoren (web)	Redigering av docs-noder i nettleseren
KanbanTrait	Arbeidstavlen som del av Synops-treet