@codecell-germany/company-agent-wiki-skill 0.1.3 → 0.1.4

package/README.md

@@ -11,7 +11,7 @@
 `company-agent-wiki-skill` is an agent-first local company knowledge toolkit.
 It ships as a real CLI plus a shared agent skill payload, so an agent can set up a private company wiki, verify the index state, search knowledge, inspect metadata and headings first, and only then load full Markdown when needed.
 
-The shared install layout is meant to work across agent environments that understand the common `~/.agents` skill home, including Codex through its compatibility mirror and other skills.sh-style runtimes such as Claude Code or OpenClaw.
+The shared install layout is meant to work across agent environments that understand the common `~/.agents` skill home, including Codex through a compatibility shim and other skills.sh-style runtimes such as Claude Code or OpenClaw.
 
 The product surface is the public CLI:
 
@@ -46,6 +46,16 @@ The retrieval model is deliberately inspired by Anthropic's Agent Skills model w
 The difference is the retrieval layer.
 Here, front matter is not only stored in Markdown files, but also indexed and filterable through a local SQLite search layer.
 
+## Architecture visuals
+
+### Agentic knowledge ingestion
+
+![Agentic knowledge ingestion](https://cdn.codecell.de/codecell-intern/company-agent-wiki/data-ingestion.jpg)
+
+### Agent-first knowledge retrieval
+
+![Agent-first knowledge retrieval](https://cdn.codecell.de/codecell-intern/company-agent-wiki/data-retrieval.jpg)
+
 ## Installation
 
 ### 1. Install with one command
@@ -61,10 +71,11 @@ That installs:
 - the shared skill payload into `~/.agents/skills/company-agent-wiki-cli`
 - the shared runtime into `~/.agents/tools/company-agent-wiki-cli`
 - the shared CLI shim into `~/.agents/bin/company-agent-wiki-cli`
-- the skill payload into `~/.codex/skills/company-agent-wiki-cli`
-- the runtime into `~/.codex/tools/company-agent-wiki-cli`
 - the Codex compatibility shim into `~/.codex/bin/company-agent-wiki-cli`
 
+The skill payload intentionally exists only once under `~/.agents/skills`.
+Codex gets a CLI compatibility shim, but not a second duplicate skill payload.
+
 ### 2. Verify the CLI
 
 ```bash
@@ -205,6 +216,7 @@ status: draft
 tags:
   - projekt
   - alpha
+description: Klare Kurzbeschreibung für Agenten, bevor der Volltext geladen wird.
 summary: Roadmap und Entscheidungen für Projekt Alpha.
 project: alpha
 department: entwicklung
@@ -219,7 +231,7 @@ Recommended authoring order:
 
 1. Create the Markdown file inside `knowledge/canonical/` or another registered managed root.
 2. Use a filename that roughly describes the real content.
-3. Set front matter including `id`, `summary` and the routing fields that matter.
+3. Set front matter including `id`, `description`, `summary` and the routing fields that matter.
 4. If the content depends on external sources, document provenance, date and source type.
 5. Structure the file with clear `#`, `##` and `###` headings.
 6. Rebuild the index or use an `--auto-rebuild` retrieval path.

package/dist/index.js

@@ -7814,6 +7814,7 @@ type: process
 status: active
 tags:
   - example
+description: Short routing description for agents.
 ---
 \`\`\`
 `;
@@ -8439,6 +8440,8 @@ function normalizeStringArrayValue(value) {
 function buildDocumentMetadataView(row) {
   const frontmatter = JSON.parse(row.frontmatterJson);
   const tags = JSON.parse(row.tagsJson);
+  const description = normalizeStringValue(frontmatter.description) ?? normalizeStringValue(frontmatter.summary);
+  const summary = normalizeStringValue(frontmatter.summary) ?? description;
   return {
     docId: row.docId,
     title: row.title,
@@ -8447,7 +8450,8 @@ function buildDocumentMetadataView(row) {
     docType: row.docType ?? void 0,
     status: row.status ?? void 0,
     tags,
-    summary: normalizeStringValue(frontmatter.summary),
+    description,
+    summary,
     project: normalizeStringValue(frontmatter.project),
     department: normalizeStringValue(frontmatter.department),
     owners: normalizeStringArrayValue(frontmatter.owners),
@@ -12611,6 +12615,10 @@ function printMetadata(metadata) {
   }
   if (metadata.systems.length > 0) {
     process.stdout.write(`  systems: ${metadata.systems.join(", ")}
+`);
+  }
+  if (metadata.description) {
+    process.stdout.write(`  description: ${metadata.description}
 `);
   }
   if (metadata.summary) {

package/dist/installer.js

@@ -3570,6 +3570,7 @@ function installIntoHome(target, home, packageRoot, force = false) {
   writeShim(shimPath, runtimeScript);
   return {
     target,
+    mode: "full",
     home,
     binDir,
     runtimeDir,
@@ -3579,6 +3580,34 @@ function installIntoHome(target, home, packageRoot, force = false) {
     pathHint: (process.env.PATH || "").split(import_node_path.default.delimiter).includes(binDir) ? void 0 : `The shim exists, but ${binDir} is not in PATH. Use "${shimPath}" directly or add ${binDir} to PATH.`
   };
 }
+function installCompatibilityShim(target, home, runtimeHome, force = false) {
+  const runtimeDir = import_node_path.default.join(runtimeHome, "tools", SKILL_NAME);
+  const runtimeScript = import_node_path.default.join(runtimeDir, "dist", "index.js");
+  if (!import_node_fs2.default.existsSync(runtimeScript)) {
+    throw new Error(`Cannot create compatibility shim because runtime is missing: ${runtimeScript}`);
+  }
+  const binDir = import_node_path.default.join(home, "bin");
+  const shimPath = import_node_path.default.join(binDir, CLI_NAME);
+  const legacyRuntimeDir = import_node_path.default.join(home, "tools", SKILL_NAME);
+  const legacySkillDir = import_node_path.default.join(home, "skills", SKILL_NAME);
+  if (force) {
+    import_node_fs2.default.rmSync(legacyRuntimeDir, { recursive: true, force: true });
+    import_node_fs2.default.rmSync(legacySkillDir, { recursive: true, force: true });
+    import_node_fs2.default.rmSync(shimPath, { force: true });
+  }
+  ensureDir(binDir);
+  writeShim(shimPath, runtimeScript);
+  return {
+    target,
+    mode: "shim-only",
+    home,
+    binDir,
+    runtimeDir,
+    shimPath,
+    shimInPath: (process.env.PATH || "").split(import_node_path.default.delimiter).includes(binDir),
+    pathHint: (process.env.PATH || "").split(import_node_path.default.delimiter).includes(binDir) ? void 0 : `The shim exists, but ${binDir} is not in PATH. Use "${shimPath}" directly or add ${binDir} to PATH.`
+  };
+}
 function installIntoAgentHomes(options) {
   const packageRoot = resolvePackageRoot(__dirname);
   const agentsHome = options?.agentsHome || getDefaultAgentsHome();
@@ -3594,7 +3623,11 @@ function installIntoAgentHomes(options) {
   if (target === "codex" || target === "all") {
     const shouldSkipCodex = installs.some((entry) => entry.home === codexHome);
     if (!shouldSkipCodex) {
-      installs.push(installIntoHome("codex", codexHome, packageRoot, options?.force));
+      if (target === "codex") {
+        installs.push(installIntoHome("codex", codexHome, packageRoot, options?.force));
+      } else {
+        installs.push(installCompatibilityShim("codex", codexHome, agentsHome, options?.force));
+      }
     }
   }
   return {
@@ -3697,10 +3730,23 @@ program2.command("install").option("--agents-home <path>", "Target shared agents
     return;
   }
   for (const install of result.installs) {
-    process.stdout.write(`Installed ${install.target} target into ${install.home}
+    process.stdout.write(`Installed ${install.target} target (${install.mode}) into ${install.home}
 `);
     process.stdout.write(`CLI shim: ${install.shimPath}
 `);
+    if (install.mode === "full") {
+      if (install.skillDir) {
+        process.stdout.write(`Skill payload: ${install.skillDir}
+`);
+      }
+      if (install.runtimeDir) {
+        process.stdout.write(`Runtime: ${install.runtimeDir}
+`);
+      }
+    } else if (install.runtimeDir) {
+      process.stdout.write(`Runtime source: ${install.runtimeDir}
+`);
+    }
     if (install.pathHint) {
       process.stdout.write(`warning: ${install.pathHint}
 `);

package/knowledge/ARCHITECTURE.md

@@ -46,7 +46,7 @@ The index and manifest are derived artifacts and should stay ignored in the priv
 8. `search`, `route` and `read` either enforce a fresh index or can explicitly auto-rebuild when `--auto-rebuild` is set.
 9. Runtime commands may detect the current workspace automatically when the shell is already inside a private workspace.
 10. A global per-user workspace registry stores known workspace paths and a default workspace so other agents can resolve the knowledge location automatically on macOS, Windows and Linux.
-11. The installer now targets a shared `~/.agents` home as the primary skill/runtime location and also installs a Codex compatibility mirror under `~/.codex`.
+11. The installer now targets a shared `~/.agents` home as the primary skill/runtime location and adds a Codex compatibility shim under `~/.codex/bin`.
 12. `serve` exposes the same read-only data through a local web view and now distinguishes `missing`, `stale` and `ok` states with a rebuild action.
 
 ## Onboarding Model
@@ -86,6 +86,8 @@ Phase 1 now explicitly supports a two-step retrieval model:
 
 This keeps the agent loop lighter and encourages stronger filenames plus front matter without forcing a rigid folder taxonomy.
 
+The preferred front-matter contract now includes both `description` and `summary`, so agents can inspect a short routing description before deciding whether to load full Markdown content.
+
 ## Global Workspace Discovery
 
 Phase 1 now persists workspace discovery outside the private workspace itself:

package/knowledge/KNOWN_LIMITATIONS.md

@@ -30,4 +30,4 @@
 - The CLI can initialize a private Git remote URL, but it does not validate remote policy or access controls.
 - The package does not enforce OS-level filesystem permissions; the workspace owner must place the private workspace in a properly protected location.
 - The global workspace registry is only a discovery layer, not an access-control boundary. Any agent running as the same local user can read the registered workspace path.
-- The installer now targets a shared `~/.agents` home first and mirrors into `~/.codex` for compatibility, but it does not manage every agent product's own skill-indexing or refresh logic automatically.
+- The installer now targets a shared `~/.agents` home first and adds a Codex compatibility shim, but it does not manage every agent product's own skill-indexing or refresh logic automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codecell-germany/company-agent-wiki-skill",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Context is king: agent-first local company knowledge workspace with metadata-first retrieval, Markdown as truth, SQLite-indexed front matter, Git-aware verification, and a shared agent skill installer.",
   "private": false,
   "license": "MIT",

package/skills/company-agent-wiki-cli/SKILL.md

@@ -21,7 +21,7 @@ This package now targets a shared `~/.agents` home first so the same published p
 - The private workspace may be the current dedicated local folder; it just must not be the public skill/CLI repo.
 - The human should provide the workspace path at least once and, if desired, the private Git remote URL. After setup or manual registration, the CLI stores the workspace path in a global per-user registry so later agents can resolve it automatically.
 - Runtime discovery matters. Before relying on the CLI, verify which path is actually available.
-- The primary shared install target is `~/.agents`. Codex additionally gets a compatibility mirror under `~/.codex`.
+- The primary shared install target is `~/.agents`. Codex should only need the compatibility shim under `~/.codex/bin`, not a duplicate second skill payload.
 - The preferred one-command installer path is `npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force`. This only works after the npm package is really published.
 - If the binary is not already installed in PATH, use these fallbacks in this order:
 
@@ -157,6 +157,7 @@ status: draft
 tags:
   - projekt
   - alpha
+description: Klare Kurzbeschreibung für Agenten, bevor der Volltext geladen wird.
 summary: Roadmap und Entscheidungen für Projekt Alpha.
 project: alpha
 department: entwicklung
@@ -173,7 +174,7 @@ Empfohlener Ablauf:
 
 1. Datei unter `knowledge/canonical/` oder einem anderen registrierten Managed Root anlegen.
 2. Dateiname so wählen, dass er den Inhalt grob repräsentiert, etwa `projekt-alpha-roadmap.md`.
-3. Front Matter inklusive `id`, `summary` und passenden Routing-Feldern setzen.
+3. Front Matter inklusive `id`, `description`, `summary` und passenden Routing-Feldern setzen.
 4. Wenn der Inhalt auf externer Recherche basiert, Provenienz ergänzen:
    - Quellenstand oder Prüfdokumentation im Dokument
    - Datum der Prüfung
@@ -217,6 +218,7 @@ tags:
   - crm
   - partner
   - netzwerk
+description: Kurzbeschreibung der Beziehung und ihrer Relevanz für Agenten.
 summary: Rolle, Status und Relevanz des Partners im CodeCell-Netzwerk.
 department: vertrieb
 owners:

package/skills/company-agent-wiki-cli/references/authoring-workflow.md

@@ -34,6 +34,7 @@ status: draft
 tags:
   - projekt
   - alpha
+description: Klare Kurzbeschreibung für Agenten, bevor der Volltext geladen wird.
 summary: Roadmap und Entscheidungen für Projekt Alpha.
 project: alpha
 department: entwicklung
@@ -52,6 +53,7 @@ systems:
 - `type`: z. B. `project`, `process`, `policy`, `guide`, `note`
 - `status`: z. B. `draft`, `active`, `archived`
 - `tags`: freie Schlagwörter
+- `description`: kurze Pflichtbeschreibung für Agenten-Routing und Metadata-First-Reads
 - `summary`: kurze 1-Zeilen-Zusammenfassung für Agenten-Routing
 - `project`: Projektkennung oder Projektslug
 - `department`: Abteilung oder Verantwortungsbereich
@@ -65,6 +67,7 @@ Wenn Wissen aus Webrecherche, Nutzerangaben, E-Mails oder anderen externen Quell
 
 Empfohlen:
 
+- `description` im Front Matter als sofort sichtbare Kurzbeschreibung
 - `summary` im Front Matter für die Kurzbeschreibung
 - im Dokument ein Abschnitt `## Quellenstand`
 - Prüfdaten oder Prüfdatum
@@ -92,7 +95,7 @@ Beispiel:
 
 1. Dokument im passenden Managed Root anlegen, meist unter `knowledge/canonical/`.
 2. Dateinamen so wählen, dass er `title` und Inhalt grob repräsentiert.
-3. Front Matter setzen, idealerweise inklusive `id`.
+3. Front Matter setzen, idealerweise inklusive `id`, `description` und `summary`.
 4. Bei externem Wissen Provenienz ergänzen.
 5. Abschnitte schreiben.
 6. `company-agent-wiki-cli index rebuild --workspace /absolute/path --json` ausführen.
@@ -147,6 +150,7 @@ tags:
   - crm
   - partner
   - netzwerk
+description: Kurzbeschreibung der Beziehung und ihrer Relevanz für Agenten.
 summary: Rolle, Status und Relevanz des Partners im CodeCell-Netzwerk.
 department: vertrieb
 owners:

package/skills/company-agent-wiki-cli/references/overview.md

@@ -1,7 +1,7 @@
 # Overview
 
 `company-agent-wiki-cli` is the public interface for a private, local company knowledge workspace.
-The published package now installs into a shared `~/.agents` home first and mirrors into `~/.codex` for Codex compatibility.
+The published package now installs into a shared `~/.agents` home first and adds a Codex compatibility shim under `~/.codex/bin`.
 
 ## Source of Truth