hmgr 0.0.2 → 0.0.3

package/README.md

@@ -26,34 +26,5 @@ npm run build
 
 ## Kommandos
 
-```
-source add <url|pfad>   Quelle hinzufügen (URL wird geklont, Pfad bleibt Arbeitskopie)
-source list             Quellen zeigen
-dir add <pfad>          Arbeitsverzeichnis merken und an seinen Zeiger binden
-dir forget <pfad>       Arbeitsverzeichnis und Bindung vergessen, Links bleiben
-dir list                Arbeitsverzeichnisse mit ihrer Bindung zeigen
-link <skill>            Skill in ein Ziel verlinken
-unlink <skill>          Link entfernen
-adopt [name]            Fremde Links im Ziel durch eigene hmgr-Links ersetzen
-plugin add <name>       Plugin in ein Ziel legen (installieren oder Skills verlinken)
-plugin remove <name>    Plugin aus einem Ziel entfernen
-plugin list             Plugins der Marketplaces aller Quellen
-sync [pfad]             Ziel auf den Stand seines Zeigers bringen
-update                  Alle Checkouts aktualisieren
-status                  Ist-Zustand der Ziele
-```
-
-Optionen:
-
-```
---harness <name>        claude-code, hermes oder agents, Standard claude-code
---ort home|dir:<pfad>|profil:<name>   Standard home
---quelle <teilstring>   Quelle bei mehrdeutigem Skill-Namen
---version <spanne>      Versionseinschränkung nach Composer-Regeln, nur mit Zeiger
---composer <pfad>       composer.json wählen, wenn mehrere in Frage kommen
---local                 Link nur ins Ziel legen, nicht in den Zeiger
---ersetzen              fremden Eintrag am Ziel ersetzen
---probelauf             bei adopt nur melden, nichts schreiben
-```
-
-`hmgr help` zeigt dieselbe Übersicht.
+`hmgr --help` zeigt die Kommandos, `hmgr help <kommando>` Schalter, Beispiele
+und Zusammenhänge.

package/dist/cli/hilfe.js

