Init

docs/ARCHITECTURE.md

@@ -0,0 +1,202 @@
+# Architektur
+
+## Zielbild
+
+```text
+                           ┌─────────────────────┐
+                           │       GLPI          │
+                           └─────────┬───────────┘
+                                     │
+                                     ▼
+                           ┌─────────────────────┐
+                           │   GLPI AI Agent     │
+                           │ policies / actions  │
+                           └──────┬───────┬──────┘
+                                  │       │ events
+                   semantic query │       └──────────────┐
+                                  ▼                      ▼
+                     ┌─────────────────────┐      ┌──────────────┐
+                     │ NeuroForge Brain    │      │ Control      │
+                     │ HNSW / Disk-PQ      │      │ read-only    │
+                     │ NFVJ2 + SQAR        │      └──────────────┘
+                     │ memory / research   │
+                     │ validated outcomes  │
+                     └─────────┬───────────┘
+                               │ draft proposal only
+                               ▼
+                     ┌─────────────────────┐
+                     │ Knowledge Staging   │
+                     │ human review        │
+                     └─────────┬───────────┘
+                               │ promote
+                               ▼
+                     ┌─────────────────────┐
+                     │ Production KB       │
+                     └─────────┬───────────┘
+                               │ shared files / incremental scan
+                               └──────────────► Agent
+```
+
+## Verantwortungsgrenzen
+
+### GLPI AI Agent
+
+Bleibt die autoritative Schicht für:
+
+- Kategorien- und Prioritätslogik
+- Eskalation
+- Auto-Reply-Gates
+- GLPI-Schreiboperationen
+- Dry-Run
+- Idempotenz und Ticket-State
+- Hybrid-Scoring nach semantischer Kandidatensuche
+- Quellen-Allowlisten
+
+NeuroForge darf diese Regeln weder verändern noch umgehen.
+
+### NeuroForge
+
+Ist die autoritative Schicht für zentral externalisierte Chunk-Vektoren:
+
+- namespace-isolierte Knowledge-Chunks
+- HNSW-/Disk-PQ-Kandidatensuche
+- Vector Journal NFVJ2
+- SQAR-Kompression des Vector Journals
+- Brain-/Knowledge-Events
+- eigenes Learning/Research
+
+Die neue Integrations-API ist mit dem App Key geschützt und enthält bewusst keine Admin-Funktionen.
+
+### Knowledgebase
+
+Bleibt die Governance-Schicht:
+
+- kanonische JSON-Artikel
+- Editor
+- Suche
+- Staging
+- Backup
+- Review
+- Promotion
+
+Maschinelle Integrationen können nur Staging-Entwürfe ablegen.
+
+## Datenfluss für Retrieval
+
+```text
+Tickettext
+  -> Embedding-Profil des Agenten
+  -> NeuroForge namespace search
+  -> Top-N semantische Kandidaten
+  -> Agent ordnet Treffer Dokumenten zu
+  -> exakte lokale Titel-/Keyword-/Kategorie-/Lexikal-Signale
+  -> deterministischer Hybrid-Score
+  -> bestehende GLPI Policy-Gates
+  -> ggf. Aktion
+```
+
+Damit bleibt ANN ein Kandidatengenerator, nicht die finale Policy-Entscheidung.
+
+## Persistenz
+
+### Agent
+
+- lokale Knowledge-Metadaten und Chunks
+- Titelvektoren
+- im `local`/`dual`-Modus auch Chunk-Vektoren
+- Audit-/Run-/State-Dateien
+
+### NeuroForge
+
+- Memory/WAL/Segments
+- HNSW bzw. Disk-PQ
+- NFVJ2 Vector Journal
+- SQAR nur auf geeigneten Vektorblöcken
+
+### Knowledgebase
+
+- `knowledge/` produktiv
+- `staging/` ungeprüft
+- `backups/` Recovery
+
+## Konsistenzmodell
+
+Die JSON-Knowledgebase bleibt fachlich kanonisch. NeuroForge ist ein abgeleiteter semantischer Index. Dokument-IDs und Chunk-Indizes erzeugen deterministische NeuroForge-Memory-IDs. Änderungen ersetzen Chunks batchweise; entfernte Chunks werden entfernt. Dadurch kann ein kompletter Neuaufbau aus der Knowledgebase erfolgen.
+
+## Eventing
+
+Die vorhandenen `brainactivity`-Clients zeigen jetzt auf:
+
+```text
+POST /api/v1/integrations/events
+```
+
+Diese Events sind Telemetrie/Audit, keine Policy-Eingaben. Beispiele sind `knowledge.search` sowie Synchronisationsereignisse.
+
+
+## Kontrolliertes Lernmodell (v1.2.0)
+
+### Human Outcome Gate
+
+```text
+Ticket -> AI proposal -> technician accept/correct
+                         |
+                         v
+                  immutable local audit
+                         | App Key
+                         v
+             /api/v1/integrations/outcomes
+                         |
+                         v
+          trusted semantic outcome memory
+```
+
+Der Agent bestimmt nicht selbst die vertrauenswürdige Provenance. NeuroForge akzeptiert über diesen Pfad ausschließlich `accepted` und `corrected` und setzt `glpi.outcome.*` serverseitig. Eine spätere Korrektur wird als neue Outcome-Version mit `supersedes_id` geführt.
+
+### Optionaler Research-Layer
+
+```text
+             [compose profile: research]
+                      SearXNG
+                         |
+                         v
+Goal/manual research -> Search -> Fetch -> Evidence
+                                      |
+                                      v
+                         provenance + dedup +
+                         independent corroboration
+                                      |
+                                      v
+                              NeuroForge Memory
+                                      |
+                                      v
+                              KB staging only
+```
+
+Research-Infrastruktur und zeitgesteuerte Autonomie sind getrennt. `NEUROFORGE_AUTONOMY_ENABLED=false` verhindert selbstlaufende Goal-Cycles auch dann, wenn SearXNG und manuelles Research aktiv sind.
+
+## v1.3: Closed Outcome Feedback Loop
+
+Menschlich validierte Helpdesk-Erfahrung besitzt einen eigenen, schmalen Retrieval-Pfad:
+
+```text
+Agent ticket query
+   |--------------------------|
+   v                          v
+Knowledge namespace      Validated outcomes
+HNSW/PQ + hybrid         active accepted/corrected only
+   |                          |
+   +------------+-------------+
+                v
+          Reply selection
+                |
+      Knowledge ID allow-list
+                |
+          Policy gates / GLPI
+```
+
+Die beiden Evidenzklassen werden absichtlich nicht vermischt. Outcome-Memories liegen im NeuroForge-Brain und sind Trust-/Revision-basiert; Knowledge bleibt die veröffentlichte Autorität. Bei Korrekturen bleiben alte Memories auditierbar, wechseln aber auf `superseded` und sind nicht mehr search-active.
+
+Für source-begrenzte Exact-Fallbacks hält der Store einen rebuildbaren In-Memory-Index `Provenance.Source -> Memory IDs`. Damit wächst der Fallback mit der betreffenden Integration/Source statt mit dem gesamten Memory-Katalog. HNSW/Disk-PQ bleiben globale Kandidatenindizes.
+
+Die Qualitätsmessung ist vom Schreibpfad getrennt: `/api/quality/replay` ist read-only und evaluiert live die aktuelle Knowledge-/Outcome-Retrieval-Konfiguration gegen einen bereitgestellten historischen Fallkorpus.

docs/CODEBASE-MEMORY-MCP.md

