# 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).