docs(okr): innboks-ingestion funn-grunnlag (web-verifisert)

Self-bearing grunnlag for den koeede innboks-ingestion-oppgaven (start etter
OKF-fasen). Web-verifisert undersoekelse av GoogleCloudPlatform/knowledge-catalog:
ingen ferdig innboks->OKF-pipeline finnes (verken Google eller oss). Dokumenterer
hva som finnes (reference_agent/index-generator/Source-ABC/fileskb), OKF-relasjons-
modellen (markdown-lenker i body), gap (dok-konvertering + konsept-ekstraksjon +
generalisert relasjons-oppdagelse), gjenbrukbare byggeklosser, og kilder for
etterproevbarhet. STATE I-koe-peker oppdatert (local-only).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFW5scLL7oEwWWTv1fPQG6

docs/innboks-ingestion-funn-2026-06.md

@@ -0,0 +1,109 @@
+# Innboks-ingestion — funn-grunnlag (2026-06-26)
+
+> Self-bearing grunnlag for den **køede** innboks-ingestion-oppgaven (start **etter**
+> OKF-fasen er stengt; egen minor-bump). Speiler rollen `okf-second-brain-note-2026-06.md`
+> hadde for OKF-fasen. Alle påstander om Google-repoet er **verifisert mot faktisk lest
+> innhold** (kilder i §9) — ikke antakelser.
+
+## 1. Oppgaven
+
+Bruker slipper vilkårlige dokumenter (PDF, Word, tekst, e-post) i en **innboks-mappe**.
+okr-pluginen skal oppdage dem, konvertere til markdown, og legge dem inn **OKF-kompatibelt**
+i second-brain-treet — med korrekt frontmatter (`type/resource/title/description/tags/timestamp`),
+`index.md` per nivå, **og relasjoner/kryss-lenker** mellom konsepter. Original beholdes,
+markdown-peker plasseres. Søsken-pluginen `ms-ai-architect` har samme oppgave (delt mønster).
+
+## 2. Hovedkonklusjon
+
+**Det finnes ingen ferdig innboks→OKF-ingestion-løsning med relasjonshåndtering — verken i
+`GoogleCloudPlatform/knowledge-catalog` eller i okr-pluginen.** Google gir oss spec +
+gjenbrukbare byggeklosser (index-generator, relasjons-mønster, kilde-utvidelsespunkt), men
+**ikke** en pipeline fra «ustrukturert innboks» til «ferdig OKF-bundle». Dette blir et reelt
+byggeløp.
+
+Rammeavklaring (verifisert): «knowledge-catalog» = Google Cloud **Knowledge Catalog (tidl.
+Dataplex)** — metadata for *dataassets*. «OKF» (`okf/`) er et eget, vendor-nøytralt
+markdown-format. Beslektede, men distinkte spor i repoet.
+
+## 3. Hva Google-repoet faktisk har
+
+| Komponent | Sti | Hva det er | Innboks-ingestion? |
+|---|---|---|---|
+| `reference_agent` | `okf/src/reference_agent/` | OKF-**produsent** (CLI: `enrich`/`visualize`). Auto-genererer `index.md` + auto-vever kryss-lenker | **Delvis** — kun fra **BigQuery + web-crawl**, ingen «ingest folder»-kommando |
+| `bundle/index.py` (`regenerate_indexes`) | `okf/src/reference_agent/bundle/` | Kildeagnostisk `index.md`-generator per nivå (LLM-synt. mappebeskrivelser) | Gjenbrukbart |
+| `sources/base.py` (`Source`-ABC) | `okf/src/reference_agent/sources/` | Utvidelsespunkt for kilder; eneste impl. er `bq` (`_SOURCES = ("bq",)`) | Utvidelsespunkt — ingen fil-/dokumentkilde finnes |
+| `fileskb` / `md-fileset` | `samples/enrichment/src/tools/fileskb/`, `toolbox/enrichment/src/tools/md/` | **Read-only** MCP over en markdown-mappe (`fileset-source`-skill) | Nei — retrieval, antar allerede markdown |
+| `enrichment` | `samples/enrichment/`, `toolbox/enrichment/` | Beriker **katalog-metadata** for et BQ-datasett, publiserer til Dataplex | Nei — ikke OKF-output |
+| `discovery` | `samples/discovery/SKILL.md` | `knowledge_catalog_discovery_agent` — søk/ranking | Nei — ren retrieval |
+| `mdcode` | `toolbox/mdcode/` | Spec + bi-direksjonell sync (`kcmd` pull/push) mot Dataplex | Nei — sync, ikke ingestion |
+| `okf/SPEC.md` | `okf/` | OKF v0.1 spec (markdown + frontmatter, `index.md`, `log.md`, kryss-lenker, citations) | Spec |
+
+## 4. Relasjons-modellen i OKF (verifisert, `okf/SPEC.md` §5, §8)
+
+- Relasjoner = **vanlige markdown-lenker i body**, IKKE et frontmatter-felt. Anbefalt
+  bundle-relativ form (`/tables/customers.md`). En lenke er en *uttypet, rettet* relasjon;
+  *hvilken* relasjon (join/parent/depends-on) bæres av prosaen rundt lenken.
+- Citations (§8) = lenker til eksterne kilder. Vieweren beregner «Cited by»-backlinks som
+  reverserte kanter.
+- **Auto-etablering finnes** i `reference_agent` (`prompts/reference_instruction.md` +
+  `web_ingestion_instruction.md`: mynter `references/joins/<a>__<b>.md`, `references/metrics/<slug>.md`,
+  legger til `# Joins`/`# Metrics`-seksjoner) — men logikken er **skreddersydd for BQ-joins/metrikker
+  + web-dokumentasjon**, ikke et vilkårlig dokumentkorpus.
+- Kontrast: `mdcode` har et eget `EntryLink`-konsept i YAML for *katalog*-relasjoner — separat fra OKF.
+
+## 5. Gap — hva vi må bygge selv
+
+1. **Dokument-konvertering** (PDF/Word/e-post/tekst → markdown). Finnes ikke i repoet. De
+   eneste fil-verktøyene (`fileskb`/`md-fileset`) antar markdown og er read-only.
+2. **Konsept-ekstraksjon + frontmatter-tilordning** for vilkårlige dokumenter (splitte til
+   «konsepter», sette `type/resource/title/description/tags/timestamp`). reference_agent gjør
+   dette kun for BQ-tabeller.
+3. **Generalisert relasjons-oppdagelse** — dagens relasjons-prompt er BQ/web-spesifikk og må
+   generaliseres til vilkårlige dokumenter.
+4. **Innboks-orkestrering** — oppdage nye filer, beholde original + markdown-peker, idempotent
+   re-kjøring, plassering i riktig nivå av treet.
+
+## 6. Gjenbrukbart (lener oss på, bygger ikke fra null)
+
+- **Index-generering:** Vi har allerede `scripts/okf-index.mjs` (Step 6, OKF-fasen) som speiler
+  Googles `regenerate_indexes` — kildeagnostisk, idempotent. Innboks-pipelinen kan kalle den
+  etter skriv (samme mønster som `oppsett.md`-tre-skriverne i Step 8).
+- **Frontmatter:** `lib/frontmatter.mjs` (parse/skrive) + `scripts/okf-check.mjs` (validering)
+  fra OKF-fasen dekker skrive- og verifiserings-siden.
+- **Kilde-mønster:** Googles `Source`-ABC viser et rent adapter-mønster — en «innboks-kilde»
+  som lister konsepter fra en mappe kunne mate eksisterende skrive-/index-/kryss-lenke-maskineri.
+
+## 7. Forbehold / ikke verifisert (verifiseringsplikt)
+
+- **`kb-search/SKILL.md` ble IKKE funnet** i repoet, til tross for at våre egne planer
+  (`plan.md:26`, `brief.md:168`) refererer den. Skillene som finnes heter `fileset-source`
+  (retrieval) og `knowledge_catalog_discovery_agent` (søk). Mulig repoet har endret seg, eller
+  referansen var unøyaktig. **Ikke kritisk for OKF-fasen** (vår retrieval-SKILL er ferdig og
+  testet), men korrigerer en navne-antakelse for innboks-løpet.
+- Ikke fullt lest: `okf/src/reference_agent/{agent.py, runner.py, tools/*.py}` og
+  `toolbox/enrichment/src/agent/*`. Kilde-/ingestion-konklusjonen er likevel entydig fra
+  `cli.py` (`_SOURCES = ("bq",)`), `sources/`-innholdet, og enrichment-README/`enrich.py`.
+
+## 8. Sekvens / scope
+
+- **Start: etter OKF-fasen er stengt** (Session 5 release → 1.6.0). Scope-guard: innboks bygger
+  på OKF-leveransen og er bevisst utsatt — **ikke start før operatør sier fra**.
+- Eget Voyage-løp (brief → plan → execute), egen **minor-bump** (1.7.0-kandidat).
+- Delt mønster med `ms-ai-architect` — vurder felles abstraksjon før dobbel-implementasjon.
+
+## 9. Kilder (faktisk lest, etterprøvbart)
+
+GitHub API-mappelistinger: repo-rot, `okf/`, `samples/`, `toolbox/`,
+`okf/src/reference_agent/{prompts,tools,sources,bundle}`, `samples/enrichment/src/{enrichment,tools}`,
+`toolbox/enrichment/src/{agent,tools}`, `toolbox/mdcode/{docs,demo}`.
+
+Rå filer (`raw.githubusercontent.com/GoogleCloudPlatform/knowledge-catalog/main/`):
+`README.md`, `samples/README.md`, `okf/README.md`, `okf/SPEC.md`,
+`okf/src/reference_agent/cli.py`, `.../sources/base.py`, `.../prompts/reference_instruction.md`,
+`.../prompts/web_ingestion_instruction.md`, `.../bundle/synthesizer.py`, `.../bundle/index.py`,
+`samples/enrichment/README.md`, `samples/enrichment/src/enrichment/enrich.py`,
+`samples/enrichment/src/tools/fileskb/README.md`, `toolbox/enrichment/README.md`,
+`samples/discovery/SKILL.md`, `toolbox/mdcode/docs/spec.md`, `toolbox/mdcode/docs/concept.md`,
+`toolbox/mdcode/README.md`.
+
+Undersøkelse utført 2026-06-26 (Opus-subagent, web-verifisert).