kimal3 0.4.0 → 0.5.0

package/dist/zeigen-rechnung.js

@@ -0,0 +1,226 @@
+// Reine Rechnungen hinter `kimal3 zeigen` (Aufnahme von Bildschirm und Ton fuer Claude).
+// Kein Dateisystem, kein Prozess, keine Anzeige-Texte: Die Befehle holen die Fakten und fragen hier.
+// Gedeckt von `npm run check:zeigen` (Spec 2026-10-18-k3zeigen-design.md).
+import { win32 } from "node:path";
+const MAX_PFAD_WINDOWS = 170;
+/** "2026-10-19-0912" in Ortszeit. */
+export function ordnerName(jetzt) {
+    const z = (n) => String(n).padStart(2, "0");
+    return `${jetzt.getFullYear()}-${z(jetzt.getMonth() + 1)}-${z(jetzt.getDate())}-${z(jetzt.getHours())}${z(jetzt.getMinutes())}`;
+}
+/** Index des Projektordners im Segment-Array, -1 wenn keiner, -2 wenn der Pfad bei der Werkbank endet. */
+function projektEnde(segmente) {
+    const i = segmente.findIndex((s) => /^(werkbank|workbench)-/i.test(s));
+    if (i < 0)
+        return -1;
+    const projekte = /^werkbank-/i.test(segmente[i]) ? /^projekte$/i : /^projects$/i;
+    if (i === segmente.length - 1)
+        return -2;
+    if (!projekte.test(segmente[i + 1]))
+        return -1;
+    return i + 2 < segmente.length ? i + 2 : -2;
+}
+/** Wohin die Aufnahme faellt: ins Projekt, in dem man steht -- nie in die Werkbank selbst. */
+export function aufnahmeOrt(start, jetzt, plattform, gibtEs) {
+    const trenner = start.includes("\\") ? "\\" : "/";
+    const segmente = start.split(/[\\/]/);
+    while (segmente.length > 1 && segmente[segmente.length - 1] === "")
+        segmente.pop();
+    const ende = projektEnde(segmente);
+    if (ende === -2)
+        return { art: "werkbank" };
+    const projekt = (ende >= 0 ? segmente.slice(0, ende + 1) : segmente).join(trenner);
+    const aufnahmen = `${projekt}${trenner}material${trenner}aufnahmen`; // kein-anzeigetext: Ordnerpfad
+    const basis = `${aufnahmen}${trenner}${ordnerName(jetzt)}`;
+    let ordner = basis;
+    for (let n = 2; gibtEs(ordner); n++)
+        ordner = `${basis}-${n}`;
+    if (plattform === "win32" && ordner.length > MAX_PFAD_WINDOWS) {
+        return { art: "zu-lang", laenge: ordner.length, hoechstens: MAX_PFAD_WINDOWS };
+    }
+    return { art: "ort", ordner, aufnahmen };
+}
+/** 93 -> "1:33", 3725 -> "1:02:05". */
+export function dauerText(sekunden) {
+    const s = Math.floor(sekunden);
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const rest = String(s % 60).padStart(2, "0");
+    return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${rest}` : `${m}:${rest}`;
+}
+/** "0:26" -> 26, "1:02:05" -> 3725, "26" -> 26; alles andere null. */
+export function zeitAusText(text) {
+    const teile = text.trim().split(":");
+    if (teile.length > 3 || !teile.every((t) => /^\d+$/.test(t)))
+        return null;
+    const zahlen = teile.map(Number);
+    if (zahlen.slice(1).some((n) => n >= 60))
+        return null;
+    return zahlen.reduce((summe, n) => summe * 60 + n, 0);
+}
+/** 26 -> "0-26.png", 3725 -> "1-02-05.png" (Doppelpunkte duerfen nicht in Dateinamen). */
+export function bildName(sekunden) {
+    return `${dauerText(sekunden).replaceAll(":", "-")}.png`; // kein-anzeigetext: Dateiname
+}
+// Reihenfolge zaehlt: das erste Muster, das trifft, gewinnt. Das Protokoll enthaelt Fenstertitel -- es wird nie
+// zurueckgegeben oder angezeigt, nur nach diesen festen Mustern durchsucht.
+const GRUENDE = [
+    [/FFmpegUnavailableError|ffmpeg.*not found/i, "ffmpeg-fehlt"],
+    [/returned success without a non-empty output/, "pfad-zu-lang"],
+    [/PortAudio|No Default Input Device|sounddevice/, "kein-mikrofon"],
+    [/DesktopCaptureError|screen layout/, "bildschirm-gesperrt"],
+    [/did not become ready|did not start/, "startet-nicht"],
+];
+export function fehlerGrund(protokoll) {
+    return GRUENDE.find(([muster]) => muster.test(protokoll))?.[1] ?? "unbekannt";
+}
+/** Der Aufnehmer antwortet mit einer JSON-Zeile ganz am Ende; alles andere (auch ein Traceback) ist ein Fehlschlag. */
+export function liesWerkzeugAntwort(rueckgabe, stdout) {
+    if (rueckgabe !== 0)
+        return { ok: false };
+    const zeilen = stdout.split(/\r?\n/).filter((z) => z.trim() !== "");
+    const letzte = zeilen[zeilen.length - 1];
+    if (letzte === undefined)
+        return { ok: false };
+    try {
+        const daten = JSON.parse(letzte);
+        if (typeof daten !== "object" || daten === null || Array.isArray(daten))
+            return { ok: false };
+        return { ok: true, daten: daten };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** So alt darf das Lebenszeichen des Starters hoechstens sein, damit er als lebend gilt (er schreibt alle 2 s). */
+const LEBENSZEICHEN_SEK = 10;
+/** Lebt der Starter nachweislich -- meldet `startet`/`laeuft` UND sein Lebenszeichen ist hoechstens 10 s alt? (R-3) */
+export function starterLebt(s, jetzt) {
+    if (s === null || (s.zustand !== "startet" && s.zustand !== "laeuft"))
+        return false;
+    return s.zuletzt !== undefined && jetzt - s.zuletzt <= LEBENSZEICHEN_SEK;
+}
+/**
+ * Die Wahrheit ueber "laeuft" kommt vom Aufnehmer; Notiz und Starter erzaehlen nur dazu.
+ * `jetzt` in Epochensekunden. Ausnahme Uebergangsfenster (R-3): Der Aufnehmer meldet noch/schon keine Sitzung, der
+ * Starter lebt aber nachweislich (frisches Lebenszeichen) -- dann laeuft etwas, sonst waere "abgebrochen" falsch.
+ */
+export function aufnahmeZustand(f, jetzt) {
+    if (f.aktiveSitzungen === null)
+        return { art: "unbekannt" };
+    // Der Starter konnte den Aufnehmer nicht beenden: Solange er noch lebt (und es weiter versucht) oder der Aufnehmer
+    // eine Sitzung meldet, weiss niemand, ob aufgenommen wird. Ein laengst stiller Starter ohne aktive Sitzung blockiert
+    // dagegen nicht jeden weiteren Start im Projekt -- er zaehlt unten als abgebrochen (Endpruefung, Punkt 3).
+    const frisch = f.starter?.zuletzt !== undefined && jetzt - f.starter.zuletzt <= LEBENSZEICHEN_SEK;
+    if (f.starter?.grund === "nicht-beendet" && (frisch || f.aktiveSitzungen.length > 0))
+        return { art: "unbekannt" };
+    const n = f.notiz;
+    const ausNotiz = (sitzung, eigenerOrdner) => n !== null && ((sitzung !== null && n.sitzung === sitzung) || eigenerOrdner)
+        ? { art: "laeuft", sitzung, ordner: n.ordner, gestartet: n.gestartet, frist: n.frist, fremd: false }
+        : { art: "laeuft", sitzung, ordner: null, gestartet: null, frist: null, fremd: true };
+    if (f.aktiveSitzungen.length > 0) {
+        const eigene = n !== null && f.aktiveSitzungen.includes(n.sitzung) ? n.sitzung : null;
+        return ausNotiz(eigene ?? f.aktiveSitzungen[0], false);
+    }
+    const s = f.starter;
+    if (s === null)
+        return { art: "keine", letzte: null };
+    if (starterLebt(s, jetzt))
+        return ausNotiz(s.sitzung ?? null, f.starterImNotizOrdner);
+    if (s.zustand === "selbst-gestoppt" || s.zustand === "gestoppt")
+        return { art: "keine", letzte: s.zustand };
+    return { art: "keine", letzte: "abgebrochen" };
+}
+/**
+ * Das Python des Aufnehmers ist nicht zu finden (Ruling R-13). Ohne Notiz und ohne offenen Starter kann nichts laufen,
+ * was kimal3 gestartet hat -> wie "keine aktive Sitzung". Gibt es aber eine Notiz oder einen Starter in
+ * `startet`/`laeuft`, entscheidet allein sein Lebenszeichen: frisch -> laeuft, sonst weiss es niemand.
+ * Steht der Starter in einem ENDZUSTAND, ist die Aufnahme zu, auch mit Notiz (Ruling R-17): Er schreibt ihn erst, wenn
+ * sein Kind weg ist. Ausnahme `grund: nicht-beendet` mit frischem Lebenszeichen -- die faengt `aufnahmeZustand` als
+ * "weiss nicht" ab.
+ */
+export function zustandOhneAufnehmer(f, jetzt) {
+    const mitListe = { ...f, aktiveSitzungen: [] };
+    const offen = f.starter?.zustand === "startet" || f.starter?.zustand === "laeuft";
+    const zu = f.starter !== null && !offen;
+    if (zu || f.notiz === null && !offen)
+        return aufnahmeZustand(mitListe, jetzt);
+    return starterLebt(f.starter, jetzt) ? aufnahmeZustand(mitListe, jetzt) : { art: "unbekannt" };
+}
+export const AUFNEHMER_FASSUNG = "1.3.0";
+/** Die Fassung des Aufnehmers, wie `teile` sie meldet -- nur in der Form `1.3.0…`, alles andere ist keine Angabe (R-14, Punkt 5). */
+export const gueltigeFassung = (w) => (typeof w === "string" && /^\d+\.\d+\.\d+\S*$/.test(w) ? w : null);
+/**
+ * Die Antwort von `werkzeug.py teile` -> `Teile`. Ohne Antwort (kein Aufnehmer-Python) oder mit einer unlesbaren gilt
+ * alles ausser uv als fehlend: Einrichten holt es dann (wieder), statt einem stummen Aufnehmer zu glauben.
+ */
+export function teileAus(uv, antwort) {
+    if (antwort === null || !antwort.ok)
+        return { uv, aufnehmer: null, ffmpeg: false, modell: false };
+    const d = antwort.daten;
+    return { uv, aufnehmer: gueltigeFassung(d.aufnehmer), ffmpeg: d.ffmpeg === true, modell: d.modell === true };
+}
+export const AUFNEHMER_PAKET = `openadapt-capture[transcribe-fast]==${AUFNEHMER_FASSUNG}`; // kein-anzeigetext: Paketname
+/** `uv tool install …` -- `ersetzen`, sobald schon eine Umgebung des Aufnehmers liegt (andere Fassung, kaputt). */
+export function aufnehmerArgumente(ersetzen) {
+    // kein-anzeigetext: Befehlszeile
+    return ["tool", "install", "--python", "3.12", ...(ersetzen ? ["--force"] : []), AUFNEHMER_PAKET];
+}
+/**
+ * Wie uv auf den Rechner kommt: winget zuerst (Coach-Regel: Paketmanager), sonst der offizielle Installer pro Benutzer.
+ * Ohne die beiden Zustimmungsschalter haengt winget auf einem frischen Rechner an einer Frage (Spec US-2).
+ */
+export function uvEinrichtung(winget) {
+    // kein-anzeigetext: Befehlszeile
+    if (winget)
+        return { befehl: "winget", argumente: ["install", "--id", "astral-sh.uv", "-e", "--scope", "user", "--accept-source-agreements", "--accept-package-agreements"] };
+    // kein-anzeigetext: Befehlszeile
+    return { befehl: "powershell", argumente: ["-ExecutionPolicy", "ByPass", "-c", "irm https://astral.sh/uv/install.ps1 | iex"] };
+}
+/** Was beim Einrichten noch fehlt, in der Reihenfolge, in der es gebraucht wird. */
+export function einrichtPlan(t) {
+    const fehlt = [
+        [t.uv === null, "uv"],
+        [t.aufnehmer !== AUFNEHMER_FASSUNG, "aufnehmer"],
+        [!t.ffmpeg, "ffmpeg"],
+        [!t.modell, "modell"],
+    ];
+    return fehlt.filter(([f]) => f).map(([, schritt]) => schritt);
+}
+/** Wo uv unter Windows liegen kann, wenn es nicht im PATH steht (frisch installiert, Terminal noch alt). */
+export function uvKandidaten(env, home) {
+    const lokal = env.LOCALAPPDATA ?? win32.join(home, "AppData", "Local"); // kein-anzeigetext: Ordnerpfad
+    return [
+        // kein-anzeigetext: Ordnerpfad
+        win32.join(lokal, "Microsoft", "WinGet", "Packages", "astral-sh.uv_Microsoft.Winget.Source_8wekyb3d8bbwe", "uv.exe"),
+        win32.join(home, ".local", "bin", "uv.exe"),
+        win32.join(home, ".cargo", "bin", "uv.exe"),
+    ];
+}
+/**
+ * Welcher Ordner in `material/aufnahmen/` ist die juengste Aufnahme? Nur Namen von `ordnerName` (mit Endung `-2` …)
+ * zaehlen; `-10` kommt nach `-9` (als Text stuende es davor). `istAufnahme` sortiert Ordner aus, in denen keine
+ * Aufnahme liegt (ein gescheiterter Start hinterlaesst nur Protokoll und Starter-Bericht) -- sonst verdeckte er die
+ * letzte echte fuer auswerten und stopp (Endpruefung, Punkt 4). `null`, wenn keiner passt.
+ */
+export function juengsteAufnahme(namen, istAufnahme) {
+    const schluessel = (n) => {
+        const m = /^(\d{4}-\d{2}-\d{2}-\d{4})(?:-(\d+))?$/.exec(n);
+        return m ? { name: n, basis: m[1], nr: m[2] === undefined ? 1 : Number(m[2]) } : null;
+    };
+    const passend = namen.map(schluessel).filter((k) => k !== null);
+    passend.sort((a, b) => (a.basis === b.basis ? b.nr - a.nr : a.basis < b.basis ? 1 : -1));
+    return passend.find((k) => istAufnahme(k.name))?.name ?? null;
+}
+/** `zahlenDa`: Dauer, Klicks, Tasten und Ton kamen in der erwarteten Form. Ohne sie ist auch "gestoppt" nicht bestaetigt. */
+export function stoppAusgang(ergebnis, zahlenDa) {
+    if (ergebnis === "keine")
+        return { satz: "keine", code: 0, notizWeg: true };
+    if ((ergebnis === "gestoppt" || ergebnis === "selbst-gestoppt") && zahlenDa)
+        return { satz: ergebnis, code: 0, notizWeg: true };
+    if (ergebnis === "nicht-sauber" || ergebnis === "abgebrochen")
+        return { satz: ergebnis, code: 1, notizWeg: true };
+    if (ergebnis === "wird-abgeschlossen")
+        return { satz: ergebnis, code: 1, notizWeg: false };
+    return { satz: "unklar", code: 1, notizWeg: false };
+}

package/dist/zeigen-umgebung.js

@@ -0,0 +1,190 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { juengsteAufnahme, liesWerkzeugAntwort, starterLebt, uvKandidaten } from "./zeigen-rechnung.js";
+/**
+ * Die Umgebung hinter `kimal3 zeigen`: wo der Aufnehmer und sein Python liegen, wie das Werkzeug gerufen wird, und
+ * die Notiz `~/.kimal3/zeigen.json` (welcher Ordner zu welcher Sitzung gehoert). Entscheidungen trifft
+ * `zeigen-rechnung.ts`; hier wird nur gesucht, gestartet, gelesen und geschrieben.
+ * 🔴 Ausgaben fremder Programme werden nie weitergereicht: vom Werkzeug zaehlt nur die eine JSON-Zeile (gelesen von
+ * `liesWerkzeugAntwort`), stderr wird verworfen.
+ */
+/** `cli/dist/zeigen-umgebung.js` -> `cli/zeigen/werkzeug.py` (im Paket unter `files`, Task 7). */
+const WERKZEUG = fileURLToPath(new URL("../zeigen/werkzeug.py", import.meta.url)); // kein-anzeigetext: Paketpfad
+function laeuft(befehl, argumente) {
+    try {
+        const r = spawnSync(befehl, argumente, { encoding: "utf8", windowsHide: true, timeout: 20_000 });
+        return r.status === 0 ? r.stdout : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Das erste uv, das antwortet: Suchpfad, dann die bekannten Orte (frisch installiert, Terminal noch alt). */
+export function findeUv() {
+    for (const uv of ["uv", ...uvKandidaten(process.env, homedir())]) {
+        const version = laeuft(uv, ["--version"]);
+        if (version !== null)
+            return { uv, version };
+    }
+    return null;
+}
+/** "uv 0.12.10 (…)" -> "0.12.10"; `null`, wenn es kein uv gibt. */
+export function uvFassung() {
+    return /^uv (\d+\.\d+\.\d+\S*)/.exec(findeUv()?.version ?? "")?.[1] ?? null;
+}
+/** Python und pythonw des Aufnehmers: `<uv tool dir>/openadapt-capture/Scripts/`, sonst `%APPDATA%\uv\tools\…`. */
+export function aufnehmerPython() {
+    const uv = findeUv();
+    const toolDir = uv === null ? null : laeuft(uv.uv, ["tool", "dir"])?.trim() || null;
+    const appdata = process.env.APPDATA ?? win32.join(homedir(), "AppData", "Roaming"); // kein-anzeigetext: Ordnerpfad
+    // Antwortet uv, gilt sein Ordner allein (so greift `UV_TOOL_DIR`); der Standardort nur, wenn uv selbst fehlt (Task 5:
+    // sonst faende ein nachgestellter frischer Rechner den echten Aufnehmer unter %APPDATA% doch).
+    const orte = toolDir !== null ? [toolDir] : [win32.join(appdata, "uv", "tools")]; // kein-anzeigetext: Ordnerpfad
+    for (const ort of orte) {
+        const scripts = win32.join(ort, "openadapt-capture", "Scripts"); // kein-anzeigetext: Ordnerpfad
+        const python = win32.join(scripts, "python.exe");
+        const pythonw = win32.join(scripts, "pythonw.exe");
+        if (existsSync(python) && existsSync(pythonw))
+            return { python, pythonw };
+    }
+    return null;
+}
+/** Wohin uv die Programme seiner Werkzeuge legt (`uv tool dir --bin`, beachtet `UV_TOOL_BIN_DIR`). */
+export function uvBinOrdner(uv) {
+    return laeuft(uv, ["tool", "dir", "--bin"])?.trim() || null;
+}
+/**
+ * Ein fremdes Programm (winget, uv, capture) ohne Fenster und ohne dass eine Zeile davon irgendwo erscheint -- nicht
+ * einmal eingesammelt. `true` nur bei Rueckgabewert 0; ob die Sache danach WIRKLICH da ist, prueft der Aufrufer neu.
+ * Arbeitsordner ist der Temp-Ordner: nie das Projekt (eine `uv.toml`/`.env` dort gehoert nicht zum Einrichten).
+ */
+export function stillAusfuehren(befehl, argumente, zeitgrenze) {
+    try {
+        const r = spawnSync(befehl, argumente, { stdio: "ignore", windowsHide: true, cwd: tmpdir(), env: UMGEBUNG(), timeout: zeitgrenze });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Umgebung jedes Werkzeug-Aufrufs, auch des Starters (R-14, Punkt 6); den Rest setzt das Werkzeug selbst. */
+const UMGEBUNG = () => ({ ...process.env, PYTHONUTF8: "1", PYTHONUNBUFFERED: "1" });
+/** Lesende Aufrufe (`teile`, `zustand`) duerfen nicht haengen: nach 20 s gilt die Antwort als "weiss nicht" (R-14, Punkt 7). */
+export const LESEN_MS = 20_000;
+/**
+ * `stoppen` antwortet nach spaetestens 495 s selbst (werkzeug.py, STOPP_SEK + WARTEN_SEK). Diese Grenze ist nur das
+ * Netz, falls es haengt: Claude Code bricht einen Werkzeugaufruf nach 10 Minuten ab, und dann kaeme gar kein Satz.
+ */
+export const STOPPEN_MS = 540_000;
+/**
+ * Ein Unterbefehl des Werkzeugs, synchron. Arbeitsordner = Aufnahmeordner (nie das Projekt: `.env`-Falle).
+ * `zeitgrenze` in ms oder `null` (stoppen und auswerten duerfen dauern). Abgebrochen = `status` null = `{ ok: false }`.
+ */
+export function rufeWerkzeug(p, argumente, arbeitsordner, zeitgrenze) {
+    try {
+        // stderr wird gar nicht erst eingesammelt: Er wird nie gelesen, und ein Fortschrittsbalken (Modell laden, 1,6 GB)
+        // koennte sonst `maxBuffer` sprengen -- dann bricht Node den Aufruf ab (Task 5).
+        const r = spawnSync(p.python, [WERKZEUG, ...argumente], {
+            encoding: "utf8", windowsHide: true, cwd: arbeitsordner ?? tmpdir(), maxBuffer: 1024 * 1024, env: UMGEBUNG(),
+            stdio: ["ignore", "pipe", "ignore"],
+            ...(zeitgrenze === null ? {} : { timeout: zeitgrenze }),
+        });
+        return liesWerkzeugAntwort(r.status, r.stdout ?? "");
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** Startet den Starter abgehaengt mit pythonw (kein Fenster, keine Ausgabe). `false`, wenn schon das Starten scheitert. */
+export function starteStarter(p, konfig, ordner) {
+    try {
+        const kind = spawn(p.pythonw, [WERKZEUG, "starten", konfig], { cwd: ordner, detached: true, stdio: "ignore", windowsHide: true, env: UMGEBUNG() });
+        kind.on("error", () => { });
+        kind.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Die Notiz ─────────────────────────────────────────────────────────────────────────────────────────────────────
+const ORDNER = join(homedir(), ".kimal3");
+const NOTIZ = join(ORDNER, "zeigen.json"); // kein-anzeigetext: Dateiname
+export function leseNotiz() {
+    try {
+        const n = JSON.parse(readFileSync(NOTIZ, "utf8"));
+        const zahl = (w) => typeof w === "number" && Number.isFinite(w);
+        if (typeof n.sitzung !== "string" || typeof n.ordner !== "string" || !zahl(n.gestartet) || !zahl(n.frist))
+            return null;
+        return { sitzung: n.sitzung, ordner: n.ordner, gestartet: n.gestartet, frist: n.frist };
+    }
+    catch {
+        return null;
+    }
+}
+/** `false`, wenn die Notiz nicht geschrieben werden konnte -- die Aufnahme laeuft trotzdem (status findet sie ueber den Ordner). */
+export function schreibeNotiz(n) {
+    try {
+        mkdirSync(ORDNER, { recursive: true, mode: 0o700 }); // wie wache-schalter.ts: wer den Ordner anlegt, legt die Rechte fest
+        writeFileSync(NOTIZ, JSON.stringify(n, null, 2), "utf8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function loescheNotiz() {
+    try {
+        rmSync(NOTIZ, { force: true });
+    }
+    catch {
+        /* bleibt liegen -- status vergleicht sie ohnehin mit den Sitzungen des Aufnehmers */
+    }
+}
+// ── Ordner und Bericht des Starters ───────────────────────────────────────────────────────────────────────────────
+/**
+ * Der juengste Aufnahmeordner unter `aufnahmen`, oder `null`. Zaehlt nur, wo eine Aufnahme liegt (`roh/recording.db`)
+ * oder ein Starter noch lebt (er startet gerade, die Datei kommt erst noch). `roh/` gehoert allein dem Aufnehmer
+ * (gemeinsam.py, ROH: sein Siegel bricht an jeder Datei, die wir dort schreiben).
+ */
+export function juengsterOrdner(aufnahmen) {
+    try {
+        const namen = readdirSync(aufnahmen, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+        const istAufnahme = (name) => existsSync(join(aufnahmen, name, "roh", "recording.db")) || // kein-anzeigetext: Dateiname
+            starterLebt(starterFakt(leseStarter(join(aufnahmen, name))), Date.now() / 1000);
+        const name = juengsteAufnahme(namen, istAufnahme);
+        return name === null ? null : join(aufnahmen, name);
+    }
+    catch {
+        return null;
+    }
+}
+/** Der Bericht des Starters (`starter.json`), roh; `null`, wenn er fehlt oder kaputt ist. */
+export function leseStarter(ordner) {
+    try {
+        const d = JSON.parse(readFileSync(join(ordner, "starter.json"), "utf8")); // kein-anzeigetext: Dateiname
+        return d && typeof d === "object" && !Array.isArray(d) ? d : null;
+    }
+    catch {
+        return null;
+    }
+}
+const STARTER_ZUSTAENDE = ["startet", "laeuft", "gestoppt", "selbst-gestoppt", "abgebrochen", "fehlgeschlagen"];
+/** Bericht des Starters -> `Fakten.starter`; alles, was nicht die erwartete Form hat, faellt weg. */
+export function starterFakt(roh) {
+    if (!roh || typeof roh !== "object")
+        return null;
+    const r = roh;
+    const zustand = STARTER_ZUSTAENDE.find((z) => z === r.zustand);
+    if (zustand === undefined)
+        return null;
+    return {
+        zustand,
+        ...(typeof r.sitzung === "string" ? { sitzung: r.sitzung } : {}),
+        ...(typeof r.zuletzt === "number" && Number.isFinite(r.zuletzt) ? { zuletzt: r.zuletzt } : {}),
+        ...(typeof r.grund === "string" ? { grund: r.grund } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kimal3",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Trag deine KI-Projekte dort ein, wo sie entstehen: im Terminal. · Log your AI projects where they happen: in the terminal.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "skill",
     "claude-plugins",
     "coach",
+    "zeigen",
     "README.md"
   ],
   "engines": {

package/skill/SKILL.md

@@ -13,7 +13,7 @@ description: Projekte ins kimal3-Erfolgsprofil eintragen oder auflisten, Firmend
 Sobald der Mensch sagt, ein Projekt sei fertig, oder ausdrücklich bittet, es einzutragen.
 **Oder** wenn er seinen KI-Arbeitsplatz anlegen will — dann s. „Den Arbeitsplatz anlegen".
 
-## Die acht Slash-Befehle, die der Mensch hat
+## Die neun Slash-Befehle, die der Mensch hat
 
 `kimal3 skill install` legt sie global ab (`~/.claude/commands/`) — er kann sie also in
 **jedem** Ordner tippen. Sie sind der Weg, den er selbst auslöst; dieses Skill ist der Weg,
@@ -29,6 +29,7 @@ den du erkennst.
 | `/k3liste` | Seine eingetragenen Projekte zeigen |
 | `/k3analyse` | Firmendaten holen und seine Frage dazu beantworten |
 | `/k3kontext` | Die offenen Fragen über seine Firma im Gespräch beantworten |
+| `/k3zeigen` | Eine Aufgabe vormachen statt beschreiben — nimmt mit `kimal3 zeigen …` auf, wertet auf dem Rechner aus und schreibt den Plan; gelesen wird erst nach seinem Ja |
 
 🔴 **Nenne einen dieser Befehle nur, wenn du weißt, dass er ihn hat.** Sie kommen mit
 `kimal3 skill install`; wer das nie ausgeführt hat, sieht beim Tippen nichts, und ein Rat ins
@@ -37,7 +38,7 @@ einen Befehl zu zeigen.
 
 ⚠️ **`/k3start`, `/k3feierabend` und `/k3kurs` kamen bis 0.2.4 NUR im Kursordner mit** — Pro-
 Kunden ohne Mini-Kurs hatten sie nie, und aktualisieren ließen sie sich gar nicht. Seit 0.2.5
-liefert das Programm alle acht aus. *Triffst du jemanden mit einer älteren Fassung, ist ein
+liefert das Programm sie alle aus. *Triffst du jemanden mit einer älteren Fassung, ist ein
 fehlender Befehl dort kein Fehler, sondern der alte Stand.*
 
 ## 🔴 Mehrere Firmen: DU WÄHLST NICHT

package/skill/commands/k3.md

@@ -83,17 +83,18 @@ Stell die Liste in zwei Gruppen dar:
 | `/k3projekt <was du gebaut hast>` | Ein fertiges Projekt ins Erfolgsprofil eintragen |
 | `/k3liste` | Deine eingetragenen Projekte zeigen |
 | `/k3analyse <deine Frage>` | Firmendaten holen und deine Frage dazu beantworten |
+| `/k3zeigen` | Eine Aufgabe vormachen statt beschreiben — ich nehme auf und mache daraus einen Plan |
 
 Sag dazu: Die Slash-Befehle sind der **sichere** Weg — du musst dir keinen Satz merken. Ohne
 sie geht es auch: „das Projekt ist fertig" genügt, dann greife ich über den Skill.
 
-## 6. Der neunte Eintrag im Menü: `/kimal3` ist KEIN Befehl
+## 6. Der zehnte Eintrag im Menü: `/kimal3` ist KEIN Befehl
 
 In derselben `/`-Liste steht auch **`/kimal3`**. Erklär den Unterschied **ungefragt** — das Menü
 wirft zwei verschiedene Sorten in eine Liste, und genau daran hat sich der erste Mensch gestoßen,
 der die Familie gesehen hat (Dennis, 2026-08-19):
 
-- Die acht **`/k3…`** sind **Slash-Befehle** (Dateien in `~/.claude/commands/`) — **der Mensch**
+- Die neun **`/k3…`** sind **Slash-Befehle** (Dateien in `~/.claude/commands/`) — **der Mensch**
   tippt sie bewusst.
 - **`/kimal3`** ist der **Skill** (`~/.claude/skills/kimal3/SKILL.md`) — meine
   Bedienungsanleitung. Sie ist der Grund, warum „das Projekt ist fertig" genügt: Ich schlage sie
@@ -101,5 +102,5 @@ der die Familie gesehen hat (Dennis, 2026-08-19):
   sie mehrere Dinge auf einmal und liest sich nicht wie ein Menüpunkt.
 
 Sag auch, was `/kimal3` **nicht** ist: **nicht die Installation.** Die ist `kimal3 skill install`
-im Terminal — der eine Befehl, der beides ablegt, den Skill **und** die acht `/k3…`. Was im Menü
+im Terminal — der eine Befehl, der beides ablegt, den Skill **und** die neun `/k3…`. Was im Menü
 steht, ist sein Ergebnis.

package/skill/commands/k3kurs.md

@@ -1,41 +1,41 @@
----
-description: Zurück in den Mini-Kurs — da weiter, wo du aufgehört hast
----
-
-<!-- kimal3:erzeugt — diese Datei wird von `kimal3 skill install` gepflegt und bei
-     jedem Update ueberschrieben. Eigene Aenderungen gehen dabei verloren; wer sie
-     behalten will, kopiert die Datei unter einem anderen Namen. -->
-# Kurs
-
-> Zurück in den Mini-Kurs: „Wo war ich nochmal?" — macht da weiter, wo du aufgehört hast.
-> Den Stand holt `kimal3 kurs` frisch von kimal3 — dieselben Haken, die der Mensch im Browser unter
-> https://app.kimal3.de/kurs sieht.
-
-Führe die Schritte der Reihe nach aus. Bleib im Coaching-Ton: Deutsch, freundlich, ein Schritt
-nach dem anderen, das Warum vor dem Wie, null Vorwissen vorausgesetzt.
-
-## 1. Den Stand holen
-- Führ `kimal3 kurs` aus (unter Windows so, wie es `SKILL.md` beschreibt).
-- Rückgabewert **2**: Der Mensch ist nicht angemeldet. Zeig ihm `kimal3 login`, lass ihn selbst im Browser bestätigen
-  und nenn **keinen** Kursstand.
-- Rückgabewert **3**: Der Stand ist gerade nicht abrufbar. Sag es in einem Satz und **erzähl den Kurs nicht aus dem
-  Gedächtnis**.
-- Kennt das Programm den Befehl nicht, ist es zu alt: Nenn `npm install -g kimal3@latest`, danach `kimal3 skill install`.
-
-## 2. Stand in einem Satz sagen
-- Sag in **einem** Satz, wo ihr im Kurs steht — aus der Ausgabe (Zeile `Kurs:`), nichts dazuerfinden. Kein Vortrag.
-
-## 3. Als Nächstes führen
-- Die Zeile `Als Nächstes:` nennt den nächsten Schritt. Führ **einen** Schritt nach dem anderen: zeigen, machen lassen,
-  verstehen. Nie die ganze Liste auf einmal.
-- Steht dahinter **„(du hakst ab)"** und hat der Mensch den Schritt offensichtlich schon getan (zum Beispiel „Claude ganz
-  beendet und neu geöffnet" — er sitzt ja gerade in Claude), führ ihn nicht noch einmal: Frag kurz nach und bitte ihn,
-  den Schritt unter https://app.kimal3.de/kurs abzuhaken.
-- Steht dahinter **„(setzt Claude)"** und ist er offen, lass die Einrichtung noch einmal laufen — über die Anleitung
-  `https://app.kimal3.de/einrichten` (lade sie wie der Kurs-Satz und folge ihr), **nicht** mit einem frei aufgerufenen
-  `kimal3 einrichten`. Bleibt der Schritt danach offen, nenn den Grund aus der Ausgabe von `einrichten` und schlag
-  keinen dritten Lauf vor.
-
-## 4. Abgeschlossen
-- Steht in der Ausgabe `Kurs: abgeschlossen`, gratuliere kurz und frag mit einem Vorschlag, woran er hier arbeiten
-  möchte. Kein Kurs-Gerede mehr.
+---
+description: Zurück in den Mini-Kurs — da weiter, wo du aufgehört hast
+---
+
+<!-- kimal3:erzeugt — diese Datei wird von `kimal3 skill install` gepflegt und bei
+     jedem Update ueberschrieben. Eigene Aenderungen gehen dabei verloren; wer sie
+     behalten will, kopiert die Datei unter einem anderen Namen. -->
+# Kurs
+
+> Zurück in den Mini-Kurs: „Wo war ich nochmal?" — macht da weiter, wo du aufgehört hast.
+> Den Stand holt `kimal3 kurs` frisch von kimal3 — dieselben Haken, die der Mensch im Browser unter
+> https://app.kimal3.de/kurs sieht.
+
+Führe die Schritte der Reihe nach aus. Bleib im Coaching-Ton: Deutsch, freundlich, ein Schritt
+nach dem anderen, das Warum vor dem Wie, null Vorwissen vorausgesetzt.
+
+## 1. Den Stand holen
+- Führ `kimal3 kurs` aus (unter Windows so, wie es `SKILL.md` beschreibt).
+- Rückgabewert **2**: Der Mensch ist nicht angemeldet. Zeig ihm `kimal3 login`, lass ihn selbst im Browser bestätigen
+  und nenn **keinen** Kursstand.
+- Rückgabewert **3**: Der Stand ist gerade nicht abrufbar. Sag es in einem Satz und **erzähl den Kurs nicht aus dem
+  Gedächtnis**.
+- Kennt das Programm den Befehl nicht, ist es zu alt: Nenn `npm install -g kimal3@latest`, danach `kimal3 skill install`.
+
+## 2. Stand in einem Satz sagen
+- Sag in **einem** Satz, wo ihr im Kurs steht — aus der Ausgabe (Zeile `Kurs:`), nichts dazuerfinden. Kein Vortrag.
+
+## 3. Als Nächstes führen
+- Die Zeile `Als Nächstes:` nennt den nächsten Schritt. Führ **einen** Schritt nach dem anderen: zeigen, machen lassen,
+  verstehen. Nie die ganze Liste auf einmal.
+- Steht dahinter **„(du hakst ab)"** und hat der Mensch den Schritt offensichtlich schon getan (zum Beispiel „Claude ganz
+  beendet und neu geöffnet" — er sitzt ja gerade in Claude), führ ihn nicht noch einmal: Frag kurz nach und bitte ihn,
+  den Schritt unter https://app.kimal3.de/kurs abzuhaken.
+- Steht dahinter **„(setzt Claude)"** und ist er offen, lass die Einrichtung noch einmal laufen — über die Anleitung
+  `https://app.kimal3.de/einrichten` (lade sie wie der Kurs-Satz und folge ihr), **nicht** mit einem frei aufgerufenen
+  `kimal3 einrichten`. Bleibt der Schritt danach offen, nenn den Grund aus der Ausgabe von `einrichten` und schlag
+  keinen dritten Lauf vor.
+
+## 4. Abgeschlossen
+- Steht in der Ausgabe `Kurs: abgeschlossen`, gratuliere kurz und frag mit einem Vorschlag, woran er hier arbeiten
+  möchte. Kein Kurs-Gerede mehr.

package/skill/commands/k3start.md

@@ -24,7 +24,7 @@ nicht relevant, sag das kurz und überspring ihn — kein Leerlauf.
 - Gibt es ein Status-Doc (`WEITER-HIER.md` oder `ROADMAP.md`) — eine kleine Datei, in der der
   letzte Stand und der nächste Schritt festgehalten sind? Dann lies es.
 - **Wo der Statuszettel liegt und wie er heißt.** Die Projektregel gilt **nur innerhalb eines Arbeitsplatzes**: Liegt ein Ordner `projekte/` oder `projects/` direkt in einem Ordner `werkbank-…` oder `workbench-…` (beide Schreibweisen kommen vor, auch gemischt) und steht die Sitzung in oder unter einem Ordner darin, ist dieser **Projektordner** der Ort. Name dort: unter `projekte/` `WEITER-HIER.md`, unter `projects/` `NEXT-STEPS.md`. **Überall sonst** (Starter-Paket, eigene Repos, auch ein Ordner `~/projects/mein-repo`) bleibt es wie bisher: Der Zettel liegt im Startordner, liegt einer da, nimm ihn; muss einer neu entstehen, heißt er `WEITER-HIER.md` — oder `NEXT-STEPS.md`, wenn der Ordner englisch angelegt wurde. Liegen beide da, frag, welcher gilt, und schreib in keinen, bevor die Antwort da ist. **Welcher gilt (im Arbeitsplatz):** Hat das Projekt einen, gilt der des Projekts. Sonst gilt ein vorhandener Werkbank-Zettel (`werkbank-…/WEITER-HIER.md` oder `workbench-…/NEXT-STEPS.md` aus der alten Vorlage) — den liest und pflegst du weiter. Gibt es keinen von beiden, entsteht er **im Projekt**. **Leg nie einen neuen Zettel in der Werkbank an.**
-- **Stehst du in der Werkbank selbst (`werkbank-…` oder `workbench-…`), nicht in einem Projekt?** Steht in ihrer `CLAUDE.md` der Abschnitt „Erste Sitzung“ (englisch „First session“), folge **ihm** — er hat Vorrang vor allem Folgenden. Steht er nicht (mehr) da, zeig die Projekte in `projekte/` bzw. `projects/` (ohne `beispiel-rechnungen-erfassen` und `example-capture-invoices`) mit je der **ersten Stand-Zeile** ihres Zettels, oder „noch kein Zettel“, wenn keiner da ist; ein vorhandener Werkbank-Zettel (`WEITER-HIER.md` oder `NEXT-STEPS.md`) steht darüber. Empfiehl daraus **eines** und stell **eine** Frage dazu.
+- **Stehst du in der Werkbank selbst (`werkbank-…` oder `workbench-…`), nicht in einem Projekt?** Steht in ihrer `CLAUDE.md` der Abschnitt „Erste Sitzung“ (englisch „First session“), folge **ihm** — er hat Vorrang vor allem Folgenden. Steht er nicht (mehr) da, zeig die Projekte in `projekte/` bzw. `projects/` (ohne `beispiel-rechnungen-erfassen` und `example-capture-invoices`) mit je der **ersten Stand-Zeile** ihres Zettels, oder „noch kein Zettel“, wenn keiner da ist; ein vorhandener Werkbank-Zettel (`WEITER-HIER.md` oder `NEXT-STEPS.md`) steht darüber. Empfiehl daraus **eines** und stell **eine** Frage dazu. Wählt der Mensch ein Projekt aus der Liste oder nennt eine neue Aufgabe (dann legst du erst Ordner und Statuszettel im Projekt an, nie in der Werkbank), bring die Sitzung in den Projektordner: mit `change_directory` (steht es nur als Name in deiner Werkzeugliste, lade es über die Werkzeugsuche) — und sag vorher: „Gleich fragt dich die Claude-App, ob ich den Ordner wechseln darf, und danach, ob du ihm vertraust — beides ist richtig so, klick jeweils auf Erlauben. Landest du danach in einem leeren Gespräch, tipp dort `/k3start`; dieses Gespräch findest du links in der Liste wieder.“ Ohne das Werkzeug oder wenn der Mensch ablehnt: nenne den genauen Projektordner (nicht die Werkbank darüber) — in der App „Ordner wählen“ und diesen Ordner nehmen, im Terminal `/exit`, `cd '‹Pfad›'`, `claude` — und dann `/k3start`. Bei einem neuen Projekt lies vorher `projekte/CLAUDE.md` (englisch `projects/CLAUDE.md`): ab jetzt gilt sie.
 - Kein Status-Doc? **Sieh erst nach, ob ein `.git`-Ordner im Zettel-Ort liegt** (im Arbeitsplatz der Projektordner, sonst der Startordner). Wenn ja, führt dieses
   Projekt eine Versionsgeschichte, und `git log --oneline -10` plus `git status` zeigen dir den
   letzten Stand.