create-snipara 1.3.7 → 1.3.9

package/README.md

@@ -1,12 +1,18 @@
 # create-snipara
 
-One-command onboarding and maintenance CLI for **Snipara Hosted MCP Context + Memory** with optional `snipara-companion` and optional RLM-Runtime.
+**One-command onboarding for Snipara Hosted MCP Context + Memory.**
+
+`create-snipara` connects a local project to Snipara so AI agents can start
+with project-owned context, reviewed memory, shared guidance, and optional code
+impact tooling instead of starting cold every session.
 
 ```bash
 npx create-snipara
 ```
 
-`create-snipara` is the simple onboarding package for the agent path. It creates or reuses auth, writes Hosted MCP config, and prepares the local project so an LLM client can use Snipara context and reviewed memory.
+`create-snipara` is the simple onboarding package for the agent path. It
+creates or reuses auth, writes Hosted MCP config, and prepares the local project
+so an LLM client can use Snipara context and reviewed memory.
 
 Use it for:
 
@@ -15,6 +21,26 @@ Use it for:
 - local project wiring, `doctor`, `repair`, and `upgrade`
 - GitHub repository sync approval when the current folder is a GitHub repo
 
+## Why It Exists
+
+AI clients all have slightly different config formats, but the project need is
+the same: connect the agent to the same durable project memory. `create-snipara`
+normalizes that setup.
+
+```mermaid
+flowchart LR
+    Project["Local project"] --> CLI["npx create-snipara"]
+    CLI --> Auth["Snipara auth and project key"]
+    CLI --> MCP["Hosted MCP config"]
+    CLI --> Templates["AGENTS.md, CLAUDE.md, Cursor, Codex snippets"]
+    MCP --> Agents["Codex, Claude Code, Cursor, ChatGPT Desktop"]
+    Templates --> Agents
+    Agents --> Context["Snipara context and memory"]
+```
+
+The CLI does not become the runtime brain. After setup, the agent talks to
+Hosted MCP and keeps using its own LLM.
+
 Do not use it to choose business documents one by one. For local folders, mounted Drive/SharePoint exports, old offers, or PowerPoints, use `snipara-business`.
 
 The product surfaces remain:
@@ -46,7 +72,7 @@ Default profile: `hosted-only`
 
 Free onboarding is now **Context + Memory**, not Context-only:
 
-- Context Free: one project and 100 context queries/month
+- Context Free: three projects and 1,000 context queries/month
 - Memory Free: reviewed hosted memories for continuity across sessions
 - Hosted MCP: direct connection for Claude Code, Codex, Cursor, ChatGPT Desktop, and other MCP clients
 
@@ -76,6 +102,8 @@ That distinction matters:
 - installs `snipara-companion` when the selected profile needs local helper workflows
 - installs optional `rlm-runtime`
 - configures `.mcp.json`
+- generates merge-ready AI agent templates in `.snipara/templates/`, including Pro+ symbol-card and code-impact guidance for paid Context plans
+- creates `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/snipara.mdc`, and `.codex/config.toml` when those files do not already exist
 - updates `.env`, `.env.local`, and `.env.example`
 - generates `.snipara/companion/README.md`
 - generates `.snipara/companion/commands.json`
@@ -102,15 +130,30 @@ npx create-snipara
 
 The interactive flow now asks for:
 
-- install profile
 - project slug
-- optional project id
 - API key path: project key, team key, free signup, or add key later
 - AI client
+
+By default, this stays on the recommended `hosted-only` setup. Add
+`--advanced` when you want profile selection, project id entry, hook prompts,
+GitHub automation prompts, or runtime provider prompts.
+
+The advanced flow asks for:
+
+- install profile
+- optional project id
 - whether hooks should be generated
 - whether to open GitHub repository automation when a GitHub remote is detected
 - optional runtime provider config when `rlm-runtime` is installed
 
+The generated agent templates cover:
+
+- Codex `AGENTS.md`
+- Claude Code `CLAUDE.md`
+- Cursor `.cursor/rules/snipara.mdc`
+- Codex `.codex/config.toml` snippet
+- ChatGPT/OpenAI HTTP MCP snippet
+
 ## Main Commands
 
 ### Install or initialize
@@ -207,6 +250,7 @@ That keeps business truth review separate from agent onboarding.
 npx create-snipara --profile hosted-only
 npx create-snipara --profile hosted-companion
 npx create-snipara --profile full-stack
+npx create-snipara --advanced
 
 # Runtime-only local execution
 npx create-snipara --runtime-only
