kimal3 0.1.4 → 0.1.6

package/dist/gesehen.js

@@ -0,0 +1,85 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Welche Nachricht an welchem Tag schon im Terminal stand.
+ *
+ * 🔑 WARUM EINE EIGENE DATEI UND NICHT IN anmeldung.json: `kimal3 logout`
+ * loescht die Anmeldedatei. Laege der Merkzettel darin, kaeme nach jedem
+ * Abmelden jede Nachricht von vorn -- und ausgerechnet der Mensch, der sich
+ * gerade neu anmeldet, bekaeme die Wand.
+ *
+ * 🔴 BEIDE FUNKTIONEN WERFEN NIE. Ein kaputter oder schreibgeschuetzter
+ * Merkzettel darf keinen Befehl scheitern lassen (Spec US-8). Schlimmstenfalls
+ * sieht der Kunde denselben Hinweis zweimal -- das ist kein Schaden, ein
+ * abgebrochener `projekt neu` schon.
+ */
+const ORDNER = join(homedir(), ".kimal3");
+const DATEI = join(ORDNER, "gesehen.json");
+export function leseGesehen() {
+    try {
+        const roh = JSON.parse(readFileSync(DATEI, "utf8"));
+        if (!roh || typeof roh !== "object" || Array.isArray(roh))
+            return {};
+        const raus = {};
+        for (const [k, v] of Object.entries(roh)) {
+            // Nur Zeichenketten uebernehmen. Wer die Datei von Hand bearbeitet hat,
+            // soll damit hoechstens seinen eigenen Merkzettel verlieren.
+            if (typeof v === "string")
+                raus[k] = v;
+        }
+        return raus;
+    }
+    catch {
+        return {};
+    }
+}
+export function merkeGesehen(id, tag) {
+    try {
+        const alles = leseGesehen();
+        /*
+          🔑 ERST LOESCHEN, DANN SETZEN -- damit der Eintrag ans ENDE rutscht.
+          Ohne die erste Zeile behaelt ein schon vorhandener Schluessel seinen
+          alten Platz, und `slice(-20)` unten wirft dann ausgerechnet den weg, den
+          wir gerade geschrieben haben (Befund der vierten Review-Runde: der
+          Kommentar unten versprach genau das Gegenteil).
+    
+          Die Folge waere klein -- derselbe Hinweis erschiene einmal zu viel --,
+          aber sie steht im Widerspruch zu einer Zusage im Code. Und eine Zusage
+          im Code ist das, was der naechste Leser glaubt, statt nachzurechnen.
+        */
+        delete alles[id];
+        alles[id] = tag;
+        /*
+          ⚠️ Nur die letzten 20 behalten. Ohne diese Zeile waechst die Datei mit
+          jeder je gezeigten Nachricht -- langsam, aber ohne Ende, und niemand
+          raeumt sie je auf.
+    
+          🔑 Warum das gefahrlos ist: `Object.entries` gibt Zeichenketten-Schluessel
+          in Einfuegereihenfolge zurueck, und der gerade gesetzte Eintrag ist immer
+          dabei -- entweder als letzter (neu) oder an seinem alten Platz
+          (aktualisiert). Was hinten abfaellt, ist die aelteste Nachricht; die
+          schlimmste Folge waere, dass sie noch einmal erscheint.
+        */
+        const paare = Object.entries(alles).slice(-20);
+        /*
+          ⚠️ `mode: 0o700` wie in anmeldung.ts -- und das ist KEINE Kosmetik
+          (Befund der ersten Review-Runde): `mkdirSync` mit `recursive: true`
+          aendert die Rechte eines Ordners, den es schon gibt, NICHT MEHR. Wer
+          diesen Ordner also zuerst anlegt, legt seine Rechte fuer immer fest.
+    
+          Der Fall ist echt: Ein Mensch mit altem Skill, aber ohne Anmeldung,
+          tippt `kimal3` -- der Skill-Hinweis feuert, dieser Merkzettel entsteht,
+          und `~/.kimal3` bekaeme die Vorgabe-Rechte (auf einem gemeinsam
+          genutzten Rechner meist 0755). Ein spaeteres `kimal3 login` koennte sie
+          nicht mehr enger ziehen. Der Ausweis selbst bliebe zwar 0600 -- aber die
+          Haertung des Ordners waere still verloren, und "still" ist hier das
+          Schlimme.
+        */
+        mkdirSync(ORDNER, { recursive: true, mode: 0o700 });
+        writeFileSync(DATEI, JSON.stringify(Object.fromEntries(paare), null, 2), "utf8");
+    }
+    catch {
+        /* Merkzettel nicht schreibbar -- der Befehl laeuft trotzdem durch. */
+    }
+}

