# Modul 5 — Ingest dokumentow -> koperta KB

> Adapter obu zrodel (Paperless API + Nextcloud WebDAV) -> koperta KB. Domyka filar #2
> w warstwie 2 (preprocess+index). Zalezy od: 2 (Paperless), 4 (Nextcloud).

## Cel
Wciagnac dokumenty z Paperless i Nextcloud do spine KB (envelope w kb-postgres@PIHA),
z OCR-textem + metadanymi, budujac pierwszy cross-source link (correspondent->maile).

## Wymogi
- `jobs/documents-ingest/` — job CLI (wzorzec jak jobs/gmail-bulk-import/), pip install -e.
- Dwa adaptery:
  - **Paperless API**: pobierz dokumenty (doc-id, correspondent, tags, created, OCR-content).
    `raw_ref` = REFERENCJA (doc-id) — Paperless=zrodlo prawdy. NIE kopiuj bajtow.
  - **Nextcloud WebDAV**: listuj pliki, pobierz. `raw_ref` = KOPIA do archiwum KB
    (snapshot, bo pliki znikaja). Wykrywaj zmiany (etag/mtime) -> nowa koperta (append).
- Mapping -> koperta (`packages/kb-mail` wzorzec, moze `packages/kb-documents`):
  - `source` = `paperless` | `nextcloud`
  - `id` = stabilny (paperless doc-id | nextcloud fileid+etag)
  - `ts` = data dokumentu (Paperless: created/z tresci; Nextcloud: mtime)
  - `geo` = null (dokumenty zwykle bez geo; opcjonalnie z tresci pozniej)
  - `raw_ref` = referencja (paperless) | sciezka-archiwum (nextcloud)
  - `entities[]` = OCR-text (do embed), correspondent, tags, filename, content_type
- **Selektywny index** (jak maile): archiwizuj/referuj wszystko, embeduj sensowne
  (OCR-text -> bge-m3 na SOLARIA -> pgvector). Pomijaj smiecie (puste skany? duplikaty?).

## Graf encji (warstwa 3 — cienki start, PIERWSZY cross-source)
- **correspondent** (Paperless: kto wystawil) = encja. Zmapuj do encji z maili
  (ten sam nadawca faktury i maila = ta sama osoba/firma). To DOWOD zasady kb-00 #7
  (cienka warstwa 4 po drugim zrodle udowadnia cross-source linking).
- Zapisz link w grafie encji (schema z warstwy 3 — jesli nie istnieje, cienki start tutaj).

## Domkniecie dlugu z maili (faza-2-zalacznikow)
- 70k zalacznikow z importu Gmaila (manifest w entities[] kopert mailowych).
- Faktury/umowy/PDFy -> wyslij do Paperless (jego OCR + correspondent-detection),
  potem wciagnij z powrotem przez adapter Paperless. NIE osobny pipeline OCR.
- Sizing: batch, partie (modul 3 OCR-worker na SOLARIA miele).

## Do zweryfikowania przez CC
- Paperless API: endpointy (documents, correspondents, tags), auth (token), paginacja.
- Nextcloud WebDAV: listowanie rekurencyjne, etag, pobieranie, auth.
- Czy `packages/kb-mail` da sie reuzyc czy potrzeba `packages/kb-documents` (koperta wspolna!).
- Jak wykrywac zmiany w Nextcloud (polling etag? webhooks?) dla re-ingestu.
- Deduplikacja: dokument w Paperless I jako zalacznik maila — ten sam? (sha256 match).

## Kryteria ukonczenia
- Dokumenty z Paperless + Nextcloud w tabeli envelope (kb-postgres@PIHA).
- OCR-text zembedowany (pgvector), correspondent jako encja.
- Min. jeden cross-source link correspondent<->mail zademonstrowany.
- Idempotentny (re-run nie duplikuje — wzorzec z gmail-bulk-import ON CONFLICT).
- Testy jednostkowe (wzorzec jobs/gmail-bulk-import/).
- Faza-2-zalacznikow: przetestowana na probce (kilka faktur z maili -> Paperless -> ingest).