@cachly-dev/mcp-server 0.10.124 → 0.10.126

package/dist/src/handlers/brain.js

@@ -3,11 +3,69 @@ import { createRequire } from 'node:module';
 import { calculateConfidence, confidenceBadge, STRUCTURED_TEMPLATES, CONFIDENCE_WARN_VALUE, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_DAYS } from '../confidence.js';
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge, ckgUpsertPersonNode, ckgUpsertFileNode, ckgRecordCollaboration, ckgUpsertServiceNode } from '../ckg.js';
 import { safeJsonParse, scanKeys } from '../utils.js';
+import { ersparteMinuten, istStarterLektion } from '../wertbeitrag.js';
+import { lessonPreviewLines, trimTo } from '../lesson-preview.js';
+import { meldeEinmal, OHNE_VEKTOREN, OHNE_DIENST, OHNE_FRAGEVEKTOR } from '../aussetzer.js';
+import { versuchStart, neueKennung, wendeZuteilungAn, schliesseVersuchAb } from '../versuch.js';
+/**
+ * Preview for one smart_recall hit.
+ *
+ * WHY THIS EXISTS: the previous version sliced `r.content` — the RAW JSON of the
+ * stored record — at 300/400 characters. So the budget was spent on syntax:
+ *
+ *   > {"topic":"node4:einrichtung-contabo-und-fallen","outcome":"success","sev…
+ *
+ * Roughly the first 80 characters carry no information at all, the reader gets
+ * field names instead of facts, and `commands` / `what_failed` never appear
+ * because they sit far past the cut. smart_recall is the call this project
+ * mandates BEFORE EVERY TASK — it is the worst possible place for that.
+ *
+ * A lesson is now rendered as a lesson: trimmed prose, its warning when the
+ * lesson is critical, and its commands/paths. Anything that is not a lesson
+ * (context entries, indexes) keeps a raw preview — but trimmed at a word
+ * boundary and with an honest cut marker.
+ */
+export function recallVorschau(key, content, maxChars) {
+    if (key.includes('lesson:best:')) {
+        const l = safeJsonParse(content, {});
+        if (l && typeof l === 'object' && (l.what_worked || l.what_failed || l.commands?.length)) {
+            return lessonPreviewLines(l, { maxChars, indent: '  ' });
+        }
+    }
+    const roh = trimTo(content, maxChars);
+    return roh ? [roh] : [];
+}
 import { getRole, ROLE_BADGE, getScopes, lessonVisibleToScope, reviewModeEnabled, storeLessonProposal } from './team.js';