@@ -319,7 +363,7 @@ Best when the user only wants Hosted MCP Context + Memory.
 ### Full local stack
 
 ```bash
-npx create-snipara --profile full-stack
+npx create-snipara --profile full-stack --advanced
 ```
 
 Best when the user also wants `snipara-companion` and `rlm-runtime`.
@@ -367,7 +411,7 @@ npx create-snipara print-config --json
 When testing a locally packed tarball, use `npm exec --package` instead of `npx`, for example:
 
 ```bash
-npm exec --package ./create-snipara-1.3.7.tgz create-snipara -- --help
+npm exec --package ./create-snipara-1.3.9.tgz create-snipara -- --help
 ```
 
 This avoids `npx` resolution issues with unpublished tarballs.

package/dist/index.js

@@ -9,7 +9,7 @@ import fs from "fs";
 import path from "path";
 import { execSync, spawn } from "child_process";
 import { homedir } from "os";
-var VERSION = "1.3.7";
+var VERSION = "1.3.9";
 var BASE_URL = "https://www.snipara.com";
 var API_URL = "https://api.snipara.com";
 var COMPANION_PACKAGE_NAME = "snipara-companion";
@@ -27,7 +27,7 @@ function getCompanionInitClientFlag(aiClient) {
 function buildProgram() {
   const program = new Command();
   program.name("create-snipara").description("Scaffold hosted Snipara MCP config plus optional local helper workflows").version(VERSION);
-  program.command("init").description("Install and configure Snipara for this project").option("--api-key <key>", "Snipara project API key").option("--team-key <key>", "Snipara team API key").option("--slug <slug>", "Project slug").option("--project-id <id>", "Project ID").option(
+  program.command("init").description("Install and configure Snipara for this project").option("--api-key <key>", "Snipara project API key").option("--team-key <key>", "Snipara team API key").option("--slug <slug>", "Project slug").option("--project-id <id>", "Project ID").option("--advanced", "Show advanced profile, project id, hooks, GitHub, and runtime prompts").option(
     "--profile <profile>",
     "Install profile: hosted-only, hosted-companion, full-stack, runtime-only"
   ).option("--skip-companion", "Skip local companion CLI installation").option("--skip-mcp", "Skip local snipara-mcp package installation").option("--skip-runtime", "Skip rlm-runtime installation").option("--skip-hooks", "Skip hook generation").option("--skip-test", "Skip hosted connection test").option("--github", "Open GitHub repository automation setup when a git remote is detected").option("--skip-github", "Skip the GitHub automation prompt").option("--github-path <path>", "Optional GitHub path filter for the initial repository sync").option("--runtime-only", "Install only RLM-Runtime").option("-y, --yes", "Accept defaults without prompting").action(async (options) => {
@@ -58,7 +58,7 @@ function buildProgram() {
   return program;
 }
 function addSharedRootOptions(program) {
-  program.option("--api-key <key>", "Snipara project API key").option("--team-key <key>", "Snipara team API key").option("--slug <slug>", "Project slug").option("--project-id <id>", "Project ID").option(
+  program.option("--api-key <key>", "Snipara project API key").option("--team-key <key>", "Snipara team API key").option("--slug <slug>", "Project slug").option("--project-id <id>", "Project ID").option("--advanced", "Show advanced profile, project id, hooks, GitHub, and runtime prompts").option(
     "--profile <profile>",
     "Install profile: hosted-only, hosted-companion, full-stack, runtime-only"
   ).option("--skip-companion", "Skip local companion CLI installation").option("--skip-mcp", "Skip local snipara-mcp package installation").option("--skip-runtime", "Skip rlm-runtime installation").option("--skip-hooks", "Skip hook generation").option("--skip-test", "Skip hosted connection test").option("--github", "Open GitHub repository automation setup when a git remote is detected").option("--skip-github", "Skip the GitHub automation prompt").option("--github-path <path>", "Optional GitHub path filter for the initial repository sync").option("--runtime-only", "Install only RLM-Runtime").option("-y, --yes", "Accept defaults without prompting");
@@ -67,8 +67,63 @@ async function main() {
   const program = buildProgram();
   await program.parseAsync(process.argv);
 }
+function normalizeInitOptions(options) {
+  const parsed = parseInitOptionsFromArgv(process.argv.slice(2));
+  const normalized = { ...parsed };
+  for (const [key, value] of Object.entries(options)) {
+    if (value !== void 0) {
+      normalized[key] = value;
+    }
+  }
+  return normalized;
+}
+function parseInitOptionsFromArgv(args) {
+  const parsed = {};
+  const valueFlags = {
+    "--api-key": "apiKey",
+    "--team-key": "teamKey",
+    "--slug": "slug",
+    "--project-id": "projectId",
+    "--profile": "profile",
+    "--github-path": "githubPath"
+  };
+  const booleanFlags = {
+    "--advanced": "advanced",
+    "--skip-companion": "skipCompanion",
+    "--skip-mcp": "skipMcp",
+    "--skip-runtime": "skipRuntime",
+    "--skip-hooks": "skipHooks",
+    "--skip-test": "skipTest",
+    "--runtime-only": "runtimeOnly",
+    "--github": "github",
+    "--skip-github": "skipGithub",
+    "--yes": "yes",
+    "-y": "yes"
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "init") {
+      continue;
+    }
+    const [flag, inlineValue] = arg.split("=", 2);
+    if (flag in valueFlags) {
+      const value = inlineValue ?? args[index + 1];
+      if (value && !value.startsWith("-")) {
+        parsed[valueFlags[flag]] = value;
+        if (inlineValue === void 0) {
+          index += 1;
+        }
+      }
+      continue;
+    }
+    if (arg in booleanFlags) {
+      parsed[booleanFlags[arg]] = true;
+    }
+  }
+  return parsed;
+}
 async function runInit(options) {
-  const answers = await gatherConfiguration(options);
+  const answers = await gatherConfiguration(normalizeInitOptions(options));
   if (answers.installMcp || answers.installRuntime) {
     await installPythonPackages(answers, false);
   }
@@ -78,6 +133,7 @@ async function runInit(options) {
   if (answers.profile !== "runtime-only" || answers.installRuntime) {
     await createMcpConfig(answers);
   }
+  await createAgentTemplates(answers);
   if (answers.installHooks && answers.aiClient === "claude-code") {
     await installClaudeCodeHooks(answers);
   }
@@ -113,6 +169,7 @@ async function runRepair(options) {
     await installNodeCompanion(true);
   }
   await createMcpConfig(answers);
+  await createAgentTemplates(answers);
   await updateEnvFiles(answers);
   await createCompanionPack(answers);
   if (answers.installHooks && answers.aiClient === "claude-code") {
@@ -140,6 +197,7 @@ async function runUpgrade(options) {
   if (options.withMcp || options.withRuntime || detection.files.mcpConfig) {
     await createMcpConfig(upgradedAnswers);
   }
+  await createAgentTemplates(upgradedAnswers);
   if (options.withHooks || answers.installHooks) {
     await installClaudeCodeHooks({ ...answers, installHooks: true });
   }
@@ -195,6 +253,7 @@ async function gatherConfiguration(options) {
   const detectedClient = detectAiClient();
   const existingConfig = getExistingConfig();
   const detectedGitRepo = detectGitRepository();
+  const showAdvancedPrompts = Boolean(options.advanced);
   if (options.github && !detectedGitRepo) {
     console.log(
       chalk.yellow(
@@ -227,7 +286,7 @@ async function gatherConfiguration(options) {
   }
   const response = await prompts([
     {
-      type: "select",
+      type: showAdvancedPrompts ? "select" : null,
       name: "profile",
       message: "Choose an install profile:",
       initial: installProfileChoices().findIndex((choice) => choice.value === initialProfile),
@@ -241,7 +300,7 @@ async function gatherConfiguration(options) {
       validate: (value) => value.length > 0 ? true : "Project slug is required (for example my-project)"
     },
     {
-      type: "text",
+      type: showAdvancedPrompts ? "text" : null,
       name: "projectId",
       message: "Project ID (optional, press Enter to skip):",
       initial: options.projectId || detectedProjectId || ""
@@ -282,7 +341,9 @@ async function gatherConfiguration(options) {
       type: "select",
       name: "aiClient",
       message: "Which AI client are you using?",
-      initial: ["claude-code", "cursor", "claude-desktop", "other"].indexOf(detectedClient),
+      initial: ["claude-code", "cursor", "codex", "chatgpt", "claude-desktop", "other"].indexOf(
+        detectedClient
+      ),
       choices: [
         {
           title: "Claude Code (CLI/VS Code extension)",
@@ -294,6 +355,16 @@ async function gatherConfiguration(options) {
           value: "cursor",
           description: "MCP via .mcp.json plus companion terminal workflows"
         },
+        {
+          title: "OpenAI Codex",
+          value: "codex",
+          description: "Hosted MCP plus AGENTS.md"
+        },
+        {
+          title: "ChatGPT / OpenAI MCP",
+          value: "chatgpt",
+          description: "Hosted MCP for ChatGPT Desktop or OpenAI-compatible clients"
+        },
         {
           title: "Claude Desktop",
           value: "claude-desktop",
@@ -303,19 +374,19 @@ async function gatherConfiguration(options) {
       ]
     },
     {
-      type: "confirm",
+      type: showAdvancedPrompts ? "confirm" : null,
       name: "installHooks",
       message: "Generate local hooks when supported?",
       initial: detectedClient === "claude-code"
     },
     {
-      type: (_, values) => detectedGitRepo && !options.skipGithub && values.profile !== "runtime-only" ? "confirm" : null,
+      type: (_, values) => detectedGitRepo && showAdvancedPrompts && !options.skipGithub && (values.profile || initialProfile) !== "runtime-only" ? "confirm" : null,
       name: "configureGitHub",
       message: detectedGitRepo ? `Open GitHub automation setup for ${detectedGitRepo.fullName} after local config?` : "Open GitHub automation setup after local config?",
       initial: true
     },
     {
-      type: (_, values) => values.configureGitHub && detectedGitRepo ? "text" : null,
+      type: (_, values) => showAdvancedPrompts && values.configureGitHub && detectedGitRepo ? "text" : null,
       name: "githubPath",
       message: "GitHub path filter (optional, press Enter for Snipara defaults):",
       initial: options.githubPath || ""
@@ -339,7 +410,7 @@ async function gatherConfiguration(options) {
   }
   const answers = buildAnswersFromProfile({
     projectSlug: signupResult?.projectSlug || response.projectSlug,
-    projectId: signupResult?.projectId || response.projectId || "",
+    projectId: signupResult?.projectId || response.projectId || options.projectId || "",
     apiKey: apiKey || "",
     apiKeyType,
     profile: response.profile || initialProfile,
@@ -744,6 +815,162 @@ async function createMcpConfig(answers) {
     await createClaudeDesktopConfig(answers);
   }
 }
+async function createAgentTemplates(answers) {
+  if (answers.profile === "runtime-only") {
+    return;
+  }
+  console.log(chalk.bold("\nGenerating Agent Templates\n"));
+  const templatesDir = path.join(process.cwd(), ".snipara", "templates");
+  fs.mkdirSync(templatesDir, { recursive: true });
+  const templates = [
+    { path: path.join(templatesDir, "AGENTS.md"), content: buildAgentsMdTemplate(answers) },
+    { path: path.join(templatesDir, "CLAUDE.md"), content: buildClaudeMdTemplate(answers) },
+    {
+      path: path.join(templatesDir, "cursor-snipara.mdc"),
+      content: buildCursorRuleTemplate(answers)
+    },
+    {
+      path: path.join(templatesDir, "codex-config.toml"),
+      content: buildCodexConfigTemplate(answers)
+    },
+    {
+      path: path.join(templatesDir, "chatgpt-openai-mcp.json"),
+      content: buildChatGptMcpTemplate(answers)
+    }
+  ];
+  for (const template of templates) {
+    fs.writeFileSync(template.path, template.content);
+  }
+  console.log(chalk.green("   Created .snipara/templates agent snippets"));
+  writeIfMissing(
+    path.join(process.cwd(), "AGENTS.md"),
+    buildAgentsMdTemplate(answers),
+    "AGENTS.md"
+  );
+  writeIfMissing(
+    path.join(process.cwd(), "CLAUDE.md"),
+    buildClaudeMdTemplate(answers),
+    "CLAUDE.md"
+  );
+  const cursorRulesDir = path.join(process.cwd(), ".cursor", "rules");
+  fs.mkdirSync(cursorRulesDir, { recursive: true });
+  writeIfMissing(
+    path.join(cursorRulesDir, "snipara.mdc"),
+    buildCursorRuleTemplate(answers),
+    ".cursor/rules/snipara.mdc"
+  );
+  const codexDir = path.join(process.cwd(), ".codex");
+  fs.mkdirSync(codexDir, { recursive: true });
+  writeIfMissing(
+    path.join(codexDir, "config.toml"),
+    buildCodexConfigTemplate(answers),
+    ".codex/config.toml"
+  );
+  ensureGitignoreEntry(".snipara/companion/doctor.json", "# Snipara generated validation output");
+}
+function writeIfMissing(filePath, content, label) {
+  if (fs.existsSync(filePath)) {
+    console.log(chalk.dim(`   ${label} already exists; merge from .snipara/templates if needed`));
+    return;
+  }
+  fs.writeFileSync(filePath, content);
+  console.log(chalk.green(`   Created ${label}`));
+}
+function buildHostedMcpEndpoint(answers) {
+  return `${API_URL}/mcp/${answers.projectSlug}`;
+}
+function buildAgentsMdTemplate(answers) {
+  return `# AGENTS.md
+
+## Snipara Context Workflow
+
+This project uses Snipara Hosted MCP for project context and reviewed memory.
+
+- Endpoint: \`${buildHostedMcpEndpoint(answers)}\`
+- Auth: use \`SNIPARA_API_KEY\` or \`RLM_API_KEY\` from the environment. Never commit keys.
+
+Agent task lifecycle:
+
+1. Start substantial work with \`rlm_recall\` and a targeted \`rlm_context_query\`.
+2. Use \`rlm_context_query\` for docs, business context, client/project truth, architecture notes, runbooks, and narrative source material.
+3. When \`rlm_context_query\` returns \`answer_pack\`, treat it as the first-pass response plan: use its source facts, caveats, source map, and verification checklist before drafting claims.
+4. Use \`rlm_get_chunk\` to load cited source sections returned by reference-based queries before relying on precise wording.
+5. Use \`rlm_code_callers\`, \`rlm_code_imports\`, \`rlm_code_neighbors\`, or \`rlm_code_shortest_path\` for structural code questions.
+6. On paid Context plans, use \`rlm_code_symbol_card\` for agent-ready symbol context and \`rlm_code_impact\` before risky multi-file changes or PR reviews.
+7. Use \`rlm_plan\` or \`rlm_decompose\` only for complex work and only when the hosted server exposes them.
+8. Use local file reads, \`rg\`, git commands, and test commands for exact edits, current working-tree state, and verification.
+9. Use RLM Runtime only when sandboxed execution, repeatable validation, or isolated transformations materially help.
+10. If a broad query is slow, retry once with a narrow keyword query before falling back to local search.
+11. End substantial work with \`rlm_end_of_task_commit\` when available. Use \`rlm_remember_if_novel\` for one reusable memory while avoiding duplicates, and use \`rlm_remember\` for explicit direct memory writes.
+12. Do not store secrets, tokens, passwords, private keys, raw logs, transient command output, or unreviewed guesses in memory.
+`;
+}
+function buildClaudeMdTemplate(answers) {
+  return `# CLAUDE.md
+
+Canonical project context is in \`AGENTS.md\`. This file exists for Claude Code compatibility.
+
+## Snipara
+
+Use Snipara Hosted MCP before answering project-specific questions.
+
+- Endpoint: \`${buildHostedMcpEndpoint(answers)}\`
+- Start substantial work with \`rlm_recall\` and a targeted \`rlm_context_query\`.
+- Use \`rlm_context_query\` for source truth and \`rlm_get_chunk\` for exact cited sections.
+- When \`rlm_context_query\` returns \`answer_pack\`, use its facts, caveats, source map, and verification checklist before drafting claims.
+- Use \`rlm_code_callers\`, \`rlm_code_imports\`, \`rlm_code_neighbors\`, or \`rlm_code_shortest_path\` for structural code questions.
+- On paid Context plans, use \`rlm_code_symbol_card\` before editing important symbols and \`rlm_code_impact\` before risky multi-file changes or PR reviews.
+- Use RLM Runtime only when sandboxed execution or repeatable validation materially helps.
+- End substantial work with \`rlm_end_of_task_commit\` when available; use \`rlm_remember_if_novel\` or \`rlm_remember\` only for narrow durable memories.
+- Do not store secrets, one-off command output, raw logs, or unreviewed guesses in memory.
+- Use the Snipara Claude Code plugin only when slash commands, skills, or hooks are helpful; Hosted MCP remains the normal agent path.
+`;
+}
+function buildCursorRuleTemplate(answers) {
+  return `---
+description: Use Snipara Hosted MCP for project context and reviewed memory.
+alwaysApply: true
+---
+
+# Snipara Agent Workflow
+
+This workspace uses Snipara Hosted MCP for current project context, business/client context, and reviewed memory.
+
+- Check the configured Snipara MCP server before answering project-specific questions.
+- Endpoint: \`${buildHostedMcpEndpoint(answers)}\`
+- Use \`rlm_recall\` for durable decisions, preferences, and validated learnings.
+- Use \`rlm_context_query\` for docs, business context, current client/project truth, and narrative source material.
+- When \`rlm_context_query\` returns \`answer_pack\`, use its facts, caveats, source map, and verification checklist before drafting claims.
+- Use \`rlm_get_chunk\` before relying on exact cited wording from reference-based results.
+- Use \`rlm_code_callers\`, \`rlm_code_imports\`, \`rlm_code_neighbors\`, or \`rlm_code_shortest_path\` for structural code questions.
+- On paid Context plans, use \`rlm_code_symbol_card\` before editing important symbols and \`rlm_code_impact\` before risky multi-file changes or PR reviews.
+- Use \`rlm_plan\` or \`rlm_decompose\` only for complex work and only when available.
+- Use local file reads and tests for exact code edits and current working-tree state.
+- Use RLM Runtime only when sandboxed execution or repeatable validation materially helps.
+- End substantial work with \`rlm_end_of_task_commit\` when available; use \`rlm_remember_if_novel\` or \`rlm_remember\` only for narrow durable memories. Never store secrets.
+`;
+}
+function buildCodexConfigTemplate(answers) {
+  return `[mcp_servers.snipara]
+type = "streamable_http"
+url = "${buildHostedMcpEndpoint(answers)}"
+bearer_token_env_var = "SNIPARA_API_KEY"
+`;
+}
+function buildChatGptMcpTemplate(answers) {
+  return `${JSON.stringify(
+    {
+      name: "snipara",
+      url: buildHostedMcpEndpoint(answers),
+      headers: {
+        "X-API-Key": "YOUR_SNIPARA_PROJECT_API_KEY"
+      }
+    },
+    null,
+    2
+  )}
+`;
+}
 function ensureGitignoreEntry(entry, comment) {
   const gitignorePath = path.join(process.cwd(), ".gitignore");
   if (fs.existsSync(gitignorePath)) {
@@ -978,6 +1205,18 @@ function getClientGuidance(client) {
       "Use the companion CLI only for explicit upload, planning, chunk lookup, doctor, and task commit workflows outside the editor UI."
     ];
   }
+  if (client === "codex") {
+    return [
+      "Codex should use the hosted MCP surface plus AGENTS.md as the canonical project instruction file.",
+      "The generated .snipara/templates/codex-config.toml is a merge-ready snippet for ~/.codex/config.toml if your Codex app does not read project .codex/config.toml."
+    ];
+  }
+  if (client === "chatgpt") {
+    return [
+      "ChatGPT and OpenAI-compatible MCP clients should use the direct hosted MCP endpoint.",
+      "The generated chatgpt-openai-mcp.json is a copy-ready HTTP MCP reference with placeholder auth."
+    ];
+  }
   if (client === "claude-desktop") {
     return [
       "Claude Desktop uses the generated desktop MCP config plus the same hosted Snipara tool contract.",
@@ -1253,6 +1492,11 @@ async function runValidation(answers, includeHostedCheck) {
     status: detection.files.sniparaCompanionPack ? "pass" : "warn",
     detail: detection.files.sniparaCompanionPack ? ".snipara/companion present" : ".snipara/companion missing"
   });
+  checks.push({
+    name: "agent_templates",
+    status: detection.files.sniparaTemplates && detection.files.cursorRule && detection.files.codexConfig ? "pass" : "warn",
+    detail: detection.files.sniparaTemplates && detection.files.cursorRule && detection.files.codexConfig ? ".snipara/templates, .cursor/rules/snipara.mdc, and .codex/config.toml present" : "Agent templates, Cursor rule, or Codex config missing"
+  });
   checks.push({
     name: "env_files",
     status: detection.files.env || detection.files.envLocal || detection.files.envExample ? "pass" : "warn",
@@ -1264,7 +1508,7 @@ async function runValidation(answers, includeHostedCheck) {
     detail: answers.installHooks && answers.aiClient === "claude-code" ? detection.files.claudeDir ? "~/.claude detected" : "~/.claude missing" : "Hooks not requested"
   });
   if (includeHostedCheck && answers.apiKeyType !== "none" && !answers.apiKey.includes("YOUR_")) {
-    checks.push(await testConnection(answers));
+    checks.push(...await testHostedConnection(answers));
   } else if (includeHostedCheck) {
     checks.push({
       name: "hosted_connection",
@@ -1303,47 +1547,118 @@ function printDoctorReport(detection, report) {
   }
   console.log("");
 }
-async function testConnection(answers) {
-  const spinner = ora("Connecting to Snipara API...").start();
+async function testHostedConnection(answers) {
+  const spinner = ora("Connecting to Snipara Hosted MCP...").start();
   try {
-    const response = await fetch(`${API_URL}/mcp/${answers.projectSlug}`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-API-Key": answers.apiKey
-      },
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        id: 1,
-        method: "tools/list",
-        params: {}
-      })
-    });
-    if (response.ok) {
-      const data = await response.json();
-      const toolCount = data.result?.tools?.length || 0;
-      spinner.succeed(`Connected! ${toolCount} MCP tools available.`);
-      return {
+    const toolsResponse = await callHostedMcp(answers, "tools/list", {});
+    if (!toolsResponse.ok) {
+      spinner.warn(`Hosted MCP returned HTTP ${toolsResponse.status}`);
+      return [
+        {
+          name: "hosted_connection",
+          status: toolsResponse.status === 401 || toolsResponse.status === 403 ? "fail" : "warn",
+          detail: describeHostedHttpFailure(toolsResponse.status, toolsResponse.bodyText)
+        }
+      ];
+    }
+    if (toolsResponse.data.error) {
+      spinner.warn("Hosted MCP tools/list returned a JSON-RPC error");
+      return [
+        {
+          name: "hosted_connection",
+          status: "warn",
+          detail: describeJsonRpcError(toolsResponse.data)
+        }
+      ];
+    }
+    const toolCount = toolsResponse.data.result?.tools?.length || 0;
+    spinner.succeed(`Connected! ${toolCount} MCP tools available.`);
+    const checks = [
+      {
         name: "hosted_connection",
         status: "pass",
-        detail: `Connected successfully (${toolCount} tools reported)`
-      };
+        detail: `tools/list succeeded (${toolCount} tools reported)`
+      }
+    ];
+    const settingsResponse = await callHostedMcp(answers, "tools/call", {
+      name: "rlm_settings",
+      arguments: {}
+    });
+    if (settingsResponse.ok && !settingsResponse.data.error) {
+      checks.push({
+        name: "hosted_settings",
+        status: "pass",
+        detail: "rlm_settings tool call succeeded"
+      });
+    } else {
+      checks.push({
+        name: "hosted_settings",
+        status: "warn",
+        detail: settingsResponse.ok ? describeJsonRpcError(settingsResponse.data) : describeHostedHttpFailure(settingsResponse.status, settingsResponse.bodyText)
+      });
     }
-    const errorText = await response.text();
-    spinner.warn(`Connection returned ${response.status}`);
-    return {
-      name: "hosted_connection",
-      status: "warn",
-      detail: `HTTP ${response.status}: ${errorText.slice(0, 120)}`
-    };
+    return checks;
   } catch (error) {
     spinner.warn(`Could not connect: ${error}`);
-    return {
-      name: "hosted_connection",
-      status: "warn",
-      detail: "Could not reach Snipara API from this machine"
-    };
+    return [
+      {
+        name: "hosted_connection",
+        status: "warn",
+        detail: "Could not reach Snipara Hosted MCP from this machine"
+      }
+    ];
+  }
+}
+async function callHostedMcp(answers, method, params) {
+  const response = await fetch(`${API_URL}/mcp/${answers.projectSlug}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": answers.apiKey
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method,
+      params
+    })
+  });
+  const bodyText = await response.text();
+  let data = {};
+  try {
+    data = bodyText ? JSON.parse(bodyText) : {};
+  } catch {
+    data = {};
+  }
+  return {
+    ok: response.ok,
+    status: response.status,
+    data,
+    bodyText
+  };
+}
+function describeHostedHttpFailure(status, bodyText) {
+  const detail = bodyText.trim().slice(0, 120);
+  if (status === 401 || status === 403) {
+    return `Auth failed (${status}). Check the project/team API key and project slug.`;
+  }
+  if (status === 404) {
+    return "Endpoint or project slug was not found. Check the hosted MCP URL.";
+  }
+  if (status === 429) {
+    return "Rate limit reached. Retry later or check plan limits.";
+  }
+  if (status >= 500) {
+    return `Hosted MCP server error (${status}). Retry later or check Snipara status.`;
   }
+  return detail ? `HTTP ${status}: ${detail}` : `HTTP ${status}`;
+}
+function describeJsonRpcError(data) {
+  if (!data.error) {
+    return "Unexpected hosted MCP response";
+  }
+  const code = data.error.code !== void 0 ? ` ${data.error.code}` : "";
+  return `JSON-RPC error${code}: ${data.error.message || "unknown error"}`;
 }
 function printSuccess(answers, report) {
   console.log(
@@ -1387,6 +1702,11 @@ function printSuccess(answers, report) {
     nextStep += 1;
   };
   printNextStep("Restart your AI client if you created or changed hosted MCP config.");
+  if (answers.aiClient === "codex") {
+    printNextStep(
+      "For Codex, merge .snipara/templates/codex-config.toml into ~/.codex/config.toml if the app does not read project .codex/config.toml."
+    );
+  }
   printNextStep("Open .snipara/companion/README.md for local commands and repair flow.");
   printNextStep("Run create-snipara doctor anytime you want a fresh local validation report.");
   if (answers.installCompanion) {
@@ -1452,9 +1772,14 @@ function detectEnvironment() {
       env: fs.existsSync(path.join(process.cwd(), ".env")),
       envLocal: fs.existsSync(path.join(process.cwd(), ".env.local")),
       envExample: fs.existsSync(path.join(process.cwd(), ".env.example")),
+      agentsMd: fs.existsSync(path.join(process.cwd(), "AGENTS.md")),
+      claudeMd: fs.existsSync(path.join(process.cwd(), "CLAUDE.md")),
+      codexConfig: fs.existsSync(path.join(process.cwd(), ".codex", "config.toml")),
+      cursorRule: fs.existsSync(path.join(process.cwd(), ".cursor", "rules", "snipara.mdc")),
       claudeDir: fs.existsSync(path.join(homedir(), ".claude")),
       cursorDir: fs.existsSync(path.join(homedir(), ".cursor")),
-      sniparaCompanionPack: fs.existsSync(path.join(process.cwd(), ".snipara", "companion"))
+      sniparaCompanionPack: fs.existsSync(path.join(process.cwd(), ".snipara", "companion")),
+      sniparaTemplates: fs.existsSync(path.join(process.cwd(), ".snipara", "templates"))
     },
     tooling: {
       node: commandExists("node"),
@@ -1507,7 +1832,7 @@ function resolveMaintenanceProfile(detection, explicitProfile) {
   if (detection.existingConfig.hasSniparaServer) {
     return "hosted-only";
   }
-  return detection.tooling.runtimeCli ? "runtime-only" : "hosted-only";
+  return "hosted-only";
 }
 function readApiKeyFromEnvFiles() {
   const candidates = [".env.local", ".env"];
@@ -1515,7 +1840,7 @@ function readApiKeyFromEnvFiles() {
     const filePath = path.join(process.cwd(), file);
     if (!fs.existsSync(filePath)) continue;
     const content = fs.readFileSync(filePath, "utf-8");
-    const match = content.match(/^SNIPARA_API_KEY=(.+)$/m);
+    const match = content.match(/^(?:SNIPARA_API_KEY|RLM_API_KEY)=(.+)$/m);
     if (match?.[1]) {
       return match[1].trim();
     }
@@ -1525,7 +1850,8 @@ function readApiKeyFromEnvFiles() {
 function detectProjectSlug() {
   try {
     const remote = execSync("git remote get-url origin", {
-      encoding: "utf-8"
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
     }).trim();
     const match = remote.match(/[/:]([^/]+?)(?:\.git)?$/);
     if (match) {
@@ -1538,7 +1864,8 @@ function detectProjectSlug() {
 function detectGitRepository() {
   try {
     const remoteUrl = execSync("git remote get-url origin", {
-      encoding: "utf-8"
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
     }).trim();
     const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/) || remoteUrl.match(/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/);
     if (!match) {
@@ -1561,7 +1888,8 @@ function detectGitRepository() {
 function detectGitBranch() {
   try {
     const branch = execSync("git branch --show-current", {
-      encoding: "utf-8"
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
     }).trim();
     if (branch) {
       return branch;
@@ -1570,7 +1898,8 @@ function detectGitBranch() {
   }
   try {
     const branch = execSync("git rev-parse --abbrev-ref HEAD", {
-      encoding: "utf-8"
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
     }).trim();
     return branch && branch !== "HEAD" ? branch : "main";
   } catch {
@@ -1588,6 +1917,9 @@ function isGitRepo() {
   }
 }
 function detectAiClient() {
+  if (fs.existsSync(path.join(process.cwd(), ".codex"))) {
+    return "codex";
+  }
   if (fs.existsSync(path.join(homedir(), ".claude")) || process.env.CLAUDE_CODE) {
     return "claude-code";
   }
@@ -1598,6 +1930,9 @@ function detectAiClient() {
   if (fs.existsSync(claudeDesktopPath)) {
     return "claude-desktop";
   }
+  if (fs.existsSync(path.join(homedir(), ".codex"))) {
+    return "codex";
+  }
   return "other";
 }
 function detectPipCommand() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-snipara",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "description": "Onboard Snipara Hosted MCP Context + Memory with auth plus optional local helper and runtime workflows",
   "main": "dist/index.js",
   "type": "module",
@@ -11,6 +11,8 @@
     "build": "tsup src/index.ts --format esm --dts --clean",
     "dev": "tsup src/index.ts --format esm --watch",
     "prepublishOnly": "npm run build",
+    "pretest": "pnpm build",
+    "test": "node --test test/*.test.cjs",
     "pack:smoke": "bash ../../scripts/smoke-node-package.sh packages/create-snipara create-snipara create-snipara --help",
     "type-check": "tsc --noEmit",
     "lint": "eslint src --ext .ts"
@@ -26,6 +28,9 @@
     "multi-agent",
     "memory",
     "claude-code",
+    "codex",
+    "chatgpt",
+    "openai",
     "cursor",
     "claude-desktop"
   ],