pi-skill-search 0.1.0

package/skills/pdf/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: pdf
+description: Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.
+---
+
+# PDF Processing Guide
+
+## Overview
+
+This guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see reference.md. If you need to fill out a PDF form, read forms.md and follow its instructions.
+
+## Quick Start
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+# Read a PDF
+reader = PdfReader("document.pdf")
+print(f"Pages: {len(reader.pages)}")
+
+# Extract text
+text = ""
+for page in reader.pages:
+    text += page.extract_text()
+```
+
+## Python Libraries
+
+### pypdf - Basic Operations
+
+#### Merge PDFs
+```python
+from pypdf import PdfWriter, PdfReader
+
+writer = PdfWriter()
+for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
+    reader = PdfReader(pdf_file)
+    for page in reader.pages:
+        writer.add_page(page)
+
+with open("merged.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### pdfplumber - Text and Table Extraction
+
+#### Extract Text with Layout
+```python
+import pdfplumber
+
+with pdfplumber.open("document.pdf") as pdf:
+    for page in pdf.pages:
+        text = page.extract_text()
+        print(text)
+```
+
+#### Extract Tables
+```python
+with pdfplumber.open("document.pdf") as pdf:
+
+# Combine all tables
+if all_tables:
+    combined_df = pd.concat(all_tables, ignore_index=True)
+    combined_df.to_excel("extracted_tables.xlsx", index=False)
+```
+
+### reportlab - Create PDFs
+
+#### Basic PDF Creation
+```python
+from reportlab.lib.pagesizes import letter
+from reportlab.pdfgen import canvas
+
+c = canvas.Canvas("hello.pdf", pagesize=letter)
+width, height = letter
+
+# Add text
+c.drawString(100, height - 100, "Hello World!")
+c.drawString(100, height - 120, "This is a PDF created with reportlab")
+
+# Add a line
+c.line(100, height - 140, 400, height - 140)
+
+# Save
+c.save()
+```
+
+#### Create PDF with Multiple Pages
+```python
+from reportlab.lib.pagesizes import letter
+from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
+from reportlab.lib.styles import getSampleStyleSheet
+
+doc = SimpleDocTemplate("report.pdf", pagesize=letter)
+styles = getSampleStyleSheet()
+story = []
+
+# Add content
+title = Paragraph("Report Title", styles['Title'])
+story.append(title)
+story.append(Spacer(1, 12))
+
+body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
+story.append(body)
+story.append(PageBreak())
+
+# Page 2
+story.append(Paragraph("Page 2", styles['Heading1']))
+story.append(Paragraph("Content for page 2", styles['Normal']))
+
+# Build PDF
+doc.build(story)
+```

package/skills/peer-review/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: peer-review
+description: Structured manuscript/grant review with checklist-based evaluation. Use when writing formal peer reviews with specific criteria methodology assessment, statistical validity, reporting standards compliance (CONSORT/STROBE), and constructive feedback. Best for actual review writing, manuscript revision. For evaluating claims/evidence quality use scientific-critical-thinking; for quantitative scoring frameworks use scholar-evaluation.
+---
+
+# Scientific Critical Evaluation and Peer Review
+
+## Overview
+
+Peer review is a systematic process for evaluating scientific manuscripts. Assess methodology, statistics, design, reproducibility, ethics, and reporting standards. Apply this skill for manuscript and grant review across disciplines with constructive, rigorous evaluation.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Conducting peer review of scientific manuscripts for journals
+- Evaluating grant proposals and research applications
+- Assessing methodology and experimental design rigor
+- Reviewing statistical analyses and reporting standards
+- Evaluating reproducibility and data availability
+- Checking compliance with reporting guidelines (CONSORT, STROBE, PRISMA)
+- Providing constructive feedback on scientific writing
+
+## Visual Enhancement with Scientific Schematics
+
+**When creating documents with this skill, always consider adding scientific diagrams and schematics to enhance visual communication.**
+
+If your document does not already contain schematics or diagrams:
+- Use the **scientific-schematics** skill to generate AI-powered publication-quality diagrams
+- Simply describe your desired diagram in natural language
+- Nano Banana Pro will automatically generate, review, and refine the schematic
+
+**For new documents:** Scientific schematics should be generated by default to visually represent key concepts, workflows, architectures, or relationships described in the text.
+
+**How to generate schematics:**
+```bash
+python scripts/generate_schematic.py "your diagram description" -o figures/output.png
+```
+
+## Peer Review Workflow
+
+Conduct peer review systematically through the following stages, adapting depth and focus based on the manuscript type and discipline.
+
+### Stage 1: Initial Assessment
+
+Begin with a high-level evaluation to determine the manuscript's scope, novelty, and overall quality.
+
+**Key Questions:**
+- What is the central research question or hypothesis?
+- What are the main findings and conclusions?
+- Is the work scientifically sound and significant?
+- Is the work appropriate for the intended venue?
+- Are there any immediate major flaws that would preclude publication?
+
+**Output:** Brief summary (2-3 sentences) capturing the manuscript's essence and initial impression.
+
+### Stage 2: Detailed Section-by-Section Review
+
+Conduct a thorough evaluation of each manuscript section, documenting specific concerns and strengths.
+
+#### Abstract and Title
+- **Accuracy:** Does the abstract accurately reflect the study's content and conclusions?
+- **Clarity:** Is the title specific, accurate, and informative?
+- **Completeness:** Are key findings and methods summarized appropriately?
+- **Accessibility:** Is the abstract comprehensible to a broad scientific audience?
+
+#### Introduction
+- **Context:** Is the background information adequate and current?
+- **Rationale:** Is the research question clearly motivated and justified?
+- **Novelty:** Is the work's originality and significance clearly articulated?
+- **Literature:** Are relevant prior studies appropriately cited?
+
+### Stage 3: Methodological and Statistical Rigor
+
+Evaluate the technical quality and rigor of the research with particular attention to common pitfalls.
+
+**Statistical Assessment:**
+- Are statistical assumptions met (normality, independence, homoscedasticity)?
+- Are effect sizes reported alongside p-values?
+- Is multiple testing correction applied appropriately?
+- Are confidence intervals provided?
+- Is sample size justified with power analysis?
+- Are parametric vs. non-parametric tests chosen appropriately?
+- Are missing data handled properly?
+- Are exploratory vs. confirmatory analyses distinguished?
+
+**Experimental Design:**
+
+### Stage 4: Reproducibility and Transparency
+
+Assess whether the research meets modern standards for reproducibility and open science.
+
+**Data Availability:**
+- Are raw data deposited in appropriate repositories?
+- Are accession numbers provided for public databases?
+- Are data sharing restrictions justified (e.g., patient privacy)?
+- Are data formats standard and accessible?
+
+**Code and Materials:**
+- Is analysis code made available (GitHub, Zenodo, etc.)?
+- Are unique materials available or described sufficiently for recreation?
+- Are protocols detailed in sufficient depth?
+
+
+### Stage 5: Figure and Data Presentation
+
+Evaluate the quality, clarity, and integrity of data visualization.
+
+**Quality Checks:**
+- Are figures high resolution and clearly labeled?
+- Are axes properly labeled with units?
+- Are error bars defined (SD, SEM, CI)?
+- Are statistical significance indicators explained?
+- Are color schemes appropriate and accessible (colorblind-friendly)?
+- Are scale bars included for images?
+- Is data visualization appropriate for the data type?
+
+**Integrity Checks:**
+
+

package/skills/pennylane/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: pennylane
+description: Hardware-agnostic quantum ML framework with automatic differentiation. Use when training quantum circuits via gradients, building hybrid quantum-classical models, or needing device portability across IBM/Google/Rigetti/IonQ. Best for variational algorithms (VQE, QAOA), quantum neural networks, and integration with PyTorch/JAX/TensorFlow. For hardware-specific optimizations use qiskit (IBM) or cirq (Google); for open quantum systems use qutip.
+---
+
+# PennyLane
+
+## Overview
+
+PennyLane is a quantum computing library that enables training quantum computers like neural networks. It provides automatic differentiation of quantum circuits, device-independent programming, and seamless integration with classical machine learning frameworks.
+
+# IBM Quantum
+uv pip install pennylane-qiskit
+
+# Amazon Braket
+uv pip install amazon-braket-pennylane-plugin
+
+# Google Cirq
+uv pip install pennylane-cirq
+
+# Rigetti Forest
+uv pip install pennylane-rigetti
+
+# IonQ
+uv pip install pennylane-ionq
+```
+
+## Quick Start
+
+Build a quantum circuit and optimize its parameters:
+
+```python
+import pennylane as qml
+from pennylane import numpy as np
+
+# Create device
+dev = qml.device('default.qubit', wires=2)
+
+# Define quantum circuit
+@qml.qnode(dev)
+def circuit(params):
+    qml.RX(params[0], wires=0)
+    qml.RY(params[1], wires=1)
+    qml.CNOT(wires=[0, 1])
+    return qml.expval(qml.PauliZ(0))
+
+# Optimize parameters
+opt = qml.GradientDescentOptimizer(stepsize=0.1)
+params = np.array([0.1, 0.2], requires_grad=True)
+
+for i in range(100):
+    params = opt.step(circuit, params)
+```
+
+## Core Capabilities
+
+### 1. Quantum Circuit Construction
+
+Build circuits with gates, measurements, and state preparation. See `(see docs)` for:
+- Single and multi-qubit gates
+- Controlled operations and conditional logic
+- Mid-circuit measurements and adaptive circuits
+- Various measurement types (expectation, probability, samples)
+- Circuit inspection and debugging
+
+### 2. Quantum Machine Learning
+
+Create hybrid quantum-classical models. See `(see docs)` for:
+- Integration with PyTorch, JAX, TensorFlow
+- Quantum neural networks and variational classifiers
+- Data encoding strategies (angle, amplitude, basis, IQP)
+- Training hybrid models with backpropagation
+- Transfer learning with quantum circuits
+
+### 3. Quantum Chemistry
+
+Simulate molecules and compute ground state energies. See `(see docs)` for:
+- Molecular Hamiltonian generation
+- Variational Quantum Eigensolver (VQE)
+- UCCSD ansatz for chemistry
+- Geometry optimization and dissociation curves
+- Molecular property calculations
+
+### 4. Device Management
+
+Execute on simulators or quantum hardware. See `(see docs)` for:
+- Built-in simulators (default.qubit, lightning.qubit, default.mixed)
+- Hardware plugins (IBM, Amazon Braket, Google, Rigetti, IonQ)
+- Device selection and configuration
+- Performance optimization and caching
+- GPU acceleration and JIT compilation
+
+### 5. Optimization
+
+Train quantum circuits with various optimizers. See `(see docs)` for:
+- Built-in optimizers (Adam, gradient descent, momentum, RMSProp)
+- Gradient computation methods (backprop, parameter-shift, adjoint)
+- Variational algorithms (VQE, QAOA)
+- Training strategies (learning rate schedules, mini-batches)
+- Handling barren plateaus and local minima
+
+### 6. Advanced Features
+
+Leverage templates, transforms, and compilation. See `(see docs)` for:
+- Circuit templates and layers
+- Transforms and circuit optimization
+- Pulse-level programming
+- Catalyst JIT compilation
+- Noise models and error mitigation
+- Resource estimation
+
+## Common Workflows
+
+### Train a Variational Classifier
+
+```python
+# 1. Define ansatz
+
+

package/skills/phylogenetics/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: phylogenetics
+description: Build and analyze phylogenetic trees using MAFFT (multiple alignment), IQ-TREE 2 (maximum likelihood), and FastTree (fast NJ/ML). Visualize with ETE3 or FigTree. For evolutionary analysis, microbial genomics, viral phylodynamics, protein family analysis, and molecular clock studies.
+---
+
+# Phylogenetics
+
+## Overview
+
+Phylogenetic analysis reconstructs the evolutionary history of biological sequences (genes, proteins, genomes) by inferring the branching pattern of descent. This skill covers the standard pipeline:
+
+1. **MAFFT** — Multiple sequence alignment
+2. **IQ-TREE 2** — Maximum likelihood tree inference with model selection
+3. **FastTree** — Fast approximate maximum likelihood (for large datasets)
+4. **ETE3** — Python library for tree manipulation and visualization
+
+**Installation:**
+```bash
+# Conda (recommended for CLI tools)
+conda install -c bioconda mafft iqtree fasttree
+pip install ete3
+```
+
+## When to Use This Skill
+
+Use phylogenetics when:
+
+- **Evolutionary relationships**: Which organism/gene is most closely related to my sequence?
+- **Viral phylodynamics**: Trace outbreak spread and estimate transmission dates
+- **Protein family analysis**: Infer evolutionary relationships within a gene family
+- **Horizontal gene transfer detection**: Identify genes with discordant species/gene trees
+- **Ancestral sequence reconstruction**: Infer ancestral protein sequences
+- **Molecular clock analysis**: Estimate divergence dates using temporal sampling
+- **GWAS companion**: Place variants in evolutionary context (e.g., SARS-CoV-2 variants)
+- **Microbiology**: Species phylogeny from 16S rRNA or core genome phylogeny
+
+## Standard Workflow
+
+### 1. Multiple Sequence Alignment with MAFFT
+
+```python
+import subprocess
+import os
+
+def run_mafft(input_fasta: str, output_fasta: str, method: str = "auto",
+               n_threads: int = 4) -> str:
+    """
+    Align sequences with MAFFT.
+
+    Args:
+        input_fasta: Path to unaligned FASTA file
+        output_fasta: Path for aligned output
+        method: 'auto' (auto-select), 'einsi' (accurate), 'linsi' (accurate, slow),
+
+# MAFFT method selection guide:
+# Few sequences (<200), accurate: linsi or einsi
+# Many sequences (<1000), moderate: fftnsi
+# Large datasets (>1000): fftns or auto
+# Ultra-fast (>10000): mafft --retree 1
+```
+
+### 2. Trim Alignment (Optional but Recommended)
+
+```python
+def trim_alignment_trimal(aligned_fasta: str, output_fasta: str,
+                            method: str = "automated1") -> str:
+    """
+    Trim poorly aligned columns with TrimAl.
+
+    Methods:
+    - 'automated1': Automatic heuristic (recommended)
+    - 'gappyout': Remove gappy columns
+    - 'strict': Strict gap threshold
+    """
+    cmd = ["trimal", f"-{method}", "-in", aligned_fasta, "-out", output_fasta, "-fasta"]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+### 3. IQ-TREE 2 — Maximum Likelihood Tree
+
+```python
+def run_iqtree(aligned_fasta: str, output_prefix: str,
+                model: str = "TEST", bootstrap: int = 1000,
+                n_threads: int = 4, extra_args: list = None) -> dict:
+    """
+    Build a maximum likelihood tree with IQ-TREE 2.
+
+    Args:
+        aligned_fasta: Aligned FASTA file
+        output_prefix: Prefix for output files
+        model: 'TEST' for automatic model selection, or specify (e.g., 'GTR+G' for DNA,
+               'LG+G4' for proteins, 'JTT+G' for proteins)
+        bootstrap: Number of ultrafast bootstrap replicates (1000 recommended)
+
+# IQ-TREE model selection guide:
+# DNA:     TEST → GTR+G, HKY+G, TrN+G
+# Protein: TEST → LG+G4, WAG+G, JTT+G, Q.pfam+G
+# Codon:   TEST → MG+F3X4
+
+# For temporal (molecular clock) analysis, add:
+# extra_args = ["--date", "dates.txt", "--clock-test", "--date-CI", "95"]
+
+

package/skills/pi-extension-lifecycle/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: pi-extension-lifecycle
+description: Pi extension lifecycle and registration patterns. Use when adding or reviewing extension tools, commands, resources, providers, event handlers, session hooks, or context-sensitive Pi API usage.
+---
+
+
+# pi-extension-lifecycle
+
+Use this skill when working on Pi extension registration or lifecycle behavior.
+
+## Source patterns distilled
+
+- Pi core: `source/pi-mono/packages/coding-agent/src/core/extensions/types.ts`, `loader.ts`, `runner.ts`
+- Pi examples: `source/pi-mono/packages/coding-agent/examples/extensions/`
+- pi-crew extension entry: `src/extension/register.ts`, `src/extension/registration/*.ts`
+
+## Rules
+
+- Register tools, commands, shortcuts, widgets, providers, and event handlers from the extension factory or lifecycle callbacks.
+- Tool definitions should use a TypeBox schema and an `execute(toolCallId, params, signal, onUpdate, ctx)` handler.
+- Use fresh `ExtensionContext`/`ExtensionCommandContext` after session replacement (`newSession`, `fork`, `switchSession`, `reload`). Do not retain old context references for later work.
+- For session-scoped work, derive session identity from `ctx.sessionManager.getSessionId()` and pass it into pi-crew `TeamContext`.
+- Prefer small registration modules under `src/extension/registration/`; keep `index.ts` minimal.
+- Clean up intervals, event subscriptions, child processes, and watchers on session switch/shutdown.
+- Wrap optional Pi API hooks in compatibility checks/try-catch when supporting older Pi versions.
+
+## Anti-patterns
+
+- Do not use stale context objects after session switch.
+- Do not register duplicate tool/command names and assume override behavior.
+- Do not perform blocking filesystem or network work inside extension render callbacks.
+- Do not add hardcoded global keybindings without config or collision review.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+npm test
+```
+

package/skills/plan/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: plan
+description: Strategic planning with optional interview workflow
+---
+
+- User wants autonomous end-to-end execution -- use `autopilot` instead
+- User wants to start coding immediately with a clear task -- use `ralph` or delegate to executor
+- User asks a simple question that can be answered directly -- just answer it
+- Task is a single focused fix with obvious scope -- use an execution skill instead of running it from this planning module
+
+Jumping into code without understanding requirements leads to rework, scope creep, and missed edge cases. Plan provides structured requirements gathering, expert analysis, and quality-gated plans so that execution starts from a solid foundation. The consensus mode adds multi-perspective validation for high-stakes projects.
+
+- Auto-detect interview vs direct mode based on request specificity
+- Ask one question at a time during interviews -- never batch multiple questions
+- Gather codebase facts via `explore` agent before asking the user about them
+- Plans must meet quality standards: 80%+ claims cite file/line, 90%+ criteria are testable
+- Consensus mode runs fully automated by default; add `--interactive` to enable user prompts at draft review and final approval steps
+- Consensus mode uses RALPLAN-DR short mode by default; switch to deliberate mode with `--deliberate` or when the request explicitly signals high risk (auth/security, data migration, destructive/irreversible changes, production incident, compliance/PII, public API breakage)
+- **Planning/execution boundary:** planning modes inspect context and produce plans/specs/proposals only. They MUST mark artifacts as `pending approval` unless the user has explicitly opted into execution in the current turn or via the structured approval UI. Before explicit execution approval, planning modes MUST NOT run mutation-oriented shell commands, edit source files, commit, push, open PRs, invoke execution skills, or delegate implementation tasks.
+
+### Mode Selection
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Interview | Default for broad requests | Interactive requirements gathering |
+| Direct | `--direct`, or detailed request | Skip interview, generate plan directly |
+| Consensus | `--consensus`, "ralplan" | Planner -> Architect -> Critic loop until agreement with RALPLAN-DR structured deliberation (short by default, `--deliberate` for high-risk); add `--interactive` for user prompts at draft and approval steps |
+| Review | `--review`, "review this plan" | Critic evaluation of existing plan |
+
+### Interview Mode (broad/vague requests)
+
+1. **Classify the request**: Broad (vague verbs, no specific files, touches 3+ areas) triggers interview mode
+2. **Ask one focused question** using `AskUserQuestion` for preferences, scope, and constraints
+3. **Gather codebase facts first**: Before asking "what patterns does your code use?", spawn an `explore` agent to find out, then ask informed follow-up questions
+4. **Build on answers**: Each question builds on the previous answer
+5. **Consult Analyst** (Opus) for hidden requirements, edge cases, and risks
+6. **Create plan** when the user signals readiness: "create the plan", "I'm ready", "make it a work plan"
+
+### Direct Mode (detailed requests)
+
+1. **Quick Analysis**: Optional brief Analyst consultation
+2. **Create plan**: Generate comprehensive work plan immediately
+3. **Review** (optional): Critic review if requested
+
+### Consensus Mode (`--consensus` / "ralplan")
+
+**RALPLAN-DR modes**: **Short** (default, bounded structure) and **Deliberate** (for `--deliberate` or explicit high-risk requests). Both modes keep the same Planner -> Architect -> Critic sequence and the same `AskUserQuestion` gates.
+
+**Provider overrides (supported when the provider CLI is installed):**
+- `--architect codex` — replace the Claude Architect pass with `omc ask codex --agent-prompt architect "..."` for implementation-heavy architecture review
+- `--critic codex` — replace the Claude Critic pass with `omc ask codex --agent-prompt critic "..."` for an external review pass before execution
+- If the requested provider is unavailable, briefly note that and continue with the default Claude Architect/Critic step for that stage
+
+**State lifecycle**: The persistent-mode stop hook uses `ralplan-state.json` to enforce continuation during the consensus loop. The skill **MUST** manage this state:
+- **On entry**: Call `state_write(mode="ralplan", active=true, session_id=<current_session_id>)` before step 1
+- **On handoff to execution** (approval → ralph/team): Call `state_write(mode="ralplan", active=false, session_id=<current_session_id>)`. Do NOT use `state_clear` here — `state_clear` writes a 30-second cancel signal that disables stop-hook enforcement for ALL modes, leaving the newly launched execution mode unprotected.
+- **On true terminal exit** (rejection, non-interactive plan output, error/abort): Call `state_clear(mode="ralplan", session_id=<current_session_id>)` — no execution mode follows, so the cancel signal window is harmless.
+- Do NOT clear during intermediate steps like Critic approval or max-iteration presentation, as the user may still select "Request changes".
+
+Without cleanup, the stop hook blocks all subsequent stops with `[RALPLAN - CONSENSUS PLANNING]` reinforcement messages even after the consensus workflow has finished. Always pass `session_id` to avoid clearing other concurrent sessions' state.
+
+1. **Planner** creates initial plan and a compact **RALPLAN-DR summary** before any Architect review. The summary **MUST** include:
+   - **Principles** (3-5)
+   - **Decision Drivers** (top 3)
+
+

package/skills/polars/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: polars
+description: Fast in-memory DataFrame library for datasets that fit in RAM. Use when pandas is too slow but data still fits in memory. Lazy evaluation, parallel execution, Apache Arrow backend. Best for 1-100GB datasets, ETL pipelines, faster pandas replacement. For larger-than-RAM data use dask or vaex.
+---
+
+# Polars
+
+## Overview
+
+Polars is a lightning-fast DataFrame library for Python and Rust built on Apache Arrow. Work with Polars' expression-based API, lazy evaluation framework, and high-performance data manipulation capabilities for efficient data processing, pandas migration, and data pipeline optimization.
+
+## Quick Start
+
+### Installation and Basic Usage
+
+Install Polars:
+```python
+uv pip install polars
+```
+
+Basic DataFrame creation and operations:
+```python
+import polars as pl
+
+# Create DataFrame
+df = pl.DataFrame({
+    "name": ["Alice", "Bob", "Charlie"],
+    "age": [25, 30, 35],
+    "city": ["NY", "LA", "SF"]
+})
+
+# Select columns
+df.select("name", "age")
+
+# Filter rows
+df.filter(pl.col("age") > 25)
+
+# Add computed columns
+df.with_columns(
+    age_plus_10=pl.col("age") + 10
+)
+```
+
+## Core Concepts
+
+### Expressions
+
+Expressions are the fundamental building blocks of Polars operations. They describe transformations on data and can be composed, reused, and optimized.
+
+**Key principles:**
+- Use `pl.col("column_name")` to reference columns
+- Chain methods to build complex transformations
+- Expressions are lazy and only execute within contexts (select, with_columns, filter, group_by)
+
+**Example:**
+```python
+# Expression-based computation
+df.select(
+    pl.col("name"),
+    (pl.col("age") * 12).alias("age_in_months")
+)
+```
+
+### Lazy vs Eager Evaluation
+
+**Eager (DataFrame):** Operations execute immediately
+```python
+df = pl.read_csv("file.csv")  # Reads immediately
+result = df.filter(pl.col("age") > 25)  # Executes immediately
+```
+
+**Lazy (LazyFrame):** Operations build a query plan, optimized before execution
+```python
+lf = pl.scan_csv("file.csv")  # Doesn't read yet
+result = lf.filter(pl.col("age") > 25).select("name", "age")
+df = result.collect()  # Now executes optimized query
+```
+
+
+## Common Operations
+
+### Select
+Select and manipulate columns:
+```python
+# Select specific columns
+df.select("name", "age")
+
+# Select with expressions
+df.select(
+    pl.col("name"),
+    (pl.col("age") * 2).alias("double_age")
+)
+
+# Select all columns matching a pattern
+df.select(pl.col("^.*_id$"))
+```
+
+### Filter
+Filter rows by conditions:
+```python
+# Single condition
+df.filter(pl.col("age") > 25)
+
+# Multiple conditions (cleaner than using &)
+df.filter(
+    pl.col("age") > 25,
+    pl.col("city") == "NY"
+)
+
+# Complex conditions
+df.filter(
+    (pl.col("age") > 25) | (pl.col("city") == "LA")
+)
+```