kimal3 0.1.6 → 0.2.1

package/dist/befehle-katalog.js

@@ -42,7 +42,13 @@ export const BEFEHLE = [
         tippen: "! kimal3 skill install",
         terminal: "kimal3 skill install",
         details: [
-            "Der Befehl, der aus den anderen erst etwas macht: Er legt 🤖 Claudes Anleitung ab (den „Skill“) und 🧑 deine vier Slash-Befehle.",
+            // ⚠️ KEINE Anzahl hier (Review-Runde 5): Hier stand „deine vier
+            // Slash-Befehle“, und die Zahl war ab `/k3kontext` falsch — auf der
+            // Pro-Seite UND in der Terminal-Hilfe, denn dieser Text wird an beiden
+            // Stellen ausgegeben. Dieselbe Lehre wie bei „13 Pruefungen“ in
+            // `check:arbeitsplatz`: Eine Anzahl im Fliesstext ist eine Behauptung,
+            // die verrottet. Welche es sind, sagt `/k3` beim Laufen.
+            "Der Befehl, der aus den anderen erst etwas macht: Er legt 🤖 Claudes Anleitung ab (den „Skill“) und 🧑 deine Slash-Befehle.",
             "Er läuft NICHT automatisch — einmal nach der Installation, und nach jedem Update noch einmal. Sonst arbeitet Claude weiter mit der alten Anleitung.",
             "Geklappt hat es, wenn er „Skill angelegt“ meldet und die Slash-Befehle aufzählt. Beides kennt Claude ab der NÄCHSTEN Sitzung — die laufende einmal neu starten.",
         ],
@@ -84,6 +90,56 @@ export const BEFEHLE = [
             "Gib deinen Vornamen mit — der Ordner trägt ihn: aus sabine wird werkbank-sabine. Ohne Angabe bildet der Server ihn aus deiner Anmelde-Adresse. So sieht man später, wem welche Werkbank gehört.",
         ],
     },