@@ -0,0 +1,254 @@
+// Hilfetexte der CLI. Nur Zeichenketten, keine Ausgabe: die macht main.ts (Terminal-I/O).
+/** Ebene 1: Orientierung, je Kommando ein Einzeiler, Verweis auf die Kommando-Hilfe. */
+export const HILFE = `hmgr verlinkt Skills aus Git-Quellen in die Verzeichnisse, aus denen ein Harness sie lädt:
+claude-code, hermes oder agents. Welche Skills und Plugins zu einem Arbeitsverzeichnis gehören,
+steht in seinem Zeiger, dem extra-Abschnitt einer composer.json.
+
+Arbeitszyklus: Skill in seiner Quelle ändern, committen und pushen, dann hmgr update. Ein frisch
+geklontes Vorhaben holt seinen Stand mit hmgr sync.
+
+hmgr <kommando> [schalter]
+
+  source add <url|pfad>   Quelle hinzufügen (URL wird geklont, Pfad bleibt Arbeitskopie)
+  source list             Quellen zeigen
+  dir add <pfad>          Arbeitsverzeichnis merken und an seinen Zeiger binden
+  dir forget <pfad>       Arbeitsverzeichnis und Bindung vergessen, Links bleiben
+  dir list                Arbeitsverzeichnisse mit ihrer Bindung zeigen
+  link <skill>            Skill in ein Ziel verlinken
+  unlink <skill>          Link entfernen
+  adopt [name]            Fremde Links im Ziel durch eigene hmgr-Links ersetzen
+  plugin add <name>       Plugin in ein Ziel legen (installieren oder Skills verlinken)
+  plugin remove <name>    Plugin aus einem Ziel entfernen
+  plugin list             Plugins der Marketplaces aller Quellen
+  sync [pfad]             Ziel auf den Stand seines Zeigers bringen
+  update                  Alle Checkouts aktualisieren
+  status                  Ist-Zustand der Ziele
+
+hmgr help <kommando> zeigt Schalter, Beispiele und Zusammenhänge.`;
+const SOURCE = `hmgr source add <url|pfad>
+hmgr source list
+
+Eine Quelle ist ein Git-Repo mit Skills. source add prüft, ob sie erreichbar ist, liest ihre Skills
+und ihren Marketplace und merkt sie unter ~/.hmgr. Erst danach kennt hmgr die Skill-Namen, mit
+denen link und plugin add arbeiten. Eine URL wird geklont, ein Pfad bleibt die Arbeitskopie, die
+dort schon liegt, und wird von hmgr nicht verändert.
+
+Schalter: keine.
+
+Beispiele:
+  hmgr source add https://github.com/tim/skills.git
+  hmgr source add ~/.skills/tim-skills
+  hmgr source list
+
+Häufige Fälle:
+  „Skill … liegt in keiner Quelle": die Quelle fehlt, erst source add, dann link.
+  Neue Commits einer bekannten Quelle holt hmgr update, nicht source add.
+
+Siehe auch: hmgr help link, hmgr help plugin, hmgr help update`;
+const DIR = `hmgr dir add <pfad> [--composer <pfad>]
+hmgr dir forget <pfad>
+hmgr dir list
+
+Ein Arbeitsverzeichnis ist ein Verzeichnis, in dem ein Harness gestartet wird. dir add merkt es und
+bindet es an seinen Zeiger, also an die composer.json, in deren extra-Abschnitt Quellen, Skills und
+Plugins des Vorhabens stehen. Ohne Zeiger bleibt das Verzeichnis gemerkt und jeder Link dort lokal
+(E26). dir forget löst Bindung und Eintrag, die gelegten Links bleiben liegen.
+
+Schalter:
+  --composer <pfad>   composer.json wählen, wenn unter dem Verzeichnis mehrere in Frage kommen
+
+Beispiele:
+  hmgr dir add ~/Code/site
+  hmgr dir add ~/Code/site --composer ~/Code/site/app/composer.json
+  hmgr dir list
+
+Häufige Fälle:
+  „Mehrere composer.json unter …": eine mit --composer nennen, hmgr rät nicht.
+  link --ort dir:<pfad> merkt das Verzeichnis von selbst. dir add braucht es vorher nur, wenn die
+  composer.json mehrdeutig ist.
+
+Siehe auch: hmgr help link, hmgr help sync`;
+const LINK = `hmgr link <skill> [schalter]
+
+Legt im Ziel einen Symlink auf den Skill an, der aus einer bekannten Quelle stammt, und trägt ihn
+in den Zeiger des Ziels ein, damit hmgr sync ihn anderswo reproduzieren kann. Einen Zeiger gibt es
+nur für ein Arbeitsverzeichnis mit composer.json, an Home und Profil bleibt jeder Link lokal.
+
+Schalter:
+  --harness <name>    claude-code, hermes oder agents, Standard claude-code
+  --ort <ort>         home, dir:<pfad> oder profil:<name>, Standard home. profil kennt nur hermes
+  --quelle <teil>     Teilstring der Quelle, wenn der Skill-Name in mehreren Quellen vorkommt
+  --version <spanne>  Versionseinschränkung nach Composer-Regeln (etwa ^1.2) oder ein Tag- oder
+                      Branchname. Nur mit Zeiger, also dir:<pfad> ohne --local (E33)
+  --composer <pfad>   composer.json des Arbeitsverzeichnisses, wenn mehrere in Frage kommen
+  --local             Link nur ins Ziel legen, nicht in den Zeiger
+  --ersetzen          einen fremden Eintrag gleichen Namens am Ziel ersetzen
+
+Beispiele:
+  hmgr link netzwerk
+  hmgr link netzwerk --harness hermes --ort profil:researcher
+  hmgr link tq-schema --ort dir:. --version ^2.0
+
+Häufige Fälle:
+  „liegt in mehreren Quellen": mit --quelle <teilstring der URL oder des Pfads> entscheiden.
+  „liegt bereits ein fremder Eintrag": --ersetzen setzen oder vorher hmgr adopt <name>.
+  „gibt es keinen Zeiger": --version braucht ein Arbeitsverzeichnis mit composer.json und kein
+  --local. Ohne Zeiger den Link ohne --version legen.
+
+Siehe auch: hmgr help unlink, hmgr help sync, hmgr help adopt`;
+const UNLINK = `hmgr unlink <skill> [schalter]
+
+Entfernt den Link aus dem Ziel und, wenn das Ziel an einen Zeiger gebunden ist, den Skill aus dem
+Zeiger. Der Checkout unter ~/.hmgr bleibt liegen, Links anderer Ziele bleiben unberührt.
+
+Schalter:
+  --harness <name>    claude-code, hermes oder agents, Standard claude-code
+  --ort <ort>         home, dir:<pfad> oder profil:<name>, Standard home. profil kennt nur hermes
+  --composer <pfad>   composer.json des Arbeitsverzeichnisses, wenn mehrere in Frage kommen
+  --local             nur den Link entfernen, den Eintrag im Zeiger stehen lassen
+
+Beispiele:
+  hmgr unlink netzwerk
+  hmgr unlink netzwerk --ort dir:. --local
+
+Häufige Fälle:
+  Bleibt der Skill im Zeiger stehen, legt hmgr sync ihn wieder an. Ohne --local räumt unlink
+  beides ab.
+
+Siehe auch: hmgr help link, hmgr help sync`;
+const ADOPT = `hmgr adopt [name] [schalter]
+
+Ersetzt fremde Symlinks im Ziel durch eigene hmgr-Links: hmgr liest, aus welcher Git-Arbeitskopie
+ein Link stammt, nimmt deren remote.origin.url als Quelle, legt einen Checkout am selben Branch an
+und verlinkt den Skill daraus. Ohne Namen laufen alle fremden Einträge des Ziels durch, mit Namen
+nur dieser eine. Was sich nicht auflösen lässt, bleibt liegen und wird mit Grund gemeldet.
+
+Schalter:
+  --harness <name>    claude-code, hermes oder agents, Standard claude-code
+  --ort <ort>         home, dir:<pfad> oder profil:<name>, Standard home. profil kennt nur hermes
+  --composer <pfad>   composer.json des Arbeitsverzeichnisses, wenn mehrere in Frage kommen
+  --local             Übernahme nicht in den Zeiger schreiben
+  --probelauf         nur melden, nichts schreiben
+
+Beispiele:
+  hmgr adopt --probelauf
+  hmgr adopt netzwerk --ort dir:.
+
+Häufige Fälle:
+  „kein Symlink": der Eintrag ist ein echtes Verzeichnis, hmgr fasst ihn nicht an.
+  „liegt in keiner Git-Arbeitskopie" oder „ohne remote.origin.url": die Quelle ist nicht
+  bestimmbar. Mit hmgr source add <url> eine Quelle nennen und mit hmgr link --ersetzen verlinken.
+  „ohne Branch (detached HEAD)": in der Arbeitskopie einen Branch auschecken, dann erneut adopt.
+  „Pfad ist in der Quelle kein Skill": im Repo liegt an der Stelle keine SKILL.md.
+
+Siehe auch: hmgr help link, hmgr help status`;
+const PLUGIN = `hmgr plugin add <name> [schalter]
+hmgr plugin remove <name> [schalter]
+hmgr plugin list
+
+Ein Plugin ist ein Bündel aus einem Marketplace, also aus einer Quelle mit
+.claude-plugin/marketplace.json. Hat der Harness die Plugin-Fähigkeit (claude-code), lässt hmgr das
+Plugin von dessen CLI installieren, sonst verlinkt es die flache Skill-Liste des Plugins samt
+seinen Abhängigkeiten. In den Zeiger kommt das Plugin, nicht seine Einzelskills. plugin list zeigt
+die Marketplaces aller bekannten Quellen mit ihren Plugins.
+
+Schalter (add und remove):
+  --harness <name>    claude-code, hermes oder agents, Standard claude-code
+  --ort <ort>         home, dir:<pfad> oder profil:<name>, Standard home. profil kennt nur hermes
+  --composer <pfad>   composer.json des Arbeitsverzeichnisses, wenn mehrere in Frage kommen
+  --local             Plugin nicht in den Zeiger schreiben
+  --quelle <teil>     nur bei add: Quelle eingrenzen, wenn der Name in mehreren Marketplaces steht
+
+Beispiele:
+  hmgr plugin list
+  hmgr plugin add superpowers --ort dir:.
+  hmgr plugin remove superpowers
+
+Häufige Fälle:
+  „Keine Quelle mit Marketplace": erst hmgr source add <url> der Quelle mit der marketplace.json.
+  „liegt in keinem Marketplace der bekannten Quellen": Namen mit hmgr plugin list prüfen.
+  „liegt in mehreren Marketplaces": mit --quelle <teilstring> entscheiden.
+  „braucht …, das im selben Marketplace nicht steht": die Abhängigkeit fehlt im Marketplace, das
+  kann nur die Quelle beheben.
+
+Siehe auch: hmgr help source, hmgr help sync`;
+const SYNC = `hmgr sync [pfad]
+
+Bringt ein Arbeitsverzeichnis auf den Stand seines Zeigers: fehlende Quellen übernehmen, fehlende
+Links legen, Links auf einen anderen Ref umlegen, Plugins herstellen. Ohne Pfad gilt das aktuelle
+Verzeichnis. Das ist der Befehl nach einem frischen Clone eines Vorhabens und nach jeder Änderung
+am Zeiger. Eigene Links, die im Zeiger fehlen, werden als abweichend gemeldet und nicht entfernt,
+fremde Einträge bleiben unberührt.
+
+Schalter: keine.
+
+Beispiele:
+  hmgr sync
+  hmgr sync ~/Code/site
+
+Häufige Fälle:
+  „Kein Zeiger unter …, nichts zu tun": im Verzeichnis liegt keine composer.json. Mit
+  hmgr dir add <pfad> --composer <pfad> eine nennen.
+  „steht nicht im Zeiger": den Link mit hmgr link <skill> --ort dir:<pfad> eintragen oder mit
+  hmgr unlink <skill> --ort dir:<pfad> --local entfernen.
+  „Kein Harness auf diesem Rechner": weder ~/.claude noch ~/.hermes noch ~/.agents ist angelegt.
+
+Siehe auch: hmgr help dir, hmgr help link, hmgr help update`;
+const UPDATE = `hmgr update
+
+Holt für jeden Checkout unter ~/.hmgr den neuesten Stand seines Refs und zieht bei Harnesses mit
+Plugin-Fähigkeit deren Plugins nach (E14). Die Links zeigen weiter auf dieselben Pfade und müssen
+nicht erneuert werden. Ein Checkout mit lokaler Änderung wird übersprungen und gemeldet (E15),
+damit nichts verloren geht. Lokale Quellen haben keinen Checkout und bleiben unberührt.
+
+So wird eine Änderung an einem Skill überall wirksam: in der Quelle committen und pushen, dann
+hmgr update.
+
+Schalter: keine.
+
+Beispiel:
+  hmgr update
+
+Häufige Fälle:
+  „übersprungen … lokale Änderung (E15)": im Checkout liegt eine Änderung, die durch einen Link
+  hindurch gemacht wurde. Dort committen und pushen, dann erneut hmgr update.
+  „Keine Checkouts": es gibt nur lokale Quellen oder noch keinen Link.
+
+Siehe auch: hmgr help sync, hmgr help status`;
+const STATUS = `hmgr status
+
+Liest den Ist-Zustand vom Dateisystem: je Ziel eines vorhandenen Harness die Einträge mit Quelle
+und Ref, davor die Versionseinschränkung, falls der Zeiger eine nennt. Fremde Einträge und Links
+ohne bekannte Quelle sind eigens gekennzeichnet, dazu kommen die Plugins des Ziels. Am Ende stehen
+die Harnesses, die auf diesem Rechner nicht liegen.
+
+Schalter: keine.
+
+Beispiel:
+  hmgr status
+
+Häufige Fälle:
+  „fremd": der Eintrag stammt nicht von hmgr. hmgr adopt <name> übernimmt ihn.
+  „Link ohne bekannte Quelle": der Link zeigt in einen hmgr-Checkout, dessen Quelle nicht mehr im
+  Zustand steht. Mit hmgr source add <url> die Quelle wieder eintragen.
+  „Nicht vorhanden": der Harness hat sein Verzeichnis auf diesem Rechner nicht angelegt, hmgr
+  überspringt seine Ziele.
+
+Siehe auch: hmgr help adopt, hmgr help sync`;
+/** Ebene 2, je Kommandofamilie ein Text. Unterkommandos teilen sich die Hilfe ihrer Familie. */
+const THEMEN = new Map([
+    ['source', SOURCE],
+    ['dir', DIR],
+    ['link', LINK],
+    ['unlink', UNLINK],
+    ['adopt', ADOPT],
+    ['plugin', PLUGIN],
+    ['sync', SYNC],
+    ['update', UPDATE],
+    ['status', STATUS],
+    ['help', HILFE],
+]);
+/** Hilfetext zu einem Kommando, undefined für ein unbekanntes Thema. */
+export function hilfeText(thema) {
+    return THEMEN.get(thema);
+}

