Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

docs/06_API/API_DESIGN.md

@@ -0,0 +1,31 @@
+# API Design
+
+## Principes
+
+- Prefix `/v1` voor productresources; health blijft onversioned.
+- JSON en RFC 9457-style problem details voor fouten.
+- Opaque UUID identifiers.
+- Idempotency-Key vereist voor create/upload/sync requests die clients kunnen herhalen.
+- Cursorpagination, stabiele sortering en begrensde page sizes.
+- Timestamps in RFC 3339 UTC.
+- Geen raw SQL, Qdrantfilter, providerprompt of onbeperkte modelparameters in publieke requests.
+
+## Kernresources
+
+- workspaces/applications/service accounts;
+- knowledge spaces en grants;
+- sources/sync runs;
+- documents/versions;
+- jobs;
+- search/context/answers;
+- citations/feedback;
+- profiles/evaluation runs;
+- audit events.
+
+## Async operations
+
+Upload, sync, reindex en evaluatie leveren `202 Accepted` met job ID en status URL. Jobstatus bevat typed state, progress en sanitized failure.
+
+## Streaming
+
+Answers kunnen Server-Sent Events gebruiken met events `metadata`, `delta`, `citation`, `complete`, `error`. Citations en answerabilitymetadata worden vóór of uiterlijk met complete geleverd.

docs/06_API/ERROR_MODEL.md

@@ -0,0 +1,23 @@
+# Error Model
+
+Alle API-fouten gebruiken `application/problem+json`:
+
+```json
+{
+  "type": "https://ragcore.example.test/problems/space-forbidden",
+  "title": "Knowledge space access denied",
+  "status": 403,
+  "code": "SPACE_FORBIDDEN",
+  "detail": "The caller is not allowed to use one or more requested spaces.",
+  "trace_id": "..."
+}
+```
+
+## Regels
+
+- `code` is stabiel en machineleesbaar.
+- `detail` bevat geen secrets, SQL, filesystemroots of providerkeys.
+- Validation errors bevatten veldpaden en veilige redenen.
+- Provider/downstream errors worden gemapt naar RAGCore-codes.
+- Retryable errors geven optioneel `retry_after_seconds`.
+- 404 mag voor gevoelige resources worden gebruikt waar 403 bestaan zou lekken.

docs/06_API/SDK_REQUIREMENTS.md

@@ -0,0 +1,51 @@
+# SDK Requirements
+
+V1 levert handgeschreven Python (`sdk/python`, pakket `ragcore-sdk`) en
+TypeScript (`sdk/typescript`, pakket `@ragcore/sdk`) clients tegen de
+pinned OpenAPI-specificatie, elk scoped tot de drie echt geïmplementeerde
+retrieval-endpoints (`search`/`context`/`answers`) -- `/v1/citations/{id}`
+en `/v1/jobs/{id}` staan wel in `docs/contracts/openapi.yaml`, maar zijn
+nooit als echte route geïmplementeerd, dus geen van beide SDK's doet
+alsof ze bestaan.
+
+Beide SDK's:
+
+- accepteren het bearer token veilig zonder het ooit te loggen (Python:
+  nooit buiten de request-headers; TypeScript: een echt privé class field
+  `#token`, niet TypeScript's compile-time-only `private`, dus niet
+  zichtbaar via `console.log`/spread/`JSON.stringify`);
+- ondersteunen timeouts (beide) en cancellation via de standaard taal-
+  mechanismen (Python: normale `asyncio`-cancellation; TypeScript: een
+  interne `AbortController` per request) -- geen aparte cancellation-API
+  bovenop wat de taal al biedt;
+- exposen typed problem details (`ProblemDetails`/`RAGCoreAPIError`) voor
+  elke non-2xx-response, die allemaal dezelfde RFC7807-vorm hebben;
+- modelleren de search/context/answer-types volledig, inclusief citations;
+- handelen de SSE-answerstream af (`event: <type>\ndata: <json>\n\n`,
+  zoals `answers/routes.py::_sse_body` het echt verstuurt);
+- retryen alleen de non-streaming requestpaden, en alleen bij een
+  connectiefout of een `503` -- nooit een `4xx`, nooit een al gestarte
+  SSE-stream (zie beide SDK's eigen moduledocstring voor de redenering);
+- sturen een eigen versie-identifier mee: Python zet een echte
+  `User-Agent: ragcore-sdk-python/<versie>` header; TypeScript zet in
+  plaats daarvan `X-RAGCore-SDK-Version: <versie>`, omdat browsers
+  pogingen om `User-Agent` via `fetch` te zetten stilzwijgend negeren
+  (Node accepteert het wel, wat een inconsistent gedrag tussen runtimes
+  zou opleveren als `User-Agent` zelf gebruikt was).
+
+Geen SDK exposet Qdrant- of databaseconcepten.
+
+## Bewust niet geleverd
+
+Twee requirements uit een eerdere versie van dit document zijn bewust
+losgelaten, omdat ze niet passen bij wat er echt bestaat:
+
+- **Idempotency keys.** `search`/`context`/`answers` zijn stateless,
+  side-effect-vrije queries (geen enkele schrijft iets weg) -- een
+  idempotency key is een mechanisme tegen dubbele *schrijf*-operaties bij
+  een retry, en heeft dus geen functie hier. De retry-policy hierboven is
+  om diezelfde reden al veilig zonder een key.
+- **Cursor-iterators.** Geen van de drie endpoints heeft cursor-based
+  paginering (search/context/answers geven een vast-begrensde
+  resultatenset terug, geen paginated lijst); er is dus niets om te
+  itereren.