@oh-my-pi/pi-coding-agent 13.19.0 → 14.0.2

package/src/modes/theme/theme.ts

@@ -4,10 +4,10 @@ import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Effort } from "@oh-my-pi/pi-ai";
 import {
 	detectMacOSAppearance,
+	MacAppearanceObserver,
 	type HighlightColors as NativeHighlightColors,
 	highlightCode as nativeHighlightCode,
 	supportsLanguage as nativeSupportsLanguage,
-	startMacAppearanceObserver as startNativeMacObserver,
 } from "@oh-my-pi/pi-natives";
 import type { EditorTheme, MarkdownTheme, SelectListTheme, SymbolTheme } from "@oh-my-pi/pi-tui";
 import { adjustHsv, getCustomThemesDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
@@ -1148,9 +1148,14 @@ const langMap: Record<string, SymbolKey> = {
 	sh: "lang.shell",
 	zsh: "lang.shell",
 	fish: "lang.shell",
+	powershell: "lang.shell",
+	just: "lang.shell",
 	shell: "lang.shell",
 	html: "lang.html",
 	htm: "lang.html",
+	astro: "lang.html",
+	vue: "lang.html",
+	svelte: "lang.html",
 	css: "lang.css",
 	scss: "lang.css",
 	sass: "lang.css",
@@ -2057,10 +2062,12 @@ function startMacAppearanceObserver(): void {
 	stopMacAppearanceObserver();
 	if (!shouldUseMacOSAppearanceFallback()) return;
 	try {
-		macOSReportedAppearance = detectMacOSAppearance();
-		macObserver = startNativeMacObserver(appearance => {
-			macOSReportedAppearance = appearance;
-			reevaluateAutoTheme("macOS fallback");
+		macOSReportedAppearance = detectMacOSAppearance() ?? undefined;
+		macObserver = MacAppearanceObserver.start((err, appearance) => {
+			if (!err && (appearance === "dark" || appearance === "light")) {
+				macOSReportedAppearance = appearance;
+				reevaluateAutoTheme("macOS fallback");
+			}
 		});
 	} catch (err) {
 		logger.warn("Failed to start macOS appearance observer", { err });
@@ -2315,69 +2322,132 @@ export function getLanguageFromPath(filePath: string): string | undefined {
 	) {
 		return "conf";
 	}
+	if (baseName === "dockerfile" || baseName.startsWith("dockerfile.") || baseName === "containerfile") {
+		return "dockerfile";
+	}
+	if (baseName === "justfile") return "just";
+	if (baseName === "cmakelists.txt") return "cmake";
 
 	const ext = filePath.split(".").pop()?.toLowerCase();
 	if (!ext) return undefined;
 
 	const extToLang: Record<string, string> = {
 		ts: "typescript",
-		tsx: "typescript",
+		cts: "typescript",
+		mts: "typescript",
+		tsx: "tsx",
 		js: "javascript",
 		jsx: "javascript",
 		mjs: "javascript",
 		cjs: "javascript",
 		py: "python",
+		pyi: "python",
 		rb: "ruby",
+		rbw: "ruby",
+		gemspec: "ruby",
 		rs: "rust",
 		go: "go",
 		java: "java",
 		kt: "kotlin",
+		ktm: "kotlin",
+		kts: "kotlin",
 		swift: "swift",
 		c: "c",
 		h: "c",
 		cpp: "cpp",
 		cc: "cpp",
 		cxx: "cpp",
+		hh: "cpp",
 		hpp: "cpp",
+		cu: "cpp",
+		ino: "cpp",
 		cs: "csharp",
+		clj: "clojure",
+		cljc: "clojure",
+		cljs: "clojure",
+		edn: "clojure",
 		php: "php",
 		sh: "bash",
 		bash: "bash",
 		zsh: "bash",
+		ksh: "bash",
+		bats: "bash",
+		tmux: "bash",
+		cgi: "bash",
+		fcgi: "bash",
+		command: "bash",
+		tool: "bash",
 		fish: "fish",
 		ps1: "powershell",
+		psm1: "powershell",
 		sql: "sql",
 		html: "html",
 		htm: "html",
+		xhtml: "html",
+		astro: "astro",
+		vue: "vue",
+		svelte: "svelte",
 		css: "css",
 		scss: "scss",
 		sass: "sass",
 		less: "less",
 		json: "json",
+		ipynb: "ipynb",
+		hbs: "handlebars",
+		hsb: "handlebars",
+		handlebars: "handlebars",
 		yaml: "yaml",
 		yml: "yaml",
 		toml: "toml",
 		xml: "xml",
+		xsl: "xml",
+		xslt: "xml",
+		svg: "xml",
+		plist: "xml",
 		md: "markdown",
 		markdown: "markdown",
+		mdx: "markdown",
+		diff: "diff",
+		patch: "diff",
 		dockerfile: "dockerfile",
-		makefile: "makefile",
+		containerfile: "dockerfile",
+		makefile: "make",
+		justfile: "just",
+		mk: "make",
+		mak: "make",
 		cmake: "cmake",
 		lua: "lua",
+		jl: "julia",
+		pl: "perl",
+		pm: "perl",
 		perl: "perl",
 		r: "r",
 		scala: "scala",
-		clj: "clojure",
+		sc: "scala",
+		sbt: "scala",
 		ex: "elixir",
 		exs: "elixir",
 		erl: "erlang",
 		hs: "haskell",
+		nix: "nix",
+		odin: "odin",
+		zig: "zig",
+		star: "starlark",
+		bzl: "starlark",
+		sol: "solidity",
+		v: "verilog",
+		sv: "verilog",
+		svh: "verilog",
+		vh: "verilog",
+		m: "objc",
+		mm: "objc",
 		ml: "ocaml",
 		vim: "vim",
 		graphql: "graphql",
 		proto: "protobuf",
 		tf: "hcl",
 		hcl: "hcl",
+		tfvars: "hcl",
 		txt: "text",
 		text: "text",
 		log: "log",
@@ -2388,6 +2458,8 @@ export function getLanguageFromPath(filePath: string): string | undefined {
 		conf: "conf",
 		config: "conf",
 		properties: "conf",
+		tla: "tlaplus",
+		tlaplus: "tlaplus",
 		env: "env",
 	};
 

package/src/modes/types.ts

@@ -14,7 +14,7 @@ import type { MCPManager } from "../mcp";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
-import type { ExitPlanModeDetails } from "../tools";
+import type { ExitPlanModeDetails, LspStartupServerInfo } from "../tools";
 import type { AssistantMessageComponent } from "./components/assistant-message";
 import type { BashExecutionComponent } from "./components/bash-execution";
 import type { CustomEditor } from "./components/custom-editor";
@@ -76,7 +76,7 @@ export interface InteractiveModeContext {
 	agent: AgentSession["agent"];
 	historyStorage?: HistoryStorage;
 	mcpManager?: MCPManager;
-	lspServers?: Array<{ name: string; status: "ready" | "error"; fileTypes: string[]; error?: string }>;
+	lspServers?: LspStartupServerInfo[];
 
 	// State
 	isInitialized: boolean;

package/src/prompts/system/system-prompt.md

@@ -109,6 +109,7 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
 - `artifact://<id>` — Raw artifact content (truncated tool output)
 - `local://<TITLE>.md` — Finalized plan artifact created after `exit_plan_mode` approval
 - `jobs://<job-id>` — Specific job status and result
+- `mcp://<resource-uri>` — MCP resource from a connected server; matched against exact resource URIs first, then RFC 6570 URI templates advertised by connected servers
 - `pi://..` — Internal documentation files about Oh My Pi, you **MUST NOT** read them unless the user asks about omp/pi itself: its SDK, extensions, themes, skills, TUI, keybindings, or configuration
 
 In `bash`, URIs auto-resolve to filesystem paths (e.g., `python skill://my-skill/scripts/init.py`).
@@ -261,7 +262,7 @@ These are inviolable. Violation is system failure.
 - You **MUST NOT** suppress tests to make code pass. You **MUST NOT** fabricate outputs not observed.
 - You **MUST NOT** solve the wished-for problem instead of the actual problem.
 - You **MUST NOT** ask for information obtainable from tools, repo context, or files.
-- You **MUST** perform full CUTOVER when refactoring. Replace old usage, not write shims. No gradual migration. Let it error while you fix it.
+- You **MUST** always design a clean solution. You **MUST NOT** introduce unnecessary backwards compatibiltity layers, no shims, no gradual migration, no bridges to old code unless user explicitly asks for it. Let the errors guide you on what to include in the refactoring. **ALWAYS default to performing full CUTOVER!**
 
 # Design Integrity
 

package/src/prompts/tools/chunk-edit.md

@@ -0,0 +1,219 @@
+Edits files via syntax-aware chunks. Run `read(path="file.ts")` first. The edit selector is a chunk path, optionally qualified with a region.
+
+<rules>
+- **MUST** `read` first. Never invent chunk paths or CRCs. Copy them from the latest `read` output or edit response.
+- `sel` format:
+  - insertions: `chunk` or `chunk@region`
+  - replacements: `chunk#CRC` or `chunk#CRC@region`
+- Without a `@region` it defaults to the entire chunk including leading trivia. Valid regions: `head`, `body`, `tail`, `decl`.
+- If the exact chunk path is unclear, run `read(path="file", sel="?")` and copy a selector from that listing.
+- Use a single leading space per indent level in `content`. Write content at indent-level 0 — the tool re-indents it to match the chunk's position in the file. For example, to replace `@body` of a method, write the body starting at column 0:
+  ```
+  content: "if (x) {\n return true;\n}"
+  ```
+  The tool adds the correct base indent automatically. Never manually pad with the chunk's own indentation.
+- `@region` only works on container chunks (classes, functions, impl blocks, sections). Do **not** use `@head`/`@body`/`@tail` on leaf chunks (enum variants, fields, single statements) — use the whole chunk instead.
+- `replace` requires the current CRC. Insertions do not.
+- **CRCs change after every edit.** Always use the selectors/CRCs from the most recent `read` or edit response. Never reuse a CRC from a previous edit.
+</rules>
+
+<critical>
+You **MUST** use the narrowest region that covers your change. Replacing without a region replaces the **entire chunk including leading comments, decorators, and attributes** — omitting them from `content` deletes them.
+</critical>
+
+<regions>
+```
+  @head ··· ┊ /// doc comment
+          · ┊ #[attr]
+  @decl ··· ┊ fn foo(x: i32) {
+   @body ·· ┊     body();
+   @tail ·· ┊ }
+```
+- `@body` — the interior only. **Use for most edits.**
+- `@head` — leading trivia + signature + opening delimiter.
+- `@tail` — the closing delimiter.
+- `@decl` — everything except leading trivia (signature + body + closing delimiter).
+- *(no region)* — the entire chunk including leading trivia. Same as `@head` + `@body` + `@tail`.
+
+For leaf chunks (fields, variants, single-line items), `@body` falls back to the full chunk.
+
+`append`/`prepend` without a `@region` inserts _outside_ the chunk. To add children _inside_ a class, struct, enum, or function body, use `@body`:
+- `class_Foo@body` + `append` → adds inside the class before `}`
+- `class_Foo@body` + `prepend` → adds inside the class after `{`
+- `class_Foo` + `append` → adds after the entire class (after `}`)
+</regions>
+
+<ops>
+|op|sel|effect|
+|---|---|---|
+|`replace`|`chunk#CRC(@region)?`|rewrite the addressed region|
+|`before`|`chunk(@region)?`|insert before the region span|
+|`after`|`chunk(@region)?`|insert after the region span|
+|`prepend`|`chunk(@region)?`|insert at the start inside the region|
+|`append`|`chunk(@region)?`|insert at the end inside the region|
+</ops>
+
+<examples>
+Given this `read` output for `example.ts`:
+```
+  | example.ts·34L·ts·#QBMH
+  |
+  | [<interface_Config#BWTR>]
+ 1| interface Config {
+  | 	[<interface_Config.field_host#TTMN>]
+ 2| 	host: string;
+  | 	[<interface_Config.field_port#QSMH>]
+ 3| 	port: number;
+  | 	[<interface_Config.field_debug#JPRR>]
+ 4| 	debug: boolean;
+ 5| }
+  |
+  | [<class_Counter#HZHY>]
+ 7| class Counter {
+  | 	[<class_Counter.field_value#QJBY>]
+ 8| 	value: number = 0;
+ 9|
+  | 	[<class_Counter.fn_increment#NQWY>]
+10| 	increment(): void {
+11| 		this.value += 1;
+12| 	}
+13|
+  | 	[<class_Counter.fn_decrement#PMBP>]
+14| 	decrement(): void {
+15| 		this.value -= 1;
+16| 	}
+17|
+  | 	[<class_Counter.fn_toString#ZQZP>]
+18| 	toString(): string {
+19| 		return `Counter(${this.value})`;
+20| 	}
+21| }
+  |
+  | [<enum_Status#HYQJ>]
+23| enum Status {
+  | 	[<enum_Status.variant_Active#PQNS>]
+24| 	Active = "ACTIVE",
+  | 	[<enum_Status.variant_Paused#HHNM>]
+25| 	Paused = "PAUSED",
+  | 	[<enum_Status.variant_Stopped#NHTY>]
+26| 	Stopped = "STOPPED",
+27| }
+  |
+  | [<fn_createCounter#PQQY>]
+29| function createCounter(initial: number): Counter {
+30| 	const counter = new Counter();
+31| 	counter.value = initial;
+32| 	return counter;
+33| }
+```
+
+**Replace a whole chunk** (rename a function):
+```
+{ "sel": "fn_createCounter#PQQY", "op": "replace", "content": "function makeCounter(start: number): Counter {\n const c = new Counter();\n c.value = start;\n return c;\n}\n" }
+```
+Result — the entire chunk is rewritten:
+```
+function makeCounter(start: number): Counter {
+  const c = new Counter();
+  c.value = start;
+  return c;
+}
+```
+
+**Replace a method body** (`@body`):
+```
+{ "sel": "class_Counter.fn_increment#NQWY@body", "op": "replace", "content": "this.value += 1;\nconsole.log('incremented to', this.value);\n" }
+```
+Result — only the body changes, signature and braces are kept:
+```
+  increment(): void {
+    this.value += 1;
+    console.log('incremented to', this.value);
+  }
+```
+
+**Replace a function header** (`@head` — signature and doc comment):
+```
+{ "sel": "fn_createCounter#PQQY@head", "op": "replace", "content": "/** Creates a counter with the given start value. */\nfunction createCounter(initial: number, label?: string): Counter {\n" }
+```
+Result — adds a doc comment and updates the signature, body untouched:
+```
+/** Creates a counter with the given start value. */
+function createCounter(initial: number, label?: string): Counter {
+  const counter = new Counter();
+  counter.value = initial;
+  return counter;
+}
+```
+
+**Insert before a chunk** (`before`):
+```
+{ "sel": "fn_createCounter", "op": "before", "content": "/** Factory function below. */\n" }
+```
+Result — a comment is inserted before the function:
+```
+/** Factory function below. */
+
+function createCounter(initial: number): Counter {
+```
+
+**Insert after a chunk** (`after`):
+```
+{ "sel": "enum_Status", "op": "after", "content": "\nfunction isActive(s: Status): boolean {\n return s === Status.Active;\n}\n" }
+```
+Result — a new function appears after the enum:
+```
+enum Status {
+  Active = "ACTIVE",
+  Paused = "PAUSED",
+  Stopped = "STOPPED",
+}
+
+function isActive(s: Status): boolean {
+  return s === Status.Active;
+}
+
+function createCounter(initial: number): Counter {
+```
+
+**Prepend inside a container** (`@body` + `prepend`):
+```
+{ "sel": "class_Counter@body", "op": "prepend", "content": "label: string = 'default';\n\n" }
+```
+Result — a new field is added at the top of the class body, before existing members:
+```
+class Counter {
+  label: string = 'default';
+
+  value: number = 0;
+```
+
+**Append inside a container** (`@body` + `append`):
+```
+{ "sel": "class_Counter@body", "op": "append", "content": "\nreset(): void {\n this.value = 0;\n}\n" }
+```
+Result — a new method is added at the end of the class body, before the closing `}`:
+```
+  toString(): string {
+    return `Counter(${this.value})`;
+  }
+
+  reset(): void {
+    this.value = 0;
+  }
+}
+```
+
+**Delete a chunk** (`replace` with empty content):
+```
+{ "sel": "class_Counter.fn_toString#ZQZP", "op": "replace", "content": "" }
+```
+Result — the method is removed from the class.
+- Indentation rules (important):
+  - Use one leading space for each indent level in canonical chunk-edit content. The tool expands those levels to the file's actual style (2-space, 4-space, tabs, etc.).
+  - Do NOT include the chunk's base indentation — only indent relative to the region's opening level.
+  - For `@body` of a function: write at column 0, e.g. `"return x;\n"`. The tool adds the correct base indent.
+  - For `@head`: write at the chunk's own depth. A class member's head uses `"/** doc */\nstart(): void {"`.
+  - For a top-level item: start at zero indent. Write `"function foo() {\n return 1;\n}\n"`.
+  - The tool strips common leading indentation from your content as a safety net, so accidental over-indentation is corrected.
+</examples>

package/src/prompts/tools/debug.md

@@ -0,0 +1,43 @@
+Provides debugger access through the Debug Adapter Protocol (DAP). Use this to launch or attach debuggers, set breakpoints, step through execution, inspect threads/stack/variables, evaluate expressions, capture program output, and interrupt hung programs.
+
+<instruction>
+- Prefer this over bash when you need program state, breakpoints, stepping, thread inspection, or to interrupt a running process.
+- `action: "launch"` starts a debugger session for a program or script. `program` is required. `adapter` is optional; when omitted, the tool selects an installed adapter from the target path and workspace.
+- `action: "attach"` connects to an existing process. Provide `pid` for local process attach or `port` for adapters that support remote attach. Use `adapter` to force a specific debugger.
+- Breakpoints:
+  - Source breakpoints: `set_breakpoint` / `remove_breakpoint` with `file` + `line`
+  - Function breakpoints: `set_breakpoint` / `remove_breakpoint` with `function`
+  - Optional `condition` adds a conditional breakpoint expression
+- Flow control:
+  - `continue` resumes execution and waits briefly to see whether the program stops or keeps running
+  - `step_over`, `step_in`, `step_out` perform single-step execution
+  - `pause` interrupts a running program so you can inspect the current state
+- Inspection:
+  - `threads` lists threads
+  - `stack_trace` returns frames for the current stopped thread
+  - `scopes` requires `frame_id` or a current stopped frame
+  - `variables` requires `variable_ref` or `scope_id`
+  - `evaluate` requires `expression`; use `context: "repl"` for raw debugger commands when the adapter supports them
+  - `output` returns captured stdout/stderr/console output from the debuggee and adapter
+  - `sessions` lists tracked debug sessions
+  - `terminate` ends the active debug session
+- Timeouts apply to individual debugger requests, not the full session lifetime.
+</instruction>
+
+<caution>
+- Only one active debug session is supported at a time.
+- Some adapters require a launched session to receive `configurationDone` before the target actually runs; if the tool says configuration is pending, set breakpoints and then call `continue`.
+- Adapter availability depends on local binaries. Common built-ins are `gdb`, `lldb-dap`, `python -m debugpy.adapter`, and `dlv dap`.
+</caution>
+
+<example name="launch and inspect hang">
+1. `debug(action: "launch", program: "./my_app")`
+2. `debug(action: "set_breakpoint", file: "src/main.c", line: 42)`
+3. `debug(action: "continue")`
+4. If the program appears hung: `debug(action: "pause")`
+5. Inspect state with `threads`, `stack_trace`, `scopes`, and `variables`
+</example>
+
+<example name="raw debugger command through repl">
+`debug(action: "evaluate", expression: "info registers", context: "repl")`
+</example>

package/src/prompts/tools/grep.md

@@ -17,6 +17,9 @@ Searches files using powerful regex matching.
 - Text output is line-number-prefixed
 {{/if}}
 {{/if}}
+{{#if IS_CHUNK_MODE}}
+- Text output is chunk-path-prefixed: `path:selector>LINE|content`
+{{/if}}
 </output>
 
 <critical>

package/src/prompts/tools/lsp.md

@@ -1,21 +1,21 @@
 Interacts with Language Server Protocol servers for code intelligence.
 
 <operations>
-- `diagnostics`: Get errors/warnings for file, glob, or entire workspace (no file)
+- `diagnostics`: Get errors/warnings for a file, a glob of files, or the entire workspace (`file: "*"`)
 - `definition`: Go to symbol definition → file path + position + 3-line source context
 - `type_definition`: Go to symbol type definition → file path + position + 3-line source context
 - `implementation`: Find concrete implementations → file path + position + 3-line source context
 - `references`: Find references → locations with 3-line source context (first 50), remaining location-only
 - `hover`: Get type info and documentation → type signature + docs
-- `symbols`: List symbols in file, or search workspace (with query, no file)
+- `symbols`: List symbols in a file, or search workspace with `file: "*"` and a `query`
 - `rename`: Rename symbol across codebase → preview or apply edits
 - `code_actions`: List available quick-fixes/refactors/import actions; apply one when `apply: true` and `query` matches title or index
 - `status`: Show active language servers
-- `reload`: Restart the language server
+- `reload`: Restart a specific server (via `file`) or all servers with `file: "*"`
 </operations>
 
 <parameters>
-- `file`: File path; for diagnostics it may be a glob pattern (e.g., `src/**/*.ts`)
+- `file`: File path, glob pattern (e.g. `src/**/*.ts`), or `"*"` for workspace scope. Globs are expanded locally before dispatch. `"*"` routes `diagnostics`/`symbols`/`reload` to their workspace-wide form.
 - `line`: 1-indexed line number for position-based actions
 - `symbol`: Substring on the target line used to resolve column automatically
 - `occurrence`: 1-indexed match index when `symbol` appears multiple times on the same line
@@ -28,6 +28,6 @@ Interacts with Language Server Protocol servers for code intelligence.
 <caution>
 - Requires running LSP server for target language
 - Some operations require file to be saved to disk
-- Diagnostics glob mode samples up to 20 files per request to avoid long-running stalls on broad patterns
+- Glob expansion samples up to 20 files per request; use `file: "*"` for broader coverage
 - When `symbol` is provided for position-based actions, missing symbols or out-of-bounds `occurrence` values return an explicit error instead of silently falling back
 </caution>

package/src/prompts/tools/read-chunk.md

@@ -0,0 +1,17 @@
+Reads files using syntax-aware chunks.
+
+<instruction>
+- `path` — file path or URL; may include `:selector` suffix
+- `sel` — optional selector: `class_Foo`, `class_Foo.fn_bar#ABCD@body`, `?`, `L50`, `L50-L120`, or `raw`
+- `timeout` — seconds, for URLs only
+
+Each opening anchor `[< full.chunk.path#CCCC ]` in the default output identifies a chunk. Use `full.chunk.path#CCCC` as-is to read truncated chunks.
+If you need a canonical target list, run `read(path="file", sel="?")`. That listing shows chunk paths with CRCs.
+Line numbers in the gutter are absolute file line numbers.
+
+Chunk trees: JS, TS, TSX, Python, Rust, Go. Others use blank-line fallback.
+</instruction>
+
+<critical>
+- **MUST** `read` before editing — never invent chunk names or CRCs.
+</critical>

package/src/prompts/tools/read.md

@@ -4,9 +4,23 @@ Reads the content at the specified path or URL.
 The `read` tool is a multi-purpose tool that can be used to inspect all kinds of files and URLs.
 - You **MUST** parallelize reads when exploring related files
 
+## Parameters
+- `path` -- file path or URL (required)
+- `sel` -- optional selector for line ranges or raw mode
+- `timeout` -- seconds, for URLs only
+
+## Selectors
+
+|`sel` value|Behavior|
+|---|---|
+|*(omitted)*|Read full file (up to {{DEFAULT_LIMIT}} lines)|
+|`L50`|Read from line 50 onward|
+|`L50-L120`|Read lines 50 through 120|
+|`raw`|Raw content without transformations (for URLs: untouched HTML)|
+
+Max {{DEFAULT_MAX_LINES}} lines per call.
+
 # Filesystem
-- Reads up to {{DEFAULT_LIMIT}} lines by default
-- Use `offset` and `limit` for large files; max {{DEFAULT_MAX_LINES}} lines per call
 {{#if IS_HASHLINE_MODE}}
 - If reading from FS, result will be prefixed with anchors: `41#ZZ:def alpha():`
 {{else}}
@@ -26,7 +40,7 @@ When used against a directory, or an archive root, the tool will return a list o
 
 # URLs
 - Extract information from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, technical blogs, RSS/Atom feeds, JSON endpoints
-- `raw: true` for untouched HTML or debugging
+- `sel="raw"` for untouched HTML or debugging
 - `timeout` to override the default request timeout
 </instruction>
 
@@ -35,6 +49,6 @@ When used against a directory, or an archive root, the tool will return a list o
 - You **MUST** use `read` instead of `ls` for directory listings.
 - You **MUST** use `read` instead of shelling out to `tar` or `unzip` for supported archive reads.
 - You **MUST** always include the `path` parameter, NEVER call `read` with empty arguments `{}`.
-- When reading specific line ranges, use `offset` and `limit`: `read(path="file", offset=50, limit=100)` not `cat -n file | sed`.
-- You **MAY** use `offset` and `limit` with URL reads; the tool will paginate the cached fetched output.
+- When reading specific line ranges, use `sel`: `read(path="file", sel="L50-L150")` not `cat -n file | sed`.
+- You **MAY** use `sel` with URL reads; the tool will paginate the cached fetched output.
 </critical>