create-snipara 2.0.4 → 2.0.6

package/README.md

@@ -188,11 +188,12 @@ native skills should keep using `AGENTS.md`, `CLAUDE.md`, or project rules as th
 shared instruction surface.
 
 For Codex, `SNIPARA_API_KEY` is the only generated bearer token environment
-variable. If Codex lazily exposes only a minimal Snipara MCP surface after
-restart, force exact discovery for `snipara_recall`, `snipara_context_query`,
-and `snipara_settings`. Use `snipara-companion recall`, `snipara-companion
-query`, and `snipara-companion task-commit` as the reliable local fallback while
-the Codex session reloads or rediscovers tools.
+variable. If Codex exposes only the lean Snipara MCP surface after restart,
+that is expected. Use `snipara_help(query=...)` for routed guidance and
+`snipara_help(list_all=true)` to inspect specialist opt-in surfaces. Use
+`snipara-companion recall`, `snipara-companion query`, and
+`snipara-companion task-commit` as the reliable local fallback when the simple
+hosted tools are not callable.
 
 Existing root `AGENTS.md` and `CLAUDE.md` files are not replaced. The installer
 adds or refreshes a marked Snipara section so project-specific instructions stay

package/dist/index.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "2.0.4",
+  version: "2.0.6",
   description: "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   main: "dist/index.js",
   type: "module",
@@ -1492,7 +1492,7 @@ function buildSniparaOnboardingSkill(endpoint, companionPrefix) {
     "",
     `Use the Hosted MCP endpoint: \`${endpoint}\`. Keep the API key in \`SNIPARA_API_KEY\` or the client secret store. Never paste keys into tracked files, prompts, logs, screenshots, or durable memory.`,
     "",
-    "Validate availability with a tool-oriented call such as `snipara_help(list_all=true)`, `snipara_settings`, or a lightweight `snipara_context_query`. Empty MCP resources or resource templates do not prove an outage because Snipara may be exposed as a tool-only MCP server.",
+    'Validate availability with a simple tool-oriented call such as `snipara_help(query="what should I use for project context?")`, `snipara_settings`, or a lightweight `snipara_context_query`. Empty MCP resources or resource templates do not prove an outage because Snipara may be exposed as a tool-only MCP server.',
     "",
     "## Setup Steps",
     "",
@@ -1512,7 +1512,7 @@ function buildSniparaOnboardingSkill(endpoint, companionPrefix) {
     "",
     "## Failure Handling",
     "",
-    "If broad discovery shows only a partial tool surface, call `snipara_help(list_all=true)` before concluding a tool is unavailable. If the client still lags after config changes, use Companion commands as a local fallback for recall, query, and task commit until the MCP session refreshes.",
+    "If broad discovery shows only the lean default tool surface, treat that as normal. Use `snipara_help(query=...)` for routed guidance, `snipara_help(list_all=true)` to inspect specialist opt-in surfaces, and Companion commands as a local fallback for recall, query, and task commit until the MCP session refreshes.",
     ""
   ].join("\n");
 }