package/dist/kimal3.js

@@ -11,16 +11,21 @@
  * `kimal3 login`, bei 4 hilft genau das nicht. Wer beide auf dieselbe Zahl
  * legt, laesst Claude den falschen Rat geben.
  */
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { BASIS_URL, leseAnmeldung } from "./anmeldung.js";
-import { NichtAngemeldet } from "./api.js";
+import { gemerkterHinweis, NichtAngemeldet } from "./api.js";
+import { leseGesehen, merkeGesehen } from "./gesehen.js";
+import { formatiere, heuteAus, skillMeldung, skillZustand, sollZeigen, } from "./nachricht.js";
+import { eigeneVersion } from "./version.js";
 import { hilfeText } from "./befehle-katalog.js";
+import { arbeitsplatzNeu } from "./befehle/arbeitsplatz.js";
+import { werkbankNeu } from "./befehle/werkbank.js";
 import { firmaDaten } from "./befehle/firma-daten.js";
 import { login } from "./befehle/login.js";
 import { logout } from "./befehle/logout.js";
 import { projektListe } from "./befehle/projekt-liste.js";
 import { projektNeu } from "./befehle/projekt-neu.js";
-import { skillInstall } from "./befehle/skill-install.js";
+import { skillDatei, skillInstall } from "./befehle/skill-install.js";
 // 📌 Kein handgeschriebener Block mehr (2026-08-18): Die Liste wohnt in
 // `befehle-katalog.ts` und wird von dort AUCH im Pro-Bereich der App angezeigt.
 // Zwei Listen ueber dieselben Befehle driften — die eine bekaeme den naechsten