@@ -0,0 +1,26 @@
+# Optional Codebase Memory MCP integration
+
+`codebase-memory-mcp` is an optional developer tool, not a production dependency and not an authoritative NeuroForge store. The project uses its structural-code-graph ideas while retaining an in-repo Go AST/Compose snapshot for reproducibility.
+
+## Why optional
+
+The external tool can provide deeper MCP/Cypher/code-navigation and its own rich graph UI. The Mega project's runtime, GLPI decisions, learning and Control Center do not depend on it.
+
+## Local use
+
+Install `codebase-memory-mcp` according to the upstream project, then run:
+
+```sh
+./scripts/codebase-memory-ui.sh
+```
+
+The helper sets `CBM_ALLOWED_ROOT` to this repository, indexes it through the upstream CLI and starts the optional UI (default port 9749). `.cbmignore` keeps generated/runtime data out of indexing.
+
+To expose its status/link in the Control Center set, as appropriate for your host/network:
+
+```env
+CODEBASE_MEMORY_URL=http://host.docker.internal:9749
+PUBLIC_CODEBASE_MEMORY_URL=http://localhost:9749
+```
+
+Leave `CODEBASE_MEMORY_URL` empty when the Control container should not health-check the developer service. The component is always optional and never affects platform readiness.

docs/CONTROL-CENTER.md

@@ -0,0 +1,48 @@
+# Control Center und Interaktion
+
+Das Control Center ist absichtlich read-only. Es ist eine Beobachtungs- und Navigationsschicht, nicht der gemeinsame Super-Admin der Plattform.
+
+## Warum read-only?
+
+Ein einziges Dashboard mit GLPI-Schreibrechten, Knowledge-Editor-Rechten und NeuroForge-Admin-Token würde bei einem Fehler oder einer Kompromittierung alle Trust Boundaries gleichzeitig aufheben. Das Mega-Projekt trennt deshalb Statussicht und Schreibrechte.
+
+## Wo Daten verändert werden
+
+- **GLPI Agent:** policy-gated Ticket-/Followup-/Kategorie-/Eskalationsaktionen.
+- **Knowledgebase:** Artikel bearbeiten, Staging prüfen und nach menschlicher Freigabe promoten.
+- **NeuroForge Admin:** Brain-/Storage-/Provider-Verwaltung mit separatem Admin-Token.
+- **Integration Draft API:** maschinelle Vorschläge ausschließlich nach Staging; `auto_reply=false` wird serverseitig erzwungen.
+
+Das Control Center verlinkt diese Oberflächen und aggregiert Health/Readiness sowie die aktiven Vektor-Migrationsparameter. Es besitzt selbst keine Route, die Produktionsdaten verändert.
+
+## Erweiterungsregel
+
+Falls zentrale Aktionen später direkt im Control Center benötigt werden, sollten sie als einzelne delegierte Operationen mit eigenem Scope, Audit-Eintrag und expliziter Bestätigung implementiert werden. Die Admin-Credentials der Zielsysteme sollen nicht pauschal im Control Center hinterlegt werden.
+
+
+## v1.2.0: Controlled-Autonomy-Status
+
+Das Control Center zeigt zusätzlich die effektiven Stack-Schalter für:
+
+- Controlled Learning
+- Outcome Learning
+- Research/SearXNG
+- Autonomy
+
+Diese Anzeigen sind bewusst nur Beobachtung. Das Aktivieren von Research oder Autonomy erfolgt über Betreiberkonfiguration/Compose bzw. NeuroForge-Admin, nicht über einen globalen Super-Admin-Schalter im Control Center.
+
+## v1.3.0: Lernwirkung sichtbar machen
+
+Das Control Center zeigt zusätzlich:
+
+- Outcome Retrieval an/aus
+- Retrieval-K
+- Similarity-Floor
+- fail-open/fail-closed der Erfahrungs-Suche
+- Verfügbarkeit des read-only Quality-Replay-Endpunkts im Agenten
+
+Die eigentlichen Laufzeitmetriken und Einzelfall-Evidenzen bleiben beim Agenten bzw. Prometheus. Das Control Center erhält dafür weiterhin keine Outcome-Schreib- oder NeuroForge-Adminrechte.
+
+## v1.4 Unified Graph Explorer
+
+The Control Center remains read-only. Its graph views use a dedicated Agent `CONTROL_READ_TOKEN` and the scoped NeuroForge app key. The Engineering Graph is embedded from a reproducible Go AST/Compose snapshot; optional Codebase Memory MCP is developer-only. See `UNIFIED-GRAPH.md`.

docs/CONTROL-MATRIX.md

@@ -0,0 +1,83 @@
+# Kontroll- und Berechtigungsmatrix
+
+| Capability | Agent | KB Editor | NeuroForge App API | NeuroForge Admin | Control Center |
+|---|---:|---:|---:|---:|---:|
+| GLPI lesen | ja | nein | nein | nein | nein |
+| GLPI schreiben | nur Policy-gated | nein | nein | nein | nein |
+| Produktive KB lesen | ja | ja | indirekt über Sync | nein | nein |
+| Produktive KB schreiben | nein | ja | nein | nein | nein |
+| KB-Staging schreiben | nein | ja | über getrennten KB Integration Token möglich | nein | nein |
+| KB-Staging promoten | nein | ja | nein | nein | nein |
+| Knowledge-Vektoren upserten | ja, App Key | nein | ja | ja | nein |
+| Knowledge-Vektoren suchen | ja, App Key | nein | ja | ja | nein |
+| NeuroForge Config ändern | nein | nein | nein | ja | nein |
+| NeuroForge Secrets lesen/rotieren | nein | nein | nein | ja | nein |
+| Systemstatus lesen | eigene Readiness | eigene Health | Stats mit App Key | ja | aggregiert read-only |
+| Obsidian-Export | Live-Sicht inkl. GLPI-Relations | kanonische KB | nein | nein | verlinkt Ziel-UI |
+| Human Outcome erfassen | ja, authentifizierter Techniker | nein | empfängt nur validated outcome | sichtbar/admin | Status read-only |
+| Trusted Outcome-Source setzen | nein | nein | **serverseitig fest** | ja | nein |
+| SearXNG Research | nein | nein | Research Engine via SearXNG | konfigurierbar | Status read-only |
+| Autonomy aktivieren | nein | nein | nein | Betreiber/Admin bzw. Env | Status read-only |
+
+## Credentials
+
+- `NEUROFORGE_ADMIN_TOKEN`: nur Betreiber/Admin.
+- `NEUROFORGE_APP_API_KEY`: Agent und read-only Control-Stats; keine Admin-Config.
+- `NEUROFORGE_WORKER_TOKEN`: nur NeuroForge Worker.
+- `NEUROFORGE_METRICS_TOKEN`: nur Metrics-Scraper.
+- `KB_INTEGRATION_TOKEN`: ausschließlich maschineller Staging-Ingress.
+- `BASIC_AUTH_USER/PASSWORD`: Knowledgebase-Editor.
+- `WEB_USERNAME/PASSWORD`: Agent-Webzugang.
+- `SEARXNG_SECRET`: nur optionaler SearXNG-Container/Betreiber.
+- GLPI-Credentials: ausschließlich Agent.
+
+## Failure-Policy
+
+| Einstellung | NeuroForge nicht erreichbar | Verhalten |
+|---|---|---|
+| `local` | irrelevant | Agent bleibt vollständig lokal |
+| `dual` | Fehler wird geloggt | lokale Vektoren bleiben erhalten |
+| `neuroforge` + fail-open | Fehler wird geloggt | lokale/lexikalische Evidenz soweit verfügbar |
+| `neuroforge` + fail-closed | Fehler wird propagiert | semantischer Schritt blockiert kontrolliert |
+
+## Outcome-Learning Failure-Policy
+
+| Einstellung | NeuroForge-Sync nach Technikerentscheidung | Verhalten |
+|---|---|---|
+| `OUTCOME_LEARNING_ENABLED=false` | nicht ausgeführt | kein Outcome-Learning |
+| enabled + `FAIL_OPEN=false` | Fehler | lokaler Audit bleibt `failed`, UI meldet Fehler |
+| enabled + `FAIL_OPEN=true` | Fehler | lokaler Audit bleibt `failed`, Workflow darf fortfahren |
+| enabled + Sync OK | Erfolg | Audit `learned` + NeuroForge Memory-ID |
+
+## Nicht lernende Kontrollinformationen
+
+Folgende Informationen bleiben absichtlich außerhalb des NeuroForge-Learnings:
+
+- GLPI OAuth/API-Secrets
+- Auto-Reply-Policy
+- Eskalationsregeln
+- Idempotenz-/Run-State
+- Schreibfreigaben
+- Source-Allowlisten
+- Review-/Promotion-Status
+
+## v1.3 zusätzliche Daten- und Aktionsgrenzen
+
+| Akteur | Outcome suchen | Outcome lernen | Outcome superseden | Quality Replay | Auto-Reply autorisieren |
+|---|---:|---:|---:|---:|---:|
+| GLPI Agent App-Key | ja, nur aktives validated Outcome API | ja, accepted/corrected | indirekt nur über neue korrigierte Revision | nein über NeuroForge; eigener read-only Agent-Endpunkt | nur über bestehende Agent-Policies + freigegebene KB |
+| Agent Web-Operator | indirekt sichtbar | explizit bestätigen/korrigieren | durch Korrektur | ja, authentifiziert/read-only | nicht durch Outcome allein |
+| NeuroForge Admin | technische Brain-Administration | technisch ja | technisch ja | nein | nein |
+| Control Center | Status/Konfiguration sichtbar | nein | nein | Verfügbarkeit sichtbar | nein |
+| Research/SearXNG | nein | Research-Evidence, nicht trusted outcome | nein | nein | nein |
+
+`POST /api/v1/integrations/outcomes/search` akzeptiert den NeuroForge App-Key und liefert ausschließlich aktive Memories der serverseitig festgelegten Outcome-Provenance. Es ist kein generischer Memory-Search-Endpunkt und gewährt keine Admin-Funktionen.
+
+### v1.4 graph scopes
+
+| Actor | Capability | Credential | Write authority |
+|---|---|---|---|
+| Control -> Agent | runs/evidence/learning graphs | `CONTROL_READ_TOKEN` | none |
+| Control -> NeuroForge | research/brain graph | app API key | none through graph endpoints |
+| Control -> embedded Engineering Graph | structural read | none/internal | none |
+| Optional Codebase Memory MCP | developer code analysis | local process / allowed root | none in platform |

