grepmax 0.17.18 → 0.17.19

package/dist/commands/dead.js

@@ -46,6 +46,7 @@ exports.dead = void 0;
 const commander_1 = require("commander");
 const graph_builder_1 = require("../lib/graph/graph-builder");
 const vector_db_1 = require("../lib/store/vector-db");
+const agent_errors_1 = require("../lib/utils/agent-errors");
 const exit_1 = require("../lib/utils/exit");
 const filter_builder_1 = require("../lib/utils/filter-builder");
 const project_registry_1 = require("../lib/utils/project-registry");
@@ -134,7 +135,7 @@ exports.dead = new commander_1.Command("dead")
             .limit(1)
             .toArray();
         if (defRows.length === 0) {
-            console.log(opts.agent ? "(not found)" : `Symbol not found: ${symbol}`);
+            console.log((0, agent_errors_1.symbolNotFoundLines)(symbol, { agent: opts.agent }).join("\n"));
             process.exitCode = 1;
             return;
         }

package/dist/commands/extract.js

@@ -46,6 +46,7 @@ exports.extract = void 0;
 const fs = __importStar(require("node:fs"));
 const commander_1 = require("commander");
 const vector_db_1 = require("../lib/store/vector-db");
+const agent_errors_1 = require("../lib/utils/agent-errors");
 const exit_1 = require("../lib/utils/exit");
 const filter_builder_1 = require("../lib/utils/filter-builder");
 const import_extractor_1 = require("../lib/utils/import-extractor");
@@ -130,13 +131,11 @@ exports.extract = new commander_1.Command("extract")
         const where = buildScopeWhere(scope, `array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(symbol)}')`);
         const chunks = yield findSymbolChunks(vectorDb, where);
         if (chunks.length === 0) {
-            const lines = [
-                `Symbol not found: ${opts.agent ? symbol : style.bold(symbol)}`,
-            ];
-            if (!opts.agent) {
-                lines.push("", style.dim("Possible reasons:"), style.dim("  \u2022 The symbol doesn't exist in any indexed project"), style.dim("  \u2022 The containing file hasn't been indexed yet"), style.dim("  \u2022 The name is spelled differently in the source"), "", style.dim("Try:"), style.dim("  gmax status          \u2014 see which projects are indexed"), style.dim("  gmax search <name>   \u2014 fuzzy search for similar symbols"));
-            }
-            console.log(lines.join("\n"));
+            console.log((0, agent_errors_1.symbolNotFoundLines)(symbol, {
+                agent: opts.agent,
+                dim: style.dim,
+                bold: style.bold,
+            }).join("\n"));
             process.exitCode = 1;
             return;
         }

package/dist/commands/help-agent.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.helpAgent = void 0;
+const commander_1 = require("commander");
+const agent_cheatsheet_1 = require("../lib/help/agent-cheatsheet");
+exports.helpAgent = new commander_1.Command("help-agent")
+    .description("Print the agent command cheatsheet (re-summon the SessionStart hint on demand)")
+    .addHelpText("after", `
+The same survey injected at SessionStart. Useful when a long session has
+compacted away the original hint and you need to re-discover the commands.`)
+    .action(() => {
+    process.stdout.write(`${agent_cheatsheet_1.AGENT_CHEATSHEET}\n`);
+});

package/dist/commands/impact.js

@@ -47,6 +47,7 @@ const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const impact_1 = require("../lib/graph/impact");
 const vector_db_1 = require("../lib/store/vector-db");
+const agent_errors_1 = require("../lib/utils/agent-errors");
 const exit_1 = require("../lib/utils/exit");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
@@ -73,7 +74,7 @@ exports.impact = new commander_1.Command("impact")
         if (symbols.length === 0) {
             console.log(resolvedAsFile
                 ? `No symbols found in file: ${target}`
-                : `Symbol not found: ${target}`);
+                : (0, agent_errors_1.symbolNotFoundLines)(target, { agent: opts.agent }).join("\n"));
             process.exitCode = 1;
             return;
         }

package/dist/commands/peek.js

@@ -47,6 +47,7 @@ const fs = __importStar(require("node:fs"));
 const commander_1 = require("commander");
 const graph_builder_1 = require("../lib/graph/graph-builder");
 const vector_db_1 = require("../lib/store/vector-db");
