grepmax 0.17.18 → 0.17.20

package/README.md

@@ -163,6 +163,9 @@ gmax "query" [options]
 | `--explain` | Show scoring breakdown per result. | `false` |
 | `-C <n>` | Context lines before/after. | `0` |
 | `--root <dir>` | Search a different project. | cwd |
+| `--all-projects` | Search every indexed project; results grouped by project. | `false` |
+| `--projects <list>` | Search only these projects (comma-separated names). | — |
+| `--exclude-projects <list>` | With `--all-projects`, skip these projects. | — |
 | `--min-score <n>` | Minimum relevance score. | `0` |
 
 ## Background Daemon

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/search.js

@@ -56,6 +56,7 @@ const setup_helpers_1 = require("../lib/setup/setup-helpers");
 const skeleton_1 = require("../lib/skeleton");
 const retriever_1 = require("../lib/skeleton/retriever");
 const vector_db_1 = require("../lib/store/vector-db");
+const cross_project_1 = require("../lib/utils/cross-project");
 const exit_1 = require("../lib/utils/exit");
 const formatter_1 = require("../lib/utils/formatter");
 const import_extractor_1 = require("../lib/utils/import-extractor");
@@ -370,6 +371,9 @@ exports.search = new commander_1.Command("search")
     .option("--file <name>", "Filter to files matching this name (e.g. 'syncer.ts')")
     .option("--in <subpath>", "Restrict to a sub-path of the project (repeatable; comma-separated also accepted)", (value, prev) => prev ? [...prev, value] : [value])
     .option("--exclude <subpath>", "Exclude a sub-path of the project (repeatable; e.g. 'tests/')", (value, prev) => prev ? [...prev, value] : [value])
+    .option("--all-projects", "Search across every indexed project, not just the current one", false)
+    .option("--projects <list>", "Search only these indexed projects (comma-separated names)")
+    .option("--exclude-projects <list>", "With --all-projects, skip these projects (comma-separated names)")
     .option("--lang <ext>", "Filter by file extension (e.g. 'ts', 'py')")
     .option("--role <role>", "Filter by role: ORCHESTRATION, DEFINITION, IMPLEMENTATION")
     .option("--symbol", "Append call graph after search results", false)
@@ -389,9 +393,11 @@ Examples:
   gmax "VectorDB" --symbol --plain
   gmax "error handling" -C 5 --imports --plain
   gmax "handler" --name "handle.*" --exclude tests/
+  gmax "rate limiter" --all-projects --agent
+  gmax "auth middleware" --projects api,gateway --plain
 `)
     .action((pattern, exec_path, _options, cmd) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0;
     const options = cmd.optsWithGlobals();
     const root = process.cwd();
     const minScore = Number.isFinite(Number.parseFloat(options.minScore))
@@ -401,10 +407,46 @@ Examples:
     const _searchStartMs = Date.now();
     let _searchResultCount = 0;
     let _searchError;
-    // Check for running server
+    // Cross-project scope (Phase 6): --all-projects / --projects / --exclude-projects.
+    // When active, single-project path scoping is dropped in favor of the
+    // project_roots filter clauses, and results are grouped by owning project.
+    const crossProject = (0, cross_project_1.resolveCrossProjectScope)({
+        allProjects: options.allProjects,
+        projects: options.projects,
+        excludeProjects: options.excludeProjects,
+    });
+    if (crossProject.active) {
+        // These modifiers are inherently single-project (one skeleton root, one
+        // call-graph center, one budget rollup). Reject the combination up front
+        // rather than emit confusing cross-root output.
+        const conflict = options.skeleton
+            ? "--skeleton"
+            : options.contextForLlm
+                ? "--context-for-llm"
+                : options.symbol
+                    ? "--symbol"
+                    : null;
+        if (conflict) {
+            console.error(`${conflict} is single-project; drop --all-projects/--projects or ${conflict}.`);
+            process.exitCode = 1;
+            return;
+        }
+        for (const w of crossProject.warnings)
+            console.warn(`Warning: ${w}`);
+        if (!crossProject.roots.length) {
+            console.error("No matching indexed projects. Run `gmax status` to list them.");
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // Check for running server. The per-project HTTP server can't answer
+    // cross-project queries, so cross-project mode skips it and uses the
+    // daemon-mediated / in-process path (both query the shared table).
     const execPathForServer = exec_path ? path.resolve(exec_path) : root;
     const projectRootForServer = (_a = (0, project_root_1.findProjectRoot)(execPathForServer)) !== null && _a !== void 0 ? _a : execPathForServer;
-    const server = (0, server_registry_1.getServerForProject)(projectRootForServer);
+    const server = crossProject.active
+        ? null
+        : (0, server_registry_1.getServerForProject)(projectRootForServer);
     if (server) {
         try {
             const response = yield fetch(`http://localhost:${server.port}/search`, {
