oh-my-opencode 4.19.2 → 4.19.4

package/dist/plugin-config/omo-config-chain.d.ts

@@ -0,0 +1,14 @@
+import { type OmoConfigEnv } from "@oh-my-opencode/omo-config-core";
+export type OmoOpenCodeConfigView = {
+    readonly config: Record<string, unknown>;
+    readonly path: string;
+};
+export type OmoOpenCodeConfigChain = {
+    readonly diagnostics: readonly {
+        readonly message: string;
+        readonly path: string;
+    }[];
+    readonly protectedUserView: Record<string, unknown>;
+    readonly views: readonly OmoOpenCodeConfigView[];
+};
+export declare function loadOmoOpenCodeConfigChain(directory: string, environment?: OmoConfigEnv): OmoOpenCodeConfigChain;

package/dist/plugin-config/unknown-key-diagnostics.d.ts

@@ -0,0 +1,5 @@
+import * as z from "zod";
+export type UnknownKeyPath = readonly PropertyKey[];
+type Schema = z.core.$ZodType;
+export declare function findUnknownKeyPaths(schema: Schema, value: unknown): readonly UnknownKeyPath[];
+export {};

package/dist/plugin-config.d.ts

@@ -1,3 +1,3 @@
-export { loadPluginConfig } from "./plugin-config/layered-config-loader";
+import type { OhMyOpenCodeConfig } from "./config";
 export { mergeConfigs } from "./plugin-config/config-merger";
-export { loadConfigFromPath, parseConfigPartially, } from "./plugin-config/single-config-loader";
+export declare function loadPluginConfig(directory: string, _context: unknown): OhMyOpenCodeConfig;

package/dist/plugin-handlers/prometheus-agent-config-builder.d.ts

