@niroai/niro 0.3.5 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niroai/niro",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
   "keywords": [
     "niro",

package/src/mcp/setup.js

@@ -41,17 +41,27 @@ const NIRO_MD_MARKER = "<!-- niro-mcp -->";
  * own notes added below the block survive uninstall — see teardown.js removeMarkerSection).
  * Each begins with a leading "\n" because install does `existing + section`.
  */
+/**
+ * Explore-first rule, shared by every client's markdown section. Prose alone is weak, but this is the
+ * one lever some clients (Codex, Copilot CLI, Factory, OpenCode, Windsurf) have — they support no hooks,
+ * so their ONLY always-on nudge is this file. For Claude Code it reinforces the PreToolUse Grep|Glob|Read
+ * hook (NIRO_EXPLORE_COMMAND), which fires once per session/repo/branch; this stays in force for the rest
+ * of the session. Wording is imperative and names concrete tools so the agent knows what to call instead
+ * of native search.
+ */
+const NIRO_EXPLORE_FIRST_SENTENCE = "MUST FOLLOW: before you run grep, find, glob, or open a file to hunt for something, first check whether a Niro tool answers it (code_grep for content search, resolve_fqn and get_source_code for a known symbol, find_handler and find_api_endpoints for entry points). Use the connection tools (get_call_chain, get_reverse_call_chain, get_blast_radius, get_impact_analysis, get_service_topology) to understand how code connects BEFORE deciding which file to read or search next, rather than reading files to rebuild that picture by hand. Native search is the fallback for what Niro does not cover (config files, docs, logs, generated output, non-code text) or when the tools are unavailable.";
+
 const NIRO_MULTI_REPO_SENTENCE = "The temporary project answer is per (repo, BRANCH): after you create/switch a branch in a repo — and before your first edit on that branch — call should_create_temp_project with the repo's git url, its CURRENT branch, and its `.niro-project` id if present, then run `niro new-temp-project` in its folder if needs_temp_project is true. Re-check after every branch change (a `false` from another branch does NOT carry over); this applies to every repo you touch, including when the session started in a parent folder that is not itself a git repo.";