@@ -552,14 +594,22 @@ Examples:
             in: options.in,
             exclude: options.exclude,
         });
-        const pathFilter = options.in && options.in.length > 0
-            ? scope.pathPrefix
-            : exec_path
-                ? (() => {
-                    const p = path.resolve(exec_path);
-                    return p.endsWith("/") ? p : `${p}/`;
-                })()
-                : scope.pathPrefix;
+        // Cross-project mode drops the single-project path prefix (and any
+        // --in/[path] sub-scoping, which is meaningless across roots) in favor of
+        // the project_roots filter clauses computed below.
+        if (crossProject.active && (exec_path || ((_d = options.in) === null || _d === void 0 ? void 0 : _d.length))) {
+            console.warn("Warning: --in / [path] are single-project; ignored under --all-projects/--projects.");
+        }
+        const pathFilter = crossProject.active
+            ? undefined
+            : options.in && options.in.length > 0
+                ? scope.pathPrefix
+                : exec_path
+                    ? (() => {
+                        const p = path.resolve(exec_path);
+                        return p.endsWith("/") ? p : `${p}/`;
+                    })()
+                    : scope.pathPrefix;
         const searchFilters = {};
         if (options.file)
             searchFilters.file = options.file;
@@ -567,10 +617,19 @@ Examples:
             searchFilters.language = options.lang;
         if (options.role)
             searchFilters.role = options.role;
-        if (scope.inPrefixes.length > 0)
-            searchFilters.inPrefixes = scope.inPrefixes;
-        if (scope.excludePrefixes.length > 0)
-            searchFilters.excludePrefixes = scope.excludePrefixes;
+        if (crossProject.active) {
+            if (crossProject.projectRootsCsv)
+                searchFilters.project_roots = crossProject.projectRootsCsv;
+            if (crossProject.excludeProjectRootsCsv)
+                searchFilters.exclude_project_roots =
+                    crossProject.excludeProjectRootsCsv;
+        }
+        else {
+            if (scope.inPrefixes.length > 0)
+                searchFilters.inPrefixes = scope.inPrefixes;
+            if (scope.excludePrefixes.length > 0)
+                searchFilters.excludePrefixes = scope.excludePrefixes;
+        }
         // Aider-style seeding: --seed-file / --seed-symbol (repeatable, also
         // comma-separated) bias candidate generation toward the caller's working
         // context. Absent → undefined → inert.
@@ -621,7 +680,7 @@ Examples:
                         indexState = resp.indexState;
                     }
                     else if (process.env.GMAX_DEBUG === "1") {
-                        console.error(`[search] daemon path unavailable: ${(_d = resp.error) !== null && _d !== void 0 ? _d : "unknown"}`);
+                        console.error(`[search] daemon path unavailable: ${(_e = resp.error) !== null && _e !== void 0 ? _e : "unknown"}`);
                     }
                 }
             }
@@ -703,7 +762,7 @@ Examples:
                 }
             }
             // Ensure a watcher is running for live reindexing
-            if (!process.env.VITEST && !((_e = process.env.NODE_ENV) === null || _e === void 0 ? void 0 : _e.includes("test"))) {
+            if (!process.env.VITEST && !((_f = process.env.NODE_ENV) === null || _f === void 0 ? void 0 : _f.includes("test"))) {
                 const { launchWatcher } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/watcher-launcher")));
                 const launched = yield launchWatcher(projectRoot);
                 if (!launched.ok && launched.reason === "spawn-failed") {
@@ -715,7 +774,7 @@ Examples:
                 ? searchFilters
                 : undefined, pathFilter);
         } // end if (!searchResult) — in-process fallback
-        if (!options.agent && ((_f = searchResult.warnings) === null || _f === void 0 ? void 0 : _f.length)) {
+        if (!options.agent && ((_g = searchResult.warnings) === null || _g === void 0 ? void 0 : _g.length)) {
             for (const w of searchResult.warnings) {
                 console.warn(`Warning: ${w}`);
             }
@@ -740,7 +799,7 @@ Examples:
                     return defs.some((d) => regex.test(d));
                 });
             }
