token-pilot 0.14.1 → 0.15.0

package/dist/server.js

@@ -28,7 +28,7 @@ import { handleNonCodeRead, isNonCodeStructured } from './handlers/non-code.js';
 import { handleFindUnused } from './handlers/find-unused.js';
 import { handleReadForEdit } from './handlers/read-for-edit.js';
 import { handleRelatedFiles } from './handlers/related-files.js';
-import { handleOutline, CODE_EXTENSIONS } from './handlers/outline.js';
+import { handleOutline } from './handlers/outline.js';
 import { handleCodeAudit } from './handlers/code-audit.js';
 import { handleModuleInfo } from './handlers/module-info.js';
 import { handleSmartDiff } from './handlers/smart-diff.js';
@@ -38,7 +38,9 @@ import { handleTestSummary } from './handlers/test-summary.js';
 import { detectContextMode } from './integration/context-mode-detector.js';
 import { estimateTokens } from './core/token-estimator.js';
 import { checkPolicy, isFullReadTool } from './core/policy-engine.js';
-import { resolveSafePath, validateSmartReadArgs, validateReadSymbolArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, validateSmartDiffArgs, validateExploreAreaArgs, validateSmartLogArgs, validateTestSummaryArgs, } from './core/validation.js';
+import { MCP_INSTRUCTIONS, TOOL_DEFINITIONS } from './server/tool-definitions.js';
+import { createTokenEstimates } from './server/token-estimates.js';
+import { validateSmartReadArgs, validateReadSymbolArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, validateSmartDiffArgs, validateExploreAreaArgs, validateSmartLogArgs, validateTestSummaryArgs, } from './core/validation.js';
 export async function createServer(projectRoot, options) {
     const config = await loadConfig(projectRoot);
     const astIndex = new AstIndexClient(projectRoot, config.astIndex.timeout, {
@@ -194,462 +196,13 @@ export async function createServer(projectRoot, options) {
     catch { /* fallback to hardcoded */ }
     const server = new Server({ name: 'token-pilot', version: pkgVersion }, {
         capabilities: { tools: {} },
-        instructions: [
-            'Token Pilot provides token-efficient code reading. Use these rules:',
-            '',
-            'WHEN TO USE TOKEN PILOT (saves 60-80% tokens):',
-            '• Reading code files → smart_read (returns structure, not raw content)',
-            '• Need one function/class → read_symbol (loads only that symbol)',
-            '• Exploring a directory → outline (all symbols in one call)',
-            '• Preparing an edit → read_for_edit (exact text for Edit old_string)',
-            '• Verifying edits → read_diff (only changed hunks). IMPORTANT: call smart_read BEFORE editing to create baseline.',
-            '• Finding symbol references → find_usages (semantic, grouped by type)',
-            '• Understanding file relationships → related_files (imports, dependents, tests)',
-            '• New codebase → project_overview first',
-            '• Reading file again → smart_read (returns compact reminder, not full content)',
-            '• Multiple files → smart_read_many (batch, max 20)',
-            '• Code quality audit → code_audit (TODOs, deprecated, structural code patterns)',
-            '• Reviewing git changes → smart_diff (structural diff with symbol mapping, not raw patch)',
-            '• Starting work on an area → explore_area (outline + imports + tests + git log in one call)',
-            '• Understanding commit history → smart_log (structured git log with categories, not raw output)',
-            '• Running tests → test_summary (structured pass/fail summary, not 200 lines of raw output)',
-            '',
-            'WHEN TO USE DEFAULT TOOLS (Token Pilot adds no value):',
-            '• Small files (≤200 lines) → smart_read returns full content anyway, same as Read',
-            '• Regex text search (e.g. TODO.*fix) → use Grep/ripgrep',
-            '• Counting occurrences (e.g. how many `any` types?) → use Grep count mode',
-            '• Finding code duplication → use Grep to search for repeated patterns',
-            '• Non-code files (JSON, YAML, Markdown, configs) → smart_read handles these but default Read works too',
-            '• You need exact raw content for copy-paste → use Read',
-            '',
-            'COMBINE BOTH for audits and code review:',
-            '• Structure/navigation → Token Pilot (project_overview, outline, smart_read)',
-            '• Dead code detection → find_unused (finds unreferenced symbols)',
-            '• Code issues → code_audit (TODOs, deprecated, structural patterns like bare except:)',
-            '• Text pattern search/counting → Grep (regex, count mode)',
-            '• Security audit → Grep for: password, token, secret, credential, hardcoded, api_key, TODO.*security',
-            '• Deep dive into specific code → read_symbol (after finding issues)',
-            '• Module architecture → module_info (deps, dependents, public API, unused deps)',
-            '',
-            'WORKFLOW: project_overview → explore_area → smart_read → read_symbol → read_for_edit → edit → smart_diff',
-        ].join('\n'),
+        instructions: MCP_INSTRUCTIONS,
     });
     server.setRequestHandler(ListToolsRequestSchema, () => ({
-        tools: [
-            // --- Core reading tools ---
-            {
-                name: 'smart_read',
-                description: 'Use INSTEAD OF Read/cat for code files. Returns code structure (classes, functions, methods with signatures and line ranges) — 60-80% fewer tokens than raw content. Use read_symbol() to drill into specific code.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        path: { type: 'string', description: 'File path (absolute or relative to project root)' },
-                        show_imports: { type: 'boolean', description: 'Include import details (default: true)' },
-                        show_docs: { type: 'boolean', description: 'Include doc comments (default: true)' },
-                        depth: { type: 'number', description: 'Max depth for nested symbols (default: 2)' },
-                    },
-                    required: ['path'],
-                },
-            },
-            {
-                name: 'read_symbol',
-                description: 'Read source code of ONE specific function/method/class — INSTEAD OF reading the whole file. Supports Class.method syntax.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        path: { type: 'string', description: 'File path' },
-                        symbol: { type: 'string', description: 'Symbol name, e.g. "UserService.updateUser"' },
-                        context_before: { type: 'number', description: 'Lines of context before (default: 2)' },
-                        context_after: { type: 'number', description: 'Lines of context after (default: 0)' },
-                        show: { type: 'string', enum: ['full', 'head', 'tail', 'outline'], description: 'Display mode: full (all lines), head (first 50), tail (last 30), outline (head + methods + tail). Default: auto (full ≤300 lines, outline >300)' },
-                    },
-                    required: ['path', 'symbol'],
-                },
-            },
-            {
-                name: 'read_range',
-                description: 'Read a specific line range from a file.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        path: { type: 'string', description: 'File path' },
-                        start_line: { type: 'number', description: 'Start line (1-indexed)' },
-                        end_line: { type: 'number', description: 'End line (1-indexed, inclusive)' },
-                    },
-                    required: ['path', 'start_line', 'end_line'],
-                },
-            },
-            {
-                name: 'read_diff',
-                description: 'Use INSTEAD OF re-reading whole file after edits. Shows only changed hunks. REQUIRES: call smart_read or read_for_edit BEFORE editing to create baseline snapshot.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        path: { type: 'string', description: 'File path' },
-                        context_lines: { type: 'number', description: 'Lines of context around changes (default: 3)' },
-                    },
-                    required: ['path'],
-                },
-            },
-            {
-                name: 'read_for_edit',
-                description: 'Use INSTEAD OF Read when preparing an edit. Returns exact raw code around a symbol or line — copy directly as old_string for Edit tool. Optional: include_callers, include_tests, include_changes for enriched context.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        path: { type: 'string', description: 'File path' },
-                        symbol: { type: 'string', description: 'Symbol name to edit (e.g. "UserService.updateUser")' },
-                        line: { type: 'number', description: 'Line number to edit (alternative to symbol)' },
-                        context: { type: 'number', description: 'Lines of context around target (default: 5)' },
-                        include_callers: { type: 'boolean', description: 'Show top callers of this symbol (saves a separate find_usages call)' },
-                        include_tests: { type: 'boolean', description: 'Show related test file and test names' },
-                        include_changes: { type: 'boolean', description: 'Show recent git changes in the target region' },
-                    },
-                    required: ['path'],
-                },
-            },
-            {
-                name: 'smart_read_many',
-                description: 'Batch smart_read for multiple files at once — INSTEAD OF calling Read on each file. Returns structure for each file. Max 20 files.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        paths: {
-                            type: 'array',
-                            items: { type: 'string' },
-                            description: 'Array of file paths',
-                        },
-                    },
-                    required: ['paths'],
-                },
-            },
-            // --- Search & navigation ---
-            {
-                name: 'find_usages',
-                description: 'Use INSTEAD OF Grep/ripgrep for finding symbol references. Semantic search across the project — groups results by: definitions, imports, usages. (v1.1: added scope, kind, limit, lang filters)',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        symbol: { type: 'string', description: 'Symbol name to find usages of' },
-                        scope: { type: 'string', description: 'Filter results by path prefix (e.g., "src/Domain/")' },
-                        kind: { type: 'string', enum: ['definitions', 'imports', 'usages', 'all'], description: 'Show only specific section (default: "all")' },
-                        limit: { type: 'number', description: 'Max results per category (default: 50, max: 500)' },
-                        lang: { type: 'string', description: 'Filter by language/extension (e.g., "php", "typescript")' },
-                    },
-                    required: ['symbol'],
-                },
-            },
-            {
-                name: 'project_overview',
-                description: 'START HERE for unfamiliar codebases. Shows project type (dual-detection: ast-index + config files), architecture, framework detection, quality tools, CI, directory map. (v1.1: added include filter)',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        include: {
-                            type: 'array',
-                            items: { type: 'string', enum: ['stack', 'ci', 'quality', 'architecture'] },
-                            description: 'Sections to include (default: all). Use ["stack"] for quick type check, ["quality","ci"] for tooling overview.',
-                        },
-                    },
-                },
-            },
-            {
-                name: 'related_files',
-                description: 'Show ranked import graph for a file: imports, importers, and tests scored by relevance (test adjacency, import closeness, recent changes, path proximity). Files ranked into HIGH VALUE / MEDIUM / LOW to prioritize reading.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        path: { type: 'string', description: 'File path to analyze' },
-                    },
-                    required: ['path'],
-                },
-            },
-            {
-                name: 'outline',
-                description: 'Use INSTEAD OF listing dir + reading each file. One call returns all symbols (classes, functions, methods, routes) for every code file in a directory. (v1.1: added recursive, max_depth)',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        path: { type: 'string', description: 'Directory path' },
-                        recursive: { type: 'boolean', description: 'Recursively outline subdirectories (default: false)' },
-                        max_depth: { type: 'number', description: 'Max recursion depth when recursive=true (default: 2, max: 5)' },
-                    },
-                    required: ['path'],
-                },
-            },
-            // --- Analytics ---
-            {
-                name: 'session_analytics',
-                description: 'Show token savings report for this session: total tokens saved, per-tool breakdown, top files by savings.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {},
-                },
-            },
-            // --- Analysis ---
-            {
-                name: 'find_unused',
-                description: 'Find dead code — functions, classes, and variables with no references across the project. Use for cleanup and refactoring.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        module: { type: 'string', description: 'Filter by module path (e.g., "src/services/")' },
-                        export_only: { type: 'boolean', description: 'Only check exported (capitalized) symbols' },
-                        limit: { type: 'number', description: 'Max results (default: 30)' },
-                    },
-                },
-            },
-            {
-                name: 'code_audit',
-                description: 'Find code quality issues: TODO/FIXME comments, deprecated symbols, structural code patterns (bare except:, print() calls). Use for project-wide audits.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        check: {
-                            type: 'string',
-                            enum: ['pattern', 'todo', 'deprecated', 'annotations', 'all'],
-                            description: 'What to check: "pattern" (structural search via ast-grep, e.g. "except:", "print($$$ARGS)"), "todo" (TODO/FIXME comments), "deprecated" (deprecated symbols), "annotations" (find by decorator name), "all" (todo + deprecated summary)',
-                        },
-                        pattern: { type: 'string', description: 'Code pattern for check="pattern". ast-grep syntax: "except:" finds bare excepts, "print($$$ARGS)" finds print calls.' },
-                        name: { type: 'string', description: 'Decorator/annotation name for check="annotations". Example: "Deprecated", "Controller"' },
-                        lang: { type: 'string', description: 'Language filter for check="pattern" (e.g., "python", "typescript")' },
-                        limit: { type: 'number', description: 'Max results (default: 50)' },
-                    },
-                    required: ['check'],
-                },
-            },
-            {
-                name: 'module_info',
-                description: 'Analyze module dependencies, dependents, public API, and unused deps. Use for architecture understanding and dependency cleanup.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        module: { type: 'string', description: 'Module name or path pattern (e.g., "auth", "src/Domain/")' },
-                        check: {
-                            type: 'string',
-                            enum: ['deps', 'dependents', 'api', 'unused-deps', 'all'],
-                            description: 'What to check: "deps" (dependencies), "dependents" (who depends on this), "api" (public symbols), "unused-deps" (dead dependencies), "all" (everything). Default: "all"',
-                        },
-                    },
-                    required: ['module'],
-                },
-            },
-            // --- Diff & exploration ---
-            {
-                name: 'smart_diff',
-                description: 'Use INSTEAD OF raw git diff. Shows changed files with AST symbol mapping — which functions/classes were modified/added/removed. Small diffs include hunks, large diffs show summary.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        scope: { type: 'string', enum: ['unstaged', 'staged', 'commit', 'branch'], description: 'Diff scope (default: "unstaged")' },
-                        path: { type: 'string', description: 'Filter to specific file or directory' },
-                        ref: { type: 'string', description: 'Git ref — required for scope="commit" (commit hash) or scope="branch" (branch name)' },
-                    },
-                },
-            },
-            {
-                name: 'explore_area',
-                description: 'One-call exploration of a directory: outline (all symbols), imports (external deps + who imports this area), tests (matching test files), recent git changes. Use INSTEAD OF separate outline + related_files + git log calls.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        path: { type: 'string', description: 'Directory path (or file path — will use its parent directory)' },
-                        include: {
-                            type: 'array',
-                            items: { type: 'string', enum: ['outline', 'imports', 'tests', 'changes'] },
-                            description: 'Sections to include (default: all)',
-                        },
-                    },
-                    required: ['path'],
-                },
-            },
-            {
-                name: 'smart_log',
-                description: 'Use INSTEAD OF raw git log. Structured commit history with category detection (feat/fix/refactor/docs), file stats, author breakdown. Filters by path and ref.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        path: { type: 'string', description: 'Filter to specific file or directory' },
-                        count: { type: 'number', description: 'Number of commits (default: 10, max: 50)' },
-                        ref: { type: 'string', description: 'Git ref — branch, tag, or commit (default: HEAD)' },
-                    },
-                },
-            },
-            {
-                name: 'test_summary',
-                description: 'Run tests and return structured summary: total/passed/failed/skipped + failure details. 200 lines of raw output → 10-15 lines. Supports vitest, jest, pytest, phpunit, go test, cargo test.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        command: { type: 'string', description: 'Test command to run (e.g., "npm test", "pytest", "go test ./...")' },
-                        runner: { type: 'string', enum: ['vitest', 'jest', 'pytest', 'phpunit', 'go', 'cargo', 'rspec', 'mocha'], description: 'Force specific parser (auto-detected if omitted)' },
-                        timeout: { type: 'number', description: 'Timeout in ms (default: 60000, max: 300000)' },
-                    },
-                    required: ['command'],
-                },
-            },
-        ],
+        tools: TOOL_DEFINITIONS,
     }));
