kimal3 0.4.0 → 0.6.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,29 +1,30 @@
-{
-  "name": "kimal3",
-  "version": "0.4.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": {
-    "kimal3": "dist/kimal3.js"
-  },
-  "files": [
-    "dist",
-    "skill",
-    "claude-plugins",
-    "coach",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "kimal3",
-    "cli"
-  ],
-  "homepage": "https://app.kimal3.de/pro",
-  "license": "SEE LICENSE IN README.md"
-}
+{
+  "name": "kimal3",
+  "version": "0.6.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": {
+    "kimal3": "dist/kimal3.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "claude-plugins",
+    "coach",
+    "zeigen",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "kimal3",
+    "cli"
+  ],
+  "homepage": "https://app.kimal3.de/pro",
+  "license": "SEE LICENSE IN README.md"
+}

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 zehn 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,
@@ -26,9 +26,11 @@ den du erkennst.
 | `/k3feierabend` | Sitzung sauber beenden: Stand sichern, aufräumen, zusammenfassen |
 | `/k3kurs` | Zurück in den Mini-Kurs — holt den Stand mit `kimal3 kurs` und macht da weiter, wo er aufgehört hat |
 | `/k3projekt` | Ein fertiges Projekt ins Erfolgsprofil eintragen |
+| `/k3plan` | Die Specs eines Projekts gegen den Code prüfen und das Ergebnis mit `kimal3 plan` und `kimal3 plan hoch` auf die Projektseite laden |
 | `/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 +39,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

@@ -81,19 +81,21 @@ Stell die Liste in zwei Gruppen dar:
 | `/k3kurs` | Zurück in den Mini-Kurs — da weiter, wo du aufgehört hast |
 | `/k3kontext` | Durch die offenen Fragen über deine Firma führen |
 | `/k3projekt <was du gebaut hast>` | Ein fertiges Projekt ins Erfolgsprofil eintragen |
+| `/k3plan` | Die Specs gegen den Code prüfen und die Planung in die App hochladen |
 | `/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 elfte 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 zehn **`/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 +103,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 zehn `/k3…`. Was im Menü
 steht, ist sein Ergebnis.