codesift-mcp 0.3.0 → 0.5.0

package/dist/register-tools.js

@@ -2,11 +2,14 @@ import { z } from "zod";
 /** Boolean that also accepts "true"/"false" strings (LLMs often send strings instead of booleans) */
 const zBool = () => z.union([z.boolean(), z.string().transform((s) => s === "true")]).optional();
 import { wrapTool, registerShortener } from "./server-helpers.js";
-import { indexFolder, indexFile, indexRepo, listAllRepos, invalidateCache } from "./tools/index-tools.js";
+import { detectProjectLanguagesSync } from "./utils/language-detect.js";
+import { indexFolder, indexFile, indexRepo, listAllRepos, invalidateCache, getCodeIndex } from "./tools/index-tools.js";
+import { STUB_LANGUAGES } from "./parser/parser-manager.js";
 import { searchSymbols, searchText, semanticSearch } from "./tools/search-tools.js";
 import { getFileTree, getFileOutline, getRepoOutline, suggestQueries } from "./tools/outline-tools.js";
 import { getSymbol, getSymbols, findAndShow, findReferences, findReferencesBatch, findDeadCode, getContextBundle, formatRefsCompact, formatSymbolCompact, formatSymbolsCompact, formatBundleCompact } from "./tools/symbol-tools.js";
 import { traceCallChain } from "./tools/graph-tools.js";
+import { traceComponentTree, analyzeHooks, analyzeRenders, buildContextGraph, auditCompilerReadiness, reactQuickstart } from "./tools/react-tools.js";
 import { impactAnalysis } from "./tools/impact-tools.js";
 import { traceRoute } from "./tools/route-tools.js";
 import { detectCommunities } from "./tools/community-tools.js";
@@ -24,14 +27,60 @@ import { getUsageStats, formatUsageReport } from "./storage/usage-stats.js";
 import { goToDefinition, getTypeInfo, renameSymbol, getCallHierarchy } from "./lsp/lsp-tools.js";
 import { indexConversations, searchConversations, searchAllConversations, findConversationsForSymbol } from "./tools/conversation-tools.js";
 import { scanSecrets } from "./tools/secret-tools.js";
+import { resolvePhpNamespace, tracePhpEvent, findPhpViews, resolvePhpService, phpSecurityScan, phpProjectAudit, } from "./tools/php-tools.js";
 import { consolidateMemories, readMemory } from "./tools/memory-tools.js";
 import { createAnalysisPlan, writeScratchpad, readScratchpad, listScratchpad, updateStepStatus, getPlan, listPlans } from "./tools/coordinator-tools.js";
 import { frequencyAnalysis } from "./tools/frequency-tools.js";
+import { findExtensionFunctions, analyzeSealedHierarchy, traceSuspendChain, analyzeKmpDeclarations, traceFlowChain } from "./tools/kotlin-tools.js";
+import { traceHiltGraph } from "./tools/hilt-tools.js";
+import { traceComposeTree, analyzeComposeRecomposition } from "./tools/compose-tools.js";
+import { traceRoomSchema } from "./tools/room-tools.js";
+import { extractKotlinSerializationContract } from "./tools/serialization-tools.js";
+import { astroAnalyzeIslands, astroHydrationAudit } from "./tools/astro-islands.js";
+import { astroRouteMap } from "./tools/astro-routes.js";
+import { astroActionsAudit } from "./tools/astro-actions.js";
+import { astroAudit } from "./tools/astro-audit.js";
+import { nextjsRouteMap } from "./tools/nextjs-route-tools.js";
+import { nextjsMetadataAudit } from "./tools/nextjs-metadata-tools.js";
+import { frameworkAudit } from "./tools/nextjs-framework-audit-tools.js";
+import { astroConfigAnalyze } from "./tools/astro-config.js";
+import { astroContentCollections } from "./tools/astro-content-collections.js";
 import { analyzeProject, getExtractorVersions } from "./tools/project-tools.js";
+import { getModelGraph } from "./tools/model-tools.js";
+import { getTestFixtures } from "./tools/pytest-tools.js";
+import { findFrameworkWiring } from "./tools/wiring-tools.js";
+import { runRuff } from "./tools/ruff-tools.js";
+import { parsePyproject } from "./tools/pyproject-tools.js";
+import { resolveConstantValue } from "./tools/python-constants-tools.js";
+import { effectiveDjangoViewSecurity } from "./tools/django-view-security-tools.js";
+import { findPythonCallers } from "./tools/python-callers.js";
+import { taintTrace } from "./tools/taint-tools.js";
+import { analyzeDjangoSettings } from "./tools/django-settings.js";
+import { runMypy, runPyright } from "./tools/typecheck-tools.js";
+import { analyzePythonDeps } from "./tools/python-deps-analyzer.js";
+import { pythonAudit } from "./tools/python-audit.js";
+import { traceFastAPIDepends } from "./tools/fastapi-depends.js";
+import { analyzeAsyncCorrectness } from "./tools/async-correctness.js";
+import { getPydanticModels } from "./tools/pydantic-models.js";
 import { reviewDiff } from "./tools/review-diff-tools.js";
+import { auditScan } from "./tools/audit-tools.js";
+import { indexStatus } from "./tools/status-tools.js";
+import { auditAgentConfig } from "./tools/agent-config-tools.js";
+import { testImpactAnalysis } from "./tools/test-impact-tools.js";
+import { dependencyAudit } from "./tools/dependency-audit-tools.js";
+import { migrationLint } from "./tools/migration-lint-tools.js";
+import { planTurn, formatPlanTurnResult } from "./tools/plan-turn-tools.js";
+import { astroMigrationCheck } from "./tools/astro-migration.js";
+import { analyzePrismaSchema } from "./tools/prisma-schema-tools.js";
+import { findPerfHotspots } from "./tools/perf-tools.js";
+import { fanInFanOut, coChangeAnalysis } from "./tools/coupling-tools.js";
+import { architectureSummary } from "./tools/architecture-tools.js";
+import { nestAudit } from "./tools/nest-tools.js";
+import { explainQuery } from "./tools/query-tools.js";
 import { formatSnapshot, getContext, getSessionState } from "./storage/session-state.js";
 import { formatComplexityCompact, formatComplexityCounts, formatClonesCompact, formatClonesCounts, formatHotspotsCompact, formatHotspotsCounts, formatTraceRouteCompact, formatTraceRouteCounts } from "./formatters-shortening.js";