-    // Helper: get real full-file token count for honest analytics
-    async function fullFileTokens(relativePath) {
-        try {
-            const absPath = resolveSafePath(projectRoot, relativePath);
-            const cached = fileCache.get(absPath);
-            if (cached)
-                return estimateTokens(cached.content);
-            const { readFile: readFileAsync } = await import('node:fs/promises');
-            const content = await readFileAsync(absPath, 'utf-8');
-            return estimateTokens(content);
-        }
-        catch {
-            return 0;
-        }
-    }
-    async function estimateProjectOverviewWorkflowTokens(includeSections) {
-        const sectionFiles = {
-            stack: ['package.json', 'composer.json', 'Cargo.toml', 'pyproject.toml', 'go.mod'],
-            ci: ['.gitlab-ci.yml', 'Jenkinsfile', '.circleci/config.yml', 'bitbucket-pipelines.yml', '.travis.yml'],
-            quality: [
-                'tsconfig.json',
-                'vitest.config.ts',
-                'vitest.config.js',
-                'vitest.config.mts',
-                'jest.config.js',
-                'jest.config.ts',
-                'jest.config.mjs',
-                'eslint.config.js',
-                'eslint.config.mjs',
-                '.eslintrc',
-                '.eslintrc.js',
-                '.eslintrc.json',
-                '.eslintrc.yml',
-                'biome.json',
-                'biome.jsonc',
-                '.prettierrc',
-                '.prettierrc.js',
-                '.prettierrc.json',
-                'prettier.config.js',
-                'phpunit.xml',
-                'phpunit.xml.dist',
-                'phpstan.neon',
-                'phpstan.neon.dist',
-            ],
-            architecture: ['README.md'],
-        };
-        let total = 0;
-        const seen = new Set();
-        for (const section of includeSections) {
-            for (const file of sectionFiles[section]) {
-                if (seen.has(file))
-                    continue;
-                seen.add(file);
-                total += await fullFileTokens(file);
-            }
-        }
-        if (includeSections.includes('ci')) {
-            try {
-                const { readdir: readDirAsync } = await import('node:fs/promises');
-                const workflowDir = resolveSafePath(projectRoot, '.github/workflows');
-                const workflowFiles = await readDirAsync(workflowDir, { withFileTypes: true });
-                for (const file of workflowFiles) {
-                    if (!file.isFile())
-                        continue;
-                    if (!file.name.endsWith('.yml') && !file.name.endsWith('.yaml'))
-                        continue;
-                    total += await fullFileTokens(`.github/workflows/${file.name}`);
-                }
-            }
-            catch {
-                // ignore missing workflows dir
-            }
-        }
-        if (includeSections.includes('architecture')) {
-            total += 200;
-        }
-        return total;
-    }
-    async function estimateOutlineWorkflowTokens(relativePath, recursive, maxDepth) {
-        const SAMPLE_LIMIT = 30;
-        try {
-            const { readdir: readDirAsync } = await import('node:fs/promises');
-            const { resolve: resolvePath } = await import('node:path');
-            const absDir = resolveSafePath(projectRoot, relativePath);
-            const sampledFiles = [];
-            let totalFiles = 0;
-            async function walk(dirPath, depth) {
-                const entries = await readDirAsync(dirPath, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (entry.isFile()) {
-                        const ext = entry.name.split('.').pop()?.toLowerCase() ?? '';
-                        if (!CODE_EXTENSIONS.has(ext))
-                            continue;
-                        totalFiles++;
-                        if (sampledFiles.length < SAMPLE_LIMIT) {
-                            sampledFiles.push(resolvePath(dirPath, entry.name));
-                        }
-                        continue;
-                    }
-                    if (entry.isDirectory() && recursive && depth < maxDepth) {
-                        await walk(resolvePath(dirPath, entry.name), depth + 1);
-                    }
-                }
-            }
-            await walk(absDir, 0);
-            if (totalFiles === 0)
-                return 0;
-            let sampledTokens = 0;
-            for (const filePath of sampledFiles) {
-                const relPath = filePath.startsWith(projectRoot)
-                    ? filePath.slice(projectRoot.length + 1)
-                    : filePath;
-                sampledTokens += await fullFileTokens(relPath);
-            }
-            if (sampledFiles.length === 0 || sampledTokens === 0)
-                return 0;
-            if (sampledFiles.length === totalFiles)
-                return sampledTokens;
-            const averageTokens = sampledTokens / sampledFiles.length;
-            return Math.round(averageTokens * totalFiles);
-        }
-        catch {
-            return 0;
-        }
-    }
-    async function estimateRelatedFilesWorkflowTokens(targetPath, meta) {
-        const related = new Set([targetPath]);
-        for (const path of meta?.imports ?? [])
-            related.add(path);
-        for (const path of meta?.importedBy ?? [])
-            related.add(path);
-        for (const path of meta?.tests ?? [])
-            related.add(path);
-        let total = 0;
-        let counted = 0;
-        for (const path of related) {
-            total += await fullFileTokens(path);
-            counted++;
-            if (counted >= 12)
-                break;
-        }
-        return total;
-    }
-    async function estimateFindUsagesWorkflowTokens(files) {
-        let total = 0;
-        let counted = 0;
-        for (const file of files) {
-            total += await fullFileTokens(file);
-            counted++;
-            if (counted >= 20)
-                break;
-        }
-        return total;
-    }
-    /** Detect savings category from response text prefix. */
-    function detectSavingsCategory(text) {
-        if (text.startsWith('REMINDER:') || text.startsWith('DEDUP:'))
-            return 'dedup';
-        return 'compression';
-    }
+    // Token estimation functions (extracted to server/token-estimates.ts)
+    const { fullFileTokens, estimateProjectOverviewWorkflowTokens, estimateOutlineWorkflowTokens, estimateRelatedFilesWorkflowTokens, estimateFindUsagesWorkflowTokens, estimateExploreAreaWorkflowTokens, detectSavingsCategory, } = createTokenEstimates(() => projectRoot, fileCache);
     /** Record analytics with intent classification and decision trace. Returns policy advisory if any. */
     function recordWithTrace(call) {
         const { absPath, args, recentlyEdited, ...rest } = call;
@@ -682,28 +235,6 @@ export async function createServer(projectRoot, options) {
         });
         return advisory ? `\n${advisory.message}` : null;
     }
