create-snipara 1.3.8 → 1.3.11

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:
@@ -22,9 +48,9 @@ The product surfaces remain:
 - Hosted MCP for LLM agents, context, and reviewed memory
 - HTTP API / SDK for apps, integrators, backends, and pipelines
 
-The CLI can wire local helpers around those surfaces:
+The default CLI path wires the local companion around those surfaces:
 
-- `snipara-companion` for local `rlm-hook` workflows when you want them
+- `snipara-companion` for local `rlm-hook` workflows and managed phase commits
 - `rlm-runtime` for optional local code execution
 - local config, env files, hook scripts, and a project companion pack
 - `snipara-mcp` only for local stdio compatibility, development, or testing
@@ -35,12 +61,12 @@ The CLI now works around explicit install profiles:
 
 | Profile            | What it installs                          | Best for                                            |
 | ------------------ | ----------------------------------------- | --------------------------------------------------- |
-| `hosted-only`      | Hosted MCP config only                    | Default: agents without local helper workflows      |
-| `hosted-companion` | MCP + `snipara-companion`                 | Hook-heavy clients that want local helper workflows |
-| `full-stack`       | MCP + `snipara-companion` + `rlm-runtime` | Hosted context plus local execution                 |
+| `hosted-companion` | MCP + `snipara-companion`                 | Default: hosted context plus managed local workflow |
+| `hosted-only`      | Hosted MCP config only                    | Locked-down or minimal environments                 |
+| `full-stack`       | MCP + `snipara-companion` + `rlm-runtime` | Hosted context plus sandboxed local execution       |
 | `runtime-only`     | `rlm-runtime` only                        | Local execution without hosted API                  |
 
-Default profile: `hosted-only`
+Default profile: `hosted-companion`
 
 ## Free Account Fit
 
@@ -73,10 +99,10 @@ That distinction matters:
 - opens the browser device-flow free Context + Memory account flow when needed
 - writes Hosted MCP configuration
 - detects a GitHub remote and can open the Snipara GitHub App automation path
-- installs `snipara-companion` when the selected profile needs local helper workflows
+- installs `snipara-companion` by default for local managed 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
+- generates merge-ready AI agent templates in `.snipara/templates/`, including Pro+ symbol-card, code-impact, and managed workflow 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`
@@ -104,11 +130,19 @@ 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 uses the recommended `hosted-companion` setup: hosted MCP plus
+the local `rlm-hook` workflow helper. 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
@@ -121,6 +155,17 @@ The generated agent templates cover:
 - Codex `.codex/config.toml` snippet
 - ChatGPT/OpenAI HTTP MCP snippet
 
+When `snipara-companion` is installed, the companion pack also includes the compaction-safe managed workflow:
+
+```bash
+rlm-hook workflow start --goal "ship auth hardening" --plan-file ./plan.md
+rlm-hook workflow phase-start context
+rlm-hook workflow run --mode full --include-session-context --query "load auth context"
+rlm-hook code impact --changed-files src/auth.ts tests/auth.test.ts --diff-summary "auth hardening"
+rlm-hook workflow phase-commit context --summary "Loaded context and mapped impacted files" --files src/auth.ts
+rlm-hook final-commit --summary "Shipped auth hardening and tests" --files src/auth.ts tests/auth.test.ts
+```
+
 ## Main Commands
 
 ### Install or initialize
@@ -214,9 +259,10 @@ That keeps business truth review separate from agent onboarding.
 
 ```bash
 # Use an explicit install profile
-npx create-snipara --profile hosted-only
 npx create-snipara --profile hosted-companion
+npx create-snipara --profile hosted-only
 npx create-snipara --profile full-stack
+npx create-snipara --advanced
 
 # Runtime-only local execution
 npx create-snipara --runtime-only
@@ -237,6 +283,7 @@ npx create-snipara --skip-github
 
 # Force extra layers during maintenance
 npx create-snipara repair --with-hooks