@@ -3,6 +3,7 @@ import type { FallbackModels } from "../config/schema/fallback-models";
 type PrometheusOverride = Record<string, unknown> & {
     category?: string;
     model?: string;
+    reasoning?: string;
     variant?: string;
     reasoningEffort?: string;
     textVerbosity?: string;

package/dist/shared/agent-display-names.d.ts

@@ -19,7 +19,7 @@ export declare function stripAgentListSortPrefix(agentName: string): string;
  *
  * @param overrides - Optional per-agent overrides map. If the agent has a `displayName`
  *   field set, it takes precedence over the hardcoded AGENT_DISPLAY_NAMES entry.
- *   This enables i18n: `agents.sisyphus.displayName = "总指挥"` in oh-my-openagent.json.
+ *   This enables i18n: `agents.sisyphus.displayName = "总指挥"` in .omo/omo.jsonc.
  */
 export declare function getAgentDisplayName(configKey: string, overrides?: Record<string, {
     displayName?: string;

package/dist/shared/agent-variant.d.ts

@@ -1,4 +1,11 @@
+import type { GetModelCapabilitiesInput } from "@oh-my-opencode/model-core";
 import type { OhMyOpenCodeConfig } from "../config";
+type OpenCodeReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type LoweredReasoning = {
+    variant?: string;
+    reasoningEffort?: OpenCodeReasoningEffort;
+};
+export declare function lowerReasoningForModel(reasoning: string | undefined, model: GetModelCapabilitiesInput): LoweredReasoning;
 export declare function resolveAgentVariant(config: OhMyOpenCodeConfig, agentName?: string): string | undefined;
 export declare function resolveVariantForModel(config: OhMyOpenCodeConfig, agentName: string, currentModel: {
     providerID: string;
@@ -6,4 +13,8 @@ export declare function resolveVariantForModel(config: OhMyOpenCodeConfig, agent
 }): string | undefined;
 export declare function applyAgentVariant(config: OhMyOpenCodeConfig, agentName: string | undefined, message: {
     variant?: string;
+}, currentModel: {
+    providerID: string;
+    modelID: string;
 }): void;
+export {};

package/dist/shared/jsonc-parser.d.ts

@@ -1 +1 @@
-export { clearPluginConfigFileDetectionCache, detectConfigFile, detectPluginConfigFile, parseJsonc, parseJsoncSafe, readJsoncFile, type DetectPluginConfigFileOptions, type JsoncParseResult, } from "@oh-my-opencode/utils";
+export { detectConfigFile, parseJsonc, parseJsoncSafe, readJsoncFile, type JsoncParseResult, } from "@oh-my-opencode/utils";

package/dist/shared/migration.d.ts

@@ -1 +1,5 @@
-export * from "@oh-my-opencode/utils/migration";
+export { AGENT_NAME_MAP, BUILTIN_AGENT_NAMES, migrateAgentNames } from "@oh-my-opencode/utils/migration/agent-names";
+export { migrateAgentConfigToCategory, MODEL_TO_CATEGORY_MAP, shouldDeleteAgentConfig } from "@oh-my-opencode/utils/migration/agent-category";
+export { HOOK_NAME_MAP, migrateHookNames } from "@oh-my-opencode/utils/migration/hook-names";
+export { getSidecarPath, readAppliedMigrations, writeAppliedMigrations } from "@oh-my-opencode/utils/migration/migrations-sidecar";
+export { migrateModelVersions, MODEL_VERSION_MAP } from "@oh-my-opencode/utils/migration/model-versions";

package/dist/shared/opencode-config-dir-types.d.ts

@@ -9,5 +9,4 @@ export type OpenCodeConfigPaths = {
     configJson: string;
     configJsonc: string;
     packageJson: string;
-    omoConfig: string;
 };

package/dist/shared/plugin-identity.d.ts

@@ -1,8 +1,6 @@
-export declare const PLUGIN_NAME: string;
-export declare const LEGACY_PLUGIN_NAME: string;
-export declare const PUBLISHED_PACKAGE_NAME: string;
-export declare const ACCEPTED_PACKAGE_NAMES: readonly string[];
-export declare const CONFIG_BASENAME: string;
-export declare const LEGACY_CONFIG_BASENAME: string;
-export declare const LOG_FILENAME: string;
-export declare const CACHE_DIR_NAME: string;
+export declare const PLUGIN_NAME = "oh-my-openagent";
+export declare const LEGACY_PLUGIN_NAME = "oh-my-opencode";
+export declare const PUBLISHED_PACKAGE_NAME = "oh-my-openagent";
+export declare const ACCEPTED_PACKAGE_NAMES: string[];
+export declare const LOG_FILENAME = "oh-my-opencode.log";
+export declare const CACHE_DIR_NAME = "oh-my-opencode";

package/dist/shared/project-discovery-dirs.d.ts

@@ -4,4 +4,3 @@ export declare function findProjectClaudeSkillDirs(startDirectory: string, stopD
 export declare function findProjectAgentsSkillDirs(startDirectory: string, stopDirectory?: string): string[];
 export declare function findProjectOpencodeSkillDirs(startDirectory: string, stopDirectory?: string): string[];
 export declare function findProjectOpencodeCommandDirs(startDirectory: string, stopDirectory?: string): string[];
-export declare function findProjectOpencodePluginConfigFiles(startDirectory: string, stopDirectory?: string): string[];

package/dist/shared/session-prompt-params-helpers.d.ts

@@ -1,6 +1,11 @@
+import type { LoweredReasoning } from "./agent-variant";
 type PromptParamModel = {
+    providerID?: string;
+    modelID?: string;
+    runtimeModel?: Record<string, unknown>;
     temperature?: number;
     top_p?: number;
+    reasoning?: string;
     reasoningEffort?: string;
     maxTokens?: number;
     thinking?: {
@@ -8,5 +13,5 @@ type PromptParamModel = {
         budgetTokens?: number;
     };
 };
-export declare function applySessionPromptParams(sessionID: string, model: PromptParamModel | undefined): void;
+export declare function applySessionPromptParams(sessionID: string, model: PromptParamModel | undefined): LoweredReasoning;
 export {};

package/dist/skills/coding-agent-sessions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coding-agent-sessions
-description: "MUST USE when asked to find, read, list, search, inspect, fetch, export, or reconstruct coding-agent sessions across Codex, Claude Code/Desktop, OpenCode, Senpi/pi, oh-my-pi (omp), gajae-code (gjc), OpenClaw, Factory Droid, Amp, Gemini/Kimi/Qwen CLIs, Codebuff, Roo/Kilo/Cline, Kodu, Cursor CLI, Aider, or unknown local agent logs. Covers transcripts, session IDs, rollout JSONL, state SQLite, Claude projects/pre-compact histories, OpenCode messages/parts, child/subagent linkage, cwd/model/time/token filters, archives, and cost clues. Expands fuzzy recall into parallel query lanes and first probes known stores so absent platforms are skipped cheaply. Triggers: coding agent sessions, Codex/Claude/OpenCode/Senpi/pi/oh-my-pi/omp/gajae-code/gjc/OpenClaw/Droid/Amp/Kodu/Cursor/Aider sessions, transcript search, session history, session ID, read transcript, token usage, subagent sessions, what did I do yesterday, did we already do this."
+description: "MUST USE when asked to find, read, list, search, inspect, fetch, export, or reconstruct coding-agent sessions across Codex, Claude Code/Desktop, OpenCode, Senpi/pi, oh-my-pi (omp), gajae-code (gjc), OpenClaw, Factory Droid, Amp, Gemini/Kimi/Qwen CLIs, Codebuff, Roo/Kilo/Cline, Kodu, Cursor CLI, Aider, Aside browser-agent sessions, or unknown local agent logs. Covers transcripts, session IDs, rollout JSONL, state SQLite, Claude projects/pre-compact histories, OpenCode messages/parts, child/subagent linkage, cwd/model/time/token filters, archives, and cost clues. Expands fuzzy recall into parallel query lanes and first probes known stores so absent platforms are skipped cheaply. Triggers: coding agent sessions, Codex/Claude/OpenCode/Senpi/pi/oh-my-pi/omp/gajae-code/gjc/OpenClaw/Droid/Amp/Kodu/Cursor/Aider/Aside sessions, transcript search, session history, session ID, read transcript, token usage, subagent sessions, what did I do yesterday, did we already do this."
 ---
 
 # Coding Agent Sessions
@@ -18,7 +18,7 @@ Find local coding-agent sessions across agent products before answering from mem
    | Senpi / pi coding-agent logs | `references/senpi.md` |
    | oh-my-pi (`omp`, `~/.omp`) and gajae-code (`gjc`, `~/.gjc`) logs | `references/senpi.md` |
    | OpenCode / oh-my-openagent (formerly oh-my-opencode) storage | `references/opencode.md` |
-   | OpenClaw, Droid, Amp, Gemini, Kimi, Qwen, Codebuff, Roo/Kilo/Cline, Kodu, Cursor CLI, Aider, Kiro, Goose, Hermes, Crush, Zed | `references/all-platforms.md` |
+   | OpenClaw, Droid, Amp, Gemini, Kimi, Qwen, Codebuff, Roo/Kilo/Cline, Kodu, Cursor CLI, Aider, Kiro, Goose, Hermes, Crush, Zed, Aside | `references/all-platforms.md` |
    | Unknown / "any session" / cross-agent search | `references/all-platforms.md` |
 
 2. **Run the broad finder first unless the user gave an exact file path. For fuzzy recall, expand the query first.**
@@ -51,7 +51,7 @@ The finder prints JSON for stdout and `jq`. Every result includes:
 
 | Field | Meaning |
 |---|---|
-| `platform` | Registered platform key such as `codex`, `claude`, `senpi`, `oh-my-pi`, `gajae-code`, `opencode`, `openclaw`, `droid`, `amp`, `kodu`, `cursor-cli`, `aider`, `roo-code`, `kilo-code`, `kilo-cli`, or `kiro` |
+| `platform` | Registered platform key such as `codex`, `claude`, `senpi`, `oh-my-pi`, `gajae-code`, `opencode`, `openclaw`, `droid`, `amp`, `kodu`, `cursor-cli`, `aider`, `roo-code`, `kilo-code`, `kilo-cli`, `kiro`, or `aside` |
 | `id` | Session ID or stable file-derived ID |
 | `path` | Raw transcript/index file |
 | `cwd` | Working directory when recoverable |
@@ -122,6 +122,7 @@ Use `references/codex.md` for Codex storage details.
 | Missing oh-my-pi / gajae-code sessions | Those stores live in `~/.omp/agent/sessions` and `~/.gjc/agent/sessions`. For a custom `PI_CONFIG_DIR` / `PI_CODING_AGENT_DIR`, pass that agent dir with `--root`. |
 | Missing OpenCode sessions | Pass the data dir that contains `messages/` and `parts/`, often `~/.opencode` or `~/.local/share/opencode`. |
 | Missing Claude sessions | Search `~/.claude/projects`, `~/.claude/transcripts`, and `~/.claude/pre-compact-session-histories`; use `--root` for nonstandard config dirs. |
+| Missing Aside sessions | The Aside browser agent stores per-user data under `~/.aside/u/<n>/` (`sessions/<date>_<id>/messages.jsonl` transcripts + a `state.db` index; `agents/*/sessions/` is just a hardlink mirror). Pass `--root` for a nonstandard `.aside` dir or an exported user dir. |
 | Missing optional platform sessions | Check `references/all-platforms.md` for the exact local store. For project-local tools such as Aider, pass `--root /path/to/workspace` if the repo is outside the bounded default roots. |
 | Date filter misses local sessions | Timestamps are compared as UTC instants when parseable; otherwise file mtime is used. |
 | Search is slow | Narrow with repeated `--platform` flags or date/cwd filters. Optional stores are probed before parsing; avoid passing your whole home as `--root` unless you really want every bounded project-local scan. |

package/dist/skills/coding-agent-sessions/references/all-platforms.md

@@ -4,7 +4,7 @@
 
 Search these first, then add user-supplied roots with `--root`:
 
-Registered platform keys: `codex`, `claude`, `senpi`, `oh-my-pi`, `gajae-code`, `opencode`, `openclaw`, `droid`, `amp`, `gemini`, `kimi`, `qwen`, `codebuff`, `roo-code`, `kilo-code`, `cline`, `kodu`, `cursor-cli`, `aider`, `kilo-cli`, `hermes`, `goose`, `crush`, `zed`, `kiro`.
+Registered platform keys: `codex`, `claude`, `senpi`, `oh-my-pi`, `gajae-code`, `opencode`, `openclaw`, `droid`, `amp`, `gemini`, `kimi`, `qwen`, `codebuff`, `roo-code`, `kilo-code`, `cline`, `kodu`, `cursor-cli`, `aider`, `kilo-cli`, `hermes`, `goose`, `crush`, `zed`, `kiro`, `aside`.
 
 | Platform | Unix/macOS | Windows |
 |---|---|---|
@@ -25,6 +25,7 @@ Registered platform keys: `codex`, `claude`, `senpi`, `oh-my-pi`, `gajae-code`,
 | Aider | bounded project roots containing `.aider.chat.history.md`; use `--root` for other repos | pass `--root` |
 | Kilo CLI (`kilo-cli`) / Hermes / Goose / Crush / Zed | Known SQLite roots are probed cheaply; unsupported schemas return empty | pass `--root` |
 | Kiro | `~/.kiro/sessions/cli/*.json` plus paired `*.jsonl` prompt events | pass `--root` |
+| Aside (browser agent) | `~/.aside/u/*/sessions/<date>_<id>/messages.jsonl`, joined with the per-user `state.db` `sessions` table (title, parent_id, cwd, model, timestamps). `~/.aside/u/*/agents/*/sessions/` is a hardlink mirror of `sessions/` and is intentionally not scanned | pass `--root` |
 
 ## Excluded usage-only sources
 
@@ -52,6 +53,7 @@ Do not add these as default transcript platforms without a separate prompt-recon
 | Claude | `projects/<proj>/<sid>/subagents/**/agent-<agentId>.jsonl` | directory `<sid>` | `agent-*.meta.json` `agentType` |
 | Codex | thread row + own rollout JSONL | `thread_spawn_edges` / `source.subagent.thread_spawn.parent_thread_id` | `agent_nickname (agent_role)` |
 | OpenCode | `session` table row / `storage/session/**.json` | `parent_id` column / `parentID` field | `agent` column |
+| Aside | own `sessions/<date>_<id>/messages.jsonl` transcript | `parent_id` column in `state.db` `sessions` | child session's `title` column (task description) |
 
 ## Parallelism
 

package/dist/skills/coding-agent-sessions/scripts/agent_sessions/aside_scanner.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypeAlias
+
+from .jsonio import as_map, iter_jsonl, parse_json_text, text
+from .timeparse import file_time, unix_millis, unix_seconds
+from .transcript import content_text, existing, flat_parallel, merge_usage, recent
+from .types import JsonMap, Session
+
+SqlValue: TypeAlias = str | int | float | bytes | None
+SqlRow: TypeAlias = tuple[SqlValue, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class _StateRow:
+    parent_id: str | None
+    title: str | None
+    cwd: str | None
+    provider: str | None
+    model: str | None
+    created_at: str | None
+    updated_at: str | None
+
+
+def scan_aside(extra_roots: tuple[Path, ...], workers: int) -> list[Session]:
+    roots = _roots([Path.home() / ".aside"], extra_roots, (".aside",))
+    sessions: list[Session] = []
+    for user_dir in _user_dirs(roots):
+        index = _state_index(user_dir / "state.db")
+        paths = list((user_dir / "sessions").glob("*/messages.jsonl"))
+        sessions.extend(flat_parallel(recent(paths), workers, lambda path, rows=index: [_aside_session(path, rows)]))
+    return sessions
+
+
+def _user_dirs(roots: list[Path]) -> list[Path]:
+    dirs: list[Path] = []
+    for root in roots:
+        users = sorted(path for path in (root / "u").glob("*") if path.is_dir())
+        if users:
+            dirs.extend(users)
+        elif (root / "sessions").exists():
+            dirs.append(root)
+    return dirs
+
+
+def _state_index(db_path: Path) -> dict[str, _StateRow]:
+    if not db_path.exists():
+        return {}
+    try:
+        with sqlite3.connect(f"file:{db_path}?mode=ro", uri=True) as conn:
+            rows: list[SqlRow] = conn.execute("select id, parent_id, title, cwd, model, created_at, updated_at from sessions").fetchall()
+    except sqlite3.Error:
+        return {}
+    index: dict[str, _StateRow] = {}
+    for row in rows:
+        sid = _cell_text(row, 0)
+        if sid is None:
+            continue
+        provider, model = _model_fields(_cell_text(row, 4))
+        index[sid] = _StateRow(
+            _cell_text(row, 1),
+            _cell_text(row, 2),
+            _cell_text(row, 3),
+            provider,
+            model,
+            unix_seconds(_cell_number(row, 5)),
+            unix_seconds(_cell_number(row, 6)),
+        )
+    return index
+
+
+def _cell_text(row: SqlRow, index: int) -> str | None:
+    value = row[index] if index < len(row) else None
+    return value if isinstance(value, str) else None
+
+
+def _cell_number(row: SqlRow, index: int) -> int | float | None:
+    value = row[index] if index < len(row) else None
+    return value if isinstance(value, int | float) else None
+
+
+def _model_fields(model_json: str | None) -> tuple[str | None, str | None]:
+    data = as_map(parse_json_text(model_json)) if model_json else None
+    if data is None:
+        return None, None
+    return text(data.get("provider")), text(data.get("modelId")) or text(data.get("model"))
+
+
+def _aside_session(path: Path, index: dict[str, _StateRow]) -> Session:
+    sid = _dir_session_id(path.parent.name)
+    row = index.get(sid)
+    first_user = last_user = ""
+    provider = model = None
+    created = updated = None
+    usage: JsonMap = {}
+    for data in iter_jsonl(path):
+        stamp = data.get("timestamp")
+        moment = unix_millis(int(stamp)) if isinstance(stamp, int | float) else None
+        created = created or moment
+        updated = moment or updated
+        role = text(data.get("role"))
+        if role == "user":
+            prompt = content_text(data.get("content"))
+            if prompt:
+                first_user = first_user or prompt
+                last_user = prompt
+        elif role == "assistant":
+            provider = provider or text(data.get("provider"))
+            model = model or text(data.get("model"))
+            merge_usage(usage, as_map(data.get("usage")))
+    return Session(
+        "aside",
+        sid,
+        str(path),
+        row.cwd if row is not None else None,
+        (row.created_at if row is not None else None) or created or file_time(path),
+        (row.updated_at if row is not None else None) or updated or created or file_time(path),
+        (row.provider if row is not None else None) or provider,
+        (row.model if row is not None else None) or model,
+        first_user,
+        usage,
+        row.parent_id if row is not None else None,
+        row.title if row is not None and row.parent_id is not None else None,
+        last_user,
+    )
+
+
+def _dir_session_id(name: str) -> str:
+    return name.split("_", 1)[-1]
+
+
+def _roots(defaults: list[Path], extra_roots: tuple[Path, ...], children: tuple[str, ...]) -> list[Path]:
+    candidates = [*defaults]
+    for root in extra_roots:
+        candidates.append(root)
+        candidates.extend(root / child for child in children)
+    return existing(candidates)

package/dist/skills/coding-agent-sessions/scripts/agent_sessions/scanners.py

@@ -4,6 +4,7 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from typing import Callable, TypeAlias
 
+from .aside_scanner import scan_aside
 from .claude import scan_claude
 from .codex import scan_codex
 from .file_scanners import (
@@ -54,6 +55,7 @@ PLATFORM_SCANNERS: dict[str, Scanner] = {
     "crush": scan_crush,
     "zed": scan_zed,
     "kiro": scan_kiro,
+    "aside": scan_aside,
 }
 DEFAULT_PLATFORMS = frozenset(PLATFORM_SCANNERS)
 PLATFORM_ALIASES = {
@@ -69,6 +71,7 @@ PLATFORM_ALIASES = {
     "gjc": "gajae-code",
     "gajae": "gajae-code",
     "gajaecode": "gajae-code",
+    "aside-browser": "aside",
 }
 
 __all__ = ["DEFAULT_PLATFORMS", "PLATFORM_SCANNERS", "scan", "scan_claude", "scan_codex", "scan_gajae_code", "scan_oh_my_pi", "scan_opencode", "scan_senpi"]

package/dist/skills/data-scientist/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: data-scientist
+description: "Expert data processing specialist with intelligent DuckDB/Polars selection for maximum performance. Always includes numpy, never uses pandas, runs everything through uv. Triggers: 'analyze the data', 'analyze this file', 'what is in this CSV/parquet/json', 'summarize this', 'group by', 'filter rows', 'sort by', 'join these files', 'merge datasets', 'time series trend', 'last 30 days data', 'compare yesterday and today', 'distribution/histogram', 'correlation', 'clean duplicates', 'handle missing values', 'dataset larger than RAM', 'SQL query on files', 'DataFrame operations', 'chart/plot this data', DuckDB vs Polars selection, quick data exploration CLI. NOT for plain text/code inspection, configs, or tiny inline math."
+---
+
+# Data Scientist: High-Performance Data Processing Expert
+
+## Role & Expertise
+
+Performance-obsessed data scientist with expertise in:
+- Intelligent tool selection: DuckDB vs Polars based on operation characteristics
+- Zero-copy data interchange via Apache Arrow
+- Memory-efficient processing for datasets exceeding RAM
+- SQL and DataFrame API mastery for analytical workloads
+
+## Environment Setup
+
+Everything runs through **uv**. If `uv` is not on PATH, set it up first — pick the path that matches the system and run it, no manual guesswork:
+
+```bash
+bash scripts/setup-uv.sh        # macOS / Linux / WSL / Git Bash — auto-detects OS + arch, installs or updates uv to latest
+```
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/setup-uv.ps1   # native Windows — installs or updates uv to latest
+```
+
+Both scripts detect the platform, install uv when missing (official installer first, Homebrew/winget as fallback), upgrade it when present (`uv self update`), put it on PATH for the current shell, and verify with `uv --version`. The full per-platform matrix, PATH notes, and CI usage live in [references/uv-setup.md](references/uv-setup.md). Verify: `uv --version`.
+
+## Core Principles
+
+### ABSOLUTE RULES
+
+1. **ALWAYS include numpy** in all data processing operations (`uv run --with numpy ...`)
+2. **NEVER use pandas** - Polars and DuckDB beat it decisively on every operation; the entire skill assumes pandas is absent
+3. **ALWAYS use Python via `uv run`** for calculations and data processing
+4. **Intelligent tool selection**: Choose DuckDB or Polars based on operation types, NOT arbitrarily
+5. **Zero-copy conversions**: hand data across DuckDB and Polars through Arrow — `duckdb.sql(...).pl()`. Never call `.df()` (returns a pandas frame; crashes without pandas). Keep `pyarrow` in the package set or `.pl()` raises `ModuleNotFoundError`
+6. **Lazy evaluation**: Prefer `scan_csv`/`scan_parquet` and `.collect()` only when needed
+7. **Direct file queries**: Let DuckDB query files directly instead of loading to memory when possible
+
+### Standard Package Pattern
+
+```bash
+# Default for data tasks (numpy + pyarrow are mandatory parts of the set)
+uv run --with numpy --with duckdb --with polars --with pyarrow python -c "{code}"
+
+# With visualization (RECOMMENDED for most analysis requests)
+uv run --with numpy --with duckdb --with polars --with pyarrow --with matplotlib python -c "{code}"
+
+# Pure Polars
+uv run --with numpy --with polars python -c "{code}"
+
+# Pure DuckDB (with the Arrow handoff available)
+uv run --with numpy --with duckdb --with pyarrow python -c "{code}"
+```
+
+**When to include matplotlib:**
+- User requests visualization: "graph", "chart", "plot", "show me"
+- Exploratory data analysis (EDA): "analyze", "trends", "patterns"
+- Time-series analysis: "over time", "daily", "trends"
+- Distribution analysis: "distribution", "histogram", "statistics"
+- Comparison tasks: "compare", visual comparison implied
+- **Default to including matplotlib** when in doubt - overhead is minimal
+
+## Tool Selection Logic
+
+### Decision Tree (Apply in Order)
+
+1. **Is it a `.duckdb` file?** → **USE DUCKDB** (native format, optimal performance)
+2. **Simple one-off query without needing full data in memory?** → **USE DUCKDB** (direct file query, zero memory load)
+3. **Very heavy complex SQL query (multi-table joins, window functions)?** → **USE DUCKDB** (superior SQL optimizer)
+4. **Main operation is FILTERING?** → **USE POLARS** (typically the fastest by a wide margin — see benchmarks)
+5. **Main operation is SORTING?** → **USE POLARS** (typically the fastest)
+6. **Complex SQL JOINS needed?** → **USE DUCKDB** (stronger join engine, more join types)
+7. **Heavy GROUP BY AGGREGATIONS?** → **USE DUCKDB** (typically faster on large datasets)
+8. **Window functions with partitioning?** → **POLARS** (typically faster)
+9. **Complex TRANSFORMATIONS (pivot, melt, string ops)?** → **USE POLARS**
+10. **Dataset larger than available RAM?** → **USE POLARS** (streaming support) or **DUCKDB** (out-of-core)
+11. **Mixed operations?** → **USE HYBRID APPROACH** (leverage strengths of both)
+
+### Quick Reference
+
+```
+Simple query → DuckDB
+Heavy complex query → DuckDB
+Filter → Polars
+Sort → Polars
+Join → DuckDB
+Aggregate → DuckDB
+Window → Polars
+Transform → Polars
+Too large for RAM → Polars streaming
+Mixed operations → Hybrid
+```
+
+The exact multipliers these heuristics distill (with sources and caveats — routing heuristics, not guarantees) live in [performance-benchmarks.md](references/performance-benchmarks.md).
+
+## Essential Patterns
+
+### DuckDB Direct File Query
+
+```python
+import duckdb
+# Query file directly - no memory load
+result = duckdb.sql("""
+    SELECT category, SUM(amount) as total
+    FROM 'data.csv'
+    GROUP BY category
+""").pl()  # .pl() -> Polars via Arrow. Requires pyarrow. Never .df() (pandas).
+```
+
+### Polars Lazy Evaluation
+
+```python
+import polars as pl
+# Lazy scan - optimizes and executes once
+result = (
+    pl.scan_csv('data.csv')
+    .filter(pl.col('value') > 100)
+    .sort('value', descending=True)
+    .collect()
+)
+```
+
+### Zero-Copy DuckDB → Polars
+
+```python
+import duckdb
+# Direct conversion via Arrow (pyarrow required in the package set)
+df_polars = duckdb.sql("SELECT * FROM 'data.csv'").pl()
+```
+
+### Hybrid Approach
+
+```python
+import duckdb
+import polars as pl
+
+# Phase 1: DuckDB for joins
+joined = duckdb.sql(
+    "SELECT * FROM 'orders.csv' o "
+    "JOIN 'customers.csv' c ON o.customer_id = c.customer_id"
+).pl()
+
+# Phase 2: Polars for filtering
+filtered = joined.filter(pl.col('amount') > 100)
+
+# Phase 3: Back to DuckDB for aggregation
+duckdb.register('filtered_data', filtered)
+final = duckdb.sql('SELECT category, SUM(amount) FROM filtered_data GROUP BY category').pl()
+```
+
+## Quick Query CLI
+
+For ad-hoc data exploration, use the built-in query runner:
+
+```bash
+# SQL query (uses DuckDB)
+uv run scripts/quick-query.py data.csv "SELECT category, COUNT(*) FROM data GROUP BY category"
+
+# Filter expression — Polars SQL syntax, e.g. "amount > 100" (NOT Python: never passes through eval)
+uv run scripts/quick-query.py data.csv --filter "amount > 100"
+
+# Auto-describe (schema + stats)
+uv run scripts/quick-query.py data.parquet --describe
+```
+
+Supports CSV, Parquet, JSON, NDJSON. Cross-platform (macOS, Linux, Windows). Excel files are not read directly — export to CSV or Parquet first.
+
+## Reference Documentation
+
+For detailed guidance, consult these reference files:
+
+- **Environment setup per platform**: See [uv-setup.md](references/uv-setup.md) — install/update uv on macOS, Linux, Windows, WSL, CI; PATH fixes; `scripts/setup-uv.sh` / `scripts/setup-uv.ps1` automate it.
+- **Performance benchmarks and operation detection**: See [performance-benchmarks.md](references/performance-benchmarks.md)
+- **Integration patterns and best practices**: See [integration-patterns.md](references/integration-patterns.md)
+- **Execution templates**: See [execution-templates.md](references/execution-templates.md)
+- **Common scenarios**: See [common-scenarios.md](references/common-scenarios.md)
+
+## Quality Assurance Process
+
+### Before Execution
+1. **Analyze request** → Detect operation types (filter, join, aggregate, etc.)
+2. **Select optimal tool** → Apply decision tree based on detected operations
+3. **Verify approach** → Confirm tool selection matches the benchmark heuristics
+4. **Check package list** → Ensure numpy AND pyarrow are included
+
+### During Execution
+1. **Use lazy evaluation** when possible (Polars `scan_*`, DuckDB direct queries)
+2. **Monitor for errors** and have fallback strategy ready
+3. **Provide progress updates** for long operations
+
+### After Execution
+1. **Report performance** → Show processing time and row counts
+2. **Validate results** → Confirm output matches expectations
+3. **Document tool choice** → Explain why specific tool was selected
+
+## Activation Context
+
+**Automatic activation triggers:**
+
+### Exploratory Questions
+- "Analyze the data" / "What's in the data" / "What's in this file"
+- "Show me the data" / "Take a look at this file" / "Check the file contents"
+
+### Temporal/Historical Analysis
+- "What happened in the past N days?" / "How's last week's data?"
+- "What's the trend for the last 30 days?" / "Compare yesterday and today"
+
+### Aggregation/Summary Requests
+- "Summarize this" / "What's the total?" / "What's the average?"
+- "Show by category" / "Show statistics" / "How many?"
+
+### Filtering/Search Patterns
+- "Show only above 100" / "Find specific conditions" / "Top 10"
+
+### Comparison/Correlation
+- "Compare A and B" / "What's the difference?" / "Is there a correlation?" / "Merge two files"
+
+### Transformation/Cleaning
+- "Clean this up" / "Remove duplicates" / "Handle missing values" / "Convert format"
+
+### Technical Patterns
+- Working with CSV, Parquet, JSON, NDJSON, or `.duckdb` files
+- File paths ending in `.csv`, `.parquet`, `.json`, `.jsonl`, `.ndjson`, `.tsv`, `.duckdb`
+- Requests involving calculations or aggregations
+- Joining, filtering, sorting, or transforming datasets
+- Processing large datasets that may exceed memory
+- Comparing or analyzing data from multiple sources
+- Performance-critical data operations
+- SQL queries or DataFrame operations mentioned
+
+### When NOT to Activate
+- Simple file reading for text/code inspection (use the harness's file-read surface)
+- Non-data files (images, videos, binaries)
+- Configuration files (YAML, TOML, JSON configs) unless specifically for data analysis
+- Small inline calculations (run them directly)
+- Excel files — convert to CSV/Parquet first
+
+---
+
+**Core execution principle:** Always apply intelligent tool selection based on operation characteristics, never use pandas, and always include numpy and pyarrow in the execution environment.