-    async function estimateExploreAreaWorkflowTokens(meta) {
-        const localFiles = new Set();
-        for (const file of meta.codeFiles ?? [])
-            localFiles.add(file);
-        for (const file of meta.testFiles ?? [])
-            localFiles.add(file);
-        for (const file of meta.internalDeps ?? [])
-            localFiles.add(file);
-        for (const file of meta.importedBy ?? [])
-            localFiles.add(file);
-        let total = 0;
-        let counted = 0;
-        for (const file of localFiles) {
-            total += await fullFileTokens(file);
-            counted++;
-            if (counted >= 24)
-                break;
-        }
-        total += (meta.externalDeps?.length ?? 0) * 30;
-        total += (meta.changeCount ?? 0) * 40;
-        return total;
-    }
     // Handle tool calls with validated arguments
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;

package/dist/types.d.ts

@@ -98,6 +98,7 @@ export interface TokenPilotConfig {
         enabled: boolean;
         interceptRead: boolean;
         autoInstall: boolean;
+        denyThreshold: number;
     };
     context: {
         estimateTokens: boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "token-pilot",
-  "version": "0.14.1",
-  "description": "Save 60-80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
+  "version": "0.15.0",
+  "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -29,24 +29,26 @@
     "prepublishOnly": "npm run build && node --input-type=module -e \"import { chmod } from 'node:fs/promises'; await chmod('dist/index.js', 0o755);\""
   },
   "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "cursor",