-import { formatSearchSymbols, formatFileTree, formatFileOutline, formatSearchPatterns, formatDeadCode, formatComplexity, formatClones, formatHotspots, formatRepoOutline, formatSuggestQueries, formatSecrets, formatConversations, formatRoles, formatAssembleContext, formatCommunities, formatCallTree, formatTraceRoute, formatKnowledgeMap, formatImpactAnalysis, formatDiffOutline, formatChangedSymbols, formatReviewDiff } from "./formatters.js";
+import { formatSearchSymbols, formatFileTree, formatFileOutline, formatSearchPatterns, formatDeadCode, formatComplexity, formatClones, formatHotspots, formatRepoOutline, formatSuggestQueries, formatSecrets, formatConversations, formatRoles, formatAssembleContext, formatCommunities, formatCallTree, formatTraceRoute, formatKnowledgeMap, formatImpactAnalysis, formatDiffOutline, formatChangedSymbols, formatReviewDiff, formatPerfHotspots, formatFanInFanOut, formatCoChange, formatArchitectureSummary, formatNextjsRouteMap, formatNextjsMetadataAudit, formatFrameworkAudit } from "./formatters.js";
+import { formatNextjsRouteMapCompact, formatNextjsRouteMapCounts, formatNextjsMetadataAuditCompact, formatNextjsMetadataAuditCounts, formatFrameworkAuditCompact, formatFrameworkAuditCounts } from "./formatters-shortening.js";
 const zFiniteNumber = z.number().finite();
 /** Coerce string→number for numeric params while rejecting NaN/empty strings. */
 export const zNum = () => z.union([
@@ -43,6 +92,73 @@ export const zNum = () => z.union([
         .pipe(zFiniteNumber),
 ]).optional();
 // ---------------------------------------------------------------------------
+// H11 — warn when symbol tools return empty for repos with text_stub languages
+// ---------------------------------------------------------------------------
+export const SYMBOL_TOOLS = new Set([
+    "search_symbols", "get_file_outline", "get_symbol", "get_symbols",
+    "find_references", "trace_call_chain", "find_dead_code", "analyze_complexity",
+]);
+/**
+ * Build an H11 hint string from a list of FileEntry-like records. Returns
+ * null when no hint is needed. Separated from `checkTextStubHint` so the
+ * purely-deterministic core can be unit-tested without spinning up a real
+ * index.
+ *
+ * A file is counted as a "stub" when its language appears in STUB_LANGUAGES
+ * (queried dynamically). Languages like `kotlin` that have a real extractor
+ * are automatically excluded because they live outside STUB_LANGUAGES, so
+ * H11 no longer fires for Kotlin-heavy repos.
+ */
+export function buildH11Hint(files) {
+    if (files.length === 0)
+        return null;
+    const stubFiles = files.filter((f) => STUB_LANGUAGES.has(f.language));
+    if (stubFiles.length === 0)
+        return null;
+    const stubPct = Math.round((stubFiles.length / files.length) * 100);
+    if (stubPct < 30)
+        return null;
+    const stubExts = [...new Set(stubFiles.map((f) => "." + f.path.split(".").pop()))].slice(0, 3).join(", ");
+    return `⚡H11 No parser for ${stubExts} files (${stubPct}% of repo). Symbol tools return empty.\n` +
+        `  → search_text(query) works on ALL files (uses ripgrep, not parser)\n` +
+        `  → get_file_tree shows file listing\n` +
+        `  → Only symbol-based tools (this one) need a parser to return results.\n`;
+}
+/**
+ * Check if a repo has stub-language files as a dominant portion. Returns a
+ * hint string to prepend to empty results, or null if no hint needed.
+ */
+async function checkTextStubHint(repo, toolName, resultEmpty) {
+    if (!resultEmpty || !repo || !SYMBOL_TOOLS.has(toolName))
+        return null;
+    const index = await getCodeIndex(repo);
+    if (!index)
+        return null;
+    return buildH11Hint(index.files);
+}
+function formatAuditScan(result) {
+    const lines = [];
+    lines.push(`AUDIT SCAN: ${result.repo}`);
+    lines.push(`Gates checked: ${result.summary.gates_checked} | Findings: ${result.summary.total_findings} (${result.summary.critical} critical, ${result.summary.warning} warning)`);
+    lines.push("");
+    for (const gate of result.gates) {
+        const count = gate.findings.length;
+        const status = count === 0 ? "✓ PASS" : `✗ ${count} finding${count > 1 ? "s" : ""}`;
+        lines.push(`${gate.gate} ${status} — ${gate.description}`);
+        lines.push(`  tool: ${gate.tool_used}`);
+        for (const f of gate.findings.slice(0, 10)) {
+            const loc = f.line ? `:${f.line}` : "";
+            const sev = f.severity === "critical" ? "🔴" : "🟡";
+            lines.push(`  ${sev} ${f.file}${loc} — ${f.detail}`);
+        }
+        if (gate.findings.length > 10) {
+            lines.push(`  ... +${gate.findings.length - 10} more`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
 // Registered tool handles — populated by registerTools(), used by describe_tools reveal
 // ---------------------------------------------------------------------------
 const toolHandles = new Map();
@@ -50,6 +166,213 @@ const toolHandles = new Map();
 export function getToolHandle(name) {
     return toolHandles.get(name);
 }
+/** Framework-specific tool bundles — auto-enabled when the framework is detected in an indexed repo */
+const FRAMEWORK_TOOL_BUNDLES = {
+    nestjs: [
+    // All NestJS sub-tools absorbed into nest_audit
+    ],
+};
+/** Track which framework bundles have been auto-enabled this session (avoid repeat work) */
+const enabledFrameworkBundles = new Set();
+/**
+ * Enable framework-specific tool bundle — called after indexing when framework is detected.
+ * Idempotent: safe to call multiple times. Only enables tools that exist and are currently disabled.
+ */
+export function enableFrameworkToolBundle(framework) {
+    if (enabledFrameworkBundles.has(framework))
+        return [];
+    const bundle = FRAMEWORK_TOOL_BUNDLES[framework];
+    if (!bundle)
+        return [];
+    const enabled = [];
+    for (const name of bundle) {
+        const handle = toolHandles.get(name);
+        if (handle && typeof handle.enable === "function") {
+            handle.enable();
+            enabled.push(name);
+        }
+    }
+    if (enabled.length > 0)
+        enabledFrameworkBundles.add(framework);
+    return enabled;
+}
+// ---------------------------------------------------------------------------
+// Framework-specific tool auto-loading
+// ---------------------------------------------------------------------------
+/**
+ * Tool groups that should be auto-enabled when a matching project type is detected at CWD.
+ * Keys are detection signals (files at CWD root), values are tool names to enable.
+ */
+const FRAMEWORK_TOOL_GROUPS = {
+    // PHP / Yii2 / Laravel — detected by composer.json
+    "composer.json": [
+        "resolve_php_namespace",
+        // analyze_activerecord, find_php_n_plus_one, find_php_god_model absorbed into php_project_audit
+        "trace_php_event",
+        "find_php_views",
+        "resolve_php_service",
+        "php_security_scan",
+        "php_project_audit",
+    ],
+    // Kotlin / Android / Gradle — detected by build.gradle.kts or settings.gradle.kts
+    "build.gradle.kts": [
+        "find_extension_functions",
+        "analyze_sealed_hierarchy",
+        "trace_hilt_graph",
+        "trace_suspend_chain",
+        "analyze_kmp_declarations",
+        "trace_compose_tree",
+        "analyze_compose_recomposition",
+        "trace_room_schema",
+        "extract_kotlin_serialization_contract",
+        "trace_flow_chain",
+    ],
+    "settings.gradle.kts": [
+        "find_extension_functions",
+        "analyze_sealed_hierarchy",
+        "trace_hilt_graph",
+        "trace_suspend_chain",
+        "analyze_kmp_declarations",
+        "trace_compose_tree",
+        "analyze_compose_recomposition",
+        "trace_room_schema",
+        "extract_kotlin_serialization_contract",
+        "trace_flow_chain",
+    ],
+    // Fallback — Android projects with Groovy gradle but Kotlin source
+    "build.gradle": [
+        "find_extension_functions",
+        "analyze_sealed_hierarchy",
+        "trace_hilt_graph",
+        "trace_suspend_chain",
+        "analyze_kmp_declarations",
+        "trace_compose_tree",
+        "analyze_compose_recomposition",
+        "trace_room_schema",
+        "extract_kotlin_serialization_contract",
+        "trace_flow_chain",
+    ],
+};
+/**
+ * React-specific tools — auto-enabled when a React project is detected.
+ * Detection requires BOTH a package.json with react dependency AND presence
+ * of .tsx/.jsx files (prevents false positives on non-UI projects that happen
+ * to have react as a transitive dep).
+ */
+const REACT_TOOLS = [
+    "trace_component_tree",
+    "analyze_hooks",
+    "analyze_renders",
+    "analyze_context_graph",
+    "audit_compiler_readiness",
+    "react_quickstart",
+];
+/**
+ * Hono-specific tools — auto-enabled when a Hono project is detected.
+ * Core tools (trace_middleware_chain, analyze_hono_app) are already in
+ * CORE_TOOL_NAMES. This list covers the 5 hidden tools that agents need
+ * to discover via describe_tools/discover_tools otherwise.
+ *
+ * Detection: package.json with "hono" OR "@hono/zod-openapi" dep.
+ * Content-based (not filename), so lives outside FRAMEWORK_TOOL_GROUPS.
+ */
+const HONO_TOOLS = [
+    "trace_context_flow",
+    "extract_api_contract",
+    "trace_rpc_types",
+    "audit_hono_security",
+    "visualize_hono_routes",
+    // Phase 2 additions — closes blog-API demo gaps + GitHub issues #3587/#4121/#4270
+    "analyze_inline_handler",
+    "extract_response_types",
+    "detect_hono_modules",
+    "find_dead_hono_routes",
+];
+/**
+ * Detect project type at CWD and return list of tools that should be auto-enabled.
+ * Returns empty array if no framework-specific tools apply.
+ * Exported for unit testing.
+ */
+export async function detectAutoLoadTools(cwd) {
+    const { existsSync, readFileSync, readdirSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const toEnable = [];
+    for (const [signalFile, tools] of Object.entries(FRAMEWORK_TOOL_GROUPS)) {
+        if (existsSync(join(cwd, signalFile))) {
+            toEnable.push(...tools);
+        }
+    }
+    // React + Hono detection: both need to read package.json for dep signals.
+    const pkgPath = join(cwd, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            // React: dep + .tsx/.jsx files
+            const hasReact = !!(allDeps["react"] || allDeps["next"] || allDeps["@remix-run/react"]);
+            if (hasReact && hasJsxFilesShallow(cwd, readdirSync)) {
+                toEnable.push(...REACT_TOOLS);
+            }
+            // Hono: any hono package is enough — the framework is only pulled in
+            // when used, and all 5 hidden tools degrade gracefully on non-Hono repos
+            // so false positives are harmless (return "no Hono detected" errors).
+            const hasHono = !!(allDeps["hono"] ||
+                allDeps["@hono/zod-openapi"] ||
+                allDeps["@hono/node-server"] ||
+                allDeps["hono-openapi"] ||
+                allDeps["chanfana"]);
+            if (hasHono) {
+                toEnable.push(...HONO_TOOLS);
+            }
+        }
+        catch { /* malformed package.json */ }
+    }
+    return toEnable;
+}
+/**
+ * Quick recursive scan for .tsx/.jsx files in common source dirs.
+ * Limits depth to 3 and stops on first match to stay fast (<10ms on typical repos).
+ * Skips node_modules, dist, build, .next, .astro, .git.
+ */
+function hasJsxFilesShallow(cwd, readdirSyncFn) {
+    const { join } = require("node:path");
+    const IGNORE = new Set([
+        "node_modules", "dist", "build", ".next", ".astro", ".git",
+        "out", "coverage", ".turbo", ".vercel", ".cache",
+    ]);
+    const ROOTS = ["src", "app", "pages", "components", "."];
+    function scan(dir, depth) {
+        if (depth > 3)
+            return false;
+        let entries;
+        try {
+            entries = readdirSyncFn(dir, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const e of entries) {
+            if (e.isFile() && /\.(tsx|jsx)$/.test(e.name))
+                return true;
+        }
+        for (const e of entries) {
+            if (e.isDirectory() && !IGNORE.has(e.name) && !e.name.startsWith(".")) {
+                if (scan(join(dir, e.name), depth + 1))
+                    return true;
+            }
+        }
+        return false;
+    }
+    for (const root of ROOTS) {
+        const dir = root === "." ? cwd : join(cwd, root);
+        try {
+            if (scan(dir, 0))
+                return true;
+        }
+        catch { /* skip */ }
+    }
+    return false;
+}
 // ---------------------------------------------------------------------------
 // Output schemas — typed results for structured validation & documentation
 // ---------------------------------------------------------------------------
@@ -109,23 +432,67 @@ export const OutputSchemas = {
     /** list_repos */
     repoList: z.union([z.array(z.string()), z.array(z.object({ name: z.string() }).passthrough())]),
 };
-/** Tools always registered with full schema — top 10 by usage (91% of calls) + essentials */
-const CORE_TOOL_NAMES = new Set([
-    "search_text", // #1: 1536 calls, 36%
-    "codebase_retrieval", // #2: 510 calls, 12%
-    "get_file_outline", // #3: 342 calls, 8%
-    "search_symbols", // #4: 321 calls, 8%
-    "list_repos", // #5: 223 calls, 5%
-    "get_file_tree", // #6: 218 calls, 5%
-    "index_file", // #7: 163 calls, 4% — lightweight schema
-    "get_symbol", // #8: 135 calls, 3%
-    "index_conversations", // #9: 125 calls, 3% — lightweight schema
-    "search_patterns", // #10: 122 calls, 3%
-    "index_folder", // essential: repo onboarding
-    "discover_tools", // meta: discovers deferred tools
-    "get_session_snapshot", // session: compaction survival (core — always visible)
-    "analyze_project", // project profile: stack, conventions, file classifications
-    "get_extractor_versions", // cache invalidation for project profile
+/** Tools visible in ListTools — core (high usage) + direct-use (agents call without discovery) */
+export const CORE_TOOL_NAMES = new Set([
+    // --- Top 10 by usage (91% of calls) ---
+    "search_text", // #1: 1841 calls
+    "codebase_retrieval", // #2: 574 calls
+    "get_file_outline", // #3: 351 calls
+    "search_symbols", // #4: 332 calls
+    "list_repos", // #5: 292 calls
+    "get_file_tree", // #6: 268 calls
+    "index_file", // #7: 209 calls
+    "get_symbol", // #8: 138 calls
+    "search_patterns", // #9: 135 calls
+    "index_conversations", // #10: 127 calls
+    // --- Direct-use: agents call these without discovery ---
+    "assemble_context", // 64 calls, 21 sessions, 100% direct
+    "get_symbols", // 69 calls — batch symbol reads
+    "find_references", // 39 calls — symbol usage
+    "find_and_show", // 55 calls — symbol + refs
+    "search_conversations", // 37 calls, 100% direct
+    "get_context_bundle", // 36 calls, 19 sessions, 100% direct
+    "analyze_complexity", // 33 calls, 28 sessions
+    "detect_communities", // 32 calls, 24 sessions
+    "search_all_conversations", // 27 calls, 100% direct
+    "analyze_hotspots", // 22 calls, 18 sessions
+    "trace_call_chain", // 15 calls, 100% direct
+    "suggest_queries", // 13 calls, 13 sessions
+    "usage_stats", // 11 calls, 100% direct
+    "get_knowledge_map", // 10 calls, 100% direct
+    "get_repo_outline", // 9 calls, 100% direct
+    "trace_route", // 9 calls, 100% direct
+    "get_type_info", // 8 calls, 100% direct
+    "impact_analysis", // 4 calls, 100% direct
+    "go_to_definition", // 4 calls, 100% direct
+    // --- Composite tools ---
+    "audit_scan", // one-call audit: CQ8+CQ11+CQ13+CQ14+CQ17
+    "nest_audit", // one-call NestJS analysis: modules+DI+guards+routes+lifecycle
+    // --- Essential infrastructure ---
+    "index_folder", // repo onboarding
+    "discover_tools", // meta: discovers remaining hidden tools
+    "describe_tools", // meta: full schema for hidden tools
+    "plan_turn", // meta: route query to best tools/symbols/files
+    "get_session_snapshot", // session: compaction survival
+    "analyze_project", // project profile
+    "get_extractor_versions", // cache invalidation
+    "index_status", // meta: check if repo is indexed
+    // --- Astro tools (7 core) ---
+    "astro_analyze_islands",
+    // astro_hydration_audit: discoverable — use astro_audit for full check or call directly
+    "astro_route_map",
+    "astro_config_analyze",
+    "astro_actions_audit",
+    "astro_migration_check",
+    "astro_content_collections",
+    "astro_audit",
+    // --- Hono tools (Task 23) ---
+    "trace_middleware_chain", // core: top Hono pain point (Discussion #4255)
+    "analyze_hono_app", // core: meta-tool, first call for any Hono project
+    // --- Next.js tools ---
+    "nextjs_route_map",
+    "nextjs_metadata_audit",
+    "framework_audit",
 ]);
 /** Get all tool definitions (exported for testing) */
 export function getToolDefinitions() {
@@ -174,8 +541,16 @@ const TOOL_DEFINITIONS = [
         description: "List indexed repos. Only needed for multi-repo discovery — single-repo tools auto-resolve from CWD. Set compact=false for full metadata.",
         schema: {
             compact: zBool().describe("true=names only (default), false=full metadata"),
+            name_contains: z.string().optional().describe("Filter repos by name substring (case-insensitive). E.g. 'tgm' matches 'local/tgm-panel'"),
+        },
+        handler: (args) => {
+            const opts = {
+                compact: args.compact ?? true,
+            };
+            if (args.name_contains)
+                opts.name_contains = args.name_contains;
+            return listAllRepos(opts);
         },
-        handler: (args) => listAllRepos({ compact: args.compact ?? true }),
     },
     {
         name: "invalidate_cache",
@@ -203,12 +578,13 @@ const TOOL_DEFINITIONS = [
         category: "search",
         searchHint: "search find symbols functions classes types methods by name signature",
         outputSchema: OutputSchemas.searchResults,
-        description: "Search symbols by name/signature. detail_level: compact (~15 tok), standard (default), full.",
+        description: "Search symbols by name/signature. Supports kind, file, and decorator filters. detail_level: compact (~15 tok), standard (default), full.",
         schema: {
             repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
             query: z.string().describe("Search query string"),
             kind: z.string().optional().describe("Filter by symbol kind (function, class, etc.)"),
             file_pattern: z.string().optional().describe("Glob pattern to filter files"),
+            decorator: z.string().optional().describe("Filter by decorator metadata, e.g. login_required, @dataclass, router.get"),
             include_source: zBool().describe("Include full source code of each symbol"),
             top_k: zNum().describe("Maximum number of results to return (default 50)"),
             source_chars: zNum().describe("Truncate each symbol's source to N characters (reduces output size)"),
@@ -220,6 +596,7 @@ const TOOL_DEFINITIONS = [
             const results = await searchSymbols(args.repo, args.query, {
                 kind: args.kind,
                 file_pattern: args.file_pattern,
+                decorator: args.decorator,
                 include_source: args.include_source,
                 top_k: args.top_k,
                 source_chars: args.source_chars,
@@ -227,18 +604,20 @@ const TOOL_DEFINITIONS = [
                 token_budget: args.token_budget,
                 rerank: args.rerank,
             });
-            return formatSearchSymbols(results);
+            const output = formatSearchSymbols(results);
+            const hint = await checkTextStubHint(args.repo, "search_symbols", results.length === 0);
+            return hint ? hint + output : output;
         },
     },
     {
         name: "ast_query",
         category: "search",
-        searchHint: "AST tree-sitter query structural pattern matching code shape",
-        description: "Search AST patterns via tree-sitter S-expressions. Finds code by structural shape.",
+        searchHint: "AST tree-sitter query structural pattern matching code shape jsx react",
+        description: "Search AST patterns via tree-sitter S-expressions. Finds code by structural shape. React examples (language='tsx'): `(jsx_element open_tag: (jsx_opening_element name: (identifier) @tag))` finds all JSX component usage; `(call_expression function: (identifier) @fn (#match? @fn \"^use[A-Z]\"))` finds all hook calls.",
         schema: {
             repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
-            query: z.string().describe("Tree-sitter query in S-expression syntax"),
-            language: z.string().describe("Tree-sitter grammar: typescript, javascript, python, go, rust, java, ruby, php"),
+            query: z.string().describe("Tree-sitter query in S-expression syntax. For JSX/React use language='tsx'."),
+            language: z.string().describe("Tree-sitter grammar: typescript, tsx, javascript, python, go, rust, java, ruby, php"),
             file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
             max_matches: zNum().describe("Maximum matches to return (default: 50)"),
         },
@@ -341,7 +720,10 @@ const TOOL_DEFINITIONS = [
         },
         handler: async (args) => {
             const result = await getFileOutline(args.repo, args.file_path);
-            return formatFileOutline(result);
+            const output = formatFileOutline(result);
+            const isEmpty = !result || (Array.isArray(result) && result.length === 0);
+            const hint = await checkTextStubHint(args.repo, "get_file_outline", isEmpty);
+            return hint ? hint + output : output;
         },
     },
     {
@@ -387,8 +769,10 @@ const TOOL_DEFINITIONS = [
             if (args.include_related != null)
                 opts.include_related = args.include_related;
             const result = await getSymbol(args.repo, args.symbol_id, opts);
-            if (!result)
-                return null;
+            if (!result) {
+                const hint = await checkTextStubHint(args.repo, "get_symbol", true);
+                return hint ?? null;
+            }
             let text = formatSymbolCompact(result.symbol);
             if (result.related && result.related.length > 0) {
                 text += "\n\n--- children ---\n" + result.related.map((s) => `${s.kind} ${s.name}${s.signature ? s.signature : ""} [${s.file}:${s.start_line}]`).join("\n");
@@ -410,7 +794,9 @@ const TOOL_DEFINITIONS = [
         },
         handler: async (args) => {
             const syms = await getSymbols(args.repo, args.symbol_ids);
-            return formatSymbolsCompact(syms);
+            const output = formatSymbolsCompact(syms);
+            const hint = await checkTextStubHint(args.repo, "get_symbols", syms.length === 0);
+            return hint ? hint + output : output;
         },
     },
     {
@@ -470,16 +856,17 @@ const TOOL_DEFINITIONS = [
                 return findReferencesBatch(args.repo, names, args.file_pattern);
             }
             const refs = await findReferences(args.repo, args.symbol_name, args.file_pattern);
-            // Compact format: drop col, use file:line: context (matches grep output)
-            return formatRefsCompact(refs);
+            const output = formatRefsCompact(refs);
+            const hint = await checkTextStubHint(args.repo, "find_references", refs.length === 0);
+            return hint ? hint + output : output;
         },
     },
     {
         name: "trace_call_chain",
         category: "graph",
-        searchHint: "trace call chain callers callees dependency graph mermaid",
+        searchHint: "trace call chain callers callees dependency graph mermaid react hooks",
         outputSchema: OutputSchemas.callTree,
-        description: "Trace call chain: callers or callees. output_format='mermaid' for diagram.",
+        description: "Trace call chain: callers or callees. output_format='mermaid' for diagram. filter_react_hooks=true skips useState/useEffect etc. for cleaner React graphs.",
         schema: {
             repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
             symbol_name: z.string().describe("Name of the symbol to trace"),
@@ -488,6 +875,7 @@ const TOOL_DEFINITIONS = [
             include_source: zBool().describe("Include full source code of each symbol (default: false)"),
             include_tests: zBool().describe("Include test files in trace results (default: false)"),
             output_format: z.enum(["json", "mermaid"]).optional().describe("Output format: 'json' (default) or 'mermaid' (flowchart diagram)"),
+            filter_react_hooks: zBool().describe("Skip edges to React stdlib hooks (useState, useEffect, etc.) to reduce call graph noise in React codebases (default: false)"),
         },
         handler: async (args) => {
             const result = await traceCallChain(args.repo, args.symbol_name, args.direction, {
@@ -495,8 +883,12 @@ const TOOL_DEFINITIONS = [
                 include_source: args.include_source,
                 include_tests: args.include_tests,
                 output_format: args.output_format,
+                filter_react_hooks: args.filter_react_hooks,
             });
-            return formatCallTree(result);
+            const output = formatCallTree(result);
+            const isEmpty = typeof result === "object" && result != null && "children" in result && Array.isArray(result.children) && result.children.length === 0;
+            const hint = await checkTextStubHint(args.repo, "trace_call_chain", isEmpty);
+            return hint ? hint + output : output;
         },
     },
     {
@@ -521,6 +913,120 @@ const TOOL_DEFINITIONS = [
             return formatImpactAnalysis(result);
         },
     },
+    {
+        name: "trace_component_tree",
+        category: "graph",
+        searchHint: "react component tree composition render jsx parent child hierarchy",
+        description: "Trace React component composition tree from a root component. Shows which components render which via JSX. React equivalent of trace_call_chain. output_format='mermaid' for diagram.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            component_name: z.string().describe("Root component name (must have kind 'component' in index)"),
+            depth: zNum().describe("Maximum depth of composition tree (default: 3)"),
+            include_source: zBool().describe("Include full source of each component (default: false)"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+            output_format: z.enum(["json", "mermaid"]).optional().describe("Output format: 'json' (default) or 'mermaid'"),
+        },
+        handler: async (args) => {
+            const result = await traceComponentTree(args.repo, args.component_name, {
+                depth: args.depth,
+                include_source: args.include_source,
+                include_tests: args.include_tests,
+                output_format: args.output_format,
+            });
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        name: "analyze_hooks",
+        category: "analysis",
+        searchHint: "react hooks analyze inventory rule of hooks violations usestate useeffect custom",
+        description: "Analyze React hooks: inventory per component, Rule of Hooks violations (hook inside if/loop, hook after early return), custom hook composition, codebase-wide hook usage summary.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            component_name: z.string().optional().describe("Filter to single component/hook (default: all)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+            max_entries: zNum().describe("Max entries to return (default: 100)"),
+        },
+        handler: async (args) => {
+            const result = await analyzeHooks(args.repo, {
+                component_name: args.component_name,
+                file_pattern: args.file_pattern,
+                include_tests: args.include_tests,
+                max_entries: args.max_entries,
+            });
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        name: "analyze_renders",
+        category: "analysis",
+        searchHint: "react render performance inline props memo useCallback useMemo re-render risk optimization",
+        description: "Static re-render risk analysis for React components. Detects inline object/array/function props in JSX (new reference every render), unstable default values (= [] or = {}), and components missing React.memo that render children. Returns per-component risk level (low/medium/high) with actionable suggestions.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            component_name: z.string().optional().describe("Filter to single component (default: all)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+            max_entries: zNum().describe("Max entries to return (default: 100)"),
+        },
+        handler: async (args) => {
+            const result = await analyzeRenders(args.repo, {
+                component_name: args.component_name,
+                file_pattern: args.file_pattern,
+                include_tests: args.include_tests,
+                max_entries: args.max_entries,
+            });
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        name: "analyze_context_graph",
+        category: "analysis",
+        searchHint: "react context createContext provider useContext consumer re-render propagation",
+        description: "Map React context flows: createContext → Provider → useContext consumers. Shows which components consume each context and which provide values. Helps identify unnecessary re-renders from context value changes.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+        },
+        handler: async (args) => {
+            const index = await getCodeIndex(args.repo);
+            if (!index)
+                throw new Error(`Repository not found: ${args.repo}`);
+            const result = buildContextGraph(index.symbols);
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        name: "audit_compiler_readiness",
+        category: "analysis",
+        searchHint: "react compiler forget memoization bailout readiness migration adoption auto-memo",
+        description: "Audit React Compiler (v1.0) adoption readiness. Scans all components for patterns that cause silent bailout (side effects in render, ref reads, prop/state mutation, try/catch). Returns readiness score (0-100), prioritized fix list, and count of redundant manual memoization safe to remove post-adoption. No competitor offers codebase-wide compiler readiness analysis.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+        },
+        handler: async (args) => {
+            const result = await auditCompilerReadiness(args.repo, {
+                file_pattern: args.file_pattern,
+                include_tests: args.include_tests,
+            });
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        name: "react_quickstart",
+        category: "analysis",
+        searchHint: "react onboarding day-1 overview stack inventory components hooks critical issues",
+        description: "Day-1 onboarding composite for React projects. Single call returns: component/hook inventory, stack detection (state mgmt, routing, UI lib, form lib, build tool), critical pattern scan (XSS, Rule of Hooks, memory leaks), top hook usage, and suggested next queries. Replaces 5-6 manual tool calls. First tool to run on an unfamiliar React codebase.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+        },
+        handler: async (args) => {
+            const result = await reactQuickstart(args.repo);
+            return JSON.stringify(result, null, 2);
+        },
+    },
     {
         name: "trace_route",
         category: "graph",
@@ -842,7 +1348,10 @@ const TOOL_DEFINITIONS = [
                 file_pattern: args.file_pattern,
                 include_tests: args.include_tests,
             });
-            return formatDeadCode(result);
+            const output = formatDeadCode(result);
+            const isEmpty = !result || (result.candidates?.length ?? 0) === 0;
+            const hint = await checkTextStubHint(args.repo, "find_dead_code", isEmpty);
+            return hint ? hint + output : output;
         },
     },
     {
@@ -893,7 +1402,10 @@ const TOOL_DEFINITIONS = [
                 min_complexity: args.min_complexity,
                 include_tests: args.include_tests,
             });
-            return formatComplexity(result);
+            const output = formatComplexity(result);
+            const isEmpty = !result || (result.functions?.length ?? 0) === 0;
+            const hint = await checkTextStubHint(args.repo, "analyze_complexity", isEmpty);
+            return hint ? hint + output : output;
         },
     },
     {
@@ -1118,247 +1630,1936 @@ const TOOL_DEFINITIONS = [
             return formatSecrets(result);
         },
     },
-    // --- Memory consolidation ---
+    // --- Kotlin tools (discoverable via discover_tools(query="kotlin")) ---
     {
-        name: "consolidate_memories",
-        category: "conversations",
-        searchHint: "consolidate memories dream knowledge MEMORY.md decisions solutions patterns",
-        description: "Consolidate conversations into MEMORY.md — decisions, solutions, patterns.",
+        name: "find_extension_functions",
+        category: "analysis",
+        requiresLanguage: "kotlin",
+        searchHint: "kotlin extension function receiver type method discovery",
+        description: "Find all Kotlin extension functions for a given receiver type. Scans indexed symbols for signatures matching 'ReceiverType.' prefix.",
         schema: {
-            project_path: z.string().optional().describe("Project path (auto-detects from cwd if omitted)"),
-            output_path: z.string().optional().describe("Custom output file path (default: MEMORY.md in project root)"),
-            min_confidence: z.enum(["high", "medium", "low"]).optional().describe("Minimum confidence level for extracted memories (default: low)"),
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            receiver_type: z.string().describe("Receiver type name, e.g. 'String', 'List', 'User'"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
         },
         handler: async (args) => {
             const opts = {};
-            if (typeof args.output_path === "string")
-                opts.output_path = args.output_path;
-            if (typeof args.min_confidence === "string")
-                opts.min_confidence = args.min_confidence;
-            const result = await consolidateMemories(args.project_path, opts);
-            return result;
+            if (typeof args.file_pattern === "string")
+                opts.file_pattern = args.file_pattern;
+            return await findExtensionFunctions(args.repo, args.receiver_type, opts);
         },
     },
     {
-        name: "read_memory",
-        category: "conversations",
-        searchHint: "read memory MEMORY.md institutional knowledge past decisions",
-        description: "Read MEMORY.md knowledge file with past decisions and patterns.",
+        name: "analyze_sealed_hierarchy",
+        category: "analysis",
+        requiresLanguage: "kotlin",
+        searchHint: "kotlin sealed class interface subtype when exhaustive branch missing hierarchy",
+        description: "Analyze a Kotlin sealed class/interface: find all subtypes and check when() blocks for exhaustiveness (missing branches).",
         schema: {
-            project_path: z.string().optional().describe("Project path (default: current directory)"),
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            sealed_class: z.string().describe("Name of the sealed class or interface to analyze"),
         },
         handler: async (args) => {
-            const result = await readMemory(args.project_path);
-            if (!result)
-                return { error: "No MEMORY.md found. Run consolidate_memories first." };
-            return result.content;
+            return await analyzeSealedHierarchy(args.repo, args.sealed_class);
         },
     },
-    // --- Coordinator ---
     {
-        name: "create_analysis_plan",
-        category: "meta",
-        searchHint: "create plan multi-step analysis workflow coordinator scratchpad",
-        description: "Create multi-step analysis plan with shared scratchpad and dependencies.",
+        name: "trace_hilt_graph",
+        category: "analysis",
+        searchHint: "hilt dagger DI dependency injection viewmodel inject module provides binds android kotlin graph",
+        description: "Trace a Hilt DI dependency tree rooted at a class annotated with @HiltViewModel / @AndroidEntryPoint / @HiltAndroidApp. Returns constructor dependencies with matching @Provides/@Binds providers and their module. Unresolved deps are flagged.",
         schema: {
-            title: z.string().describe("Plan title describing the analysis goal"),
-            steps: z.union([
-                z.array(z.object({
-                    description: z.string(),
-                    tool: z.string(),
-                    args: z.record(z.string(), z.unknown()),
-                    result_key: z.string().optional(),
-                    depends_on: z.array(z.string()).optional(),
-                })),
-                z.string().transform((s) => JSON.parse(s)),
-            ]).describe("Steps array: {description, tool, args, result_key?, depends_on?}. JSON string OK."),
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            class_name: z.string().describe("Name of the Hilt-annotated class (e.g. 'UserViewModel')"),
+            depth: z.number().optional().describe("Max traversal depth (default: 1)"),
         },
         handler: async (args) => {
-            const result = await createAnalysisPlan(args.title, args.steps);
-            return result;
+            const opts = {};
+            if (typeof args.depth === "number")
+                opts.depth = args.depth;
+            return await traceHiltGraph(args.repo, args.class_name, opts);
         },
     },
     {
-        name: "scratchpad_write",
-        category: "meta",
-        searchHint: "scratchpad write store knowledge cross-step data persist",
-        description: "Write key-value to plan scratchpad for cross-step knowledge sharing.",
+        name: "trace_suspend_chain",
+        category: "analysis",
+        searchHint: "kotlin coroutine suspend dispatcher withContext runBlocking Thread.sleep blocking chain trace anti-pattern",
+        description: "Trace the call chain of a Kotlin suspend function, emitting dispatcher transitions (withContext(Dispatchers.X)) and warnings for coroutine anti-patterns: runBlocking inside suspend, Thread.sleep, non-cancellable while(true) loops. Lexical walk — follows callee names found in the source, filtered to suspend-only functions.",
         schema: {
-            plan_id: z.string().describe("Analysis plan identifier"),
-            key: z.string().describe("Key name for the entry"),
-            value: z.string().describe("Value to store"),
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            function_name: z.string().describe("Name of the suspend function to trace"),
+            depth: z.number().optional().describe("Max chain depth (default: 3)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.depth === "number")
+                opts.depth = args.depth;
+            return await traceSuspendChain(args.repo, args.function_name, opts);
         },
-        handler: async (args) => writeScratchpad(args.plan_id, args.key, args.value),
     },
     {
-        name: "scratchpad_read",
-        category: "meta",
-        searchHint: "scratchpad read retrieve knowledge entry",
-        description: "Read a key from a plan's scratchpad. Returns the stored value or null if not found.",
+        name: "analyze_kmp_declarations",
+        category: "analysis",
+        searchHint: "kotlin multiplatform kmp expect actual source set common main android ios jvm js missing orphan",
+        description: "Validate Kotlin Multiplatform expect/actual declarations across source sets. For each `expect` in commonMain, check every platform source set (androidMain/iosMain/jvmMain/jsMain/etc. discovered from the repo layout) for a matching `actual`. Reports fully matched pairs, expects missing on a platform, and orphan actuals with no corresponding expect.",
         schema: {
-            plan_id: z.string().describe("Analysis plan identifier"),
-            key: z.string().describe("Key name to read"),
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
         },
         handler: async (args) => {
-            const result = await readScratchpad(args.plan_id, args.key);
-            return result ?? { error: "Key not found in scratchpad" };
+            return await analyzeKmpDeclarations(args.repo);
         },
     },
+    // --- Kotlin Wave 3 tools ---
     {
-        name: "scratchpad_list",
-        category: "meta",
-        searchHint: "scratchpad list entries keys",
-        description: "List all entries in a plan's scratchpad with their sizes.",
+        name: "trace_compose_tree",
+        category: "analysis",
+        searchHint: "kotlin compose composable component tree hierarchy ui call graph jetpack preview",
+        description: "Build a Jetpack Compose component hierarchy rooted at a @Composable function. Traces PascalCase calls matching indexed composables, excludes @Preview. Reports tree depth, leaf components, and total component count.",
         schema: {
-            plan_id: z.string().describe("Analysis plan identifier"),
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            root_name: z.string().describe("Name of the root @Composable function (e.g. 'HomeScreen')"),
+            depth: z.number().optional().describe("Max tree depth (default: 10)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.depth === "number")
+                opts.depth = args.depth;
+            return await traceComposeTree(args.repo, args.root_name, opts);
         },
-        handler: (args) => listScratchpad(args.plan_id),
     },
     {
-        name: "update_step_status",
-        category: "meta",
-        searchHint: "update step status plan progress completed failed",
-        description: "Update step status in plan. Auto-updates plan status on completion.",
+        name: "analyze_compose_recomposition",
+        category: "analysis",
+        searchHint: "kotlin compose recomposition unstable remember mutableStateOf performance skip lambda collection",
+        description: "Detect recomposition hazards in @Composable functions: mutableStateOf without remember (critical), unstable collection parameters (List/Map/Set), excessive function-type params. Scans all indexed composables, skipping @Preview.",
         schema: {
-            plan_id: z.string().describe("Analysis plan identifier"),
-            step_id: z.string().describe("Step identifier (e.g. step_1)"),
-            status: z.enum(["pending", "in_progress", "completed", "failed", "skipped"]).describe("New status for the step"),
-            error: z.string().optional().describe("Error message if status is 'failed'"),
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
         },
         handler: async (args) => {
-            const result = await updateStepStatus(args.plan_id, args.step_id, args.status, args.error);
-            return result;
+            const opts = {};
+            if (typeof args.file_pattern === "string")
+                opts.file_pattern = args.file_pattern;
+            return await analyzeComposeRecomposition(args.repo, opts);
         },
     },
     {
-        name: "get_analysis_plan",
-        category: "meta",
-        searchHint: "get plan status steps progress",
-        description: "Get the current state of an analysis plan including all step statuses.",
+        name: "trace_room_schema",
+        category: "analysis",
+        searchHint: "kotlin room database entity dao query insert update delete schema sqlite persistence android",
+        description: "Build a Room persistence schema graph: @Entity classes (with table names, primary keys), @Dao interfaces (with @Query SQL extraction), @Database declarations (with entity refs and version). Index-only.",
         schema: {
-            plan_id: z.string().describe("Analysis plan identifier"),
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
         },
         handler: async (args) => {
-            const plan = getPlan(args.plan_id);
-            return plan ?? { error: "Plan not found" };
+            return await traceRoomSchema(args.repo);
         },
     },
     {
-        name: "list_analysis_plans",
-        category: "meta",
-        searchHint: "list plans active analysis workflows",
-        description: "List all active analysis plans with their completion status.",
-        schema: {},
-        handler: async () => listPlans(),
+        name: "extract_kotlin_serialization_contract",
+        category: "analysis",
+        searchHint: "kotlin serialization serializable json schema serialname field type api contract data class",
+        description: "Derive JSON field schema from @Serializable data classes. Extracts field names, types, @SerialName remapping, nullable flags, and defaults.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            class_name: z.string().optional().describe("Filter to a single class by name"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.file_pattern === "string")
+                opts.file_pattern = args.file_pattern;
+            if (typeof args.class_name === "string")
+                opts.class_name = args.class_name;
+            return await extractKotlinSerializationContract(args.repo, opts);
+        },
     },
-    // --- Review diff ---
     {
-        name: "review_diff",
-        category: "diff",
-        searchHint: "review diff static analysis git changes secrets breaking-changes complexity dead-code blast-radius",
-        description: "Run 9 parallel static analysis checks on a git diff: secrets, breaking changes, coupling gaps, complexity, dead-code, blast-radius, bug-patterns, test-gaps, hotspots. Returns a scored verdict (pass/warn/fail) with tiered findings.",
+        name: "trace_flow_chain",
+        category: "analysis",
+        searchHint: "kotlin flow coroutine operator map filter collect stateIn shareIn catch chain pipeline reactive",
+        description: "Analyze a Kotlin Flow<T> operator chain: detects 50+ operators, reports ordered list, warns about .collect without .catch and .stateIn without lifecycle scope.",
         schema: {
             repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
-            since: z.string().optional().describe("Base git ref (default: HEAD~1)"),
-            until: z.string().optional().describe("Target ref. Default: HEAD. Special: WORKING, STAGED"),
-            checks: z.string().optional().describe("Comma-separated check names (default: all)"),
-            exclude_patterns: z.string().optional().describe("Comma-separated globs to exclude"),
-            token_budget: zNum().describe("Max tokens (default: 15000)"),
-            max_files: zNum().describe("Warn above N files (default: 50)"),
-            check_timeout_ms: zNum().describe("Per-check timeout ms (default: 8000)"),
+            symbol_name: z.string().describe("Name of the function or property containing the Flow chain"),
         },
         handler: async (args) => {
-            const checksArr = args.checks
+            return await traceFlowChain(args.repo, args.symbol_name);
+        },
+    },
+    // --- Python tools (all discoverable via discover_tools(query="python")) ---
+    {
+        name: "get_model_graph",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python django sqlalchemy orm model relationship foreignkey manytomany entity graph mermaid",
+        description: "Extract ORM model relationships (Django ForeignKey/M2M/O2O, SQLAlchemy relationship). JSON or mermaid erDiagram.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            output_format: z.enum(["json", "mermaid"]).optional().describe("Output as structured JSON or mermaid erDiagram"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.output_format != null)
+                opts.output_format = args.output_format;
+            return await getModelGraph(args.repo, opts);
+        },
+    },
+    {
+        name: "get_test_fixtures",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python pytest fixture conftest scope autouse dependency graph session function",
+        description: "Extract pytest fixture dependency graph: conftest hierarchy, scope, autouse, fixture-to-fixture deps.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            return await getTestFixtures(args.repo, opts);
+        },
+    },
+    {
+        name: "find_framework_wiring",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python django signal receiver celery task middleware management command flask fastapi event wiring",
+        description: "Discover implicit control flow: Django signals, Celery tasks/.delay() calls, middleware, management commands, Flask init_app, FastAPI events.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            return await findFrameworkWiring(args.repo, opts);
+        },
+    },
+    {
+        name: "run_ruff",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python ruff lint check bugbear performance simplify security async unused argument",
+        description: "Run ruff linter with symbol graph correlation. Configurable rule categories (B, PERF, SIM, UP, S, ASYNC, RET, ARG).",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            categories: z.array(z.string()).optional().describe("Rule categories to enable (default: B,PERF,SIM,UP,S,ASYNC,RET,ARG)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            max_results: zFiniteNumber.optional().describe("Max findings to return (default: 100)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.categories != null)
+                opts.categories = args.categories;
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.max_results != null)
+                opts.max_results = args.max_results;
+            return await runRuff(args.repo, opts);
+        },
+    },
+    {
+        name: "parse_pyproject",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python pyproject toml dependencies version build system entry points scripts tools ruff pytest mypy",
+        description: "Parse pyproject.toml: name, version, Python version, build system, dependencies, optional groups, entry points, configured tools.",
+        schema: { repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)") },
+        handler: async (args) => { return await parsePyproject(args.repo); },
+    },
+    {
+        name: "resolve_constant_value",
+        category: "analysis",
+        searchHint: "python typescript nestjs resolve constant value literal alias import default parameter propagation",
+        description: "Resolve Python or TypeScript constants and function default values through simple aliases and import chains. Returns literals or explicit unresolved reasons.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            symbol_name: z.string().describe("Constant, function, or method name to resolve"),
+            file_pattern: z.string().optional().describe("Filter candidate symbols by file path substring"),
+            language: z.enum(["python", "typescript"]).optional().describe("Force resolver language instead of auto-inference"),
+            max_depth: zFiniteNumber.optional().describe("Maximum alias/import resolution depth (default: 8)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.language != null)
+                opts.language = args.language;
+            if (args.max_depth != null)
+                opts.max_depth = args.max_depth;
+            return await resolveConstantValue(args.repo, args.symbol_name, opts);
+        },
+    },
+    {
+        name: "effective_django_view_security",
+        category: "security",
+        requiresLanguage: "python",
+        searchHint: "python django view auth csrf login_required middleware mixin route security posture",
+        description: "Assess effective Django view security from decorators, mixins, settings middleware, and optional route resolution.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            path: z.string().optional().describe("Django route path to resolve first, e.g. /settings/"),
+            symbol_name: z.string().optional().describe("View function/class/method name when you already know the symbol"),
+            file_pattern: z.string().optional().describe("Filter candidate symbols by file path substring"),
+            settings_file: z.string().optional().describe("Explicit Django settings file path (auto-detects if omitted)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.path != null)
+                opts.path = args.path;
+            if (args.symbol_name != null)
+                opts.symbol_name = args.symbol_name;
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.settings_file != null)
+                opts.settings_file = args.settings_file;
+            return await effectiveDjangoViewSecurity(args.repo, opts);
+        },
+    },
+    {
+        name: "taint_trace",
+        category: "security",
+        requiresLanguage: "python",
+        searchHint: "python django taint data flow source sink request get post redirect mark_safe cursor execute subprocess session trace",
+        description: "Trace Python/Django user-controlled data from request sources to security sinks like redirect, mark_safe, cursor.execute, subprocess, requests/httpx, open, or session writes.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            framework: z.enum(["python-django"]).optional().describe("Currently only python-django is implemented"),
+            file_pattern: z.string().optional().describe("Restrict analysis to matching Python files"),
+            source_patterns: z.array(z.string()).optional().describe("Optional source pattern allowlist (defaults to request.* presets)"),
+            sink_patterns: z.array(z.string()).optional().describe("Optional sink pattern allowlist (defaults to built-in security sinks)"),
+            max_depth: zFiniteNumber.optional().describe("Maximum interprocedural helper depth (default: 4)"),
+            max_traces: zFiniteNumber.optional().describe("Maximum traces to return before truncation (default: 50)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.framework != null)
+                opts.framework = args.framework;
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.source_patterns != null)
+                opts.source_patterns = args.source_patterns;
+            if (args.sink_patterns != null)
+                opts.sink_patterns = args.sink_patterns;
+            if (args.max_depth != null)
+                opts.max_depth = args.max_depth;
+            if (args.max_traces != null)
+                opts.max_traces = args.max_traces;
+            return await taintTrace(args.repo, opts);
+        },
+    },
+    {
+        name: "find_python_callers",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python callers call site usage trace cross module import delay apply_async constructor",
+        description: "Find all call sites of a Python symbol: direct calls, method calls, Celery .delay()/.apply_async(), constructor, references.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            target_name: z.string().describe("Name of the target function/class/method"),
+            target_file: z.string().optional().describe("Disambiguate target by file path substring"),
+            file_pattern: z.string().optional().describe("Restrict caller search scope"),
+            max_results: zFiniteNumber.optional().describe("Max callers to return (default: 100)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.target_file != null)
+                opts.target_file = args.target_file;
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.max_results != null)
+                opts.max_results = args.max_results;
+            return await findPythonCallers(args.repo, args.target_name, opts);
+        },
+    },
+    {
+        name: "analyze_django_settings",
+        category: "security",
+        requiresLanguage: "python",
+        searchHint: "python django settings security debug secret key allowed hosts csrf middleware cookie hsts cors",
+        description: "Audit Django settings.py: 15 security/config checks (DEBUG, SECRET_KEY, CSRF, CORS, HSTS, cookies, sqlite, middleware).",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            settings_file: z.string().optional().describe("Explicit settings file path (auto-detects if omitted)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.settings_file != null)
+                opts.settings_file = args.settings_file;
+            return await analyzeDjangoSettings(args.repo, opts);
+        },
+    },
+    {
+        name: "run_mypy",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python mypy type check error strict return incompatible argument missing",
+        description: "Run mypy type checker with symbol correlation. Parses error codes, maps to containing symbols.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            strict: zBool().describe("Enable mypy --strict mode"),
+            max_results: zFiniteNumber.optional().describe("Max findings (default: 100)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.strict != null)
+                opts.strict = args.strict;
+            if (args.max_results != null)
+                opts.max_results = args.max_results;
+            return await runMypy(args.repo, opts);
+        },
+    },
+    {
+        name: "run_pyright",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python pyright type check reportMissingImports reportGeneralTypeIssues",
+        description: "Run pyright type checker with symbol correlation. Parses JSON diagnostics, maps to containing symbols.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            strict: zBool().describe("Enable strict level"),
+            max_results: zFiniteNumber.optional().describe("Max findings (default: 100)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.strict != null)
+                opts.strict = args.strict;
+            if (args.max_results != null)
+                opts.max_results = args.max_results;
+            return await runPyright(args.repo, opts);
+        },
+    },
+    {
+        name: "analyze_python_deps",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python dependency version outdated vulnerable CVE pypi osv requirements pyproject",
+        description: "Python dependency analysis: parse pyproject.toml/requirements.txt, detect unpinned deps, optional PyPI freshness, optional OSV.dev CVE scan.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            check_pypi: zBool().describe("Check PyPI for latest versions (network, opt-in)"),
+            check_vulns: zBool().describe("Check OSV.dev for CVEs (network, opt-in)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.check_pypi != null)
+                opts.check_pypi = args.check_pypi;
+            if (args.check_vulns != null)
+                opts.check_vulns = args.check_vulns;
+            return await analyzePythonDeps(args.repo, opts);
+        },
+    },
+    {
+        name: "trace_fastapi_depends",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python fastapi depends dependency injection security scopes oauth2 authentication auth endpoint",
+        description: "Trace FastAPI Depends()/Security() dependency injection chains recursively from route handlers. Detects yield deps (resource cleanup), Security() with scopes, shared deps across endpoints, endpoints without auth.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            endpoint: z.string().optional().describe("Focus on a specific endpoint function name"),
+            max_depth: zFiniteNumber.optional().describe("Max dependency tree depth (default: 5)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.endpoint != null)
+                opts.endpoint = args.endpoint;
+            if (args.max_depth != null)
+                opts.max_depth = args.max_depth;
+            return await traceFastAPIDepends(args.repo, opts);
+        },
+    },
+    {
+        name: "analyze_async_correctness",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python async await asyncio blocking sync requests sleep subprocess django sqlalchemy ORM coroutine fastapi",
+        description: "Detect 8 asyncio pitfalls in async def: blocking requests/sleep/IO/subprocess, sync SQLAlchemy/Django ORM in async views, async without await, asyncio.create_task without ref storage.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            rules: z.array(z.string()).optional().describe("Subset of rules to run"),
+            max_results: zFiniteNumber.optional().describe("Max findings (default: 200)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.rules != null)
+                opts.rules = args.rules;
+            if (args.max_results != null)
+                opts.max_results = args.max_results;
+            return await analyzeAsyncCorrectness(args.repo, opts);
+        },
+    },
+    {
+        name: "get_pydantic_models",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python pydantic basemodel fastapi schema request response contract validator field constraint type classdiagram",
+        description: "Extract Pydantic models: fields with types, validators, Field() constraints, model_config, cross-model references (list[X], Optional[Y]), inheritance. JSON or mermaid classDiagram.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            output_format: z.enum(["json", "mermaid"]).optional().describe("Output as structured JSON or mermaid classDiagram"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.output_format != null)
+                opts.output_format = args.output_format;
+            return await getPydanticModels(args.repo, opts);
+        },
+    },
+    {
+        name: "python_audit",
+        category: "analysis",
+        requiresLanguage: "python",
+        searchHint: "python audit health score compound project review django security circular patterns celery dependencies dead code task shared_task delay apply_async chain group chord canvas retry orphan queue import cycle ImportError TYPE_CHECKING DFS",
+        description: "Compound Python project health audit: circular imports + Django settings + anti-patterns (17) + framework wiring + Celery orphans + pytest fixtures + deps + dead code. Runs in parallel, returns unified health score (0-100) + severity counts + prioritized top_risks list.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter by file path substring"),
+            checks: z.array(z.string()).optional().describe("Subset of checks: circular_imports, django_settings, anti_patterns, framework_wiring, celery, pytest_fixtures, dependencies, dead_code"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.checks != null)
+                opts.checks = args.checks;
+            return await pythonAudit(args.repo, opts);
+        },
+    },
+    // --- PHP / Yii2 tools (all discoverable via discover_tools(query="php")) ---
+    {
+        name: "resolve_php_namespace",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "php namespace resolve PSR-4 autoload composer class file path yii2 laravel symfony",
+        description: "Resolve a PHP FQCN to file path via composer.json PSR-4 autoload mapping.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            class_name: z.string().describe("Fully-qualified class name, e.g. 'App\\\\Models\\\\User'"),
+        },
+        handler: async (args) => {
+            return await resolvePhpNamespace(args.repo, args.class_name);
+        },
+    },
+    {
+        name: "trace_php_event",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "php event listener trigger handler chain yii2 laravel observer dispatch",
+        description: "Trace PHP event → listener chains: find trigger() calls and matching on() handlers.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            event_name: z.string().optional().describe("Filter by specific event name"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.event_name === "string")
+                opts.event_name = args.event_name;
+            return await tracePhpEvent(args.repo, opts);
+        },
+    },
+    {
+        name: "find_php_views",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "php view render template controller widget yii2 laravel blade",
+        description: "Map PHP controller render() calls to view files. Yii2/Laravel convention-aware.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            controller: z.string().optional().describe("Filter by controller class name"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.controller === "string")
+                opts.controller = args.controller;
+            return await findPhpViews(args.repo, opts);
+        },
+    },
+    {
+        name: "resolve_php_service",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "php service locator DI container component resolve yii2 laravel facade provider",
+        description: "Resolve PHP service locator references (Yii::$app->X, Laravel facades) to concrete classes via config parsing.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            service_name: z.string().optional().describe("Filter by specific service name (e.g. 'db', 'user', 'cache')"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.service_name === "string")
+                opts.service_name = args.service_name;
+            return await resolvePhpService(args.repo, opts);
+        },
+    },
+    {
+        name: "php_security_scan",
+        category: "security",
+        requiresLanguage: "php",
+        searchHint: "php security scan audit vulnerability injection XSS CSRF SQL eval exec unserialize",
+        description: "Scan PHP code for security vulnerabilities: SQL injection, XSS, eval, exec, unserialize, file inclusion. Parallel pattern checks.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Glob pattern to filter scanned files (default: '*.php')"),
+            checks: z.array(z.string()).optional().describe("Subset of checks to run: sql-injection-php, xss-php, eval-php, exec-php, unserialize-php, file-include-var, unescaped-yii-view, raw-query-yii"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.file_pattern === "string")
+                opts.file_pattern = args.file_pattern;
+            if (Array.isArray(args.checks))
+                opts.checks = args.checks;
+            return await phpSecurityScan(args.repo, opts);
+        },
+    },
+    {
+        name: "php_project_audit",
+        category: "analysis",
+        requiresLanguage: "php",
+        searchHint: "php project audit health quality technical debt code review comprehensive yii2 laravel activerecord eloquent model schema relations rules behaviors table orm n+1 query foreach eager loading relation god class anti-pattern too many methods oversized",
+        description: "Compound PHP project audit: security scan + ActiveRecord analysis + N+1 detection + god model detection + health score. Runs checks in parallel.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Glob pattern to filter analyzed files"),
+            checks: z.string().optional().describe("Comma-separated checks: n_plus_one, god_model, activerecord, security, events, views, services, namespace. Default: all"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.file_pattern === "string")
+                opts.file_pattern = args.file_pattern;
+            if (typeof args.checks === "string" && args.checks.trim()) {
+                opts.checks = args.checks.split(",").map((c) => c.trim()).filter(Boolean);
+            }
+            return await phpProjectAudit(args.repo, opts);
+        },
+    },
+    // --- Memory consolidation ---
+    {
+        name: "consolidate_memories",
+        category: "conversations",
+        searchHint: "consolidate memories dream knowledge MEMORY.md decisions solutions patterns",
+        description: "Consolidate conversations into MEMORY.md — decisions, solutions, patterns.",
+        schema: {
+            project_path: z.string().optional().describe("Project path (auto-detects from cwd if omitted)"),
+            output_path: z.string().optional().describe("Custom output file path (default: MEMORY.md in project root)"),
+            min_confidence: z.enum(["high", "medium", "low"]).optional().describe("Minimum confidence level for extracted memories (default: low)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.output_path === "string")
+                opts.output_path = args.output_path;
+            if (typeof args.min_confidence === "string")
+                opts.min_confidence = args.min_confidence;
+            const result = await consolidateMemories(args.project_path, opts);
+            return result;
+        },
+    },
+    {
+        name: "read_memory",
+        category: "conversations",
+        searchHint: "read memory MEMORY.md institutional knowledge past decisions",
+        description: "Read MEMORY.md knowledge file with past decisions and patterns.",
+        schema: {
+            project_path: z.string().optional().describe("Project path (default: current directory)"),
+        },
+        handler: async (args) => {
+            const result = await readMemory(args.project_path);
+            if (!result)
+                return { error: "No MEMORY.md found. Run consolidate_memories first." };
+            return result.content;
+        },
+    },
+    // --- Coordinator ---
+    {
+        name: "create_analysis_plan",
+        category: "meta",
+        searchHint: "create plan multi-step analysis workflow coordinator scratchpad",
+        description: "Create multi-step analysis plan with shared scratchpad and dependencies.",
+        schema: {
+            title: z.string().describe("Plan title describing the analysis goal"),
+            steps: z.union([
+                z.array(z.object({
+                    description: z.string(),
+                    tool: z.string(),
+                    args: z.record(z.string(), z.unknown()),
+                    result_key: z.string().optional(),
+                    depends_on: z.array(z.string()).optional(),
+                })),
+                z.string().transform((s) => JSON.parse(s)),
+            ]).describe("Steps array: {description, tool, args, result_key?, depends_on?}. JSON string OK."),
+        },
+        handler: async (args) => {
+            const result = await createAnalysisPlan(args.title, args.steps);
+            return result;
+        },
+    },
+    {
+        name: "scratchpad_write",
+        category: "meta",
+        searchHint: "scratchpad write store knowledge cross-step data persist",
+        description: "Write key-value to plan scratchpad for cross-step knowledge sharing.",
+        schema: {
+            plan_id: z.string().describe("Analysis plan identifier"),
+            key: z.string().describe("Key name for the entry"),
+            value: z.string().describe("Value to store"),
+        },
+        handler: async (args) => writeScratchpad(args.plan_id, args.key, args.value),
+    },
+    {
+        name: "scratchpad_read",
+        category: "meta",
+        searchHint: "scratchpad read retrieve knowledge entry",
+        description: "Read a key from a plan's scratchpad. Returns the stored value or null if not found.",
+        schema: {
+            plan_id: z.string().describe("Analysis plan identifier"),
+            key: z.string().describe("Key name to read"),
+        },
+        handler: async (args) => {
+            const result = await readScratchpad(args.plan_id, args.key);
+            return result ?? { error: "Key not found in scratchpad" };
+        },
+    },
+    {
+        name: "scratchpad_list",
+        category: "meta",
+        searchHint: "scratchpad list entries keys",
+        description: "List all entries in a plan's scratchpad with their sizes.",
+        schema: {
+            plan_id: z.string().describe("Analysis plan identifier"),
+        },
+        handler: (args) => listScratchpad(args.plan_id),
+    },
+    {
+        name: "update_step_status",
+        category: "meta",
+        searchHint: "update step status plan progress completed failed",
+        description: "Update step status in plan. Auto-updates plan status on completion.",
+        schema: {
+            plan_id: z.string().describe("Analysis plan identifier"),
+            step_id: z.string().describe("Step identifier (e.g. step_1)"),
+            status: z.enum(["pending", "in_progress", "completed", "failed", "skipped"]).describe("New status for the step"),
+            error: z.string().optional().describe("Error message if status is 'failed'"),
+        },
+        handler: async (args) => {
+            const result = await updateStepStatus(args.plan_id, args.step_id, args.status, args.error);
+            return result;
+        },
+    },
+    {
+        name: "get_analysis_plan",
+        category: "meta",
+        searchHint: "get plan status steps progress",
+        description: "Get the current state of an analysis plan including all step statuses.",
+        schema: {
+            plan_id: z.string().describe("Analysis plan identifier"),
+        },
+        handler: async (args) => {
+            const plan = getPlan(args.plan_id);
+            return plan ?? { error: "Plan not found" };
+        },
+    },
+    {
+        name: "list_analysis_plans",
+        category: "meta",
+        searchHint: "list plans active analysis workflows",
+        description: "List all active analysis plans with their completion status.",
+        schema: {},
+        handler: async () => listPlans(),
+    },
+    // --- Review diff ---
+    {
+        name: "review_diff",
+        category: "diff",
+        searchHint: "review diff static analysis git changes secrets breaking-changes complexity dead-code blast-radius",
+        description: "Run 9 parallel static analysis checks on a git diff: secrets, breaking changes, coupling gaps, complexity, dead-code, blast-radius, bug-patterns, test-gaps, hotspots. Returns a scored verdict (pass/warn/fail) with tiered findings.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            since: z.string().optional().describe("Base git ref (default: HEAD~1)"),
+            until: z.string().optional().describe("Target ref. Default: HEAD. Special: WORKING, STAGED"),
+            checks: z.string().optional().describe("Comma-separated check names (default: all)"),
+            exclude_patterns: z.string().optional().describe("Comma-separated globs to exclude"),
+            token_budget: zNum().describe("Max tokens (default: 15000)"),
+            max_files: zNum().describe("Warn above N files (default: 50)"),
+            check_timeout_ms: zNum().describe("Per-check timeout ms (default: 8000)"),
+        },
+        handler: async (args) => {
+            const checksArr = args.checks
                 ? args.checks.split(",").map((c) => c.trim()).filter(Boolean)
                 : undefined;
             const excludeArr = args.exclude_patterns
                 ? args.exclude_patterns.split(",").map((p) => p.trim()).filter(Boolean)
                 : undefined;
             const opts = {
-                repo: args.repo,
+                repo: args.repo,
+            };
+            if (args.since != null)
+                opts.since = args.since;
+            if (args.until != null)
+                opts.until = args.until;
+            if (checksArr != null)
+                opts.checks = checksArr.join(",");
+            if (excludeArr != null)
+                opts.exclude_patterns = excludeArr;
+            if (args.token_budget != null)
+                opts.token_budget = args.token_budget;
+            if (args.max_files != null)
+                opts.max_files = args.max_files;
+            if (args.check_timeout_ms != null)
+                opts.check_timeout_ms = args.check_timeout_ms;
+            const result = await reviewDiff(args.repo, opts);
+            return formatReviewDiff(result);
+        },
+    },
+    // --- Stats ---
+    {
+        name: "usage_stats",
+        category: "meta",
+        searchHint: "usage statistics tool calls tokens timing metrics",
+        outputSchema: OutputSchemas.usageStats,
+        description: "Show usage statistics for all CodeSift tool calls (call counts, tokens, timing, repos)",
+        schema: {},
+        handler: async () => {
+            const stats = await getUsageStats();
+            return { report: formatUsageReport(stats) };
+        },
+    },
+    // ── Session context tools ───────────────────────────────────────────────
+    {
+        name: "get_session_snapshot",
+        category: "session",
+        searchHint: "session context snapshot compaction summary explored symbols files queries",
+        description: "Get a compact ~200 token snapshot of what was explored in this session. Designed to survive context compaction. Call proactively before long tasks.",
+        schema: {
+            repo: z.string().optional().describe("Filter to specific repo. Default: most recent repo."),
+        },
+        handler: async (args) => {
+            return formatSnapshot(getSessionState(), args.repo);
+        },
+    },
+    {
+        name: "get_session_context",
+        category: "session",
+        searchHint: "session context full explored symbols files queries negative evidence",
+        description: "Get full session context: explored symbols, files, queries, and negative evidence (searched but not found). Use get_session_snapshot for a compact version.",
+        schema: {
+            repo: z.string().optional().describe("Filter to specific repo"),
+            include_stale: zBool().describe("Include stale negative evidence entries (default: false)"),
+        },
+        handler: async (args) => {
+            const includeStale = args.include_stale === true || args.include_stale === "true";
+            return getContext(args.repo, includeStale);
+        },
+    },
+    // --- Project Analysis ---
+    {
+        name: "analyze_project",
+        category: "analysis",
+        searchHint: "project profile stack conventions middleware routes rate-limits auth detection",
+        description: "Analyze a repository to extract stack, file classifications, and framework-specific conventions. Returns a structured project profile (schema v1.0) with file:line evidence for convention-level facts.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            force: zBool().describe("Ignore cached results and re-analyze"),
+        },
+        handler: async (args) => {
+            const result = await analyzeProject(args.repo, {
+                force: args.force,
+            });
+            return result;
+        },
+    },
+    {
+        name: "get_extractor_versions",
+        category: "meta",
+        searchHint: "extractor version cache invalidation profile parser languages",
+        description: "Return parser_languages (tree-sitter symbol extractors) and profile_frameworks (analyze_project detectors). Text tools (search_text, get_file_tree) work on ALL files regardless — use this only for cache invalidation or to check symbol support for a specific language.",
+        schema: {},
+        handler: async () => getExtractorVersions(),
+    },
+    // --- Composite tools ---
+    {
+        name: "audit_scan",
+        category: "analysis",
+        searchHint: "audit scan code quality CQ gates dead code clones complexity patterns",
+        description: "Run 5 analysis tools in parallel, return findings keyed by CQ gate. One call replaces sequential find_dead_code + search_patterns + find_clones + analyze_complexity + analyze_hotspots. Returns: CQ8 (empty catch), CQ11 (complexity), CQ13 (dead code), CQ14 (clones), CQ17 (perf anti-patterns).",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+            checks: z.string().optional().describe("Comma-separated CQ gates to check (default: all). E.g. 'CQ8,CQ11,CQ14'"),
+        },
+        handler: async (args) => {
+            const checks = args.checks ? args.checks.split(",").map(s => s.trim()) : undefined;
+            const opts = {};
+            if (args.file_pattern)
+                opts.file_pattern = args.file_pattern;
+            if (args.include_tests)
+                opts.include_tests = args.include_tests;
+            if (checks)
+                opts.checks = checks;
+            const result = await auditScan(args.repo, opts);
+            return formatAuditScan(result);
+        },
+    },
+    // --- New tools (agent-requested) ---
+    {
+        name: "index_status",
+        category: "meta",
+        searchHint: "index status indexed repo check files symbols languages",
+        description: "Check whether a repository is indexed and return index metadata: file count, symbol count, language breakdown, text_stub languages (no parser). Use this before calling symbol-based tools on unfamiliar repos.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+        },
+        handler: async (args) => {
+            const result = await indexStatus(args.repo);
+            if (!result.indexed)
+                return "index_status: NOT INDEXED — run index_folder first";
+            const langs = Object.entries(result.language_breakdown ?? {})
+                .sort(([, a], [, b]) => b - a)
+                .map(([lang, count]) => `${lang}(${count})`)
+                .join(", ");
+            const parts = [
+                `index_status: indexed=true`,
+                `files: ${result.file_count} | symbols: ${result.symbol_count} | last_indexed: ${result.last_indexed}`,
+                `languages: ${langs}`,
+            ];
+            if (result.text_stub_languages) {
+                parts.push(`text_stub (no parser): ${result.text_stub_languages.join(", ")}`);
+            }
+            return parts.join("\n");
+        },
+    },
+    {
+        name: "find_perf_hotspots",
+        category: "analysis",
+        searchHint: "performance perf hotspot N+1 unbounded query sync handler pagination findMany pLimit",
+        description: "Scan for 6 performance anti-patterns: unbounded DB queries, sync I/O in handlers, N+1 loops, unbounded Promise.all, missing pagination, expensive recompute. Returns findings grouped by severity (high/medium/low) with fix hints.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            patterns: z.string().optional().describe("Comma-separated pattern names to check (default: all). Options: unbounded-query, sync-in-handler, n-plus-one, unbounded-parallel, missing-pagination, expensive-recompute"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+            max_results: zNum().describe("Max findings to return (default: 50)"),
+        },
+        handler: async (args) => {
+            const patterns = args.patterns
+                ? args.patterns.split(",").map((s) => s.trim()).filter(Boolean)
+                : undefined;
+            const opts = {};
+            if (patterns)
+                opts.patterns = patterns;
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.include_tests != null)
+                opts.include_tests = args.include_tests;
+            if (args.max_results != null)
+                opts.max_results = args.max_results;
+            const result = await findPerfHotspots(args.repo, opts);
+            return formatPerfHotspots(result);
+        },
+    },
+    {
+        name: "fan_in_fan_out",
+        category: "architecture",
+        searchHint: "fan-in fan-out coupling dependencies imports hub afferent efferent instability threshold",
+        description: "Analyze import graph to find most-imported files (fan-in), most-dependent files (fan-out), and hub files (high both — instability risk). Returns coupling score 0-100. Use min_fan_in/min_fan_out for threshold-based audits ('all files with fan_in > 50') instead of top_n cap.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            path: z.string().optional().describe("Focus on files in this directory"),
+            top_n: zNum().describe("How many entries per list (default: 20)"),
+            min_fan_in: zNum().describe("Only return files with fan_in >= this value (default: 0). Use for audits."),
+            min_fan_out: zNum().describe("Only return files with fan_out >= this value (default: 0). Use for audits."),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.path != null)
+                opts.path = args.path;
+            if (args.top_n != null)
+                opts.top_n = args.top_n;
+            if (args.min_fan_in != null)
+                opts.min_fan_in = args.min_fan_in;
+            if (args.min_fan_out != null)
+                opts.min_fan_out = args.min_fan_out;
+            const result = await fanInFanOut(args.repo, opts);
+            return formatFanInFanOut(result);
+        },
+    },
+    {
+        name: "co_change_analysis",
+        category: "architecture",
+        searchHint: "co-change temporal coupling git history Jaccard co-commit correlation cluster",
+        description: "Analyze git history to find files that frequently change together (temporal coupling). Returns file pairs ranked by Jaccard similarity, plus clusters of always-co-changed files. Useful for detecting hidden dependencies.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            since_days: zNum().describe("Analyze last N days of history (default: 180)"),
+            min_support: zNum().describe("Minimum co-commits to include a pair (default: 3)"),
+            min_jaccard: zNum().describe("Minimum Jaccard similarity threshold (default: 0.3)"),
+            path: z.string().optional().describe("Focus on files in this directory"),
+            top_n: zNum().describe("Max pairs to return (default: 30)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.since_days != null)
+                opts.since_days = args.since_days;
+            if (args.min_support != null)
+                opts.min_support = args.min_support;
+            if (args.min_jaccard != null)
+                opts.min_jaccard = args.min_jaccard;
+            if (args.path != null)
+                opts.path = args.path;
+            if (args.top_n != null)
+                opts.top_n = args.top_n;
+            const result = await coChangeAnalysis(args.repo, opts);
+            return formatCoChange(result);
+        },
+    },
+    {
+        name: "architecture_summary",
+        category: "architecture",
+        searchHint: "architecture summary overview structure stack framework communities coupling circular dependencies entry points",
+        description: "One-call architecture profile: stack detection, module communities, coupling hotspots, circular dependencies, LOC distribution, and entry points. Runs 5 analyses in parallel. Supports Mermaid diagram output.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            focus: z.string().optional().describe("Focus on this directory path"),
+            output_format: z.enum(["text", "mermaid"]).optional().describe("Output format (default: text)"),
+            token_budget: zNum().describe("Max tokens for output"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.focus != null)
+                opts.focus = args.focus;
+            if (args.output_format != null)
+                opts.output_format = args.output_format;
+            if (args.token_budget != null)
+                opts.token_budget = args.token_budget;
+            const result = await architectureSummary(args.repo, opts);
+            return formatArchitectureSummary(result);
+        },
+    },
+    {
+        name: "explain_query",
+        category: "analysis",
+        searchHint: "explain query SQL Prisma ORM database performance EXPLAIN ANALYZE findMany pagination index",
+        description: "Parse a Prisma call and generate approximate SQL with EXPLAIN ANALYZE. Detects: unbounded queries, N+1 risks from includes, missing indexes. MVP: Prisma only. Supports postgresql/mysql/sqlite dialects.",
+        schema: {
+            code: z.string().describe("Prisma code snippet (e.g. prisma.user.findMany({...}))"),
+            dialect: z.enum(["postgresql", "mysql", "sqlite"]).optional().describe("SQL dialect (default: postgresql)"),
+        },
+        handler: async (args) => {
+            const eqOpts = {};
+            if (args.dialect != null)
+                eqOpts.dialect = args.dialect;
+            const result = explainQuery(args.code, eqOpts);
+            const parts = [
+                `explain_query: prisma.${result.parsed.model}.${result.parsed.method}`,
+                `─── Generated SQL (${args.dialect ?? "postgresql"}) ───`,
+                `  ${result.sql}`,
+                `─── EXPLAIN command ───`,
+                `  ${result.explain_command}`,
+            ];
+            if (result.warnings.length > 0) {
+                parts.push("─── Warnings ───");
+                for (const w of result.warnings)
+                    parts.push(`  ⚠ ${w}`);
+            }
+            if (result.optimization_hints.length > 0) {
+                parts.push("─── Optimization hints ───");
+                for (const h of result.optimization_hints)
+                    parts.push(`  → ${h}`);
+            }
+            return parts.join("\n");
+        },
+    },
+    // --- NestJS analysis tools (sub-tools absorbed into nest_audit) ---
+    {
+        name: "nest_audit",
+        category: "nestjs",
+        searchHint: "nestjs audit analysis comprehensive module di guard route lifecycle pattern graphql websocket schedule typeorm microservice hook onModuleInit onApplicationBootstrap shutdown dependency graph circular import boundary injection provider constructor inject cycle interceptor pipe filter middleware chain security endpoint api map inventory list all params resolver query mutation subscription apollo gateway subscribemessage socketio realtime event cron interval timeout scheduled job task onevent listener entity relation onetomany manytoone database schema messagepattern eventpattern kafka rabbitmq nats transport request pipeline handler execution flow visualization bull bullmq queue processor process background worker scope transient singleton performance escalation swagger openapi documentation apiproperty apioperation apiresponse contract extract",
+        description: "One-call NestJS architecture audit: modules, DI, guards, routes, lifecycle, patterns, GraphQL, WebSocket, schedule, TypeORM, microservices.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            checks: z.string().optional().describe("Comma-separated checks (default: all). Options: modules,routes,di,guards,lifecycle,patterns,graphql,websocket,schedule,typeorm,microservice"),
+        },
+        handler: async (args) => {
+            const checks = args.checks?.split(",").map((s) => s.trim()).filter(Boolean);
+            return nestAudit(args.repo ?? "", checks ? { checks } : undefined);
+        },
+    },
+    // --- Agent config audit ---
+    {
+        name: "audit_agent_config",
+        category: "meta",
+        searchHint: "audit agent config CLAUDE.md cursorrules stale symbols dead paths token waste redundancy",
+        description: "Scan a config file (CLAUDE.md, .cursorrules) for stale symbol references, dead file paths, token cost, and redundancy. Cross-references against the CodeSift index. Optionally compares two config files for redundant content blocks.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            config_path: z.string().optional().describe("Path to config file (default: CLAUDE.md in repo root)"),
+            compare_with: z.string().optional().describe("Path to second config file for redundancy detection"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.config_path != null)
+                opts.config_path = args.config_path;
+            if (args.compare_with != null)
+                opts.compare_with = args.compare_with;
+            const result = await auditAgentConfig(args.repo, opts);
+            const parts = [`audit_agent_config: ${result.config_path}`, `token_cost: ~${result.token_cost} tokens`];
+            if (result.stale_symbols.length > 0) {
+                parts.push(`\n─── Stale Symbols (${result.stale_symbols.length}) ───`);
+                for (const s of result.stale_symbols)
+                    parts.push(`  line ${s.line}: \`${s.symbol}\` — not found in index`);
+            }
+            if (result.dead_paths.length > 0) {
+                parts.push(`\n─── Dead Paths (${result.dead_paths.length}) ───`);
+                for (const p of result.dead_paths)
+                    parts.push(`  line ${p.line}: ${p.path} — file not in index`);
+            }
+            if (result.redundant_blocks.length > 0) {
+                parts.push(`\n─── Redundant Blocks (${result.redundant_blocks.length}) ───`);
+                for (const b of result.redundant_blocks)
+                    parts.push(`  "${b.text.slice(0, 60)}..." found in: ${b.found_in.join(", ")}`);
+            }
+            if (result.findings.length > 0) {
+                parts.push(`\n─── Findings ───`);
+                for (const f of result.findings)
+                    parts.push(`  ${f}`);
+            }
+            if (result.stale_symbols.length === 0 && result.dead_paths.length === 0 && result.redundant_blocks.length === 0) {
+                parts.push("\nAll references valid. No issues found.");
+            }
+            return parts.join("\n");
+        },
+    },
+    // --- Test impact analysis ---
+    {
+        name: "test_impact_analysis",
+        category: "analysis",
+        searchHint: "test impact analysis affected tests changed files CI confidence which tests to run",
+        description: "Determine which tests to run based on changed files. Uses impact analysis, co-change correlation, and naming convention matching. Returns prioritized test list with confidence scores and a suggested test command.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            since: z.string().optional().describe("Git ref to compare from (default: HEAD~1)"),
+            until: z.string().optional().describe("Git ref to compare to (default: HEAD)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.since != null)
+                opts.since = args.since;
+            if (args.until != null)
+                opts.until = args.until;
+            const result = await testImpactAnalysis(args.repo, opts);
+            const parts = [`test_impact: ${result.affected_tests.length} tests affected | ${result.changed_files.length} files changed`];
+            if (result.suggested_command)
+                parts.push(`\nRun: ${result.suggested_command}`);
+            if (result.affected_tests.length > 0) {
+                parts.push("\n─── Affected Tests ───");
+                for (const t of result.affected_tests) {
+                    parts.push(`  ${t.test_file} (confidence: ${t.confidence.toFixed(2)}) — ${t.reasons.join(", ")}`);
+                }
+            }
+            else {
+                parts.push("\nNo affected tests found.");
+            }
+            return parts.join("\n");
+        },
+    },
+    // --- Dependency audit (composite) ---
+    {
+        name: "dependency_audit",
+        category: "analysis",
+        searchHint: "dependency audit npm vulnerabilities CVE licenses outdated freshness lockfile drift supply chain",
+        description: "Composite dependency health check: vulnerabilities (npm/pnpm/yarn audit), licenses (problematic copyleft detection), freshness (outdated count + major gaps), lockfile integrity (drift, duplicates). Runs 4 sub-checks in parallel. Replaces ~40 manual bash calls for D1-D5 audit dimensions.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            workspace_path: z.string().optional().describe("Workspace path (default: index root)"),
+            skip_licenses: zBool().describe("Skip license check (faster, default: false)"),
+            min_severity: z.enum(["low", "moderate", "high", "critical"]).optional().describe("Filter vulnerabilities by minimum severity"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.workspace_path != null)
+                opts.workspace_path = args.workspace_path;
+            if (args.skip_licenses != null)
+                opts.skip_licenses = args.skip_licenses;
+            if (args.min_severity != null)
+                opts.min_severity = args.min_severity;
+            const result = await dependencyAudit(args.repo, opts);
+            const parts = [
+                `dependency_audit: ${result.workspace} (${result.package_manager}) — ${result.duration_ms}ms`,
+                `\n─── Vulnerabilities (${result.vulnerabilities.total}) ───`,
+                `  critical: ${result.vulnerabilities.by_severity.critical} | high: ${result.vulnerabilities.by_severity.high} | moderate: ${result.vulnerabilities.by_severity.moderate} | low: ${result.vulnerabilities.by_severity.low}`,
+            ];
+            for (const v of result.vulnerabilities.findings.slice(0, 10)) {
+                parts.push(`  [${v.severity}] ${v.package}${v.fix_available ? " (fix available)" : ""}`);
+            }
+            parts.push(`\n─── Licenses (${result.licenses.total}) ───`);
+            if (result.licenses.problematic.length > 0) {
+                parts.push(`  ⚠ Problematic: ${result.licenses.problematic.length}`);
+                for (const l of result.licenses.problematic.slice(0, 10))
+                    parts.push(`    ${l.package}: ${l.license}`);
+            }
+            parts.push(`\n─── Freshness (${result.freshness.outdated_count} outdated) ───`);
+            for (const o of result.freshness.major_gaps.slice(0, 10)) {
+                parts.push(`  ${o.package}: ${o.current} → ${o.latest} (${o.major_gap} major)`);
+            }
+            parts.push(`\n─── Lockfile ───`);
+            parts.push(`  present: ${result.lockfile.present} | issues: ${result.lockfile.issues.length}`);
+            for (const i of result.lockfile.issues.slice(0, 5))
+                parts.push(`    ${i.type}: ${i.message}`);
+            if (result.errors.length > 0) {
+                parts.push(`\n─── Sub-check errors (${result.errors.length}) ───`);
+                for (const e of result.errors)
+                    parts.push(`  ${e}`);
+            }
+            return parts.join("\n");
+        },
+    },
+    // --- Migration safety linter (squawk wrapper) ---
+    {
+        name: "migration_lint",
+        category: "analysis",
+        searchHint: "migration lint squawk SQL postgresql safety linter unsafe-migration not-null drop-column alter-column-type concurrently",
+        description: "PostgreSQL migration safety linter via squawk wrapper. Detects 30+ anti-patterns: NOT NULL without default, DROP COLUMN, ALTER COLUMN TYPE, CREATE INDEX without CONCURRENTLY, etc. Requires squawk CLI installed (brew install squawk OR cargo install squawk-cli). Auto-discovers prisma/migrations, migrations/, db/migrate, drizzle/.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            migration_glob: z.string().optional().describe("Custom migration file glob pattern"),
+            excluded_rules: z.union([z.array(z.string()), z.string().transform((s) => s.split(",").map((x) => x.trim()))]).optional().describe("Squawk rules to exclude (comma-sep or array)"),
+            pg_version: z.string().optional().describe("PostgreSQL version for version-aware rules (e.g. '13')"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.migration_glob != null)
+                opts.migration_glob = args.migration_glob;
+            if (args.excluded_rules != null)
+                opts.excluded_rules = args.excluded_rules;
+            if (args.pg_version != null)
+                opts.pg_version = args.pg_version;
+            const result = await migrationLint(args.repo, opts);
+            if (!result.squawk_installed) {
+                return `migration_lint: squawk not installed.\n${result.install_hint}\n${result.files_checked} migration files would be checked.`;
+            }
+            const parts = [
+                `migration_lint: squawk ${result.squawk_version ?? "unknown"} — ${result.files_checked} files checked`,
+                `errors: ${result.by_severity.error} | warnings: ${result.by_severity.warning}`,
+            ];
+            if (result.findings.length > 0) {
+                parts.push("\n─── Findings ───");
+                for (const f of result.findings.slice(0, 30)) {
+                    parts.push(`  [${f.level}] ${f.file}:${f.line} ${f.rule} — ${f.message}`);
+                }
+            }
+            else {
+                parts.push("\nNo issues found.");
+            }
+            return parts.join("\n");
+        },
+    },
+    // --- Prisma schema analyzer ---
+    {
+        name: "analyze_prisma_schema",
+        category: "analysis",
+        searchHint: "prisma schema analyze ast model field index foreign-key relation soft-delete enum coverage",
+        description: "Parse schema.prisma into structured AST. Returns model coverage: fields, indexes, FKs, relations, soft-delete detection, FK index coverage %, unindexed FKs (audit warning), status-as-String suggestions. Uses @mrleebo/prisma-ast for proper AST parsing (vs regex-only extractor).",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            schema_path: z.string().optional().describe("Path to schema.prisma (default: auto-detected)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.schema_path != null)
+                opts.schema_path = args.schema_path;
+            const result = await analyzePrismaSchema(args.repo, opts);
+            const parts = [
+                `analyze_prisma_schema: ${result.schema_path}`,
+                `models: ${result.model_count} | enums: ${result.enum_count}`,
+                `\n─── FK Index Coverage ───`,
+                `  ${result.totals.fk_with_index}/${result.totals.fk_columns} FKs indexed (${result.totals.fk_index_coverage_pct.toFixed(1)}%)`,
+                `  unindexed FKs: ${result.totals.fk_without_index}`,
+                `  soft-delete models: ${result.totals.soft_delete_models}`,
+                `  composite indexes: ${result.totals.composite_indexes} | single indexes: ${result.totals.single_indexes}`,
+            ];
+            if (result.warnings.length > 0) {
+                parts.push(`\n─── Warnings (${result.warnings.length}) ───`);
+                for (const w of result.warnings.slice(0, 20))
+                    parts.push(`  ⚠ ${w}`);
+            }
+            // List models with audit issues
+            const auditModels = result.models.filter((m) => m.fk_columns_without_index.length > 0 || m.status_like_string_fields.length > 0);
+            if (auditModels.length > 0) {
+                parts.push(`\n─── Models with issues (${auditModels.length}) ───`);
+                for (const m of auditModels.slice(0, 15)) {
+                    const issues = [];
+                    if (m.fk_columns_without_index.length > 0)
+                        issues.push(`unindexed FKs: ${m.fk_columns_without_index.join(",")}`);
+                    if (m.status_like_string_fields.length > 0)
+                        issues.push(`status-as-String: ${m.status_like_string_fields.join(",")}`);
+                    parts.push(`  ${m.name} — ${issues.join(" | ")}`);
+                }
+            }
+            return parts.join("\n");
+        },
+    },
+    // --- Astro tools ---
+    {
+        name: "astro_analyze_islands",
+        category: "analysis",
+        searchHint: "astro islands client hydration directives framework",
+        description: "Analyze Astro islands (client:* directives) in a repo. Finds all interactive components with hydration directives, lists server islands with fallback status, and optionally generates optimization recommendations.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            path_prefix: z.string().optional().describe("Only scan files under this path prefix"),
+            include_recommendations: z.boolean().default(true).describe("Include optimization recommendations (default: true)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.repo != null)
+                opts.repo = args.repo;
+            if (args.path_prefix != null)
+                opts.path_prefix = args.path_prefix;
+            if (args.include_recommendations != null)
+                opts.include_recommendations = args.include_recommendations;
+            return await astroAnalyzeIslands(opts);
+        },
+    },
+    {
+        name: "astro_hydration_audit",
+        category: "analysis",
+        searchHint: "astro hydration audit anti-patterns client load",
+        description: "Audit Astro hydration usage for anti-patterns such as client:load on heavy components, missing client directives, or suboptimal hydration strategies. Returns issues grouped by severity with a letter grade.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            severity: z.enum(["all", "warnings", "errors"]).default("all").describe("Filter issues by severity (default: all)"),
+            path_prefix: z.string().optional().describe("Only scan files under this path prefix"),
+            fail_on: z.enum(["error", "warning", "info"]).optional().describe("Set exit_code gate: 'error' exits 1 on any errors; 'warning' exits 2 on warnings; 'info' exits 2 on info or warnings"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.repo != null)
+                opts.repo = args.repo;
+            if (args.severity != null)
+                opts.severity = args.severity;
+            if (args.path_prefix != null)
+                opts.path_prefix = args.path_prefix;
+            if (args.fail_on != null)
+                opts.fail_on = args.fail_on;
+            return await astroHydrationAudit(opts);
+        },
+    },
+    {
+        name: "astro_route_map",
+        category: "navigation",
+        searchHint: "astro routes pages endpoints file-based routing",
+        description: "Map all Astro routes (pages + API endpoints) discovered from the file-based routing structure. Returns routes with type, dynamic params, and handler symbols. Supports json/tree/table output formats.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            include_endpoints: z.boolean().default(true).describe("Include API endpoint routes (default: true)"),
+            output_format: z.enum(["json", "tree", "table"]).default("json").describe("Output format: json | tree | table (default: json)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.repo != null)
+                opts.repo = args.repo;
+            if (args.include_endpoints != null)
+                opts.include_endpoints = args.include_endpoints;
+            if (args.output_format != null)
+                opts.output_format = args.output_format;
+            return await astroRouteMap(opts);
+        },
+    },
+    {
+        name: "astro_config_analyze",
+        category: "analysis",
+        searchHint: "astro config integrations adapter output mode",
+        description: "Analyze an Astro project's configuration file (astro.config.mjs/ts/js). Extracts output mode (static/server/hybrid), adapter, integrations, site URL, and base path. Identifies dynamic/unresolved config.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+        },
+        handler: async (args) => {
+            const index = await getCodeIndex(args.repo ?? "");
+            if (!index)
+                throw new Error("Repository not found — run index_folder first");
+            return await astroConfigAnalyze({ project_root: index.root });
+        },
+    },
+    {
+        name: "astro_actions_audit",
+        category: "analysis",
+        searchHint: "astro actions defineAction zod refine passthrough multipart file enctype audit",
+        description: "Audit Astro Actions (src/actions/index.ts) for 6 known anti-patterns (AA01-AA06): missing handler return, top-level .refine() (Astro issue #11641), .passthrough() usage (issue #11693), File schema without multipart form, server-side invocation via actions.xxx(), and client calls to unknown actions. Returns issues grouped by severity with an A/B/C/D score.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            severity: z.enum(["all", "warnings", "errors"]).default("all").describe("Filter issues by severity (default: all)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.repo != null)
+                opts.repo = args.repo;
+            if (args.severity != null)
+                opts.severity = args.severity;
+            return await astroActionsAudit(opts);
+        },
+    },
+    {
+        name: "astro_content_collections",
+        category: "analysis",
+        searchHint: "astro content collections defineCollection zod schema reference glob loader frontmatter",
+        description: "Parse an Astro content collections config (src/content.config.ts or legacy src/content/config.ts), extract each collection's loader + Zod schema fields, build a reference() graph, and optionally validate entry frontmatter against required fields.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            validate_entries: z.boolean().default(true).describe("Validate entry frontmatter against required schema fields (default: true)"),
+        },
+        handler: async (args) => {
+            const index = await getCodeIndex(args.repo ?? "");
+            if (!index)
+                throw new Error("Repository not found — run index_folder first");
+            const opts = { project_root: index.root };
+            if (args.validate_entries != null)
+                opts.validate_entries = args.validate_entries;
+            return await astroContentCollections(opts);
+        },
+    },
+    {
+        name: "astro_audit",
+        category: "analysis",
+        searchHint: "astro meta audit full health check score gates recommendations islands hydration routes config actions content migration patterns",
+        description: "One-call Astro project health check: runs all 7 Astro tools + 13 Astro patterns in parallel, returns unified {score, gates, sections, recommendations}. Mirrors react_quickstart pattern.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            skip: z.array(z.string()).optional().describe("Sections to skip: config, hydration, routes, actions, content, migration, patterns"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.repo != null)
+                opts.repo = args.repo;
+            if (args.skip != null)
+                opts.skip = args.skip;
+            return await astroAudit(opts);
+        },
+    },
+    // --- Hono framework tools (Task 23) ---
+    {
+        name: "trace_middleware_chain",
+        category: "graph",
+        searchHint: "hono middleware chain trace order scope auth use conditional applied_when if method header path basicAuth gated",
+        description: "Hono middleware introspection. Three query modes: (1) route mode — pass path (+optional method) to get the chain effective for that route; (2) scope mode — pass scope literal (e.g. '/posts/*') to get that specific app.use chain; (3) app-wide mode — omit path and scope to get every chain flattened. Any mode supports only_conditional=true to filter to entries with applied_when populated, so the blog-API pattern (basicAuth wrapped in `if (method !== 'GET')`) is surfaced as gated rather than missed. Absorbs the former trace_conditional_middleware tool.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            path: z.string().optional().describe("Route path to look up (e.g. '/api/users/:id'). Omit for scope or app-wide query."),
+            method: z.string().optional().describe("HTTP method filter (GET, POST, etc.). Only used in route mode."),
+            scope: z.string().optional().describe("Exact middleware scope literal (e.g. '/posts/*'). Mutually exclusive with path."),
+            only_conditional: z.boolean().optional().describe("Filter entries to those whose applied_when field is populated (conditional middleware)."),
+        },
+        handler: async (args) => {
+            const { traceMiddlewareChain } = await import("./tools/hono-middleware-chain.js");
+            const opts = {};
+            if (args.scope !== undefined)
+                opts.scope = args.scope;
+            if (args.only_conditional !== undefined)
+                opts.only_conditional = args.only_conditional;
+            return await traceMiddlewareChain(args.repo, args.path, args.method, Object.keys(opts).length > 0 ? opts : undefined);
+        },
+    },
+    {
+        name: "analyze_hono_app",
+        category: "analysis",
+        searchHint: "hono overview analyze app routes middleware runtime env bindings rpc",
+        description: "Complete Hono application overview: routes grouped by method/scope, middleware map, context vars, OpenAPI status, RPC exports (flags Issue #3869 slow pattern), runtime, env bindings. One call for full project analysis.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            entry_file: z.string().optional().describe("Hono entry file (auto-detected if omitted)"),
+            force_refresh: z.boolean().optional().describe("Clear cache and rebuild"),
+        },
+        handler: async (args) => {
+            const { analyzeHonoApp } = await import("./tools/hono-analyze-app.js");
+            return await analyzeHonoApp(args.repo, args.entry_file, args.force_refresh);
+        },
+    },
+    {
+        name: "trace_context_flow",
+        category: "analysis",
+        searchHint: "hono context flow c.set c.get c.var c.env middleware variable unguarded",
+        description: "Trace Hono context variable flow (c.set/c.get/c.var/c.env). Detects MISSING_CONTEXT_VARIABLE findings where routes access variables that no middleware in their scope sets.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            variable: z.string().optional().describe("Specific variable name to trace (default: all)"),
+        },
+        handler: async (args) => {
+            const { traceContextFlow } = await import("./tools/hono-context-flow.js");
+            return await traceContextFlow(args.repo, args.variable);
+        },
+    },
+    {
+        name: "extract_api_contract",
+        category: "analysis",
+        searchHint: "hono openapi contract api schema createRoute zValidator",
+        description: "Extract OpenAPI-style API contract from a Hono app. Uses explicit createRoute() definitions when available, infers from regular routes otherwise. Format: 'openapi' (paths object) or 'summary' (table).",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            entry_file: z.string().optional().describe("Hono entry file (auto-detected if omitted)"),
+            format: z.enum(["openapi", "summary"]).optional().describe("Output format (default: openapi)"),
+        },
+        handler: async (args) => {
+            const { extractApiContract } = await import("./tools/hono-api-contract.js");
+            return await extractApiContract(args.repo, args.entry_file, args.format);
+        },
+    },
+    {
+        name: "trace_rpc_types",
+        category: "analysis",
+        searchHint: "hono rpc client type export typeof slow pattern Issue 3869 compile time",
+        description: "Analyze Hono RPC type exports. Detects the slow `export type X = typeof app` pattern from Issue #3869 (8-min CI compile time) and recommends splitting into per-route-group types.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+        },
+        handler: async (args) => {
+            const { traceRpcTypes } = await import("./tools/hono-rpc-types.js");
+            return await traceRpcTypes(args.repo);
+        },
+    },
+    {
+        name: "audit_hono_security",
+        category: "security",
+        searchHint: "hono security audit rate limit secure headers auth order csrf env regression createMiddleware BlankEnv Issue 3587",
+        description: "Security + type-safety audit of a Hono app. Rules: missing-secure-headers (global), missing-rate-limit + missing-auth (mutation routes, conditional-middleware aware via applied_when), auth-ordering (auth after non-auth in chain), env-regression (plain createMiddleware in 3+ chains — Hono Issue #3587, absorbed from the former detect_middleware_env_regression tool). Returns prioritized findings plus heuristic disclaimers via `notes` field for best-effort rules.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+        },
+        handler: async (args) => {
+            const { auditHonoSecurity } = await import("./tools/hono-security.js");
+            return await auditHonoSecurity(args.repo);
+        },
+    },
+    {
+        name: "visualize_hono_routes",
+        category: "reporting",
+        searchHint: "hono routes visualize mermaid tree diagram documentation",
+        description: "Produce a visualization of Hono routing topology. Supports 'mermaid' (diagram) and 'tree' (ASCII) formats.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            format: z.enum(["mermaid", "tree"]).optional().describe("Output format (default: tree)"),
+        },
+        handler: async (args) => {
+            const { visualizeHonoRoutes } = await import("./tools/hono-visualize.js");
+            return await visualizeHonoRoutes(args.repo, args.format);
+        },
+    },
+    // --- Hono Phase 2 tools (T13) ---
+    {
+        name: "analyze_inline_handler",
+        category: "analysis",
+        searchHint: "hono inline handler analyze c.json c.text status response error db fetch context",
+        description: "Structured body analysis for each Hono inline handler: responses (c.json/text/html/redirect/newResponse with status + shape_hint), errors (throw new HTTPException/Error), db calls (prisma/db/knex/drizzle/mongoose/supabase), fetch calls, c.set/get/var/env access, inline validators, has_try_catch. Optional method + path filter. Named-handler routes return empty.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            method: z.string().optional().describe("HTTP method filter (case-insensitive)"),
+            path: z.string().optional().describe("Route path filter (exact match, e.g. '/users/:id')"),
+        },
+        handler: async (args) => {
+            const { analyzeInlineHandler } = await import("./tools/hono-inline-analyze.js");
+            return await analyzeInlineHandler(args.repo, args.method, args.path);
+        },
+    },
+    {
+        name: "extract_response_types",
+        category: "analysis",
+        searchHint: "hono response types status codes error paths RPC client InferResponseType Issue 4270",
+        description: "Aggregate statically-knowable response types per route: c.json/text/html/body/redirect/newResponse emissions + throw new HTTPException/Error entries with status codes. Closes Hono Issue #4270 — RPC clients can generate types that include error paths. Returns routes[] plus total_statuses across the app.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+        },
+        handler: async (args) => {
+            const { extractResponseTypes } = await import("./tools/hono-response-types.js");
+            return await extractResponseTypes(args.repo);
+        },
+    },
+    {
+        name: "detect_hono_modules",
+        category: "analysis",
+        searchHint: "hono modules architecture cluster path prefix middleware bindings enterprise Issue 4121",
+        description: "Cluster Hono routes into logical modules by 2-segment path prefix, rolling up middleware chains, env bindings (from inline_analysis context_access), and source files per module. Closes Hono Issue #4121 — surfaces the implicit module structure for architecture review of enterprise apps. No new AST walking; post-processes the existing HonoAppModel.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+        },
+        handler: async (args) => {
+            const { detectHonoModules } = await import("./tools/hono-modules.js");
+            return await detectHonoModules(args.repo);
+        },
+    },
+    {
+        name: "find_dead_hono_routes",
+        category: "analysis",
+        searchHint: "hono dead routes unused RPC client caller refactor monorepo cleanup",
+        description: "Heuristically flag Hono server routes whose path segments do not appear in any non-server .ts/.tsx/.js/.jsx source file in the repo. Useful in monorepos to identify server endpoints that no Hono RPC client calls after refactors. Fully-dynamic routes (`/:id` only) are skipped. Documented as best-effort via the result note field.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+        },
+        handler: async (args) => {
+            const { findDeadHonoRoutes } = await import("./tools/hono-dead-routes.js");
+            return await findDeadHonoRoutes(args.repo);
+        },
+    },
+    // --- Next.js framework tools ---
+    {
+        name: "nextjs_route_map",
+        category: "analysis",
+        searchHint: "nextjs next.js route map app router pages router rendering strategy SSG SSR ISR edge middleware",
+        description: "Complete Next.js route map with rendering strategy per route. Enumerates App Router and Pages Router conventions, reads route segment config exports (dynamic/revalidate/runtime), classifies each route as static/ssr/isr/edge/client, detects metadata exports, computes layout chain, and flags hybrid conflicts where the same URL is served by both routers.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            workspace: z.string().optional().describe("Monorepo workspace path, e.g. 'apps/web'"),
+            router: z.enum(["app", "pages", "both"]).optional().describe("Which routers to scan (default 'both')"),
+            include_metadata: z.boolean().optional().describe("Include metadata export detection (default true)"),
+            max_routes: z.number().int().positive().optional().describe("Max routes to process (default 1000)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.workspace != null)
+                opts.workspace = args.workspace;
+            if (args.router != null)
+                opts.router = args.router;
+            if (args.include_metadata != null)
+                opts.include_metadata = args.include_metadata;
+            if (args.max_routes != null)
+                opts.max_routes = args.max_routes;
+            const result = await nextjsRouteMap(args.repo ?? "", opts);
+            return formatNextjsRouteMap(result);
+        },
+    },
+    {
+        name: "nextjs_metadata_audit",
+        category: "analysis",
+        searchHint: "nextjs seo metadata title description og image audit canonical twitter json-ld",
+        description: "Audit Next.js page metadata for SEO completeness with per-route scoring. Walks app/page.tsx files, extracts title/description/openGraph/canonical/twitter/JSON-LD via tree-sitter, scores each route 0-100 with a weighted formula, and aggregates a per-grade distribution + top issue list.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            workspace: z.string().optional().describe("Monorepo workspace path, e.g. 'apps/web'"),
+            max_routes: z.number().int().positive().optional().describe("Max routes to process (default 1000)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.workspace != null)
+                opts.workspace = args.workspace;
+            if (args.max_routes != null)
+                opts.max_routes = args.max_routes;
+            const result = await nextjsMetadataAudit(args.repo ?? "", opts);
+            return formatNextjsMetadataAudit(result);
+        },
+    },
+    {
+        name: "framework_audit",
+        category: "analysis",
+        searchHint: "nextjs next.js framework audit meta-tool overall score security metadata routes components classifier use client use server hooks server actions auth validation rate limit zod api contract route handler openapi method body schema response client boundary bundle imports loc link integrity broken navigation href router push 404 data flow fetch waterfall cache cookies headers ssr revalidate middleware coverage protected admin matcher",
+        description: "Run all Next.js sub-audits (components, routes, metadata, security, api_contract, boundary, links, data_flow, middleware_coverage) and aggregate into a unified weighted overall score with grade. Use as a single first-call for any Next.js project.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            workspace: z.string().optional().describe("Monorepo workspace path, e.g. 'apps/web'"),
+            tools: z.array(z.string()).optional().describe("Subset of tools to run (default: all 9). Names: components, routes, metadata, security, api_contract, boundary, links, data_flow, middleware_coverage"),
+            mode: z.enum(["full", "priority"]).optional().describe("Output mode: 'full' returns per-tool results + aggregated summary; 'priority' returns a single unified top-N actionable findings list sorted by severity × cross-tool occurrences"),
+            priority_limit: z.number().int().positive().optional().describe("Max findings in priority mode (default: 20)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.workspace != null)
+                opts.workspace = args.workspace;
+            if (args.tools != null)
+                opts.tools = args.tools;
+            if (args.mode != null)
+                opts.mode = args.mode;
+            if (args.priority_limit != null)
+                opts.priority_limit = args.priority_limit;
+            const result = await frameworkAudit(args.repo ?? "", opts);
+            return formatFrameworkAudit(result);
+        },
+    },
+    // ── SQL analysis tools (hidden/discoverable) ─────────────
+    {
+        name: "analyze_schema",
+        category: "analysis",
+        searchHint: "SQL schema ERD entity relationship tables views columns foreign key database migration",
+        description: "Analyze SQL schema: tables, views, columns, foreign keys, relationships. Output as JSON or Mermaid ERD.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Filter SQL files by pattern (e.g. 'migrations/')"),
+            output_format: z.enum(["json", "mermaid"]).optional().describe("Output format (default: json)"),
+            include_columns: zBool().describe("Include column details in output (default: true)"),
+        },
+        handler: async (args) => {
+            const { analyzeSchema } = await import("./tools/sql-tools.js");
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.output_format != null)
+                opts.output_format = args.output_format;
+            if (args.include_columns != null)
+                opts.include_columns = args.include_columns;
+            const result = await analyzeSchema(args.repo, opts);
+            const parts = [];
+            parts.push(`Tables: ${result.tables.length} | Views: ${result.views.length} | Relationships: ${result.relationships.length}`);
+            if (result.warnings.length > 0)
+                parts.push(`Warnings: ${result.warnings.join("; ")}`);
+            if (result.mermaid) {
+                parts.push("");
+                parts.push(result.mermaid);
+            }
+            else {
+                for (const t of result.tables) {
+                    const cols = t.columns.map((c) => `${c.name} ${c.type}`).join(", ");
+                    parts.push(`  ${t.name} (${t.file}:${t.line}) — ${cols || "(no columns)"}`);
+                }
+                for (const v of result.views) {
+                    parts.push(`  VIEW ${v.name} (${v.file}:${v.line})`);
+                }
+                if (result.relationships.length > 0) {
+                    parts.push("Relationships:");
+                    for (const r of result.relationships) {
+                        parts.push(`  ${r.from_table}.${r.from_column} → ${r.to_table}.${r.to_column} [${r.type}]`);
+                    }
+                }
+            }
+            return parts.join("\n");
+        },
+    },
+    {
+        name: "trace_query",
+        category: "analysis",
+        searchHint: "SQL table query trace references cross-language ORM Prisma Drizzle migration",
+        description: "Trace SQL table references across the codebase: DDL, DML, FK, and ORM models (Prisma, Drizzle).",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            table: z.string().describe("Table name to trace (required)"),
+            include_orm: zBool().describe("Check Prisma/Drizzle ORM models (default: true)"),
+            file_pattern: z.string().optional().describe("Scope search to files matching pattern"),
+            max_references: zNum().describe("Maximum references to return (default: 500)"),
+        },
+        handler: async (args) => {
+            const { traceQuery } = await import("./tools/sql-tools.js");
+            const opts = {
+                table: args.table,
             };
-            if (args.since != null)
-                opts.since = args.since;
-            if (args.until != null)
-                opts.until = args.until;
-            if (checksArr != null)
-                opts.checks = checksArr.join(",");
-            if (excludeArr != null)
-                opts.exclude_patterns = excludeArr;
-            if (args.token_budget != null)
-                opts.token_budget = args.token_budget;
-            if (args.max_files != null)
-                opts.max_files = args.max_files;
-            if (args.check_timeout_ms != null)
-                opts.check_timeout_ms = args.check_timeout_ms;
-            const result = await reviewDiff(args.repo, opts);
-            return formatReviewDiff(result);
+            if (args.include_orm != null)
+                opts.include_orm = args.include_orm;
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.max_references != null)
+                opts.max_references = args.max_references;
+            const result = await traceQuery(args.repo, opts);
+            const parts = [];
+            if (result.table_definition) {
+                parts.push(`Definition: ${result.table_definition.file}:${result.table_definition.line} [${result.table_definition.kind}]`);
+            }
+            else {
+                parts.push(`Definition: not found in index`);
+            }
+            parts.push(`SQL references: ${result.sql_references.length}${result.truncated ? " (truncated)" : ""}`);
+            for (const ref of result.sql_references.slice(0, 50)) {
+                parts.push(`  ${ref.file}:${ref.line} [${ref.type}] ${ref.context}`);
+            }
+            if (result.orm_references.length > 0) {
+                parts.push(`ORM references: ${result.orm_references.length}`);
+                for (const ref of result.orm_references) {
+                    parts.push(`  ${ref.file}:${ref.line} [${ref.orm}] model ${ref.model_name}`);
+                }
+            }
+            if (result.warnings.length > 0) {
+                parts.push(`Warnings: ${result.warnings.join("; ")}`);
+            }
+            return parts.join("\n");
         },
     },
