@oh-my-pi/pi-coding-agent 12.13.0 → 12.14.1

package/CHANGELOG.md

@@ -2,7 +2,51 @@
 
 ## [Unreleased]
 
+## [12.14.1] - 2026-02-19
+
+### Fixed
+
+- Fixed `omp stats` failing on npm/bun installs by including required stats build files in published `@oh-my-pi/omp-stats` package ([#113](https://github.com/can1357/oh-my-pi/pull/113) by [@masonc15](https://github.com/masonc15))
+
+## [12.14.0] - 2026-02-19
+
+### Added
+
+- Support for `docs://` internal URL protocol to access embedded documentation files (e.g., `docs://sdk.md`)
+- Added `generate-docs-index` npm script to automatically index and embed documentation files at build time
+- Support for executable tool files (.ts, .js, .sh, .bash, .py) in custom tools discovery alongside markdown files
+- Display streamed tool intent in working message during agent execution
+- Added `tools.intentTracing` setting to enable intent tracing, which asks the agent to describe the intent of each tool call before executing it
+- Support for file deletion in hashline edit mode via `delete: true` parameter
+- Support for file renaming/moving in hashline edit mode via `rename` parameter
+- Optional content-replace edit variant in hashline mode (enabled via `PI_HL_REPLACETXT=1` environment variable)
+- Support for grepping internal URLs (artifact://) by resolving them to their backing files
+
+### Changed
+
+- System prompt now identifies agent as operating inside Oh My Pi harness and instructs reading docs:// URLs for omp/pi topics
+- Tool discovery now accepts executable script extensions (.ts, .js, .sh, .bash, .py) in addition to .json and .md files
+- Updated bash and read tool documentation to reference `docs://` URL support
+- Hashline format separator changed from pipe (`|`) to colon (`:`) for improved readability (e.g., `LINE#ID:content` instead of `LINE#ID|content`)
+- Hashline hash representation changed from 4-character base36 to 2-character hexadecimal for more compact line references
+- Hashline edit API: renamed `delete` parameter to `rm` for consistency with standard file operations
+- Hashline edit API: renamed `rename` parameter to `mv` for consistency with standard file operations
+- Hashline edit API: content-replace operations now require explicit `op: "replaceText"` field to distinguish from other edit types
+- Hashline documentation terminology updated: references to 'anchors' replaced with 'tags' for clearer semantics
+- Intent tracing now uses `_intent` field name in tool schemas
+- Hashline edit API: renamed `set` operation to `target`/`new_content` for clearer semantics
+- Hashline edit API: renamed `set_range` operation to `first`/`last`/`new_content`
+- Hashline edit API: renamed `insert` operation fields from `body` to `inserted_lines` and made `inserted_lines` required non-empty
+- Hashline edit API: flattened `replace` operation to top-level fields (`old_text`, `new_text`, `all`) when enabled
+- Hashline edit validation now provides more specific error messages indicating which variant is expected
+
+### Fixed
+
+- Grep tool now properly handles internal URL resolution when searching artifact paths
+- Working message intent updates now fall back to tool execution events when streamed tool arguments omit the intent field
+
 ## [12.13.0] - 2026-02-19
+
 ### Breaking Changes
 
 - Removed automatic line relocation when hash references become stale; edits with mismatched line hashes now fail with an error instead of silently relocating to matching lines elsewhere in the file
@@ -171,6 +215,7 @@
 - Refactored session directory naming to use single-dash format for home-relative paths and double-dash format for absolute paths, with automatic migration of legacy session directories on first access
 
 ## [12.8.2] - 2026-02-17
+
 ### Changed
 
 - Changed system environment context to use built-in `os` values for distro, kernel, and CPU model instead of native system-info data
@@ -183,11 +228,14 @@
 ## [12.8.0] - 2026-02-16
 
 ### Changed
+
 - Improved `/changelog` performance by displaying only the most recent 3 versions by default, with a `--full` flag for the complete history ([#85](https://github.com/can1357/oh-my-pi/pull/85) by [@tctev](https://github.com/tctev))
 - Centralized builtin slash command definitions and handlers into a shared registry, replacing the large input-controller if-chain dispatch
 
 ## [12.7.0] - 2026-02-16
+
 ### Added
+
 - Added abort signal support to LSP file operations (`ensureFileOpen`, `refreshFile`) for cancellable file synchronization
 - Added abort signal propagation through LSP request handlers (definition, references, hover, symbols, rename) enabling operation cancellation
 - Added `shouldBypassAutocompleteOnEscape` callback to custom editor for context-aware escape key handling during active operations
@@ -202,7 +250,9 @@
 - Added secret obfuscation: env vars matching secret patterns and `secrets.json` entries are replaced with placeholders before sending to LLM providers, deobfuscated in tool call arguments
 - Added `secrets.enabled` setting to toggle secret obfuscation
 - Added full regex literal support for `secrets.json` entries (`"/pattern/flags"` syntax with escaped `/` handling, automatic `g` flag enforcement)
+
 ### Changed
+
 - Changed context promotion to trigger on context overflow instead of a configurable threshold, promoting to a larger model before attempting compaction
 - Changed context promotion behavior to retry immediately on the promoted model without compacting, providing faster recovery from context limits
 - Changed default grep context lines from 1 before/3 after to 0 before/0 after for more focused search results
@@ -217,20 +267,25 @@
 - Updated web search provider priority order to include Brave (Exa → Brave → Jina → Perplexity → Anthropic → Gemini → Codex → Z.AI)
 - Extended recency filter support to Brave provider alongside Perplexity
 - Changed GitHub issue comment fetching to use paginated API requests with 100 comments per page instead of single request with 50-comment limit
+
 ### Removed
 
 - Removed `contextPromotion.thresholdPercent` setting as context promotion now triggers only on overflow
 
 ### Fixed
+
 - Fixed LSP operations to properly respect abort signals and throw `ToolAbortError` when cancelled
 - Fixed workspace diagnostics process cleanup to remove abort event listeners in finally block
 - Fixed PTY-backed bash execution to enforce timeout completion when detached child processes keep the PTY stream open ([#88](https://github.com/can1357/oh-my-pi/issues/88))
+
 ## [12.5.1] - 2026-02-15
+
 ### Added
 
 - Added `repeatToolDescriptions` setting to render full tool descriptions in the system prompt instead of a tool name list
 
 ## [12.5.0] - 2026-02-15
+
 ### Breaking Changes
 
 - Replaced `theme` setting with `theme.dark` and `theme.light` (auto-migrated)
@@ -281,6 +336,7 @@
 - Sanitized debug log display to strip control codes, normalize tabs, and trim width
 
 ## [12.4.0] - 2026-02-14
+
 ### Changed
 
 - Moved `sanitizeText` function from `@oh-my-pi/pi-utils` to `@oh-my-pi/pi-natives` for better code organization
@@ -296,6 +352,7 @@
 - Fixed Cloudflare returning corrupted bytes when compression is negotiated in web scraper requests
 
 ## [12.3.0] - 2026-02-14
+
 ### Added
 
 - Added autonomous memory extraction and consolidation system with configurable settings
@@ -341,6 +398,7 @@
 - Fixed fetch tool to preserve actual response metadata (finalUrl, contentType) instead of defaults when requests fail
 
 ||||||| parent of a70a34c8b (fix(coding-agent/debug): Sanitized debug log rendering)
+
 ## [12.1.0] - 2026-02-13
 
 ### Added
@@ -392,6 +450,7 @@
 - Removed @types/jsdom dependency
 
 ## [11.14.1] - 2026-02-12
+
 ### Changed
 
 - Improved Bun binary detection to check `Bun.env.PI_COMPILED` environment variable
@@ -403,6 +462,7 @@
 - Fixed Bun update process to properly handle version pinning and report installation mismatches
 
 ## [11.14.0] - 2026-02-12
+
 ### Added
 
 - Added SwiftLint linter client with JSON reporter support for Swift file linting
@@ -455,6 +515,7 @@
 - Refactored browser/file opening across multiple modules to use unified `openPath` utility for improved maintainability
 
 ## [11.12.0] - 2026-02-11
+
 ### Added
 
 - Added `resolveFileDisplayMode` utility to centralize file display mode resolution across tools (read, grep, file mentions)
@@ -543,6 +604,7 @@
 - Refactored hash line formatting to use async `streamHashLinesFromLines` for better performance
 
 ## [11.10.3] - 2026-02-10
+
 ### Added
 
 - Exported `./patch/*` subpath for direct access to patch utilities
@@ -568,6 +630,7 @@
 - Removed AggregateError unwrapping from console.warn in CLI initialization
 
 ## [11.10.1] - 2026-02-10
+
 ### Changed
 
 - Migrated CLI framework from oclif to lightweight pi-utils CLI runner
@@ -582,6 +645,7 @@
 - Removed custom oclif help renderer (oclif-help.ts)
 
 ## [11.10.0] - 2026-02-10
+
 ### Breaking Changes
 
 - Changed `HashlineEdit.src` from string format (e.g., `"5:ab"`, `"5:ab..9:ef"`) to structured `SrcSpec` object with discriminated union types (`{ kind: "single", ref: "..." }`, `{ kind: "range", start: "...", end: "..." }`, etc.)
@@ -732,6 +796,7 @@
 - Improved bash tool output draining after foreground completion to reduce tail output truncation
 
 ## [11.8.0] - 2026-02-10
+
 ### Added
 
 - Added `ctx.reload()` method to extension command context to reload extensions, skills, prompts, and themes from disk
@@ -754,6 +819,7 @@
 - Fixed archive extraction error handling to provide clear error messages on failure
 
 ## [11.7.0] - 2026-02-07
+
 ### Changed
 
 - Enhanced error messages for failed Python cells to include full combined output context instead of just the error message
@@ -765,6 +831,7 @@
 - Fixed tab character rendering in Python tool output display to properly format whitespace in cell output and status events
 
 ## [11.6.1] - 2026-02-07
+
 ### Fixed
 
 - Fixed potential crash when rendering results with undefined details.results
@@ -813,6 +880,7 @@
 - Removed ability to save screenshots to custom paths or artifacts directory
 
 ## [11.4.1] - 2026-02-06
+
 ### Fixed
 
 - Fixed tab character display in error messages and bash tool output by properly replacing tabs with spaces
@@ -4786,4 +4854,4 @@ Initial public release.
 - Git branch display in footer
 - Message queueing during streaming responses
 - OAuth integration for Gmail and Google Calendar access
-- HTML export with syntax highlighting and collapsible sections
+- HTML export with syntax highlighting and collapsible sections

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "12.13.0",
+	"version": "12.14.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"bin": {
@@ -78,18 +78,19 @@
 	"scripts": {
 		"check": "tsgo -p tsconfig.json",
 		"format-prompts": "bun scripts/format-prompts.ts",
+		"generate-docs-index": "bun scripts/generate-docs-index.ts",
 		"build:binary": "cd ../.. && bun --cwd=packages/stats scripts/generate-client-bundle.ts && bun --cwd=packages/natives run embed:native && bun build --compile --define PI_COMPILED=true --root . ./packages/coding-agent/src/cli.ts --outfile packages/coding-agent/dist/omp && bun --cwd=packages/natives run embed:native --reset && bun --cwd=packages/stats scripts/generate-client-bundle.ts --reset",
 		"generate-template": "bun scripts/generate-template.ts",
 		"test": "bun test"
 	},
 	"dependencies": {
 		"@mozilla/readability": "0.6.0",
-		"@oh-my-pi/omp-stats": "12.13.0",
-		"@oh-my-pi/pi-agent-core": "12.13.0",
-		"@oh-my-pi/pi-ai": "12.13.0",
-		"@oh-my-pi/pi-natives": "12.13.0",
-		"@oh-my-pi/pi-tui": "12.13.0",
-		"@oh-my-pi/pi-utils": "12.13.0",
+		"@oh-my-pi/omp-stats": "12.14.1",
+		"@oh-my-pi/pi-agent-core": "12.14.1",
+		"@oh-my-pi/pi-ai": "12.14.1",
+		"@oh-my-pi/pi-natives": "12.14.1",
+		"@oh-my-pi/pi-tui": "12.14.1",
+		"@oh-my-pi/pi-utils": "12.14.1",
 		"@sinclair/typebox": "^0.34.48",
 		"@xterm/headless": "^6.0.0",
 		"ajv": "^8.18.0",

package/scripts/generate-docs-index.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+
+import { Glob } from "bun";
+import * as path from "node:path";
+
+const docsDir = new URL("../../../docs/", import.meta.url).pathname;
+const outputPath = new URL("../src/internal-urls/docs-index.generated.ts", import.meta.url).pathname;
+const importBase = "../../../../docs";
+
+function toIdentifier(relativePath: string): string {
+	const withoutExt = relativePath.replace(/\.md$/i, "");
+	const parts = withoutExt
+		.split(/[^a-zA-Z0-9]+/)
+		.filter(Boolean)
+		.map((part, index) => {
+			if (index === 0) {
+				return part.toLowerCase();
+			}
+			return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase();
+		});
+
+	const base = parts.length > 0 ? parts.join("") : "doc";
+	const safeBase = /^[0-9]/.test(base) ? `doc${base}` : base;
+	return `${safeBase}Md`;
+}
+
+const glob = new Glob("**/*.md");
+const entries: string[] = [];
+for await (const relativePath of glob.scan(docsDir)) {
+	entries.push(relativePath.split(path.sep).join("/"));
+}
+entries.sort();
+
+const usedIdentifiers = new Set<string>();
+const docs = entries.map((relativePath) => {
+	let identifier = toIdentifier(relativePath);
+	let suffix = 2;
+	while (usedIdentifiers.has(identifier)) {
+		identifier = `${toIdentifier(relativePath)}${suffix}`;
+		suffix++;
+	}
+	usedIdentifiers.add(identifier);
+	return { relativePath, identifier };
+});
+docs.sort((a, b) => a.identifier.localeCompare(b.identifier) || a.relativePath.localeCompare(b.relativePath));
+
+const imports = docs
+	.map(({ relativePath, identifier }) => `import ${identifier} from "${importBase}/${relativePath}" with { type: "text" };`)
+	.join("\n");
+
+const mapEntries = docs.map(({ relativePath, identifier }) => `\t"${relativePath}": ${identifier},`).join("\n");
+
+const output = `// Auto-generated by scripts/generate-docs-index.ts - DO NOT EDIT\n\n${imports}\n\nexport const EMBEDDED_DOCS: Readonly<Record<string, string>> = {\n${mapEntries}\n};\n\nexport const EMBEDDED_DOC_FILENAMES = Object.keys(EMBEDDED_DOCS).sort();\n`;
+
+await Bun.write(outputPath, output);
+console.log(`Generated ${path.relative(process.cwd(), outputPath)} (${docs.length} docs)`);

package/src/config/prompt-templates.ts

@@ -247,11 +247,11 @@ handlebars.registerHelper("hlineref", (lineNum: unknown, content: unknown): stri
 
 /**
  * {{hlinefull lineNum "content"}} — format a full read-style line with prefix.
- * Returns `"lineNum#hash|content"`.
+ * Returns `"lineNum#hash:content"`.
  */
 handlebars.registerHelper("hlinefull", (lineNum: unknown, content: unknown): string => {
 	const { ref, text } = formatHashlineRef(lineNum, content);
-	return `${ref}|${text}`;
+	return `${ref}:${text}`;
 });
 
 export function renderPromptTemplate(template: string, context: TemplateContext = {}): string {

package/src/config/settings-schema.ts

@@ -287,7 +287,7 @@ export const SETTINGS_SCHEMA = {
 		ui: {
 			tab: "config",
 			label: "Read hash lines",
-			description: "Include line hashes in read output for hashline edit mode (LINE#ID|content)",
+			description: "Include line hashes in read output for hashline edit mode (LINE#ID:content)",
 		},
 	},
 	showHardwareCursor: {
@@ -502,6 +502,15 @@ export const SETTINGS_SCHEMA = {
 			description: "Launch browser in headless mode (disable to show browser UI)",
 		},
 	},
+	"tools.intentTracing": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tools",
+			label: "Intent tracing",
+			description: "Ask the agent to describe the intent of each tool call before executing it",
+		},
+	},
 
 	// ─────────────────────────────────────────────────────────────────────────
 	// Task tool settings

package/src/discovery/builtin.ts

@@ -656,7 +656,7 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 
 		fileLoadPromises.push(
 			loadFilesFromDir<CustomTool>(ctx, toolsDir, PROVIDER_ID, level, {
-				extensions: ["json", "md"],
+				extensions: ["json", "md", "ts", "js", "sh", "bash", "py"],
 				transform: (name, content, path, source) => {
 					if (name.endsWith(".json")) {
 						const data = parseJSON<{ name?: string; description?: string }>(content);
@@ -668,11 +668,21 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 							_source: source,
 						};
 					}
-					const { frontmatter } = parseFrontmatter(content, { source: path });
+					if (name.endsWith(".md")) {
+						const { frontmatter } = parseFrontmatter(content, { source: path });
+						return {
+							name: (frontmatter.name as string) || name.replace(/\.md$/, ""),
+							path,
+							description: frontmatter.description as string | undefined,
+							level,
+							_source: source,
+						};
+					}
+					// Executable tool files (.ts, .js, .sh, .bash, .py)
+					const toolName = name.replace(/\.(ts|js|sh|bash|py)$/, "");
 					return {
-						name: (frontmatter.name as string) || name.replace(/\.md$/, ""),
+						name: toolName,
 						path,
-						description: frontmatter.description as string | undefined,
 						level,
 						_source: source,
 					};

package/src/extensibility/extensions/types.ts

@@ -503,6 +503,7 @@ export interface ToolExecutionStartEvent {
 	toolCallId: string;
 	toolName: string;
 	args: unknown;
+	intent?: string;
 }
 
 /** Fired during tool execution with partial/streaming output */

package/src/internal-urls/docs-index.generated.ts

@@ -0,0 +1,101 @@
+// Auto-generated by scripts/generate-docs-index.ts - DO NOT EDIT
+
+import bashToolRuntimeMd from "../../../../docs/bash-tool-runtime.md" with { type: "text" };
+import blobArtifactArchitectureMd from "../../../../docs/blob-artifact-architecture.md" with { type: "text" };
+import compactionMd from "../../../../docs/compaction.md" with { type: "text" };
+import configUsageMd from "../../../../docs/config-usage.md" with { type: "text" };
+import customToolsMd from "../../../../docs/custom-tools.md" with { type: "text" };
+import environmentVariablesMd from "../../../../docs/environment-variables.md" with { type: "text" };
+import extensionLoadingMd from "../../../../docs/extension-loading.md" with { type: "text" };
+import extensionsMd from "../../../../docs/extensions.md" with { type: "text" };
+import fsScanCacheArchitectureMd from "../../../../docs/fs-scan-cache-architecture.md" with { type: "text" };
+import geminiManifestExtensionsMd from "../../../../docs/gemini-manifest-extensions.md" with { type: "text" };
+import handoffGenerationPipelineMd from "../../../../docs/handoff-generation-pipeline.md" with { type: "text" };
+import hooksMd from "../../../../docs/hooks.md" with { type: "text" };
+import mcpProtocolTransportsMd from "../../../../docs/mcp-protocol-transports.md" with { type: "text" };
+import mcpRuntimeLifecycleMd from "../../../../docs/mcp-runtime-lifecycle.md" with { type: "text" };
+import mcpServerToolAuthoringMd from "../../../../docs/mcp-server-tool-authoring.md" with { type: "text" };
+import modelsMd from "../../../../docs/models.md" with { type: "text" };
+import nativesAddonLoaderRuntimeMd from "../../../../docs/natives-addon-loader-runtime.md" with { type: "text" };
+import nativesArchitectureMd from "../../../../docs/natives-architecture.md" with { type: "text" };
+import nativesBindingContractMd from "../../../../docs/natives-binding-contract.md" with { type: "text" };
+import nativesBuildReleaseDebuggingMd from "../../../../docs/natives-build-release-debugging.md" with { type: "text" };
+import nativesMediaSystemUtilsMd from "../../../../docs/natives-media-system-utils.md" with { type: "text" };
+import nativesRustTaskCancellationMd from "../../../../docs/natives-rust-task-cancellation.md" with { type: "text" };
+import nativesShellPtyProcessMd from "../../../../docs/natives-shell-pty-process.md" with { type: "text" };
+import nativesTextSearchPipelineMd from "../../../../docs/natives-text-search-pipeline.md" with { type: "text" };
+import nonCompactionRetryPolicyMd from "../../../../docs/non-compaction-retry-policy.md" with { type: "text" };
+import notebookToolRuntimeMd from "../../../../docs/notebook-tool-runtime.md" with { type: "text" };
+import pluginManagerInstallerPlumbingMd from "../../../../docs/plugin-manager-installer-plumbing.md" with { type: "text" };
+import portingFromPiMonoMd from "../../../../docs/porting-from-pi-mono.md" with { type: "text" };
+import portingToNativesMd from "../../../../docs/porting-to-natives.md" with { type: "text" };
+import providerStreamingInternalsMd from "../../../../docs/provider-streaming-internals.md" with { type: "text" };
+import pythonReplMd from "../../../../docs/python-repl.md" with { type: "text" };
+import rpcMd from "../../../../docs/rpc.md" with { type: "text" };
+import rulebookMatchingPipelineMd from "../../../../docs/rulebook-matching-pipeline.md" with { type: "text" };
+import sdkMd from "../../../../docs/sdk.md" with { type: "text" };
+import secretsMd from "../../../../docs/secrets.md" with { type: "text" };
+import sessionMd from "../../../../docs/session.md" with { type: "text" };
+import sessionOperationsExportShareForkResumeMd from "../../../../docs/session-operations-export-share-fork-resume.md" with { type: "text" };
+import sessionSwitchingAndRecentListingMd from "../../../../docs/session-switching-and-recent-listing.md" with { type: "text" };
+import sessionTreePlanMd from "../../../../docs/session-tree-plan.md" with { type: "text" };
+import skillsMd from "../../../../docs/skills.md" with { type: "text" };
+import slashCommandInternalsMd from "../../../../docs/slash-command-internals.md" with { type: "text" };
+import taskAgentDiscoveryMd from "../../../../docs/task-agent-discovery.md" with { type: "text" };
+import themeMd from "../../../../docs/theme.md" with { type: "text" };
+import treeMd from "../../../../docs/tree.md" with { type: "text" };
+import ttsrInjectionLifecycleMd from "../../../../docs/ttsr-injection-lifecycle.md" with { type: "text" };
+import tuiMd from "../../../../docs/tui.md" with { type: "text" };
+import tuiRuntimeInternalsMd from "../../../../docs/tui-runtime-internals.md" with { type: "text" };
+
+export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
+	"bash-tool-runtime.md": bashToolRuntimeMd,
+	"blob-artifact-architecture.md": blobArtifactArchitectureMd,
+	"compaction.md": compactionMd,
+	"config-usage.md": configUsageMd,
+	"custom-tools.md": customToolsMd,
+	"environment-variables.md": environmentVariablesMd,
+	"extension-loading.md": extensionLoadingMd,
+	"extensions.md": extensionsMd,
+	"fs-scan-cache-architecture.md": fsScanCacheArchitectureMd,
+	"gemini-manifest-extensions.md": geminiManifestExtensionsMd,
+	"handoff-generation-pipeline.md": handoffGenerationPipelineMd,
+	"hooks.md": hooksMd,
+	"mcp-protocol-transports.md": mcpProtocolTransportsMd,
+	"mcp-runtime-lifecycle.md": mcpRuntimeLifecycleMd,
+	"mcp-server-tool-authoring.md": mcpServerToolAuthoringMd,
+	"models.md": modelsMd,
+	"natives-addon-loader-runtime.md": nativesAddonLoaderRuntimeMd,
+	"natives-architecture.md": nativesArchitectureMd,
+	"natives-binding-contract.md": nativesBindingContractMd,
+	"natives-build-release-debugging.md": nativesBuildReleaseDebuggingMd,
+	"natives-media-system-utils.md": nativesMediaSystemUtilsMd,
+	"natives-rust-task-cancellation.md": nativesRustTaskCancellationMd,
+	"natives-shell-pty-process.md": nativesShellPtyProcessMd,
+	"natives-text-search-pipeline.md": nativesTextSearchPipelineMd,
+	"non-compaction-retry-policy.md": nonCompactionRetryPolicyMd,
+	"notebook-tool-runtime.md": notebookToolRuntimeMd,
+	"plugin-manager-installer-plumbing.md": pluginManagerInstallerPlumbingMd,
+	"porting-from-pi-mono.md": portingFromPiMonoMd,
+	"porting-to-natives.md": portingToNativesMd,
+	"provider-streaming-internals.md": providerStreamingInternalsMd,
+	"python-repl.md": pythonReplMd,
+	"rpc.md": rpcMd,
+	"rulebook-matching-pipeline.md": rulebookMatchingPipelineMd,
+	"sdk.md": sdkMd,
+	"secrets.md": secretsMd,
+	"session.md": sessionMd,
+	"session-operations-export-share-fork-resume.md": sessionOperationsExportShareForkResumeMd,
+	"session-switching-and-recent-listing.md": sessionSwitchingAndRecentListingMd,
+	"session-tree-plan.md": sessionTreePlanMd,
+	"skills.md": skillsMd,
+	"slash-command-internals.md": slashCommandInternalsMd,
+	"task-agent-discovery.md": taskAgentDiscoveryMd,
+	"theme.md": themeMd,
+	"tree.md": treeMd,
+	"ttsr-injection-lifecycle.md": ttsrInjectionLifecycleMd,
+	"tui.md": tuiMd,
+	"tui-runtime-internals.md": tuiRuntimeInternalsMd,
+};
+
+export const EMBEDDED_DOC_FILENAMES = Object.keys(EMBEDDED_DOCS).sort();

package/src/internal-urls/docs-protocol.ts

@@ -0,0 +1,84 @@
+/**
+ * Protocol handler for docs:// URLs.
+ *
+ * Serves statically embedded documentation files bundled at build time.
+ *
+ * URL forms:
+ * - docs:// - Lists all available documentation files
+ * - docs://<file>.md - Reads a specific documentation file
+ */
+import * as path from "node:path";
+import { EMBEDDED_DOC_FILENAMES, EMBEDDED_DOCS } from "./docs-index.generated";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+/**
+ * Handler for docs:// URLs.
+ *
+ * Resolves documentation file names to their content, or lists available docs.
+ */
+export class DocsProtocolHandler implements ProtocolHandler {
+	readonly scheme = "docs";
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		// Extract filename from host + path
+		const host = url.rawHost || url.hostname;
+		const pathname = url.rawPathname ?? url.pathname;
+		const filename = host ? (pathname && pathname !== "/" ? host + pathname : host) : "";
+
+		if (!filename) {
+			return this.#listDocs(url);
+		}
+
+		return this.#readDoc(filename, url);
+	}
+
+	async #listDocs(url: InternalUrl): Promise<InternalResource> {
+		if (EMBEDDED_DOC_FILENAMES.length === 0) {
+			throw new Error("No documentation files found");
+		}
+
+		const listing = EMBEDDED_DOC_FILENAMES.map(f => `- [${f}](docs://${f})`).join("\n");
+		const content = `# Documentation\n\n${EMBEDDED_DOC_FILENAMES.length} files available:\n\n${listing}\n`;
+
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: "docs://",
+		};
+	}
+
+	async #readDoc(filename: string, url: InternalUrl): Promise<InternalResource> {
+		// Validate: no traversal, no absolute paths
+		if (path.isAbsolute(filename)) {
+			throw new Error("Absolute paths are not allowed in docs:// URLs");
+		}
+
+		const normalized = path.posix.normalize(filename.replaceAll("\\", "/"));
+		if (normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+			throw new Error("Path traversal (..) is not allowed in docs:// URLs");
+		}
+
+		const content = EMBEDDED_DOCS[normalized];
+		if (content === undefined) {
+			const lookup = normalized.replace(/\.md$/, "");
+			const suggestions = EMBEDDED_DOC_FILENAMES.filter(
+				f => f.includes(lookup) || lookup.includes(f.replace(/\.md$/, "")),
+			).slice(0, 5);
+			const suffix =
+				suggestions.length > 0
+					? `\nDid you mean: ${suggestions.join(", ")}`
+					: "\nUse docs:// to list available files.";
+			throw new Error(`Documentation file not found: ${filename}${suffix}`);
+		}
+
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: `docs://${normalized}`,
+		};
+	}
+}

package/src/internal-urls/index.ts

@@ -22,6 +22,7 @@
 
 export { AgentProtocolHandler, type AgentProtocolOptions } from "./agent-protocol";
 export { ArtifactProtocolHandler, type ArtifactProtocolOptions } from "./artifact-protocol";
+export { DocsProtocolHandler } from "./docs-protocol";
 export { applyQuery, parseQuery, pathToQuery } from "./json-query";
 export { MemoryProtocolHandler, type MemoryProtocolOptions, resolveMemoryUrlToPath } from "./memory-protocol";
 export { PlanProtocolHandler, type PlanProtocolOptions, resolvePlanUrlToPath } from "./plan-protocol";

package/src/internal-urls/router.ts

@@ -1,5 +1,5 @@
 /**
- * Internal URL router for internal protocols (agent://, artifact://, plan://, memory://, skill://, rule://).
+ * Internal URL router for internal protocols (agent://, artifact://, plan://, memory://, skill://, rule://, docs://).
  */
 import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
 

package/src/modes/controllers/event-controller.ts

@@ -1,3 +1,4 @@
+import { INTENT_FIELD } from "@oh-my-pi/pi-agent-core";
 import { Loader, TERMINAL, Text } from "@oh-my-pi/pi-tui";
 import { settings } from "../../config/settings";
 import { AssistantMessageComponent } from "../../modes/components/assistant-message";
@@ -14,6 +15,7 @@ export class EventController {
 	#lastReadGroup: ReadToolGroupComponent | undefined = undefined;
 	#lastThinkingCount = 0;
 	#renderedCustomMessages = new Set<string>();
+	#lastIntent: string | undefined = undefined;
 
 	constructor(private ctx: InteractiveModeContext) {}
 
@@ -32,6 +34,13 @@ export class EventController {
 		return this.#lastReadGroup;
 	}
 
+	#updateWorkingMessageFromIntent(intent: string | undefined): void {
+		const trimmed = intent?.trim();
+		if (!trimmed || trimmed === this.#lastIntent) return;
+		this.#lastIntent = trimmed;
+		this.ctx.setWorkingMessage(`${trimmed} (esc to interrupt)`);
+	}
+
 	subscribeToAgent(): void {
 		this.ctx.unsubscribe = this.ctx.session.subscribe(async (event: AgentSessionEvent) => {
 			await this.handleEvent(event);
@@ -48,6 +57,7 @@ export class EventController {
 
 		switch (event.type) {
 			case "agent_start":
+				this.#lastIntent = undefined;
 				if (this.ctx.retryEscapeHandler) {
 					this.ctx.editor.onEscape = this.ctx.retryEscapeHandler;
 					this.ctx.retryEscapeHandler = undefined;
@@ -155,6 +165,15 @@ export class EventController {
 							}
 						}
 					}
+
+					// Update working message with intent from streamed tool arguments
+					for (const content of this.ctx.streamingMessage.content) {
+						if (content.type !== "toolCall") continue;
+						const args = content.arguments;
+						if (!args || typeof args !== "object" || !(INTENT_FIELD in args)) continue;
+						this.#updateWorkingMessageFromIntent(args[INTENT_FIELD] as string | undefined);
+					}
+
 					this.ctx.ui.requestRender();
 				}
 				break;
@@ -196,6 +215,7 @@ export class EventController {
 				break;
 
 			case "tool_execution_start": {
+				this.#updateWorkingMessageFromIntent(event.intent);
 				if (!this.ctx.pendingTools.has(event.toolCallId)) {
 					if (event.toolName === "read") {
 						const group = this.#getReadGroup();

package/src/modes/interactive-mode.ts

@@ -200,7 +200,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.ui.requestRender(true);
 		};
 		this.editor.onAutocompleteUpdate = () => {
-			this.ui.requestRender(true);
+			this.ui.requestRender();
 		};
 		this.#syncEditorMaxHeight();
 		this.#resizeHandler = () => {