+    "codex",
+    "cline",
+    "ai-coding",
+    "llm-tools",
     "token-savings",
     "token-reduction",
     "context-window",
-    "save-tokens",
-    "reduce-tokens",
-    "token-efficient",
-    "token-economy",
     "context-optimization",
-    "fewer-tokens",
-    "mcp",
-    "mcp-server",
-    "model-context-protocol",
     "ast",
     "code-reading",
     "code-navigation",
     "smart-read",
-    "ai-coding",
-    "llm-tools"
+    "developer-tools",
+    "tree-sitter"
   ],
   "repository": {
     "type": "git",

package/skills/guide/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: guide
+description: Show a quick-reference guide for all Token Pilot tools — when to use each one
+command: guide
+user_invocable: true
+---
+
+Display the following Token Pilot tool reference to the user. Show it exactly as formatted below.
+
+---
+
+## Token Pilot — Tool Reference
+
+### Reading code
+| Goal | Tool |
+|------|------|
+| Explore a file's structure | `smart_read(path)` |
+| Read one function or class | `read_symbol(path, symbol="ClassName.method")` |
+| Read a specific line range | `read_range(path, start, end)` |
+| Get edit-ready exact text | `read_for_edit(path, symbol="name")` |
+| Read many files at once | `smart_read_many([paths])` |
+
+### Exploring a codebase
+| Goal | Tool |
+|------|------|
+| First look at a new project | `project_overview()` |
+| All symbols in a file | `outline(path)` |
+| Deep dive on one area | `explore_area(path)` |
+| Related files (imports, tests) | `related_files(path)` |
+| Module deps + public API | `module_info(module_path)` |
+
+### Finding things
+| Goal | Tool |
+|------|------|
+| Where a symbol is used | `find_usages(symbol)` |
+| Symbols with no references | `find_unused(path)` |
+
+### After editing
+| Goal | Tool |
+|------|------|
+| Verify your edit is correct | `read_diff(path)` |
+
+### Git & tests
+| Goal | Tool |
+|------|------|
+| Understand recent commits | `smart_log()` |
+| Review a diff structurally | `smart_diff(base, head)` |
+| Parse test output | `test_summary(command)` |
+
+### Code quality
+| Goal | Tool |
+|------|------|
+| Find TODOs, deprecated, patterns | `code_audit(path)` |
+
+### Session
+| Goal | Tool |
+|------|------|
+| Token savings this session | `session_analytics()` |
+
+---
+
+**Workflow:** `project_overview` → `explore_area` → `smart_read` → `read_symbol` → `read_for_edit` → edit → `read_diff`
+
+**Tip:** `smart_read` on a file you've already read returns a compact reminder (dedup) — no wasted tokens.