docs/CONTROLLED-AUTONOMY.md

@@ -0,0 +1,161 @@
+# Kontrollierte Autonomie und Outcome-gated Learning
+
+Stand: v1.3.0
+
+## Ziel
+
+NeuroForge soll recherchieren und lernen können, ohne KI-Ausgaben automatisch mit bestätigtem Betriebswissen gleichzusetzen. Der Release trennt deshalb drei Vertrauensklassen:
+
+| Klasse | Beispiele | Standard-Trust | Freigabe |
+|---|---|---:|---|
+| Rohes Modell-/Chat-Signal | `chat.input`, `chat.response` | 0.25 / 0.20 im Controlled Mode | kein automatisches Langzeitlernen |
+| Quellengebundene Research-Evidence | `web.search`, `web.page` | 0.45 / 0.60 | Provenance + Dedup + unabhängige Corroboration |
+| Menschlich validiertes Helpdesk-Outcome | `glpi.outcome.accepted`, `glpi.outcome.corrected` | 1.00 | explizite Technikeraktion |
+
+Die Werte sind eine Ranking-/Learning-Policy, keine Behauptung absoluter Wahrheit. Auch menschlich bestätigtes Wissen bleibt mit Ticket, Run, Actor und Outcome-ID nachvollziehbar.
+
+## Helpdesk-Lernpfad
+
+```text
+GLPI Ticket
+   |
+   v
+Agent analysiert + erzeugt Antwortvorschlag
+   |
+   v
+Techniker prüft
+   |--------------------|
+   v                    v
+bestätigt            korrigiert
+   |                    |
+   +---------+----------+
+             v
+      lokales Outcome-Audit
+             |
+             v
+ POST /api/v1/integrations/outcomes
+             |
+             v
+ NeuroForge Semantic Memory
+```
+
+Vor dem Persistieren liest der Agent bei aktuellen Runs den Ticketzustand erneut aus GLPI und vergleicht ihn mit `SourceVersion`. Hat sich der entscheidungsrelevante Ticketzustand geändert, wird die Validierung blockiert und ein neuer Agent-Run verlangt.
+
+Nur `accepted` und `corrected` sind zulässig. Der Client kann die vertrauenswürdige Source nicht frei setzen; NeuroForge erzeugt serverseitig `glpi.outcome.accepted` bzw. `glpi.outcome.corrected`.
+
+### Audit und Revisionen
+
+`services/agent` speichert Entscheidungen in `DATA_DIR/ticket-outcomes.json`:
+
+- `pending`: lokal erfasst, Sync noch offen
+- `learned`: NeuroForge hat eine Memory-ID bestätigt
+- `failed`: Entscheidung bleibt erhalten, Remote-Sync ist fehlgeschlagen
+- `supersedes_id`: verweist bei einer späteren Korrektur/Neubewertung auf den vorigen Outcome
+
+Eine exakt wiederholte Entscheidung ist idempotent. Bereits erfolgreich gelernte Outcomes werden nicht ein zweites Mal an NeuroForge gesendet. Ein `failed`-Outcome kann dagegen bewusst erneut synchronisiert werden.
+
+Ab v1.3.0 wird eine Revision auch im NeuroForge-Store wirksam: eine neue Korrektur markiert den Vorgänger atomar als `superseded` und trägt die Revisionskante auf der neuen Memory ein. Supersedete Memories bleiben für Audit/History erhalten, werden aber von semantischer Suche ausgeschlossen.
+
+`OUTCOME_LEARNING_FAIL_OPEN=false` ist der kontrollierte Standard: Ein Remote-Fehler wird dem Techniker sichtbar zurückgegeben. `true` ist nur sinnvoll, wenn lokale Audit-Erfassung wichtiger ist als sofortige zentrale Konsistenz.
+
+## Validierte Erfahrung wiederverwenden
+
+Der geschlossene Lernkreis verwendet aktive menschliche Outcomes bei späteren Tickets als sekundäre Evidenz:
+
+```text
+neues Ticket
+   |
+   +--> offizielle Knowledge-Kandidaten -----------+
+   |                                               |
+   +--> NeuroForge Outcome Retrieval --------------+
+                                                   v
+                                          Reply-Auswahl
+                                                   |
+                                    nur Knowledge-ID aus
+                                    offizieller Kandidatenliste
+```
+
+Konfiguration:
+
+```env
+OUTCOME_RETRIEVAL_ENABLED=true
+OUTCOME_RETRIEVAL_SEARCH_K=6
+OUTCOME_RETRIEVAL_MIN_SIMILARITY=0.58
+OUTCOME_RETRIEVAL_FAIL_OPEN=true
+```
+
+Die Outcome-Suche greift ausschließlich auf aktive `glpi.outcome.accepted` und `glpi.outcome.corrected` Memories zu. Der LLM-Systemprompt weist zusätzlich explizit an, dass diese Erfahrungen einen Knowledge-Artikel nur stützen oder widerlegen dürfen. Sie dürfen niemals selbst einen Auto-Reply autorisieren oder eine nicht im Artikel belegte Lösung einführen.
+
+Der Agent protokolliert die verwendeten Outcome-Kandidaten, Similarity, Suchdauer und Fehler pro Run. Prometheus enthält Such-, Treffer-, Fehler- und Learning-Zähler.
+
+## Wirkung messen
+
+`POST /api/quality/replay` ist eine read-only Qualitätsprüfung gegen historische Fälle. Sie meldet Knowledge Recall@K/MRR und Outcome Recall@K/MRR. `experience_rescued_cases` zählt konservativ Fälle, in denen die erwartete offizielle KB nicht in Top-K lag, aber eine aktive validierte Erfahrung die erwarteten Lösungsterme enthielt. Das ist ein Learning-Lift-Indikator, keine automatische Produktionsfreigabe.
+
+Siehe `docs/QUALITY-REPLAY.md`.
+
+## Controlled Learning
+
+`NEUROFORGE_CONTROLLED_LEARNING=true` setzt beim Serverstart eine konservative Policy:
+
+- `learn_chat_inputs=false`
+- `learn_chat_responses=false`
+- `allow_explicit_learn=true`
+- `allow_imports=false`
+- `learn_goal_cycles=false`
+- höhere Mindestanforderungen für semantische Konsolidierung
+- niedriger Trust für Web-/Chat-Signale
+- maximaler Trust für explizite GLPI-Outcomes
+
+Damit ist „das Modell hat es gesagt“ kein Lernsignal. Lernen braucht entweder einen expliziten, kontrollierten API-Pfad oder quellengebundene Evidence.
+
+## Research und SearXNG
+
+SearXNG ist im Root-Compose als Profil `research` definiert und wird im normalen `docker compose up` nicht gestartet.
+
+### Research manuell freischalten
+
+1. In `.env` einen zufälligen `SEARXNG_SECRET` setzen. Für reproduzierbare Produktion `SEARXNG_IMAGE` auf einen freigegebenen Tag oder Digest pinnen.
+2. Research starten:
+
+```bash
+./scripts/research-up.sh
+```
+
+Das Script aktiviert für diesen Compose-Aufruf:
+
+```text
+NEUROFORGE_RESEARCH_ENABLED=true
+NEUROFORGE_SEARXNG_ENABLED=true
+```
+
+Es aktiviert **nicht** automatisch `NEUROFORGE_AUTONOMY_ENABLED`.
+
+### Autonomie bewusst separat aktivieren
+
+Für zeitgesteuerte, selbstinitiierte Goal-Cycles zusätzlich in `.env`:
+
+```text
+NEUROFORGE_AUTONOMY_ENABLED=true
+```
+
+Ein Goal muss zusätzlich `auto_run`/Research erlauben. Damit sind die infrastrukturelle Suchfähigkeit, manuelles Research und zyklische Autonomie getrennt kontrollierbar.
+
+## Research-Vertrauen
+
+Research-Inhalte werden als untrusted external data behandelt. NeuroForge hält Source-URI, Source-ID, Hash, Retrieval-Zeitpunkt und Evidence-Quellen fest. Ähnliche Evidence aus einer weiteren unabhängigen Source erhöht `EvidenceCount` und Confidence über die Corroboration-Logik, statt einen einzelnen Treffer sofort auf Trust 1.0 zu setzen.
+
+Research darf außerdem nicht direkt produktive Knowledge-Artikel veröffentlichen. Der vorhandene Maschinenpfad endet beim token-geschützten KB-Staging; `auto_reply=false` wird dort serverseitig erzwungen. Promotion bleibt eine menschliche Entscheidung.
+
+## Empfohlener Produktionsmodus
+
+```text
+NEUROFORGE_CONTROLLED_LEARNING=true
+OUTCOME_LEARNING_ENABLED=true
+OUTCOME_LEARNING_FAIL_OPEN=false
+NEUROFORGE_RESEARCH_ENABLED=false
+NEUROFORGE_SEARXNG_ENABLED=false
+NEUROFORGE_AUTONOMY_ENABLED=false
+```
+
+Research anschließend gezielt aktivieren, beobachten und erst danach – falls gewünscht – Autonomy einschalten.