+npx create-snipara repair --with-runtime
 npx create-snipara upgrade --with-runtime
 ```
 
@@ -245,18 +292,19 @@ npx create-snipara upgrade --with-runtime
 The intended split is:
 
 - `create-snipara`: Context + Memory onboarding, auth, config, inspect, repair, and upgrade
-- `snipara-companion`: optional ongoing local runtime workflows through `rlm-hook`
+- `snipara-companion`: default local workflow helper through `rlm-hook`; optional only for `hosted-only`
 - `snipara-mcp`: local stdio bridge, client-package development, compatibility, and testing
 - `rlm-runtime`: optional local execution engine
 
 ## Codex Setup
 
-For Codex, keep the setup minimal:
+For Codex, keep Hosted MCP as the core path and let companion add workflow
+ergonomics:
 
 - use Hosted MCP as the core Snipara surface
 - use `AGENTS.md` for project instructions
-- choose `hosted-only` if you do not need local helper workflows
-- add `snipara-companion` only if you explicitly want the local helper CLI
+- use the default `hosted-companion` path when you want compaction-safe local phase commits
+- choose `hosted-only` or `--skip-companion` only in locked-down environments
 - use local `snipara-mcp` only for stdio compatibility, development, or tests
 
 Codex does not require hook presets to use Snipara successfully.
@@ -318,21 +366,29 @@ Recommended explanation to users:
 
 ## Example Flows
 
-### Default hosted setup
+### Default managed hosted setup
+
+```bash
+npx create-snipara
+```
+
+Best when the user wants Hosted MCP Context + Memory plus `rlm-hook` managed workflows.
+
+### Minimal hosted setup
 
 ```bash
 npx create-snipara --profile hosted-only
 ```
 
-Best when the user only wants Hosted MCP Context + Memory.
+Best when the user only wants Hosted MCP Context + Memory and cannot install local helper tooling.
 
 ### 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`.
+Best when the user also wants sandboxed `rlm-runtime` execution.
 
 ### Connect the current repository
 
@@ -377,7 +433,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.8.tgz create-snipara -- --help
+npm exec --package ./create-snipara-1.3.11.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.8";
+var VERSION = "1.3.11";
 var BASE_URL = "https://www.snipara.com";
 var API_URL = "https://api.snipara.com";
 var COMPANION_PACKAGE_NAME = "snipara-companion";
@@ -26,8 +26,8 @@ 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.name("create-snipara").description("Scaffold hosted Snipara MCP config plus companion workflow helpers").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("--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);
   }
