@mjasnikovs/pi-task 0.10.2 → 0.11.0

package/dist/task/child-runner.d.ts

@@ -38,6 +38,8 @@ interface PhaseDeps {
      */
     recordSubStep?: (label: string, ms: number) => void;
     spawn?: SpawnFn;
+    /** Write a timestamped line to the per-task debug log. Fire-and-forget. */
+    logDebug?: (msg: string) => void;
 }
 export type { PhaseDeps };
 /**

package/dist/task/orchestrator.js

@@ -164,6 +164,13 @@ export class TaskRunner {
         // any phase work — and recover it if the session dies mid-pipeline.
         if (this._onStart)
             await this._onStart(id);
+        // Wire up per-task debug log (<cwd>/.pi-tasks/TASK_XXXX-debug.log).
+        const debugLogPath = path.join(tasksDir(cwd), `${id}-debug.log`);
+        this._deps.logDebug = (msg) => {
+            const line = `${new Date().toISOString()} ${msg}\n`;
+            fsp.appendFile(debugLogPath, line).catch(() => { });
+        };
+        this._deps.logDebug(`run: start phase=${resumePhase}`);
         // Register as active.
         this._widgetState.taskId = id;
         this._widgetState.title = title;
@@ -194,6 +201,7 @@ export class TaskRunner {
                     continue;
                 }
                 await advance(phase.name);
+                this._deps.logDebug?.(`phase:${phase.name}: start`);
                 const children = [];
                 this._currentPhaseChildren = children;
                 const phaseStart = Date.now();
@@ -202,12 +210,10 @@ export class TaskRunner {
                     out = await phase.run(this._deps, this._pc);
                 }
                 finally {
-                    this._timings.push({
-                        label: phase.name,
-                        ms: Date.now() - phaseStart,
-                        children
-                    });
+                    const phaseMs = Date.now() - phaseStart;
+                    this._timings.push({ label: phase.name, ms: phaseMs, children });
                     this._currentPhaseChildren = null;
+                    this._deps.logDebug?.(`phase:${phase.name}: done ms=${phaseMs}`);
                 }
                 await setTaskSection(cwd, id, phase.section, out);
                 this._pc[phase.field] = out;

package/dist/task/phases.js

@@ -74,6 +74,7 @@ export async function phaseVerifyTooling(deps, research) {
     await setTaskSection(deps.cwd, deps.taskId, 'verified tooling', verifiedSection);
     return replaceToolingWithVerified(research, parsed.verified);
 }
+const DOCS_EXTENSION_PATH = new URL('../workers/docs-extension.js', import.meta.url).pathname;
 export async function phaseResearch(deps, refined, researchDeps = {}) {
     const docsRawFn = researchDeps.docsRaw ?? docsRaw;
     const fetchRawFn = researchDeps.fetchRaw ?? fetchRaw;
@@ -192,7 +193,12 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             label: 'worker:files',
             prompt: appendNoThink(promptHeader + RESEARCH_FILES_PROMPT(refined))
         },
-        { label: 'worker:apis', prompt: appendNoThink(promptHeader + RESEARCH_APIS_PROMPT(refined)) },
+        {
+            label: 'worker:apis',
+            prompt: appendNoThink(promptHeader + RESEARCH_APIS_PROMPT(refined)),
+            tools: 'read,grep,find,ls,pi-worker-docs',
+            extensions: [DOCS_EXTENSION_PATH]
+        },
         {
             label: 'worker:context',
             prompt: appendNoThink(promptHeader + RESEARCH_CONTEXT_PROMPT(refined)),
@@ -209,13 +215,22 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     ];
     const workerResults = [];
     for (const spec of workerSpecs) {
+        deps.logDebug?.(`${spec.label}: start`);
         const r = await recordWorker(spec.label, runWorker({
             prompt: spec.prompt,
             cwd: deps.cwd,
             signal: deps.signal,
             spawn: deps.spawn,
-            ...(spec.tools ? { tools: spec.tools } : {})
+            ...(spec.tools ? { tools: spec.tools } : {}),
+            ...(spec.extensions ? { extensions: spec.extensions } : {}),
+            onLine: line => {
+                deps.logDebug?.(`${spec.label}: ${line}`);
+                deps.onChildOutput?.(`${spec.label}: ${line}`);
+            }
         }));
+        deps.logDebug?.(`${spec.label}: done exit=${r.exitCode} wait=${r.waitMs}ms work=${r.workMs}ms`
+            + (r.stderr ? ` stderr=${r.stderr.slice(0, 300)}` : '')
+            + (r.leakedToolCall ? ` leaked=${r.leakedToolCall.trim().slice(0, 80)}` : ''));
         updateProgress();
         workerResults.push(r);
     }

package/dist/task/prompts.js

@@ -88,7 +88,9 @@ No section header. No other sections. No preamble.
 
 Task:
 ${refined}`;
-const RESEARCH_APIS_PROMPT = (refined) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools to identify the commands, functions, types, and interfaces the agent will use for the following task.
+const RESEARCH_APIS_PROMPT = (refined) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools — and \`pi-worker-docs\` for installed npm packages — to identify the commands, functions, types, and interfaces the agent will use for the following task.
+
+NPM PACKAGES — use pi-worker-docs, NOT file reads: for any third-party npm package (e.g. "zod", "hono", "drizzle-orm"), call \`pi-worker-docs(module, query)\` to get its type signatures and API surface. Do NOT open node_modules source files directly — those reads are expensive and produce far more noise than the tool. The tool returns a compact, focused excerpt in a fraction of the token cost.
 
 APIS owns symbols and commands BY NAME ONLY. Do NOT include any file path or path fragment — no \`package.json\`, no \`./src/foo.ts\`, no \`package.json#scripts.lint\`. If the symbol is a script defined in package.json, write the invocation (\`npm run lint\`), not its location. If the symbol is a config file, it does not belong in APIS at all — it belongs in FILES.
 

package/dist/workers/docs-extension.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export default function (pi: ExtensionAPI): void;

package/dist/workers/docs-extension.js

@@ -0,0 +1,4 @@
+import { registerPiWorkerDocs } from './pi-worker-docs.js';
+export default function (pi) {
+    registerPiWorkerDocs(pi);
+}

package/dist/workers/docs-project.d.ts

@@ -0,0 +1,38 @@
+import type { CacheHandle } from './docs-cache.js';
+import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
+import type { RetrievedChunk } from './docs-retrieve.js';
+export declare function getProjectName(cwd: string): string;
+export declare function cwdKey(cwd: string): string;
+export declare function getProjectFiles(cwd: string): string[];
+export declare function getMaxMtime(files: string[]): string;
+export interface ProjectIndexResult {
+    hitCache: boolean;
+    filesIngested: number;
+    chunksWritten: number;
+    indexingMs?: number;
+}
+export declare function ensureProjectIndexed(cache: CacheHandle, name: string, version: string, files: string[], cwd: string): ProjectIndexResult;
+export type ProjectDocsRawResult = {
+    kind: 'ok';
+    projectName: string;
+    cacheKey: string;
+    version: string;
+    chunks: RetrievedChunk[];
+    hitCache: boolean;
+    filesIngested: number;
+    chunksWritten: number;
+    indexingMs?: number;
+} | {
+    kind: 'no_chunks';
+    projectName: string;
+    cacheKey: string;
+    version: string;
+    hitCache: boolean;
+    filesIngested: number;
+} | {
+    kind: 'error';
+    projectName: string;
+    message: string;
+};
+export declare function projectDocsRaw(cache: CacheHandle, cwd: string, query: string, retrieveChunksFn?: typeof defaultRetrieveChunks): ProjectDocsRawResult;
+export declare function buildProjectPrompt(projectName: string, query: string, content: string): string;

package/dist/workers/docs-project.js

@@ -0,0 +1,249 @@
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
+const MAX_CHUNK_BYTES = 8 * 1024;
+const DEFAULT_LIMIT = 50;
+const DEFAULT_BUDGET = 24_000;
+const DECL_SPLIT_RE = /^(?:export\s+|declare\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|namespace|module|const|let|var|enum)\s+/m;
+export function getProjectName(cwd) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+        if (pkg.name)
+            return pkg.name;
+    }
+    catch { }
+    return path.basename(cwd);
+}
+export function cwdKey(cwd) {
+    return createHash('sha256').update(cwd).digest('hex').slice(0, 8);
+}
+export function getProjectFiles(cwd) {
+    try {
+        const result = spawnSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '*.ts', '*.tsx'], { cwd, encoding: 'utf8', timeout: 5000 });
+        if (result.status === 0 && result.stdout?.trim()) {
+            return result.stdout
+                .trim()
+                .split('\n')
+                .filter(Boolean)
+                .map(f => path.join(cwd, f));
+        }
+    }
+    catch { }
+    return walkTsFiles(cwd);
+}
+function walkTsFiles(root) {
+    const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
+    const out = [];
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (SKIP.has(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                stack.push(full);
+            else if (entry.isFile() &&
+                (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))) {
+                out.push(full);
+            }
+        }
+    }
+    return out.sort();
+}
+export function getMaxMtime(files) {
+    let max = 0;
+    for (const f of files) {
+        try {
+            const { mtimeMs } = fs.statSync(f);
+            if (mtimeMs > max)
+                max = mtimeMs;
+        }
+        catch { }
+    }
+    return String(Math.floor(max));
+}
+function chunkTs(content, relPath) {
+    const splits = splitAtMatches(content, new RegExp(DECL_SPLIT_RE.source, 'gm'));
+    const chunks = [];
+    for (const part of splits) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const prefixed = `// ${relPath}\n${trimmed}`;
+        if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
+            for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES))
+                chunks.push(slice);
+        }
+        else {
+            chunks.push(prefixed);
+        }
+    }
+    return chunks;
+}
+function splitAtMatches(text, re) {
+    const parts = [];
+    let lastIndex = 0;
+    let m;
+    while ((m = re.exec(text))) {
+        if (m.index > lastIndex)
+            parts.push(text.slice(lastIndex, m.index));
+        lastIndex = m.index;
+        re.lastIndex = m.index + 1;
+    }
+    if (lastIndex < text.length)
+        parts.push(text.slice(lastIndex));
+    return parts.length ? parts : [text];
+}
+function sliceBytes(s, maxBytes) {
+    const out = [];
+    let buf = Buffer.from(s, 'utf8');
+    while (buf.length > maxBytes) {
+        const slice = buf.subarray(0, maxBytes).toString('utf8');
+        out.push(slice);
+        buf = buf.subarray(Buffer.byteLength(slice, 'utf8'));
+    }
+    if (buf.length)
+        out.push(buf.toString('utf8'));
+    return out;
+}
+export function ensureProjectIndexed(cache, name, version, files, cwd) {
+    const existing = cache.db
+        .prepare('SELECT content_hash FROM packages WHERE name = ? AND version = ?')
+        .get(name, version);
+    if (existing)
+        return { hitCache: true, filesIngested: 0, chunksWritten: 0 };
+    const t0 = Date.now();
+    cache.db.exec('BEGIN IMMEDIATE');
+    try {
+        // Clear all old versions of this project
+        cache.db.prepare('DELETE FROM chunks WHERE name = ?').run(name);
+        cache.db.prepare('DELETE FROM packages WHERE name = ?').run(name);
+        const insertChunk = cache.db.prepare('INSERT INTO chunks (name, version, file_path, kind, content) VALUES (?, ?, ?, ?, ?)');
+        let filesIngested = 0;
+        let chunksWritten = 0;
+        for (const abs of files) {
+            let raw;
+            try {
+                raw = fs.readFileSync(abs, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const rel = path.relative(cwd, abs);
+            const chunks = chunkTs(raw, rel);
+            if (!chunks.length)
+                continue;
+            filesIngested++;
+            for (const c of chunks) {
+                insertChunk.run(name, version, rel, 'dts', c);
+                chunksWritten++;
+            }
+        }
+        cache.db
+            .prepare('INSERT OR REPLACE INTO packages (name, version, content_hash, indexed_at) VALUES (?, ?, ?, ?)')
+            .run(name, version, version, Date.now());
+        cache.db.exec('COMMIT');
+        return { hitCache: false, filesIngested, chunksWritten, indexingMs: Date.now() - t0 };
+    }
+    catch (err) {
+        cache.db.exec('ROLLBACK');
+        throw err;
+    }
+}
+export function projectDocsRaw(cache, cwd, query, retrieveChunksFn = defaultRetrieveChunks) {
+    const projectName = getProjectName(cwd);
+    const cacheKey = `project:${cwdKey(cwd)}`;
+    const files = getProjectFiles(cwd);
+    const version = getMaxMtime(files);
+    let indexResult;
+    try {
+        indexResult = ensureProjectIndexed(cache, cacheKey, version, files, cwd);
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            projectName,
+            message: `Indexing failed: ${err instanceof Error ? err.message : String(err)}`
+        };
+    }
+    const chunkCount = cache.db
+        .prepare('SELECT count(*) AS c FROM chunks WHERE name = ? AND version = ?')
+        .get(cacheKey, version)?.c ?? 0;
+    if (chunkCount === 0) {
+        return {
+            kind: 'no_chunks',
+            projectName,
+            cacheKey,
+            version,
+            hitCache: indexResult.hitCache,
+            filesIngested: indexResult.filesIngested
+        };
+    }
+    let chunks;
+    try {
+        chunks = retrieveChunksFn(cache, {
+            name: cacheKey,
+            version,
+            query,
+            limit: DEFAULT_LIMIT,
+            contentBudget: DEFAULT_BUDGET
+        });
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            projectName,
+            message: `Retrieval failed: ${err instanceof Error ? err.message : String(err)}`
+        };
+    }
+    if (chunks.length === 0) {
+        return {
+            kind: 'no_chunks',
+            projectName,
+            cacheKey,
+            version,
+            hitCache: indexResult.hitCache,
+            filesIngested: indexResult.filesIngested
+        };
+    }
+    return {
+        kind: 'ok',
+        projectName,
+        cacheKey,
+        version,
+        chunks,
+        hitCache: indexResult.hitCache,
+        filesIngested: indexResult.filesIngested,
+        chunksWritten: indexResult.chunksWritten,
+        indexingMs: indexResult.indexingMs
+    };
+}
+export function buildProjectPrompt(projectName, query, content) {
+    return (`You answer one question about a local project's source code, using only the provided content.\n`
+        + `\n`
+        + `Rules:\n`
+        + `1. Output ONLY two tags, in this order, with NO text outside them:\n`
+        + `   <answer>...your answer...</answer>\n`
+        + `   <excerpt>...verbatim quote from <project-content>...</excerpt>\n`
+        + `2. The <excerpt> MUST be copied character-for-character from <project-content>.\n`
+        + `   Do not paraphrase, translate, or summarise inside <excerpt>.\n`
+        + `3. Prefer type signatures, function declarations, and code blocks as evidence over prose.\n`
+        + `4. If the answer is unclear, ambiguous, or absent from <project-content>, write exactly:\n`
+        + `   <answer>unclear from this project</answer> and put the closest related text in <excerpt>.\n`
+        + `   Do not guess.\n`
+        + `5. Be terse. One short paragraph in <answer> max.\n`
+        + `\n`
+        + `<project>${projectName}</project>\n`
+        + `<question>${query}</question>\n`
+        + `<project-content>\n${content}\n</project-content>\n`);
+}

package/dist/workers/docs-retrieve.js

@@ -1,4 +1,4 @@
-const DEFAULT_LIMIT = 8;
+const DEFAULT_LIMIT = 50;
 const DEFAULT_BUDGET = 24_000;
 const MIN_TOKEN_LEN = 2;
 const FALLBACK_DTS_CHARS = 12_000;

package/dist/workers/pi-worker-core.d.ts

@@ -6,6 +6,10 @@ export interface RunWorkerInput {
     spawn?: SpawnFn;
     /** Comma-separated tool whitelist passed to `pi --tools`. Defaults to read,grep,find,ls. */
     tools?: string;