-    // --- Stats ---
     {
-        name: "usage_stats",
-        category: "meta",
-        searchHint: "usage statistics tool calls tokens timing metrics",
-        outputSchema: OutputSchemas.usageStats,
-        description: "Show usage statistics for all CodeSift tool calls (call counts, tokens, timing, repos)",
-        schema: {},
-        handler: async () => {
-            const stats = await getUsageStats();
-            return { report: formatUsageReport(stats) };
+        name: "sql_audit",
+        category: "analysis",
+        searchHint: "SQL audit composite drift orphan lint DML safety complexity god table schema diagnostic",
+        description: "Composite SQL audit — runs 5 diagnostic gates (drift, orphan, lint, dml, complexity) in one call. Use this instead of calling the individual gate functions separately.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            checks: z.array(z.enum(["drift", "orphan", "lint", "dml", "complexity"])).optional().describe("Subset of gates to run (default: all 5)"),
+            file_pattern: z.string().optional().describe("Scope to files matching pattern"),
+            max_results: zNum().describe("Max DML findings per pattern (default: 200)"),
+        },
+        handler: async (args) => {
+            const { sqlAudit } = await import("./tools/sql-tools.js");
+            const opts = {};
+            if (args.checks != null)
+                opts.checks = args.checks;
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.max_results != null)
+                opts.max_results = args.max_results;
+            const result = await sqlAudit(args.repo, opts);
+            const parts = [];
+            parts.push(`SQL audit: ${result.summary.gates_run} gates run, ${result.summary.gates_passed} passed, ${result.summary.gates_failed} failed`);
+            parts.push(`  Total findings:    ${result.summary.total_findings}`);
+            parts.push(`  Critical findings: ${result.summary.critical_findings}`);
+            parts.push("");
+            for (const g of result.gates) {
+                const icon = g.pass ? "✓" : (g.critical ? "✗ CRITICAL" : "⚠");
+                parts.push(`${icon} ${g.check}: ${g.summary}`);
+            }
+            if (result.warnings.length > 0) {
+                parts.push("");
+                parts.push("─── Warnings ───");
+                for (const w of result.warnings)
+                    parts.push(`  ⚠ ${w}`);
+            }
+            return parts.join("\n");
         },
     },