@@ -198,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(
@@ -230,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),
@@ -244,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 || ""
@@ -318,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 || ""
@@ -354,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,
@@ -427,27 +483,27 @@ function resolveRequestedProfile(options) {
   if (options.profile && isInstallProfile(options.profile)) {
     return options.profile;
   }
-  return "hosted-only";
+  return "hosted-companion";
 }
 function isInstallProfile(value) {
   return ["hosted-only", "hosted-companion", "full-stack", "runtime-only"].includes(value);
 }
 function installProfileChoices() {
   return [
-    {
-      title: "Hosted only",
-      value: "hosted-only",
-      description: "Default: hosted MCP config, no local companion or runtime"
-    },
     {
       title: "Hosted + Companion",
       value: "hosted-companion",
-      description: "Hosted MCP config plus optional local companion workflows"
+      description: "Default: hosted MCP config plus managed local workflow commands"
+    },
+    {
+      title: "Hosted only",
+      value: "hosted-only",
+      description: "Minimal setup: hosted MCP config, no local companion or runtime"
     },
     {
       title: "Hosted + Companion + Runtime",
       value: "full-stack",
-      description: "Add local runtime execution as well"
+      description: "Add sandboxed local runtime execution as well"
     },
     {
       title: "Runtime only",
@@ -837,15 +893,20 @@ 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.
+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. When the LLM has produced a visible multi-phase plan and \`snipara-companion\` is installed, run \`rlm-hook workflow start --goal "<goal>" --plan-file <plan_file>\`, then use \`workflow phase-start\`, \`workflow phase-commit\`, \`workflow resume\`, and \`final-commit\` so compaction cannot lose the next phase.
+9. Use local file reads, \`rg\`, git commands, and test commands for exact edits, current working-tree state, and verification.
+10. Treat every \`rlm_code_*\` response as indexed context: check its indexed commit SHA, indexing time, included file sample, coverage, freshness warnings, and sync guidance before relying on it.
+11. If \`git status --short\` is dirty, warn that Snipara's indexed code graph may not include local edits; use local reads/tests for exact edits and Snipara for architecture/code graph context.
+12. Use RLM Runtime only when sandboxed execution, repeatable validation, or isolated transformations materially help.
+13. If a broad query is slow, retry once with a narrow keyword query before falling back to local search.
+14. End each substantial phase with \`rlm_end_of_task_commit\` or \`rlm-hook workflow phase-commit\` when companion manages the plan. End the whole managed workflow with \`rlm-hook final-commit\`.
+15. Use \`rlm_remember_if_novel\` for one reusable memory while avoiding duplicates, and use \`rlm_remember\` for explicit direct memory writes.
+16. Do not store secrets, tokens, passwords, private keys, raw logs, transient command output, or unreviewed guesses in memory.
 `;
 }
 function buildClaudeMdTemplate(answers) {
@@ -860,10 +921,15 @@ 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.
+- Check every \`rlm_code_*\` response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings.
+- Use local file reads, \`rg\`, \`git status --short\`, and tests for exact edits/current working tree; use Snipara for architecture and indexed code graph context.
+- When the plan is visible and \`snipara-companion\` is installed, use \`rlm-hook workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` to keep phase state durable across compaction.
 - 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.
+- End substantial work with \`rlm_end_of_task_commit\` when available; for managed workflows, end every phase with \`rlm-hook workflow phase-commit\` and the task with \`rlm-hook final-commit\`.
+- 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.
 `;
@@ -882,13 +948,16 @@ This workspace uses Snipara Hosted MCP for current project context, business/cli
 - 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.
+- Check every \`rlm_code_*\` response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings.
 - 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 local file reads, \`rg\`, \`git status --short\`, and tests for exact code edits and current working-tree state.
+- When \`snipara-companion\` is installed and the LLM has a visible multi-phase plan, use \`rlm-hook workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` so the next phase survives compaction.
 - 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.
+- End substantial work with \`rlm_end_of_task_commit\` when available; for managed workflows, end every phase with \`rlm-hook workflow phase-commit\` and the task with \`rlm-hook final-commit\`. Use \`rlm_remember_if_novel\` or \`rlm_remember\` only for narrow durable memories. Never store secrets.
 `;
 }
 function buildCodexConfigTemplate(answers) {
@@ -1049,7 +1118,11 @@ export SNIPARA_PROJECT_SLUG="${answers.projectSlug}"
 ${answers.projectId ? `export SNIPARA_PROJECT_ID="${answers.projectId}"` : ""}
 
 if command -v rlm-hook >/dev/null 2>&1; then
-  rlm-hook session-bootstrap || true
+  if [ -f ".snipara/workflow/current.json" ]; then
+    rlm-hook workflow resume --include-session-context || true
+  else
+    rlm-hook session-bootstrap || true
+  fi
 fi
 `;
 }
@@ -1073,7 +1146,11 @@ export SNIPARA_PROJECT_SLUG="${answers.projectSlug}"
 ${answers.projectId ? `export SNIPARA_PROJECT_ID="${answers.projectId}"` : ""}
 
 if command -v rlm-hook >/dev/null 2>&1; then
-  rlm-hook task-commit --summary "Claude Code compacted local session context" --outcome partial || true
+  if [ -f ".snipara/workflow/current.json" ]; then
+    rlm-hook task-commit --summary "Claude Code compacted while a managed workflow state existed. Resume with rlm-hook workflow resume --include-session-context and continue from .snipara/workflow/current.json." --category workflow-compaction --outcome partial || true
+  else
+    rlm-hook task-commit --summary "Claude Code compacted local session context" --outcome partial || true
+  fi
 fi
 `;
 }
@@ -1149,7 +1226,7 @@ function getClientGuidance(client) {
   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."
+      "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") {
@@ -1222,6 +1299,21 @@ function getCompanionCommands(answers) {
       command: 'rlm-hook plan --query "Implement webhook retry hardening" --max-tokens 3000',
       purpose: "Produce a structured execution plan against indexed project knowledge."
     },
+    {
+      title: "Start a managed workflow from the visible plan",
+      command: 'rlm-hook workflow start --goal "Implement webhook retry hardening" --plan-file ./plan.md',
+      purpose: "Record the LLM-visible plan in .snipara/workflow/current.json so phase state survives compaction."
+    },
+    {
+      title: "Start the current workflow phase",
+      command: "rlm-hook workflow phase-start context",
+      purpose: "Mark a phase active and print the required Snipara context gate for the agent."
+    },
+    {
+      title: "Analyze code impact before a risky change",
+      command: 'rlm-hook code impact --changed-files src/api/webhooks.ts tests/webhooks.test.ts --diff-summary "webhook retry hardening"',
+      purpose: "Use paid Context code impact analysis to surface likely tests, docs, routes, config, and risks."
+    },
     {
       title: "Upload or refresh a doc",
       command: "rlm-hook upload --path docs/local-playbook.md --file ./docs/local-playbook.md",
@@ -1247,6 +1339,16 @@ function getCompanionCommands(answers) {
       title: "Commit durable task memory",
       command: 'rlm-hook task-commit --summary "Hardened webhook retries and updated tests" --category engineering --outcome completed --files src/api/webhooks.ts tests/webhooks.test.ts',
       purpose: "Persist reusable outcomes back into hosted memory after the work is done."
+    },
+    {
+      title: "Commit a managed workflow phase",
+      command: 'rlm-hook workflow phase-commit context --summary "Loaded context and mapped impacted files" --files src/api/webhooks.ts tests/webhooks.test.ts',
+      purpose: "Persist this phase through hosted memory and advance the local managed workflow state."
+    },
+    {
+      title: "Commit the final managed workflow result",
+      command: 'rlm-hook final-commit --summary "Shipped webhook retry hardening and tests" --files src/api/webhooks.ts tests/webhooks.test.ts',
+      purpose: "Persist the final workflow outcome and close the managed workflow after verification."
     }
   ];
 }
@@ -1259,7 +1361,7 @@ async function createCompanionPack(answers) {
   fs.mkdirSync(packDir, { recursive: true });
   const readme = `# Snipara Companion Pack
 
-This project uses Snipara as a hosted-first context and memory layer with an optional local companion CLI.
+This project uses Snipara as a hosted-first context and memory layer with local companion workflow helpers.
 
 ## Install Profile
 
@@ -1325,6 +1427,7 @@ ${item.purpose}`
 
 - Context first: use hosted queries, shared-context, and document loads for source truth.
 - Memory second: use session bootstrap and task commit for durable decisions, learnings, and preferences.
+- Managed workflow when a visible plan exists: \`workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` keep phase state durable across compaction.
 - Durable memory, policy, and orchestration stay hosted in Snipara.
 - The local companion is optional tooling for capture, bootstrap, upload, exploration, doctor, repair, and explicit task summaries.
 `;
@@ -1449,7 +1552,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",
@@ -1488,47 +1591,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(
@@ -1572,6 +1746,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) {
@@ -1697,7 +1876,7 @@ function resolveMaintenanceProfile(detection, explicitProfile) {
   if (detection.existingConfig.hasSniparaServer) {
     return "hosted-only";
   }
-  return detection.tooling.runtimeCli ? "runtime-only" : "hosted-only";
+  return "hosted-companion";
 }
 function readApiKeyFromEnvFiles() {
   const candidates = [".env.local", ".env"];
@@ -1705,7 +1884,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();
     }
@@ -1715,7 +1894,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) {
@@ -1728,7 +1908,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) {
@@ -1751,7 +1932,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;
@@ -1760,7 +1942,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 {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-snipara",
-  "version": "1.3.8",
-  "description": "Onboard Snipara Hosted MCP Context + Memory with auth plus optional local helper and runtime workflows",
+  "version": "1.3.11",
+  "description": "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional runtime",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -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"