create-snipara 1.3.7 → 1.3.8

package/README.md

@@ -46,7 +46,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 +76,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`
@@ -111,6 +113,14 @@ The interactive flow now asks for:
 - 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
@@ -367,7 +377,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.8.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.8";
 var BASE_URL = "https://www.snipara.com";
 var API_URL = "https://api.snipara.com";
 var COMPANION_PACKAGE_NAME = "snipara-companion";
@@ -78,6 +78,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 +114,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 +142,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 });
   }
@@ -282,7 +285,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 +299,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",
@@ -744,6 +759,159 @@ 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. Use \`rlm_get_chunk\` to load cited source sections returned by reference-based queries before relying on precise wording.
+4. Use \`rlm_code_callers\`, \`rlm_code_imports\`, \`rlm_code_neighbors\`, or \`rlm_code_shortest_path\` for structural code questions.
+5. 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.
+6. Use \`rlm_plan\` or \`rlm_decompose\` only for complex work and only when the hosted server exposes them.
+7. Use local file reads, \`rg\`, git commands, and test commands for exact edits, current working-tree state, and verification.
+8. Use RLM Runtime only when sandboxed execution, repeatable validation, or isolated transformations materially help.
+9. If a broad query is slow, retry once with a narrow keyword query before falling back to local search.
+10. 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.
+11. 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.
+- 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.
+- 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 +1146,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 can be merged into ~/.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 +1433,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",
@@ -1452,9 +1637,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"),
@@ -1588,6 +1778,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 +1791,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.8",
   "description": "Onboard Snipara Hosted MCP Context + Memory with auth plus optional local helper and runtime workflows",
   "main": "dist/index.js",
   "type": "module",
@@ -26,6 +26,9 @@
     "multi-agent",
     "memory",
     "claude-code",
+    "codex",
+    "chatgpt",
+    "openai",
     "cursor",
     "claude-desktop"
   ],