-import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
+import { keywordSearch, wortindexEntwerten, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
 import { rerankByQuality, qualityMultiplier, extractLessonQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
+import { VEKTOR_PRAEFIX, NAME_VEKTOR_PRAEFIX, packe, textFuerVektor, textFuerNamensVektor, Vektorbestand, } from '../bedeutung.js';
+import { schreibeEingaenge, Eingangsbestand, EINGANG_GEWICHT } from '../eingaenge.js';
+import { Seltenheitsbestand } from '../seltenheitsbestand.js';
+import { spurLegen } from '../spuren.js';
+import { bewerteTopf, spreizeImTopf, reichereAn, inhaltsWoerter, grobStamm, GEWICHTE, } from '../rangfolge.js';
+/**
+ * Ein Vektorbestand fuer den ganzen Prozess.
+ *
+ * Er haelt rund 2 MB je 500 Lektionen im Arbeitsspeicher. Die bei jeder Frage
+ * neu zu holen waere langsamer als der Wortabgleich, den wir gerade ergaenzen —
+ * der Gewinn waere weg, bevor er anfaengt.
+ */
+const vektorbestand = new Vektorbestand();
+/** Dieselbe Mechanik, andere Sicht: die Vektoren der Themennamen. */
+const namensbestand = new Vektorbestand(60_000, NAME_VEKTOR_PRAEFIX);
+/** Die Fehlertext-Eingaenge, je Lektion ihr bester. */
+const eingangsbestand = new Eingangsbestand();
+/** Die Wortstatistik des Bestands — stehend, nicht je Frage neu. */
+const seltenheitsbestand = new Seltenheitsbestand();
 import { upgradeNudge } from '../upgrade-nudge.js';
+import { recallTiefe, TIEFE_VOLL, TIEFE_VOLL_MEHRTHEMIG } from '../recall-tiefe.js';
+import { nutzungInWorten, nutzungsSchluessel, verdichte } from '../werkzeug-nutzung.js';
+import { inWorten as lieferungInWorten, lieferBild, lieferSchluessel, trefferSchluessel } from '../geliefert.js';
+import { COAUTHOR_PREF_KEY, autorHinweis, coautorAus, echterGitLeser, ermittleAutor, mitCoautor, nurMensch } from '../autor.js';
+import { TOOLS } from '../tools.js';
+import { vorspannHinweis } from '../vorspann.js';
+import { autorAbzeichen, fremdanteil } from '../autor-abzeichen.js';
 import { cachlyUrl } from '../cachly-url.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
 // Resolve the package version at runtime from package.json so the session briefing
@@ -407,11 +465,15 @@ export const BRAIN_TOOL_NAMES = new Set([
 ]);
 // ── Free-tier Teaser-Gate ──────────────────────────────────────────────────
 // When a Free-tier Brain crosses its recall limit, smart_recall still delivers
-// the top hits — the magic moment is sacred — but withholds the long tail
-// behind an upgrade teaser ("🔒 N more relevant lessons available"). This is a
+// the top hit — the magic moment is sacred — but withholds the long tail
+// behind an upgrade teaser ("🔒 N further relevant lessons withheld"). This is a
 // DEPTH gate (hide the tail), never an access wall: the #1 result is always
 // returned. Usage/limit come from the same authoritative numbers as the Brain
 // Health bar (GET /instances/:id/memory), cached briefly to avoid per-call latency.
+//
+// Diese Zusage stand von 2026-07 bis 2026-08-18 NUR hier im Kommentar, waehrend
+// der Zweig `visibleCount = gateActive ? 0 : 8` null Treffer zurueckgab. Seither
+// ist sie eine Funktion mit Gegenprobe: ../recall-tiefe.ts (GROW-043).
 const UPGRADE_URL = cachlyUrl('/billing', 'upgrade');
 const _recallGateCache = new Map();
 /**
@@ -480,6 +542,29 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], depends_on = [], author = '', visibility = 'team', service = '', service_kind = 'service', group = '', } = args;
             const redis = await getConnection(instance_id);
             const ts = new Date().toISOString();
+            /*
+             * ── Der Autor wird HERGELEITET, nicht erwartet ─────────────────────
+             *
+             * Gemessen am 19.08.2026: 195 von 493 Lektionen ohne Autor. `author`
+             * war ein optionales Feld, das ein Agent bei jedem Aufruf mitschicken
+             * sollte — und natuerlich vergisst. Dabei steht der Name in
+             * `git config user.name`.
+             *
+             * Ein Pflichtfeld, das man vergessen kann, ist kein Pflichtfeld.
+             */
+            const herkunft = ermittleAutor({
+                uebergeben: author,
+                umgebung: process.env.CACHLY_AUTHOR,
+                git: echterGitLeser(process.env.CACHLY_WORKSPACE ?? process.cwd()),
+            });
+            // Mitautor nur, wenn ausdruecklich eingeschaltet — Standard ist aus.
+            let coautor = '';
+            try {
+                coautor = coautorAus(await redis.get(`cachly:prefs:${COAUTHOR_PREF_KEY}:${instance_id}`));
+            }
+            catch { /* eine Einstellung darf das Speichern nie stoppen */ }
+            const autorFeld = mitCoautor(herkunft.autor, coautor);
+            const autorTipp = autorHinweis(herkunft);
             // ── Lessons-Review workflow (P1-1) ─────────────────────────────────────
             // When the org enabled pending-mode on this (shared) brain, team-visible
             // lessons become proposals awaiting owner/admin approval instead of
@@ -489,7 +574,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 return storeLessonProposal(redis, topic, {
                     topic, outcome, what_worked, what_failed, context: ctx, severity,
                     file_paths, commands, tags, depends_on,
-                    ...(author ? { author } : {}),
+                    ...(autorFeld ? { author: autorFeld } : {}),
                     ...(service ? { service } : {}),
                     ...(group ? { group: String(group).toLowerCase().trim() } : {}),
                     visibility, recall_count: 0, ts, confidence: 1.0, version: 3,
@@ -611,7 +696,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 commands,
                 tags,
                 depends_on,
-                ...(author ? { author } : {}),
+                // Auch hier der hergeleitete Name — sonst traegt die gespeicherte
+                // Lektion selbst keinen Autor, waehrend der Kausalgraph einen hat.
+                ...(autorFeld ? { author: autorFeld } : {}),
                 ...(service ? { service } : {}),
                 ...(group ? { group: String(group).toLowerCase().trim() } : {}),
                 visibility,
@@ -633,11 +720,71 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             await redis.ltrim(listKey, -100, -1);
             await redis.expire(listKey, 90 * 86400);
             // Update best key for success/partial; for failure only update if no success exists
+            let bestGeschrieben = false;
             if (outcome === 'success' || outcome === 'partial') {
                 await redis.set(`cachly:lesson:best:${topic}`, lesson);
+                bestGeschrieben = true;
             }
             else if (!existingRaw) {
                 await redis.set(`cachly:lesson:best:${topic}`, lesson);
+                bestGeschrieben = true;
+            }
+            // Der stehende Wortindex kennt die neue Lektion noch nicht.
+            //
+            // Ohne diese Zeile waere sie bis zu eine Minute lang nicht auffindbar —
+            // und genau der Fall "gerade gelernt, sofort gesucht" ist der, bei dem
+            // ein Gedaechtnis sich beweisen muss. Der Index wird beim naechsten
+            // Recall neu gebaut, nicht hier: Lernen soll nicht auf das Bauen warten.
+            if (bestGeschrieben)
+                wortindexEntwerten();
+            // ── Vektor fuer den Bedeutungsabgleich ─────────────────────────────────
+            //
+            // Wird beim Schreiben berechnet, nicht beim Suchen. Der Grund steht in
+            // Zahlen: die Einbettung kostet rund 280 ms Netz. Einmal je Lektion ist
+            // das nichts, bei jeder Frage waere es der halbe Gewinn.
+            //
+            // Bewusst NICHT abgewartet: wer eine Lektion speichert, soll nicht auf
+            // einen fremden Dienst warten. Faellt die Einbettung aus, fehlt der
+            // Vektor — und der Bedeutungsabgleich uebergeht diese eine Lektion still.
+            // Das ist der Preis dafuer, dass Lernen immer funktioniert, auch ohne
+            // Netz. Wie viele Lektionen einen Vektor haben, meldet brain_doctor.
+            if (bestGeschrieben && hasEmbedProvider()) {
+                void (async () => {
+                    const gelesen = safeJsonParse(lesson, {});
+                    try {
+                        const v = await computeEmbedding(textFuerVektor(gelesen));
+                        if (v?.length)
+                            await redis.set(`${VEKTOR_PRAEFIX}${topic}`, packe(v));
+                    }
+                    catch { /* kein Vektor ist besser als keine Lektion */ }
+                    // Der Themenname als eigene Sicht.
+                    //
+                    // Er ist kurz und frageaehnlich; eine 60-Zeichen-Frage gegen 60
+                    // Zeichen zu halten ist symmetrisch, gegen 1376 Zeichen Volltext
+                    // nicht. Der Sortierer bewertet beide getrennt (naeheText 1,0,
+                    // naeheThema 0,6). Bis zum 20.08.2026 gab es diese Vektoren nur im
+                    // Messstand — deshalb war rangfolge.ts auch nie verdrahtet.
+                    try {
+                        const nv = await computeEmbedding(textFuerNamensVektor(topic));
+                        if (nv?.length)
+                            await redis.set(`${NAME_VEKTOR_PRAEFIX}${topic}`, packe(nv));
+                    }
+                    catch { /* siehe oben */ }
+                    // Die zweite Tuer: woertliche Fehlertexte als eigene Eingaenge.
+                    //
+                    // Gemessen am 20.08.2026 an 499 Lektionen mit zwei unabhaengigen
+                    // 100-Fragen-Saetzen: von fuenf ausprobierten Tuerarten traegt genau
+                    // DIESE eine. Erstsatz und Uebersetzung brachten null, der Themenname
+                    // steckt schon im Sortierer. Volle Zahlen und Gegenproben stehen in
+                    // .agent/cachly/tor0-tor1-ergebnis.md.
+                    //
+                    // Genau wie der Vektor: nicht abgewartet, Fehler verschluckt. Eine
+                    // Lektion muss auch ohne Netz gespeichert werden koennen.
+                    try {
+                        await schreibeEingaenge(redis, topic, gelesen, computeEmbedding);
+                    }
+                    catch { /* keine Eingaenge ist besser als keine Lektion */ }
+                })();
             }
             // Track in decision log for session replay
             try {
@@ -711,7 +858,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                                 fix_confidence: existEdge.confidence,
                                 fix_trials: existEdge.trials,
                                 failure_outcome: outcome,
-                                reported_by: author || 'unknown',
+                                reported_by: autorFeld || 'unknown',
                                 what_failed: what_failed || '',
                                 resolved: false,
                             }), 'EX', 60 * 60 * 24 * 90);
@@ -779,14 +926,19 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // ── Phase 3A: People + File nodes in knowledge graph ──────────────────────
             // Builds the "who knows what" map automatically from author + file_paths.
             // Person → authored → Concept edges power brain_who_knows queries.
-            if (author) {
+            //
+            // Seit dem 19.08.2026 steht hier autorFeld statt author: der Name wird
+            // aus git hergeleitet, wenn der Aufrufer keinen mitschickt. Vorher blieb
+            // dieser ganze Block bei zwei Fuenfteln aller Lektionen ungenutzt — und
+            // damit brain_who_knows leer.
+            if (autorFeld) {
                 // Agent activity registry (Move 4): track which agents are actively
                 // writing to this Brain, keyed by author, with a 1h TTL. Powers
                 // brain_conflicts' "who is live" view and multi-agent arbitration.
-                redis.set(`cachly:agents:active:${author}`, JSON.stringify({ author, last_topic: topic, last_outcome: outcome, ts: new Date().toISOString() }), 'EX', 60 * 60).catch(() => { });
+                redis.set(`cachly:agents:active:${autorFeld}`, JSON.stringify({ author: autorFeld, last_topic: topic, last_outcome: outcome, ts: new Date().toISOString() }), 'EX', 60 * 60).catch(() => { });
                 try {
                     const domain = topic.split(':')[0] ?? 'unknown';
-                    const personId = await ckgUpsertPersonNode(redis, author, domain);
+                    const personId = await ckgUpsertPersonNode(redis, nurMensch(autorFeld), domain);
                     const conceptId = ckgSlug(topic);
                     await ckgUpdateEdge(redis, personId, 'authored', conceptId, outcome === 'success', outcome === 'partial');
                     for (const fp of file_paths.slice(0, 8)) {
@@ -811,8 +963,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     const conceptId = ckgSlug(topic);
                     // concept → affects → service (outcome decides edge confidence)
                     await ckgUpdateEdge(redis, conceptId, 'affects', serviceId, outcome === 'success', outcome === 'partial');
-                    if (author) {
-                        const personId = `person:${ckgSlug(author)}`;
+                    if (autorFeld) {
+                        const personId = `person:${ckgSlug(nurMensch(autorFeld))}`;
                         await ckgUpdateEdge(redis, personId, 'operates', serviceId, true);
                     }
                     for (const fp of file_paths.slice(0, 8)) {
@@ -826,12 +978,12 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // auto-store as a team lesson so knowledge is shared without a separate
             // team_learn call. Tags gain 'team'; the lesson is attributed to the author.
             // This makes team knowledge sharing the default, not the opt-in.
-            if (author && (outcome === 'success' || outcome === 'partial')) {
+            if (autorFeld && (outcome === 'success' || outcome === 'partial')) {
                 const teamLesson = {
                     topic, outcome, what_worked,
                     what_failed: what_failed ?? '',
                     severity,
-                    author,
+                    author: autorFeld,
                     file_paths,
                     commands,
                     tags: [...new Set([...tags, 'team'])],
@@ -860,14 +1012,22 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 isUpdate
                     ? `♻️ Updated (recall count: ${recallCount} · audit entries: ${auditTrail.length})`
                     : `💡 Recall later with \`recall_best_solution(topic="${topic}")\``,
-                (author && (outcome === 'success' || outcome === 'partial'))
-                    ? `👥 Auto-shared with team (by _${author}_) — visible in \`team_recall\``
+                (autorFeld && (outcome === 'success' || outcome === 'partial'))
+                    ? `👥 Auto-shared with team (by _${autorFeld}_${herkunft.quelle !== 'uebergeben' ? ` · aus ${herkunft.quelle}` : ''}) — visible in \`team_recall\``
                     : '',
+                autorTipp ?? '',
                 depends_on.length > 0
                     ? `🔗 Depends on: ${depends_on.map(d => `\`${d}\``).join(', ')} → trace with \`trace_dependency\``
                     : '',
                 ...templateWarnings,
                 ...iWasWrongWarning,
+                // GROW-044: Die 100-Zeichen-Regel wird geprueft, nicht geglaubt.
+                // Das Briefing der naechsten Sitzung zeigt je Lektion rund 100
+                // Zeichen; am 16.08.2026 stand die gesuchte Adresse an Zeichen 323,
+                // die Lektion war eingeblendet und der Fehler passierte trotzdem.
+                // Hinweis statt Ablehnung: es gibt Lektionen ohne harte Zahl, und eine
+                // abgelehnte Lektion ist immer schlechter als eine unscharfe.
+                vorspannHinweis(what_worked) ?? '',
             ].filter(l => l !== '').join('\n');
         }
         case 'recall_best_solution': {
@@ -898,9 +1058,12 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 // A targeted lookup is a recall too, and costs the same one quota unit
                 // as a broad smart_recall — the user asked the brain a question either way.
                 void bumpRecallQuota(redis);
-                // Track estimated time saved (30m minor · 60m major · 240m critical)
-                const savedMins = lesson.severity === 'critical' ? 240 : lesson.severity === 'major' ? 60 : 30;
-                redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => { });
+                // Track estimated time saved (30m minor · 60m major · 240m critical).
+                // Starter-Lektionen zaehlen 0 — siehe wertbeitrag.ts.
+                const savedMins = ersparteMinuten(lesson);
+                if (savedMins > 0) {
+                    redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => { });
+                }
                 const sevEmoji = lesson.severity === 'critical' ? '🔴' : lesson.severity === 'major' ? '🟡' : lesson.severity ? '🟢' : '';
                 const auditSummary = (lesson.audit_trail ?? []).length > 1
                     ? `_Audit: ${(lesson.audit_trail ?? []).length} changes · stored ${new Date(lesson.ts).toLocaleDateString('de-DE')}_`
@@ -1006,11 +1169,179 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // ── Layer 1.5: Quality-aware rerank — proven success lessons outrank
             // text-similar failed attempts (the moat; see src/rerank.ts + Cachly-Bench). ──
             const kwMatches = rerankByQuality(rawMatches);
+            // ── Layer 1.7: Bedeutungsabgleich ──────────────────────────────────────
+            //
+            // Der Wortabgleich findet, was woertlich dasteht. Eine Frage beschreibt
+            // aber ein SYMPTOM, die Lektion eine URSACHE — "Der Deploy haengt beim
+            // Bauen" und "No space left on device" teilen kein Wort und meinen
+            // dasselbe.
+            //
+            // Gemessen am 19.08.2026 an 499 echten Lektionen mit 100 Fragen:
+            //
+            //   Verfahren      Platz 1   Top 3   Top 10
+            //   nur Woerter      21 %    33 %     47 %
+            //   nur Bedeutung    40 %    60 %     68 %
+            //   gemischt 30/70   39 %    55 %     71 %
+            //
+            // Gemischt wird, nicht ersetzt: ohne Netz gibt es keine Einbettung, und
+            // die ersten zehn Treffer sind gemischt besser als bei beiden einzeln.
+            //
+            // Faellt hier etwas aus, bleibt es beim Wortabgleich. Ein Recall, der
+            // wegen eines fremden Dienstes gar nichts liefert, waere schlimmer als
+            // einer, der schlechter sortiert.
+            //
+            // Jeder Ausstieg hier meldet sich EINMAL je Prozess (siehe
+            // `aussetzer.ts`). Am 20.08.2026 wurde gemessen, dass dieser Pfad in
+            // Produktion monatelang stumm ausstieg: 0 Vektoren bei 506 Lektionen.
+            // Von aussen war das von "alles in Ordnung" nicht zu unterscheiden.
+            let sinnAngewandt = false;
+            const kwGemischt = await (async () => {
+                if (!hasEmbedProvider()) {
+                    meldeEinmal(OHNE_DIENST, 'kein Einbettungsdienst eingerichtet — die Suche laeuft nur ueber Woerter');
+                    return kwMatches;
+                }
+                try {
+                    await vektorbestand.aktualisiere(redis);
+                    if (vektorbestand.groesse === 0) {
+                        meldeEinmal(OHNE_VEKTOREN, 'keine einzige Lektion hat eine Einbettung — die Suche laeuft nur ueber '
+                            + 'Woerter. Nachruesten mit eingaenge-nachruesten, pruefen mit brain_doctor');
+                        return kwMatches;
+                    }
+                    const frageVektor = await computeEmbedding(query);
+                    if (!frageVektor?.length) {
+                        meldeEinmal(OHNE_FRAGEVEKTOR, 'die Frage liess sich nicht einbetten — diese Suche laeuft nur ueber Woerter');
+                        return kwMatches;
+                    }
+                    await namensbestand.aktualisiere(redis);
+                    await eingangsbestand.aktualisiere(redis);
+                    await seltenheitsbestand.aktualisiere(redis);
+                    const wortThemen = kwMatches
+                        .filter((m) => m.key.startsWith('cachly:lesson:best:'))
+                        .map((m) => m.key.slice('cachly:lesson:best:'.length));
+                    // ── Die Vorauswahl ────────────────────────────────────────────────
+                    //
+                    // Woerter (Top 25) vereinigt mit Bedeutung (Top 25). Bei vorhandenen
+                    // Eingaengen zaehlt je Lektion ihr BESTER Eingang statt des
+                    // Volltextvektors — gemessen am 20.08.2026 hebt das die Findequote@3
+                    // von 52 auf 56 Prozent, und mit dem Merkmal unten auf 58.
+                    //
+                    // Der Preis steht offen im Ergebnisdokument: dieselben Eingaenge
+                    // SENKEN die Decke von 89 auf 86 Prozent. Fuer den Nutzer zaehlt die
+                    // Findequote — er sieht drei Lektionen, nicht 25.
+                    //
+                    // WICHTIG: das Maximum ueber ALLE Tueren — Volltext, Themenname UND
+                    // Fehlertext. Der erste Versuch am 20.08. hat die Volltext-Auswahl
+                    // durch die Eingangs-Auswahl ERSETZT. Das war falsch: nur 399 von 507
+                    // Lektionen tragen einen Fehlertext, die uebrigen 108 fielen damit
+                    // aus der Vorauswahl. Am echten Bestand gemessen fiel die Trefferlage
+                    // von 90 auf 70 Prozent und die Findequote@3 von 50 auf 48.
+                    const naeheBesteTuer = (t) => Math.max(vektorbestand.naehe(frageVektor, t), namensbestand.naehe(frageVektor, t), eingangsbestand.besteNaehe(frageVektor, t));
+                    const alleThemen = [...seltenheitsbestand.themen()];
+                    const sinnThemen = (alleThemen.length > 0
+                        ? alleThemen
+                        : vektorbestand.aehnlichste(frageVektor, 500).map((x) => x.topic))
+                        .map((t) => ({ t, n: naeheBesteTuer(t) }))
+                        .sort((a, b) => b.n - a.n)
+                        .slice(0, 25)
+                        .map((x) => x.t);
+                    // ── Die Sortierung ───────────────────────────────────────────────
+                    //
+                    // Bis zum 20.08.2026 stand hier `mischeRangfolgen` (Reciprocal Rank
+                    // Fusion). Das war der Grund, warum die ganze Eingangs-Arbeit im
+                    // Produkt fast nichts brachte: RRF mischt ueber PLATZIERUNGEN und
+                    // kann die Naehe zum besten Eingang nicht als abgestufte Groesse
+                    // verwerten.
+                    //
+                    //   frischer Pruefsatz, Findequote@3
+                    //     RRF, wie ausgeliefert                    50 %
+                    //     RRF + Eingaenge als dritte Quelle        51 %
+                    //     bewerteTopf                              52 %
+                    //     bewerteTopf + Eingaenge                  58 %
+                    //
+                    // Faellt ein Merkmal aus (kein Namensvektor, kein Eingang), meldet es
+                    // -2 und `spreizeImTopf` macht daraus fuer alle dieselbe Null — die
+                    // Sortierung faellt dann auf die uebrigen Merkmale zurueck, statt
+                    // falsch zu werden.
+                    const topf = [...new Set([...wortThemen, ...sinnThemen])];
+                    const besteDrei = sinnThemen.slice(0, 3)
+                        .map((t) => vektorbestand.rohvektor(t)).filter(Boolean);
+                    const angereichert = besteDrei.length ? reichereAn(frageVektor, besteDrei) : frageVektor;
+                    const frageWoerter = inhaltsWoerter(query);
+                    const statistik = seltenheitsbestand.statistik;
+                    const bewertbar = topf.map((t) => ({
+                        naeheText: vektorbestand.naehe(frageVektor, t),
+                        naeheThema: namensbestand.naehe(frageVektor, t),
+                        naeheRueckkopplung: vektorbestand.naehe(angereichert, t),
+                        seltenheitsDeckung: statistik
+                            ? statistik.deckung(frageWoerter, new Set([...inhaltsWoerter(seltenheitsbestand.textVon(t))].map(grobStamm)))
+                            : 0,
+                    }));
+                    let punkte = bewerteTopf(bewertbar, GEWICHTE);
+                    if (eingangsbestand.groesse > 0) {
+                        const naehen = topf.map((t) => eingangsbestand.besteNaehe(frageVektor, t));
+                        const gespreizt = spreizeImTopf(naehen);
+                        punkte = punkte.map((pkt, i) => pkt + EINGANG_GEWICHT * gespreizt[i]);
+                    }
+                    const reihenfolge = topf
+                        .map((t, i) => ({ t, p: punkte[i] }))
+                        .sort((a, b) => b.p - a.p)
+                        .map((x) => x.t);
+                    const bekannt = new Map(kwMatches.map((m) => [m.key, m]));
+                    // Lektionen, die NUR der Bedeutungsabgleich gefunden hat, muessen
+                    // nachgeladen werden — der Wortabgleich hat sie nie angefasst.
+                    const sortiert = [];
+                    for (const thema of reihenfolge) {
+                        const key = `cachly:lesson:best:${thema}`;
+                        const da = bekannt.get(key);
+                        if (da) {
+                            sortiert.push(da);
+                            bekannt.delete(key);
+                            continue;
+                        }
+                        const inhalt = await redis.get(key).catch(() => null);
+                        if (inhalt) {
+                            sortiert.push({ key, content: inhalt, score: 0, matchedWords: [], finalScore: 0, qualityBoost: 1 });
+                        }
+                    }
+                    // Alles, was kein Thema war (Kontexteintraege, Index), bleibt hinten
+                    // erhalten statt still zu verschwinden.
+                    sortiert.push(...bekannt.values());
+                    sinnAngewandt = true;
+                    return sortiert;
+                }
+                catch {
+                    return kwMatches;
+                }
+            })();
+            void sinnAngewandt;
             // One quota unit for this call, regardless of how many lessons it surfaced.
             void bumpRecallQuota(redis);
+            // ── Gedaechtniszellen ────────────────────────────────────────────────
+            //
+            // Diese Frage hat diese Lektionen gefunden — das ist ein bewiesener Weg
+            // zu ihnen. Fuehrt dieselbe Frage ein ZWEITES Mal hierher, wird sie ein
+            // eigener Eingang, und beim naechsten Mal ist der Weg breiter.
+            //
+            // Warum erst beim zweiten Mal: das Signal "wurde benutzt" gibt es nicht.
+            // Der Server sieht, was er ausgeliefert hat, nicht was jemand damit
+            // gemacht hat. Wiederholung IST das, was einen Trampelpfad ausmacht.
+            //
+            // Nur die ersten DREI: das ist, was die Einblendung zeigt. Wer alle
+            // Treffer aufzeichnet, macht aus jedem Streifschuss einen Weg.
+            //
+            // Nicht abgewartet: wer sucht, soll nicht warten, bis das Gedaechtnis
+            // nachgefuehrt ist.
+            if (hasEmbedProvider()) {
+                const gefundeneThemen = kwGemischt
+                    .filter((m) => m.key.startsWith('cachly:lesson:best:'))
+                    .slice(0, 3)
+                    .map((m) => m.key.slice('cachly:lesson:best:'.length));
+                void spurLegen(redis, query, gefundeneThemen, computeEmbedding)
+                    .catch(() => { });
+            }
             const savedHere = [];
             // Exclude archived lessons — they are kept for audit but must not surface in recall.
-            const lessonMatches = kwMatches.filter(m => m.key.startsWith('cachly:lesson:best:'));
+            const lessonMatches = kwGemischt.filter(m => m.key.startsWith('cachly:lesson:best:'));
             let crossAuthorThisCall = 0;
             let successRecallsThisCall = 0;
             for (const m of lessonMatches.slice(0, 5)) {
@@ -1024,9 +1355,11 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const recalledAt = new Date().toISOString();
                         const updated = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1, verified_at: recalledAt, last_recalled_at: recalledAt };
                         redis.set(m.key, JSON.stringify(updated)).catch(() => { });
-                        const sev = lesson.severity;
-                        const savedMins = sev === 'critical' ? 240 : sev === 'major' ? 60 : 30;
-                        redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => { });
+                        // Starter-Lektionen zaehlen 0 — siehe wertbeitrag.ts.
+                        const savedMins = ersparteMinuten(lesson);
+                        if (savedMins > 0) {
+                            redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => { });
+                        }
                         // Metric 3 (team-knowledge-reuse): a recall of a lesson authored by
                         // someone OTHER than the requester is cross-author reuse — the value
                         // only cachly delivers. Track total proven recalls + cross-author ones.
@@ -1044,11 +1377,16 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         }
                         if (lesson.outcome === 'success')
                             successRecallsThisCall++;
-                        // Surface banner for proven successes (recall_count >= 1 means it's been validated)
-                        if (lesson.outcome === 'success' && (lesson.recall_count ?? 0) >= 1) {
+                        // Surface banner for proven successes (recall_count >= 1 means it's been validated).
+                        //
+                        // Der Startvorrat kommt hier NICHT ins Banner. "Brain saved you ~8h
+                        // here — docker:layer-cache" ist keine Leistung des Gedaechtnisses,
+                        // sondern mitgeliefertes Allgemeinwissen. Genau dieses Banner hat
+                        // die Zahl im Panel jahrelang glaubwuerdig aussehen lassen.
+                        if (lesson.outcome === 'success' && (lesson.recall_count ?? 0) >= 1 && !istStarterLektion(lesson)) {
                             savedHere.push({
                                 topic: m.key.replace('cachly:lesson:best:', ''),
-                                severity: sev ?? 'major',
+                                severity: lesson.severity ?? 'major',
                                 recall_count: (lesson.recall_count ?? 0) + 1,
                                 savedMins,
                                 ts: lesson.ts,
@@ -1098,12 +1436,12 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     // Semantic search failed silently — keyword results are enough
                 }
             }
-            const bm25Scores = kwMatches.map(m => m.score);
+            const bm25Scores = kwGemischt.map(m => m.score);
             const bm25Min = bm25Scores.length ? Math.min(...bm25Scores) : 0;
             const bm25Range = bm25Scores.length ? (Math.max(...bm25Scores) - bm25Min) || 1 : 1;
             const bm25Norm = (s) => (s - bm25Min) / bm25Range;
             const hybridMap = new Map();
-            for (const m of kwMatches) {
+            for (const m of kwGemischt) {
                 const n = bm25Norm(m.score);
                 hybridMap.set(m.key, {
                     key: m.key, content: m.content, bm25Score: n,
@@ -1227,14 +1565,49 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 return true;
             })
                 .sort((a, b) => b.hybridScore - a.hybridScore);
+            // ── Versuch (Messtechnik, siehe versuch.ts) ───────────────────────────────
+            //
+            // Standardmaessig AUS: `versuchStart()` gibt dann `null` zurueck, und
+            // dieser ganze Block tut nichts — `hybridResults` bleibt unangetastet,
+            // nichts wird nach Redis geschrieben, kein Zeichen im Text aendert sich.
+            // Erst mit `CACHLY_VERSUCH=an` UND gesetztem Salz greift die Zuteilung.
+            const versuchSalz = versuchStart();
+            let versuchKennung = '';
+            let versuchTeil = null;
+            if (versuchSalz !== null) {
+                versuchKennung = neueKennung();
+                const hoechstePunktzahl = hybridResults[0]?.hybridScore ?? 0;
+                const ergebnis = wendeZuteilungAn(hybridResults.map((r) => ({ key: r.key, content: r.content, punktzahl: r.hybridScore })), versuchKennung, versuchSalz, hoechstePunktzahl);
+                if (ergebnis.weggelassenesThema !== undefined) {
+                    // HOLD: der bisher beste Treffer wird aus der ausgelieferten Liste
+                    // entfernt. Die uebrigen Treffer und ihre Reihenfolge bleiben gleich.
+                    hybridResults.splice(0, 1);
+                }
+                else if (ergebnis.markierungGesetzt && hybridResults[0] && ergebnis.treffer[0]) {
+                    // DELIVER: derselbe Treffer, aber sein Inhalt traegt jetzt die
+                    // Kanarien-Markierung am Ende von `what_worked`.
+                    hybridResults[0] = { ...hybridResults[0], content: ergebnis.treffer[0].content };
+                }
+                versuchTeil = {
+                    frage: query,
+                    hoechstePunktzahl,
+                    themen: [], // unten befuellt, sobald feststeht, was wirklich sichtbar ist
+                    zulassungsfaehig: ergebnis.zulassungsfaehig,
+                    zulassungsGrund: ergebnis.zulassungsGrund,
+                    zuteilung: ergebnis.zuteilung,
+                    weggelassenesThema: ergebnis.weggelassenesThema,
+                    markierungGesetzt: ergebnis.markierungGesetzt,
+                };
+            }
             // ── Teaser-Gate: free tier over its recall limit hides the long tail ──────
             const recallGate = await getRecallGate(instance_id, apiFetch);
-            // Hard gate: once a free user is over their (monthly, goodwill-adjusted)
-            // recall limit, the long tail is fully withheld until they upgrade or the
-            // month resets. We still show the single highest-value proven lesson below
-            // as a teaser so the tool isn't dead and the value is obvious.
+            // Depth gate: once a free user is over their (monthly, goodwill-adjusted)
+            // recall limit, the LONG TAIL is withheld — never the top hit. The rule
+            // lives in recall-tiefe.ts with tests (GROW-043), because it used to live
+            // only in a comment while the branch said `? 0 :` and returned nothing.
             const gateActive = recallGate.reached;
-            const visibleCount = gateActive ? 0 : 8;
+            const tiefe = recallTiefe({ ueberLimit: gateActive, gesamt: hybridResults.length, volleTiefe: TIEFE_VOLL });
+            const visibleCount = tiefe.sichtbar;
             // ── Build output ──────────────────────────────────────────────────────────
             const lines = [`🧠 **Smart Recall** for: _"${query}"_\n`];
             // Warm goodwill note — shown the month a free user is gifted +250 recalls.
@@ -1288,7 +1661,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 // Group by sub-query for multi-topic queries
                 if (subQueries.length > 1) {
                     const grouped = new Map();
-                    for (const r of hybridResults.slice(0, gateActive ? 0 : 12)) {
+                    const tiefeMehrthemig = recallTiefe({ ueberLimit: gateActive, gesamt: hybridResults.length, volleTiefe: TIEFE_VOLL_MEHRTHEMIG });
+                    for (const r of hybridResults.slice(0, tiefeMehrthemig.sichtbar)) {
                         const sq = r.subQuery ?? query;
                         if (!grouped.has(sq))
                             grouped.set(sq, []);
@@ -1307,7 +1681,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                                         : r.matchType === 'semantic'
                                             ? `sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🎯 semantic`
                                             : `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, matched: ${r.matchedWords?.join(', ')}`;
-                            const preview = r.content.slice(0, 300).replace(/\n/g, ' ');
+                            const vorschau = recallVorschau(r.key, r.content, 300);
                             lines.push(`  **${label}** _(${scorePart})_`);
                             // Lesbares Brain (docs/produkt/team-puls.md P1): plain-language layer
                             // stored at lesson:human:<topic> — display-only, ranking untouched.
@@ -1318,7 +1692,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                                 if (h.title)
                                     lines.push(`  📖 **${h.title}** — ${h.summary ?? ''}`);
                             }
-                            lines.push(`  > ${preview}${r.content.length > 300 ? '…' : ''}\n`);
+                            for (const z of vorschau)
+                                lines.push(`  > ${z}`);
+                            lines.push('');
                         }
                     }
                     const matched = [...grouped.keys()];
@@ -1342,7 +1718,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             : r.matchType === 'semantic'
                                 ? `sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🎯 semantic`
                                 : `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, matched: ${r.matchedWords?.join(', ')}`;
-                        const preview = r.content.slice(0, 400).replace(/\n/g, ' ');
+                        const vorschau = recallVorschau(r.key, r.content, 400);
                         lines.push(`**${label}**${authorBadge}${contextBadge} _(${scorePart})_`);
                         // Lesbares Brain (docs/produkt/team-puls.md P1): plain-language layer.
                         if (r.key.startsWith('cachly:lesson:best:')) {
@@ -1352,14 +1728,18 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             if (h.title)
                                 lines.push(`📖 **${h.title}** — ${h.summary ?? ''}`);
                         }
-                        lines.push(`> ${preview}${r.content.length > 400 ? '…' : ''}\n`);
+                        for (const z of vorschau)
+                            lines.push(`> ${z}`);
+                        lines.push('');
                     }
                 }
-                // ── Hard gate footer: over the recall limit, the tail is withheld ──────
-                if (gateActive) {
-                    const withheld = Math.max(0, hybridResults.length - visibleCount);
+                // ── Depth-gate footer: the top hit stayed, the tail is withheld ────────
+                // Only speak when something was actually held back — announcing
+                // "0 lessons withheld" would sell a wall that isn't there.
+                if (gateActive && tiefe.zurueckgehalten > 0) {
+                    const withheld = tiefe.zurueckgehalten;
                     lines.push(`🔒 **Free recall limit reached** (${recallGate.used}/${recallGate.limit} this month). ` +
-                        `${withheld} relevant lesson${withheld !== 1 ? 's' : ''} withheld. ` +
+                        `Showing your top match; ${withheld} further relevant lesson${withheld !== 1 ? 's are' : ' is'} withheld. ` +
                         `Your limit resets next month, or unlock your full Brain now → ${UPGRADE_URL}\n`);
                 }
             }
@@ -1397,6 +1777,15 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     lines.push(`  • Use \`recall_best_solution("topic")\` for exact topic lookup`);
                 }
             }
+            // Versuch, Abschluss: Kanarienvogel gegen die WIRKLICH zusammengebaute
+            // Antwort pruefen, Markierung entfernen, Protokoll schreiben (schlaegt
+            // das fehl, bleibt die Antwort trotzdem stehen — siehe schreibeTurnProtokoll).
+            if (versuchSalz !== null && versuchTeil) {
+                const themen = hybridResults.slice(0, visibleCount)
+                    .filter((r) => r.key.startsWith('cachly:lesson:best:'))
+                    .map((r) => r.key.slice('cachly:lesson:best:'.length));
+                return schliesseVersuchAb(redis, versuchKennung, { ...versuchTeil, themen }, lines.join('\n'));
+            }
             return lines.join('\n');
         }
         // ── get_api_status ────────────────────────────────────────────────────────
@@ -1741,7 +2130,13 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // auto-promote a lesson without any manual step.
             {
                 const CRYSTALLIZE_RECALLS = 5;
+                // Der Startvorrat wird nie zum Gesetz. Eine mitgelieferte Lektion sammelt
+                // Abrufe, weil sie zu allem ein bisschen passt — nicht, weil sie sich
+                // bewaehrt hat. Gemessen am 17.08.2026: Die fuenf obersten "Gesetze"
+                // eines Brains mit 475 Lektionen waren alle aus dem Startvorrat, und die
+                // echten Lektionen standen darunter bei zwei bis fuenf Abrufen.
                 const laws = lessons
+                    .filter(l => !istStarterLektion(l))
                     .filter(l => l.outcome === 'success' && (l.pinned === true || (l.recall_count ?? 0) >= CRYSTALLIZE_RECALLS))
                     .sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0))
                     .slice(0, 5);
@@ -1751,7 +2146,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
                         const rc = l.recall_count ?? 0;
                         const why = l.pinned === true ? 'pinned' : `recalled ${rc}×`;
-                        lines.push(`  🏆${sev} \`${l.topic}\` _(${why})_ — ${l.what_worked.slice(0, 100)}`);
+                        const body = lessonPreviewLines(l);
+                        lines.push(`  🏆${sev} \`${l.topic}\` _(${why})_ — ${body[0] ?? ''}`, ...body.slice(1));
                     }
                     lines.push('');
                 }