@@ -56,20 +61,167 @@ const HILFE = hilfeText();
  * eine Ebene unter `cli/`.
  */
 function versionsZeilen() {
-    let version = "unbekannt";
+    // 📌 Seit dem 2026-08-21 wird die Nummer NICHT mehr hier gelesen, sondern in
+    // `version.ts` -- sie hat einen zweiten Aufrufer bekommen (den Skill-Stempel
+    // in `skill install`). Zwei Lesestellen fuer dieselbe Zahl waeren genau das
+    // Muster, gegen das der Kommentar oben schon einmal geschrieben wurde.
+    //
+    // "unbekannt" bleibt hier stehen und wandert NICHT in `version.ts`: Diese
+    // Zeile zeigt einem Menschen etwas an, und da ist "unbekannt" die ehrliche
+    // Antwort. Der andere Aufrufer RECHNET mit dem Wert und braucht dort das
+    // Gegenteil -- er will lieber gar keine Nummer als eine erfundene.
+    const version = eigeneVersion() ?? "unbekannt";
+    return `  kimal3 ${version}\n  spricht mit ${BASIS_URL}`;
+}
+/**
+ * Welcher Update-Hinweis soll ans Ende -- oder keiner?
+ *
+ * 🔑 WARUM stderr (entschieden wird es erst beim Schreiben, gemeint ist es
+ * hier): Dort stoert der Hinweis keine Weiterverarbeitung --
+ * `kimal3 firma daten > firma.json` bleibt sauberes JSON --, und Claude sieht
+ * ihn trotzdem, denn es liest beide Kanaele.
+ *
+ * 🔴 WARUM ALLES IN EINEM try STECKT: Diese Funktion laeuft NACH dem
+ * eigentlichen Befehl. Wenn sie wirft, faellt ein bereits erfolgreicher Befehl
+ * auf Rueckgabewert 3 -- und Claude gaebe den Rat "gleich noch einmal" fuer
+ * etwas, das laengst erledigt ist. Die Zahlen sind laut dem Kopf dieser Datei
+ * die eigentliche Schnittstelle; ein Nebenschauplatz darf sie nicht anfassen.
+ */
+function hinweisText() {
     try {
-        const roh = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-        if (roh && typeof roh === "object" && "version" in roh) {
-            const v = roh.version;
-            if (typeof v === "string")
-                version = v;
+        const eigene = eigeneVersion();
+        // Ohne eigene Nummer ist jeder Vergleich geraten -- dann lieber schweigen.
+        // Das ist der Fall "package.json unlesbar", und da hat der Kunde groessere
+        // Sorgen als einen Update-Hinweis.
+        if (eigene === null)
+            return null;
+        const heute = heuteAus(new Date());
+        const h = gemerkterHinweis();
+        if (h && sollZeigen(h, eigene, leseGesehen(), heute)) {
+            // Hoechstens EIN Hinweis je Aufruf -- zwei sind eine Wand.
+            return { text: formatiere(h), kennung: h.id, tag: heute };
+        }
+        /*
+          Weg 2: ohne Netz.
+          ⚠️ Er greift immer dann, wenn oben NICHTS gezeigt wird -- nicht nur,
+          wenn gar kein Netz-Hinweis ankam (praezisiert nach der dritten
+          Review-Runde). Auch "die Nachricht stand heute schon da" und "sie gilt
+          fuer diese Fassung nicht" fuehren hierher. Das ist gewollt: Es bleibt
+          bei einem Hinweis je Aufruf.
+          *Hier stand vorher "nur, wenn kein Netz-Hinweis kam" -- eine Bedingung,
+          die der Code nicht hat. Genau der Kommentartyp, den dieses Projekt schon
+          zweimal teuer bezahlt hat.*
+        */
+        // Der Pfad kommt aus `skill-install.ts` -- dort wird er geschrieben, hier
+        // gelesen. Zwei Zusammenbauten desselben Ortes driften, und der zweite
+        // verrottet lautlos (Befund der vierten Review-Runde).
+        const datei = skillDatei();
+        const inhalt = existsSync(datei) ? readFileSync(datei, "utf8") : null;
+        if (skillZustand(inhalt, eigene) === "veraltet") {
+            // Auch dieser Hinweis nur einmal am Tag, unter einer festen Kennung.
+            // Sie kann mit keiner Nachrichten-UUID kollidieren.
+            const gesehen = leseGesehen();
+            if (gesehen["skill-veraltet"] !== heute) {
+                return { text: skillMeldung(), kennung: "skill-veraltet", tag: heute };
+            }
         }
     }
     catch {
-        // Kein Absturz, wenn die Datei fehlt: "unbekannt" ist eine ehrliche
-        // Antwort, ein Stapelabzug waere keine.
+        /* Ein Nebenschauplatz darf den Befehl nicht umwerfen. */
+    }
+    return null;
+}
+/**
+ * Den Hinweis schreiben und ERST DANN aussteigen.
+ *
+ * 🔴 WARUM NICHT EINFACH `console.error` UND `process.exit`: Auf Windows ist
+ * `process.stderr` auch bei Roehren und Terminals ASYNCHRON, und
+ * `process.exit()` wirft ausstehende Schreibvorgaenge weg (Befund der ersten
+ * Review-Runde). Der Hinweis ist das Letzte, was geschrieben wird -- er waere
+ * damit genau das Erste, was verlorengeht. *Ein Merkmal, dessen ganzer Wert an
+ * der letzten Zeile haengt, darf diese Zeile nicht dem Zufall ueberlassen.*
+ *
+ * `process.exitCode` wird vorher gesetzt: Sollte der Rueckruf wider Erwarten
+ * ausbleiben und der Prozess von selbst enden, stimmt die Zahl trotzdem -- und
+ * die Zahl ist laut dem Kopf dieser Datei die eigentliche Schnittstelle.
+ */
+function endeMitHinweis(code) {
+    try {
+        process.exitCode = code;
+        /*
+          🔴 NUR NACH EINEM GELUNGENEN BEFEHL (Befund der sechsten Review-Runde).
+          `haupt()` WIRFT bei den meisten Fehlern nicht, sondern gibt eine Zahl
+          zurueck -- 1 fuer einen unbekannten Befehl, 2 und 4 aus den Befehlen
+          selbst. Der Hinweis landete damit unter Fehlermeldungen, obwohl der
+          `.catch`-Zweig unten und der Wrapper auf dem Server beide das Gegenteil
+          begruenden: "Eine Fehlermeldung ist der schlechteste Augenblick fuer eine
+          Nebenbemerkung."
+    
+          ⚠️ Schlimmer als die Optik ist die Nebenwirkung: Der gescheiterte Lauf
+          verbrauchte den EINEN Platz des Tages. Wer sich vertippt und danach
+          richtig tippt, saehe die Nachricht dann heute gar nicht mehr.
+        */
+        const raus = code === 0 ? hinweisText() : null;
+        /*
+          🔴 BEIDE KANAELE LEEREN, NICHT NUR STDERR. Die erste Fassung dieser
+          Funktion sicherte stderr -- und liess den haeufigeren Weg (kein Hinweis)
+          bei einem nackten `process.exit` stehen. Genau der Fehler, gegen den sie
+          geschrieben war, stand also noch daneben.
+    
+          Es trifft naemlich vor allem STDOUT: `firma daten` schreibt ein
+          mehrere Kilobyte grosses JSON mit `console.log` und landet dann hier.
+          Auf Windows sind beide Kanaele asynchron; `process.exit()` wirft
+          Ausstehendes weg. Das Ergebnis waere das schlimmstmoegliche: ein
+          abgeschnittenes JSON MIT Rueckgabewert 0 -- Claude liest es als
+          gelungene Auskunft.
+    
+          🔑 Warum ueberhaupt noch `process.exit` und kein natuerliches Ende:
+          Nach einem `fetch` haelt Node seine Verbindungen eine Weile offen. Der
+          Befehl wuerde sekundenlang scheinbar haengen, nachdem er fertig ist.
+    
+          Die Notbremse ist `unref`t: Sie haelt die Schleife nicht am Leben,
+          feuert aber, falls ein Kanal wirklich haengt. Und weil `exitCode` schon
+          oben steht, stimmt die Zahl in JEDEM dieser Wege -- auch dann, wenn der
+          Prozess von selbst endet.
+    
+          🔴 UND DIE REIHENFOLGE IST DER PUNKT (Befund der sechsten Review-Runde):
+          ERST stdout leeren, DANN den Hinweis auf stderr schreiben. Die beiden
+          Kanaele haben eigene Puffer, und ihre Reihenfolge ist nur dann sicher,
+          wenn beide synchron sind -- auf einer POSIX-Roehre ist stdout es NICHT.
+          Bei `kimal3 firma daten 2>&1 | tee firma.json` mit mehr als 64 KiB
+          Nutzlast koennte die kleine stderr-Zeile also VOR dem grossen JSON
+          ankommen und mitten hineinrutschen. Genau das verbietet US-1 ("nie
+          mittendrin"), und es waere eine Ausgabe, die SKILL.md als Firmendaten
+          zu lesen anweist.
+          📌 Auf Windows liess es sich nicht herstellen -- dort sind Roehren
+          synchron. *Eine Reihenfolge, die nur auf dem Rechner haelt, auf dem man
+          sie gemessen hat, ist keine Reihenfolge, sondern ein Zufall.*
+        */
+        setTimeout(() => process.exit(code), 2000).unref();
+        process.stdout.write("", () => {
+            if (!raus) {
+                process.stderr.write("", () => process.exit(code));
+                return;
+            }
+            // Erst schreiben, DANN vermerken -- und nur, wenn kein Fehler zurueckkam.
+            process.stderr.write(`${raus.text}\n`, (fehler) => {
+                if (!fehler)
+                    merkeGesehen(raus.kennung, raus.tag);
+                process.exit(code);
+            });
+        });
+    }
+    catch {
+        /*
+          ⚠️ Auch das Schreiben selbst kann werfen -- ein geschlossener
+          Ausgabekanal genuegt. Ohne dieses `catch` liefe der Wurf in den
+          `.catch`-Zweig unten, und der macht aus einem GELUNGENEN Befehl eine
+          3 ("gleich noch einmal"). Das ist genau das, was der Kommentar an
+          `hinweisText` verspricht, dass es nie passiert -- versprochen war es
+          dort aber nur fuer die halbe Strecke.
+        */
+        process.exit(code);
     }
-    return `  kimal3 ${version}\n  spricht mit ${BASIS_URL}`;
 }
 /**
  * Was diese Zeile sagen KANN — und was nicht.
@@ -123,11 +275,18 @@ async function haupt() {
         return firmaDaten(argv.slice(2));
     if (wort === "skill install")
         return skillInstall();
+    if (argv[0] === "arbeitsplatz" && argv[1] === "neu")
+        return arbeitsplatzNeu(argv.slice(2));
+    if (argv[0] === "werkbank" && argv[1] === "neu")
+        return werkbankNeu(argv.slice(2));
     console.error(`Den Befehl „${wort}" kenne ich nicht.\n${HILFE}`);
     return 1;
 }
 haupt()
-    .then((code) => process.exit(code))
+    .then((code) => endeMitHinweis(code))
+    // ⚠️ Im Fehlerzweig bewusst KEIN Hinweis. Wer gerade eine Fehlermeldung
+    // liest, braucht keine zweite Zeile ueber Updates -- und ein Netz-Hinweis
+    // kann hier ohnehin nicht angekommen sein, denn genau das Netz hat versagt.
     .catch((f) => {
     if (f instanceof NichtAngemeldet) {
         console.error("Bitte zuerst `kimal3 login` ausführen.");

package/dist/nachricht.js

@@ -0,0 +1,198 @@
+/**
+ * Die reinen Rechnungen des Update-Kanals -- und sonst nichts.
+ *
+ * 🔑 WARUM DIESE DATEI NICHTS ANFASST: Kein fetch, kein readFileSync, kein
+ * `new Date()` ohne Uebergabe. Genau deshalb kann `npm run check:nachrichten`
+ * Faelle pruefen, die es in der Wirklichkeit nur durch Warten gaebe --
+ * "gestern gesehen", "0.10.0 gegen 0.9.0", "Stempel aus der Zukunft".
+ * Die Raender (Datei, Netz, Uhr) wohnen in gesehen.ts, api.ts und kimal3.ts.
+ */
+/** Der Stempel, den `kimal3 skill install` ans Ende der SKILL.md schreibt. */
+export const STEMPEL_MARKE = "kimal3:erzeugt version=";
+/**
+ * Zieht den Hinweis aus einer Server-Antwort -- oder gibt `null` zurueck.
+ *
+ * ⚠️ Jedes Feld einzeln pruefen, obwohl der Server unserer ist. Diese Zeilen
+ * laufen auf dem Rechner des Kunden und muessen auch dann halten, wenn dort
+ * eine ALTE CLI auf eine NEUE Antwort trifft oder umgekehrt. Genau dieser
+ * Versatz ist bei einem Werkzeug, das man selbst aktualisieren muss, der
+ * Normalfall -- kein Sonderfall.
+ */
+export function hinweisAusAntwort(koerper) {
+    if (!koerper || typeof koerper !== "object")
+        return null;
+    const roh = koerper.hinweis;
+    if (!roh || typeof roh !== "object")
+        return null;
+    const h = roh;
+    if (typeof h.id !== "string" || typeof h.text !== "string")
+        return null;
+    return {
+        id: h.id,
+        text: h.text,
+        gilt_unter_version: typeof h.gilt_unter_version === "string" ? h.gilt_unter_version : null,
+    };
+}
+function teile(v) {
+    /*
+      ⚠️ Ein Anhaengsel wie `-rc.1` oder `+build3` faellt vorher weg (Befund der
+      ersten Review-Runde). Ohne diese Zeile legt ein einziges `npm version
+      prerelease` den GANZEN Kanal still: `eigeneVersion()` gaebe "0.2.0-rc.1"
+      zurueck -- nicht `null`, also faehrt `hinweisText` weiter --, aber jeder
+      Vergleich antwortete `false`. Kein Netz-Hinweis, kein Skill-Hinweis, keine
+      Fehlermeldung. *Ein Merkmal, das sich lautlos abschaltet, faellt niemandem
+      auf.*
+  
+      🔑 Bewusst NICHT nach Semver sortiert (dort gilt `0.2.0-rc.1` < `0.2.0`):
+      Diese Rechnung beantwortet "soll ich jemandem ein Update anbieten", und da
+      ist eine Vorabversion nah genug an ihrer Fassung. Die Genauigkeit waere
+      Aufwand fuer einen Fall, den es hier noch nie gab -- YAGNI.
+    */
+    const stuecke = v.trim().split(/[-+]/)[0].split(".");
+    if (stuecke.length === 0)
+        return null;
+    const zahlen = [];
+    for (const s of stuecke) {
+        // ⚠️ Absichtlich streng: `Number("1a")` ist NaN, aber `parseInt("1a")` ist 1.
+        // Wer hier `parseInt` nimmt, macht aus dem Muellwert "bald" eine 0 und
+        // vergleicht dann munter weiter.
+        if (!/^\d+$/.test(s))
+            return null;
+        zahlen.push(Number(s));
+    }
+    return zahlen;
+}
+/**
+ * Ist `a` aelter als `b`? Zahl fuer Zahl, nicht als Text.
+ *
+ * 🔴 DER FALL, DER DIESE FUNKTION RECHTFERTIGT: `"0.10.0" < "0.9.0"` ist als
+ * Textvergleich WAHR. Wer so vergleicht, haelt die neueste Fassung fuer die
+ * aeltere und drangsaliert genau die Kunden, die aktuell sind.
+ *
+ * Ist einer der beiden Werte kein Versionsstand, lautet die Antwort `false` --
+ * "im Zweifel schweigen" ist bei einem Nebenschauplatz die richtige Vorgabe.
+ */
+export function istAelter(a, b) {
+    const x = teile(a);
+    const y = teile(b);
+    if (!x || !y)
+        return false;
+    const laenge = Math.max(x.length, y.length);
+    for (let i = 0; i < laenge; i++) {
+        const links = x[i] ?? 0;
+        const rechts = y[i] ?? 0;
+        if (links !== rechts)
+            return links < rechts;
+    }
+    return false;
+}
+/**
+ * Welcher Tag ist in Deutschland gerade?
+ *
+ * ⚠️ NICHT `toISOString().slice(0,10)` -- das ist UTC. Um 00:30 deutscher Zeit
+ * waere "heute" der Vortag, und die Nachricht erschiene an einem Abend zweimal.
+ * `sv-SE` liefert von sich aus `JJJJ-MM-TT`; dieselbe Technik wie
+ * `heuteInDeutschland` in der App. Importieren laesst sie sich nicht --
+ * `cli/tsconfig.json` steht auf `rootDir: src` (Begruendung steht schon in
+ * projekt-zeilen.ts).
+ */
+export function heuteAus(d) {
+    return new Intl.DateTimeFormat("sv-SE", { timeZone: "Europe/Berlin" }).format(d);
+}
+/**
+ * Die ganze Entscheidung, als Funktion von vier Werten.
+ */
+export function sollZeigen(h, eigeneVersion, gesehen, heute) {
+    if (!h.id)
+        return false;
+    if (!h.text || h.text.trim() === "")
+        return false;
+    // Leeres Feld = alle sehen es. Sonst nur, wer aelter ist als die Grenze.
+    if (h.gilt_unter_version && !istAelter(eigeneVersion, h.gilt_unter_version))
+        return false;
+    // Hoechstens einmal am Tag -- auch bei zwanzig Befehlen.
+    if (gesehen[h.id] === heute)
+        return false;
+    return true;
+}
+/**
+ * Die Zeilen fuers Terminal.
+ *
+ * Bewusst Klartext mit `→`, wie der Rest der CLI: `cli/` hat null
+ * Abhaengigkeiten und nirgends ANSI-Farben. Ein gezeichneter Kasten braeche
+ * ausserdem in einem schmalen Terminal auseinander -- ein eingerueckter Satz
+ * nicht.
+ */
+export function formatiere(h) {
+    return `\n  →  ${saeubere(h.text)}\n`;
+}
+/**
+ * Macht aus dem Nachrichtentext EINE harmlose Zeile.
+ *
+ * 🔴 WARUM UEBERHAUPT (Befund der vierten Review-Runde): Der Text kommt aus
+ * der Datenbank und wird in ein TERMINAL geschrieben. Steuerzeichen sind dort
+ * keine Zeichen, sondern Befehle -- eine ANSI-Fluchtfolge kann faerben, den
+ * Bildschirm loeschen oder den Wagen zurueckholen und damit Zeilen
+ * ueberschreiben, die schon dastanden. Der Kanal wuerde dann nicht mehr nur
+ * etwas HINZUFUEGEN, sondern die Ausgabe des Befehls veraendern.
+ *
+ * ⚠️ Und Zeilenumbrueche muessen weg, weil die Ausgabe genau eine eingerueckte
+ * Zeile ist: Ein "\n" mitten im Text schoebe den Rest linksbuendig darunter --
+ * es saehe aus wie Ausgabe des Befehls, nicht wie ein Hinweis.
+ *
+ * 📌 Die Pruefung dazu stand vorher da und konnte nicht rot werden: Sie mass
+ * einen Vordruck ohne Steuerzeichen. *Eine gruene Pruefung ueber einen Wert,
+ * der nie anders aussieht, prueft den Vordruck, nicht den Code.*
+ */
+function saeubere(text) {
+    return text
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Zieht `0.1.6` aus `<!-- kimal3:erzeugt version=0.1.6 -->`.
+ *
+ * 🔴 DER LETZTE TREFFER GILT, nicht der erste (Befund der fuenften
+ * Review-Runde). Der echte Stempel steht immer am DATEIENDE -- aber die
+ * SKILL.md ist ein Text ueber dieses Werkzeug und beschreibt inzwischen selbst,
+ * wie der Kanal funktioniert. Nennt sie eines Tages ein Beispiel wie
+ * `version=9.9.9`, gewaenne der Beispieltext gegen den echten Stempel:
+ * `skillZustand` antwortete fuer immer "still", und Weg 2 waere lautlos tot.
+ *
+ * *Ein Dokument, das seine eigene Maschinenlesbarkeit beschreibt, wird
+ * irgendwann versehentlich zu seinen eigenen Daten.*
+ */
+export function stempelAus(inhalt) {
+    const treffer = [...inhalt.matchAll(/kimal3:erzeugt version=([0-9][0-9.]*)/g)];
+    return treffer.length > 0 ? treffer[treffer.length - 1][1] : null;
+}
+/**
+ * Die DREI Zustaende aus US-4/US-5 -- und sie sind ausdruecklich drei, nicht
+ * zwei:
+ *
+ * | Was liegt dort        | Antwort    |
+ * |-----------------------|------------|
+ * | Datei fehlt           | still      |  <- nie installiert
+ * | Datei ohne Stempel    | veraltet   |  <- 0.1.4 und aelter
+ * | Stempel aelter        | veraltet   |
+ * | Stempel gleich/neuer  | still      |  <- niemand wird rueckwaerts gedraengt
+ *
+ * ⚠️ Die ersten beiden sehen im Dateisystem fast gleich aus und bedeuten das
+ * Gegenteil. `null` heisst hier "es gibt keine Datei", NICHT "leer".
+ */
+export function skillZustand(inhalt, eigeneVersion) {
+    if (inhalt === null)
+        return "still";
+    const stempel = stempelAus(inhalt);
+    if (stempel === null)
+        return "veraltet";
+    return istAelter(stempel, eigeneVersion) ? "veraltet" : "still";
+}
+/**
+ * ⚠️ Sie nennt den Befehl, sie FUEHRT IHN NICHT AUS. Ein Befehl darf nicht
+ * mehr tun, als sein Name verspricht -- die Regel steht schon in kimal3.ts.
+ */
+export function skillMeldung() {
+    return "\n  →  Deine kimal3-Skilldateien sind aelter als die CLI.  kimal3 skill install\n";
+}

package/dist/version.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+/**
+ * Die eigene Versionsnummer -- GELESEN, nie abgetippt.
+ *
+ * ⚠️ Die Regel dahinter ist gemessen (QA-Befund B-8, 2026-08-18): Stuende die
+ * Zahl als Text im Code, sagte die CLI nach dem naechsten `npm version` die
+ * alte Nummer. Dieselbe Zahl an zwei Tueren mit zwei Werten -- ein Muster, das
+ * in diesem Projekt schon mehrfach zugeschlagen hat.
+ *
+ * 📌 `../package.json` stimmt aus `dist/` UND aus `src/`: Beide liegen eine
+ * Ebene unter `cli/`. Deshalb steht hier kein fester Pfad.
+ *
+ * 🔴 RUECKGABE `null`, NICHT "0.0.0" und auch nicht "unbekannt".
+ * Diese Funktion hat zwei Aufrufer mit gegensaetzlichem Bedarf:
+ *   - `versionsZeilen()` ZEIGT den Wert einem Menschen. Dort ist "unbekannt"
+ *     die ehrliche Antwort -- eine erfundene "0.0.0" waere eine Luege auf dem
+ *     Bildschirm.
+ *   - `hinweisAusgeben()` RECHNET damit. Dort ist "unbekannt" Muell, der jeden
+ *     Versionsvergleich schweigen laesst.
+ * `null` zwingt beide, ihren eigenen Fall zu entscheiden, statt einen
+ * Ersatzwert zu erben, der nur fuer den anderen passt.
+ */
+export function eigeneVersion() {
+    try {
+        const roh = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        if (roh && typeof roh === "object" && "version" in roh) {
+            const v = roh.version;
+            if (typeof v === "string")
+                return v;
+        }
+    }
+    catch {
+        // Kein Absturz, wenn die Datei fehlt oder Unsinn enthaelt. Der Aufrufer
+        // entscheidet, was "keine Nummer" bei ihm bedeutet.
+    }
+    return null;
+}