+const agent_errors_1 = require("../lib/utils/agent-errors");
 const exit_1 = require("../lib/utils/exit");
 const filter_builder_1 = require("../lib/utils/filter-builder");
 const language_1 = require("../lib/utils/language");
@@ -152,13 +153,11 @@ exports.peek = new commander_1.Command("peek")
         const graphBuilder = new graph_builder_1.GraphBuilder(vectorDb, scope.pathPrefix, scope.excludePrefixes);
         const graph = yield graphBuilder.buildGraph(symbol);
         if (!graph.center) {
-            const lines = [
-                `Symbol not found: ${opts.agent ? symbol : style.bold(symbol)}`,
-            ];
-            if (!opts.agent) {
-                lines.push("", style.dim("Possible reasons:"), style.dim("  \u2022 The symbol doesn't exist in any indexed project"), style.dim("  \u2022 The containing file hasn't been indexed yet"), style.dim("  \u2022 The name is spelled differently in the source"), "", style.dim("Try:"), style.dim("  gmax status          \u2014 see which projects are indexed"), style.dim("  gmax search <name>   \u2014 fuzzy search for similar symbols"));
-            }
-            console.log(lines.join("\n"));
+            console.log((0, agent_errors_1.symbolNotFoundLines)(symbol, {
+                agent: opts.agent,
+                dim: style.dim,
+                bold: style.bold,
+            }).join("\n"));
             process.exitCode = 1;
             return;
         }

package/dist/commands/related.js

@@ -46,6 +46,7 @@ exports.related = void 0;
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const vector_db_1 = require("../lib/store/vector-db");
+const agent_errors_1 = require("../lib/utils/agent-errors");
 const filter_builder_1 = require("../lib/utils/filter-builder");
 const exit_1 = require("../lib/utils/exit");
 const project_registry_1 = require("../lib/utils/project-registry");
@@ -85,8 +86,7 @@ exports.related = new commander_1.Command("related")
             .where(`path = '${(0, filter_builder_1.escapeSqlString)(absPath)}'`)
             .toArray();
         if (fileChunks.length === 0) {
-            console.log(`File not found in index: ${file}`);
-            console.log("\nCheck that the path is relative to the project root. Run `gmax status` to see indexed projects.");
+            console.log((0, agent_errors_1.fileNotFoundLines)(file, { agent: opts.agent }).join("\n"));
             process.exitCode = 1;
             return;
         }

package/dist/commands/similar.js

@@ -46,6 +46,7 @@ exports.similar = void 0;
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const vector_db_1 = require("../lib/store/vector-db");
+const agent_errors_1 = require("../lib/utils/agent-errors");
 const filter_builder_1 = require("../lib/utils/filter-builder");
 const exit_1 = require("../lib/utils/exit");
 const project_registry_1 = require("../lib/utils/project-registry");
@@ -96,9 +97,9 @@ exports.similar = new commander_1.Command("similar")
                 .toArray();
         }
         if (sourceRows.length === 0) {
-            console.log(isFile
-                ? `File not found in index: ${target}`
-                : `Symbol not found: ${target}`);
+            console.log((isFile
+                ? (0, agent_errors_1.fileNotFoundLines)(target, { agent: opts.agent })
+                : (0, agent_errors_1.symbolNotFoundLines)(target, { agent: opts.agent })).join("\n"));
             process.exitCode = 1;
             return;
         }

package/dist/commands/trace.js

@@ -48,6 +48,7 @@ const commander_1 = require("commander");
 const graph_builder_1 = require("../lib/graph/graph-builder");
 const formatter_1 = require("../lib/output/formatter");
 const vector_db_1 = require("../lib/store/vector-db");
+const agent_errors_1 = require("../lib/utils/agent-errors");
 const exit_1 = require("../lib/utils/exit");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
