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
```bash
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:
```markdown
## 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 |