docs/IMPLEMENTED.md

@@ -0,0 +1,37 @@
+# Implementierungsstand
+
+## Implementiert
+
+- gemeinsames Monorepo mit `go.work`
+- gemeinsamer Docker-Compose-Stack
+- zentraler Ollama-Endpunkt für Agent/KB/NeuroForge
+- NeuroForge + NFVJ2/SQAR Vector Journal
+- App-Key-geschützte NeuroForge Knowledge Integration API
+- namespace-isolierte semantische Suche
+- Batch-Upsert/Batch-Delete für Knowledge-Chunks
+- Agent `local` / `dual` / `neuroforge` Betriebsmodi
+- explizites fail-open / fail-closed
+- Remote-Semantik bleibt nur Evidenz; Agent-Hybrid-/Policy-Logik bleibt autoritativ
+- inkrementelle Updates und Löschungen in NeuroForge
+- vorhandene Brain-Activity-Hooks auf NeuroForge Events
+- read-only Control Center
+- gemeinsames produktives `knowledge/` mit KB-RW / Agent-RO
+- separater Bearer-geschützter Research-/Integration-Draft-Ingress in KB-Staging
+- Research-Drafts können nicht produktiv schreiben und erzwingen `auto_reply=false`
+- getrennte Secrets für Admin, App, Worker, Metrics und KB-Staging-Integration
+- Tests für Namespace-Isolation, Lifecycle, Fail-open/fail-closed und Staging-Governance
+- optionaler SearXNG-Service als Compose-Profil `research`
+- Controlled-Learning-Bootstrap ohne automatisches Chat-Input/Assistant-Output-Lernen
+- Human-Outcome-Learning (`accepted`/`corrected`) über separaten App-Key-Endpunkt
+- lokales Outcome-Audit mit `pending|learned|failed`, Retry und unveränderlicher Revisionskette
+- Stale-Run-Schutz gegen Lernen aus überholten GLPI-Ticketzuständen
+- getrennte Schalter für Research/SearXNG und zeitgesteuerte Autonomie
+
+## Bewusst nicht automatisiert
+
+- Kein NeuroForge-Research-Run wird ohne expliziten Workflow automatisch zum KB-Entwurf.
+- Kein KB-Entwurf wird automatisch promoted.
+- Keine GLPI-Automation wird durch die Vektormigration automatisch aktiviert.
+- Das Control Center besitzt keine Admin-Aktionen.
+
+Diese Grenzen sind Teil des Kontrollmodells und können später gezielt über signierte/approvable Jobs erweitert werden.

docs/MIGRATION-CUTOVER.md

@@ -0,0 +1,85 @@
+# Kontrollierter Cutover
+
+## Phase 0 – Baseline
+
+```env
+KNOWLEDGE_VECTOR_BACKEND=local
+DRY_RUN=true
+AUTO_CATEGORY=false
+AUTO_REPLY=false
+AUTO_PRIORITY=false
+AUTO_ESCALATION=false
+```
+
+Ziel: unverändertes Agent-Verhalten und Baseline-Metriken sichern.
+
+## Phase 1 – Dual Mirror
+
+```env
+KNOWLEDGE_VECTOR_BACKEND=dual
+NEUROFORGE_FAIL_OPEN=true
+```
+
+Der Agent behält lokale Chunk-Vektoren und synchronisiert dieselben Dokumente zusätzlich nach NeuroForge. Suchentscheidungen bleiben lokal. Beobachten:
+
+- Sync-Fehler im Agent-Log
+- NeuroForge Memory-/Index-Wachstum
+- Vector-Journal-Größe
+- Retrieval-Latenz der Baseline
+- keine Änderungen an GLPI-Aktionen
+
+Rollback: `KNOWLEDGE_VECTOR_BACKEND=local` und Agent neu starten.
+
+## Phase 2 – NeuroForge Candidate Search
+
+```env
+KNOWLEDGE_VECTOR_BACKEND=neuroforge
+NEUROFORGE_FAIL_OPEN=true
+```
+
+NeuroForge liefert semantische Kandidaten. Der Agent bleibt Besitzer des finalen Hybrid-Scores und aller Policies. Nach erfolgreicher Synchronisation können lokale Chunk-Vektoren aus dem normalen Snapshot externalisiert werden; Titelvektoren und Text-/Metadaten bleiben lokal.
+
+Rollback: auf `dual` oder `local` zurückstellen. Die kanonischen Knowledge-JSON-Dateien sind unverändert und können den semantischen Index neu aufbauen.
+
+## Phase 3 – Optional fail-closed
+
+Erst nach stabiler Betriebsphase:
+
+```env
+NEUROFORGE_FAIL_OPEN=false
+```
+
+Damit werden semantische Backend-Ausfälle sichtbar blockierend statt degradierend behandelt. Diese Einstellung ist sinnvoll, wenn eine Antwort ohne zentralen semantischen Index nicht zulässig sein soll.
+
+## Phase 4 – GLPI-Automation separat freigeben
+
+Die Vektormigration ist **keine** Freigabe für automatische GLPI-Aktionen. Jede Automation wird unabhängig aktiviert und getestet:
+
+```env
+DRY_RUN=false
+AUTO_CATEGORY=true|false
+AUTO_REPLY=true|false
+AUTO_PRIORITY=true|false
+AUTO_ESCALATION=true|false
+```
+
+Auto-Reply sollte zuletzt aktiviert werden.
+
+## Vergleichsstrategie
+
+Vor dem Umschalten auf `neuroforge` sollten repräsentative Tickets in `local` und `dual` mit denselben Modellen getestet werden. Zu vergleichen sind mindestens:
+
+- Top-1/Top-k Knowledge-ID
+- semantischer Teilscore
+- finaler Hybrid-Score
+- Schwellenwertentscheidungen
+- Kategorie-/Prioritätsentscheidung
+- Antwortfreigabe
+- Latenz
+
+## Recovery
+
+- Produktive Knowledge-JSONs sind kanonisch.
+- NeuroForge-Semantik kann aus diesen Daten neu aufgebaut werden.
+- Staging ist getrennt und kann nicht versehentlich produktiv werden.
+- NFVJ2/SQAR ist eine Storage-Optimierung; fachliche IDs und Vektoren bleiben verlustfrei rekonstruierbar.