-const NIRO_CLAUDE_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP tools are available for code intelligence. Use them (call chains, blast radius, impact analysis, source lookup) before falling back to native grep/read for code questions.\nBefore adding/writing any new code, you MUST use the find_reusable_code tool from niro to figure out if there is anything reusable.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
-const NIRO_CODEX_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the \`niro-skill\` are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase; the niro-skill has the full tool-routing playbook. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
-const NIRO_WINDSURF_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the niro-skill are available. Prefer them over grep/read for questions about this codebase (structure, call chains, blast radius, impact, data flows, reuse); the niro-skill has the full routing playbook. Before writing any new code, use find_reusable_code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_CLAUDE_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP tools are available for code intelligence. Use them (call chains, blast radius, impact analysis, source lookup) before falling back to native grep/read for code questions.\nBefore adding/writing any new code, you MUST use the find_reusable_code tool from niro to figure out if there is anything reusable.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_CODEX_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the \`niro-skill\` are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase; the niro-skill has the full tool-routing playbook. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_WINDSURF_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the niro-skill are available. Prefer them over grep/read for questions about this codebase (structure, call chains, blast radius, impact, data flows, reuse); the niro-skill has the full routing playbook. Before writing any new code, use find_reusable_code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
 /**
  * Shared generic section for clients whose "always-on instructions" file has no companion
  * skill mechanism we've verified (Gemini CLI's GEMINI.md, GitHub Copilot CLI's
  * copilot-instructions.md, Factory's AGENTS.md, OpenCode's AGENTS.md) — one wording, reused
  * across those destination files (teardown matches it per-file, so reuse is safe).
  */
-const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
 
 /** All niro markdown sections — the uninstaller tries each for an exact removal. */
 const NIRO_MD_SECTIONS = [NIRO_CLAUDE_MD_SECTION, NIRO_CODEX_MD_SECTION, NIRO_WINDSURF_MD_SECTION, NIRO_GENERIC_MD_SECTION];
@@ -886,6 +896,16 @@ code — structure, behavior, impact, data/event flows, semantics — prefer the
 native grep/read. For anything outside the indexed code (config files, docs, runtime state),
 use your native tools.
 
+## Explore first — MUST FOLLOW
+
+Before you run grep, find, glob, or open a file to hunt for something, check whether a Niro
+tool answers it: \`code_grep\` for content search, \`resolve_fqn\` + \`get_source_code\` for a known
+symbol, \`find_handler\` / \`find_api_endpoints\` for entry points. Use the connection tools
+(\`get_call_chain\`, \`get_reverse_call_chain\`, \`get_blast_radius\`, \`get_impact_analysis\`,
+\`get_service_topology\`) to understand how the code connects BEFORE you decide which file to
+read or search next, instead of reading files to rebuild that picture by hand. Native search
+stays the fallback for what Niro does not cover, and when the tools are unavailable.
+
 \`project_id\` auto-resolves from a \`.niro-project\` file at the repo root — omit it. If there
 is no such file, call \`list_projects\` and pass the chosen \`project_id\`.
 
@@ -1287,6 +1307,13 @@ alwaysApply: false
 The niro MCP server exposes code-intelligence tools for this codebase. Prefer them over
 grep/read for any question answerable from the indexed code.
 
+MUST FOLLOW — explore first: before you run grep, find, glob, or open a file to hunt for
+something, check whether a niro tool answers it (code_grep, resolve_fqn + get_source_code,
+find_handler, find_api_endpoints). Use the connection tools (get_call_chain,
+get_reverse_call_chain, get_blast_radius, get_impact_analysis, get_service_topology) to see
+how the code connects BEFORE deciding which file to read or search next. Native search is the
+fallback for what niro does not cover, and when the tools are unavailable.
+
 Availability self-check FIRST — if the niro tools are not present in this session, or the
 repo is not indexed (no project resolves / a tool reports "not indexed"), fall back to
 native tools silently and do not mention Niro.
@@ -1574,6 +1601,13 @@ Niro code-intelligence MCP tools are available for the current codebase. Prefer
 grep/read for questions about structure, call chains, blast radius, impact, data flows, and
 reuse. Before writing or adding any new code, use \`find_reusable_code\` first.
 
+MUST FOLLOW — explore first: before you run grep, find, glob, or open a file to hunt for
+something, check whether a niro tool answers it (\`code_grep\`, \`resolve_fqn\` +
+\`get_source_code\`, \`find_handler\`, \`find_api_endpoints\`). Use the connection tools
+(\`get_call_chain\`, \`get_reverse_call_chain\`, \`get_blast_radius\`, \`get_impact_analysis\`,
+\`get_service_topology\`) to see how the code connects BEFORE deciding which file to read or
+search next. Native search is the fallback for what niro does not cover.
+
 If the niro tools are not present in this session, or the repo is not indexed (no project
 resolves), fall back to native tools silently — do not mention Niro's absence.
 `;
@@ -1612,6 +1646,13 @@ Niro code-intelligence MCP tools are available for the current codebase. Prefer
 grep/read for questions about structure, call chains, blast radius, impact, data flows, and
 reuse. Before writing or adding any new code, use \`find_reusable_code\` first.
 
+MUST FOLLOW — explore first: before you run grep, find, glob, or open a file to hunt for
+something, check whether a niro tool answers it (\`code_grep\`, \`resolve_fqn\` +
+\`get_source_code\`, \`find_handler\`, \`find_api_endpoints\`). Use the connection tools
+(\`get_call_chain\`, \`get_reverse_call_chain\`, \`get_blast_radius\`, \`get_impact_analysis\`,
+\`get_service_topology\`) to see how the code connects BEFORE deciding which file to read or
+search next. Native search is the fallback for what niro does not cover.
+
 If the niro tools are not present in this session, or the repo is not indexed (no project
 resolves), fall back to native tools silently — do not mention Niro's absence.
 `;
@@ -2058,6 +2099,12 @@ module.exports = {
   // Exposed for content regression tests (e.g. the cross-project routing guidance).
   NIRO_SKILL,
   NIRO_CLI_SKILL,
+  // Exposed for tests: the explore-first rule must reach EVERY client's always-on instruction surface.
+  NIRO_EXPLORE_FIRST_SENTENCE,
+  NIRO_CURSOR_RULE,
+  NIRO_CLINE_RULE,
+  NIRO_KIRO_STEERING,
+  upsertNiroMarkerSection,
   // Exposed for tests: URL resolution replaced the install-time prompt.
   resolveMcpServerUrl,
   SAAS_URL,