@@ -1841,14 +2237,18 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 for (const l of focusLessons.slice(0, 4)) {
                     const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
                     const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
-                    lines.push(`  ${emoji}${sev} \`${l.topic}\` — ${l.what_worked.slice(0, 100)}`);
+                    const body = lessonPreviewLines(l);
+                    lines.push(`  ${emoji}${sev} \`${l.topic}\` — ${body[0] ?? ''}`, ...body.slice(1));
                 }
                 lines.push('');
             }
             // Top lessons — sorted by recall_count desc (most-used = most proven value).
             // If focus is set, focus-matched lessons already shown above; show remaining here.
             if (lessons.length > 0) {
-                const byRecall = [...lessons].sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0));
+                // Auch hier ohne Startvorrat: "Most valuable" soll zeigen, was DIESES
+                // Team gelernt hat, nicht was mitgeliefert wurde.
+                const byRecall = [...lessons].filter(l => !istStarterLektion(l))
+                    .sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0));
                 const topRecalled = byRecall.filter(l => (l.recall_count ?? 0) > 0).slice(0, 3);
                 const remaining = (focusLessons.length > 0 ? lessons.filter(l => !focusLessons.includes(l)) : lessons)
                     .filter(l => !topRecalled.includes(l))
@@ -1865,7 +2265,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const trust = (nAuthors >= 2 && rc >= 5) || rc >= 10 ? ' 🏆'
                             : nAuthors >= 2 || rc >= 5 ? ' ✅' : '';
                         const rct = rc > 1 ? ` _(${rc}× recalled)_` : '';
