oh-my-opencode 4.19.2 → 4.19.4

package/packages/omo-codex/plugin/test/sync-skills-test-support.mjs

@@ -8,6 +8,7 @@ export const expectedSkills = [
 	"ast-grep",
 	"coding-agent-sessions",
 	"comment-checker",
+	"data-scientist",
 	"debugging",
 	"frontend",
 	"git-master",
@@ -126,7 +127,13 @@ prefixes when identity is needed.
 `;
 const reviewWorkCodexGatePattern = new RegExp(reviewWorkCodexGate.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
 
+const ulwResearchOriginalDeliveryGates = "### The delivery gates \u2014 every gate must PASS, in order\n\nNothing reaches the user until the gates pass:\n\n1. **Visual QA (always).** Render the produced artifact back to images \u2014 PDF pages to PNG, the HTML in a real browser \u2014 and look at them: missing or broken figures, clipped tables, overflowing CJK text, blank pages, unreadable chart labels, wrong page breaks. Fix and re-render until the pages are clean. Reading the source markup is not visual QA; inspect the pixels.\n2. **Proofread gate \u2014 `task(category=\"writing\", ...)`.** Hand the final text to a dedicated `writing` worker whose only job is language: grammar, spelling, punctuation, terminology consistency, and whether the prose reads NATIVELY in the report's own language. It returns a defect list; fix every item and re-run the gate on the delta. Deliver only on a clean pass \u2014 this gate runs BEFORE the first delivery, not after the user finds the typo.";
+const ulwResearchCodexDeliveryGate = "### The delivery gate \u2014 visual QA must PASS\n\nNothing reaches the user until the gate passes:\n\n**Visual QA (always).** Render the produced artifact back to images \u2014 PDF pages to PNG, the HTML in a real browser \u2014 and look at them: missing or broken figures, clipped tables, overflowing CJK text, blank pages, unreadable chart labels, wrong page breaks. Fix and re-render until the pages are clean. Reading the source markup is not visual QA; inspect the pixels.";
+
 export function removeCodexSkillOverlays(skillName, content) {
+	if (skillName === "ulw-research") {
+		return content.replace(ulwResearchCodexDeliveryGate, ulwResearchOriginalDeliveryGates);
+	}
 	if (skillName === "start-work") {
 		return content
 			.replace(startWorkCodexCompletion, startWorkOriginalCompletion)

package/packages/omo-codex/plugin/test/sync-skills.test.mjs

@@ -331,6 +331,18 @@ test("#given packaged Codex ulw-plan surfaces #when inspected #then dangerous sa
 	assert.doesNotMatch(componentWorkflow.content, dangerousBypassPattern, `${componentWorkflow.path} ships unsafe Codex bypass guidance`);
 });
 
+test("#given packaged ulw-research skill #when Codex delivery gates are inspected #then the category-based proofread gate is stripped", async () => {
+	// given
+	const content = await readFile(join(root, "skills", "ulw-research", "SKILL.md"), "utf8");
+
+	// then the writing-category proofread gate never ships to Codex (no category concept there)
+	assert.doesNotMatch(content, /category="writing"/, "codex ulw-research ships the writing-category proofread gate");
+	assert.doesNotMatch(content, /Proofread gate/, "codex ulw-research still references the proofread gate");
+	// and the visual-QA delivery gate survives as the single gate
+	assert.match(content, /### The delivery gate \u2014 visual QA must PASS/u, "codex ulw-research lost the visual-QA delivery gate");
+	assert.match(content, /Visual QA \(always\)/, "codex ulw-research lost the visual-QA gate body");
+});
+
 test("#given context-pressure-prone skills #when bundled for Codex #then the eagerly loaded payload stays budgeted", async () => {
 	// given
 	const skillsRoot = join(root, "skills");

package/packages/omo-codex/scripts/install-dist/install-local.mjs

@@ -5903,7 +5903,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@oh-my-opencode/omo-codex",
-    version: "4.19.2",
+    version: "4.19.4",
     type: "module",
     private: true,
     description: "Codex harness adapter for oh-my-openagent. Vendored Codex plugin namespace (omo) + TypeScript installer + telemetry.",
@@ -8840,6 +8840,24 @@ function stripUnquotedInlineComment3(line) {
 
 // packages/omo-codex/src/install/codex-config-reasoning.ts
 var MANAGED_KEYS = ["model", "model_context_window", "model_reasoning_effort", "plan_mode_reasoning_effort"];
+var CODEX_REASONING_BY_UNIFIED_LEVEL = {
+  off: "none",
+  none: "none",
+  minimal: "minimal",
+  low: "low",
+  medium: "medium",
+  high: "high",
+  xhigh: "xhigh",
+  max: "max"
+};
+function applyReasoningOverride(catalog, reasoning) {
+  if (reasoning === undefined)
+    return catalog;
+  const wireEffort = CODEX_REASONING_BY_UNIFIED_LEVEL[reasoning.trim().toLowerCase()];
+  if (wireEffort === undefined)
+    return catalog;
+  return { ...catalog, current: { ...catalog.current, modelReasoningEffort: wireEffort } };
+}
 function ensureCodexReasoningConfig(config, catalog) {
   const current = readRootReasoningSettings(config);
   if (Object.keys(current).length > 0 && !matchesProfile(current, catalog.current) && !catalog.managedProfiles.some((profile) => matchesProfile(current, profile))) {
@@ -9180,7 +9198,7 @@ async function updateCodexConfig(input) {
   config = ensureFeatureEnabled(config, "plugin_hooks");
   config = ensureFeatureEnabled(config, "multi_agent");
   config = removeUnsupportedCodexMultiAgentModeConfig(config);
-  config = ensureCodexReasoningConfig(config, await readCodexModelCatalog(input.repoRoot));
+  config = ensureCodexReasoningConfig(config, applyReasoningOverride(await readCodexModelCatalog(input.repoRoot), input.reasoning));
   config = ensureCodexMultiAgentV2Config(config, {
     multiAgentVersion: resolveCodexMultiAgentVersion(config, input.configPath)
   });
@@ -9369,7 +9387,7 @@ var MANAGED_REASONING_DEFAULT_UPGRADES = new Map([
     "explorer",
     [
       {
-        previous: { model: "gpt-5.4-mini", effort: "low" },
+        previous: { model: "gpt-5.6-luna-fast", effort: "low" },
         current: { model: "gpt-5.6-terra", effort: "medium" }
       },
       {
@@ -9382,7 +9400,7 @@ var MANAGED_REASONING_DEFAULT_UPGRADES = new Map([
     "librarian",
     [
       {
-        previous: { model: "gpt-5.4-mini", effort: "low" },
+        previous: { model: "gpt-5.6-luna-fast", effort: "low" },
         current: { model: "gpt-5.6-terra", effort: "medium" }
       },
       {
@@ -11015,7 +11033,8 @@ async function runCodexInstaller(options = {}) {
     gitBashEnabled: platform === "win32" && gitBashResolution.found,
     trustedHookStates,
     agentConfigs: [...agentConfigs.values()].sort((left, right) => left.name.localeCompare(right.name)),
-    autonomousPermissions: options.autonomousPermissions !== false
+    autonomousPermissions: options.autonomousPermissions !== false,
+    ...options.reasoning === undefined ? {} : { reasoning: options.reasoning }
   });
   await seedAndMigrateOmoSot({ env: env2, log, repoRoot, runCommand });
   const projectCleanup = await repairProjectLocalCodexArtifactsBestEffort({

package/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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.