@jcode.labs/ragmir 2.10.0 → 2.12.0

package/dist/setup.js

@@ -6,10 +6,10 @@ import { ingest } from "./ingest.js";
 import { initProject } from "./init.js";
 import { rgrCommand } from "./package-manager.js";
 import { enableSemanticEmbeddings } from "./semantic-config.js";
-import { installSkill } from "./skill.js";
+import { installAgentSkills, } from "./skill.js";
 const CONFIGURATION_PROMPT = `You are helping configure Ragmir for this repository.
 
-Work from the repository root where \`rgr setup\` was run. Your goal is to improve \`.ragmir/config.json\` so Ragmir indexes useful repository knowledge without indexing secrets, generated files, or noisy bulk data.
+Work from the knowledge-base root where \`rgr setup\` was run. Your goal is to improve \`.ragmir/config.json\` so Ragmir indexes useful repository knowledge without indexing secrets, generated files, or noisy bulk data. In a monorepo with nested Ragmir bases, keep an app base scoped to that app; only the root base should index shared or cross-app knowledge.
 
 Tasks:
 1. Inspect the repository structure and the current \`.ragmir/config.json\`.
@@ -24,7 +24,7 @@ Keep all proposed paths relative to the repository root. Do not add secrets or p
 export async function setupProject(options = {}) {
     const cwd = path.resolve(options.cwd ?? process.cwd());
     const created = await initProject(cwd);
-    const installOptions = { cwd };
+    const installOptions = { cwd, scope: "project", mode: "link" };
     if (options.targetDir !== undefined) {
         installOptions.targetDir = options.targetDir;
     }
@@ -40,7 +40,11 @@ export async function setupProject(options = {}) {
     if (options.mcpArgs !== undefined) {
         installOptions.mcpArgs = options.mcpArgs;
     }
-    const agentKit = await installSkill(installOptions);
+    if (options.forceAgentSkills !== undefined) {
+        installOptions.force = options.forceAgentSkills;
+    }
+    const agentSkills = await installAgentSkills(installOptions);
+    const agentKit = agentSkills.projectKit;
     const semantic = options.semantic ? await setupSemanticEmbeddings(cwd) : null;
     let report = await doctor(cwd);
     let ingested = null;
@@ -55,6 +59,7 @@ export async function setupProject(options = {}) {
         runCommand: command.display,
         created,
         agentKit,
+        agentInstallations: agentSkills.installations,
         semantic,
         ingested,
         doctor: report,
@@ -80,7 +85,7 @@ function setupNextSteps(report) {
     if (report.ready) {
         return [
             "Ask questions with the search or ask command shown by `rgr doctor`.",
-            "Run `rgr install-agent --agents claude` or another targeted agent list for native skill discovery.",
+            "Restart or reload the selected agents so they discover the installed Ragmir skills.",
             "Wire the matching MCP helper from .ragmir/ when the agent should call Ragmir tools directly.",
         ];
     }

package/dist/setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"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"}

package/dist/skill.d.ts

@@ -22,19 +22,19 @@ export interface InstallSkillResult {
     clineConfigPath: string;
     agentSetupPath: string;
     readmePath: string;
+    runnerPath: string;
     agentHelpers: AgentHelperFile[];
     mcpServerName: string;
     mcpCommand: string;
     mcpArgs: string[];
     written: string[];
 }
-export interface InstallAgentSkillsOptions {
-    cwd?: string;
-    agents?: readonly AgentTarget[];
+export interface InstallAgentSkillsOptions extends InstallSkillOptions {
     scope?: AgentInstallScope;
     mode?: AgentInstallMode;
     homeDir?: string;
     env?: Record<string, string | undefined>;
+    force?: boolean;
 }
 export interface AgentSkillInstallation {
     agent: AgentTarget;
@@ -54,6 +54,18 @@ export interface AgentHelperFile {
     label: string;
     path: string;
 }
+export type RagmirRunnerMode = "local-bin" | "workspace" | "installed-package" | "npm-cache";
+export interface AgentIntegrationReport {
+    runnerPath: string;
+    runnerReady: boolean;
+    runnerMode: RagmirRunnerMode | null;
+    runnerRequiresDownload: boolean;
+    projectAgents: AgentTarget[];
+    userAgents: AgentTarget[];
+    nativeAgents: AgentTarget[];
+    ready: boolean;
+    warnings: string[];
+}
 export declare const SKILL_NAMES: readonly ["ragmir", "ragmir-audio-summary", "ragmir-markdown-report", "ragmir-legal-dossier"];
 export declare const MCP_CONFIG_FILENAME = "mcp.json";
 export declare const AGENT_SETUP_FILENAME = "agent-setup.md";
@@ -63,4 +75,5 @@ export declare function bundledSkillPath(skillName?: string): string;
 export declare function parseAgentTargets(value: string | readonly string[] | undefined): AgentTarget[];
 export declare function installSkill(options?: InstallSkillOptions): Promise<InstallSkillResult>;
 export declare function installAgentSkills(options?: InstallAgentSkillsOptions): Promise<InstallAgentSkillsResult>;
+export declare function inspectAgentIntegration(cwd?: string, homeDir?: string, env?: Record<string, string | undefined>): AgentIntegrationReport;
 //# sourceMappingURL=skill.d.ts.map

package/dist/skill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"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"}

package/dist/skill.js

@@ -1,9 +1,13 @@
-import { cp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { cp, lstat, mkdir, readFile, realpath, rm, symlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_SKILL_TARGET_DIR, RAGMIR_DIR, RAGMIR_PROJECT_ROOT_ENV } from "./defaults.js";
 import { ensureRagmirGitignore } from "./gitignore.js";
-import { rgrCommand } from "./package-manager.js";
+import { knowledgeBaseIdentity } from "./knowledge-bases.js";
+import { RGR_RUNNER_FILENAME, RGR_RUNNER_PROBE_ARG, rgrCommand, } from "./package-manager.js";
+import { VERSION } from "./version.js";
 const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const PRIMARY_SKILL_NAME = "ragmir";
 const AUDIO_SKILL_NAME = "ragmir-audio-summary";
@@ -11,6 +15,7 @@ const REPORT_SKILL_NAME = "ragmir-markdown-report";
 const LEGAL_SKILL_NAME = "ragmir-legal-dossier";
 const DEFAULT_MCP_SERVER_NAME = "ragmir";
 const MCP_SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]+$/u;
+const MANAGED_SKILL_METADATA_FILENAME = ".ragmir-managed.json";
 export const SKILL_NAMES = [
     PRIMARY_SKILL_NAME,
     AUDIO_SKILL_NAME,
@@ -53,8 +58,8 @@ const AGENT_DESTINATIONS = {
     codex: {
         label: "Codex",
         env: "CODEX_SKILLS_DIR",
-        projectDir: path.join(".codex", "skills"),
-        userDir: (homeDir) => path.join(homeDir, ".codex", "skills"),
+        projectDir: path.join(".agents", "skills"),
+        userDir: (homeDir) => path.join(homeDir, ".agents", "skills"),
     },
     kimi: {
         label: "Kimi Code CLI",
@@ -105,7 +110,7 @@ export async function installSkill(options = {}) {
     const targetDir = path.resolve(cwd, options.targetDir ?? DEFAULT_SKILL_TARGET_DIR);
     const agents = options.agents ? parseAgentTargets(options.agents) : [...SUPPORTED_AGENT_TARGETS];
     const agentSet = new Set(agents);
-    const mcpServerName = normalizeMcpServerName(options.mcpServerName);
+    const mcpServerName = normalizeMcpServerName(options.mcpServerName ?? suggestedMcpServerName(cwd));
     const skillPath = path.join(targetDir, PRIMARY_SKILL_NAME);
     const audioSkillPath = path.join(targetDir, AUDIO_SKILL_NAME);
     const reportSkillPath = path.join(targetDir, REPORT_SKILL_NAME);
@@ -126,13 +131,15 @@ export async function installSkill(options = {}) {
     const clineConfigPath = agentConfigPaths.cline;
     const agentSetupPath = path.join(ragmirDir, AGENT_SETUP_FILENAME);
     const readmePath = path.join(ragmirDir, "README.md");
+    const runnerPath = path.join(ragmirDir, RGR_RUNNER_FILENAME);
     await mkdir(targetDir, { recursive: true });
     await mkdir(ragmirDir, { recursive: true });
     await copyBundledSkills(targetDir);
+    await writeFile(runnerPath, ragmirRunnerSource(VERSION, path.join(PACKAGE_ROOT, "dist", "cli.js")), { encoding: "utf8", mode: 0o755 });
     const serveCommand = await resolveMcpCommand(cwd, options);
     const doctorCommand = await rgrCommand(cwd, ["doctor"]);
     const installAgentCommand = await rgrCommand(cwd, ["install-agent", "--agents", agents.join(",")]);
-    await writeFile(mcpConfigPath, `${JSON.stringify(mcpConfig(cwd, serveCommand, undefined, mcpServerName), null, 2)}\n`, "utf8");
+    await writeFile(mcpConfigPath, `${JSON.stringify(mcpConfig(cwd, serveCommand, { [RAGMIR_PROJECT_ROOT_ENV]: cwd }, mcpServerName), null, 2)}\n`, "utf8");
     const agentHelpers = [];
     for (const agent of SUPPORTED_AGENT_TARGETS) {
         const helperPath = agentConfigPaths[agent];
@@ -197,6 +204,7 @@ export async function installSkill(options = {}) {
         path.relative(cwd, audioSkillPath),
         path.relative(cwd, reportSkillPath),
         path.relative(cwd, legalSkillPath),
+        path.relative(cwd, runnerPath),
         path.relative(cwd, mcpConfigPath),
         ...agentHelpers.map((helper) => path.relative(cwd, helper.path)),
         path.relative(cwd, agentSetupPath),
@@ -218,6 +226,7 @@ export async function installSkill(options = {}) {
         clineConfigPath,
         agentSetupPath,
         readmePath,
+        runnerPath,
         agentHelpers,
         mcpServerName,
         mcpCommand: serveCommand.command,
@@ -232,7 +241,16 @@ export async function installAgentSkills(options = {}) {
     const homeDir = path.resolve(options.homeDir ?? process.env.HOME ?? process.cwd());
     const env = options.env ?? process.env;
     const agents = options.agents ?? SUPPORTED_AGENT_TARGETS;
-    const projectKit = await installSkill({ cwd, agents });
+    const installOptions = { cwd, agents };
+    if (options.targetDir !== undefined)
+        installOptions.targetDir = options.targetDir;
+    if (options.mcpServerName !== undefined)
+        installOptions.mcpServerName = options.mcpServerName;
+    if (options.mcpCommand !== undefined)
+        installOptions.mcpCommand = options.mcpCommand;
+    if (options.mcpArgs !== undefined)
+        installOptions.mcpArgs = options.mcpArgs;
+    const projectKit = await installSkill(installOptions);
     const sourceDir = path.dirname(projectKit.skillPath);
     const installations = [];
     const written = [];
@@ -240,7 +258,7 @@ export async function installAgentSkills(options = {}) {
         const destination = AGENT_DESTINATIONS[agent];
         const targetDir = agentTargetDir(agent, scope, cwd, homeDir, env);
         await mkdir(targetDir, { recursive: true });
-        const { mode, skillPaths } = await exposeAgentSkills(sourceDir, targetDir, requestedMode);
+        const { mode, skillPaths } = await exposeAgentSkills(sourceDir, targetDir, requestedMode, options.force ?? false);
         written.push(...skillPaths.map((skillPath) => displayPath(cwd, skillPath)));
         installations.push({
             agent,
@@ -251,6 +269,15 @@ export async function installAgentSkills(options = {}) {
             skillPaths,
         });
     }
+    if (scope === "project") {
+        const gitignoreEntries = installations.flatMap((installation) => installation.skillPaths.map((skillPath) => posixRelativePath(cwd, skillPath)));
+        if (await ensureRagmirGitignore(cwd, gitignoreEntries)) {
+            if (!projectKit.written.includes(".gitignore")) {
+                projectKit.written.push(".gitignore");
+            }
+            written.push(".gitignore");
+        }
+    }
     return {
         projectKit,
         installations,
@@ -282,10 +309,46 @@ function normalizeMcpServerName(value) {
     }
     return name;
 }
+function suggestedMcpServerName(cwd) {
+    const identity = knowledgeBaseIdentity(cwd);
+    if (!identity || identity.id === ".") {
+        return DEFAULT_MCP_SERVER_NAME;
+    }
+    const suffix = sanitizeMcpServerSuffix(identity.id);
+    return suffix ? `${DEFAULT_MCP_SERVER_NAME}-${suffix}` : DEFAULT_MCP_SERVER_NAME;
+}
+function sanitizeMcpServerSuffix(value) {
+    let suffix = "";
+    let replacingInvalidRun = false;
+    for (const character of value.toLowerCase()) {
+        const code = character.charCodeAt(0);
+        const allowed = (code >= 97 && code <= 122) ||
+            (code >= 48 && code <= 57) ||
+            character === "_" ||
+            character === "-";
+        if (allowed) {
+            suffix += character;
+            replacingInvalidRun = false;
+        }
+        else if (!replacingInvalidRun) {
+            suffix += "-";
+            replacingInvalidRun = true;
+        }
+    }
+    let start = 0;
+    let end = suffix.length;
+    while (start < end && suffix[start] === "-") {
+        start += 1;
+    }
+    while (end > start && suffix[end - 1] === "-") {
+        end -= 1;
+    }
+    return suffix.slice(start, end);
+}
 async function writeAgentMcpHelper(agent, input) {
     switch (agent) {
         case "claude":
-            await writeFile(input.claudeConfigPath, `${JSON.stringify(claudeMcpServer(input.serveCommand), null, 2)}\n`, "utf8");
+            await writeFile(input.claudeConfigPath, `${JSON.stringify(claudeMcpServer(input.cwd, input.serveCommand), null, 2)}\n`, "utf8");
             return;
         case "codex":
             await writeFile(input.codexConfigPath, codexMcpConfig(input.cwd, input.serveCommand, input.mcpServerName), "utf8");
@@ -304,45 +367,96 @@ async function copyBundledSkills(targetDir) {
         force: true,
     })));
 }
-async function exposeAgentSkills(sourceDir, targetDir, requestedMode) {
+async function exposeAgentSkills(sourceDir, targetDir, requestedMode, force) {
     if (requestedMode === "copy") {
-        return copyAgentSkills(sourceDir, targetDir);
+        return copyAgentSkills(sourceDir, targetDir, force);
     }
     try {
-        return await linkAgentSkills(sourceDir, targetDir);
+        return await linkAgentSkills(sourceDir, targetDir, force);
     }
     catch {
-        return copyAgentSkills(sourceDir, targetDir);
+        return copyAgentSkills(sourceDir, targetDir, force);
     }
 }
-async function linkAgentSkills(sourceDir, targetDir) {
+async function linkAgentSkills(sourceDir, targetDir, force) {
     const skillPaths = [];
     for (const skillName of SKILL_NAMES) {
         const source = path.join(sourceDir, skillName);
         const target = path.join(targetDir, skillName);
-        await replaceWithDirectorySymlink(source, target);
+        await replaceWithDirectorySymlink(source, target, skillName, force);
         skillPaths.push(target);
     }
     return { mode: "link", skillPaths };
 }
-async function copyAgentSkills(sourceDir, targetDir) {
+async function copyAgentSkills(sourceDir, targetDir, force) {
     const skillPaths = [];
     for (const skillName of SKILL_NAMES) {
         const source = path.join(sourceDir, skillName);
         const target = path.join(targetDir, skillName);
+        await assertManagedSkillTarget(source, target, skillName, force);
         await rm(target, { recursive: true, force: true });
         await cp(source, target, { recursive: true, force: true });
+        await writeFile(path.join(target, MANAGED_SKILL_METADATA_FILENAME), `${JSON.stringify({ managedBy: "ragmir", skillName }, null, 2)}\n`, "utf8");
         skillPaths.push(target);
     }
     return { mode: "copy", skillPaths };
 }
-async function replaceWithDirectorySymlink(source, target) {
+async function replaceWithDirectorySymlink(source, target, skillName, force) {
     if (path.resolve(source) === path.resolve(target)) {
         return;
     }
+    await assertManagedSkillTarget(source, target, skillName, force);
     await rm(target, { recursive: true, force: true });
     await symlink(source, target, process.platform === "win32" ? "junction" : "dir");
 }
+async function assertManagedSkillTarget(source, target, skillName, force) {
+    let targetStats;
+    try {
+        targetStats = await lstat(target);
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT"))
+            return;
+        throw error;
+    }
+    if (force)
+        return;
+    if (targetStats.isSymbolicLink()) {
+        try {
+            if ((await realpath(target)) === (await realpath(source)))
+                return;
+        }
+        catch {
+            // A broken or unreadable link is not safe to replace implicitly.
+        }
+    }
+    else if (targetStats.isDirectory()) {
+        const metadata = await readManagedSkillMetadata(target);
+        if (metadata?.managedBy === "ragmir" && metadata.skillName === skillName)
+            return;
+    }
+    throw new Error(`Refusing to replace unmanaged agent skill at ${target}. Move it, or rerun with --force after reviewing its contents.`);
+}
+async function readManagedSkillMetadata(target) {
+    try {
+        const value = JSON.parse(await readFile(path.join(target, MANAGED_SKILL_METADATA_FILENAME), "utf8"));
+        if (typeof value === "object" &&
+            value !== null &&
+            "managedBy" in value &&
+            typeof value.managedBy === "string" &&
+            "skillName" in value &&
+            typeof value.skillName === "string") {
+            return { managedBy: value.managedBy, skillName: value.skillName };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function hasErrorCode(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
 function agentTargetDir(agent, scope, cwd, homeDir, env) {
     const destination = AGENT_DESTINATIONS[agent];
     const override = env[destination.env];
@@ -370,6 +484,185 @@ function displayPath(cwd, filePath) {
     }
     return filePath;
 }
+function posixRelativePath(cwd, filePath) {
+    return path.relative(cwd, filePath).split(path.sep).join("/");
+}
+export function inspectAgentIntegration(cwd = process.cwd(), homeDir = process.env.HOME ?? process.cwd(), env = process.env) {
+    const projectRoot = path.resolve(cwd);
+    const resolvedHome = path.resolve(homeDir);
+    const runnerPath = path.join(projectRoot, RAGMIR_DIR, RGR_RUNNER_FILENAME);
+    const probe = probeRagmirRunner(projectRoot, runnerPath);
+    const projectAgents = detectedAgentTargets("project", projectRoot, resolvedHome, env);
+    const userAgents = detectedAgentTargets("user", projectRoot, resolvedHome, env);
+    const nativeAgents = [...new Set([...projectAgents, ...userAgents])];
+    const warnings = [];
+    if (!existsSync(runnerPath)) {
+        warnings.push("The generated Ragmir runner is missing. Run `rgr setup` or `rgr doctor --fix`.");
+    }
+    else if (!probe.runnerReady) {
+        warnings.push("The generated Ragmir runner could not verify a local CLI. Install @jcode.labs/ragmir in the project or rebuild the workspace package.");
+    }
+    if (probe.runnerRequiresDownload) {
+        warnings.push("The runner will fall back to the pinned npm package and may need a network download before first use.");
+    }
+    if (nativeAgents.length === 0) {
+        warnings.push("No native agent skill exposure was detected. Run `rgr install-agent --agents <list>`.");
+    }
+    return {
+        runnerPath,
+        runnerReady: probe.runnerReady,
+        runnerMode: probe.runnerMode,
+        runnerRequiresDownload: probe.runnerRequiresDownload,
+        projectAgents,
+        userAgents,
+        nativeAgents,
+        ready: probe.runnerReady && nativeAgents.length > 0,
+        warnings,
+    };
+}
+function detectedAgentTargets(scope, projectRoot, homeDir, env) {
+    return SUPPORTED_AGENT_TARGETS.filter((agent) => {
+        const targetDir = agentTargetDir(agent, scope, projectRoot, homeDir, env);
+        return SKILL_NAMES.every((skillName) => existsSync(path.join(targetDir, skillName, "SKILL.md")));
+    });
+}
+function probeRagmirRunner(projectRoot, runnerPath) {
+    if (!existsSync(runnerPath)) {
+        return { runnerReady: false, runnerMode: null, runnerRequiresDownload: false };
+    }
+    const result = spawnSync(process.execPath, [runnerPath, RGR_RUNNER_PROBE_ARG], {
+        cwd: projectRoot,
+        encoding: "utf8",
+        timeout: 5_000,
+        env: { ...process.env, [RAGMIR_PROJECT_ROOT_ENV]: projectRoot },
+    });
+    if (result.status !== 0) {
+        return { runnerReady: false, runnerMode: null, runnerRequiresDownload: false };
+    }
+    try {
+        const value = JSON.parse(result.stdout.trim());
+        if (typeof value === "object" &&
+            value !== null &&
+            "verified" in value &&
+            typeof value.verified === "boolean" &&
+            "mode" in value &&
+            isRagmirRunnerMode(value.mode) &&
+            "requiresDownload" in value &&
+            typeof value.requiresDownload === "boolean") {
+            return {
+                runnerReady: value.verified,
+                runnerMode: value.mode,
+                runnerRequiresDownload: value.requiresDownload,
+            };
+        }
+    }
+    catch {
+        return { runnerReady: false, runnerMode: null, runnerRequiresDownload: false };
+    }
+    return { runnerReady: false, runnerMode: null, runnerRequiresDownload: false };
+}
+function isRagmirRunnerMode(value) {
+    return (value === "local-bin" ||
+        value === "workspace" ||
+        value === "installed-package" ||
+        value === "npm-cache");
+}
+function ragmirRunnerSource(version, installedCliPath) {
+    const packageSpec = `@jcode.labs/ragmir@${version}`;
+    return `#!/usr/bin/env node
+const { spawnSync } = require("node:child_process")
+const { existsSync, readFileSync } = require("node:fs")
+const path = require("node:path")
+
+const PACKAGE_SPEC = ${JSON.stringify(packageSpec)}
+const INSTALLED_CLI = ${JSON.stringify(installedCliPath)}
+const PROBE_ARG = ${JSON.stringify(RGR_RUNNER_PROBE_ARG)}
+const projectRoot = path.resolve(process.env.${RAGMIR_PROJECT_ROOT_ENV} || process.cwd())
+
+function isRagmirWorkspaceCli(cliPath) {
+  if (!existsSync(cliPath)) return false
+  try {
+    const manifestPath = path.join(path.dirname(path.dirname(cliPath)), "package.json")
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"))
+    return manifest.name === "@jcode.labs/ragmir"
+  } catch {
+    return false
+  }
+}
+
+function resolveCommand() {
+  const localBin = path.join(
+    projectRoot,
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? "rgr.cmd" : "rgr",
+  )
+  if (existsSync(localBin)) {
+    return { mode: "local-bin", command: localBin, args: [], requiresDownload: false }
+  }
+
+  const workspaceCli = path.join(projectRoot, "packages", "ragmir-core", "dist", "cli.js")
+  if (isRagmirWorkspaceCli(workspaceCli)) {
+    return {
+      mode: "workspace",
+      command: process.execPath,
+      args: [workspaceCli],
+      requiresDownload: false,
+    }
+  }
+
+  if (isRagmirWorkspaceCli(INSTALLED_CLI)) {
+    return {
+      mode: "installed-package",
+      command: process.execPath,
+      args: [INSTALLED_CLI],
+      requiresDownload: false,
+    }
+  }
+
+  return {
+    mode: "npm-cache",
+    command: process.platform === "win32" ? "npx.cmd" : "npx",
+    args: ["--yes", "--package", PACKAGE_SPEC, "rgr"],
+    requiresDownload: true,
+  }
+}
+
+const selected = resolveCommand()
+const commandArgs = process.argv.slice(2)
+
+if (commandArgs[0] === PROBE_ARG) {
+  const probeArgs = selected.mode === "npm-cache" ? ["--version"] : [...selected.args, "--version"]
+  const probe = spawnSync(selected.command, probeArgs, {
+    cwd: projectRoot,
+    stdio: "ignore",
+    env: { ...process.env, ${RAGMIR_PROJECT_ROOT_ENV}: projectRoot },
+  })
+  const available = probe.status === 0
+  console.log(
+    JSON.stringify({
+      available,
+      verified: available && selected.mode !== "npm-cache",
+      mode: selected.mode,
+      requiresDownload: selected.requiresDownload,
+    }),
+  )
+  process.exitCode = available ? 0 : 1
+} else {
+  const result = spawnSync(selected.command, [...selected.args, ...commandArgs], {
+    cwd: projectRoot,
+    stdio: "inherit",
+    env: { ...process.env, ${RAGMIR_PROJECT_ROOT_ENV}: projectRoot },
+  })
+  if (result.error) {
+    console.error(result.error.message)
+    process.exitCode = 1
+  } else {
+    process.exitCode = result.status ?? 1
+  }
+}
+`;
+}
 function mcpConfig(cwd, serveCommand, env, serverName = DEFAULT_MCP_SERVER_NAME) {
     const serverConfig = {
         command: serveCommand.command,
@@ -386,11 +679,12 @@ function mcpConfig(cwd, serveCommand, env, serverName = DEFAULT_MCP_SERVER_NAME)
     }
     return config;
 }
-function claudeMcpServer(serveCommand) {
+function claudeMcpServer(cwd, serveCommand) {
     return {
         type: "stdio",
         command: serveCommand.command,
         args: serveCommand.args,
+        env: { [RAGMIR_PROJECT_ROOT_ENV]: cwd },
     };
 }
 function codexMcpConfig(cwd, serveCommand, serverName = DEFAULT_MCP_SERVER_NAME) {
@@ -461,6 +755,10 @@ ${input.serveCommand}
 
 Use \`ragmir_route_prompt\` when an agent hook or skill needs to decide whether the current user
 prompt should call Ragmir before answering. The router is local and does not store prompt text.`,