docs/MIGRATION-MANIFEST.md

@@ -0,0 +1,115 @@
+# Migration Manifest
+
+## NeuroForge
+
+Neu/erweitert:
+
+- `internal/httpapi/integration.go` – App-Key-geschützte Knowledge-/Event-Integrationsendpunkte
+- `internal/httpapi/integration_api_test.go` – Lifecycle, Auth und Namespace-Isolation
+- `internal/store/store.go` – provenance-gefilterte semantische Suche
+- `internal/store/batch.go` – Batch-Delete zur Vermeidung mehrfacher ANN-Rebuilds
+- `cmd/server/main.go` – gemeinsamer Ollama-Endpunkt per Mega-Environment
+- vorhandene NFVJ2/SQAR-Vector-Journal-Migration bleibt Bestandteil der Plattform
+
+## GLPI AI Agent
+
+Neu/erweitert:
+
+- `internal/knowledge/neuroforge_backend.go` – SemanticBackend + NeuroForge HTTP-Client
+- `internal/knowledge/store.go` – Hybrid-Retrieval mit `local`/`dual`/`neuroforge`
+- `internal/knowledge/persistent_index.go` – inkrementelle Sync-/Externalisierungslogik
+- `internal/config/config.go` – kontrollierbare Backend-/Failure-Parameter
+- `cmd/agent/main.go` – Backend-Wiring
+- Tests für Remote-Evidenz und fail-open/fail-closed
+
+## GLPI AI Knowledgebase
+
+Neu/erweitert:
+
+- `internal/staging/staging.go` – quellenbewusste Staging-Proposals
+- `cmd/server/app.go` – `POST /api/integrations/staging`
+- `cmd/server/main.go` – Health und Staging-Ingress ohne Weitergabe von Editor-Credentials
+- Tests für Staging-only-Governance und Auth-Grenzen
+
+## Mega Platform
+
+Neu:
+
+- `docker-compose.yml`
+- `go.work`
+- `.env.example`
+- `services/control/` – read-only Control Center
+- `scripts/validate.sh`
+- `scripts/status.sh`
+- `scripts/generate-secrets.sh`
+- `scripts/propose-draft.sh`
+- gemeinsame `knowledge/`, `staging/`, `backups/`
+- Architektur-, Kontroll-, Cutover-, Betriebs- und Validierungsdokumentation
+
+## Version 1.1.0 – GLPI Relations & Obsidian Export
+
+- GLPI-KB-Sync liest verfügbare `KnowbaseItem_Item`-Relationen über die installierte OpenAPI.
+- `linked_items` werden im Agent-Knowledge-Modell erhalten.
+- Knowledgebase und Agent exportieren Obsidian-kompatible ZIP-Vaults.
+- Exporte enthalten YAML-Frontmatter, Wikilinks, Schema, Index, Manifest und `graph.json`.
+- Neuer CLI-Helfer: `scripts/export-obsidian.sh`.
+- Control-Center-Sicherheitsgrenze und delegierte Interaktionswege sind in `docs/CONTROL-CENTER.md` dokumentiert.
+- Repräsentativer Export-Snapshot liegt unter `exports/knowledge-obsidian-snapshot.zip`.
+
+## Version 1.2.0 – Controlled Autonomy
+
+### NeuroForge
+
+- `internal/httpapi/outcomes.go` – schmaler App-Key-Pfad für menschlich validierte Ticket-Outcomes
+- `internal/brain/brain.go` – interne, nicht vom JSON-Client spoofbare Trusted-Provenance-Felder
+- `cmd/server/main.go` – Controlled-Learning- und Research-Bootstrap per Environment
+- `deploy/learning-policy.example.json` – konservative Source-Trust-/Learning-Policy
+
+### GLPI AI Agent
+
+- `internal/learning/outcomes.go` – persistentes Outcome-Audit, Sync-Status, Revisionen und NeuroForge-Sink
+- `internal/agent/agent.go` – Stale-Run-Prüfung und Outcome-gated Learning
+- `internal/web/server.go` / Dashboard – Bestätigen/Korrigieren und Audit-Sicht
+- neue Outcome-Learning-Konfiguration mit explizitem fail-open/fail-closed
+
+### Mega Platform
+
+- `searxng` als optionaler Compose-Profilservice `research`
+- `deploy/searxng/settings.yml`
+- `scripts/research-up.sh`
+- separate Research-, SearXNG- und Autonomy-Schalter
+- Control Center zeigt diese Betriebsmodi read-only
+- `docs/CONTROLLED-AUTONOMY.md`
+- `docs/MIGRATION-v1.1.0-to-v1.2.0.md`
+- `RELEASE-NOTES-v1.2.0.md`
+- `patches/v1.1.0-to-v1.2.0.diff`
+
+## Version 1.3.0 – Closed Learning Loop
+
+### NeuroForge
+
+- `internal/store/source_index.go` – rebuildbarer Provenance-Source-Index und atomare Memory-Supersession
+- `internal/store/store.go` – source-begrenzter Exact-Fallback statt Full-Catalog-Scan
+- `internal/brain/brain.go` – Multi-Source-Outcome-Suche
+- `internal/httpapi/outcomes.go` – aktive Outcome-Suche + Remote-Supersession
+- `internal/httpapi/metrics.go` – NFVJ2/SQAR Savings-/Block-Metriken
+- Tests für aktive Revision, supersedete Revision und Source-Index-Rebuild nach Neustart
+
+### GLPI AI Agent
+
+- `internal/learning/outcomes.go` – OutcomeRetriever über den schmalen NeuroForge-App-Key-Pfad
+- `internal/agent/agent.go` – validierte Erfahrung als sekundärer Reply-Kontext + Learning/Retrieval-KPIs
+- `internal/model/model.go` – auditierbare `ValidatedOutcomeEvidence`
+- `internal/ollama/client.go` – Prompt-Guard: Outcome darf nur KB stützen/widerlegen, nie selbst autorisieren
+- `internal/web/server.go` – read-only `/api/quality/replay` und Statusmetriken
+- Dashboard zeigt verwendete Erfahrungen, Similarity, Dauer und Fehler
+
+### Mega Platform
+
+- `scripts/quality-replay.py`
+- `docs/QUALITY-REPLAY.md`
+- `docs/QUALITY-REPLAY-example.json`
+- `docs/MIGRATION-v1.2.0-to-v1.3.0.md`
+- `RELEASE-NOTES-v1.3.0.md`
+- Control Center zeigt Outcome Retrieval und Replay-Verfügbarkeit read-only
+- Upgrade-Patch: `patches/v1.2.0-to-v1.3.0.diff`