-    // ── Session context tools ───────────────────────────────────────────────
     {
-        name: "get_session_snapshot",
-        category: "session",
-        searchHint: "session context snapshot compaction summary explored symbols files queries",
-        description: "Get a compact ~200 token snapshot of what was explored in this session. Designed to survive context compaction. Call proactively before long tasks.",
+        name: "diff_migrations",
+        category: "analysis",
+        searchHint: "migration diff SQL destructive DROP ALTER ADD schema change deploy risk",
+        description: "Scan SQL migration files and classify operations as additive (CREATE TABLE), modifying (ALTER ADD), or destructive (DROP TABLE, DROP COLUMN, TRUNCATE). Flags deploy risks.",
         schema: {
-            repo: z.string().optional().describe("Filter to specific repo. Default: most recent repo."),
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            file_pattern: z.string().optional().describe("Scope to migration files matching pattern"),
         },
         handler: async (args) => {
-            return formatSnapshot(getSessionState(), args.repo);
+            const { diffMigrations } = await import("./tools/sql-tools.js");
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            const result = await diffMigrations(args.repo, opts);
+            const parts = [];
+            parts.push(`Migration ops: ${result.summary.additive + result.summary.modifying + result.summary.destructive} across ${result.summary.total_files} files`);
+            parts.push(`  additive:    ${result.summary.additive}`);
+            parts.push(`  modifying:   ${result.summary.modifying}`);
+            parts.push(`  destructive: ${result.summary.destructive}`);
+            if (result.destructive.length > 0) {
+                parts.push("\n⚠ DESTRUCTIVE:");
+                for (const d of result.destructive) {
+                    parts.push(`  [${d.severity.toUpperCase()}] ${d.operation} ${d.target}  (${d.file}:${d.line})`);
+                }
+            }
+            if (result.modifying.length > 0) {
+                parts.push("\nModifying:");
+                for (const m of result.modifying.slice(0, 20)) {
+                    parts.push(`  ${m.operation} ${m.target}  (${m.file}:${m.line})`);
+                }
+            }
+            return parts.join("\n");
         },
     },
     {
-        name: "get_session_context",
-        category: "session",
-        searchHint: "session context full explored symbols files queries negative evidence",
-        description: "Get full session context: explored symbols, files, queries, and negative evidence (searched but not found). Use get_session_snapshot for a compact version.",
+        name: "search_columns",
+        category: "search",
+        searchHint: "search column SQL table field name type database schema find",
+        description: "Search SQL columns across all tables by name (substring), type (int/string/float/...), or parent table. Returns column name, type, table, file, and line. Like search_symbols but scoped to SQL fields.",
         schema: {
-            repo: z.string().optional().describe("Filter to specific repo"),
-            include_stale: zBool().describe("Include stale negative evidence entries (default: false)"),
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            query: z.string().describe("Column name substring to match (case-insensitive). Empty = no name filter."),
+            type: z.string().optional().describe("Filter by normalized type: int, string, float, bool, datetime, json, uuid, bytes"),
+            table: z.string().optional().describe("Filter by table name substring"),
+            file_pattern: z.string().optional().describe("Scope to files matching pattern"),
+            max_results: zNum().describe("Max columns to return (default: 100)"),
         },
         handler: async (args) => {
-            const includeStale = args.include_stale === true || args.include_stale === "true";
-            return getContext(args.repo, includeStale);
+            const { searchColumns } = await import("./tools/sql-tools.js");
+            const opts = {
+                query: args.query ?? "",
+            };
+            if (args.type != null)
+                opts.type = args.type;
+            if (args.table != null)
+                opts.table = args.table;
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.max_results != null)
+                opts.max_results = args.max_results;
+            const result = await searchColumns(args.repo, opts);
+            const parts = [];
+            parts.push(`Columns: ${result.columns.length}${result.truncated ? `/${result.total} (truncated)` : ""}`);
+            for (const c of result.columns) {
+                parts.push(`  ${c.table}.${c.name.padEnd(24)} ${c.normalized_type.padEnd(10)} ${c.file}:${c.line}`);
+            }
+            return parts.join("\n");
         },
     },
