Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

2026-10-01 01:34:21 +02:00
commit 7ca726caf2
@@ -0,0 +1,54 @@
+# Design System
+
+## Visuele richting
+
+Professionele donkere beheerinterface met hoge informatiedichtheid zonder rommel. Neutrale oppervlakken, één primaire accentkleur, duidelijke typografische hiërarchie en consistente spacingtokens.
+
+## Componenten
+
+App shell, breadcrumb, page header, status badge, operation journey, metric card, data table, filter bar, form field, tabs, timeline, code block, citation card, confirmation dialog, toast en inline problem panel.
+
+## Tokens
+
+Gebruik CSS custom properties voor color, spacing, radius, shadow, typography en focus ring. Geen willekeurige inlinewaarden. Statuskleuren hebben tekst/iconen en geteste contrastverhoudingen.
+
+De producttokens staan in `static/admin.css` onder `:root`. De primaire
+accentkleur is warm amber op een diepe blauwzwarte basis; groen, rood en blauw
+blijven uitsluitend semantische statuskleuren. Panelen gebruiken een zichtbare
+rand en oppervlaktetint in plaats van overvloedige drop shadows. Gewone tekst
+blijft minimaal 13–14 px; 10–12 px is alleen voor korte labels en metadata.
+Iedere statusbadge combineert zijn tekst met een onderscheidend symbool
+(check, waarschuwing, fout, info of pending); kleur is nooit de enige drager.
+De operation journey gebruikt iconen en pijlen als compacte oriëntatie, maar
+blijft een semantisch gelabelde `nav` met echte links.
+
+## Productidentiteit en shell
+
+Het RAGCore-beeldmerk is een lokale inline SVG: begrenzende haken rond vier
+verbonden evidencepunten. Daardoor blijft het scherp zonder extern asset en
+herkenbaar in login en navigatie. De login koppelt de merkbelofte aan drie echte
+capabilities: governed sources, dense+sparse retrieval en cited answers.
+
+De desktop-shell houdt de gegroepeerde navigatie zichtbaar vanaf 1024 px.
+Tablet en mobiel gebruiken een focus-begrensde drawer met Escape-herstel; zo
+blijft op 768 px voldoende ruimte over voor inhoud. De topbar toont paginacontext,
+deployment environment en de vaste local-first architectuurrichting, geen
+verzonnen live status.
+
+## Responsive gedrag
+
+- 1024 px en breder: vaste zijbalk; dashboardflow vier of twee kolommen.
+- 768–1023 px: navigatiedrawer; inhoud over de volledige viewport.
+- 375–767 px: acties stapelen, metriekkaarten worden één kolom en de
+  source-to-answerflow wordt een verticale route.
+- Dichte Sources-, Documents- en Jobs-tabellen worden onder 768 px semantische
+  recordkaarten. Iedere cel herhaalt haar kolomlabel; filters worden één kolom
+  en gebruiken de volledige breedte. Op desktop blijft de tabelweergave intact.
+- De publieke login toont op tablet/mobiel eerst de SSO-actie en daarna de
+  productuitleg; de DOM- en focusvolgorde blijft logisch omdat de uitleg geen
+  interactieve elementen bevat.
+- `prefers-reduced-motion` reduceert alle animaties en transities tot één frame.
+
+## Query Lab
+
+Split view: links query/config; rechts resultaten. Tabs voor final, candidates, context, prompt en trace. Iedere kandidaat toont bron, space, scores, filters, location en inclusion/exclusion reason.
@@ -0,0 +1,25 @@
+# Screen Catalog
+
+## V1 schermen
+
+1. Sign-in/OIDC callback/failure.
+2. Dashboard — **vernieuwd in M10-01**: een source-to-answer capability map
+   (Sources, durable ingest, dense+sparse/RRF retrieval, grounded answers met
+   citations), plus geautoriseerde application/space/policy-tellingen, echte
+   health- en jobstatus, profile-activationstatus en links naar de bestaande
+   operationele schermen. Niet-geïmplementeerde backup- of indexacties worden
+   niet als dashboardstatus verzonnen.
+3. Workspaces/applications/service accounts.
+4. Knowledge spaces met policies en grants.
+5. Sources list/create/detail/sync history — **geïmplementeerd (1.2.0), operationele flow vernieuwd in M10-02**: `/admin/sources`, detail met Overview/Configuration/Documents/Sync history, acties Sync now/Pause/Resume/Edit/Delete (confirm + audit); folder/Git aanmaken, website nog niet. Documenttellingen linken naar het echte bronfilter en synchistorie onderscheidt wachtende child-ingests van complete en gedeeltelijk mislukte runs.
+6. Documents list/detail/versions/chunks/artifacts — **geïmplementeerd (1.2.0), operationele flow vernieuwd in M10-02**: `/admin/documents` workspace-breed met search/filter/paginering; detail met Overview/Chunks/Metadata/Versions/Jobs en failure-uitleg. Het bronfilter toont alleen een workspace-eigen bronnaam en paginering behoudt alle actieve filters.
+7. Jobs list/detail/events/retry — **geïmplementeerd (1.2.0)**: `/admin/jobs` en `/admin/jobs/{id}` met attempts/timing; retry alleen voor terminale jobs met retryable laatste fout. **1.2.1**: status- en typefilter en paginering draaien server-side in dezelfde workspace-gescopete query (niet meer als filter over een opgehaalde pagina), pagineringlinks behouden het actieve filter, en de vijf tellers boven de tabel blijven expliciet een scope-brede samenvatting van de wachtrij. **M10-02**: source/document/job-details linken onderling via de persistente, workspace-gescopete identiteit; vreemde, ontbrekende of voor de huidige rol onbereikbare relaties worden fail-closed niet als link gerenderd. Een retry-race eindigt als conflict en nooit als verzonnen succes.
+8. Query Lab: selector-first formulier (spaces, sources, documents, talen, content types, trust, profiel) + Advanced raw-ID's; inspector Summary/Candidates/Fusion/Context/Answer/Trace met dense/sparse rank+score en RRF-bijdragen; een rerank-sectie verschijnt alleen wanneer die stap actief is (nu niet).
+9. Profiles: embedding-profielactivatie/rollback (`/admin/profiles`); reranker- en retrievalprofielen hebben geen registry.
+10. Evaluations: suites, cases, runs en comparison — **niet als scherm geëxposeerd** (offline `EvaluationRunner`/JSON-stores; geen navigatie-entry).
+11. Auditlog met veilige filters — **niet als scherm geëxposeerd**; gedocumenteerde beperking.
+12. Operations: `/admin/system` (readiness, queue, versie, actief embeddingprofiel, Docling/OIDC/telemetry) — backup/restore/reindex blijven runbooks/scripts, geen lege navigatie.
+
+Navigatie (1.2.0): Overview · Knowledge (Spaces, Sources, Documents, Ingestion Jobs) · Access (Applications, Policies) · Quality (Query Lab, Profile Activation) · Operations (System Health).
+
+Iedere screen krijgt empty/loading/error/forbidden/degraded states en auditbare beheeracties. De drie operationele lijsten en hun detailtabellen schakelen onder 768 px naar gelabelde recordkaarten, zodat geen betekenis alleen in een verborgen tabelkop of horizontale scroll blijft zitten.
@@ -0,0 +1,56 @@
+# UX Specification
+
+## Technologie
+
+V1 gebruikt server-rendered Jinja2 + HTMX voor beheer en Query Lab. Dit houdt één deployment, gedeelde auth en weinig frontendbuildcomplexiteit. Een rijkere SPA is pas gerechtvaardigd door gemeten UX-beperkingen.
+
+## Principes
+
+- Desktop-first beheer maar volledig bruikbaar op tablet/mobiel.
+- Status en gevaar worden niet alleen door kleur gecommuniceerd.
+- Tabellen hebben zoek/filter/paginatie en behouden URL-state.
+- Destructieve acties tonen impact en vereisen bevestiging.
+- Langlopende acties tonen jobstatus en blijven na refresh volgen.
+- Query Lab verklaart retrieval in begrijpelijke lagen.
+- Geen gevoelige documenttekst in algemene dashboards.
+
+## Accessibility
+
+WCAG 2.2 AA-doel: keyboard navigation, zichtbare focus, labels, landmarks, contrast, reduced motion en semantische statusupdates.
+
+De mobiele navigatie verplaatst focus bij openen naar de eerste link, houdt Tab
+binnen de drawer en herstelt focus naar de menuknop bij Escape. Het hoofdgebied
+is een expliciet skip-linkdoel. Controls hebben op compacte viewports minimaal
+44 px bedieningshoogte; status blijft steeds als tekst beschikbaar.
+
+## Dashboard als capability map
+
+De eerste inhoud na de page header is de echte keten
+`Sources → Ingest → Retrieve → Answer`. De kaart gebruikt alleen vaste,
+geïmplementeerde capabilitytekst en geautoriseerde runtimegegevens: jobstatus en
+het aantal zichtbare applications. Retrieval heet expliciet dense+sparse met
+deterministische RRF-fusion; reranking wordt nergens als actieve stap voorgesteld.
+Iedere stap linkt naar het bestaande beheerscherm dat de operator nodig heeft.
+
+Onbereikbare stores en ontbrekende rechten worden als unavailable/restricted
+getoond. Een ontbrekende waarde wordt nooit als nul, healthy of success
+gepresenteerd. Algemene dashboards tonen geen documentinhoud.
+
+## Operationele bron-naar-zoekflow
+
+De schermen Sources, Documents en Ingestion Jobs vormen één navigeerbare keten
+`Source → Document → Processing`. Een compacte journey-balk blijft op lijst- en
+detailschermen zichtbaar. Details gebruiken de meest specifieke geautoriseerde
+relatie: bron naar zijn gefilterde documenten, document naar het producerende
+job en ingest-job terug naar het werkelijk geproduceerde document. Ontbrekende
+of workspace-vreemde relaties worden niet geraden en krijgen geen link. Ook
+generieke journey-stappen en lijstvelden linken alleen wanneer de huidige rol
+de doelroute werkelijk kan openen; opgeslagen failure-job-ID's worden opnieuw
+op bestaan en workspace-eigendom gecontroleerd voordat ze klikbaar worden.
+
+Filters en paginering blijven URL-state en behouden elkaar. Een bronfilter toont
+de geautoriseerde bronnaam; een onbekende of vreemde bron wordt alleen als
+onbeschikbaar omschreven. Syncuitkomsten onderscheiden discovery, wachtende
+child-ingests, volledige convergentie, gedeeltelijke mislukking en terminale
+mislukking. Hersteltekst verwijst naar de bestaande retry-actie wanneer die
+voor de gekoppelde job werkelijk beschikbaar kan zijn.