-            catch (_0) {
+            catch (_1) {
                 // Invalid regex — skip
             }
         }
@@ -757,6 +816,76 @@ Examples:
         };
         // Agent mode: ultra-compact one-line-per-result output
         _searchResultCount = filteredData.length;
+        // Cross-project (Phase 6): render grouped by owning project so idioms
+        // from different stacks don't blur into one flat list. Only the
+        // string-formatter modes reach here — skeleton/context-for-llm/symbol
+        // were rejected up front.
+        if (crossProject.active) {
+            const emitFooter = () => {
+                const footer = (0, index_state_footer_1.formatIndexStateFooter)(indexState, {
+                    agent: !!options.agent,
+                });
+                if (footer) {
+                    if (options.agent)
+                        console.log(footer);
+                    else
+                        console.warn(footer);
+                }
+            };
+            if (!filteredData.length) {
+                console.log(options.agent ? "(none)" : "No matches found.");
+                process.exitCode = 1;
+                emitFooter();
+                return;
+            }
+            const getPath = (r) => {
+                var _a, _b, _c;
+                return String((_c = (_a = r.path) !== null && _a !== void 0 ? _a : (_b = r.metadata) === null || _b === void 0 ? void 0 : _b.path) !== null && _c !== void 0 ? _c : "");
+            };
+            const groups = (0, cross_project_1.groupResultsByProject)(filteredData, crossProject.roots, getPath);
+            const isTTY = process.stdout.isTTY;
+            const shouldBePlain = options.plain || !isTTY;
+            const blocks = [];
+            for (const g of groups) {
+                let body;
+                if (options.agent) {
+                    body = (0, agent_search_formatter_1.formatAgentSearchResults)(g.items, g.root, {
+                        includeImports: options.imports,
+                        getImportsForFile,
+                        explain: options.explain,
+                    });
+                }
+                else if (options.compact) {
+                    body = formatCompactTable(toCompactHits(g.items), g.root, pattern, {
+                        isTTY: !!isTTY,
+                        plain: !!options.plain,
+                    });
+                }
+                else if (shouldBePlain) {
+                    body = (0, formatter_1.formatTextResults)(toTextResults(g.items), pattern, g.root, {
+                        isPlain: true,
+                        compact: options.compact,
+                        content: options.content,
+                        perFile: parseInt(options.perFile, 10),
+                        showScores: options.scores,
+                    });
+                }
+                else {
+                    const { formatResults } = yield Promise.resolve().then(() => __importStar(require("../lib/output/formatter")));
+                    body = formatResults(g.items, g.root, {
+                        content: options.content,
+                        explain: options.explain,
+                    });
+                }
+                const header = options.agent
+                    ? `## ${g.name} (${g.items.length})`
+                    : `=== ${g.name} (${g.items.length}) ===`;
+                blocks.push(`${header}\n${body}`);
+            }
+            console.log(blocks.join("\n\n"));
+            emitFooter();
+            return;
+        }
         if (options.agent) {
             if (!filteredData.length) {
                 console.log("(none)");
@@ -798,7 +927,7 @@ Examples:
                         }
                     }
                 }
-                catch (_1) { }
+                catch (_2) { }
             }
             // Partial-index footer last, so it's the final line the agent reads —
             // and emitted even on "(none)", where an empty result may just mean the