docs/MIGRATION-v1.1.0-to-v1.2.0.md

@@ -0,0 +1,44 @@
+# Migration v1.1.0 → v1.2.0
+
+## 1. Neue Secrets übernehmen
+
+```bash
+./scripts/generate-secrets.sh
+```
+
+Zusätzlich wird `SEARXNG_SECRET` ausgegeben. SearXNG ist optional; der Secret wird erst für das `research`-Profil benötigt.
+
+## 2. Controlled Learning prüfen
+
+Empfohlen:
+
+```text
+NEUROFORGE_CONTROLLED_LEARNING=true
+OUTCOME_LEARNING_ENABLED=true
+OUTCOME_LEARNING_FAIL_OPEN=false
+```
+
+Bestehende NeuroForge-Daten werden nicht gelöscht. Der Modus ändert, welche neuen Signale automatisch gelernt werden.
+
+## 3. Human Outcome Flow verwenden
+
+Neue Agent-Runs speichern den für Learning benötigten Ticket-/Reply-Snapshot. Alte Runs aus v1.1.0 können deshalb bewusst nicht nachträglich als validiertes Outcome gelernt werden, wenn dieser Snapshot fehlt.
+
+Im Agent-Dashboard den Run öffnen und **KI-Antwort bestätigen** bzw. **KI-Antwort korrigieren** verwenden.
+
+## 4. Research optional starten
+
+```bash
+./scripts/research-up.sh
+```
+
+Das startet das Compose-Profil `research` und aktiviert SearXNG/Research für den NeuroForge-Start. Zyklische Autonomie bleibt separat deaktiviert, solange `NEUROFORGE_AUTONOMY_ENABLED=false` ist.
+
+## 5. Rollback
+
+- SearXNG stoppen: `docker compose --profile research stop searxng`
+- Research deaktivieren: `NEUROFORGE_RESEARCH_ENABLED=false`, `NEUROFORGE_SEARXNG_ENABLED=false`
+- Autonomy deaktivieren: `NEUROFORGE_AUTONOMY_ENABLED=false`
+- Outcome Learning deaktivieren: `OUTCOME_LEARNING_ENABLED=false`
+
+Das lokale Outcome-Audit und bereits gelernte Memories werden dadurch nicht gelöscht.

docs/MIGRATION-v1.2.0-to-v1.3.0.md

@@ -0,0 +1,61 @@
+# Migration v1.2.0 -> v1.3.0
+
+## Ziel
+
+v1.3.0 schließt den Outcome-Learning-Kreis und ergänzt Messbarkeit. Bestehende v1.2.0-Outcomes bleiben kompatibel; neue Korrekturen können ihre Vorgänger in NeuroForge tatsächlich superseden.
+
+## Neue Konfiguration
+
+```env
+OUTCOME_RETRIEVAL_ENABLED=true
+OUTCOME_RETRIEVAL_SEARCH_K=6
+OUTCOME_RETRIEVAL_MIN_SIMILARITY=0.58
+OUTCOME_RETRIEVAL_FAIL_OPEN=true
+```
+
+Empfehlung für Pilotbetrieb: Outcome Retrieval aktivieren, aber Auto-Reply zunächst weiterhin im Shadow-/Dry-Run-Modus beobachten.
+
+`OUTCOME_RETRIEVAL_FAIL_OPEN=true` bedeutet: fällt die Erfahrungs-Suche aus, arbeitet der Agent mit offizieller Knowledge- und sonstiger Evidenz weiter. `false` blockiert die Ticketverarbeitung an dieser Stelle sichtbar. Die Auswahl richtet sich nach dem gewünschten Verfügbarkeits-/Konsistenzprofil.
+
+## Verhalten bei Korrekturen
+
+v1.2.0 führte lokal bereits `supersedes_id`. v1.3.0 zieht die Revision auch in NeuroForge nach:
+
+1. neue korrigierte Outcome-Memory wird gespeichert;
+2. Vorgänger wird über seine stabile Outcome Source-ID aufgelöst;
+3. Vorgängerstatus wird atomar `superseded`;
+4. neue Memory erhält die `Supersedes`-Kante;
+5. beide Revisionen bleiben auditierbar;
+6. nur die aktive Revision erscheint in künftiger Outcome-Suche.
+
+Es gibt keine destructive Delete-Migration.
+
+## Outcome Retrieval
+
+Der Agent sucht bei einem neuen Ticket zusätzlich in den aktiven menschlich validierten Erfahrungen. Diese Treffer werden ausschließlich in `ContextSnapshot.ValidatedOutcomes` an die Reply-Auswahl übergeben. Die Liste der erlaubten `knowledge_id`-Werte wird weiterhin ausschließlich aus freigegebenen Knowledge-Kandidaten erzeugt.
+
+Damit kann Erfahrung Ranking/Entscheidung unterstützen, ohne einen Policy-Bypass zu erzeugen.
+
+## Quality Replay
+
+Beispieldatensatz kopieren/anpassen:
+
+```bash
+cp docs/QUALITY-REPLAY-example.json /tmp/my-cases.json
+python3 scripts/quality-replay.py /tmp/my-cases.json \
+  --url http://127.0.0.1:8080 \
+  --user "$WEB_BASIC_USER" \
+  --password "$WEB_BASIC_PASSWORD"
+```
+
+Vor einem breiten Auto-Reply-Go-Live sollten historische Tickets mit bekanntem Outcome verwendet werden. Zielwerte müssen organisationsspezifisch definiert und als Release-Gate dokumentiert werden.
+
+## Rollback
+
+Outcome-Retrieval kann ohne Datenmigration deaktiviert werden:
+
+```env
+OUTCOME_RETRIEVAL_ENABLED=false
+```
+
+Das Outcome-Learning und die bestehenden Memories bleiben erhalten. Für einen vollständigen v1.2-Verhaltensrollback kann zusätzlich der v1.2.0-Code gestartet werden; die neue `superseded`-Statusinformation ist nicht destruktiv.

docs/MIGRATION-v1.3.0-to-v1.4.0.md

@@ -0,0 +1,9 @@
+# Migration v1.3.0 -> v1.4.0
+
+1. Generate and add a new `CONTROL_READ_TOKEN` (minimum 24 characters) to `.env`.
+2. Recreate `agent` and `control`; no data migration is required.
+3. Open the Control Center and verify Runtime, Ticket, Learning, Research, Brain and Engineering graph views.
+4. Keep Codebase Memory variables empty unless the optional developer tool is installed.
+5. After code changes regenerate `services/control/engineering-graph.json` with `make engineering-graph`.
+
+Rollback: deploy v1.3.0 again. The new graph APIs are read-only and introduce no persistent schema change.

docs/OBSIDIAN-EXPORT.md