-    // --- Project Analysis ---
+    // --- Astro v6 migration check ---
     {
-        name: "analyze_project",
+        name: "astro_migration_check",
         category: "analysis",
-        searchHint: "project profile stack conventions middleware routes rate-limits auth detection",
-        description: "Analyze a repository to extract stack, file classifications, and framework-specific conventions. Returns a structured project profile (schema v1.0) with file:line evidence for convention-level facts.",
+        searchHint: "astro v6 migration upgrade breaking changes compatibility check AM01 AM10 content collections ViewTransitions",
+        description: "Scan an Astro project for v5→v6 breaking changes. Detects 10 issues (AM01–AM10): removed APIs (Astro.glob, emitESMImage), component renames (ViewTransitions→ClientRouter), content collection config changes, Node.js version requirements, Zod 4 deprecations, hybrid output mode, and removed integrations (@astrojs/lit). Returns a migration report with per-issue effort estimates.",
         schema: {
             repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
-            force: zBool().describe("Ignore cached results and re-analyze"),
+            target_version: z.enum(["6"]).optional().describe("Target Astro version (default: '6')"),
         },
         handler: async (args) => {
-            const result = await analyzeProject(args.repo, {
-                force: args.force,
-            });
-            return result;
+            const mcArgs = {};
+            if (args.repo != null)
+                mcArgs.repo = args.repo;
+            if (args.target_version != null)
+                mcArgs.target_version = args.target_version;
+            const result = await astroMigrationCheck(mcArgs);
+            const lines = [];
+            lines.push(`ASTRO MIGRATION CHECK: v${result.current_version ?? "unknown"} → v${result.target_version}`);
+            lines.push(`Issues: ${result.summary.total_issues} | Estimated: ${result.summary.estimated_migration_hours}`);
+            if (Object.keys(result.summary.by_effort).length > 0) {
+                const effortStr = Object.entries(result.summary.by_effort)
+                    .map(([k, v]) => `${v}×${k}`)
+                    .join(", ");
+                lines.push(`Effort: ${effortStr}`);
+            }
+            if (result.breaking_changes.length === 0) {
+                lines.push("\n✓ No v6 breaking changes detected.");
+            }
+            else {
+                lines.push("");
+                for (const issue of result.breaking_changes) {
+                    const sev = issue.severity === "error" ? "✗" : issue.severity === "warning" ? "⚠" : "ℹ";
+                    lines.push(`${sev} ${issue.code} [${issue.category}] — ${issue.message}`);
+                    lines.push(`  effort: ${issue.effort} | files: ${issue.files.slice(0, 3).join(", ")}${issue.files.length > 3 ? ` +${issue.files.length - 3} more` : ""}`);
+                    if (issue.migration_guide)
+                        lines.push(`  guide: ${issue.migration_guide}`);
+                }
+            }
+            return lines.join("\n");
         },
     },
