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

package/README.md

@@ -9,7 +9,9 @@
 > Context is king.
 
 `company-agent-wiki-skill` is an agent-first local company knowledge toolkit.
-It ships as a real CLI plus a Codex-style 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.
+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 a compatibility shim and other skills.sh-style runtimes such as Claude Code or OpenClaw.
 
 The product surface is the public CLI:
 
@@ -44,9 +46,19 @@ 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 into Codex with one command
+### 1. Install with one command
 
 The preferred install path is:
 
@@ -56,19 +68,25 @@ npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill in
 
 That installs:
 
-- the skill payload into `~/.codex/skills/company-agent-wiki-cli`
-- the runtime into `~/.codex/tools/company-agent-wiki-cli`
-- the CLI shim into `~/.codex/bin/company-agent-wiki-cli`
+- 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 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
 company-agent-wiki-cli --help
+"$HOME/.agents/bin/company-agent-wiki-cli" --help
 "$CODEX_HOME/bin/company-agent-wiki-cli" --help
 "$HOME/.codex/bin/company-agent-wiki-cli" --help
 ```
 
-In Codex, the direct shim path is often the most reliable fallback.
+For agent environments that use the shared `~/.agents` home, the direct shim path is often the most reliable fallback.
+In Codex, the compatibility shim under `~/.codex/bin` also works.
 
 ### 3. Optional local repo workflow
 
@@ -144,6 +162,7 @@ If a fresh agent receives this skill, the correct order is:
 
 1. Verify the CLI path:
    - `company-agent-wiki-cli --help`
+   - `"$HOME/.agents/bin/company-agent-wiki-cli" --help`
    - `"$CODEX_HOME/bin/company-agent-wiki-cli" --help`
    - `"$HOME/.codex/bin/company-agent-wiki-cli" --help`
 2. If no workspace exists yet, create one with `setup workspace`.
@@ -197,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
@@ -211,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

@@ -1189,7 +1189,7 @@ var require_command = __commonJS({
   "node_modules/commander/lib/command.js"(exports2) {
     var EventEmitter = require("node:events").EventEmitter;
     var childProcess = require("node:child_process");
-    var path9 = require("node:path");
+    var path10 = require("node:path");
     var fs9 = require("node:fs");
     var process2 = require("node:process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
@@ -2202,9 +2202,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path9.resolve(baseDir, baseName);
+          const localBin = path10.resolve(baseDir, baseName);
           if (fs9.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path9.extname(baseName))) return void 0;
+          if (sourceExt.includes(path10.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
             (ext) => fs9.existsSync(`${localBin}${ext}`)
           );
@@ -2222,17 +2222,17 @@ Expecting one of '${allowedValues.join("', '")}'`);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path9.resolve(
-            path9.dirname(resolvedScriptPath),
+          executableDir = path10.resolve(
+            path10.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path9.basename(
+            const legacyName = path10.basename(
               this._scriptPath,
-              path9.extname(this._scriptPath)
+              path10.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -2243,7 +2243,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path9.extname(executableFile));
+        launchWithNode = sourceExt.includes(path10.extname(executableFile));
         let proc;
         if (process2.platform !== "win32") {
           if (launchWithNode) {
@@ -3158,7 +3158,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path9.basename(filename, path9.extname(filename));
+        this._name = path10.basename(filename, path10.extname(filename));
         return this;
       }
       /**
@@ -3172,9 +3172,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path10) {
-        if (path10 === void 0) return this._executableDir;
-        this._executableDir = path10;
+      executableDir(path11) {
+        if (path11 === void 0) return this._executableDir;
+        this._executableDir = path11;
         return this;
       }
       /**
@@ -6937,7 +6937,7 @@ var require_gray_matter = __commonJS({
 
 // src/index.ts
 var import_node_fs8 = __toESM(require("node:fs"));
-var import_node_path8 = __toESM(require("node:path"));
+var import_node_path9 = __toESM(require("node:path"));
 
 // node_modules/commander/esm.mjs
 var import_index = __toESM(require_commander(), 1);
@@ -6959,6 +6959,7 @@ var {
 // src/lib/constants.ts
 var PACKAGE_NAME = "@codecell-germany/company-agent-wiki-skill";
 var CLI_NAME = "company-agent-wiki-cli";
+var SKILL_NAME = "company-agent-wiki-cli";
 var WORKSPACE_INTERNAL_DIR = ".company-agent-wiki";
 var WORKSPACE_CONFIG_FILE = "workspace.json";
 var INDEX_DB_FILE = "index.sqlite";
@@ -7141,10 +7142,8 @@ function getGitDiff(filePath, baseRef, compareRef) {
   return runGit(args, resolved.repoRoot, true);
 }
 
-// src/lib/indexer.ts
-var import_node_fs5 = __toESM(require("node:fs"));
-var import_node_path6 = __toESM(require("node:path"));
-var import_better_sqlite3 = __toESM(require("better-sqlite3"));
+// src/lib/install.ts
+var import_node_path3 = __toESM(require("node:path"));
 
 // src/lib/fs-utils.ts
 var import_node_fs2 = __toESM(require("node:fs"));
@@ -7161,13 +7160,13 @@ function writeJsonFile(targetPath, value) {
 `);
 }
 function writeJsonAtomic(targetPath, value) {
-  const tempPath = `${targetPath}.tmp`;
+  const tempPath = `${targetPath}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
   ensureDir(import_node_path2.default.dirname(targetPath));
   writeJsonFile(tempPath, value);
   import_node_fs2.default.renameSync(tempPath, targetPath);
 }
 function replaceFileAtomic(targetPath, content) {
-  const tempPath = `${targetPath}.tmp`;
+  const tempPath = `${targetPath}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
   ensureDir(import_node_path2.default.dirname(targetPath));
   import_node_fs2.default.writeFileSync(tempPath, content);
   import_node_fs2.default.renameSync(tempPath, targetPath);
@@ -7204,6 +7203,25 @@ function walkMarkdownFiles(rootPath) {
   return files.sort();
 }
 
+// src/lib/install.ts
+function detectInstalledRuntimeHome(runtimeDir) {
+  const normalized = import_node_path3.default.resolve(runtimeDir);
+  const skillDir = import_node_path3.default.dirname(normalized);
+  const toolsDir = import_node_path3.default.dirname(skillDir);
+  if (import_node_path3.default.basename(normalized) !== "dist") {
+    return void 0;
+  }
+  if (import_node_path3.default.basename(skillDir) !== SKILL_NAME || import_node_path3.default.basename(toolsDir) !== "tools") {
+    return void 0;
+  }
+  return import_node_path3.default.dirname(toolsDir);
+}
+
+// src/lib/indexer.ts
+var import_node_fs5 = __toESM(require("node:fs"));
+var import_node_path7 = __toESM(require("node:path"));
+var import_better_sqlite3 = __toESM(require("better-sqlite3"));
+
 // src/lib/hash.ts
 var import_node_crypto = require("node:crypto");
 function sha256(input) {
@@ -7214,7 +7232,7 @@ function newBuildId() {
 }
 
 // src/lib/markdown.ts
-var import_node_path3 = __toESM(require("node:path"));
+var import_node_path4 = __toESM(require("node:path"));
 var import_gray_matter = __toESM(require_gray_matter());
 function slugify(value) {
   return value.normalize("NFKD").replace(/[^\w\s-]/g, "").trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/-+/g, "-");
@@ -7264,7 +7282,7 @@ function parseMarkdownDocument(absPath, relPath, rootId, rawContent, mtimeMs) {
     });
   };
   const titleFromFirstHeading = lines.find((line) => line.startsWith("# "))?.replace(/^#\s+/u, "").trim();
-  const title = typeof parsed.data.title === "string" && parsed.data.title.trim() || titleFromFirstHeading || import_node_path3.default.basename(relPath, ".md");
+  const title = typeof parsed.data.title === "string" && parsed.data.title.trim() || titleFromFirstHeading || import_node_path4.default.basename(relPath, ".md");
   const documentId = typeof parsed.data.id === "string" && parsed.data.id.trim() || deriveDocId(rootId, relPath);
   for (const line of lines) {
     const match = line.match(headingPattern);
@@ -7340,52 +7358,55 @@ function parseMarkdownDocument(absPath, relPath, rootId, rawContent, mtimeMs) {
 // src/lib/workspace.ts
 var import_node_fs3 = __toESM(require("node:fs"));
 var import_node_os = __toESM(require("node:os"));
-var import_node_path4 = __toESM(require("node:path"));
+var import_node_path5 = __toESM(require("node:path"));
 function getDefaultCodexHome() {
-  return process.env.CODEX_HOME || import_node_path4.default.join(import_node_os.default.homedir(), ".codex");
+  return process.env.CODEX_HOME || import_node_path5.default.join(import_node_os.default.homedir(), ".codex");
+}
+function getDefaultAgentsHome() {
+  return process.env.AGENTS_HOME || import_node_path5.default.join(import_node_os.default.homedir(), ".agents");
 }
 function getGlobalRegistryDir() {
   const explicit = process.env.COMPANY_AGENT_WIKI_CONFIG_HOME;
   if (explicit?.trim()) {
-    return import_node_path4.default.resolve(explicit);
+    return import_node_path5.default.resolve(explicit);
   }
   if (process.env.VITEST || process.env.NODE_ENV === "test") {
-    return import_node_path4.default.join(import_node_os.default.tmpdir(), GLOBAL_REGISTRY_DIR_NAME, "vitest");
+    return import_node_path5.default.join(import_node_os.default.tmpdir(), GLOBAL_REGISTRY_DIR_NAME, "vitest");
   }
   if (process.platform === "darwin") {
-    return import_node_path4.default.join(import_node_os.default.homedir(), "Library", "Application Support", GLOBAL_REGISTRY_DIR_NAME);
+    return import_node_path5.default.join(import_node_os.default.homedir(), "Library", "Application Support", GLOBAL_REGISTRY_DIR_NAME);
   }
   if (process.platform === "win32") {
-    const roaming = process.env.APPDATA || import_node_path4.default.join(import_node_os.default.homedir(), "AppData", "Roaming");
-    return import_node_path4.default.join(roaming, GLOBAL_REGISTRY_DIR_NAME);
+    const roaming = process.env.APPDATA || import_node_path5.default.join(import_node_os.default.homedir(), "AppData", "Roaming");
+    return import_node_path5.default.join(roaming, GLOBAL_REGISTRY_DIR_NAME);
   }
-  const xdgConfig = process.env.XDG_CONFIG_HOME || import_node_path4.default.join(import_node_os.default.homedir(), ".config");
-  return import_node_path4.default.join(xdgConfig, GLOBAL_REGISTRY_DIR_NAME);
+  const xdgConfig = process.env.XDG_CONFIG_HOME || import_node_path5.default.join(import_node_os.default.homedir(), ".config");
+  return import_node_path5.default.join(xdgConfig, GLOBAL_REGISTRY_DIR_NAME);
 }
 function getGlobalRegistryPath() {
-  return import_node_path4.default.join(getGlobalRegistryDir(), GLOBAL_REGISTRY_FILE);
+  return import_node_path5.default.join(getGlobalRegistryDir(), GLOBAL_REGISTRY_FILE);
 }
 function resolveWorkspacePaths(workspaceRoot) {
   const absoluteRoot = normalizeWorkspaceRootPath(workspaceRoot);
-  const internalDir = import_node_path4.default.join(absoluteRoot, WORKSPACE_INTERNAL_DIR);
+  const internalDir = import_node_path5.default.join(absoluteRoot, WORKSPACE_INTERNAL_DIR);
   return {
     workspaceRoot: absoluteRoot,
     internalDir,
-    configPath: import_node_path4.default.join(internalDir, WORKSPACE_CONFIG_FILE),
-    indexDbPath: import_node_path4.default.join(internalDir, INDEX_DB_FILE),
-    indexManifestPath: import_node_path4.default.join(internalDir, INDEX_MANIFEST_FILE),
-    managedRootPath: import_node_path4.default.join(absoluteRoot, DEFAULT_MANAGED_ROOT_PATH),
-    archiveRootPath: import_node_path4.default.join(absoluteRoot, DEFAULT_ARCHIVE_ROOT_PATH)
+    configPath: import_node_path5.default.join(internalDir, WORKSPACE_CONFIG_FILE),
+    indexDbPath: import_node_path5.default.join(internalDir, INDEX_DB_FILE),
+    indexManifestPath: import_node_path5.default.join(internalDir, INDEX_MANIFEST_FILE),
+    managedRootPath: import_node_path5.default.join(absoluteRoot, DEFAULT_MANAGED_ROOT_PATH),
+    archiveRootPath: import_node_path5.default.join(absoluteRoot, DEFAULT_ARCHIVE_ROOT_PATH)
   };
 }
 function detectWorkspaceRoot(startDir = process.cwd()) {
-  let current = import_node_path4.default.resolve(startDir);
+  let current = import_node_path5.default.resolve(startDir);
   while (true) {
-    const candidate = import_node_path4.default.join(current, WORKSPACE_INTERNAL_DIR, WORKSPACE_CONFIG_FILE);
+    const candidate = import_node_path5.default.join(current, WORKSPACE_INTERNAL_DIR, WORKSPACE_CONFIG_FILE);
     if (fileExists(candidate)) {
       return current;
     }
-    const parent = import_node_path4.default.dirname(current);
+    const parent = import_node_path5.default.dirname(current);
     if (parent === current) {
       return void 0;
     }
@@ -7400,7 +7421,7 @@ function createDefaultGlobalRegistry() {
   };
 }
 function normalizeWorkspaceRootPath(candidatePath) {
-  const resolved = import_node_path4.default.resolve(candidatePath);
+  const resolved = import_node_path5.default.resolve(candidatePath);
   try {
     return import_node_fs3.default.realpathSync.native ? import_node_fs3.default.realpathSync.native(resolved) : import_node_fs3.default.realpathSync(resolved);
   } catch {
@@ -7425,7 +7446,7 @@ function loadGlobalWorkspaceRegistry() {
     const normalizedEntry = {
       workspaceId: entry.workspaceId,
       path: normalizedPath,
-      label: entry.label || import_node_path4.default.basename(normalizedPath),
+      label: entry.label || import_node_path5.default.basename(normalizedPath),
       registeredAt: entry.registeredAt,
       lastUsedAt: entry.lastUsedAt,
       source: entry.source
@@ -7459,14 +7480,14 @@ function buildRegisteredWorkspace(workspaceRoot, source) {
   return {
     workspaceId: config.workspaceId,
     path: resolvedRoot,
-    label: import_node_path4.default.basename(resolvedRoot),
+    label: import_node_path5.default.basename(resolvedRoot),
     registeredAt: now,
     lastUsedAt: now,
     source
   };
 }
 function registerWorkspaceGlobally(workspaceRoot, options3) {
-  const resolvedRoot = import_node_path4.default.resolve(workspaceRoot);
+  const resolvedRoot = import_node_path5.default.resolve(workspaceRoot);
   const nextEntry = buildRegisteredWorkspace(resolvedRoot, options3?.source || "manual");
   const registry = loadGlobalWorkspaceRegistry();
   const existing = registry.workspaces.find((item) => item.path === resolvedRoot);
@@ -7793,6 +7814,7 @@ type: process
 status: active
 tags:
   - example
+description: Short routing description for agents.
 ---
 \`\`\`
 `;
@@ -7818,8 +7840,8 @@ function createDefaultConfig() {
       }
     ],
     index: {
-      databasePath: import_node_path4.default.join(WORKSPACE_INTERNAL_DIR, INDEX_DB_FILE),
-      manifestPath: import_node_path4.default.join(WORKSPACE_INTERNAL_DIR, INDEX_MANIFEST_FILE)
+      databasePath: import_node_path5.default.join(WORKSPACE_INTERNAL_DIR, INDEX_DB_FILE),
+      manifestPath: import_node_path5.default.join(WORKSPACE_INTERNAL_DIR, INDEX_MANIFEST_FILE)
     },
     git: {
       enabled: true,
@@ -7847,22 +7869,22 @@ function saveWorkspaceConfig(workspaceRoot, config) {
   writeJsonFile(paths.configPath, config);
 }
 function normalizeStoredRootPath(workspaceRoot, candidatePath) {
-  const absoluteCandidate = import_node_path4.default.resolve(candidatePath);
-  const relative = import_node_path4.default.relative(workspaceRoot, absoluteCandidate);
-  if (!relative.startsWith("..") && !import_node_path4.default.isAbsolute(relative)) {
+  const absoluteCandidate = import_node_path5.default.resolve(candidatePath);
+  const relative = import_node_path5.default.relative(workspaceRoot, absoluteCandidate);
+  if (!relative.startsWith("..") && !import_node_path5.default.isAbsolute(relative)) {
     return relative || ".";
   }
   return absoluteCandidate;
 }
 function isPathInsideWorkspace(workspaceRoot, candidatePath) {
-  const relative = import_node_path4.default.relative(import_node_path4.default.resolve(workspaceRoot), import_node_path4.default.resolve(candidatePath));
-  return relative === "" || !relative.startsWith("..") && !import_node_path4.default.isAbsolute(relative);
+  const relative = import_node_path5.default.relative(import_node_path5.default.resolve(workspaceRoot), import_node_path5.default.resolve(candidatePath));
+  return relative === "" || !relative.startsWith("..") && !import_node_path5.default.isAbsolute(relative);
 }
 function resolveRootPath(workspaceRoot, root) {
-  if (import_node_path4.default.isAbsolute(root.path)) {
+  if (import_node_path5.default.isAbsolute(root.path)) {
     return root.path;
   }
-  return import_node_path4.default.join(workspaceRoot, root.path);
+  return import_node_path5.default.join(workspaceRoot, root.path);
 }
 function setupWorkspace(options3) {
   const paths = resolveWorkspacePaths(options3.workspaceRoot);
@@ -7884,20 +7906,20 @@ function setupWorkspace(options3) {
     config.git.remoteConfigured = true;
   }
   saveWorkspaceConfig(paths.workspaceRoot, config);
-  writeTextFile(import_node_path4.default.join(paths.workspaceRoot, "README.md"), templateWorkspaceReadme());
-  writeTextFile(import_node_path4.default.join(paths.workspaceRoot, ".gitignore"), templateWorkspaceGitignore());
-  writeTextFile(import_node_path4.default.join(paths.managedRootPath, "README.md"), templateKnowledgeReadme());
-  writeTextFile(import_node_path4.default.join(paths.archiveRootPath, "README.md"), "# Archive\n");
+  writeTextFile(import_node_path5.default.join(paths.workspaceRoot, "README.md"), templateWorkspaceReadme());
+  writeTextFile(import_node_path5.default.join(paths.workspaceRoot, ".gitignore"), templateWorkspaceGitignore());
+  writeTextFile(import_node_path5.default.join(paths.managedRootPath, "README.md"), templateKnowledgeReadme());
+  writeTextFile(import_node_path5.default.join(paths.archiveRootPath, "README.md"), "# Archive\n");
   const created = [
     paths.configPath,
-    import_node_path4.default.join(paths.workspaceRoot, "README.md"),
-    import_node_path4.default.join(paths.workspaceRoot, ".gitignore"),
-    import_node_path4.default.join(paths.managedRootPath, "README.md"),
-    import_node_path4.default.join(paths.archiveRootPath, "README.md")
+    import_node_path5.default.join(paths.workspaceRoot, "README.md"),
+    import_node_path5.default.join(paths.workspaceRoot, ".gitignore"),
+    import_node_path5.default.join(paths.managedRootPath, "README.md"),
+    import_node_path5.default.join(paths.archiveRootPath, "README.md")
   ];
   if (options3.starterDocs !== false) {
     for (const document of createStarterDocuments()) {
-      const absPath = import_node_path4.default.join(paths.managedRootPath, document.relPath);
+      const absPath = import_node_path5.default.join(paths.managedRootPath, document.relPath);
       writeTextFile(absPath, document.content);
       created.push(absPath);
     }
@@ -7933,7 +7955,7 @@ function addRoot(workspaceRoot, rootDefinition) {
   if (config.roots.some((root2) => root2.id === rootDefinition.id)) {
     throw new CliError("ROOT_EXISTS", `Root '${rootDefinition.id}' already exists.`, EXIT_CODES.validation);
   }
-  const absoluteRoot = import_node_path4.default.resolve(rootDefinition.rootPath);
+  const absoluteRoot = import_node_path5.default.resolve(rootDefinition.rootPath);
   if (!isDirectory(absoluteRoot)) {
     throw new CliError(
       "ROOT_NOT_FOUND",
@@ -7975,10 +7997,13 @@ function listRoots(workspaceRoot) {
 function doctor(workspaceRoot) {
   const paths = resolveWorkspacePaths(workspaceRoot);
   const checks = [];
+  const agentsHome = getDefaultAgentsHome();
+  const agentsBinDir = import_node_path5.default.join(agentsHome, "bin");
+  const agentsShimPath = import_node_path5.default.join(agentsBinDir, CLI_NAME);
   const codexHome = getDefaultCodexHome();
-  const codexBinDir = import_node_path4.default.join(codexHome, "bin");
-  const codexShimPath = import_node_path4.default.join(codexBinDir, CLI_NAME);
-  const pathEntries = (process.env.PATH || "").split(import_node_path4.default.delimiter).filter(Boolean);
+  const codexBinDir = import_node_path5.default.join(codexHome, "bin");
+  const codexShimPath = import_node_path5.default.join(codexBinDir, CLI_NAME);
+  const pathEntries = (process.env.PATH || "").split(import_node_path5.default.delimiter).filter(Boolean);
   const registryPath = getGlobalRegistryPath();
   const registry = loadGlobalWorkspaceRegistry();
   checks.push({
@@ -7996,10 +8021,20 @@ function doctor(workspaceRoot) {
     ok: isGitAvailable(),
     message: isGitAvailable() ? "Git is available in PATH." : "Git is not available in PATH."
   });
+  checks.push({
+    name: "agents-cli-shim",
+    ok: fileExists(agentsShimPath),
+    message: fileExists(agentsShimPath) ? `Shared agent CLI shim found: ${agentsShimPath}` : `Shared agent CLI shim missing: ${agentsShimPath}`
+  });
+  checks.push({
+    name: "agents-bin-in-path",
+    ok: pathEntries.includes(agentsBinDir),
+    message: pathEntries.includes(agentsBinDir) ? `Shared agent bin directory is available in PATH: ${agentsBinDir}` : `Shared agent bin directory is not in PATH: ${agentsBinDir}`
+  });
   checks.push({
     name: "codex-cli-shim",
     ok: fileExists(codexShimPath),
-    message: fileExists(codexShimPath) ? `Codex CLI shim found: ${codexShimPath}` : `Codex CLI shim missing: ${codexShimPath}`
+    message: fileExists(codexShimPath) ? `Codex compatibility shim found: ${codexShimPath}` : `Codex compatibility shim missing: ${codexShimPath}`
   });
   checks.push({
     name: "codex-bin-in-path",
@@ -8045,7 +8080,7 @@ function doctor(workspaceRoot) {
 
 // src/lib/write-lock.ts
 var import_node_fs4 = __toESM(require("node:fs"));
-var import_node_path5 = __toESM(require("node:path"));
+var import_node_path6 = __toESM(require("node:path"));
 var LOCK_FILE_NAME = "write.lock";
 var LOCK_WAIT_TIMEOUT_MS = 6e4;
 var LOCK_POLL_INTERVAL_MS = 125;
@@ -8056,7 +8091,7 @@ function sleepMs(durationMs) {
   Atomics.wait(array, 0, 0, durationMs);
 }
 function getLockPath(workspaceRoot) {
-  return import_node_path5.default.join(import_node_path5.default.resolve(workspaceRoot), WORKSPACE_INTERNAL_DIR, LOCK_FILE_NAME);
+  return import_node_path6.default.join(import_node_path6.default.resolve(workspaceRoot), WORKSPACE_INTERNAL_DIR, LOCK_FILE_NAME);
 }
 function readLockPayload(lockPath) {
   if (!fileExists(lockPath)) {
@@ -8101,7 +8136,7 @@ function createLockPayload(workspaceRoot, reason) {
     token: newBuildId(),
     pid: process.pid,
     reason,
-    workspaceRoot: import_node_path5.default.resolve(workspaceRoot),
+    workspaceRoot: import_node_path6.default.resolve(workspaceRoot),
     acquiredAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
@@ -8110,7 +8145,7 @@ function withWorkspaceWriteLock(workspaceRoot, reason, callback, options3) {
   const timeoutMs = options3?.timeoutMs ?? LOCK_WAIT_TIMEOUT_MS;
   const deadline = Date.now() + timeoutMs;
   const payload = createLockPayload(workspaceRoot, reason);
-  ensureDir(import_node_path5.default.dirname(lockPath));
+  ensureDir(import_node_path6.default.dirname(lockPath));
   while (true) {
     try {
       const fileDescriptor = import_node_fs4.default.openSync(lockPath, "wx");
@@ -8190,11 +8225,11 @@ function closeDatabaseQuietly(database) {
 }
 function throwKnownDatabaseError(error, workspaceRoot) {
   const cliError = coerceCliError(error, {
-    sqliteLockHint: `Retry in a moment, serialize parallel CLI reads against ${import_node_path6.default.resolve(
+    sqliteLockHint: `Retry in a moment, serialize parallel CLI reads against ${import_node_path7.default.resolve(
       workspaceRoot
     )}, or rerun with --auto-rebuild after the current write finishes.`,
     sqliteLockDetails: {
-      workspaceRoot: import_node_path6.default.resolve(workspaceRoot)
+      workspaceRoot: import_node_path7.default.resolve(workspaceRoot)
     }
   });
   if (cliError) {
@@ -8277,7 +8312,7 @@ function collectRootSnapshot(rootId, rootPath, kind) {
   let latestMtimeMs = 0;
   for (const filePath of markdownFiles) {
     const stats = import_node_fs5.default.statSync(filePath);
-    const relPath = import_node_path6.default.relative(rootPath, filePath);
+    const relPath = import_node_path7.default.relative(rootPath, filePath);
     latestMtimeMs = Math.max(latestMtimeMs, Math.trunc(stats.mtimeMs));
     entries.push(`${relPath}|${stats.size}|${Math.trunc(stats.mtimeMs)}`);
   }
@@ -8405,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,
@@ -8413,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),
@@ -8503,7 +8541,7 @@ function rebuildIndexUnlocked(workspaceRoot) {
       for (const filePath of markdownFiles) {
         const rawContent = import_node_fs5.default.readFileSync(filePath, "utf8");
         const stats = import_node_fs5.default.statSync(filePath);
-        const relPath = import_node_path6.default.relative(rootPath, filePath);
+        const relPath = import_node_path7.default.relative(rootPath, filePath);
         const parsed = parseMarkdownDocument(filePath, relPath, root.id, rawContent, Math.trunc(stats.mtimeMs));
         insertDocument(database, parsed.document);
         insertSections(database, parsed.document, parsed.sections);
@@ -8615,7 +8653,7 @@ function requireFreshIndex(workspaceRoot, options3) {
       "The workspace has not been indexed yet.",
       EXIT_CODES.indexMissing,
       {
-        hint: verification.hint || `Run: company-agent-wiki-cli index rebuild --workspace ${import_node_path6.default.resolve(workspaceRoot)}`
+        hint: verification.hint || `Run: company-agent-wiki-cli index rebuild --workspace ${import_node_path7.default.resolve(workspaceRoot)}`
       }
     );
   }
@@ -8628,7 +8666,7 @@ function requireFreshIndex(workspaceRoot, options3) {
       "The indexed snapshot no longer matches the current roots.",
       EXIT_CODES.indexStale,
       {
-        hint: `Run: company-agent-wiki-cli index rebuild --workspace ${import_node_path6.default.resolve(workspaceRoot)}`,
+        hint: `Run: company-agent-wiki-cli index rebuild --workspace ${import_node_path7.default.resolve(workspaceRoot)}`,
         details: verification.roots.filter((root) => !root.ok)
       }
     );
@@ -8938,7 +8976,7 @@ function getDocumentHeadings(workspaceRoot, docId, options3) {
 
 // src/lib/onboarding.ts
 var import_node_fs6 = __toESM(require("node:fs"));
-var import_node_path7 = __toESM(require("node:path"));
+var import_node_path8 = __toESM(require("node:path"));
 var COMPANY_ONBOARDING_DE_V1 = {
   profileId: "de-company-v1",
   locale: "de-DE",
@@ -9530,8 +9568,8 @@ function ensureKnownAnswerKeys(payload) {
   }
 }
 function isPathInsideWorkspace2(workspaceRoot, candidatePath) {
-  const relative = import_node_path7.default.relative(import_node_path7.default.resolve(workspaceRoot), import_node_path7.default.resolve(candidatePath));
-  return relative === "" || !relative.startsWith("..") && !import_node_path7.default.isAbsolute(relative);
+  const relative = import_node_path8.default.relative(import_node_path8.default.resolve(workspaceRoot), import_node_path8.default.resolve(candidatePath));
+  return relative === "" || !relative.startsWith("..") && !import_node_path8.default.isAbsolute(relative);
 }
 function resolveManagedRoot(workspaceRoot) {
   const config = loadWorkspaceConfig(workspaceRoot);
@@ -9554,12 +9592,12 @@ function resolveManagedRoot(workspaceRoot) {
   return resolvedPath;
 }
 function createDocument(workspaceRoot, managedRoot, relPath, id, title, type, tags, body, answeredAt, answeredBy) {
-  const absPath = import_node_path7.default.join(managedRoot, relPath);
+  const absPath = import_node_path8.default.join(managedRoot, relPath);
   return {
     docId: id,
     title,
     absPath,
-    relPath: import_node_path7.default.relative(workspaceRoot, absPath),
+    relPath: import_node_path8.default.relative(workspaceRoot, absPath),
     existed: false,
     content: `${renderFrontmatter({ id, title, type, tags, answeredAt, answeredBy })}${body.trimEnd()}
 `
@@ -9791,8 +9829,8 @@ function previewCompanyOnboarding(workspaceRoot, answerFile) {
   };
 }
 function applyCompanyOnboarding(options3) {
-  const workspaceRoot = import_node_path7.default.resolve(options3.workspaceRoot);
-  const answerFile = import_node_path7.default.resolve(options3.answerFile);
+  const workspaceRoot = import_node_path8.default.resolve(options3.workspaceRoot);
+  const answerFile = import_node_path8.default.resolve(options3.answerFile);
   const preview = previewCompanyOnboarding(workspaceRoot, answerFile);
   const warnings = [...preview.warnings];
   let indexBuildId;
@@ -9818,7 +9856,7 @@ function applyCompanyOnboarding(options3) {
         }
       }
       for (const document of preview.documents) {
-        ensureDir(import_node_path7.default.dirname(document.absPath));
+        ensureDir(import_node_path8.default.dirname(document.absPath));
         if (document.existed) {
           warnings.push(`Overwriting existing file: ${document.relPath}`);
         }
@@ -12510,7 +12548,7 @@ function startServer(workspaceRoot, port, options3) {
 // src/index.ts
 function assertWorkspace(workspacePath) {
   if (workspacePath?.trim()) {
-    const resolved = import_node_path8.default.resolve(workspacePath);
+    const resolved = import_node_path9.default.resolve(workspacePath);
     rememberWorkspaceGlobally(resolved, { setDefault: true, source: "runtime" });
     return resolved;
   }
@@ -12577,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) {
@@ -12597,14 +12639,20 @@ function printHeadings(headings) {
 }
 var program2 = new Command();
 program2.name(CLI_NAME).description("Agent-first local company knowledge CLI").version(CLI_SCHEMA_VERSION);
-program2.command("about").description("Show CLI runtime metadata and common Codex paths").option("--json", "Emit JSON output", false).action((options3) => {
+program2.command("about").description("Show CLI runtime metadata and common shared-agent paths").option("--json", "Emit JSON output", false).action((options3) => {
+  const agentsHome = getDefaultAgentsHome();
   const codexHome = getDefaultCodexHome();
+  const runtimeHome = detectInstalledRuntimeHome(__dirname) || null;
   const data = {
     packageName: PACKAGE_NAME,
     cliName: CLI_NAME,
     schemaVersion: CLI_SCHEMA_VERSION,
+    runtimeHome,
+    runtimeShimPath: runtimeHome ? import_node_path9.default.join(runtimeHome, "bin", CLI_NAME) : null,
+    agentsHome,
+    agentsShimPath: import_node_path9.default.join(agentsHome, "bin", CLI_NAME),
     codexHome,
-    codexShimPath: import_node_path8.default.join(codexHome, "bin", CLI_NAME),
+    codexShimPath: import_node_path9.default.join(codexHome, "bin", CLI_NAME),
     cwdWorkspace: detectWorkspaceRoot(process.cwd()) || null,
     globalRegistryPath: getGlobalRegistryPath(),
     resolvedWorkspace: resolveWorkspaceSelection(process.cwd())
@@ -12616,6 +12664,12 @@ program2.command("about").description("Show CLI runtime metadata and common Code
   process.stdout.write(`${CLI_NAME}
 `);
   process.stdout.write(`  schema version: ${CLI_SCHEMA_VERSION}
+`);
+  if (data.runtimeShimPath) {
+    process.stdout.write(`  runtime shim: ${data.runtimeShimPath}
+`);
+  }
+  process.stdout.write(`  shared agent shim: ${data.agentsShimPath}
 `);
   process.stdout.write(`  codex shim: ${data.codexShimPath}
 `);
@@ -12680,7 +12734,7 @@ workspace.command("list").description("List globally registered workspaces").opt
   }
 });
 workspace.command("register").description("Register an existing workspace globally for other agents").requiredOption("--workspace <path>", "Absolute or relative workspace path").option("--default", "Also mark this workspace as the global default", false).option("--json", "Emit JSON output", false).action((options3) => {
-  const entry = registerWorkspaceGlobally(import_node_path8.default.resolve(options3.workspace), {
+  const entry = registerWorkspaceGlobally(import_node_path9.default.resolve(options3.workspace), {
     setDefault: Boolean(options3.default),
     source: "manual"
   });
@@ -12699,7 +12753,7 @@ workspace.command("register").description("Register an existing workspace global
   }
 });
 workspace.command("use").description("Set a registered workspace as the global default").requiredOption("--workspace <path>", "Absolute or relative workspace path").option("--json", "Emit JSON output", false).action((options3) => {
-  const entry = registerWorkspaceGlobally(import_node_path8.default.resolve(options3.workspace), {
+  const entry = registerWorkspaceGlobally(import_node_path9.default.resolve(options3.workspace), {
     setDefault: true,
     source: "manual"
   });
@@ -12717,7 +12771,7 @@ workspace.command("use").description("Set a registered workspace as the global d
 program2.addCommand(workspace);
 program2.command("setup").description("Workspace setup commands").addCommand(
   new Command("workspace").requiredOption("--workspace <path>", "Absolute or relative workspace path").option("--git-init", "Initialize a local Git repository", false).option("--git-remote <url>", "Configure a Git remote URL").option("--no-starter-docs", "Skip creation of starter Markdown documents").option("--force", "Rewrite an existing scaffold", false).option("--json", "Emit JSON output", false).action((options3) => {
-    const workspaceRoot = import_node_path8.default.resolve(options3.workspace);
+    const workspaceRoot = import_node_path9.default.resolve(options3.workspace);
     const result = setupWorkspace({
       workspaceRoot,
       gitInit: Boolean(options3.gitInit),
@@ -12971,8 +13025,8 @@ program2.command("read").option("--workspace <path>", "Workspace path. Optional
   const metadataResult = options3.docId ? getDocumentMetadataById(workspaceRoot, options3.docId, {
     autoRebuild: Boolean(options3.autoRebuild)
   }) : (() => {
-    const candidatePath = import_node_path8.default.isAbsolute(options3.path) ? options3.path : import_node_path8.default.join(workspaceRoot, options3.path);
-    return getDocumentMetadataByPath(workspaceRoot, import_node_path8.default.resolve(candidatePath), {
+    const candidatePath = import_node_path9.default.isAbsolute(options3.path) ? options3.path : import_node_path9.default.join(workspaceRoot, options3.path);
+    return getDocumentMetadataByPath(workspaceRoot, import_node_path9.default.resolve(candidatePath), {
       autoRebuild: Boolean(options3.autoRebuild)
     });
   })();
@@ -13022,7 +13076,7 @@ program2.command("read").option("--workspace <path>", "Workspace path. Optional
 });
 program2.command("history").option("--workspace <path>", "Workspace path. Optional when current directory is already inside a workspace.").option("--doc-id <id>", "Indexed document identifier").option("--path <path>", "Absolute or workspace-relative document path").option("--limit <number>", "Maximum number of commits", "20").option("--json", "Emit JSON output", false).action((options3) => {
   const workspaceRoot = assertWorkspace(options3.workspace);
-  const resolvedPath = options3.docId ? resolveDocumentById(workspaceRoot, options3.docId).absPath : import_node_path8.default.resolve(import_node_path8.default.isAbsolute(options3.path) ? options3.path : import_node_path8.default.join(workspaceRoot, options3.path));
+  const resolvedPath = options3.docId ? resolveDocumentById(workspaceRoot, options3.docId).absPath : import_node_path9.default.resolve(import_node_path9.default.isAbsolute(options3.path) ? options3.path : import_node_path9.default.join(workspaceRoot, options3.path));
   const history = getGitHistory(resolvedPath, Number(options3.limit));
   if (options3.json) {
     printJson(envelope("history", { path: resolvedPath, history }));
@@ -13035,7 +13089,7 @@ program2.command("history").option("--workspace <path>", "Workspace path. Option
 });
 program2.command("diff").option("--workspace <path>", "Workspace path. Optional when current directory is already inside a workspace.").option("--doc-id <id>", "Indexed document identifier").option("--path <path>", "Absolute or workspace-relative document path").option("--base <ref>", "Base Git ref", "HEAD").option("--compare <ref>", "Optional compare ref").option("--json", "Emit JSON output", false).action((options3) => {
   const workspaceRoot = assertWorkspace(options3.workspace);
-  const resolvedPath = options3.docId ? resolveDocumentById(workspaceRoot, options3.docId).absPath : import_node_path8.default.resolve(import_node_path8.default.isAbsolute(options3.path) ? options3.path : import_node_path8.default.join(workspaceRoot, options3.path));
+  const resolvedPath = options3.docId ? resolveDocumentById(workspaceRoot, options3.docId).absPath : import_node_path9.default.resolve(import_node_path9.default.isAbsolute(options3.path) ? options3.path : import_node_path9.default.join(workspaceRoot, options3.path));
   const diff = getGitDiff(resolvedPath, options3.base, options3.compare);
   if (options3.json) {
     printJson(envelope("diff", { path: resolvedPath, diff }));

package/dist/installer.js

@@ -3470,6 +3470,7 @@ var {
 } = import_index.default;
 
 // src/lib/constants.ts
+var PACKAGE_NAME = "@codecell-germany/company-agent-wiki-skill";
 var CLI_NAME = "company-agent-wiki-cli";
 var INSTALLER_NAME = "company-agent-wiki-skill";
 var SKILL_NAME = "company-agent-wiki-cli";
@@ -3537,14 +3538,18 @@ exec "$NODE_BIN" "${runtimeScript}" "$@"
 `;
   import_node_fs2.default.writeFileSync(targetPath, content, { encoding: "utf8", mode: 493 });
 }
-function installIntoCodexHome(options) {
-  const packageRoot = resolvePackageRoot(__dirname);
-  const codexHome = options?.codexHome || process.env.CODEX_HOME || import_node_path.default.join(import_node_os.default.homedir(), ".codex");
-  const runtimeDir = import_node_path.default.join(codexHome, "tools", SKILL_NAME);
-  const skillDir = import_node_path.default.join(codexHome, "skills", SKILL_NAME);
-  const binDir = import_node_path.default.join(codexHome, "bin");
+function getDefaultAgentsHome() {
+  return process.env.AGENTS_HOME || import_node_path.default.join(import_node_os.default.homedir(), ".agents");
+}
+function getDefaultCodexHome() {
+  return process.env.CODEX_HOME || import_node_path.default.join(import_node_os.default.homedir(), ".codex");
+}
+function installIntoHome(target, home, packageRoot, force = false) {
+  const runtimeDir = import_node_path.default.join(home, "tools", SKILL_NAME);
+  const skillDir = import_node_path.default.join(home, "skills", SKILL_NAME);
+  const binDir = import_node_path.default.join(home, "bin");
   const shimPath = import_node_path.default.join(binDir, CLI_NAME);
-  if (options?.force) {
+  if (force) {
     import_node_fs2.default.rmSync(runtimeDir, { recursive: true, force: true });
     import_node_fs2.default.rmSync(skillDir, { recursive: true, force: true });
     import_node_fs2.default.rmSync(shimPath, { force: true });
@@ -3564,7 +3569,9 @@ function installIntoCodexHome(options) {
   const runtimeScript = import_node_path.default.join(runtimeDir, "dist", "index.js");
   writeShim(shimPath, runtimeScript);
   return {
-    codexHome,
+    target,
+    mode: "full",
+    home,
     binDir,
     runtimeDir,
     skillDir,
@@ -3573,6 +3580,63 @@ function installIntoCodexHome(options) {
     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();
+  const codexHome = options?.codexHome || getDefaultCodexHome();
+  const target = options?.target || "all";
+  if (!["agents", "codex", "all"].includes(target)) {
+    throw new Error(`Unsupported install target "${target}". Use agents, codex or all.`);
+  }
+  const installs = [];
+  if (target === "agents" || target === "all") {
+    installs.push(installIntoHome("agents", agentsHome, packageRoot, options?.force));
+  }
+  if (target === "codex" || target === "all") {
+    const shouldSkipCodex = installs.some((entry) => entry.home === codexHome);
+    if (!shouldSkipCodex) {
+      if (target === "codex") {
+        installs.push(installIntoHome("codex", codexHome, packageRoot, options?.force));
+      } else {
+        installs.push(installCompatibilityShim("codex", codexHome, agentsHome, options?.force));
+      }
+    }
+  }
+  return {
+    packageName: PACKAGE_NAME,
+    installerName: INSTALLER_NAME,
+    cliName: CLI_NAME,
+    installs
+  };
+}
 
 // src/lib/errors.ts
 var CliError = class extends Error {
@@ -3653,23 +3717,40 @@ function printJson(value) {
 
 // src/installer.ts
 var program2 = new Command();
-program2.name(INSTALLER_NAME).description("Install the Company Agent Wiki skill and CLI into Codex");
-program2.command("install").option("--codex-home <path>", "Target Codex home directory").option("--force", "Replace an existing install", false).option("--json", "Emit JSON output", false).action((options) => {
-  const result = installIntoCodexHome({
+program2.name(INSTALLER_NAME).description("Install the Company Agent Wiki skill and CLI for shared agent homes and Codex compatibility");
+program2.command("install").option("--agents-home <path>", "Target shared agents home directory").option("--codex-home <path>", "Target Codex home directory").option("--target <target>", "Install target: agents, codex or all", "all").option("--force", "Replace an existing install", false).option("--json", "Emit JSON output", false).action((options) => {
+  const result = installIntoAgentHomes({
+    agentsHome: options.agentsHome,
     codexHome: options.codexHome,
-    force: Boolean(options.force)
+    force: Boolean(options.force),
+    target: options.target
   });
   if (options.json) {
     printJson(envelope("install", result));
     return;
   }
-  process.stdout.write(`Installed into ${result.codexHome}
+  for (const install of result.installs) {
+    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}
 `);
-  process.stdout.write(`CLI shim: ${result.shimPath}
+      }
+    } else if (install.runtimeDir) {
+      process.stdout.write(`Runtime source: ${install.runtimeDir}
 `);
-  if (result.pathHint) {
-    process.stdout.write(`warning: ${result.pathHint}
+    }
+    if (install.pathHint) {
+      process.stdout.write(`warning: ${install.pathHint}
 `);
+    }
   }
 });
 async function main() {

package/knowledge/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## Scope
 
-Phase 1 delivers a publishable CLI and Codex skill for a private, local company knowledge workspace.
+Phase 1 delivers a publishable CLI and a shared agent skill for a private, local company knowledge workspace.
 
 The implementation is intentionally limited to:
 
@@ -46,7 +46,8 @@ 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. `serve` exposes the same read-only data through a local web view and now distinguishes `missing`, `stale` and `ok` states with a rebuild action.
+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
 
@@ -85,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,3 +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 adds a Codex compatibility shim, but it does not manage every agent product's own skill-indexing or refresh logic automatically.

package/knowledge/RELEASE_CHECKLIST.md

@@ -66,7 +66,8 @@ Installer aus lokalem Tarball:
 ```bash
 TMP="$(mktemp -d)"
 cd "$TMP"
-npx -y -p /absolute/path/to/codecell-germany-company-agent-wiki-skill-0.1.0.tgz company-agent-wiki-skill install --codex-home "$TMP/codex" --force
+npx -y -p /absolute/path/to/codecell-germany-company-agent-wiki-skill-0.1.0.tgz company-agent-wiki-skill install --agents-home "$TMP/agents" --codex-home "$TMP/codex" --force
+"$TMP/agents/bin/company-agent-wiki-cli" --help
 "$TMP/codex/bin/company-agent-wiki-cli" --help
 ```
 
@@ -114,7 +115,8 @@ TMP="$(mktemp -d)"
 CACHE="$(mktemp -d)"
 cd "$TMP"
 npm_config_cache="$CACHE" npx -y @codecell-germany/company-agent-wiki-skill@0.1.0 company-agent-wiki-cli --help
-npm_config_cache="$CACHE" npx -y @codecell-germany/company-agent-wiki-skill@0.1.0 company-agent-wiki-skill install --codex-home "$TMP/codex" --force
+npm_config_cache="$CACHE" npx -y @codecell-germany/company-agent-wiki-skill@0.1.0 company-agent-wiki-skill install --agents-home "$TMP/agents" --codex-home "$TMP/codex" --force
+"$TMP/agents/bin/company-agent-wiki-cli" --help
 "$TMP/codex/bin/company-agent-wiki-cli" --help
 ```
 
@@ -155,6 +157,8 @@ npx -y skills add codecell-germany/company-agent-wiki-skill -g --skill company-a
 
 - CLI läuft über `company-agent-wiki-cli`
 - Installer läuft über `company-agent-wiki-skill`
+- Shared agent install unter `~/.agents` funktioniert
+- Codex-Kompatibilitätsinstall unter `~/.codex` funktioniert
 - README, Skill, Referenzen und Knowledge sind synchron
 - `npm pack` enthält nur gewollte Dateien
 - lokaler Tarball-Smoketest ist grün

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codecell-germany/company-agent-wiki-skill",
-  "version": "0.1.2",
-  "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 Codex skill installer.",
+  "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",
   "type": "commonjs",

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

@@ -12,6 +12,8 @@ Use this skill when the task is about a private company knowledge workspace buil
 - Git-backed history
 - a read-only local browsing view
 
+This package now targets a shared `~/.agents` home first so the same published package can work across multiple agent runtimes, not only Codex.
+
 ## Preconditions
 
 - The public CLI binary is `company-agent-wiki-cli`.
@@ -19,22 +21,37 @@ Use this skill when the task is about a private company knowledge workspace buil
 - 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.
-- In Codex, the most reliable fallback is usually the installed shim under `$CODEX_HOME/bin` or `~/.codex/bin`.
+- 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.
-- `node dist/index.js` only works inside the public implementation repo after `npm run build`, not inside an arbitrary private workspace.
 - If the binary is not already installed in PATH, use these fallbacks in this order:
 
 ```bash
+"$HOME/.agents/bin/company-agent-wiki-cli" --help
+"$AGENTS_HOME/bin/company-agent-wiki-cli" --help
 "$CODEX_HOME/bin/company-agent-wiki-cli" --help
 "$HOME/.codex/bin/company-agent-wiki-cli" --help
 company-agent-wiki-cli --help
 npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force
+```
+
+If you are actively developing inside the public implementation repo, the repo-local fallback also exists:
+
+```bash
+"$HOME/.agents/bin/company-agent-wiki-cli" --help
+"$CODEX_HOME/bin/company-agent-wiki-cli" --help
 node dist/index.js --help
 ```
 
 ## First Run
 
-1. In Codex, start with the explicit shim paths:
+1. Start with the shared agent shim path:
+
+```bash
+"$HOME/.agents/bin/company-agent-wiki-cli" --help
+"$AGENTS_HOME/bin/company-agent-wiki-cli" --help
+```
+
+If you are in Codex, the compatibility shim also works:
 
 ```bash
 "$CODEX_HOME/bin/company-agent-wiki-cli" --help
@@ -140,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
@@ -156,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
@@ -200,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/agent-onboarding.md

@@ -4,6 +4,8 @@
 
 ```bash
 npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force
+"$HOME/.agents/bin/company-agent-wiki-cli" --help
+"$AGENTS_HOME/bin/company-agent-wiki-cli" --help
 "$CODEX_HOME/bin/company-agent-wiki-cli" --help
 "$HOME/.codex/bin/company-agent-wiki-cli" --help
 company-agent-wiki-cli --help

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/command-cheatsheet.md

@@ -4,6 +4,8 @@
 
 ```bash
 npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force
+"$HOME/.agents/bin/company-agent-wiki-cli" --help
+"$AGENTS_HOME/bin/company-agent-wiki-cli" --help
 "$CODEX_HOME/bin/company-agent-wiki-cli" --help
 "$HOME/.codex/bin/company-agent-wiki-cli" --help
 company-agent-wiki-cli about --json

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

@@ -59,7 +59,7 @@ If target files already exist, the CLI refuses the write unless `--force` is add
 
 ```json
 {
-  "answeredBy": "Codex Agent",
+  "answeredBy": "AI Agent",
   "notes": ["Buchhaltung zuerst priorisieren"],
   "answers": {
     "official_legal_name": "Beispiel GmbH",

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

@@ -1,6 +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 adds a Codex compatibility shim under `~/.codex/bin`.
 
 ## Source of Truth
 

package/skills/company-agent-wiki-cli/references/workspace-first-run.md

@@ -26,6 +26,8 @@ Before relying on the CLI, verify a real executable path:
 
 ```bash
 npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force
+"$HOME/.agents/bin/company-agent-wiki-cli" --help
+"$AGENTS_HOME/bin/company-agent-wiki-cli" --help
 "$CODEX_HOME/bin/company-agent-wiki-cli" --help
 "$HOME/.codex/bin/company-agent-wiki-cli" --help
 company-agent-wiki-cli --help