# xbrain — Paket für einen externen Agenten (Codex)

xbrain ist ein Tab- und Wissens-Manager als Chromium-Erweiterung (Manifest V3),
Vanilla JavaScript, kein Build-Schritt. Version 0.5.0.

## Zwei Pakete

| Datei | Wofür |
|---|---|
| `xbrain-extension-v0.5.0.zip` | Fertiges Erweiterungs-Paket. Entpacken und im Browser als „entpackte Erweiterung" laden. |
| `xbrain-src-v0.5.0.tar.gz` | Voller Quellbaum inklusive Tests, README und CHANGELOG. Für Durchsicht und Weiterbau. |

Prüfsummen stehen in `SHA256SUMS`. Vor dem Verwenden prüfen:

```
sha256sum -c SHA256SUMS
```

## Holen

```
curl -fsSLO <BASIS>/xbrain-src-v0.5.0.tar.gz
curl -fsSLO <BASIS>/SHA256SUMS
sha256sum -c SHA256SUMS
tar -xzf xbrain-src-v0.5.0.tar.gz && cd xbrain
npm test
```

`<BASIS>` ist die Adresse, unter der diese Seite liegt. `npm test` braucht Node ab
Version 20 und **keine** Installation — die Tests laufen mit dem Node-eigenen
Test-Runner, es gibt bewusst keine Abhängigkeiten.

## Stand des Codes

Rund 3400 Zeilen, 74 Tests, keine CI. Die Tests decken die vier reinen Module ab
(`suggest`, `behavior`, `bookmarks-engine`, `privacy`); die Oberflächen-Dateien
(`dashboard.js`, `background.js`, `bookmarks-view.js`, `ai-panel.js`,
`server-view.js`) sind **nicht** getestet, weil sie am Browser hängen.

Die Tests sichern Produktversprechen ab, nicht Funktionsaufrufe. Wenn du daran
arbeitest, halte dich an dieselbe Linie: ein Test muss benennen, welches Risiko
er absichert, und er muss fallen, wenn man die Stelle bricht, die er bewacht.
Grün allein ist kein Nachweis.

## Aufbau des Quellbaums

```
manifest.json        MV3-Manifest, Rechte, New-Tab-Override
background.js        Service-Worker: Tab-Entladung, Screenshots, Verhaltensmessung
dashboard.html/.js   Kachel-Grid aller Tabs, Ansichten Fenster / Domains / Lesezeichen / Server
dashboard.css        Oberfläche
ai-panel.js          Ein-/ausfahrbares KI-Fenster, sammelt Kontext und fragt das Gateway
bookmarks-view.js    Lesezeichen-Ansicht, AI-Bookmarks, Vorschlags-Sektion
server-view.js       Zuschaltbares Server-Monitor-Modul, liest nur einen Collector-Endpunkt
options.html/.css/.js  Einstellungen inkl. Datenausfuhr und Löschung
lib/db.js            IndexedDB: Thumbnails, Wissen, Verhalten, Ausfuhr, Löschung
lib/privacy.js       Ausfuhr-Dokument und Schwärzung der Zugangsdaten (rein, testbar)
lib/ai.js            Gateway-Vertrag: POST {gatewayUrl}/v1/agent, OAuth PKCE
lib/entitlement.js   Server-seitiges Konto, Freischaltung ohne Neuinstallation
lib/behavior.js      Häufigkeit, letzter Besuch, aktive Verweildauer, alles lokal
lib/suggest.js       Relevanz-Gate der Vorschläge
lib/bookmarks-engine.js  Gruppierung, Dedup, Sortierung mit Backup
test/                74 Tests, node:test
```

## Was ohne Server läuft und was nicht

Ohne Gateway läuft alles Lokale: Kachel-Grid, Entladen, gespeicherte
Vorschaubilder, Lesezeichen-Sortierung, Wissens-Export, Verhaltensmessung,
Datenausfuhr und Löschung. Für die KI-Gruppierung der Lesezeichen greift ein
deterministischer Regel-Fallback, der als solcher gekennzeichnet wird.

Das KI-Panel braucht ein Gateway: `POST {gatewayUrl}/v1/agent` mit
`{prompt, mode, model, context}`, Antwort `{ok, text}`. Adresse und Token werden
zur Laufzeit gesetzt, nie im Code hinterlegt — dieses Paket enthält **keine**
Zugangsdaten. Der Vertrag steht in `lib/ai.js`.

## Verbindung zum Haus

Du kannst das Haus direkt fragen, statt zu raten oder etwas doppelt zu bauen.
Der Dienst heißt **haus-gateway** und ist als MCP-Server erreichbar. Den fertigen
Konfigurationsblock mit deinem Schlüssel gibt dir der Operator — er erzeugt ihn
mit `zugang-ausgeben.sh codex`; der Schlüssel steht bewusst nirgends in einem
Chatverlauf oder Ticket.

Auskünfte, alle **nur lesend**:

| Werkzeug | Frage dahinter |
|---|---|
| `haben_wir` | Gibt es X bei euch schon? |
| `bestand` | Was habt ihr in Bereich Y? |
| `wo_laeuft` | Auf welchem Host läuft es, und was darf ich dort? |
| `pruefe_vorhaben` | Baut ihr das gerade, oder ist es Neuland? |
| `frag_haus` | Freie Frage, wird an das Haus-Gateway weitergereicht. |

Jeder Aufruf wird protokolliert: Kennung, Werkzeug, Antwort. Dein Zugang hat ein
Ablaufdatum, eigene Rechte und einen Stundendeckel, und er lässt sich jederzeit
abschalten. Das ist Absicht und kein Misstrauen — es ist die Bedingung dafür,
dass ein fremdes Konto überhaupt hereindarf.

**Was heute noch nicht geht:** Es gibt noch keinen Briefkasten, in dem du eine
Nachricht zum Vorgang `xbrain` hinterlegst und ich sie abhole. Bis der steht,
läuft der Austausch über den Operator beziehungsweise über `frag_haus`. Der
Briefkasten ist angefragt; wenn er da ist, steht er hier.

## Wie wir zusammenarbeiten

- **Arbeite in deinem eigenen Baum.** Liefere einen Patch oder eine Beschreibung
  der Änderung. Schreib nicht in fremde Repos.
- **Deploye nichts von Hand.** Staging läuft ausschließlich über `codex-deploy`
  auf 178 — das Werkzeug erzwingt Port-Vergabe, Überschreib-Schutz und Sperre
  gegen gleichzeitige Läufe. Der 159er ist tabu.
- **Melde, statt still zu reparieren.** Wenn dir beim Arbeiten ein echter Fehler
  auffällt, der nicht zu deiner Aufgabe gehört: benenne ihn mit Fundstelle. Ein
  stiller Fix in fremdem Code ist schwerer nachzuvollziehen als ein Befund.
- **Sag, was du nicht gemessen hast.** „Konnte ich nicht prüfen" ist eine
  brauchbare Antwort. „Sieht gut aus" ist keine.

## Daten und Grenzen

Alle gemessenen Daten bleiben lokal in IndexedDB. Browser-interne Seiten,
Erweiterungs- und Neuer-Tab-Seiten sind von der Messung ausgenommen. Der echte
Lesezeichen-Baum wird nur gelesen und nie verändert; die KI-Sicht ist eine
getrennte virtuelle Struktur.

Eine Erweiterung lebt in einem Browser-Profil. Sie kann nicht gleichzeitig in
mehrere verschiedene Browser-Programme hineingreifen — pro Chromium-Browser eine
Installation.