+    // --- Discovery / concierge ---
     {
-        name: "get_extractor_versions",
-        category: "meta",
-        searchHint: "extractor version cache invalidation profile",
-        description: "Return current extractor versions without triggering analysis. Used for cache invalidation.",
-        schema: {},
-        handler: async () => getExtractorVersions(),
+        name: "plan_turn",
+        category: "discovery",
+        searchHint: "plan turn routing recommend tools symbols files gap analysis session aware concierge",
+        description: "Routes a natural-language query to the most relevant CodeSift tools, symbols, and files. Uses hybrid BM25+semantic ranking with session-aware dedup. Call at the start of a task to get a prioritized action list.",
+        schema: {
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            query: z.string().describe("Natural-language description of what you want to do"),
+            max_results: z.number().optional().describe("Max tools to return (default 10)"),
+            skip_session: z.boolean().optional().describe("Skip session state checks (default false)"),
+        },
+        handler: async (args) => {
+            const { query, max_results, skip_session } = args;
+            const opts = {};
+            if (max_results !== undefined)
+                opts.max_results = max_results;
+            if (skip_session !== undefined)
+                opts.skip_session = skip_session;
+            const result = await planTurn(args.repo, query, opts);
+            return formatPlanTurnResult(result);
+        },
     },
 ];
 function buildToolSummaries() {
@@ -1465,6 +3666,21 @@ export function discoverTools(query, category) {
 // ---------------------------------------------------------------------------
 export function registerTools(server, options) {
     const deferNonCore = options?.deferNonCore ?? false;
+    const projectRoot = options?.projectRoot ?? process.cwd();
+    // Detect which languages the project actually uses — drives language-gated
+    // tool registration. Tools with requiresLanguage="python" are only surfaced
+    // when .py files exist, same for PHP and Kotlin.
+    let languages;
+    try {
+        languages = detectProjectLanguagesSync(projectRoot);
+    }
+    catch {
+        // On failure, enable everything — conservative fallback
+        languages = {
+            python: true, php: true, typescript: true, javascript: true,
+            kotlin: true, go: true, rust: true, ruby: true,
+        };
+    }
     // Clear handles from any previous registration (e.g. tests calling registerTools multiple times)
     toolHandles.clear();
     // Register ALL tools with full schema; store returned handles
@@ -1472,6 +3688,18 @@ export function registerTools(server, options) {
         const handle = server.tool(tool.name, tool.description, tool.schema, async (args) => wrapTool(tool.name, args, () => tool.handler(args))());
         toolHandles.set(tool.name, handle);
     }
+    // Language-gated disabling — tools requiring a language absent from the
+    // project are disabled (still registered but hidden from ListTools).
+    // Users can re-enable via describe_tools(reveal=true) if needed.
+    for (const tool of TOOL_DEFINITIONS) {
+        if (!tool.requiresLanguage)
+            continue;
+        if (languages[tool.requiresLanguage])
+            continue;
+        const handle = toolHandles.get(tool.name);
+        if (handle)
+            handle.disable();
+    }
     // Always register discover_tools meta-tool
     const discoverHandle = server.tool("discover_tools", "Search tool catalog by keyword or category. Returns matching tools with descriptions.", {
         query: z.string().describe("Keywords to search for (e.g. 'dead code', 'complexity', 'rename', 'secrets')"),
@@ -1504,14 +3732,34 @@ export function registerTools(server, options) {
                 handle.disable();
             }
         }
+        // Auto-enable framework-specific tools when project type is detected at CWD.
+        // E.g. composer.json → enable PHP/Yii2 tools automatically.
+        detectAutoLoadTools(process.cwd())
+            .then((toEnable) => {
+            for (const name of toEnable) {
+                const h = toolHandles.get(name);
+                if (h)
+                    h.enable();
+            }
+            if (toEnable.length > 0) {
+                console.error(`[codesift] Auto-loaded ${toEnable.length} framework tools for detected project type: ${toEnable.join(", ")}`);
+            }
+        })
+            .catch(() => {
+            // Silently ignore — auto-detection is best-effort
+        });
     }
     // Register progressive shorteners for analysis tools with large outputs
     registerShortener("analyze_complexity", { compact: formatComplexityCompact, counts: formatComplexityCounts });
     registerShortener("find_clones", { compact: formatClonesCompact, counts: formatClonesCounts });
     registerShortener("analyze_hotspots", { compact: formatHotspotsCompact, counts: formatHotspotsCounts });
     registerShortener("trace_route", { compact: formatTraceRouteCompact, counts: formatTraceRouteCounts });
+    registerShortener("nextjs_route_map", { compact: formatNextjsRouteMapCompact, counts: formatNextjsRouteMapCounts });
+    registerShortener("nextjs_metadata_audit", { compact: formatNextjsMetadataAuditCompact, counts: formatNextjsMetadataAuditCounts });
+    registerShortener("framework_audit", { compact: formatFrameworkAuditCompact, counts: formatFrameworkAuditCounts });
     registerShortener("get_session_context", {
-        compact: (text) => {
+        compact: (raw) => {
+            const text = typeof raw === "string" ? raw : JSON.stringify(raw);
             try {
                 const data = JSON.parse(text);
                 return `session:${data.session_id?.slice(0, 8)} calls:${data.call_count} files:${data.explored_files?.count} symbols:${data.explored_symbols?.count} queries:${data.queries?.count} neg:${data.negative_evidence?.count}`;
@@ -1520,7 +3768,8 @@ export function registerTools(server, options) {
                 return text.slice(0, 500);
             }
         },
-        counts: (text) => {
+        counts: (raw) => {
+            const text = typeof raw === "string" ? raw : JSON.stringify(raw);
             try {
                 const data = JSON.parse(text);
                 return `files:${data.explored_files?.count} symbols:${data.explored_symbols?.count} queries:${data.queries?.count} neg:${data.negative_evidence?.count}`;