+    /** Extension entry-point paths to load via `-e <path>` before CHILD_BASE_ARGS. */
+    extensions?: string[];
+    /** Called for each tool execution start and text-writing event inside the worker. */
+    onLine?: (line: string) => void;
 }
 export interface RunWorkerResult {
     text: string;

package/dist/workers/pi-worker-core.js

@@ -12,7 +12,8 @@ import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../s
 const DEFAULT_TOOLS = 'read,grep,find,ls';
 export async function runWorker(input) {
     const tools = input.tools ?? DEFAULT_TOOLS;
-    const baseArgs = [...CHILD_BASE_ARGS, '--mode', 'json', '--tools', tools];
+    const extensionArgs = (input.extensions ?? []).flatMap(e => ['-e', e]);
+    const baseArgs = [...extensionArgs, ...CHILD_BASE_ARGS, '--mode', 'json', '--tools', tools];
     let hint = null;
     for (let attempt = 0;; attempt++) {
         const prompt = hint === null ? input.prompt : `${hint}\n\n${input.prompt}`;
@@ -23,7 +24,8 @@ export async function runWorker(input) {
         const result = await runChildDefault(invocation, input.cwd, input.signal, {
             mode: 'json-events',
             onFirstByte: () => (tFirstByte = Date.now()),
-            onToolCall: call => loopDetector.record(call)
+            onToolCall: call => loopDetector.record(call),
+            onLine: input.onLine
         }, input.spawn);
         const tEnd = Date.now();
         const waitMs = tFirstByte === null ? tEnd - tStart : tFirstByte - tStart;

package/dist/workers/pi-worker-docs.js

@@ -1,19 +1,22 @@
 import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
+import { openCache as defaultOpenCache } from './docs-cache.js';
+import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { docsRaw, formatResultText, buildPrompt } from './docs-core.js';
 import { formatNpmVersionSection } from './npm-version.js';
 import { runChild, CHILD_BASE_ARGS } from '../shared/child-process.js';
 import { parseChildOutput, isExcerptInContent } from '../shared/child-output.js';
 import { getPiInvocation } from '../shared/pi-invocation.js';
 import { textResult } from './shared.js';
+import { projectDocsRaw, buildProjectPrompt } from './docs-project.js';
 const CHILD_ARGS = [...CHILD_BASE_ARGS, '--no-tools'];
 const RENDER_QUERY_MAX = 100;
 const Params = Type.Object({
     module: Type.String({
-        description: 'Bare npm module name (e.g. "zod", "@scope/name", "react/jsx-runtime"). Must be installed in the project\'s node_modules.'
+        description: 'Bare npm module name (e.g. "zod", "@scope/name", "react/jsx-runtime"), OR "." to look up the current project\'s own source code. npm packages must be installed in node_modules.'
     }),
     query: Type.String({
-        description: 'What to extract from the module\'s docs. The child pi reads ranked chunks and returns ONLY content answering this.'
+        description: 'What to extract from the docs. The child pi reads ranked chunks and returns ONLY content answering this.'
     })
 });
 export function registerPiWorkerDocs(pi, internals = {}) {
@@ -35,11 +38,20 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             + '~/.cache/pi-worker/docs.sqlite, keyed by exact installed version; the '
             + 'registry lookup is best-effort and silently absent when offline.\n'
             + '\n'
+            + 'Pass module: "." to look up the CURRENT PROJECT\'S OWN SOURCE CODE instead '
+            + 'of an npm package. USE THIS when asked about what a function, class, type, '
+            + 'or module in this project does or exports — e.g. "what does orchestrator.ts '
+            + 'export?", "how does the requireAuth middleware work?", "what props does '
+            + 'ListingCard accept?". The project source is indexed from git-tracked .ts/.tsx '
+            + 'files and cached by max file mtime — always reflects the current state of '
+            + 'the working tree.\n'
+            + '\n'
             + 'Good fits:\n'
             + '- "What does library X export?" / "How does function Y work?"\n'
             + '- Confirming generic shapes, overload sets, exported types\n'
             + '- Pulling README configuration prose without burning context on raw markdown\n'
             + '- Checking the current latest published version of a package\n'
+            + '- "What does src/X.ts export?" / "How does this project\'s Y function work?"\n'
             + '\n'
             + 'Skip when:\n'
             + '- You need docs for a specific newer version than what is installed — use pi-worker-fetch on the upstream docs site',
@@ -50,6 +62,65 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 ?? (globalThis.Bun !== undefined ?
                     globalThis.Bun.spawn
                     : (await import('node:child_process')).spawn);
+            // ── Project source lookup ───────────────────────────────────────
+            if (params.module === '.') {
+                const openCache = internals.openCache ?? defaultOpenCache;
+                let cache;
+                let cacheError;
+                try {
+                    cache = openCache();
+                }
+                catch (err) {
+                    cacheError = err instanceof Error ? err.message : String(err);
+                }
+                if (!cache) {
+                    return textResult(`Project docs unavailable: cache open failed (${cacheError}).`, {});
+                }
+                const retrieveChunks = internals.retrieveChunks ?? defaultRetrieveChunks;
+                const projectResult = projectDocsRaw(cache, ctx.cwd, params.query, retrieveChunks);
+                if (projectResult.kind === 'error') {
+                    return textResult(`Project docs error: ${projectResult.message}`, {});
+                }
+                if (projectResult.kind === 'no_chunks') {
+                    return textResult(`Project "${projectResult.projectName}" has no .ts/.tsx files indexed.`, { hitCache: projectResult.hitCache, indexedFiles: projectResult.filesIngested });
+                }
+                const { projectName, chunks, hitCache, filesIngested, indexingMs } = projectResult;
+                const baseDetails = {
+                    hitCache,
+                    chunksRetrieved: chunks.length,
+                    indexedFiles: filesIngested,
+                    indexingMs
+                };
+                const concatenated = chunks.map(c => c.content).join('\n\n');
+                const prompt = buildProjectPrompt(projectName, params.query, concatenated);
+                const invocation = getPiInvocation([...CHILD_ARGS, prompt]);
+                const child = await runChild(spawn, invocation, ctx.cwd, signal);
+                if (child.aborted) {
+                    return textResult('Project docs lookup aborted.', {
+                        ...baseDetails,
+                        aborted: true,
+                        childExitCode: child.exitCode
+                    });
+                }
+                if (child.exitCode !== 0) {
+                    const tail = child.stderr.trim().slice(-500) || '(no stderr)';
+                    return textResult(`Worker exited ${child.exitCode}.\n${tail}`, {
+                        ...baseDetails,
+                        childExitCode: child.exitCode
+                    });
+                }
+                const parsed = parseChildOutput(child.stdout);
+                const verified = parsed.excerpt ?
+                    isExcerptInContent(parsed.excerpt, concatenated)
+                    : undefined;
+                const text = formatResultText({ name: projectName, version: 'local', root: ctx.cwd, entryDts: null, readme: null }, parsed, verified);
+                return textResult(text, {
+                    ...baseDetails,
+                    childExitCode: 0,
+                    excerptVerified: verified
+                });
+            }
+            // ── npm package lookup (existing path) ──────────────────────────
             const rawResult = await docsRaw({
                 pkg: params.module,
                 query: params.query,
@@ -137,8 +208,9 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         renderCall(args, theme) {
             const query = args.query.replace(/\s+/g, ' ').trim();
             const truncated = query.length > RENDER_QUERY_MAX ? `${query.slice(0, RENDER_QUERY_MAX - 1)}…` : query;
+            const label = args.module === '.' ? 'project' : args.module;
             let text = theme.fg('toolTitle', theme.bold('pi-worker-docs '));
-            text += theme.fg('accent', args.module);
+            text += theme.fg('accent', label);
             text += `\n${theme.fg('dim', `  query: ${truncated}`)}`;
             return new Text(text, 0, 0);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.10.2",
+    "version": "0.11.0",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",