+    /*
+      🔴 Auch diese zwei Eintraege stehen direkt NEBEN `werkbank neu` und nicht
+      am Ende der Liste, aus demselben Grund wie oben bei `arbeitsplatz neu`:
+      Wer hier liest, sucht den naechsten Schritt, nicht das Alphabet. Wer
+      einen KI-Arbeitsplatz gerade angelegt oder betreten hat, fragt sich als
+      Naechstes, wie der Firmenkontext (CLAUDE.md + kontext/*.md) aktuell
+      bleibt -- nicht, wie man ein Projekt eintraegt.
+    */
+    {
+        befehl: "kimal3 kontext runter",
+        beschreibung: "Den Firmenkontext holen — CLAUDE.md und die fünf Dateien in kontext/",
+        wer: "du",
+        rhythmus: "wann immer die Firma etwas geändert haben könnte",
+        tippen: "! kimal3 kontext runter",
+        terminal: "kimal3 kontext runter",
+        details: [
+            "Holt CLAUDE.md und die fünf Dateien in kontext/ von deiner Firma und legt sie in deinem KI-Arbeitsplatz ab. Was du selbst lokal geändert hast, fasst er nicht an — er sagt dir, wie du es einbringst.",
+            "Hast du eine Datei lokal geändert UND hat die Firma sie inzwischen auch geändert, sichert er deine Fassung zuerst nach kontext/vorher-<datum>/, bevor er sie ersetzt — nichts geht verloren.",
+            "Geklappt hat es, wenn er die aktualisierten Dateien nennt oder „Dein Firmenkontext ist aktuell“ sagt.",
+            "⚠️ Wie werkbank neu braucht er ein eigenes Pro-Konto. Ohne das kommt Rückgabewert 4 — dann nicht wiederholen.",
+        ],
+    },
+    {
+        befehl: "kimal3 kontext fragen",
+        beschreibung: "Die Fragen über deine Firma beantworten — Claude führt dich durch",
+        wer: "claude",
+        ausloeser: "beantworten wir die Fragen über meine Firma",
+        tippen: "/k3kontext",
+        terminal: "kimal3 kontext fragen",
+        details: [
+            "Liest die fünf Dateien in kontext/ und gibt jede Frage aus, unter der noch nichts steht — mit Datei, Frage und Hinweis. Sind alle beantwortet, sagt er das in einem Satz.",
+            "Er liest nur: kein Netz, keine Anmeldung, kein Schreiben. Deshalb ist er der richtige erste Schritt — Claude stellt dir die Fragen dann einzeln und trägt deine Antworten in die Dateien ein.",
+            "Danach schickt kimal3 kontext hoch sie an die Firma. Das darf nur der Admin; alle anderen geben ihre Antworten an ihn weiter.",
+        ],
+    },
+    {
+        befehl: "kimal3 kontext hoch",
+        beschreibung: "Deine lokalen Änderungen an den fünf Firmen-Texten hochschicken",
+        wer: "du",
+        rhythmus: "nachdem du kontext/*.md bearbeitet hast — nur als Admin",
+        tippen: "! kimal3 kontext hoch",
+        terminal: "kimal3 kontext hoch",
+        details: [
+            "Schickt alle fünf Firmen-Texte an deine Firma — die Dateien in kontext/ (kurzprofil.md, firma.md, marke.md, systeme.md, sicherheit.md). Damit kommen sie beim nächsten kontext runter auch bei den Kolleginnen und Kollegen an.",
+            "🔴 Nur der Firmen-Admin darf das. Bist du keiner, sagt er es dir — dann gib deine Ergänzung an den Admin weiter, ein zweiter Versuch ändert daran nichts.",
+            "⚠️ Klappt etwas nicht, zählt die MELDUNG, nicht die Zahl dahinter: Dieselbe 1 steht für „du bist kein Admin“, „hier steht kein Arbeitsplatz“, „jemand anderes hat inzwischen geändert“ (Ausweg --ueberschreiben) und mehreres mehr. Sie steht sogar unter einer Meldung, die mit „Die Firma hat deine Änderungen gespeichert“ beginnt und nur sagt, dass eine Datei auf deiner Platte nicht geschrieben werden konnte — DAS ist ein Erfolg: alles ist oben angekommen. Lies den Satz, nicht die Zahl.",
+            "Sieht eine der fünf Dateien nicht mehr aus wie ihre Frageliste — etwa weil etwas Fremdes darüberkopiert wurde —, bricht er ab und schickt gar nichts, auch die vier anderen nicht. kimal3 kontext runter holt die Datei zurück.",
+            "Geklappt hat es, wenn er „✓ hochgeschickt“ mit den Dateinamen meldet.",
+        ],
+    },
     {
         befehl: "kimal3 projekt neu …",
         beschreibung: "Ein Projekt ins Erfolgsprofil eintragen",
@@ -113,7 +169,7 @@ export const BEFEHLE = [
         beschreibung: "Die Daten deiner Firma holen, damit Claude sie auswerten kann",
         wer: "claude",
         ausloeser: "werte meine Firma aus",
-        tippen: "/k3firma <deine Frage>",
+        tippen: "/k3analyse <deine Frage>",
         terminal: 'kimal3 firma daten --firma "Nordwind Handel GmbH"',
         details: [
             "Holt Kennzahlen, Menschen und Projekte deiner Firma — auswerten tut Claude. Frag einfach los: „Welche drei Projekte bringen den meisten messbaren Ertrag?“",

package/dist/firmen-liste.js

@@ -2,8 +2,10 @@
  * Die Firmen-Auswahl, die eine Absage dem Menschen anbietet.
  *
  * 🔑 Eine reine Rechnung, damit `check:cli` sie ohne Server pruefen kann --
- * dieselbe Ueberlegung wie bei `fehler.ts`.
+ * dieselbe Ueberlegung wie bei `fehler.ts`. `alsWort` unten ist ebenfalls eine
+ * reine Rechnung, der Import bricht das also nicht.
  */
+import { alsWort } from "./argumente.js";
 /**
  * Aus den Namen der eigenen Firmen die Zeilen bauen, die unter „Deine Firmen:"
  * stehen.
@@ -42,7 +44,7 @@ export function firmenZeilen(namen) {
             // Fertiger Befehl statt blosser Liste: Der naechste Schritt ist dann
             // Kopieren statt Abtippen -- und ein Name mit Leerzeichen braucht
             // Anfuehrungszeichen, an die sonst niemand denkt.
-            zeilen.push(`    kimal3 firma daten --firma "${name}"`);
+            zeilen.push(`    kimal3 firma daten --firma ${alsWort(name, true)}`);
         }
         else {
             zeilen.push(`    „${name}" — kommt ${wieOft}× vor und ist über den Namen nicht wählbar.`);

package/dist/fragen-lesen.js

@@ -0,0 +1,178 @@
+/*
+  Die Fragen aus einer Kontext-Datei lesen -- die reine Rechnung hinter
+  `kimal3 kontext fragen` und hinter dem Abbruch von `kimal3 kontext hoch`.
+
+  🔑 WOHER DIE FRAGEN KOMMEN -- die eine Entscheidung dieser Datei:
+  **Aus der Datei selbst, nicht aus einem Katalog.** Jede ausgelieferte
+  Kontext-Datei traegt ihre Fragen bereits vollstaendig bei sich: einen Anker
+  (`<!-- k3:marke_anrede -->`), darunter die Frage als `## `-Ueberschrift,
+  darunter unsere Hinweiszeilen mit `>`, darunter die Antwort des Menschen.
+  Das Format beschreibt sich selbst.
+
+  🔴 WARUM DAS NICHT NUR BEQUEM, SONDERN DAS EINZIG EHRLICHE IST: Die CLI kann
+  nichts aus `src/` importieren (eigenes Paket, eigenes tsconfig -- s. Kopf von
+  `kontext-stand.ts`). Ein Katalog in `cli/src/` waere eine ZWEITE Fassung der
+  17 Fragen, und sie friert in dem Moment ein, in dem `npm publish` laeuft: Der
+  Kunde hat dann eine CLI von gestern und Dateien von heute. Die Datei auf
+  seiner Platte kommt dagegen IMMER vom Server -- sie ist die einzige Quelle,
+  die nicht gegenueber dem abweichen kann, was er wirklich vor sich hat.
+
+  ⚠️ DIESE DATEI IMPORTIERT NICHTS -- dieselbe Auflage wie `kontext-stand.ts`.
+  Nur so kann `scripts/check-kontext.mts` sie neben `FRAGEN` (aus der App) in
+  denselben Lauf holen und beide gegeneinander messen.
+
+  📌 Der Preis, ausgesprochen: Wer den ANKER einer Frage aus seiner Datei
+  loescht, die Ueberschrift aber stehen laesst, hat eine Frage, die hier nicht
+  mehr auftaucht. Die App faengt diesen Fall ab (sie erkennt die Frage am
+  Wortlaut) und setzt den Anker beim naechsten Speichern wieder ein. Die
+  Ausgabe von `kontext fragen` sagt deshalb "Fragen in deinen Dateien" und
+  nicht "alle Fragen deiner Firma" -- sie behauptet nur, was sie messen kann.
+*/
+/**
+ * `<!-- k3:anrede -->` bzw. `<!-- k3:unwoerter optional -->`.
+ *
+ * ⚠️ Woertlich dasselbe Muster wie `ANKER_MUSTER` in
+ * `src/app/firma/kontext-zerlegen.ts`. Es steht hier ein zweites Mal, weil
+ * diese Datei nichts importieren darf (s. Kopf) -- dass beide dasselbe meinen,
+ * misst `check:kontext`, indem er die ECHTEN Vorlagen durch beide Seiten
+ * schickt und die Ergebnisse vergleicht.
+ */
+const ANKER_MUSTER = /^<!--\s*k3:([a-z0-9_]+)(\s+optional)?\s*-->$/;
+function istHinweis(zeile) {
+    return zeile.trimStart().startsWith(">");
+}
+function istUeberschrift(zeile) {
+    return zeile.startsWith("## ");
+}
+/**
+ * Alle Fragen, die in `text` stehen -- in der Reihenfolge der Datei.
+ *
+ * Der Durchgang ist zeilenweise und haelt drei Dinge auseinander:
+ * 1. **Anker** -- er merkt sich, wessen Frage als Naechstes kommt.
+ * 2. **Ueberschrift** -- steht ein Anker offen, beginnt hier seine Frage.
+ * 3. **Darunter** -- die unmittelbar folgenden `>`-Zeilen sind UNSER Hinweis,
+ *    alles Weitere bis zur naechsten Ueberschrift ist die Antwort.
+ *
+ * 🔑 DER HINWEIS ZAEHLT NUR UNMITTELBAR UNTER DER UEBERSCHRIFT -- genau wie in
+ * `scripts/arbeitsplatz-inhalt.mts`, wo derselbe Katalog fuer die App entsteht.
+ * Sonst kaeme eine `>`-Zeile, die ein Mensch mitten in seine Antwort setzt,
+ * als unser Hinweis heraus.
+ *
+ * 🔴 AUS DER ANTWORT FALLEN TROTZDEM ALLE `>`-ZEILEN HERAUS, auch spaetere --
+ * das ist die Regel, nach der auch die App zerlegt (`zerlege`). Ein Zitatblock
+ * gehoert uns; ginge er als Antwort durch, stuende unser eigener Satz als
+ * Aussage der Firma in der Datenbank.
+ *
+ * ⚠️ Ein Anker OHNE Ueberschrift darunter zaehlt nicht -- er wird vom naechsten
+ * Anker oder von der naechsten Ueberschrift ueberschrieben. *Ein Anker, der auf
+ * eine Ueberschrift drei Absaetze weiter zeigt, ist kein Anker, sondern ein
+ * Zufall, der aussieht wie Absicht.*
+ */
+export function fragenAus(text) {
+    const zeilen = text.split(/\r?\n/);
+    const fragen = [];
+    let offenerAnker = null;
+    let aktuell = null;
+    let hinweisNochOffen = false;
+    const hinweise = [];
+    const antwort = [];
+    /** Die laufende Frage abschliessen -- Hinweis und Antwort festschreiben. */
+    const schliesse = () => {
+        if (aktuell === null)
+            return;
+        aktuell.hinweis = hinweise.join(" ").trim();
+        aktuell.antwort = antwort.join("\n").trim();
+        aktuell = null;
+        hinweise.length = 0;
+        antwort.length = 0;
+    };
+    for (const zeile of zeilen) {
+        const treffer = ANKER_MUSTER.exec(zeile.trim());
+        if (treffer) {
+            schliesse();
+            offenerAnker = { anker: treffer[1], pflicht: !treffer[2] };
+            continue;
+        }
+        if (istUeberschrift(zeile)) {
+            schliesse();
+            if (offenerAnker) {
+                aktuell = {
+                    anker: offenerAnker.anker,
+                    ueberschrift: zeile.slice(3).trim(),
+                    hinweis: "",
+                    pflicht: offenerAnker.pflicht,
+                    antwort: "",
+                };
+                hinweisNochOffen = true;
+                fragen.push(aktuell);
+            }
+            offenerAnker = null;
+            continue;
+        }
+        /*
+          🔴 **RULING K-14: EIN ANKER, UNTER DEM NICHT UNMITTELBAR SEINE FRAGE
+          STEHT, ZAEHLT NICHT.** Leerzeilen sind erlaubt, Text nicht. Ohne diese
+          drei Zeilen machte ein verwaister Anker die naechstbeste Ueberschrift zur
+          Frage -- und `kimal3 kontext fragen` stellte einem Menschen eine Frage,
+          die niemand geschrieben hat. Dieselbe Regel wie im Erzeuger
+          (`frageZeileNach` in `scripts/arbeitsplatz-inhalt.mts`).
+    
+          ⚠️ Die App ist an dieser Stelle NACHSICHTIGER: `zerlege` haengt einen
+          verwaisten Anker an die naechste Ueberschrift, wie weit sie auch weg ist.
+          Der Unterschied ist gewollt und folgenlos, solange keine ausgelieferte
+          Datei einen verwaisten Anker hat -- und genau das prueft
+          `check:arbeitsplatz` fuer jede Vorlage.
+        */
+        if (offenerAnker && zeile.trim() !== "")
+            offenerAnker = null;
+        if (aktuell === null)
+            continue;
+        if (istHinweis(zeile)) {
+            // Nur der Block DIREKT unter der Ueberschrift ist unser Hinweis;
+            // spaetere `>`-Zeilen fallen weg, gehoeren aber auch nicht zur Antwort.
+            if (hinweisNochOffen)
+                hinweise.push(zeile.trimStart().slice(1).trim());
+            continue;
+        }
+        // ⚠️ SCHON EINE LEERZEILE BEENDET DEN HINWEISBLOCK -- woertlich dieselbe
+        // Grenze wie im Erzeuger (`katalogAus` in `scripts/arbeitsplatz-inhalt.mts`).
+        // Zoege sie hier weiter, kaeme aus einer Datei mit einem Zitat weiter unten
+        // ein anderer Hinweis heraus als in der App, und `check:kontext` haette
+        // recht, wenn er rot wird.
+        hinweisNochOffen = false;
+        antwort.push(zeile);
+    }
+    schliesse();
+    return fragen;
+}
+/**
+ * Sieht dieser Text aus wie die Datei, die er sein soll?
+ *
+ * 🔴 **DER ABBRUCH VON `kimal3 kontext hoch` HAENGT AN DIESER ZEILE** (Spec,
+ * Abschnitt 11). Ohne sie schickt der Befehl JEDEN Dateiinhalt hoch, den er an
+ * der Stelle findet. Die App zerlegt ihn dann gegen den Katalog DIESER Datei,
+ * findet keine einzige Antwort -- und legt den kompletten Text als "Zusatz"
+ * ab. Die Firma haette danach einen Zusatz statt eines Firmentextes, und die
+ * CLI haette dazu einen Haken gemeldet. *Ein Fehlerfall darf nie denselben
+ * Namen tragen wie ein Erfolgsfall.*
+ *
+ * 🔑 **WORAN ERKANNT WIRD: an mindestens einem Anker, der zu DIESER Datei
+ * gehoert.** Die Anker sind je Datei benannt (`marke_anrede`, `firma_angebot`,
+ * `kurz_kunden` …), und `FIRMEN_TEXTE` (`kontext-stand.ts`) fuehrt je Datei
+ * ihren Praefix. Damit faellt nicht nur die voellig fremde Datei durch, sondern
+ * auch der haeufigere Unfall: `marke.md` ueber `firma.md` kopiert. Ein blosses
+ * "irgendein Anker steht drin" haette genau den durchgewunken.
+ *
+ * ⚠️ **Dass die Praefixe wirklich passen, ist keine Verabredung, sondern eine
+ * Messung:** `check:kontext` haelt jeden Anker aus `FRAGEN` (der App) gegen den
+ * Praefix, den `FIRMEN_TEXTE` fuer seine Datei nennt.
+ *
+ * 📌 **Der Preis, ausgesprochen:** Wer ALLE Anker einer Datei loescht und nur
+ * die Ueberschriften stehen laesst, bekommt hier ein Nein, obwohl die App den
+ * Text noch am Wortlaut erkennen wuerde. Das ist die sichere Seite: Es geht
+ * nichts verloren, die Meldung sagt warum, und `kimal3 kontext runter` stellt
+ * die Datei wieder her. Die andere Seite waere der stille Datenverlust oben.
+ */
+export function traegtFragenVon(text, ankerPraefix) {
+    return fragenAus(text).some((f) => f.anker.startsWith(ankerPraefix));
+}

package/dist/kimal3.js

@@ -13,7 +13,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { BASIS_URL, leseAnmeldung } from "./anmeldung.js";
-import { gemerkterHinweis, NichtAngemeldet } from "./api.js";
+import { gemerkterHinweis, lokalerKontextStandJetzt, NichtAngemeldet } from "./api.js";
 import { leseGesehen, merkeGesehen } from "./gesehen.js";
 import { formatiere, heuteAus, skillMeldung, skillZustand, sollZeigen, } from "./nachricht.js";
 import { eigeneVersion } from "./version.js";
@@ -21,6 +21,9 @@ 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 { kontextFragen } from "./befehle/kontext-fragen.js";
+import { kontextRunter } from "./befehle/kontext-runter.js";
+import { kontextHoch } from "./befehle/kontext-hoch.js";
 import { login } from "./befehle/login.js";
 import { logout } from "./befehle/logout.js";
 import { projektListe } from "./befehle/projekt-liste.js";
@@ -96,8 +99,26 @@ function hinweisText() {
         if (eigene === null)
             return null;
         const heute = heuteAus(new Date());
+        /*
+          🔴 HIER, UND NICHT FRUEHER (offener Punkt A-4). Diese Zeile liest den
+          Merkzettel auf der Platte in genau dem Augenblick, in dem der Hinweis
+          ausgegeben werden soll -- also NACH dem Befehl.
+    
+          Genau darin lag der Fehler: Den Stand, den der Server fuer seinen
+          Hinweis vergleicht, schickt die CLI im Kopf mit, und der wird VOR dem
+          Netzaufruf gelesen (`kontextStandKopf` in `api.ts`). Direkt nach
+          `kimal3 kontext runter` stand deshalb "Dein Firmenkontext ist aktuell."
+          und darunter der Rat, `kimal3 kontext runter` auszufuehren. Der zweite
+          Aufruf schwieg dann von selbst -- die Meldung kam schlicht einen Aufruf
+          zu spaet.
+    
+          🔑 `sollZeigen` VERLANGT diesen Wert (kein optionales Argument): Wer ihn
+          hier vergisst, bekommt einen Uebersetzungsfehler statt einer Rechnung,
+          die niemand mehr benutzt.
+        */
+        const standJetzt = lokalerKontextStandJetzt();
         const h = gemerkterHinweis();
-        if (h && sollZeigen(h, eigene, leseGesehen(), heute)) {
+        if (h && sollZeigen(h, eigene, leseGesehen(), heute, standJetzt)) {
             // Hoechstens EIN Hinweis je Aufruf -- zwei sind eine Wand.
             return { text: formatiere(h), kennung: h.id, tag: heute };
         }
@@ -279,6 +300,12 @@ async function haupt() {
         return arbeitsplatzNeu(argv.slice(2));
     if (argv[0] === "werkbank" && argv[1] === "neu")
         return werkbankNeu(argv.slice(2));
+    if (argv[0] === "kontext" && argv[1] === "runter")
+        return kontextRunter(argv.slice(2));
+    if (argv[0] === "kontext" && argv[1] === "hoch")
+        return kontextHoch(argv.slice(2));
+    if (argv[0] === "kontext" && argv[1] === "fragen")
+        return kontextFragen(argv.slice(2));
     console.error(`Den Befehl „${wort}" kenne ich nicht.\n${HILFE}`);
     return 1;
 }

package/dist/kontext-dateien.js

@@ -0,0 +1,248 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { istUnsichererPfad } from "./arbeitsplatz-dateien.js";
+import { MERKZETTEL_PFAD, VERWALTETE_DATEIEN, arbeitsplatzAus, leseMerkzettel, schreibeMerkzettel, sicherungsZiel, } from "./kontext-stand.js";
+/**
+ * Das Dateisystem hinter `kimal3 kontext runter` -- Ordner finden, die
+ * verwalteten Dateien lesen, sichern, schreiben, den Merkzettel lesen und
+ * schreiben.
+ *
+ * 🔴 **Ruling T8-1: Die reine Fundregel `arbeitsplatzAus` wird hier NICHT noch
+ * einmal geschrieben** -- sie steht seit Task 1 in `kontext-stand.ts` und wird
+ * hier nur VERBRAUCHT (`findeArbeitsplatz` unten fuellt sie mit echten
+ * Kandidaten vom Dateisystem). Zwei Fassungen derselben Fundregel waeren
+ * dieselbe zweite Wahrheit, die dieses Projekt schon bei `werkbankAusDateien`
+ * teuer bezahlt hat.
+ *
+ * ⚠️ **Dieselben Netze wie in `arbeitsplatz-dateien.ts`**, aus denselben,
+ * teuer bezahlten Gruenden: `existsSync`/`statSync`/`readFileSync` gehoeren
+ * in ein EIGENES `try` -- ein `EACCES` fluege sonst bis in den Auffang-Block
+ * von `kimal3.ts`, der "kimal3 ist gerade nicht erreichbar" druckt und `3`
+ * zurueckgibt. Der Mensch suchte den Fehler dann beim Server, obwohl er auf
+ * seiner eigenen Platte sitzt -- und `3` heisst "gleich noch einmal", was
+ * hier nie helfen kann. Ein Schreibfehler (Platte voll, `EACCES`) gibt
+ * deshalb `1` zurueck, nicht `3`.
+ */
+/** Ist `pfad` (relativ zu `wurzel`) ein lesbarer ORDNER? Unlesbar zaehlt als "nein". */
+function istLesbarerOrdner(pfad) {
+    try {
+        return existsSync(pfad) && statSync(pfad).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Ist `pfad` (relativ zu `wurzel`) eine lesbare DATEI? Unlesbar zaehlt als "nein". */
+function istLesbareDatei(pfad) {
+    try {
+        return existsSync(pfad) && statSync(pfad).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Von `start` aufwaerts nach dem Arbeitsplatz suchen -- die Kandidaten kommen
+ * von UNTEN NACH OBEN, `start` zuerst.
+ *
+ * 🔑 Diese Funktion FUELLT nur die Kandidatenliste vom Dateisystem; die
+ * eigentliche Entscheidung ("welcher Ordner gewinnt") trifft `arbeitsplatzAus`
+ * in `kontext-stand.ts` (Ruling P-4/T8-1).
+ *
+ * Die Schleife hat eine Sicherheitsgrenze (200 Ebenen): `dirname()` konvergiert
+ * auf jedem realen Dateisystem zur Wurzel, aber ein Netzlaufwerk mit einem
+ * kaputten Elternverweis soll trotzdem nie eine Endlosschleife erzeugen.
+ */
+export function findeArbeitsplatz(start) {
+    const kandidaten = [];
+    let aktuell = resolve(start);
+    for (let i = 0; i < 200; i++) {
+        kandidaten.push({
+            pfad: aktuell,
+            hatKontext: istLesbarerOrdner(join(aktuell, "kontext")),
+            hatClaude: istLesbareDatei(join(aktuell, "CLAUDE.md")),
+        });
+        const eltern = dirname(aktuell);
+        if (eltern === aktuell)
+            break;
+        aktuell = eltern;
+    }
+    return arbeitsplatzAus(kandidaten);
+}
+/**
+ * Eine der verwalteten Dateien lesen -- fehlend wird zu `inhalt: null`,
+ * NICHT zu einem Fehler (ein frisch geklonter Ordner hat oft noch keine).
+ */
+export function leseEineDatei(ordner, pfad) {
+    const ort = join(ordner, ...pfad.split("/"));
+    try {
+        if (!existsSync(ort))
+            return { ok: true, inhalt: null };
+        if (!statSync(ort).isFile()) {
+            return {
+                ok: false,
+                meldung: `„${pfad}" existiert, ist aber keine Datei -- ich fasse das nicht an. Bitte pruefen.`,
+            };
+        }
+        return { ok: true, inhalt: readFileSync(ort, "utf8") };
+    }
+    catch (fehler) {
+        return {
+            ok: false,
+            meldung: `Ich komme an „${pfad}" nicht heran: ${fehler instanceof Error ? fehler.message : String(fehler)}. ` +
+                "Das liegt an diesem Rechner, nicht am Server -- Rechte pruefen.",
+        };
+    }
+}
+/**
+ * Den lokalen Merkzettel lesen. Unlesbar oder nicht vorhanden -> leeres
+ * Objekt, GENAU wie `leseMerkzettel(null)` -- der sichere Fall aus §7b: "wer
+ * nichts weiss, loescht nichts". Eine unlesbare Datei fuehrt also zur
+ * Sicherung vor dem Ueberschreiben, nie zum stillen Verlust.
+ */
+export function leseMerkzettelDatei(ordner) {
+    try {
+        const ort = join(ordner, MERKZETTEL_PFAD);
+        const roh = existsSync(ort) ? readFileSync(ort, "utf8") : null;
+        return leseMerkzettel(roh);
+    }
+    catch {
+        return leseMerkzettel(null);
+    }
+}
+/** Den Merkzettel schreiben -- MIT dem Stand, der zum ausgelieferten Inhalt passt. */
+export function schreibeMerkzettelDatei(ordner, m) {
+    try {
+        const ort = join(ordner, MERKZETTEL_PFAD);
+        writeFileSync(ort, schreibeMerkzettel(m), "utf8");
+        return { ok: true };
+    }
+    catch (fehler) {
+        return {
+            ok: false,
+            meldung: `Der Merkzettel liess sich nicht schreiben: ${fehler instanceof Error ? fehler.message : String(fehler)}. Das liegt an diesem Rechner, nicht am Server -- Platz und Rechte pruefen.`,
+        };
+    }
+}
+/**
+ * Der naechste NICHT belegte Sicherungspfad -- reine Rechnung, kein
+ * Dateisystem. `istBelegt(pfad)` sagt, ob dieser Pfad schon existiert (der
+ * Aufrufer entscheidet, WIE das geprueft wird); diese Funktion zaehlt vom
+ * Basisnamen aus hoch, bis eine freie Stelle gefunden ist.
+ *
+ * 🔴 **Ruling T8-2 (Review-Fund 1, Fix-Runde 1).** Vorher gab `sichereDatei`
+ * bei einem belegten Ziel `{ uebersprungen: true }` zurueck und schrieb dabei
+ * GAR NICHTS -- eine zweite Aenderung am selben Tag verschwand beim
+ * anschliessenden Ueberschreiben spurlos, waehrend die Ausgabe im Befehl
+ * "gesichert" behauptete. **Diese Funktion darf deshalb NIE einen belegten
+ * Pfad als Endergebnis zurueckgeben und NIE einen Pfad, der schon existiert,
+ * unkommentiert ueberschreiben lassen** -- sie liefert IMMER einen Pfad, der
+ * (laut `istBelegt`) frei ist.
+ *
+ * ⚠️ **Die erste Sicherung eines Tages -- der Basisname -- bleibt fuer immer
+ * unangetastet.** Das ist US-7 woertlich: "Laeuft der Befehl am selben Tag
+ * ein zweites Mal, wird die erste Sicherung NICHT ueberschrieben." Wer diese
+ * Funktion vereinfacht ("dann eben doch den Basisnamen nehmen, wenn `nummer`
+ * gross wird") loescht genau die Sicherung, die US-7 ausdruecklich schuetzt.
+ * Eine dritte, vierte, ... Aenderung bekommt stattdessen einen weiteren,
+ * eigenen Namen daneben -- nie einen schon vergebenen.
+ */
+export function naechstesFreiesSicherungsziel(basisZielRel, istBelegt) {
+    if (!istBelegt(basisZielRel))
+        return basisZielRel;
+    for (let nummer = 2; nummer <= 1000; nummer++) {
+        const kandidat = nummeriertesZiel(basisZielRel, nummer);
+        if (!istBelegt(kandidat))
+            return kandidat;
+    }
+    /*
+      Praktisch unerreichbar (1000 Sicherungen derselben Datei am selben Tag).
+      Diese reine Funktion wirft nicht -- sie liefert den letzten geprueften
+      Namen, und der Aufrufer (`sichereDatei`) trifft beim tatsaechlichen
+      Schreiben erneut auf `existsSync` und meldet dort einen echten Fehler,
+      statt dass eine reine Rechnung selbst eine Ausnahme auslöst.
+    */
+    return nummeriertesZiel(basisZielRel, 1000);
+}
+/**
+ * `kontext/vorher-2026-08-21/firma.md` + 2 -> `.../firma-2.md`.
+ *
+ * Nur der DATEINAME bekommt die Nummer, nicht der Ordner -- alle
+ * verwalteten Dateien landen weiter FLACH im selben `vorher-<datum>/`
+ * (unveraendert gegenueber `sicherungsZiel`).
+ */
+function nummeriertesZiel(basisZielRel, nummer) {
+    const teile = basisZielRel.split("/");
+    const dateiname = teile.pop() ?? "";
+    const punkt = dateiname.lastIndexOf(".");
+    const name = punkt === -1 ? dateiname : dateiname.slice(0, punkt);
+    const endung = punkt === -1 ? "" : dateiname.slice(punkt);
+    return [...teile, `${name}-${nummer}${endung}`].join("/");
+}
+/**
+ * Die lokale Fassung von `pfad` nach `kontext/vorher-<datum>/` sichern --
+ * FLACH, mit dem Basisnamen (`sicherungsZiel`), oder -- ist der schon belegt
+ * -- unter einem durchnummerierten Namen DANEBEN (`naechstesFreiesSicherungsziel`,
+ * Ruling T8-2).
+ *
+ * 🔴 **Es wird NIE uebersprungen und NIE ueberschrieben.** Beides waere eine
+ * stille Datenvernichtung: Ueberspringen ohne Kopie loescht die zweite
+ * Aenderung eines Tages beim anschliessenden Ueberschreiben der Arbeitsdatei;
+ * Ueberschreiben der ersten Sicherung verstoesst woertlich gegen US-7.
+ * `nebenVorhandener: true` im Ergebnis sagt dem Aufrufer, dass HEUTE schon
+ * eine andere Sicherung derselben Datei existiert -- er muss das in der
+ * Ausgabe unterscheiden (§8: kein Fehlerfall traegt den Namen eines
+ * Erfolgsfalls, und hier sind es zwei verschiedene ECHTE Erfolgsfaelle).
+ */
+export function sichereDatei(ordner, pfad, inhalt, datum) {
+    const basisZielRel = sicherungsZiel(datum, pfad);
+    const istBelegt = (zielRel) => existsSync(join(ordner, ...zielRel.split("/")));
+    const zielRel = naechstesFreiesSicherungsziel(basisZielRel, istBelegt);
+    const ort = join(ordner, ...zielRel.split("/"));
+    try {
+        mkdirSync(dirname(ort), { recursive: true });
+        writeFileSync(ort, inhalt, "utf8");
+        return { ok: true, ziel: zielRel, nebenVorhandener: zielRel !== basisZielRel };
+    }
+    catch (fehler) {
+        return {
+            ok: false,
+            meldung: `Sichern von „${pfad}" ist fehlgeschlagen: ${fehler instanceof Error ? fehler.message : String(fehler)}. Das liegt an diesem Rechner, nicht am Server -- Platz und Rechte pruefen.`,
+        };
+    }
+}
+/**
+ * Eine der verwalteten Dateien schreiben.
+ *
+ * 🔴 **Positivliste, keine Verbotsliste** (Auflage aus dem Brief): `pfad` muss
+ * WOERTLICH einer der Eintraege aus `VERWALTETE_DATEIEN` sein, sonst wird
+ * NICHTS geschrieben. Diese Funktion bekommt `pfad` im echten Ablauf immer aus
+ * der eigenen Iteration ueber `VERWALTETE_DATEIEN` (nie roh aus der Server-
+ * Antwort) -- die Pruefung hier ist trotzdem ausdruecklich verlangt und bleibt
+ * als zweites Netz stehen, falls sich der Aufrufer einmal aendert.
+ *
+ * ⚠️ `istUnsichererPfad` zusaetzlich, aus demselben Grund wie in
+ * `dateienSchreiben` (`arbeitsplatz-dateien.ts`): Ein Pfad kommt letztlich aus
+ * einer Server-Antwort, und eine Pruefung, die nur dort gilt, wo man sie
+ * gerade braucht, ist keine Pruefung dieser Funktion.
+ */
+export function schreibeVerwalteteDatei(ordner, pfad, inhalt) {
+    if (!VERWALTETE_DATEIEN.includes(pfad)) {
+        return { ok: false, meldung: `„${pfad}" ist keine verwaltete Datei -- wird nicht geschrieben. Bitte melden.` };
+    }
+    if (istUnsichererPfad(pfad)) {
+        return { ok: false, meldung: `„${pfad}" ist kein sicherer Pfad -- wird nicht geschrieben. Bitte melden.` };
+    }
+    const ort = join(ordner, ...pfad.split("/"));
+    try {
+        mkdirSync(dirname(ort), { recursive: true });
+        writeFileSync(ort, inhalt, "utf8");
+        return { ok: true };
+    }
+    catch (fehler) {
+        return {
+            ok: false,
+            meldung: `Schreiben von „${pfad}" ist fehlgeschlagen: ${fehler instanceof Error ? fehler.message : String(fehler)}. Das liegt an diesem Rechner, nicht am Server -- Platz und Rechte pruefen.`,
+        };
+    }
+}