@@ -0,0 +1,72 @@
+# Obsidian / llm-wiki Export
+
+Das Mega-Projekt kann die Wissensbasis als selbständigen Obsidian-Vault exportieren. Der Export verändert keine Quelldaten.
+
+## Zwei Sichten
+
+### Kanonische Knowledgebase
+
+```text
+GET /api/export/obsidian
+```
+
+Quelle sind die produktiven JSON-Dateien im gemeinsamen `knowledge/`-Verzeichnis. Der Export enthält Kategorien sowie explizite relation-artige Felder wie `linked_items`, `relations`, `related`, `related_articles`, `references`, `links`, `connections`, `associations` und `glpi_relations`.
+
+### Live-Sicht des Agenten
+
+```text
+GET /api/knowledge/export/obsidian
+```
+
+Diese Sicht enthält zusätzlich die vom Agenten synchronisierten GLPI-KB-Artikel. Wenn die installierte GLPI-OpenAPI einen lesbaren `KnowbaseItem_Item`-Pfad bereitstellt, übernimmt der Sync die GLPI-Verknüpfungen (`knowbaseitems_id`, `itemtype`, `items_id`) in `linked_items`.
+
+Ist die Relation-API nicht verfügbar oder fehlen Rechte, wird der KB-Artikel weiterhin synchronisiert. Der Agent protokolliert dann ausdrücklich, dass GLPI-Objektrelationen im Export fehlen.
+
+## Vault-Struktur
+
+```text
+Wiki/
+├── index.md
+├── Schema.md
+├── graph.json
+├── .manifest.json
+├── Knowledge/
+├── Categories/        # kanonischer KB-Export
+├── GLPI/              # Live-Agent-Export für GLPI-Objekte
+└── Relations/         # generische Relation-Stubs
+```
+
+Artikel sind normales Markdown mit YAML-Frontmatter. Interne Beziehungen werden als Obsidian-Wikilinks `[[Wiki/...|Titel]]` geschrieben. Datumswerte sind ISO-8601-Daten (`YYYY-MM-DD`). `graph.json` enthält Knoten und Kanten zusätzlich maschinenlesbar.
+
+## Export aus der Oberfläche
+
+Sowohl Knowledgebase als auch Agent-Dashboard besitzen einen Button **„⇩ Obsidian Export“**.
+
+## Export per Skript
+
+```bash
+# kanonische KB
+KB_URL=http://127.0.0.1:8081 \
+BASIC_AUTH_USER=admin \
+BASIC_AUTH_PASSWORD='...' \
+./scripts/export-obsidian.sh kb ./knowledge-vault.zip
+
+# Live-Agent-Sicht inkl. GLPI-KB-Sync
+AGENT_URL=http://127.0.0.1:8080 \
+WEB_USERNAME=admin \
+WEB_PASSWORD='...' \
+./scripts/export-obsidian.sh agent ./live-vault.zip
+```
+
+Das Skript schreibt zunächst in eine temporäre Datei und ersetzt die Zieldatei erst nach einem erfolgreichen HTTP-Download.
+
+## Governance
+
+Der Export ist absichtlich read-only:
+
+- keine Quelldatei wird geändert,
+- keine GLPI-Verknüpfung wird zurückgeschrieben,
+- keine Auto-Reply-Policy wird verändert,
+- Secrets werden nicht in Frontmatter oder `graph.json` exportiert.
+
+Damit kann der Vault in Obsidian, Git oder einem llm-wiki-artigen Workflow analysiert werden, ohne die operative Wissensbasis zu verändern.

docs/OPERATIONS.md

@@ -0,0 +1,102 @@
+# Betrieb
+
+## Standardbefehle
+
+```bash
+make test
+make vet
+make build
+make up
+# optional: Research/SearXNG ohne Autonomy
+make research-up
+make ps
+make status
+make logs
+make down
+```
+
+## Secrets
+
+```bash
+./scripts/generate-secrets.sh
+```
+
+Die Ausgabe wird nicht automatisch in `.env` geschrieben. Das verhindert, dass vorhandene Credentials versehentlich überschrieben werden.
+
+## Status
+
+Das Control Center ist read-only und fragt parallel ab:
+
+- Agent `/readyz`
+- Knowledgebase `/api/health`
+- NeuroForge `/api/v1/stats` mit App Key
+
+Es zeigt keine Secrets und besitzt keine Schreibroute.
+
+## Knowledge Sync
+
+`knowledge/` ist das gemeinsame kanonische Verzeichnis:
+
+- Knowledgebase: read/write
+- Agent: read-only
+
+Der Agent erkennt Änderungen inkrementell. In `dual`/`neuroforge` werden veränderte Chunk-Vektoren in das NeuroForge-Namespace synchronisiert. Entfernte Dokumente werden dort ebenfalls entfernt.
+
+## Externe Knowledge-Connectoren
+
+Connector-Dokumente werden ebenfalls nach NeuroForge gespiegelt. Ihr lokaler Connector-Vektorcache wird derzeit bewusst beibehalten, damit Connector-Neustarts und Fail-open-Betrieb nicht bei jedem Zyklus neu einbetten müssen. Das ist eine Resilienz-/Effizienzentscheidung und unterscheidet sich von der Externalisierung der lokalen produktiven KB.
+
+
+## Obsidian-Export
+
+```bash
+./scripts/export-obsidian.sh kb ./knowledge-vault.zip
+./scripts/export-obsidian.sh agent ./live-vault.zip
+```
+
+Der KB-Export liest die kanonischen JSON-Dateien. Der Agent-Export ergänzt synchronisierte GLPI-KB-Artikel und verfügbare `KnowbaseItem_Item`-Verknüpfungen. Beide Exporte sind read-only. Details: [`OBSIDIAN-EXPORT.md`](OBSIDIAN-EXPORT.md).
+
+## Research-Drafts
+
+Ein Proposal-JSON kann kontrolliert ins Staging geschrieben werden:
+
+```json
+{
+  "source": "NeuroForge Research",
+  "query": "VPN Fehlerbild",
+  "title": "VPN Diagnose",
+  "text": "Beobachtetes Symptom ...",
+  "answer": "1. ...",
+  "categories": ["VPN"],
+  "keywords": ["gateway", "token"],
+  "min_score": 0.85
+}
+```
+
+```bash
+export KB_INTEGRATION_TOKEN='...'
+./scripts/propose-draft.sh proposal.json
+```
+
+Der Server erzwingt `auto_reply=false`. Promotion erfolgt im normalen Editor.
+
+## SQAR
+
+SQAR ist ausschließlich im NeuroForge Vector Journal aktiviert. Nicht komprimiert werden operative Audit-/Policy-Dateien oder zufällig zugreifbare Memory-Segmente. Der Codec wählt nur dann die SQAR-Variante, wenn sie gegenüber der Roh-/DEFLATE-Darstellung tatsächlich kleiner ist.
+
+
+## Controlled Learning / Human Outcomes
+
+Im Standard ist `NEUROFORGE_CONTROLLED_LEARNING=true`. Rohe Chat-/Assistant-Inhalte werden damit nicht automatisch als Langzeitwissen gelernt. Ein Agent-Run kann im Dashboard explizit bestätigt oder korrigiert werden. Das Outcome wird unter `DATA_DIR/ticket-outcomes.json` auditiert und erst dann über den App-Key-Pfad an NeuroForge übertragen.
+
+Bei `OUTCOME_LEARNING_FAIL_OPEN=false` ist ein NeuroForge-Syncfehler für den Techniker sichtbar. Der lokale Outcome-Eintrag bleibt erhalten und kann durch Wiederholen derselben Entscheidung retryt werden. Änderungen am GLPI-Ticket seit dem analysierten Run blockieren die Validierung.
+
+## Optionales SearXNG / Research
+
+Der Basisstack startet SearXNG nicht. Für Research zuerst einen echten `SEARXNG_SECRET` in `.env` setzen und dann:
+
+```bash
+./scripts/research-up.sh
+```
+
+Das startet das Compose-Profil `research` und schaltet Research/SearXNG für NeuroForge ein. `NEUROFORGE_AUTONOMY_ENABLED` bleibt separat und standardmäßig `false`. Details: [`CONTROLLED-AUTONOMY.md`](CONTROLLED-AUTONOMY.md).

docs/QUALITY-REPLAY-example.json

@@ -0,0 +1,11 @@
+{
+  "cases": [
+    {
+      "id": "vpn-login-001",
+      "query": "VPN verbindet nicht, Anmeldung schlägt nach Passwortwechsel fehl",
+      "expected_knowledge_id": "REPLACE-WITH-KB-ID",
+      "expected_solution_terms": ["vpn"],
+      "k": 10
+    }
+  ]
+}

