Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

docs/04_INGESTION/CONNECTORS.md

@@ -0,0 +1,51 @@
+# Connectors
+
+## V1
+
+### Upload
+Menselijke of API-upload. Vereist filename, content length en target space. Upload is nooit automatisch trusted.
+
+### Read-only folder
+Scant een expliciet gemounte root. Path traversal en symlinks buiten root worden geweigerd. De connector schrijft nooit naar de bronmap.
+
+### Git repository
+Leest een pinned commit/ref uit lokale checkout of toegestane remote. Registreert repository, commit, path en language. Secrets/binaries worden uitgesloten volgens policy.
+
+### Website/sitemap
+Optioneel late V1. Alleen expliciet toegestane domains, robots/politeness, size/time limits en SSRF-beveiligde fetcher.
+
+## Connector contract
+
+`scan(cursor) -> items + next_cursor`; `acquire(item) -> byte stream + metadata`; `fingerprint(item)`. Connectors bevatten geen parsing- of publicationlogica.
+
+## Deletion semantics
+
+Een volledige succesvolle scan mag ontbrekende items als source-deleted markeren. Een partiële/mislukte scan mag nooit massaal verwijderen.
+
+## Source Registry en synchronisatie (1.2.0)
+
+Iedere bron is een persistent record in `content.sources` (id, workspace, knowledge
+space, naam, type, status, secret-vrije configuratie, sync-state, laatste sync,
+laatste succesvolle sync, laatste revisie). Iedere ingest registreert zijn bron
+bij eerste gebruik; ad-hoc uploads zonder `source_id` horen bij de ingebouwde
+*Uploads*-bron van hun space (`upload_source_id(space_id)`, deterministisch).
+
+De `source_id` is **één identiteit** door de hele keten: document → chunk →
+Qdrant-payload → provenance → citation (`ragcore://source/<id>`) → `source_ids`-filter
+→ Control Plane. De `source_key`/`external_id`-dedupsleutel van documenten blijft
+ongewijzigd (sync-clients via de upload-API merken niets).
+
+Synchronisatie (`SourceSyncService`, worker-job `sync_source`, alleen folder/Git):
+
+```
+discover (alle pagina's) → vergelijk fingerprint met registry-items
+  → nieuw/gewijzigd: acquire → blob → ingest_upload-job (zelfde pipeline als uploads)
+  → ongewijzigd: niets
+  → verdwenen (alleen bij complete scan): document retiren
+  → persist run: discovered / new / changed / unchanged / removed / failed
+```
+
+Git-items krijgen het commit als `source_revision` op de documentversie; het
+stabiele document-id van een item is zijn pad (`locator`), niet `<commit>:<pad>`.
+Er is geen scheduler: een sync start vanuit de Control Plane ("Sync now") of door
+een `sync_source`-job te enqueuen. Website-bronnen zijn nog niet aan te maken.

docs/04_INGESTION/JOB_SYSTEM.md

@@ -0,0 +1,21 @@
+# PostgreSQL Job System
+
+## Waarom PostgreSQL
+
+V1 heeft beperkte workerconcurrency. PostgreSQL voorkomt een extra stateful dependency en maakt jobs, attempts, events en businessstate gezamenlijk inspecteerbaar.
+
+## Claim
+
+Workers selecteren ready jobs met `FOR UPDATE SKIP LOCKED`, schrijven `leased_by`, `lease_until` en increment attempt atomair. Een heartbeat verlengt alleen een lease die nog eigendom is van die worker.
+
+## Retry
+
+Exponential backoff met jitter, typed retryable/terminal errors en maximum attempts per jobtype. Poison jobs gaan terminal en blokkeren publication niet onzichtbaar.
+
+## Idempotency
+
+Unieke job key op operation + immutable target + profileversion. Handlers moeten veilig opnieuw uitvoerbaar zijn na crash tussen externe side effect en databasecommit.
+
+## Observability
+
+Iedere transition schrijft een compact event met trace ID, duur, foutcode en sanitized details. Grote parseroutput hoort in artifacts, niet in job rows.

docs/04_INGESTION/PARSING_AND_CHUNKING.md

@@ -0,0 +1,28 @@
+# Parsing and Chunking
+
+## Parserrouter
+
+- Plain text/Markdown/JSON/YAML/TOML/logs: lichte veilige parser.
+- Broncode: language-aware symbol parser waar beschikbaar, veilige fallback per file/section.
+- PDF/DOCX/PPTX/XLSX/HTML: Docling-adapter.
+- OCR: alleen bij ontbrekende of aantoonbaar defecte text layer. **Shipped gedrag (1.2.0):** het gelockte docling-slim image bevat geen OCR-engine (`easyocr`); een PDF zonder tekstlaag wordt dus niet geOCR'd maar eindigt als `failed` (`parse_failed`/`no_indexable_content`) en is zo zichtbaar in Documents/Jobs. Born-digital PDF/DOCX/PPTX/XLSX/HTML worden wel geparsed, met paginanummers.
+- Executables, macro's en scripts worden nooit uitgevoerd.
+
+## Canonical blocks
+
+Heading, paragraph, list, table, code, formula, caption, page break en asset reference met stable structure path en source location.
+
+## Chunkprofielen
+
+- `prose-v1`: 600–900 targettokens, max 1200, sectiegrens respecteren.
+- `runbook-v1`: probleem/symptomen/prerequisites/stappen/validatie/rollback bijeenhouden.
+- `code-v1`: module/class/function/method/config resource; parentcontext voor symbolscope.
+- `table-v1`: headers aan row groups toevoegen en volledige tabel als parent bewaren.
+
+## Deterministische identiteit
+
+`UUIDv5(document_version_id + structure_path + content_hash + chunk_profile_version)`.
+
+## Parent-child
+
+Kleine childchunks dienen retrievalprecisie; ruimere parentchunks dienen context. Parentexpansie mag contextbudget en ACL nooit omzeilen.

docs/04_INGESTION/PIPELINE.md

@@ -0,0 +1,24 @@
+# Ingestion Pipeline
+
+## Stages
+
+1. **Discover:** connector levert typed source items en cursor.
+2. **Acquire:** begrensde read/download met checksum en MIME-detectie.
+3. **Classify:** allowlist, size, extension/MIME mismatch en threat checks.
+4. **Persist blob:** content-addressed en immutable.
+5. **Parse:** gespecialiseerde parser maakt canonical document.
+6. **Normalize:** encoding, whitespace, metadata en structure paths.
+7. **Chunk:** documenttypebewuste deterministische chunks.
+8. **Embed:** profile-pinned dense/sparse representations.
+9. **Index:** upsert naar shadow/target build.
+10. **Validate:** counts, referential checks, sample retrieval en policychecks.
+11. **Publish:** active version en index visibility atomair coördineren.
+12. **Reconcile:** verwijderingen en orphan cleanup.
+
+## Idempotency
+
+Iedere stage gebruikt immutable input-ID + stage/profileversion als idempotency key. Retry mag geen dubbele blobs, versions, chunks of points creëren.
+
+## Resource limits
+
+Maximale file size, archive depth, uncompressed ratio, parser timeout, page count, token count en concurrentie zijn configurabel per source/policy.