-                        lines.push(`  ${emoji}${sev}${trust} \`${l.topic}\`${rct} — ${l.what_worked.slice(0, 100)}`);
+                        const body = lessonPreviewLines(l);
+                        lines.push(`  ${emoji}${sev}${trust} \`${l.topic}\`${rct} — ${body[0] ?? ''}`, ...body.slice(1));
                     }
                     lines.push('');
                 }
@@ -1875,7 +2276,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     for (const l of remaining) {
                         const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
                         const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
-                        lines.push(`  ${emoji}${sev} \`${l.topic}\` — ${l.what_worked.slice(0, 100)}`);
+                        const body = lessonPreviewLines(l);
+                        lines.push(`  ${emoji}${sev} \`${l.topic}\` — ${body[0] ?? ''}`, ...body.slice(1));
                     }
                     lines.push('');
                 }
@@ -2323,9 +2725,19 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 const rc = l.recall_count ?? 0;
                 const rcStr = rc > 0 ? ` (✓ recalled ${rc}×)` : '';
                 const snippet = l.what_worked.slice(0, 110);
-                summaryLines.push(`${sevIcon} ${sevLabel}\`${l.topic}\` — ${snippet}${rcStr}`);
+                // GROW-045: `author` wurde bisher nur entgegengenommen, nie benutzt —
+                // obwohl die Werkzeug-Spezifikation "used for team lesson filtering"
+                // verspricht. Dieselbe Regel wie in smart_recall, jetzt aus EINEM Modul.
+                const autor = autorAbzeichen(l.author, author);
+                summaryLines.push(`${sevIcon} ${sevLabel}\`${l.topic}\` — ${snippet}${rcStr}${autor}`);
             }
             summaryLines.push('');
