create-snipara 1.3.9 → 1.3.11

package/README.md

@@ -48,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
@@ -61,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
 
@@ -99,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`
@@ -134,9 +134,10 @@ The interactive flow now asks for:
 - 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.
+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:
 
@@ -154,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
@@ -247,8 +259,8 @@ 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
 
@@ -271,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
 ```
 
@@ -279,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.
@@ -352,13 +366,21 @@ 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
 
@@ -366,7 +388,7 @@ Best when the user only wants Hosted MCP Context + Memory.
 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
 
@@ -411,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.9.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.9";
+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,7 +26,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.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"
@@ -483,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",
@@ -898,11 +898,15 @@ Agent task lifecycle:
 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.
+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) {
@@ -920,8 +924,12 @@ Use Snipara Hosted MCP before answering project-specific questions.
 - 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.
 `;
@@ -944,10 +952,12 @@ This workspace uses Snipara Hosted MCP for current project context, business/cli
 - 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) {
@@ -1108,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
 `;
 }
@@ -1132,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
 `;
 }
@@ -1281,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",
@@ -1306,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."
     }
   ];
 }
@@ -1318,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
 
@@ -1384,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.
 `;
@@ -1832,7 +1876,7 @@ function resolveMaintenanceProfile(detection, explicitProfile) {
   if (detection.existingConfig.hasSniparaServer) {
     return "hosted-only";
   }
-  return "hosted-only";
+  return "hosted-companion";
 }
 function readApiKeyFromEnvFiles() {
   const candidates = [".env.local", ".env"];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-snipara",
-  "version": "1.3.9",
-  "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": {