+        `This helper is pinned to one knowledge-base root. In a monorepo, keep the generated server name
+\`${input.mcpServerName}\` and generate a separate helper from each nested base. Call
+\`ragmir_status\` and verify \`knowledgeBaseId\` before retrieval when the active base is unclear.`,
+        "Read `ragmir://context` for bounded base identity, readiness, freshness, and capabilities. Read `ragmir://sources` only when source coverage or index drift matters.",
     ];
     if (hasAgentHelper(input, "claude")) {
         sections.push(`Claude Code local MCP setup:
@@ -616,7 +914,7 @@ Default project-scope targets:
 | Agent | Project skill directory | User skill directory |
 | --- | --- | --- |
 | Claude Code | \`.claude/skills/\` | \`~/.claude/skills/\` |
-| Codex | \`.codex/skills/\` | \`~/.codex/skills/\` |
+| Codex | \`.agents/skills/\` | \`~/.agents/skills/\` |
 | Kimi Code CLI | \`.kimi/skills/\` | \`~/.kimi/skills/\` |
 | OpenCode | \`.opencode/skills/\` | \`~/.config/opencode/skills/\` |
 | Cline | \`.cline/skills/\` | \`~/.cline/skills/\` |
@@ -625,7 +923,8 @@ Override paths with \`CLAUDE_SKILLS_DIR\`, \`CODEX_SKILLS_DIR\`, \`KIMI_SKILLS_D
 \`OPENCODE_SKILLS_DIR\`, or \`CLINE_SKILLS_DIR\`.
 
 Use \`--mode copy\` only when an agent runtime does not follow symlinked skill directories. When using
-copy mode, rerun \`install-agent\` after refreshing \`.ragmir/skills/\`.
+copy mode, rerun \`install-agent\` after refreshing \`.ragmir/skills/\`. Ragmir refuses to replace
+an unmanaged same-name skill by default; use \`--force\` only after reviewing that existing folder.
 
 ## Skill Folders