@@ -221,7 +222,7 @@ exports.trace = new commander_1.Command("trace")
         const graph = yield graphBuilder.buildGraphMultiHop(symbol, depth);
         if (opts.inbound) {
             if (!graph.center) {
-                console.log(opts.agent ? "(not found)" : `Symbol not found: ${symbol}`);
+                console.log((0, agent_errors_1.symbolNotFoundLines)(symbol, { agent: opts.agent }).join("\n"));
                 process.exitCode = 1;
             }
             else {

package/dist/index.js

@@ -48,6 +48,7 @@ const codex_1 = require("./commands/codex");
 const config_1 = require("./commands/config");
 const doctor_1 = require("./commands/doctor");
 const extract_1 = require("./commands/extract");
+const help_agent_1 = require("./commands/help-agent");
 const impact_1 = require("./commands/impact");
 const droid_1 = require("./commands/droid");
 const index_1 = require("./commands/index");
@@ -110,6 +111,7 @@ commander_1.program.addCommand(add_1.add);
 commander_1.program.addCommand(remove_1.remove);
 commander_1.program.addCommand(index_1.index);
 commander_1.program.addCommand(status_1.status);
+commander_1.program.addCommand(help_agent_1.helpAgent);
 commander_1.program.addCommand(list_1.list);
 commander_1.program.addCommand(skeleton_1.skeleton);
 commander_1.program.addCommand(symbols_1.symbols);

package/dist/lib/daemon/daemon.js

@@ -355,8 +355,9 @@ class Daemon {
             //     index — this is the dominant cost)
             //   - FTS index "already exists" round-trip
             //   - Two parallel encodeQuery calls so the worker pool spawns + warms
-            //     two workers (the reaper keeps min 2 alive). With one worker busy
-            //     on a long indexing batch, the second is always free for searches.
+            //     workers ahead of the first real search. The reaper floor is
+            //     MIN_KEEP_WORKERS = 1 (pool.ts), so only one worker stays resident
+            //     long-term — but the prewarm still pays the model-load cost up front.
             // Fire-and-forget; failures are non-fatal — the next real search just
             // pays the cost once. Delay a few seconds so we don't compete with the
             // catchup scans dispatched on startup.

package/dist/lib/help/agent-cheatsheet.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Canonical agent cheatsheet — the single source of truth for the gmax command
+ * survey shown to agent sessions. Consumed by two places:
+ *   - `gmax help-agent` (re-summon the survey on demand, e.g. after a session
+ *     has compacted away the original SessionStart injection)
+ *   - the SessionStart hook (`plugins/grepmax/hooks/start.js`), which loads this
+ *     compiled module from the installed package and falls back to an inline
+ *     copy only if the require fails — so the two can never silently drift.
+ *
+ * Keep this file as plain string data with NO imports so the hook can cheaply
+ * `require()` the compiled CommonJS output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_START_HINT = exports.AGENT_CHEATSHEET = exports.SESSION_START_PREFIX = void 0;
+/** Intro line shown only at SessionStart (not part of the on-demand command). */
+exports.SESSION_START_PREFIX = "gmax ready. Add --agent to any command for compact output (~89% fewer tokens).";
+/** The command survey — Find / Understand / Survey + scope/roles/recovery. */
+exports.AGENT_CHEATSHEET = `Find:
+  gmax "topic"                       semantic search
+  gmax similar <symbol>              similar code
+
+Understand:
+  gmax peek <symbol>                 signature + callers + callees + tests
+  gmax extract <symbol>              full body + tests
+  gmax trace <symbol>                call graph (--inbound = callers + snippets)
+  gmax test <symbol>                 tests for symbol
+  gmax impact <symbol>               blast radius
+  gmax related <file>                file deps + dependents
+
+Survey:
+  gmax project                       codebase overview (langs, structure, key symbols)
+  gmax skeleton <file>               file structure (file path, NOT a directory)
+  gmax context "topic-or-path" --budget 4000 topic summary or deterministic file/dir context
+  gmax log <path-or-symbol>          git commits (replaces recent/diff)
+  gmax status                        indexed projects
+
+Scope flags: --root <name|path>, --in <subpath>, --exclude <subpath>.
+Roles in results: [DEFI] [ORCH] [IMPL] [DOCS].
+Recovery: "not added yet" → gmax add; stale → gmax index; broken → gmax doctor --fix.`;
+/** Full SessionStart context = prefix + cheatsheet. */
+exports.SESSION_START_HINT = `${exports.SESSION_START_PREFIX}\n\n${exports.AGENT_CHEATSHEET}`;

package/dist/lib/search/searcher.js

@@ -304,9 +304,6 @@ class Searcher {
                 adjusted *= boostFactor;
             }
         }
-        if (record.role === "DOCS") {
-            adjusted *= 0.6;
-        }
         const pathStr = (record.path || "").toLowerCase();
         // Use path-segment and filename patterns to avoid false positives like "latest"
         const isTestPath = /(^|\/)(__tests__|tests?|specs?|benchmark)(\/|$)/i.test(pathStr) ||
@@ -315,14 +312,21 @@ class Searcher {
             const testPenalty = Number.parseFloat((_c = process.env.GMAX_TEST_PENALTY) !== null && _c !== void 0 ? _c : "") || 0.5;
             adjusted *= testPenalty;
         }
-        if (pathStr.endsWith(".md") ||
+        // Downweight docs/data — applied ONCE whether the chunk is classified DOCS
+        // by role OR lives in a doc/data file. GMAX_DOC_PENALTY tunes both. (S2: the
+        // role branch was previously a hardcoded 0.6 that stacked with the path
+        // branch, double-penalizing a DOCS-role chunk in a .md / /docs/ path to
+        // 0.36 — and the role half was not env-tunable.)
+        const isDocOrData = record.role === "DOCS" ||
+            pathStr.endsWith(".md") ||
             pathStr.endsWith(".mdx") ||
             pathStr.endsWith(".txt") ||
             pathStr.endsWith(".json") ||
             pathStr.endsWith(".lock") ||
-            pathStr.includes("/docs/")) {
+            pathStr.includes("/docs/");
+        if (isDocOrData) {
             const docPenalty = Number.parseFloat((_d = process.env.GMAX_DOC_PENALTY) !== null && _d !== void 0 ? _d : "") || 0.6;
-            adjusted *= docPenalty; // Downweight docs/data
+            adjusted *= docPenalty;
         }
         // Import-only penalty
         if ((record.content || "").length < 50 && !record.is_exported) {

package/dist/lib/utils/agent-errors.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Shared "not found" / empty-result rendering for the symbol and file lookup
+ * commands (peek/extract/trace/dead/impact/similar/related). Two jobs:
+ *
+ *  1. Unify the format — previously each command emitted its own variant
+ *     ("Symbol not found: X", "(not found)", bare one-liners), and only
+ *     peek/extract carried the rich human "Possible reasons / Try:" block.
+ *  2. Stop discarding recovery hints under `--agent` — human mode keeps the
+ *     full block; agent mode now gets a compact trailing `next:` line instead
+ *     of a bare, dead-end error.
+ *
+ * Returns lines (caller joins with "\n"). `dim`/`bold` default to identity so
+ * the helper stays color-agnostic; commands pass their own `style.*` to
+ * preserve existing human coloring.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.symbolNotFoundLines = symbolNotFoundLines;
+exports.fileNotFoundLines = fileNotFoundLines;
+const identity = (s) => s;
+/** `Symbol not found: X` — symbol lookup miss. */
+function symbolNotFoundLines(symbol, opts = {}) {
+    const { agent = false, dim = identity, bold = identity } = opts;
+    if (agent) {
+        return [
+            `Symbol not found: ${symbol}`,
+            `next: gmax status (indexed projects) · gmax search ${symbol} (fuzzy match)`,
+        ];
+    }
+    return [
+        `Symbol not found: ${bold(symbol)}`,
+        "",
+        dim("Possible reasons:"),
+        dim("  • The symbol doesn't exist in any indexed project"),
+        dim("  • The containing file hasn't been indexed yet"),
+        dim("  • The name is spelled differently in the source"),
+        "",
+        dim("Try:"),
+        dim("  gmax status          — see which projects are indexed"),
+        dim("  gmax search <name>   — fuzzy search for similar symbols"),
+    ];
+}
+/** `File not found in index: X` — file lookup miss. */
+function fileNotFoundLines(file, opts = {}) {
+    const { agent = false, dim = identity, bold = identity } = opts;
+    if (agent) {
+        return [
+            `File not found in index: ${file}`,
+            `next: use a path relative to the project root · gmax status · gmax add <project> (if untracked)`,
+        ];
+    }
+    return [
+        `File not found in index: ${bold(file)}`,
+        "",
+        dim("Try:"),
+        dim("  ensure the path is relative to the project root"),
+        dim("  gmax status          — see which projects are indexed"),
+        dim("  gmax add <project>   — index a project that isn't tracked yet"),
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.17.18",
+  "version": "0.17.19",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {

package/plugins/grepmax/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.17.18",
+  "version": "0.17.19",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",

package/plugins/grepmax/hooks/start.js

@@ -42,6 +42,65 @@ function findMlxServerDir() {
   return null;
 }
 
+// Inline fallback so SessionStart context is never empty if the installed
+// gmax package can't be resolved (e.g. gmax not yet on PATH). The canonical
+// copy lives in src/lib/help/agent-cheatsheet.ts; getSessionStartHint() prefers
+// it and only uses this if the require fails. Keep the two in sync.
+const FALLBACK_SESSION_START_HINT = `gmax ready. Add --agent to any command for compact output (~89% fewer tokens).
+
+Find:
+  gmax "topic"                       semantic search
+  gmax similar <symbol>              similar code
+
+Understand:
+  gmax peek <symbol>                 signature + callers + callees + tests
+  gmax extract <symbol>              full body + tests
+  gmax trace <symbol>                call graph (--inbound = callers + snippets)
+  gmax test <symbol>                 tests for symbol
+  gmax impact <symbol>               blast radius
+  gmax related <file>                file deps + dependents
+
+Survey:
+  gmax project                       codebase overview (langs, structure, key symbols)
+  gmax skeleton <file>               file structure (file path, NOT a directory)
+  gmax context "topic-or-path" --budget 4000 topic summary or deterministic file/dir context
+  gmax log <path-or-symbol>          git commits (replaces recent/diff)
+  gmax status                        indexed projects
+
+Scope flags: --root <name|path>, --in <subpath>, --exclude <subpath>.
+Roles in results: [DEFI] [ORCH] [IMPL] [DOCS].
+Recovery: "not added yet" → gmax add; stale → gmax index; broken → gmax doctor --fix.`;
+
+// Load the canonical cheatsheet from the installed gmax package (single source
+// of truth shared with `gmax help-agent`). Tries the npm-resolved package root
+// first, then the dev checkout, then the inline fallback above.
+function getSessionStartHint() {
+  const roots = [];
+  try {
+    const gmaxPath = execFileSync("which", ["gmax"], {
+      encoding: "utf-8",
+    }).trim();
+    if (gmaxPath) {
+      const realPath = fs.realpathSync(gmaxPath);
+      roots.push(_path.resolve(_path.dirname(realPath), ".."));
+    }
+  } catch {}
+  // dev mode — plugin lives at <repo>/plugins/grepmax/hooks
+  roots.push(_path.resolve(__dirname, "../../.."));
+
+  for (const root of roots) {
+    try {
+      const mod = require(
+        _path.join(root, "dist", "lib", "help", "agent-cheatsheet.js"),
+      );
+      if (mod && typeof mod.SESSION_START_HINT === "string") {
+        return mod.SESSION_START_HINT;
+      }
+    } catch {}
+  }
+  return FALLBACK_SESSION_START_HINT;
+}
+
 function startPythonServer(serverDir, scriptName, logName, processName) {
   if (!serverDir) return;
 
@@ -175,30 +234,7 @@ async function main() {
   const response = {
     hookSpecificOutput: {
       hookEventName: "SessionStart",
-      additionalContext: `gmax ready. Add --agent to any command for compact output (~89% fewer tokens).
-
-Find:
-  gmax "topic"                       semantic search
-  gmax similar <symbol>              similar code
-
-Understand:
-  gmax peek <symbol>                 signature + callers + callees + tests
-  gmax extract <symbol>              full body + tests
-  gmax trace <symbol>                call graph (--inbound = callers + snippets)
-  gmax test <symbol>                 tests for symbol
-  gmax impact <symbol>               blast radius
-  gmax related <file>                file deps + dependents
-
-Survey:
-  gmax project                       codebase overview (langs, structure, key symbols)
-  gmax skeleton <file>               file structure (file path, NOT a directory)
-  gmax context "topic-or-path" --budget 4000 topic summary or deterministic file/dir context
-  gmax log <path-or-symbol>          git commits (replaces recent/diff)
-  gmax status                        indexed projects
-
-Scope flags: --root <name|path>, --in <subpath>, --exclude <subpath>.
-Roles in results: [DEFI] [ORCH] [IMPL] [DOCS].
-Recovery: "not added yet" → gmax add; stale → gmax index; broken → gmax doctor --fix.`,
+      additionalContext: getSessionStartHint(),
     },
   };
   process.stdout.write(JSON.stringify(response));