MtoRagSystem/COMMAND_REF.md

# RetrieX – CLI Command Reference

**Basis:** `rag.zip` (aktueller Code-Stand vom 2026-04-15)  
**Scope:** ausschließlich projektspezifische Symfony-Commands unter `src/Command`  
**Namespace-Konvention:** `mto:agent:*`

Diese Referenz ist gegen den realen Codebestand abgeglichen und ersetzt die veraltete Fassung der bisherigen `COMMAND_REF.md`.

---

## 1. Überblick

| Command | Bereich | Kurzbeschreibung |
|---|---|---|
| `mto:agent:chat` | Agent / CLI | Interaktiver Terminal-Chat gegen den AgentRunner |
| `mto:agent:ingest:version` | Ingest | Startet einen Ingest für eine konkrete Dokumentversion |
| `mto:agent:ingest:run` | Ingest Jobs | Führt einen vorhandenen `IngestJob` aus |
| `mto:agent:system:rebuild` | System | Globaler Hard-Rebuild von Chunks, Vektorindex, Tags und optional Service-Reload |
| `mto:agent:config:validate` | Config / Governance | Validiert die effektive RetrieX-Konfiguration |
| `mto:agent:config:audit-source` | Config / Governance | Auditiert YAML-Mappings gegen PHP-Fallbacks und Defaults |
| `mto:agent:config:audit-patterns` | Config / Governance | Auditiert fachliche Pattern-, Token- und Signalreste im PHP-Core |
| `mto:agent:config:dump-effective` | Config / Governance | Gibt die effektive Konfigurationsinventur aus |
| `mto:agent:regression:test` | Config / Governance | Fuehrt Offline-Regression-Guards fuer stabile Pfade aus |
| `mto:agent:vector:rebuild` | Vector | Baut den Chunk-Vektorindex aus `index.ndjson` neu |
| `mto:agent:vector:control` | Vector Service | Install, Start, Stop, Reload und Status des Python-Vector-Service |
| `mto:agent:vector:health` | Vector | Konsistenzcheck für Chunk-NDJSON und Vektorindex |
| `mto:agent:test-vector` | Debug | Führt Tag-Routing und Chunk-Retrieval für einen Testprompt aus |
| `mto:agent:tags:export` | Tags | Exportiert Tags nach `tags.ndjson` |
| `mto:agent:tags:rebuild` | Tags | Exportiert Tags und baut `vector_tags.index` neu |
| `mto:agent:tags:job:run` | Tag Jobs | Führt einen vorhandenen Tag-Rebuild-Job aus oder erstellt direkt einen neuen |
| `mto:agent:tag:health` | Tags | Konsistenzcheck für `tags.ndjson` und Tag-Vektorindex |
| `mto:agent:test:shop-search` | Commerce / Debug | Testkommando für die Shopware-Suche |
| `mto:agent:user:create` | User | Interaktive Anlage eines Users |

---

## 2. Agent / Chat

### `mto:agent:chat`
Interaktiver CLI-Chat mit dem Agenten.

**Signatur**
```bash
bin/console mto:agent:chat [user-id]
```

**Argumente**
- `user-id` optional, Default: `cli`

**Reales Verhalten im Code**
- startet eine Terminal-Schleife mit `Question` → `Answer`
- ruft pro Eingabe `AgentRunner->run($prompt, $userId)` auf
- streamt Tokens direkt ins Terminal
- beendet sich bei EOF, leerer Eingabe oder `exit`

**Beispiel**
```bash
bin/console mto:agent:chat
bin/console mto:agent:chat admin-debug
```

---

## 3. Ingest / Jobs

### `mto:agent:ingest:version`
Startet einen Ingest für eine konkrete `DocumentVersion` mit explizitem Benutzerkontext.

**Signatur**
```bash
bin/console mto:agent:ingest:version <versionId> <userId>
```

**Argumente**
- `versionId` erforderlich, UUID einer `DocumentVersion`
- `userId` erforderlich, UUID des auslösenden Users

**Reales Verhalten im Code**
- lädt `DocumentVersion` und `User` aus Doctrine
- bricht mit Fehler ab, wenn Version oder User nicht existieren
- ruft `IngestOrchestrator->runForVersion($version, $user)` auf
- gibt nach Abschluss die erzeugte Job-ID aus

**Beispiel**
```bash
bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
```

**Wichtige Korrektur zur alten Doku**
Die bisherige Referenz dokumentierte nur einen Parameter. Im aktuellen Code sind **zwei Pflichtargumente** erforderlich.

---

### `mto:agent:ingest:run`
Führt einen bereits existierenden `IngestJob` aus.

**Signatur**
```bash
bin/console mto:agent:ingest:run <jobId> [--dry-run]
```