@@ -1733,17 +1733,13 @@ This project uses Snipara Hosted MCP for project context and reviewed memory.
 - For Codex, expose the endpoint as a streamable HTTP MCP server and load the
   key from \`SNIPARA_API_KEY\`.
 - At the start of every new thread, validate hosted MCP with a tool-oriented
-  call such as \`snipara_settings\`, \`tools/list\`, or a lightweight
+  call such as \`snipara_settings\`, \`snipara_help(query=...)\`, or a lightweight
   \`snipara_context_query\`. Do not treat empty MCP resources/templates as an
   outage because Snipara may be tool-only.
-- In Codex, if only a minimal Snipara tool subset appears, force precise tool
-  discovery for \`snipara_recall\`, \`snipara_context_query\`, and
-  \`snipara_settings\` before concluding the MCP server is incomplete.
-- If a session appears to expose only a subset of expected Snipara tools, call
-  \`snipara_help(list_all=true)\` and compare exact tool names before concluding
-  that a tool is unavailable. Do not infer absence from one broad discovery
-  pass or a ranked tool-search result.
-- If Codex still exposes only a partial surface after exact discovery, use
+- In Codex, a lean Snipara tool set is expected. Use \`snipara_help(query=...)\`
+  for routed guidance and \`snipara_help(list_all=true)\` to inspect specialist
+  opt-in surfaces before requesting expanded schemas.
+- If Codex still cannot call the simple context or memory tools, use
   \`snipara-companion recall\`, \`snipara-companion query\`, and
   \`snipara-companion task-commit\` as the reliable local fallback, then restart
   or reload Codex after MCP config changes.
@@ -1758,7 +1754,9 @@ Agent task lifecycle:
 1. Start every new thread by validating hosted MCP availability, then use
    project-scoped \`snipara_recall\` and a targeted \`snipara_context_query\` before
    falling back to local documentation search.
-2. Use \`snipara_context_query\` for docs, business context, client/project truth, architecture notes, runbooks, and narrative source material.
+2. Use \`snipara_context_query\` for docs, business context, client/project truth,
+   architecture notes, runbooks, and narrative source material. Keep simple Q&A
+   and single-source lookups on a targeted \`snipara_context_query\`.
 3. When \`snipara_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 \`snipara_get_chunk\` to load cited source sections returned by reference-based queries before relying on precise wording.
 5. For coding tasks, choose a workflow mode before editing: LITE for small
@@ -1771,8 +1769,11 @@ Agent task lifecycle:
    context and \`snipara-companion code impact\` before risky multi-file changes, PR
    reviews, routes, services, jobs, auth, billing, deployment, schema, migrations,
    or explicit "what is missing" assessments.
-8. Use \`snipara_plan\` for complex work in any plan when exposed; reserve
-   \`snipara_decompose\` for FULL-mode work when the hosted server exposes it.
+8. Use \`snipara_plan\` for complex or multi-surface work in any plan when
+   exposed. For FULL-mode audits, comparisons, roadmap/implementation planning,
+   release readiness, or package-surface reviews, use \`snipara_decompose\` to
+   preserve the work axes and \`snipara_multi_query\` to execute independent
+   follow-up questions when Pro+ tools are exposed.
 9. When the LLM has produced a visible multi-phase plan and \`snipara-companion\`
    is installed, keep the machine plan in JSON and run
    \`snipara-companion workflow start --goal "<goal>" --plan-file <plan_json_file>\`.
@@ -1818,8 +1819,8 @@ Use Snipara Hosted MCP before answering project-specific questions.
 
 - Endpoint: \`${buildHostedMcpEndpoint(answers)}\`
 - Auth: use \`SNIPARA_API_KEY\` from the environment. Never commit keys.
-- At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`tools/list\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
-- If a session exposes only a subset of expected Snipara tools, call \`snipara_help(list_all=true)\` and compare exact tool names before concluding a tool is unavailable. If only a partial surface remains after exact discovery, use \`snipara-companion recall\`, \`snipara-companion query\`, and \`snipara-companion task-commit\` as a reliable local fallback.
+- At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`snipara_help(query=...)\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
+- A lean default Snipara tool set is expected. Use \`snipara_help(query=...)\` for routed guidance, \`snipara_help(list_all=true)\` to inspect specialist opt-in surfaces, and \`snipara-companion recall\`, \`snipara-companion query\`, or \`snipara-companion task-commit\` as local fallbacks when the simple tools are unavailable.
 - If the client supports native skills, install the generated Snipara skill pack from \`.snipara/templates/skills\`. Keep \`AGENTS.md\` as the shared fallback for clients without native skill support.
 
 ${EXPERIENCE_GOAL_SECTION}
@@ -1828,7 +1829,7 @@ ${EXPERIENCE_GOAL_SECTION}
 - Use \`snipara_context_query\` for source truth and \`snipara_get_chunk\` for exact cited sections.
 - When \`snipara_context_query\` returns \`answer_pack\`, use its facts, caveats, source map, and verification checklist before drafting claims.
 - For coding tasks, choose a workflow mode before editing: LITE for small single-phase changes, FULL managed workflow for multi-file, risky, release/deploy, architectural, compaction-prone, or future-maintainer-sensitive work.
-- Use \`snipara_plan\` for complex work when exposed; reserve \`snipara_decompose\` for FULL-mode work when the hosted server exposes it.
+- Use \`snipara_plan\` for complex or multi-surface work when exposed. Keep simple Q&A on targeted \`snipara_context_query\`; for FULL-mode audits, comparisons, roadmap/implementation planning, release readiness, or package-surface reviews, use \`snipara_decompose\` to preserve axes and \`snipara_multi_query\` for independent follow-up questions when Pro+ tools are exposed.
 - Use \`snipara_code_callers\`, \`snipara_code_imports\`, \`snipara_code_neighbors\`, or \`snipara_code_shortest_path\` for canonical structural code questions.
 - For code impact and structural code questions, use \`snipara-companion code callers/imports/neighbors/shortest-path/impact\` first when \`snipara-companion\` is installed; it auto-selects hosted MCP for clean indexed code or the local overlay for dirty/ahead worktrees and reports \`sourceSelection\`. Use hosted \`snipara_code_impact\` only when companion is unavailable or after push/reindex for canonical graph impact.
 - Run \`snipara-companion code impact\` before risky multi-file changes, PR reviews, routes, services, jobs, auth, billing, deployment, schema, migrations, or explicit "what is missing" assessments.
@@ -1858,8 +1859,8 @@ This workspace uses Snipara Hosted MCP for current project context, business/cli
 
 - Check the configured Snipara MCP server before answering project-specific questions.
 - Endpoint: \`${buildHostedMcpEndpoint(answers)}\`
-- At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`tools/list\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
-- If a session exposes only a subset of expected Snipara tools, call \`snipara_help(list_all=true)\` and compare exact tool names before concluding a tool is unavailable. If only a partial surface remains after exact discovery, use \`snipara-companion recall\`, \`snipara-companion query\`, and \`snipara-companion task-commit\` as a reliable local fallback.
+- At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`snipara_help(query=...)\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
+- A lean default Snipara tool set is expected. Use \`snipara_help(query=...)\` for routed guidance, \`snipara_help(list_all=true)\` to inspect specialist opt-in surfaces, and \`snipara-companion recall\`, \`snipara-companion query\`, or \`snipara-companion task-commit\` as local fallbacks when the simple tools are unavailable.
 - If the client supports native skills, install the generated Snipara skill pack from \`.snipara/templates/skills\`. Keep \`AGENTS.md\` as the shared fallback for clients without native skill support.
 
 ${EXPERIENCE_GOAL_SECTION}
@@ -1874,7 +1875,7 @@ ${EXPERIENCE_GOAL_SECTION}
 - Run \`snipara-companion code impact\` before risky multi-file changes, PR reviews, routes, services, jobs, auth, billing, deployment, schema, migrations, or explicit "what is missing" assessments.
 - On paid Context plans, use \`snipara_code_symbol_card\` before editing important symbols.
 - Check every \`snipara_code_*\` response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings.
-- Use \`snipara_plan\` for complex work when available; use \`snipara_decompose\` when deeper decomposition is needed and the hosted server exposes it.
+- Use \`snipara_plan\` for complex or multi-surface work when available. Keep simple Q&A on targeted \`snipara_context_query\`; for FULL-mode audits, comparisons, roadmap/implementation planning, release readiness, or package-surface reviews, use \`snipara_decompose\` to preserve axes and \`snipara_multi_query\` for independent follow-up questions when Pro+ tools are exposed.
 - Use local file reads, \`rg\`, \`git status --short\`, and tests for exact code edits and current working-tree state.
 - If a broad query is slow, retry once with a narrow keyword query before falling back to local search.
 - When \`snipara-companion\` is installed and the LLM has a visible multi-phase plan, keep the machine plan in JSON, use \`snipara-companion workflow start\`, \`phase-start\`, and \`phase-commit\` per phase, and after \`workflow resume\` rerun \`workflow phase-start\` before editing again.
@@ -2536,8 +2537,8 @@ function getClientGuidance(client) {
       "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.",
       "Use SNIPARA_API_KEY as the only Codex bearer_token_env_var; restart Codex after changing MCP config.",
-      "If Codex lazily exposes only a minimal tool set, force discovery for snipara_recall, snipara_context_query, snipara_settings, and the exact htask or swarm tool names you need; use snipara_help(list_all=true) to confirm the hosted catalog before concluding the MCP surface is incomplete.",
-      "When Codex still exposes only the minimal core tools, use snipara-orchestrator swarm-* and htask-* as the primary path for shared queues and multi-agent task work."
+      "If Codex exposes only the lean Snipara tool set, that is expected. Use snipara_help(query=...) for routed guidance and snipara_help(list_all=true) to inspect specialist opt-in surfaces before requesting exact htask or swarm schemas.",
+      "When Codex cannot expose orchestration schemas directly, use snipara-orchestrator swarm-* and htask-* as the primary path for shared queues and multi-agent task work."
     ];
   }
   if (client === "gemini") {
@@ -2835,12 +2836,12 @@ ${guidance.map((line) => `- ${line}`).join("\n")}
 
 ## Agent Workflow
 
-- At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`tools/list\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
-- If a session exposes only a subset of expected Snipara tools, call \`snipara_help(list_all=true)\` and compare exact tool names before concluding a tool is unavailable. If only a partial surface remains after exact discovery, use \`snipara-companion recall\`, \`snipara-companion query\`, and \`snipara-companion task-commit\` as a reliable local fallback.
+- At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`snipara_help(query=...)\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
+- A lean default Snipara tool set is expected. Use \`snipara_help(query=...)\` for routed guidance, \`snipara_help(list_all=true)\` to inspect specialist opt-in surfaces, and \`snipara-companion recall\`, \`snipara-companion query\`, or \`snipara-companion task-commit\` as local fallbacks when the simple tools are unavailable.
 - Start substantial work with \`snipara_recall\` and \`snipara_context_query\`.
 - Use \`answer_pack\` facts, caveats, source maps, and verification checks before making claims.
 - For coding tasks, choose a workflow mode before editing: LITE for small single-phase changes, FULL managed workflow for multi-file, risky, release/deploy, architectural, compaction-prone, or future-maintainer-sensitive work.
-- Use \`snipara_plan\` for complex work when exposed; reserve \`snipara_decompose\` for FULL-mode work when the hosted server exposes it.
+- Use \`snipara_plan\` for complex or multi-surface work when exposed. Keep simple Q&A on targeted \`snipara_context_query\`; for FULL-mode audits, comparisons, roadmap/implementation planning, release readiness, or package-surface reviews, use \`snipara_decompose\` to preserve axes and \`snipara_multi_query\` for independent follow-up questions when Pro+ tools are exposed.
 - Use \`snipara_code_symbol_card\` for important symbols. For risky multi-file changes, PR reviews, routes, services, jobs, auth, billing, deployment, schema, migrations, or explicit "what is missing" assessments, use \`snipara-companion code impact\` first when companion is available; use hosted \`snipara_code_impact\` only when companion is unavailable or after push/reindex for canonical graph impact.
 - Use the installed \`snipara-companion\` binary for low-latency hooks; use \`${COMPANION_NPX_COMMAND}\` for one-off terminal commands when freshness matters.
 - If a broad query is slow, retry once with a narrow keyword query before falling back to local search.
@@ -3707,7 +3708,7 @@ function printSuccess(answers, report) {
       "Restart Codex after changing ~/.codex/config.toml so it rediscovers the hosted Snipara MCP tools."
     );
     printNextStep(
-      "If Codex shows only a minimal Snipara tool set, force discovery for snipara_recall, snipara_context_query, snipara_settings, and any exact htask or swarm tool names you need; confirm the hosted catalog with snipara_help(list_all=true)."
+      "If Codex shows only the lean Snipara tool set, that is expected. Use snipara_help(query=...) for routed guidance, confirm specialist opt-in surfaces with snipara_help(list_all=true), and request exact htask or swarm tools only when the workflow explicitly needs them."
     );
     printNextStep(
       "If Codex still does not expose the hosted task-routing tools, prefer snipara-orchestrator swarm-* and htask-* for shared queue or multi-agent task work."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-snipara",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   "main": "dist/index.js",
   "type": "module",