@@ -836,9 +965,9 @@ Examples:
             let shown = 0;
             console.log(resultCountHeader(filteredData, parseInt(options.m, 10)));
             for (const r of filteredData) {
-                const absP = (_j = (_g = r.path) !== null && _g !== void 0 ? _g : (_h = r.metadata) === null || _h === void 0 ? void 0 : _h.path) !== null && _j !== void 0 ? _j : "";
-                const startLine = (_o = (_l = (_k = r.startLine) !== null && _k !== void 0 ? _k : r.start_line) !== null && _l !== void 0 ? _l : (_m = r.generated_metadata) === null || _m === void 0 ? void 0 : _m.start_line) !== null && _o !== void 0 ? _o : 0;
-                const endLine = (_s = (_q = (_p = r.endLine) !== null && _p !== void 0 ? _p : r.end_line) !== null && _q !== void 0 ? _q : (_r = r.generated_metadata) === null || _r === void 0 ? void 0 : _r.end_line) !== null && _s !== void 0 ? _s : startLine;
+                const absP = (_k = (_h = r.path) !== null && _h !== void 0 ? _h : (_j = r.metadata) === null || _j === void 0 ? void 0 : _j.path) !== null && _k !== void 0 ? _k : "";
+                const startLine = (_p = (_m = (_l = r.startLine) !== null && _l !== void 0 ? _l : r.start_line) !== null && _m !== void 0 ? _m : (_o = r.generated_metadata) === null || _o === void 0 ? void 0 : _o.start_line) !== null && _p !== void 0 ? _p : 0;
+                const endLine = (_t = (_r = (_q = r.endLine) !== null && _q !== void 0 ? _q : r.end_line) !== null && _r !== void 0 ? _r : (_s = r.generated_metadata) === null || _s === void 0 ? void 0 : _s.end_line) !== null && _t !== void 0 ? _t : startLine;
                 const relPath = absP.startsWith(projectRoot)
                     ? absP.slice(projectRoot.length + 1)
                     : absP;
@@ -871,7 +1000,7 @@ Examples:
                     tokensUsed += blobTokens;
                     shown++;
                 }