docs/QUALITY-REPLAY.md

@@ -0,0 +1,35 @@
+# Retrieval & Learning Replay Benchmark
+
+v1.3.0 adds a read-only benchmark endpoint: `POST /api/quality/replay`.
+It does **not** write to GLPI, does not learn and does not call the answer LLM. It replays
+historical ticket text through the current Knowledge retrieval and the human-validated
+Outcome retrieval so quality changes can be measured before a rollout.
+
+Each case may specify:
+
+- `query`: historical ticket subject/body snapshot.
+- `expected_knowledge_id`: the KB article known to be correct at that time.
+- `expected_solution_terms`: terms expected in a technician-validated outcome.
+- `k`: evaluation depth (default 10, max 50).
+
+Reported KPIs:
+
+- `knowledge_recall_at_k`
+- `knowledge_mrr`
+- `outcome_recall_at_k`
+- `outcome_mrr`
+- `experience_rescued_cases`: cases where the expected KB was not retrieved in K but a
+  matching human-validated experience was retrieved. This is a conservative proxy for
+  learning lift; it is not counted as auto-reply authority.
+
+Example:
+
+```bash
+./scripts/quality-replay.py docs/QUALITY-REPLAY-example.json \
+  --url http://127.0.0.1:8080 --user "$WEB_BASIC_USER" --password "$WEB_BASIC_PASSWORD" \
+  --output ./data/quality-replay-$(date +%F).json
+```
+
+For production acceptance, build a versioned set of historical tickets and require fixed
+minimum thresholds before changing retrieval weights, embedding models, HNSW settings or
+Outcome retrieval thresholds.

docs/UNIFIED-GRAPH.md

@@ -0,0 +1,32 @@
+# Unified Graph Explorer (v1.4.0)
+
+The Control Center remains read-only and now normalizes operational, evidence, learning, research and engineering relationships into one graph contract (`nodes[]`, `edges[]`, bounded metadata).
+
+## Views
+
+- **Runtime & Trust** — services, external systems, scoped credentials and authority boundaries.
+- **Ticket Evidence** — ticket, run, KB candidates, validated outcomes, policy checks, model attempts, proposed reply and human decision.
+- **Learning Lineage** — accepted/corrected outcomes, NeuroForge memories and immutable `supersedes` chains.
+- **Research Provenance** — goal -> query -> source -> claim/evidence -> memory without exposing full source bodies or prompts.
+- **NeuroForge Brain** — bounded/redacted memory/synapse/consolidation view; vectors and full memory exports are not returned.
+- **Engineering Graph** — reproducible Go AST + root Compose snapshot with components, packages, files, functions, HTTP routes and service dependencies.
+- **Change Impact** — bounded bidirectional dependency traversal for a file/symbol/route query with a conservative static risk hint.
+
+## Visualization
+
+The browser uses a dependency-free canvas renderer. 2D is the operational default. 3D is an optional pseudo-perspective explorer for bounded subgraphs. Node budgets and server-side filtering prevent accidental full-graph rendering.
+
+The graph is an explanation/inspection surface, not a decision authority. A `high` change-impact hint does not replace tests, code review or runtime evidence.
+
+## Trust boundaries
+
+The Control Center never receives Agent admin/basic-auth credentials. Agent graph reads require `CONTROL_READ_TOKEN`; NeuroForge graph reads use the existing scoped app key. Graph endpoints are GET-only and return redacted/bounded representations.
+
+## Reproducibility
+
+Regenerate the engineering snapshot after structural code changes:
+
+```sh
+make engineering-graph
+make engineering-graph-check
+```

docs/VALIDATION.md

@@ -0,0 +1,72 @@
+# Validierung
+
+Stand: 26.08.2026 — Release v1.4.0
+
+## Umfang
+
+- 4 Go-Module im gemeinsamen `go.work`
+- 158 Go-Dateien
+- 47.260 Go-Codezeilen inklusive Tests
+- 276 `Test...`-Testfunktionen
+- 103 produktive Knowledge-JSON-Dateien
+- 8 Compose-Services inklusive optionalem SearXNG-Profil
+- reproduzierbarer Engineering-Snapshot: 1.652 Knoten / 6.450 Kanten
+
+## Vollständige Modulprüfung
+
+```text
+platform/neuroforge   go test ./...   OK
+platform/neuroforge   go vet  ./...   OK
+platform/neuroforge   go build ./...  OK
+services/agent        go test ./...   OK
+services/agent        go vet  ./...   OK
+services/agent        go build ./...  OK
+services/knowledge    go test ./...   OK
+services/knowledge    go vet  ./...   OK
+services/knowledge    go build ./...  OK
+services/control      go test ./...   OK
+services/control      go vet  ./...   OK
+services/control      go build ./...  OK
+```
+
+Shell-Syntax (`scripts/*.sh`), Control-Center-JavaScript (`node --check`), Root-Compose und SearXNG-YAML wurden zusätzlich erfolgreich geprüft. `make engineering-graph-check` bestätigt, dass der eingebettete Engineering-Graph zum Quellstand passt.
+
+## v1.4-spezifische Prüfungen
+
+- Agent-Control-Endpunkte verlangen den separaten Bearer `CONTROL_READ_TOKEN`: **OK**
+- Ticket-Evidence-Graph enthält Knowledge, validierte Outcomes, Policy-Checks, Reply und Human Outcome: **OK**
+- Learning-Lineage erhält `supersedes`-Revisionen: **OK**
+- NeuroForge Research-/Brain-Graph verlangen den App-Key: **OK**
+- Brain-Graph ist gebunden/redigiert; Vektoren und voller Memory-Text werden nicht exportiert: **OK**
+- Research-Graph bildet Query -> Source -> learned Memory ab: **OK**
+- Engineering-Graph enthält Component/Package/File/Function/Route/Service-Knoten: **OK**
+- Engineering-Endpunkt respektiert Node-Budgets: **OK**
+- Change-Impact verlangt eine explizite Query, bleibt gebunden und liefert Risk-Metadaten: **OK**
+- 2D/3D-Canvas-JavaScript besteht Syntaxprüfung: **OK**
+- optionales Codebase Memory MCP beeinflusst Readiness nicht: konstruktiv durch `Optional`-Target / leere Default-URL abgesichert
+
+## Race-Checks der neuen Pfade
+
+```text
+services/control      go test -race ./...               OK
+services/agent        go test -race ./internal/web      OK
+platform/neuroforge   go test -race ./internal/httpapi  OK
+```
+
+Ein parallel gestarteter Sammel-Race-Lauf lief in das globale Ausführungszeitlimit; die v1.4-betroffenen Pakete wurden deshalb anschließend einzeln erfolgreich geprüft. Ein Timeout wird nicht als Testerfolg gewertet.
+
+## Weiterhin erhaltene Kernfunktionen
+
+Die bestehende Regressionstestbasis umfasst weiterhin GLPI Polling/Webhook/Followups/Kategorien/Priorität/Eskalation, kontrolliertes Outcome-Learning und Supersession, Outcome-Retrieval, Quality Replay, Knowledge `local|dual|neuroforge`, HNSW/Disk-PQ, NFVJ2/SQAR, SearXNG Research, Obsidian-Export und Staging-Governance.
+
+## Nicht als getestet behauptet
+
+Docker/Podman sind in der Prüfungsumgebung nicht installiert. Deshalb wurden nicht ausgeführt:
+
+- echter `docker compose up`
+- Live-SearXNG gegen das Internet
+- Live-GLPI gegen die Betreiberinstanz
+- optionales Codebase Memory MCP als realer externer Prozess
+- historischer Quality-Replay mit echten Betreiber-Tickets
+
+Vor Produktivfreigabe bleiben Container-Smoke-Test, echte GLPI-/Research-Konnektivität und der historische Quality-Replay Betreiber-Gates.