docs: Add README and expanded AGENTS.md with global install instructions

- README: human-facing docs (how it works, local + global installation,
  verification, troubleshooting)
- AGENTS.md: document global install options (~/.opencode/plugins/ and
  plugins array in config), plus hard-won debugging insights (Model.Info
  required fields, transform-before-config-load, silent model drops)

AGENTS.md

@@ -4,7 +4,7 @@
 
 Das existierende Plugin `opencode-models-discovery` ist **fehlfunktionell** und wurde **niemals** erfolgreich getestet. Alle bisherigen Versuche, es zu installieren und zu nutzen, schlugen fehl (AggregateError, Module Resolution Errors, etc.).
 
-**Wir verwenden `opencode-models-discovery` NICHT.** Es muss deinstalliert und nicht mehr referenced werden.
+**Wir verwenden `opencode-models-discovery` NICHT.** Es muss deinstalliert und nicht mehr referenziert werden (passiert: aus `~/.opencode` entfernt, keine Config-Referenzen mehr).
 
 ## Ziel
 
@@ -13,11 +13,14 @@ Wir bauen ein **neues OpenCode v2 Plugin** von Grund auf (`opencode-openai-disco
 - Entdeckte Modelle automatisch in OpenCode registriert
 - Sauber über die opencode v2 Plugin API (`@opencode/plugin`) funktioniert
 
+**Status: FUNKTIONIERT** – alle 900 Gateway-Modelle erscheinen als `OmniRoute/*` in `opencode models`. Commit `511d2ea`.
+
 ## Projektstruktur
 
 ```
 .
 ├── AGENTS.md                       # Diese Datei
+├── README.md                       # Doku für Menschen (Installation, global vs. projektlokal)
 ├── opencode.jsonc                  # OpenCode Projekt-Konfiguration
 └── .opencode/plugins/
     └── opencode-openai-discovery/
@@ -30,27 +33,86 @@ Wir bauen ein **neues OpenCode v2 Plugin** von Grund auf (`opencode-openai-disco
 
 - **OpenCode Version:** v2.0.32
 - **Plugin API:** `@opencode/plugin` (v2.x) — NICHT `@opencode-ai/plugin` (v1)
-- **Plugin Discovery:** Projektlokale Plugins in `.opencode/plugins/` werden automatisch geladen
-- **Config Format:** v2 verwendet `providers` (Plural), `package: "aisdk:..."`, `modelsDiscovery: { enabled: true }`
+- **Plugin Discovery:** Projektlokale Plugins in `.opencode/plugins/` werden automatisch geladen; für globale Verfügbarkeit: `~/.opencode/plugins/` (gleiche Struktur) oder `plugins`-Array in der Config (v2-Schema: `{ "package": "..." }` Strings)
+- **Config Format:** v2 verwendet `providers` (Plural), `package: "aisdk:..."`
+
+## API-Endpunkt
+
+```
+BASE_URL: http://localhost:20128/v1
+API_KEY:  sk-e9ac58c0b78cd2bc-f17d3e-f6beea67
+MODELS:   GET /v1/models   → 900 Modelle
+```
+
+## Erkenntnisse aus dem Debugging (kritisch für künftige Agenten)
+
+### 1. `modelsDiscovery` existiert NICHT im v2-Schema
+Das Feld `modelsDiscovery: { enabled: true }` in der Provider-Config war eine Erfindung des defekten `opencode-models-discovery`-Plugins. OpenCode v2 kennt es nicht (verifiziert am `@opencode/schema`). Konfig-Provider erscheinen im Provider-Index nur mit einem nicht-leeren `models`-Record – daher wurde OmniRoute initial nie instanziiert.
 
-## Plugin API (v2)
+### 2. Provider-Transform läuft VOR dem Config-Provider-Load
+`ctx.provider.transform(editor)` sieht nur die ~230 Katalog-Provider von models.dev, nicht die Config-Provider. `editor.models.set(providerID, ...)` auf einen nicht existierenden Provider ist ein **stilles No-Op**. Lösung: Provider per `editor.add({ info, models })` selbst erstellen, falls `editor.get(providerID)` nichts liefert.
+
+### 3. Model.Info-Schema: alle Pflichtfelder setzen, sonst stiller Verlust
+OpenCode verwirft Models OHNE Fehlermeldung aus dem Index, wenn Schema-Felder fehlen. Erforderlich pro Model:
+```ts
+{
+  id, modelID, providerID, name,
+  capabilities: { tools, input: [], output: [] },
+  variants: [],
+  cost: [{ input, output, cache: { read, write } }],
+  limit: { context, output },
+  time: { released },
+  status: "active",
+  enabled: true,
+}
+```
+Beachte: `limit` (SINGULAR), nicht `limits`. Die Fehler tauchen erst client-seitig als `InvalidRequestError: Missing key at ["data"][N][...]` auf – Index-N zeigt das N. verarbeitete (fehlgeschlagene) Model an.
+
+### 4. Plugin wird lazy geladen
+Der Plugin-Load wird getriggert, sobald ein Client (CLI/TUI) das Projektverzeichnis öffnet ("location services booted"). `opencode service restart` reicht manchmal nicht – hängende Server-Prozesse cache alte Plugin-Stände: `pkill -f "opencode serve"` + neuer CLI-Aufruf.
+
+### 5. Hot-Reload
+OpenCode watcht die Plugin-`index.ts` – Änderungen werden sofort neu geladen, kein Neustart nötig. Syntaxfehler im TS zeigen als `BuildMessage: Unexpected escape sequence` o.ä. im Log.
+
+### 6. `opencode models` CLI
+Zeigt ALLE verfügbaren Modelle (nicht paginiert; die anfangs sichtbaren 10 `opencode/*`-Modelle kamen vom OpenCode-Zen-Katalog, nicht von uns). Der Server-Port steht in der Log-Datei; die API braucht Auth (nicht einfach curl-bar ohne Token).
+
+## Plugin API (v2) – bewährtes Muster
 
 ```typescript
-import { Plugin, Provider, Model } from "@opencode/plugin";
+import { Plugin, Model } from "@opencode/plugin";
 
 export default Plugin.define({
   id: "opencode.openai-discovery",
   async setup(ctx) {
-    // ctx.provider.transform(editor => { ... })
-    // editor.add({ info, models })
+    // 1. fetch GET /v1/models
+    // 2. Modelle auf volles Model.Info-Schema mappen (siehe oben)
+    // 3. Registrieren:
+    ctx.provider.transform((editor) => {
+      const source = editor.get("OmniRoute");
+      if (source) {
+        // mergen:
+        editor.models.set("OmniRoute", [...existing, ...newModels]);
+      } else {
+        // erstellen (package MUSS "aisdk:@ai-sdk/openai-compatible" sein):
+        editor.add({
+          info: {
+            id: "OmniRoute",
+            name: "OmniRoute",
+            activation: "enabled",
+            package: "aisdk:@ai-sdk/openai-compatible",
+            settings: { baseURL, apiKey },
+          } as never,
+          models,
+        });
+      }
+    });
   },
 });
 ```
 
-## API-Endpunkt
+## Verifizierung
 
-```
-BASE_URL: http://localhost:20128/v1
-API_KEY:  sk-e9ac58c0b78cd2bc-f17d3e-f6beea67
-MODELS:   GET /v1/models
+```bash
+opencode models | grep -c "^OmniRoute/"   # → 900
 ```

README.md

@@ -0,0 +1,104 @@
+# opencode-openai-discovery
+
+Ein OpenCode v2 Plugin, das automatisch alle Modelle eines OpenAI-kompatiblen
+API-Endpunkts (`GET /v1/models`) entdeckt und als wählbare Modelle unter dem
+Provider **OmniRoute** registriert.
+
+> Getestet mit **OpenCode v2.0.32** – alle 900 Modelle eines lokalen Gateways
+> erscheinen in der Modellauswahl.
+
+## Wie es funktioniert
+
+```
+OpenCode startet
+  └─ lädt Plugin (Konvention: .opencode/plugins/<name>/)
+      └─ setup(ctx)
+          └─ fetch http://localhost:20128/v1/models   → 900 Modelle
+              └─ ctx.provider.transform(editor)
+                  ├─ Provider "OmniRoute" existiert?  → Modelle mergen
+                  └─ sonst                            → Provider + Modelle anlegen
+```
+
+Das Plugin **erstellt den Provider selbst** (inkl. `baseURL`/`apiKey`) –
+eine Provider-Definition in der `opencode.jsonc` ist deshalb **nicht nötig**.
+Wichtig: Das Plugin füllt alle Pflichtfelder des `Model.Info`-Schemas
+(`modelID`, `providerID`, `capabilities.tools`, `variants`, `cost`, `limit`,
+`time.released`, `status`, `enabled`) – fehlt eines davon, verwirft OpenCode
+die Modelle **still** (typisches Symptom: Plugin lädt ohne Fehler, aber keine
+Modelle erscheinen).
+
+## Installation (projektlokal)
+
+Die Dateien einfach ins Projekt kopieren:
+
+```
+<projekt>/
+└── .opencode/plugins/opencode-openai-discovery/
+    ├── index.ts        # Plugin-Code (wird von OpenCode automatisch transpiliert)
+    ├── package.json
+    └── tsconfig.json
+```
+
+**Fertig.** Kein Eintrag in irgendeiner Config nötig – OpenCode lädt
+Plugins aus `.opencode/plugins/` automatisch, sobald ein Client das
+Projektverzeichnis öffnet. Änderungen an `index.ts` werden per File-Watcher
+sofort neu geladen (Hot-Reload, kein Neustart).
+
+Endpunkt anpassen: Konstanten am Kopf von `index.ts` editieren
+(`PROVIDER_ID`, `BASE_URL`, `API_KEY`).
+
+## Installation (global, alle Projekte)
+
+**Weg 1 – Globales Plugin-Verzeichnis (Konvention):**
+
+```
+~/.opencode/plugins/opencode-openai-discovery/
+├── index.ts
+├── package.json
+└── tsconfig.json
+```
+
+OpenCode überwacht `~/.opencode/` ebenfalls (siehe Server-Logs:
+`watcher subscribe path=/home/paul/.opencode`). Gleiche Struktur wie
+projektlokal, das Plugin ist dann in jedem Projekt aktiv.
+
+**Weg 2 – Über die globale Config** (`~/.config/opencode/opencode.jsonc`),
+falls das Verzeichnis-Layout nicht greift:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "file:///home/paul/dev2/opencode-openai-compat-with-model-discovery/.opencode/plugins/opencode-openai-discovery"
+    }
+  ]
+}
+```
+
+Das v2-Schema erlaubt `"plugins": [ "<package-string>" | { "package": "...", "options": {...} } ]`.
+Es referenziert das Plugin dann direkt am Quelldort – praktisch, wenn man das
+Plugin-Verzeichnis nicht kopieren will.
+
+## Verifizieren
+
+```bash
+opencode models | grep -c "^OmniRoute/"
+# → 900
+```
+
+Falls nichts erscheint: Server hart neu starten (ein hängender Zombie-Prozess
+cache alte Plugin-Stände):
+
+```bash
+pkill -f "opencode serve"
+opencode models
+```
+
+Debug-Tipps siehe `AGENTS.md`.
+
+## Historie / Abgrenzung
+
+Dieses Plugin ersetzt das **fehlfunktionale** `opencode-models-discovery`
+(niemals erfolgreich gelaufen; AggregateError beim Build, `modelsDiscovery`-
+Config-Feld existiert im v2-Schema nicht). Es wird **nicht** verwendet.