-                catch (_2) {
+                catch (_3) {
                     console.log(`\n--- ${relPath} (file not readable) ---`);
                     shown++;
                 }
@@ -888,7 +1017,7 @@ Examples:
         if (options.imports) {
             const seenFiles = new Set();
             for (const r of filteredData) {
-                const absP = (_v = (_t = r.path) !== null && _t !== void 0 ? _t : (_u = r.metadata) === null || _u === void 0 ? void 0 : _u.path) !== null && _v !== void 0 ? _v : "";
+                const absP = (_w = (_u = r.path) !== null && _u !== void 0 ? _u : (_v = r.metadata) === null || _v === void 0 ? void 0 : _v.path) !== null && _w !== void 0 ? _w : "";
                 if (absP && !seenFiles.has(absP)) {
                     seenFiles.add(absP);
                     const imports = getImportsForFile(absP);
@@ -915,7 +1044,7 @@ Examples:
                 for (const r of filteredData) {
                     const b = r.scoreBreakdown;
                     if (b) {
-                        const absP = (_y = (_w = r.path) !== null && _w !== void 0 ? _w : (_x = r.metadata) === null || _x === void 0 ? void 0 : _x.path) !== null && _y !== void 0 ? _y : "";
+                        const absP = (_z = (_x = r.path) !== null && _x !== void 0 ? _x : (_y = r.metadata) === null || _y === void 0 ? void 0 : _y.path) !== null && _z !== void 0 ? _z : "";
                         const relPath = absP.startsWith(projectRoot)
                             ? absP.slice(projectRoot.length + 1)
                             : absP;
@@ -977,7 +1106,7 @@ Examples:
                     console.log(lines.join("\n"));
                 }
             }
-            catch (_3) {
+            catch (_4) {
                 // Trace failed — skip silently
             }
         }
@@ -997,13 +1126,13 @@ Examples:
                 source: "cli",
                 tool: "search",
                 query: pattern,
-                project: (_z = (0, project_root_1.findProjectRoot)(root)) !== null && _z !== void 0 ? _z : root,
+                project: (_0 = (0, project_root_1.findProjectRoot)(root)) !== null && _0 !== void 0 ? _0 : root,
                 results: _searchResultCount,
                 ms: Date.now() - _searchStartMs,
                 error: _searchError,
             });
         }
-        catch (_4) { }
+        catch (_5) { }
         if (vectorDb) {
             try {
                 yield vectorDb.close();

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/dist/lib/utils/cross-project.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Cross-project search scoping (Phase 6).
+ *
+ * The shared LanceDB table holds chunks from every indexed project, scoped by
+ * absolute-path prefix. Single-project search pins a `pathPrefix`; cross-project
+ * search drops the prefix and instead scopes with the `project_roots` /
+ * `exclude_project_roots` filter clauses (an OR-group of `path LIKE` prefixes —
+ * see buildWhereClause in searcher.ts). This module resolves the CLI flags
+ * (`--all-projects` / `--projects` / `--exclude-projects`) to those filter
+ * values and groups results back by owning project for display.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCrossProjectScope = resolveCrossProjectScope;
+exports.projectForPath = projectForPath;
+exports.groupResultsByProject = groupResultsByProject;
+const project_registry_1 = require("./project-registry");
+function resolveCrossProjectScope(opts) {
+    const active = !!(opts.allProjects || opts.projects);
+    if (!active) {
+        return { active: false, roots: [], warnings: [] };
+    }
+    // Ignore "error"-status projects: the daemon won't search them anyway.
+    const all = (0, project_registry_1.listProjects)().filter((p) => p.status !== "error");
+    const byName = new Map(all.map((p) => [p.name, p]));
+    const warnings = [];
+    const resolveNames = (csv) => {
+        const names = (csv !== null && csv !== void 0 ? csv : "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        const found = [];
+        const missing = [];
+        for (const n of names) {
+            const p = byName.get(n);
+            if (p)
+                found.push(p);
+            else
+                missing.push(n);
+        }
+        return { found, missing };
+    };
+    const excluded = resolveNames(opts.excludeProjects);
+    const excludedRoots = new Set(excluded.found.map((p) => p.root));
+    if (excluded.missing.length) {
+        warnings.push(`Unknown --exclude-projects: ${excluded.missing.join(", ")}`);
+    }
+    let included;
+    let projectRootsCsv;
+    let excludeProjectRootsCsv;
+    if (opts.projects) {
+        const r = resolveNames(opts.projects);
+        if (r.missing.length) {
+            warnings.push(`Unknown --projects: ${r.missing.join(", ")}. Available: ${all
+                .map((p) => p.name)
+                .join(", ")}`);
+        }
+        included = r.found.filter((p) => !excludedRoots.has(p.root));
+        // Narrowed to an explicit subset → scope with project_roots.
+        projectRootsCsv = included.length
+            ? included.map((p) => p.root).join(",")
+            : undefined;
+    }
+    else {
+        // --all-projects: search the whole shared table. No project_roots clause
+        // (its absence IS "everything"); only carve out --exclude-projects.
+        included = all.filter((p) => !excludedRoots.has(p.root));
+        if (excludedRoots.size) {
+            excludeProjectRootsCsv = [...excludedRoots].join(",");
+        }
+    }
+    return {
+        active: true,
+        roots: included.map((p) => ({ root: p.root, name: p.name })),
+        projectRootsCsv,
+        excludeProjectRootsCsv,
+        warnings,
+    };
+}
+/** Longest-prefix match of an absolute path against the in-scope project roots. */
+function projectForPath(absPath, roots) {
+    let best = null;
+    let bestLen = -1;
+    for (const r of roots) {
+        const prefix = r.root.endsWith("/") ? r.root : `${r.root}/`;
+        if (absPath === r.root || absPath.startsWith(prefix)) {
+            if (prefix.length > bestLen) {
+                best = r;
+                bestLen = prefix.length;
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Bucket ranked results by owning project, preserving rank order: groups appear
+ * in order of their best-ranked member, items keep their original order.
+ */
+function groupResultsByProject(results, roots, getPath) {
+    var _a, _b, _c;
+    const order = [];
+    const buckets = new Map();
+    for (const r of results) {
+        const owner = projectForPath(getPath(r), roots);
+        const key = (_a = owner === null || owner === void 0 ? void 0 : owner.root) !== null && _a !== void 0 ? _a : "(unknown)";
+        let bucket = buckets.get(key);
+        if (!bucket) {
+            bucket = { name: (_b = owner === null || owner === void 0 ? void 0 : owner.name) !== null && _b !== void 0 ? _b : "(unknown)", root: (_c = owner === null || owner === void 0 ? void 0 : owner.root) !== null && _c !== void 0 ? _c : "", items: [] };
+            buckets.set(key, bucket);
+            order.push(key);
+        }
+        bucket.items.push(r);
+    }
+    return order.map((k) => buckets.get(k));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.17.18",
+  "version": "0.17.20",
   "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.20",
   "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));