**Argumente / Optionen**
- `jobId` erforderlich, UUID eines `IngestJob`
- `--dry-run` optional, simuliert schwere Operationen ohne tatsächliche Ausführung

**Reales Verhalten im Code**
- lädt den Job aus der Datenbank
- bricht mit Fehler ab, wenn der Job nicht gefunden wird
- beendet sich erfolgreich, wenn der Job bereits terminal ist (`COMPLETED`, `FAILED`, `ABORTED`)
- ruft sonst `IngestOrchestrator->runExistingJob($job, $dryRun)` auf

**Beispiele**
```bash
bin/console mto:agent:ingest:run <jobUuid>
bin/console mto:agent:ingest:run <jobUuid> --dry-run
```

---

### `mto:agent:system:rebuild`
Globaler Hard-Rebuild des Systems.

**Signatur**
```bash
bin/console mto:agent:system:rebuild --hard [--no-tags] [--no-reload] [--no-health] [--dry-run]
```

**Optionen**
- `--hard` **Pflicht-Sicherheitsschalter**; ohne diese Option bricht das Kommando ab
- `--no-tags` überspringt den Tag-Rebuild
- `--no-reload` überspringt Reload/Start des Vector-Service
- `--no-health` überspringt den abschließenden Health-Check
- `--dry-run` simuliert den Reindex ohne Schreiboperationen

**Reales Verhalten im Code**
1. erzeugt einen neuen `IngestJob` vom Typ `GLOBAL_REINDEX`
2. führt den globalen Reindex über den Orchestrator aus
3. exportiert optional `tags.ndjson` und baut `vector_tags.index` neu
4. startet bzw. reloadet optional den Python-Vector-Service
5. führt optional Chunk- und Tag-Health-Checks aus

**Beispiele**
```bash
bin/console mto:agent:system:rebuild --hard
bin/console mto:agent:system:rebuild --hard --dry-run
bin/console mto:agent:system:rebuild --hard --no-tags --no-reload
```

**Hinweis**
Dieses Kommando ist aktuell der zentrale Produktions-Entry-Point für einen vollständigen Neuaufbau des Retrieval-Stacks.

---

## 4. Vector / Retrieval

### `mto:agent:vector:rebuild`
Baut den Chunk-Vektorindex neu.

**Signatur**
```bash
bin/console mto:agent:vector:rebuild
```

**Reales Verhalten im Code**
- schreibt `Rebuilding vector index...`
- ruft `VectorIndexBuilder->rebuildFromNdjson()` auf
- schreibt anschließend `Done.`

**Beispiel**
```bash
bin/console mto:agent:vector:rebuild
```

---

### `mto:agent:vector:control`
Steuert den persistenten Python-Vector-Service über `python/vector/vector_control.py`.

**Signatur**
```bash
bin/console mto:agent:vector:control [optionen]
```

**Unterstützte Optionen**
- `--install` installiert fehlende Python-Dependencies in `.venv`
- `--start` startet den Service, falls er nicht läuft
- `--stop` stoppt den Service anhand der PID-Datei
- `--force` erzwingt einen Hard-Stop
- `--reload` triggert den `/reload`-Endpoint des Service
- `--status` gibt den aktuellen Status aus
- `--foreground` startet im Vordergrund
- `--port=8090` setzt den Port
- `--host=0.0.0.0` setzt den Host

**Reales Verhalten im Code**
- baut einen Prozessaufruf gegen `.venv/bin/python python/vector/vector_control.py`
- reicht gesetzte Optionen durch
- hängt immer `--port` und `--host` an
- gibt `stdout` des Python-Skripts direkt aus

**Beispiele**
```bash
bin/console mto:agent:vector:control --install
bin/console mto:agent:vector:control --start
bin/console mto:agent:vector:control --status
bin/console mto:agent:vector:control --reload
bin/console mto:agent:vector:control --stop --force
```

---

### `mto:agent:vector:health`
Health-Check für Chunk-NDJSON und Chunk-Vektorindex.

**Signatur**
```bash
bin/console mto:agent:vector:health
```

