oh-my-opencode 5.0.0-beta.26 → 5.0.0-beta.29

package/dist/index.js

@@ -88602,6 +88602,16 @@ var SessionCategoryRegistry = {
 // packages/omo-opencode/src/shared/index.ts
 init_plugin_identity();
 
+// packages/omo-opencode/src/shared/plugin-entry-shape.ts
+function isPluginTupleEntry(entry) {
+  return Array.isArray(entry) && typeof entry[0] === "string";
+}
+function getPluginEntryName(entry) {
+  return isPluginTupleEntry(entry) ? entry[0] : entry;
+}
+function withPluginEntryName(entry, name) {
+  return isPluginTupleEntry(entry) ? [name, entry[1]] : name;
+}
 // packages/omo-opencode/src/shared/legacy-plugin-warning.ts
 import { existsSync as existsSync35, readFileSync as readFileSync24 } from "fs";
 import { join as join50 } from "path";
@@ -88624,10 +88634,12 @@ function getOpenCodeConfigPath(overrideConfigDir) {
   return null;
 }
 function isLegacyPluginEntry(entry) {
-  return entry === LEGACY_PLUGIN_NAME || entry.startsWith(`${LEGACY_PLUGIN_NAME}@`);
+  const name = getPluginEntryName(entry);
+  return name === LEGACY_PLUGIN_NAME || name.startsWith(`${LEGACY_PLUGIN_NAME}@`);
 }
 function isCanonicalPluginEntry(entry) {
-  return entry === PLUGIN_NAME || entry.startsWith(`${PLUGIN_NAME}@`);
+  const name = getPluginEntryName(entry);
+  return name === PLUGIN_NAME || name.startsWith(`${PLUGIN_NAME}@`);
 }
 function checkForLegacyPluginEntry(overrideConfigDir) {
   const configPath = getOpenCodeConfigPath(overrideConfigDir);
@@ -88668,17 +88680,20 @@ init_plugin_identity();
 // packages/omo-opencode/src/shared/plugin-entry-migrator.ts
 init_plugin_identity();
 function isLegacyEntry(entry) {
-  return entry === LEGACY_PLUGIN_NAME || entry.startsWith(`${LEGACY_PLUGIN_NAME}@`);
+  const name = getPluginEntryName(entry);
+  return name === LEGACY_PLUGIN_NAME || name.startsWith(`${LEGACY_PLUGIN_NAME}@`);
 }
 function isCanonicalEntry(entry) {
-  return entry === PLUGIN_NAME || entry.startsWith(`${PLUGIN_NAME}@`);
+  const name = getPluginEntryName(entry);
+  return name === PLUGIN_NAME || name.startsWith(`${PLUGIN_NAME}@`);
 }
 function toCanonicalEntry(entry) {
-  if (entry === LEGACY_PLUGIN_NAME) {
-    return PLUGIN_NAME;
+  const name = getPluginEntryName(entry);
+  if (name === LEGACY_PLUGIN_NAME) {
+    return withPluginEntryName(entry, PLUGIN_NAME);
   }
-  if (entry.startsWith(`${LEGACY_PLUGIN_NAME}@`)) {
-    return `${PLUGIN_NAME}${entry.slice(LEGACY_PLUGIN_NAME.length)}`;
+  if (name.startsWith(`${LEGACY_PLUGIN_NAME}@`)) {
+    return withPluginEntryName(entry, `${PLUGIN_NAME}${name.slice(LEGACY_PLUGIN_NAME.length)}`);
   }
   return entry;
 }
@@ -88744,6 +88759,9 @@ function migrateLegacyPluginEntry(configPath) {
 
 // packages/omo-opencode/src/shared/log-legacy-plugin-startup-warning.ts
 init_plugin_identity();
+function describeEntry(entry) {
+  return getPluginEntryName(entry);
+}
 function logLegacyPluginStartupWarning(deps = {}) {
   const checkForLegacyPluginEntryFn = deps.checkForLegacyPluginEntry ?? checkForLegacyPluginEntry;
   const logFn = deps.log ?? log2;
@@ -88761,9 +88779,9 @@ function logLegacyPluginStartupWarning(deps = {}) {
   console.warn(`[oh-my-openagent] WARNING: Your opencode.json uses the legacy package name "${LEGACY_PLUGIN_NAME}".` + ` The package has been renamed to "${PLUGIN_NAME}".` + ` Attempting auto-migration...`);
   const migrated = migrateLegacyPluginEntryFn(result.configPath);
   if (migrated) {
-    console.warn(`[oh-my-openagent] Auto-migrated opencode.json: ${result.legacyEntries.join(", ")} -> ${suggestedEntries.join(", ")}`);
+    console.warn(`[oh-my-openagent] Auto-migrated opencode.json: ${result.legacyEntries.map(describeEntry).join(", ")} -> ${suggestedEntries.map(describeEntry).join(", ")}`);
   } else {
-    console.warn(`[oh-my-openagent] Could not auto-migrate. Please manually update your opencode.json:` + ` ${result.legacyEntries.map((e, i) => `"${e}" -> "${suggestedEntries[i]}"`).join(", ")}`);
+    console.warn(`[oh-my-openagent] Could not auto-migrate. Please manually update your opencode.json:` + ` ${result.legacyEntries.map((entry, index) => `"${describeEntry(entry)}" -> "${describeEntry(suggestedEntries[index] ?? entry)}"`).join(", ")}`);
   }
 }
 // packages/omo-opencode/src/shared/legacy-workspace-migration.ts
@@ -89523,7 +89541,11 @@ async function resolveLatestMessageInfo(ctx, sessionID, prefetchedMessages) {
       return {
         resolvedInfo: {
           agent: info.agent,
-          model: info.model ?? (info.providerID && info.modelID ? { providerID: info.providerID, modelID: info.modelID } : undefined),
+          model: info.model ?? (info.providerID && info.modelID ? {
+            providerID: info.providerID,
+            modelID: info.modelID,
+            ...info.variant ? { variant: info.variant } : {}
+          } : undefined),
           tools: info.tools
         },
         encounteredCompaction,
@@ -98705,7 +98727,7 @@ function getCachedVersion(options = {}) {
 // package.json
 var package_default = {
   name: "oh-my-opencode",
-  version: "5.0.0-beta.26",
+  version: "5.0.0-beta.29",
   description: "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   main: "./dist/index.js",
   types: "dist/index.d.ts",
@@ -98886,7 +98908,7 @@ var package_default = {
     zod: "^4.4.3"
   },
   devDependencies: {
-    "@code-yeongyu/senpi": "2026.8.28-2",
+    "@code-yeongyu/senpi": "2026.8.30-2",
     "@oh-my-opencode/agents-md-core": "workspace:*",
     "@oh-my-opencode/ast-grep-mcp": "workspace:*",
     "@oh-my-opencode/boulder-state": "workspace:*",
@@ -98927,18 +98949,18 @@ var package_default = {
     typescript: "^7.0.2"
   },
   optionalDependencies: {
-    "oh-my-opencode-darwin-arm64": "5.0.0-beta.26",
-    "oh-my-opencode-darwin-x64": "5.0.0-beta.26",
-    "oh-my-opencode-darwin-x64-baseline": "5.0.0-beta.26",
-    "oh-my-opencode-linux-arm64": "5.0.0-beta.26",
-    "oh-my-opencode-linux-arm64-musl": "5.0.0-beta.26",
-    "oh-my-opencode-linux-x64": "5.0.0-beta.26",
-    "oh-my-opencode-linux-x64-baseline": "5.0.0-beta.26",
-    "oh-my-opencode-linux-x64-musl": "5.0.0-beta.26",
-    "oh-my-opencode-linux-x64-musl-baseline": "5.0.0-beta.26",
-    "oh-my-opencode-windows-arm64": "5.0.0-beta.26",
-    "oh-my-opencode-windows-x64": "5.0.0-beta.26",
-    "oh-my-opencode-windows-x64-baseline": "5.0.0-beta.26"
+    "oh-my-opencode-darwin-arm64": "5.0.0-beta.29",
+    "oh-my-opencode-darwin-x64": "5.0.0-beta.29",
+    "oh-my-opencode-darwin-x64-baseline": "5.0.0-beta.29",
+    "oh-my-opencode-linux-arm64": "5.0.0-beta.29",
+    "oh-my-opencode-linux-arm64-musl": "5.0.0-beta.29",
+    "oh-my-opencode-linux-x64": "5.0.0-beta.29",
+    "oh-my-opencode-linux-x64-baseline": "5.0.0-beta.29",
+    "oh-my-opencode-linux-x64-musl": "5.0.0-beta.29",
+    "oh-my-opencode-linux-x64-musl-baseline": "5.0.0-beta.29",
+    "oh-my-opencode-windows-arm64": "5.0.0-beta.29",
+    "oh-my-opencode-windows-x64": "5.0.0-beta.29",
+    "oh-my-opencode-windows-x64-baseline": "5.0.0-beta.29"
   },
   overrides: {
     "@earendil-works/pi-agent-core": "0.84.2",
@@ -98956,7 +98978,7 @@ var package_default = {
     "@code-yeongyu/comment-checker"
   ],
   patchedDependencies: {
-    "@code-yeongyu/senpi@2026.8.28-2": "patches/@code-yeongyu%2Fsenpi@2026.8.28-2.patch"
+    "@code-yeongyu/senpi@2026.8.30-2": "patches/@code-yeongyu%2Fsenpi@2026.8.30-2.patch"
   }
 };
 
@@ -99126,6 +99148,8 @@ function syncCachePackageJsonToIntent(pluginInfo) {
 import { existsSync as existsSync73 } from "fs";
 import { dirname as dirname29, join as join89 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
+// packages/omo-opencode/src/cli/config-manager/add-plugin-to-opencode-config.ts
+init_main();
 // packages/omo-opencode/src/cli/fallback-lane-policy.ts
 var EXCLUDED_FALLBACK_PROVIDERS = new Set(["openrouter", "opencode", "vercel"]);
 // packages/omo-opencode/src/startup-migration.ts
@@ -101013,7 +101037,6 @@ var TARGET_TOOLS = new Set([
   "context7_resolve-library-id",
   "context7_query-docs",
   "websearch_web_search_exa",
-  "context7_get-library-docs",
   "grep_app_searchgithub"
 ]);
 var AGENT_TOOLS = new Set([
@@ -124769,8 +124792,8 @@ function autoMigrateLegacyPluginEntry(overrideConfigDir) {
     if (legacyEntries.length === 0)
       return { migrated: false, from: null, to: null, configPath };
     const hasCanonical = plugins.some(isCanonicalEntry);
-    const from = legacyEntries[0];
-    const to = toCanonicalEntry(from);
+    const from = getPluginEntryName(legacyEntries[0]);
+    const to = getPluginEntryName(toCanonicalEntry(legacyEntries[0]));
     const migrated = migrateLegacyPluginEntry(configPath);
     if (!migrated)
       return { migrated: false, from: null, to: null, configPath };
@@ -160216,7 +160239,7 @@ Step 4: Construct permalink
 Tool 1: gh repo clone owner/repo \${TMPDIR:-/tmp}/repo -- --depth 1
 Tool 2: grep_app_searchGitHub(query: "function_name", repo: "owner/repo")
 Tool 3: gh api repos/owner/repo/commits/HEAD --jq '.sha'
-Tool 4: context7_get-library-docs(id, topic: "relevant-api")
+Tool 4: context7_query-docs(libraryId: id, query: "relevant-api")
 \`\`\`
 
 ---
@@ -160337,7 +160360,6 @@ Use OS-appropriate temp directory:
 - **TYPE B (Implementation)**: Suggested Calls 2-3 - Doc Discovery Required NO
 - **TYPE C (Context)**: Suggested Calls 2-3 - Doc Discovery Required NO
 - **TYPE D (Comprehensive)**: Suggested Calls 3-5 - Doc Discovery Required YES (Phase 0.5 first)
-| Request Type | Minimum Parallel Calls
 
 **Doc Discovery is SEQUENTIAL** (websearch \u2192 version check \u2192 sitemap \u2192 investigate).
 **Main phase is PARALLEL** once you know where to look.
@@ -165938,6 +165960,7 @@ function createLspMcpConfig(options = {}) {
     enabled: resolvedCommand.exists,
     cwd,
     environment: {
+      LSP_TOOLS_MCP_CWD: cwd,
       LSP_TOOLS_MCP_PROJECT_CONFIG: PROJECT_LSP_CONFIGS.map((configPath) => resolve44(cwd, configPath)).join(delimiter2),
       LSP_TOOLS_MCP_USER_CONFIG: resolve44(configDir, "lsp.json"),
       LSP_TOOLS_MCP_INSTALL_DECISIONS: resolve44(configDir, "lsp-install-decisions.json"),

package/dist/shared/index.d.ts

@@ -71,6 +71,7 @@ export * from "./runtime-fallback-retry-marker";
 export * from "./plugin-command-discovery";
 export { SessionCategoryRegistry } from "./session-category-registry";
 export * from "./plugin-identity";
+export * from "./plugin-entry-shape";
 export * from "./log-legacy-plugin-startup-warning";
 export * from "./legacy-workspace-migration";
 export * from "./task-system-enabled";

package/dist/shared/legacy-plugin-warning.d.ts

@@ -1,7 +1,8 @@
+import { type PluginEntry } from "./plugin-entry-shape";
 export interface LegacyPluginCheckResult {
     hasLegacyEntry: boolean;
     hasCanonicalEntry: boolean;
-    legacyEntries: string[];
+    legacyEntries: PluginEntry[];
     configPath: string | null;
 }
 export declare function checkForLegacyPluginEntry(overrideConfigDir?: string): LegacyPluginCheckResult;

package/dist/shared/plugin-entry-migrator.d.ts

@@ -1,3 +1,4 @@
-export declare function isLegacyEntry(entry: string): boolean;
-export declare function isCanonicalEntry(entry: string): boolean;
-export declare function toCanonicalEntry(entry: string): string;
+import { type PluginEntry } from "./plugin-entry-shape";
+export declare function isLegacyEntry(entry: PluginEntry): boolean;
+export declare function isCanonicalEntry(entry: PluginEntry): boolean;
+export declare function toCanonicalEntry(entry: PluginEntry): PluginEntry;

package/dist/shared/plugin-entry-shape.d.ts

@@ -0,0 +1,6 @@
+export type PluginEntryOptions = Record<string, unknown>;
+export type PluginTupleEntry = readonly [string, PluginEntryOptions];
+export type PluginEntry = string | PluginTupleEntry;
+export declare function isPluginTupleEntry(entry: unknown): entry is PluginTupleEntry;
+export declare function getPluginEntryName(entry: PluginEntry): string;
+export declare function withPluginEntryName(entry: PluginEntry, name: string): PluginEntry;

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

@@ -1,243 +1,103 @@
 ---
 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."
+description: "Expert data processing with a hybrid engine strategy: resident-kernel engines first - DuckDB plus a resident Python stack (Polars/numpy/matplotlib) in persistent js/py eval kernels where the harness has them, bun/uv one-shots elsewhere - and per-action placement judgment (in-memory vs streaming vs remote-in-place). Triggers: 'analyze the data', 'what is in this CSV/parquet/json', 'summarize this', 'group by', 'filter rows', 'sort by', 'join these files', 'merge datasets', 'time series trend', '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.
+# Data Scientist: Hybrid-Engine Data Processing
+
+Answer data questions through the cheapest engine and surface that can prove the answer, and
+decide where the computation should live before touching the data.
+
+## Execution surfaces: resident kernel first
+
+A persistent REPL/eval kernel (many harnesses expose one for JavaScript and Python) is the
+default surface. Reason: each one-shot process pays roughly a second of spawn-plus-import
+overhead and re-scans the input file, while a resident connection amortizes both — after a
+one-time load, repeat queries return in milliseconds. Exploration is repeat queries, so this
+difference dominates the session.
+
+1. **JavaScript kernel (Bun)**: run `scripts/ensure-js-deps.sh` once; it prints the absolute
+   import path for `@duckdb/node-api`. Dynamic-import it, connect once, query across cells.
+2. **Python kernel**: the default surface for Python work. duckdb/numpy/matplotlib are
+   typically resident; Polars and pyarrow come from `scripts/ensure-py-deps.sh`, which
+   installs them once into a user cache keyed to the kernel's interpreter —
+   `sys.path.insert` the printed directory and import. The interpreter itself is never
+   mutated.
+3. **uv lane** (`uv run --with ...`): isolation for a heavy or crash-prone one-shot that
+   should not take the kernel down.
+4. **No kernel** (plain-shell harness): the same engines as one-shots — `bun -e` for
+   DuckDB-js, `uv run python -c` for the Python stack — batching several questions per
+   process.
+
+Per-surface patterns and pitfalls: read `references/execution-surfaces.md` before first use.
+
+## Engine selection
+
+- **DuckDB** for SQL-shaped work: direct file queries, joins, aggregation, subqueries,
+  window functions. It queries CSV/Parquet/JSON in place without loading, spills to disk
+  past its memory limit, and reads remote files with the same syntax.
+- **Polars** when the pipeline is DataFrame-shaped: expression-chain transforms, reshapes,
+  streaming datasets past RAM — resident in the Python kernel via `ensure-py-deps.sh`.
+  Read `references/polars-lane.md` — the current 1.x API differs from widely-memorized
+  older spellings.
+- **numpy** when numeric work goes beyond SQL/DataFrame aggregation: statistical tests,
+  linear algebra, FFT, random sampling.
+- **matplotlib** for every chart — read `references/visualization.md` first; it carries the
+  quality bar and a mandatory visual check.
+
+Performance folklore ("X is Nx faster at filtering") varies with data shape, cardinality,
+and hardware. When the engine choice materially matters, measure on the actual data instead
+of trusting remembered multipliers.
+
+## Placement: decide where the computation lives
+
+Probe before you compute — one cell: file size, free RAM, and (when unclear) a row count via
+a direct scan. Then place the work:
+
+- **Load into memory** when the working set stays within roughly a quarter of free RAM AND
+  the session will run repeated queries: `CREATE TABLE t AS SELECT ...` (or a collected
+  DataFrame) once, then iterate. One scan up front converts every later query from a file
+  re-scan into milliseconds.
+- **Query in place / stream** when the question is single-pass, or the data exceeds RAM:
+  DuckDB reads files directly (`FROM 'data.csv'`); past RAM, cap DuckDB's memory and let it
+  spill, or use Polars' streaming engine in the Python kernel. NEVER load a larger-than-RAM
+  dataset fully into memory — swapping stalls the whole machine, while streaming merely
+  takes longer.
+- **Query remotely, in place** when the data lives elsewhere: DuckDB reads http(s)/S3
+  Parquet and CSV with projection and predicate pushdown, so fetch the columns and rows the
+  question needs, never the whole file. When data sits on another machine you can execute
+  on, ship the query to the data and return the small result. Rule: result much smaller
+  than data — move the query; repeated local iteration planned — move a pruned copy of the
+  data once.
+
+Sizing heuristics and recipes: `references/placement.md`.
+
+## Hard rules
+
+- **NEVER use pandas.** DuckDB and Polars beat it decisively on every workload this skill
+  covers, and the environments this skill assumes do not ship it — `.df()` on a DuckDB
+  result raises unless pandas is installed; convert with `.pl()` via Arrow instead.
+- Excel files are not read directly: export to CSV or Parquet first.
+
+## Output contract
+
+Answer the question; report row counts and timing for anything heavy; then stop — no bonus
+charts, no extra exploration passes beyond what the question needed. Chart when asked, or
+when the answer is a shape (trend, distribution, comparison) that prose cannot carry — then
+follow `references/visualization.md` including its visual QA step.
+
+## References
+
+| Read | When |
+| --- | --- |
+| `references/execution-surfaces.md` | before the first query on any surface: kernel patterns, one-shot recipes, escalation rules |
+| `references/polars-lane.md` | DataFrame-shaped pipeline or data past RAM: current API, Arrow handoff, package sets |
+| `references/placement.md` | before heavy or remote work: sizing probe, memory limits, remote reads |
+| `references/visualization.md` | before any chart: type selection, quality bar, CJK fonts, visual QA |
+| `references/uv-setup.md` | uv missing or broken on this machine |
+
+## CLI fallback
+
+When no kernel or REPL surface exists, `uv run scripts/quick-query.py <file> [SQL]`
+(`--filter <polars-sql-expr>`, `--describe`) answers ad-hoc questions with zero code.
+Supports CSV, Parquet, JSON, NDJSON.