+            // Die Zahl, die nur ein GETEILTES Gedaechtnis liefert. Ist sie null,
+            // wird nichts gesagt: "0 von Teamkollegen" ist keine Nachricht.
+            const fremde = fremdanteil(selected, author);
+            if (fremde > 0) {
+                summaryLines.push(`👥 ${fremde} of these ${fremde === 1 ? 'was' : 'were'} written by a teammate — the value only a shared brain delivers.`, '');
+            }
             if (needsRanking) {
                 summaryLines.push(`💡 Showing top ${shown} of ${total} lessons · \`session_start\` for full briefing`);
             }
@@ -3169,6 +3581,38 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 redis.get(`cachly:stats:time_saved_mins:${instance_id}`).catch(() => null),
                 redis.smembers(`cachly:stats:reuse_pairs:${instance_id}`).catch(() => []),
             ]);
+            // ── GROW-046: welche Werkzeuge dieses Brain wirklich benutzt ────────────
+            // Bewusst HIER und nicht in einem eigenen Werkzeug: ein 123. Werkzeug,
+            // um zu messen, dass es zu viele Werkzeuge gibt, waere die Pointe, die
+            // niemand will.
+            // try/catch und nicht nur .catch(): faellt die Methode ganz aus (aelterer
+            // Client, anderer Redis-Aufsatz), wirft schon der AUFRUF, und eine
+            // Zusagen-Absicherung greift dann nicht. Eine Messzeile darf das
+            // Werkzeug nie stoppen.
+            let werkzeugRoh = {};
+            try {
+                werkzeugRoh = (await redis.hgetall(nutzungsSchluessel(instance_id))) ?? {};
+            }
+            catch {
+                werkzeugRoh = {};
+            }
+            const nutzung = verdichte(werkzeugRoh, 10);
+            // ── Die GEMESSENE Ersparnis, neben der gerechneten ─────────────────────
+            // Heinrich am 19.08.2026: "Bei der Schaetzung der Tokenersparnis sollten
+            // wir schauen, dass wir nicht nur schaetzen, denn das nervt Leute sehr
+            // stark." Dies hier ist eine Summe, keine Rechnung: die Laenge dessen,
+            // was das Brain wirklich zurueckgegeben hat. Dieselbe try/catch-Vorsicht
+            // wie oben — eine Messzeile darf das Werkzeug nie stoppen.
+            let lieferRoh = { token: 0, abrufe: 0, treffer: 0 };
+            try {
+                const token = await redis.get(lieferSchluessel(instance_id));
+                const quoten = (await redis.hgetall(trefferSchluessel(instance_id))) ?? {};
+                lieferRoh = { token: token ?? 0, abrufe: quoten.abrufe ?? 0, treffer: quoten.treffer ?? 0 };
+            }
+            catch {
+                // still
+            }
+            const lieferung = lieferBild(lieferRoh);
             // ── Metric 1: Time-to-first-recall ──────────────────────────────────────
             let ttfrLine;
             if (bornAt && firstRecallAt) {
@@ -3192,6 +3636,36 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             const crossAuthor = Number(crossAuthorRaw ?? 0);
             const reusePct = recallsTotal > 0 ? Math.round((crossAuthor / recallsTotal) * 100) : 0;
             const reuseTarget = reusePct >= 30 ? '🟢 above 30 % target' : recallsTotal === 0 ? '⚪ no recalls yet' : '🟡 below 30 % target';
+            /*
+             * ── Die geschaetzten Stunden stehen nicht mehr im Kundenblick ─────────
+             *
+             * "1.429,5 h total saved not re-researching known fixes" war die
+             * groesste erfundene Zahl, die wir gezeigt haben. Sie ist gerechnet:
+             * Minuten je Lektion nach Schwere, mal Abrufzahl. Der Faktor ist
+             * geraten, und die Zahl waechst mit jedem Abruf mit — auch mit einem,
+             * der nichts gefunden hat.
+             *
+             * Heinrich am 19.08.2026 zur alten Fassung: "Ich tue mich schwer mit den
+             * 1200 h. Das haette vielleicht frueher zugetroffen, zu
+             * Entwicklungszeiten ohne AI, aber heutzutage nicht mehr. Die erscheint
+             * laecherlich hoch."
+             *
+             * Genau so ist es. Die Annahme dahinter — 30 bis 240 Minuten Recherche
+             * je Lektion — ist der Preis von VOR den Assistenten. Heute findet ein
+             * Modell dasselbe in Sekunden. Die Zahl misst eine Welt, die es nicht
+             * mehr gibt.
+             *
+             * FREMDBELEG dazu (Artikel 4278052, METR-Studie): erfahrene Entwickler
+             * FUEHLTEN sich mit KI schneller und waren gemessen 19 Prozent
+             * langsamer. Selbstauskunft und Messung zeigen in entgegengesetzte
+             * Richtungen — eine geschaetzte Zeitersparnis ist die schnellste Art,
+             * Vertrauen fuer alle anderen Zahlen gleich mit zu verlieren.
+             *
+             * Sie wird nicht geloescht, sondern ZURUECKGESTUFT: sie steht weiterhin
+             * da, aber klein, mit ihrer Annahme im selben Satz, und unter der
+             * gemessenen Liefermenge. Eine erfundene Zahl ALLEIN nervt; eine
+             * gemessene daneben traegt sie.
+             */
             const timeSaved = Math.round(Number(timeSavedRaw ?? 0));
             const timeSavedHuman = timeSaved < 60 ? `${timeSaved} min` : `${(timeSaved / 60).toFixed(1)} h`;
             const lines = [
@@ -3209,10 +3683,24 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 reusePairs.length > 0 ? `**${reusePairs.length}** distinct reuse relationship${reusePairs.length !== 1 ? 's' : ''} across the team` : '',
                 ``,
                 `---`,
-                `⏱️ **${timeSavedHuman}** total saved not re-researching known fixes.`,
+                // GEMESSEN zuerst, GESCHAETZT darunter — in dieser Reihenfolge, immer.
+                // Vorher stand die gerechnete Stundenzahl ganz oben und fett; die
+                // einzige Zahl ohne Annahme kam gar nicht vor.
+                `### 📦 Aus dem Brain geliefert _(gemessen, nicht gerechnet)_`,
+                lieferungInWorten(lieferung),
+                ``,
+                lieferung.abrufe > 0
+                    ? `_Daneben eine **Schätzung**: ${timeSavedHuman} nicht neu recherchiert — gerechnet mit 30–240 Min. je Lektion nach Schwere, nicht gemessen. Die Zahl darüber braucht diese Annahme nicht._`
+                    : `_Eine **Schätzung** von ${timeSavedHuman} „nicht neu recherchiert" wäre hier gerechnet, nicht gemessen — sie erscheint erst, wenn daneben eine gemessene Zahl steht._`,
                 recallsTotal === 0
                     ? `_Tip: pass \`author="your-handle"\` to \`smart_recall\` so cross-author reuse can be tracked._`
                     : `_These numbers compound: every learned lesson and every teammate raises all three._`,
+                ``,
+                `### 🔧 Werkzeug-Nutzung _(erst messen, dann zusammenlegen)_`,
+                nutzungInWorten(nutzung, TOOLS.length),
+                ...(nutzung.spitze.length > 0
+                    ? nutzung.spitze.map((z, i) => `  ${String(i + 1).padStart(2)}. \`${z.name}\` — ${z.aufrufe}× (${Math.round(z.anteil * 100)} %)`)
+                    : []),
             ].filter(Boolean);
             return lines.join('\n');
         }