**Reales Verhalten im Code**
- ruft `VectorIndexHealthService->check()` auf
- gibt den Report als JSON aus
- endet mit Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`

**Beispiel**
```bash
bin/console mto:agent:vector:health
```

---

### `mto:agent:test-vector`
Debug-Kommando für einen realistischen Retrieval-Test.

**Signatur**
```bash
bin/console mto:agent:test-vector <prompt>
```

**Argumente**
- `prompt` erforderlich, Testanfrage für das Retrieval

**Reales Verhalten im Code**
- führt zuerst Tag-Routing über `TagVectorSearchClient` aus
- führt danach Chunk-Retrieval über `VectorSearchClient` aus
- misst Tag-, Chunk- und Gesamtdauer
- gibt beide Result-Sets als JSON aus

**Beispiel**
```bash
bin/console mto:agent:test-vector "welche dokumente behandeln den ingest-flow?"
```

---

## 5. Tag-System

### `mto:agent:tags:export`
Exportiert die Tag-Datenbasis nach `tags.ndjson`.

**Signatur**
```bash
bin/console mto:agent:tags:export
```

**Reales Verhalten im Code**
- ruft `TagNdjsonExporter->export()` auf
- gibt Pfad, Tag-Anzahl, Zeilen und Bytes aus

**Beispiel**
```bash
bin/console mto:agent:tags:export
```

---

### `mto:agent:tags:rebuild`
Kompletter Neuaufbau des Tag-Retrievals.

**Signatur**
```bash
bin/console mto:agent:tags:rebuild
```

**Reales Verhalten im Code**
1. exportiert `tags.ndjson`
2. baut `vector_tags.index`
3. setzt einen Runtime-Marker über `IndexMetaManager->touchRuntime()`

**Beispiel**
```bash
bin/console mto:agent:tags:rebuild
```

---

### `mto:agent:tags:job:run`
Führt einen Tag-Rebuild-Job mit File-Lock aus.

**Signatur**
```bash
bin/console mto:agent:tags:job:run [jobId] [--create]
```

**Argumente / Optionen**
- `jobId` optional, UUID eines bestehenden `TagRebuildJob`
- `--create` optional, erstellt und startet sofort einen neuen `TagRebuildJob`

**Regeln im Code**
- entweder `jobId` **oder** `--create`
- beides zusammen ist ungültig
- keines von beiden ist ebenfalls ungültig

**Reales Verhalten im Code**
- markiert den Job auf `RUNNING`
- sperrt parallel laufende Tag-Rebuilds per File-Lock
- exportiert `tags.ndjson`
- baut `vector_tags.index`
- markiert den Job bei Erfolg als `COMPLETED`, sonst als `FAILED`

**Beispiele**
```bash
bin/console mto:agent:tags:job:run --create
bin/console mto:agent:tags:job:run <jobUuid>
```

---

### `mto:agent:tag:health`
Health-Check für das Tag-Retrieval.

**Signatur**
```bash
bin/console mto:agent:tag:health
```

**Reales Verhalten im Code**
- ruft `TagVectorIndexHealthService->check()` auf
- gibt den Report als JSON aus
- endet mit Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`

**Beispiel**
```bash
bin/console mto:agent:tag:health
```

**Wichtige Korrektur zur alten Doku**
Der reale Command-Name ist **`tag:health` (Singular)**, nicht `tags:health`.

---

## 6. Commerce / Shopware Debug

### `mto:agent:test:shop-search`
Testkommando für die Shopware-Suche.

**Signatur**
```bash
bin/console mto:agent:test:shop-search [query]
```

**Argumente**
- `query` optional
- Default im Code: `zeige mir testomat modelle wasserhärte unter 5000 euro`

**Beabsichtigtes Verhalten**
- ruft die Shop-Suche auf
- gibt pro Treffer Produktdaten wie ID, Produktnummer, Hersteller, Preis, Verfügbarkeit, URL und Description aus

**Wichtiger Code-Hinweis**
Im aktuellen Stand von `rag.zip` ruft das Command `ShopSearchService->search($query)` mit **einem** Argument auf, die Service-Signatur erwartet aber **zwei** Argumente (`string $originalPrompt, string $commerceIntent`). Das Kommando ist daher im aktuellen Codebestand sehr wahrscheinlich **nicht lauffähig**, solange diese Signaturabweichung nicht behoben wird.

---

## 7. User-Management

### `mto:agent:user:create`
Interaktive Anlage eines Users.

**Signatur**
```bash
bin/console mto:agent:user:create
```

**Interaktiver Ablauf**
1. E-Mail eingeben
2. Passwort eingeben
3. Rolle wählen

**Validierungen im Code**
- E-Mail muss valide sein
- User mit gleicher E-Mail darf nicht bereits existieren
- Passwort muss mindestens 8 Zeichen lang sein

**Im Code auswählbare Rollen**
- `ROLE_SUPER_ADMIN`
- `ROLE_KNOWLEDGE_ADMIN`
- `ROLE_EDITOR`
- `ROLE_USER`

**Beispiel**
```bash
bin/console mto:agent:user:create
```

---

## 8. Typische Betriebsabläufe

### Manueller Ingest einer Version
```bash
bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
```

### Vorhandenen Ingest-Job ausführen
```bash
bin/console mto:agent:ingest:run <jobUuid>
```

### Nur Chunk-Vektorindex neu bauen
```bash
bin/console mto:agent:vector:rebuild
```

### Gesamtsystem hart neu aufbauen
```bash
bin/console mto:agent:system:rebuild --hard
```

### Vector-Service prüfen und reloaden
```bash
bin/console mto:agent:vector:health
bin/console mto:agent:vector:control --reload
```