package/dist/cli/main.js

@@ -15,6 +15,7 @@ import { GitQuellen } from "../adapter/git.js";
 import { quelleAlsText, quelleAusText } from "../adapter/quelle-text.js";
 import { TerminalRueckfrage } from "../adapter/terminal.js";
 import { ZustandJson } from "../adapter/zustand-json.js";
+import { HILFE, hilfeText } from "./hilfe.js";
 export function umgebungLesen(env = process.env) {
     const home = env.HOME ?? homedir();
     return { home, hmgrHome: env.HMGR_HOME ?? path.join(home, '.hmgr') };
@@ -35,9 +36,9 @@ export function bauen(umgebung, optionen = {}) {
     };
     return { anwendungsfaelle: new Anwendungsfaelle(ports), ports };
 }
-/** Schalter ohne Wert. Alles andere braucht einen. */
-const FLAGGEN = new Set(['ersetzen', 'local', 'lokal', 'probelauf']);
-function schalterLesen(args) {
+/** Schalter ohne Wert. Alles andere braucht einen. `help` steht hier, damit --help nie greift. */
+const FLAGGEN = new Set(['ersetzen', 'local', 'lokal', 'probelauf', 'help']);
+function schalterLesen(args, kommando) {
     const rest = [];
     const werte = new Map();
     const flaggen = new Set();
@@ -54,7 +55,8 @@ function schalterLesen(args) {
         }
         const wert = args[++i];
         if (wert === undefined)
-            throw new Error(`Schalter --${name} braucht einen Wert`);
+            throw new Error(`Schalter --${name} braucht einen Wert, etwa --${name} <wert>. ` +
+                `${kommando === undefined ? 'hmgr --help' : `hmgr help ${kommando}`} zeigt die Schalter.`);
         werte.set(name, wert);
     }
     return { rest, werte, flaggen };
@@ -69,31 +71,6 @@ function ortLesen(text) {
         return { art: 'profil', name: roh.slice(7) };
     throw new Error(`Unbekannter Ort „${roh}", erwartet home, dir:<pfad> oder profil:<name>`);
 }
-const HILFE = `hmgr <kommando>
-
-  source add <url|pfad>   Quelle hinzufügen (URL wird geklont, Pfad bleibt Arbeitskopie)
-  source list             Quellen zeigen
-  dir add <pfad>          Arbeitsverzeichnis merken und an seinen Zeiger binden
-  dir forget <pfad>       Arbeitsverzeichnis und Bindung vergessen, Links bleiben
-  dir list                Arbeitsverzeichnisse mit ihrer Bindung zeigen
-  link <skill>            Skill in ein Ziel verlinken
-  unlink <skill>          Link entfernen
-  adopt [name]            Fremde Links im Ziel durch eigene hmgr-Links ersetzen
-  plugin add <name>       Plugin in ein Ziel legen (installieren oder Skills verlinken)
-  plugin remove <name>    Plugin aus einem Ziel entfernen
-  plugin list             Plugins der Marketplaces aller Quellen
-  sync [pfad]             Ziel auf den Stand seines Zeigers bringen
-  update                  Alle Checkouts aktualisieren
-  status                  Ist-Zustand der Ziele
-
-  --harness <name>        claude-code, hermes oder agents, Standard claude-code
-  --ort home|dir:<pfad>|profil:<name>   Standard home
-  --quelle <teilstring>   Quelle bei mehrdeutigem Skill-Namen
-  --version <spanne>      Versionseinschränkung nach Composer-Regeln, nur mit Zeiger (E33)
-  --composer <pfad>       composer.json wählen, wenn mehrere in Frage kommen
-  --local                 Link nur ins Ziel legen, nicht in den Zeiger
-  --ersetzen              fremden Eintrag am Ziel ersetzen
-  --probelauf             bei adopt nur melden, nichts schreiben`;
 /** Klartext für den Grund, aus dem ein fremder Eintrag liegen bleibt (B12). */
 const UEBERNAHME_GRUND = {
     'kein-link': 'kein Symlink',
@@ -105,16 +82,36 @@ const UEBERNAHME_GRUND = {
 export async function ausfuehren(argv, umgebung, optionen = {}) {
     const { anwendungsfaelle, ports } = bauen(umgebung, optionen);
     const kommando = argv[0];
-    if (kommando === undefined || kommando === 'help' || kommando === '--help') {
+    // Hilfe zuerst: --help ist überall eine Flagge, damit kein Kommando sie als Wert liest.
+    if (kommando === undefined) {
         console.log(HILFE);
-        return kommando === undefined ? 1 : 0;
+        return 1;
+    }
+    if (kommando === 'help' || kommando === '--help' || kommando === '-h') {
+        const thema = argv[1];
+        if (thema === undefined || thema.startsWith('-')) {
+            console.log(HILFE);
+            return 0;
+        }
+        const text = hilfeText(thema);
+        if (text === undefined)
+            throw new Error(`Unbekanntes Hilfe-Thema „${thema}". hmgr --help zeigt alle Kommandos.`);
+        console.log(text);
+        return 0;
+    }
+    if (argv.slice(1).includes('--help')) {
+        const text = hilfeText(kommando);
+        if (text === undefined)
+            throw new Error(`Unbekanntes Kommando „${kommando}". hmgr --help zeigt alle Kommandos.`);
+        console.log(text);
+        return 0;
     }
     if (kommando === 'source') {
         const unterkommando = argv[1];
         if (unterkommando === 'add') {
             const text = argv[2];
             if (text === undefined)
-                throw new Error('source add braucht eine URL oder einen Pfad');
+                throw new Error('source add braucht eine URL oder einen Pfad, etwa hmgr source add https://example.com/skills.git');
             const quelle = quelleAusText(text);
             const { skills, marketplace } = await anwendungsfaelle.quelleHinzufuegen(quelle);
             console.log(`Quelle ${quelleAlsText(quelle)} (${quelle.art}), ${skills.length} Skills:`);
@@ -137,15 +134,15 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
                 console.log(`${quelle.art}  ${quelleAlsText(quelle)}`);
             return 0;
         }
-        throw new Error('source add <url|pfad> oder source list');
+        throw new Error(`${unterkommando === undefined ? 'source braucht ein Unterkommando' : `Unbekanntes Unterkommando „${unterkommando}" für source`}: source add <url|pfad> oder source list. hmgr help source zeigt Beispiele.`);
     }
     if (kommando === 'dir') {
-        const { rest, werte } = schalterLesen(argv.slice(1));
+        const { rest, werte } = schalterLesen(argv.slice(1), 'dir');
         const unterkommando = rest[0];
         if (unterkommando === 'add') {
             const pfad = rest[1];
             if (pfad === undefined)
-                throw new Error('dir add braucht einen Pfad');
+                throw new Error('dir add braucht einen Pfad, etwa hmgr dir add .');
             const composer = werte.get('composer');
             const ergebnis = composer === undefined
                 ? await anwendungsfaelle.arbeitsverzeichnisHinzufuegen(pfad)
@@ -160,7 +157,7 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
         if (unterkommando === 'forget') {
             const pfad = rest[1];
             if (pfad === undefined)
-                throw new Error('dir forget braucht einen Pfad');
+                throw new Error('dir forget braucht einen Pfad. hmgr dir list zeigt die gemerkten Arbeitsverzeichnisse.');
             await anwendungsfaelle.arbeitsverzeichnisVergessen(pfad);
             console.log(`Arbeitsverzeichnis ${path.resolve(pfad)} vergessen, die Links bleiben liegen.`);
             return 0;
@@ -175,13 +172,14 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
             }
             return 0;
         }
-        throw new Error('dir add <pfad>, dir forget <pfad> oder dir list');
+        throw new Error(`${unterkommando === undefined ? 'dir braucht ein Unterkommando' : `Unbekanntes Unterkommando „${unterkommando}" für dir`}: dir add <pfad>, dir forget <pfad> oder dir list. hmgr help dir zeigt Beispiele.`);
     }
     if (kommando === 'link' || kommando === 'unlink') {
-        const { rest, werte, flaggen } = schalterLesen(argv.slice(1));
+        const { rest, werte, flaggen } = schalterLesen(argv.slice(1), kommando);
         const skill = rest[0];
         if (skill === undefined)
-            throw new Error(`${kommando} braucht einen Skill-Namen`);
+            throw new Error(`${kommando} braucht einen Skill-Namen, etwa hmgr ${kommando} <skill>. ` +
+                'hmgr status zeigt die verlinkten Skills, hmgr source add <url|pfad> die Skills einer Quelle.');
         const ziel = { harness: werte.get('harness') ?? 'claude-code', ort: ortLesen(werte.get('ort')) };
         const lokal = flaggen.has('local') || flaggen.has('lokal');
         if (ziel.ort.art === 'arbeitsverzeichnis') {
@@ -214,7 +212,7 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
         return 0;
     }
     if (kommando === 'adopt') {
-        const { rest, werte, flaggen } = schalterLesen(argv.slice(1));
+        const { rest, werte, flaggen } = schalterLesen(argv.slice(1), 'adopt');
         const ziel = { harness: werte.get('harness') ?? 'claude-code', ort: ortLesen(werte.get('ort')) };
         const probelauf = flaggen.has('probelauf');
         const name = rest[0];
@@ -253,7 +251,7 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
         return 0;
     }
     if (kommando === 'plugin') {
-        const { rest, werte, flaggen } = schalterLesen(argv.slice(1));
+        const { rest, werte, flaggen } = schalterLesen(argv.slice(1), 'plugin');
         const unterkommando = rest[0];
         if (unterkommando === 'list') {
             const marketplaces = await anwendungsfaelle.marketplaces();
@@ -272,10 +270,10 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
             return 0;
         }
         if (unterkommando !== 'add' && unterkommando !== 'remove')
-            throw new Error('plugin add <name>, plugin remove <name> oder plugin list');
+            throw new Error(`${unterkommando === undefined ? 'plugin braucht ein Unterkommando' : `Unbekanntes Unterkommando „${unterkommando}" für plugin`}: plugin add <name>, plugin remove <name> oder plugin list. hmgr help plugin zeigt Beispiele.`);
         const name = rest[1];
         if (name === undefined)
-            throw new Error(`plugin ${unterkommando} braucht einen Plugin-Namen`);
+            throw new Error(`plugin ${unterkommando} braucht einen Plugin-Namen. hmgr plugin list zeigt die Plugins der bekannten Quellen.`);
         const ziel = { harness: werte.get('harness') ?? 'claude-code', ort: ortLesen(werte.get('ort')) };
         const lokal = flaggen.has('local') || flaggen.has('lokal');
         if (ziel.ort.art === 'arbeitsverzeichnis') {
@@ -302,7 +300,7 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
         return 0;
     }
     if (kommando === 'sync') {
-        const { rest } = schalterLesen(argv.slice(1));
+        const { rest } = schalterLesen(argv.slice(1), 'sync');
         const ergebnis = await anwendungsfaelle.abgleich(rest[0]);
         if (ergebnis.zeigerPfad !== undefined)
             console.log(`Zeiger ${ergebnis.zeigerPfad}`);
@@ -360,7 +358,7 @@ export async function ausfuehren(argv, umgebung, optionen = {}) {
             console.log(`Nicht vorhanden: ${fehlend.join(', ')}`);
         return 0;
     }
-    throw new Error(`Unbekanntes Kommando „${kommando}"`);
+    throw new Error(`Unbekanntes Kommando „${kommando}". hmgr --help zeigt alle Kommandos.`);
 }
 function beschreibeOrt(ort) {
     if (ort.art === 'home')
@@ -382,13 +380,43 @@ function istModellFehler(fehler) {
         fehler instanceof PluginUnbekannt ||
         fehler instanceof AbhaengigkeitFehlt);
 }
+/**
+ * Der nächste Schritt zu einem Fehler aus dem Kern. Die Fehlertexte selbst bleiben, wie das Modell
+ * sie schreibt, die Handlungsanweisung gehört an die CLI, weil sie Kommandos nennt.
+ */
+function naechsterSchritt(fehler) {
+    if (fehler instanceof SkillMehrdeutig)
+        return `Quelle eingrenzen: hmgr link ${fehler.name} --quelle <teilstring einer der genannten Quellen>`;
+    if (fehler instanceof SkillUnbekannt)
+        return 'Erst die Quelle hinzufügen: hmgr source add <url|pfad>. hmgr source list zeigt die bekannten Quellen.';
+    if (fehler instanceof NameBelegt)
+        return `Entweder mit --ersetzen überschreiben oder den fremden Eintrag mit hmgr adopt ${fehler.skillName} übernehmen.`;
+    if (fehler instanceof PluginMehrdeutig)
+        return 'Quelle eingrenzen: --quelle <teilstring der URL oder des Pfads>. hmgr plugin list zeigt die Marketplaces.';
+    if (fehler instanceof PluginUnbekannt)
+        return 'hmgr plugin list zeigt die Plugins der bekannten Quellen. Fehlt der Marketplace, erst hmgr source add <url>.';
+    if (fehler instanceof AbhaengigkeitFehlt)
+        return 'Die Abhängigkeit steht in keinem Plugin desselben Marketplace, das kann nur die Quelle beheben.';
+    if (fehler instanceof KeinPassenderRef)
+        return 'hmgr update holt neue Tags der Quelle. Sonst einen vorhandenen Tag- oder Branchnamen als --version nennen.';
+    if (fehler instanceof HarnessNichtVorhanden)
+        return 'Der Harness legt sein Verzeichnis beim ersten Start an. hmgr status zeigt, welche Harnesses hier liegen.';
+    if (fehler instanceof OrtNichtUnterstuetzt)
+        return 'profil:<name> kennt nur hermes, claude-code und agents kennen home und dir:<pfad>.';
+    const text = fehler instanceof Error ? fehler.message : '';
+    if (text.startsWith('Unbekannter Harness'))
+        return 'Bekannt sind claude-code, hermes und agents.';
+    return undefined;
+}
 export async function main(argv, umgebung) {
     try {
         return await ausfuehren(argv, umgebung);
     }
     catch (fehler) {
         const text = fehler instanceof Error ? fehler.message : String(fehler);
-        console.error(istModellFehler(fehler) ? text : `Fehler: ${text}`);
+        const kopf = istModellFehler(fehler) ? text : `Fehler: ${text}`;
+        const schritt = naechsterSchritt(fehler);
+        console.error(schritt === undefined ? kopf : `${kopf}\n${schritt}`);
         return 1;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hmgr",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Harness Manager: Skills und Plugins für AI-Harnesses verwalten",
   "license": "MIT",
   "author": "Tim Kaufmann",