### Tag-Retrieval neu aufbauen
```bash
bin/console mto:agent:tags:rebuild
bin/console mto:agent:tag:health
```

---

## 9. Wichtige Runtime-Dateien und Pfade

Die bisherige Doku nannte teilweise veraltete Pfade unter `var/`. Im aktuellen Code liegen die Knowledge-Artefakte primär unter `var/knowledge/`.

```text
var/
├── knowledge/
│   ├── index.ndjson
│   ├── index_meta.json
│   ├── index_runtime.json
│   ├── vector.index
│   ├── vector.index.meta.json
│   ├── tags.ndjson
│   ├── vector_tags.index
│   ├── vector_tags.index.meta.json
│   ├── uploads/
│   └── locks/
│       └── tag_rebuild.lock
├── run/
│   └── vector_service.pid
└── locks/
    └── ingest.lock
```

**Herkunft im Code**
- `config/services.yaml` definiert `mto.knowledge.root = %mto.root%/var/knowledge`
- `python/vector/vector_control.py` verwendet `var/run/vector_service.pid`
- `App\Service\LockService` verwendet aktuell `var/locks/ingest.lock`

---

## 10. Wichtige Abweichungen zur alten `COMMAND_REF.md`

Die bisherige Datei war in mehreren Punkten nicht mehr codekonform. Wesentliche Korrekturen:

1. `mto:agent:system:rebuild` fehlte vollständig
2. `mto:agent:test:shop-search` fehlte vollständig
3. `mto:agent:tag:health` fehlte und war zudem leicht falsch benannt
4. `mto:agent:ingest:version` braucht aktuell **`<versionId> <userId>`**
5. Runtime-Dateien liegen nicht nur unter `var/`, sondern überwiegend unter `var/knowledge/`
6. der globale Rebuild läuft heute über `mto:agent:system:rebuild --hard`, nicht über ein dokumentiertes `ingest:global`

---


## 11. Config-Governance / YAML-only Guardrails

These commands are mandatory for changes that touch YAML-backed configuration, prompt/retrieval behavior, intent detection, commerce/shop logic or regression-sensitive answer paths.

### `mto:agent:config:validate`

Validates the effective RetrieX configuration.

**Signature**
```bash
bin/console mto:agent:config:validate [--json]
```

**Expected result before merge**
- status `OK`
- no errors

### `mto:agent:config:audit-source`

Audits YAML-backed configuration against remaining PHP defaults, fallback accessors and constructor defaults.

**Signature**
```bash
bin/console mto:agent:config:audit-source [--details] [--json]
```

**Expected result before merge**
- no missing YAML mappings
- no new undocumented PHP-only semantic constants
- no constructor defaults without YAML/service-parameter mapping

Use `--details` for reviewable console output and `--json` for machine-readable CI output.

### `mto:agent:config:dump-effective`

Dumps the effective RetrieX configuration inventory.

**Signature**
```bash
bin/console mto:agent:config:dump-effective [--summary]
```

Use `--summary` for a compact review view.

### `mto:agent:regression:test`

Runs offline regression guards for stable configuration paths.

**Signature**
```bash
bin/console mto:agent:regression:test [--json]
```

**Expected result before merge**
- status `OK`
- all checks pass

This command protects the regression-sensitive 1.4.2/1.5.0 baseline, especially the Testomat 808 / 0,02 deg dH / indicator type 300 flow and related configuration paths.

---

## 12. Fazit

Der aktuelle Custom-CLI-Umfang des Systems besteht aus mindestens **18 projektspezifischen Commands**. Für den operativen Betrieb sind besonders relevant:

- `mto:agent:ingest:run`
- `mto:agent:system:rebuild`
- `mto:agent:vector:control`
- `mto:agent:vector:health`
- `mto:agent:tags:rebuild`
- `mto:agent:tag:health`

### `mto:agent:config:audit-patterns`

Audits remaining pattern-, token- and signal-sensitive calls in PHP core files for developer-policy review.

**Signature**
```bash
bin/console mto:agent:config:audit-patterns [--details] [--json] [--all]
```

**Purpose**
- finds configured calls such as `preg_match`, `str_contains`, `in_array` and related pattern/token helpers in configured source roots
- raises WARN findings when configured domain marker terms are involved
- keeps the command non-blocking and review-oriented; it does not change runtime behavior and does not activate strict validation

**Options**
- `--details` renders reviewable warning rows
- `--json` renders machine-readable audit output
- `--all` includes lower-priority REVIEW findings in addition to WARN findings

**Expected use before merge**
```bash
bin/console mto:agent:config:audit-patterns --details
```

Review WARN findings and move new semantic terms, product names, intent words, commerce signals or retrieval/follow-up patterns to YAML-backed configuration when they are not purely technical.