pi-skill-search 0.1.0

package/skills/torch-geometric/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: torch-geometric
+description: "Guide for building Graph Neural Networks with PyTorch Geometric (PyG). Use this skill whenever the user asks about graph neural networks, GNNs, node classification, link prediction, graph classification, message passing networks, heterogeneous graphs, neighbor sampling, or any task involving torch_geometric / PyG. Also trigger when you see imports from torch_geometric, or the user mentions graph convolutions (GCN, GAT, GraphSAGE, GIN), graph data structures, or working with relational/network data. Even if the user just says 'graph learning' or 'geometric deep learning', use this skill."
+---
+
+# PyTorch Geometric (PyG)
+
+PyG is the standard library for Graph Neural Networks built on PyTorch. It provides data structures for graphs, 60+ GNN layer implementations, scalable mini-batch training, and support for heterogeneous graphs.
+
+Install: `uv add torch_geometric` (or `uv pip install torch_geometric`; requires PyTorch). Optional: `pyg-lib`, `torch-scatter`, `torch-sparse`, `torch-cluster` for accelerated ops.
+
+## Core Concepts
+
+### Graph Data: `Data` and `HeteroData`
+
+A graph lives in a `Data` object. The key attributes:
+
+```python
+from torch_geometric.data import Data
+
+data = Data(
+    x=node_features,          # [num_nodes, num_node_features]
+    edge_index=edge_index,     # [2, num_edges] — COO format, dtype=torch.long
+    edge_attr=edge_features,   # [num_edges, num_edge_features]
+    y=labels,                  # node-level [num_nodes, *] or graph-level [1, *]
+    pos=positions,             # [num_nodes, num_dimensions] (for point clouds/spatial)
+)
+```
+
+# If edges are [[src1, dst1], [src2, dst2], ...] — transpose first:
+edge_index = edge_pairs.t().contiguous()
+```
+
+For undirected graphs, include both directions: edge (0,1) needs both `[0,1]` and `[1,0]` in edge_index.
+
+For heterogeneous graphs, use `HeteroData` — see the Heterogeneous Graphs section below.
+
+### Datasets
+
+PyG bundles many standard datasets that auto-download and preprocess:
+
+```python
+from torch_geometric.datasets import Planetoid, TUDataset
+
+# Single-graph node classification (Cora, Citeseer, Pubmed)
+dataset = Planetoid(root='./data', name='Cora')
+data = dataset[0]  # single graph with train/val/test masks
+
+# Multi-graph classification (ENZYMES, MUTAG, IMDB-BINARY, etc.)
+dataset = TUDataset(root='./data', name='ENZYMES')
+# dataset[0], dataset[1], ... are individual graphs
+```
+
+Common datasets by task:
+- **Node classification**: Planetoid (Cora/Citeseer/Pubmed), OGB (ogbn-arxiv, ogbn-products, ogbn-mag)
+- **Graph classification**: TUDataset (MUTAG, ENZYMES, PROTEINS, IMDB-BINARY), OGB (ogbg-molhiv)
+- **Link prediction**: OGB (ogbl-collab, ogbl-citation2)
+- **Molecular**: QM7, QM9, MoleculeNet
+- **Point cloud/mesh**: ShapeNet, ModelNet10/40, FAUST
+
+### Transforms
+
+Transforms preprocess or augment graph data, analogous to torchvision transforms:
+
+```python
+import torch_geometric.transforms as T
+
+# Common transforms
+T.NormalizeFeatures()    # Row-normalize node features to sum to 1
+T.ToUndirected()         # Add reverse edges to make graph undirected
+T.AddSelfLoops()         # Add self-loop edges
+T.KNNGraph(k=6)          # Build k-NN graph from point cloud positions
+T.RandomJitter(0.01)     # Random noise augmentation on positions
+T.Compose([...])         # Chain multiple transforms
+
+# Apply as pre_transform (once, saved to disk) or transform (every access)
+dataset = ShapeNet(root='./data', pre_transform=T.KNNGraph(k=6),
+                   transform=T.RandomJitter(0.01))
+```
+
+## Building GNN Models
+
+### Quick Start: Using Built-in Layers
+
+The fastest way to build a GNN — stack conv layers from `torch_geometric.nn`:
+
+```python
+import torch
+import torch.nn.functional as F
+from torch_geometric.nn import GCNConv
+
+class GCN(torch.nn.Module):
+    def __init__(self, in_channels, hidden_channels, out_channels):
+        super().__init__()
+        self.conv1 = GCNConv(in_channels, hidden_channels)
+        self.conv2 = GCNConv(hidden_channels, out_channels)
+
+
+### Choosing a Conv Layer
+
+Pick based on your task and graph structure:
+
+| Layer | Best for | Key idea |
+|-------|----------|----------|
+| `GCNConv` | Homogeneous, semi-supervised node classification | Spectral-inspired, degree-normalized aggregation |
+| `GATConv` / `GATv2Conv` | When neighbor importance varies | Attention-weighted messages |
+| `SAGEConv` | Large graphs, inductive settings | Sampling-friendly, learnable aggregation |
+| `GINConv` | Graph classification, maximizing expressiveness | As powerful as WL test |
+| `TransformerConv` | Rich edge features, complex interactions | Multi-head attention with edge features |
+| `EdgeConv` | Point clouds, dynamic graphs | MLP on edge features (x_i, x_j - x_i) |
+| `RGCNConv` | Heterogeneous with many relation types | Relation-specific weight matrices |
+| `HGTConv` | Heterogeneous graphs | Type-specific attention |
+
+All conv layers accept `(x, edge_index)` at minimum. Many also accept `edge_attr` for edge features.
+
+### Lazy Initialization
+
+

package/skills/torchdrug/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: torchdrug
+description: PyTorch-native graph neural networks for molecules and proteins. Use when building custom GNN architectures for drug discovery, protein modeling, or knowledge graph reasoning. Best for custom model development, protein property prediction, retrosynthesis. For pre-trained models and diverse featurizers use deepchem; for benchmark datasets use pytdc.
+---
+
+# TorchDrug
+
+## Overview
+
+TorchDrug is a comprehensive PyTorch-based machine learning toolbox for drug discovery and molecular science. Apply graph neural networks, pre-trained models, and task definitions to molecules, proteins, and biological knowledge graphs, including molecular property prediction, protein modeling, knowledge graph reasoning, molecular generation, retrosynthesis planning, with 40+ curated datasets and 20+ model architectures.
+
+## When to Use This Skill
+
+This skill should be used when working with:
+
+**Data Types:**
+- SMILES strings or molecular structures
+- Protein sequences or 3D structures (PDB files)
+- Chemical reactions and retrosynthesis
+- Biomedical knowledge graphs
+- Drug discovery datasets
+
+**Tasks:**
+- Predicting molecular properties (solubility, toxicity, activity)
+- Protein function or structure prediction
+- Drug-target binding prediction
+
+## Getting Started
+
+# Or with optional dependencies
+uv pip install torchdrug[full]
+```
+
+### Quick Example
+
+```python
+from torchdrug import datasets, models, tasks
+from torch.utils.data import DataLoader
+
+# Load molecular dataset
+dataset = datasets.BBBP("~/molecule-datasets/")
+train_set, valid_set, test_set = dataset.split()
+
+# Define GNN model
+model = models.GIN(
+    input_dim=dataset.node_feature_dim,
+    hidden_dims=[256, 256, 256],
+    edge_input_dim=dataset.edge_feature_dim,
+    batch_norm=True,
+    readout="mean"
+)
+
+# Create property prediction task
+task = tasks.PropertyPrediction(
+    model,
+    task=dataset.tasks,
+    criterion="bce",
+    metric=["auroc", "auprc"]
+)
+
+# Train with PyTorch
+optimizer = torch.optim.Adam(task.parameters(), lr=1e-3)
+train_loader = DataLoader(train_set, batch_size=32, shuffle=True)
+
+for epoch in range(100):
+    for batch in train_loader:
+        loss = task(batch)
+        optimizer.zero_grad()
+        loss.backward()
+        optimizer.step()
+
+## Core Capabilities
+
+### 1. Molecular Property Prediction
+
+Predict chemical, physical, and biological properties of molecules from structure.
+
+**Use Cases:**
+- Drug-likeness and ADMET properties
+- Toxicity screening
+- Quantum chemistry properties
+- Binding affinity prediction
+
+**Key Components:**
+- 20+ molecular datasets (BBBP, HIV, Tox21, QM9, etc.)
+- GNN models (GIN, GAT, SchNet)
+- PropertyPrediction and MultipleBinaryClassification tasks
+
+
+### 2. Protein Modeling
+
+Work with protein sequences, structures, and properties.
+
+**Use Cases:**
+- Enzyme function prediction
+- Protein stability and solubility
+- Subcellular localization
+- Protein-protein interactions
+- Structure prediction
+
+**Key Components:**
+- 15+ protein datasets (EnzymeCommission, GeneOntology, PDBBind, etc.)
+- Sequence models (ESM, ProteinBERT, ProteinLSTM)
+- Structure models (GearNet, SchNet)
+
+### 3. Knowledge Graph Reasoning
+
+Predict missing links and relationships in biological knowledge graphs.
+
+**Use Cases:**
+- Drug repurposing
+- Disease mechanism discovery
+- Gene-disease associations
+- Multi-hop biomedical reasoning
+
+**Key Components:**
+
+

package/skills/trace/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: trace
+description: Evidence-driven tracing lane that orchestrates competing tracer hypotheses in Claude built-in team mode
+---
+
+# Trace Skill
+
+Use this skill for ambiguous, causal, evidence-heavy questions where the goal is to explain **why** an observed result happened, not to jump directly into fixing or rewriting code.
+
+This is the orchestration layer on top of the built-in `tracer` agent. The goal is to make tracing feel like a reusable OMC operating lane: restate the observation, generate competing explanations, gather evidence in parallel, rank the explanations, and propose the next probe that would collapse uncertainty fastest.
+
+## Good entry cases
+
+Use `trace` when the problem is:
+
+- ambiguous
+- causal
+- evidence-heavy
+- best answered by exploring competing explanations in parallel
+
+Examples:
+- runtime bugs and regressions
+- performance / latency / resource behavior
+- architecture / premortem / postmortem analysis
+- scientific or experimental result tracing
+- config / routing / orchestration behavior explanation
+- “given this output, trace back the likely causes”
+
+## Core tracing contract
+
+Always preserve these distinctions:
+
+1. **Observation** -- what was actually observed
+2. **Hypotheses** -- competing explanations
+3. **Evidence For** -- what supports each explanation
+4. **Evidence Against / Gaps** -- what contradicts it or is still missing
+5. **Current Best Explanation** -- the leading explanation right now
+6. **Critical Unknown** -- the missing fact keeping the top explanations apart
+7. **Discriminating Probe** -- the highest-value next step to collapse uncertainty
+
+Do **not** collapse into:
+- a generic fix-it coding loop
+- a generic debugger summary
+- a raw dump of worker output
+- fake certainty when evidence is incomplete
+
+## Evidence strength hierarchy
+
+Treat evidence as ranked, not flat.
+
+From strongest to weakest:
+
+1. **Controlled reproductions / direct experiments / uniquely discriminating artifacts**
+2. **Primary source artifacts with tight provenance** (trace events, logs, metrics, benchmark outputs, configs, git history, file:line behavior)
+3. **Multiple independent sources converging on the same explanation**
+4. **Single-source code-path or behavioral inference**
+5. **Weak circumstantial clues** (timing, naming, stack order, resemblance to prior bugs)
+6. **Intuition / analogy / speculation**
+
+Explicitly down-rank hypotheses that depend mostly on lower tiers when stronger contradictory evidence exists.
+
+## Strong falsification / disconfirmation rules
+
+Every serious `/trace` run must try to falsify its own favorite explanation.
+
+For each top hypothesis:
+
+- collect evidence **for** it
+- collect evidence **against** it
+- state what distinctive prediction it makes
+- state what observation would be hard to reconcile with it
+- identify the cheapest probe that would discriminate it from the next-best alternative
+
+Down-rank a hypothesis when:
+
+- direct evidence contradicts it
+
+## Team-mode orchestration shape
+
+Use **Claude built-in team mode** for `/trace`.
+
+The lead should:
+
+1. Restate the observed result or “why” question precisely
+2. Extract the tracing target
+3. Generate multiple deliberately different candidate hypotheses
+4. Spawn **3 tracer lanes by default** in team mode
+5. Assign one tracer worker per lane
+6. Instruct each tracer worker to gather evidence **for** and **against** its lane
+7. Run a **rebuttal round** between the leading hypothesis and the strongest remaining alternative
+8. Detect whether the top lanes genuinely differ or actually converge on the same root cause
+9. Merge findings into a ranked synthesis with an explicit critical unknown and discriminating probe
+
+Important: workers should pursue deliberately different explanations, not the same explanation in parallel.
+
+## Default hypothesis lanes for v1
+
+Unless the prompt strongly suggests a better partition, use these 3 default lanes:
+
+1. **Code-path / implementation cause**
+2. **Config / environment / orchestration cause**
+3. **Measurement / artifact / assumption mismatch cause** — covers verification-method defects, not just system defects. Examples: the verification query reuses a single dimensional key across distinct entities, tenants, streams, or groups; the comparison filter shape does not match the schema grain; or the catalog or column name was assumed portable across runtimes without enumeration. This includes multi-entity premise/key-assumption mismatches.
+
+For lane 3, cross-entity discrepancies need a premise audit before escalation: enumerate entity dimensions and check whether a zero-row or mismatch result came from applying one key across multiple entities rather than from a system defect; the result may be a verification-methodology defect.
+
+These defaults are intentionally broad so the first slice works across bug, performance, architecture, and experiment tracing.
+
+## Mandatory cross-check lenses
+
+After the initial evidence pass, pressure-test the leaders with these lenses when relevant:
+
+- **Systems lens** -- queues, retries, backpressure, feedback loops, upstream/downstream dependencies, boundary failures, coordination effects
+- **Premortem lens** -- assume the current best explanation is incomplete or wrong; what failure mode would embarrass the trace later?
+- **Science lens** -- controls, confounders, measurement bias, alternative variables, falsifiable predictions
+
+These lenses are not filler. Use them when they can surface a missed explanation, hidden dependency, or weak inference.
+
+

package/skills/transformers/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: transformers
+description: This skill should be used when working with pre-trained transformer models for natural language processing, computer vision, audio, or multimodal tasks. Use for text generation, classification, question answering, translation, summarization, image classification, object detection, speech recognition, and fine-tuning models on custom datasets.
+---
+
+# Transformers
+
+## Overview
+
+The Hugging Face Transformers library provides access to thousands of pre-trained models for tasks across NLP, computer vision, audio, and multimodal domains. Use this skill to load models, perform inference, and fine-tune on custom data.
+
+## Authentication
+
+Many models on the Hugging Face Hub require authentication. Set up access:
+
+```python
+from huggingface_hub import login
+login()  # Follow prompts to enter token
+```
+
+Or set environment variable:
+```bash
+export HUGGINGFACE_TOKEN="your_token_here"
+```
+
+Get tokens at: https://huggingface.co/settings/tokens
+
+## Quick Start
+
+Use the Pipeline API for fast inference without manual configuration:
+
+```python
+from transformers import pipeline
+
+# Text generation
+generator = pipeline("text-generation", model="gpt2")
+result = generator("The future of AI is", max_length=50)
+
+# Text classification
+classifier = pipeline("text-classification")
+result = classifier("This movie was excellent!")
+
+# Question answering
+qa = pipeline("question-answering")
+result = qa(question="What is AI?", context="AI is artificial intelligence...")
+```
+
+## Core Capabilities
+
+### 1. Pipelines for Quick Inference
+
+Use for simple, optimized inference across many tasks. Supports text generation, classification, NER, question answering, summarization, translation, image classification, object detection, audio classification, and more.
+
+**When to use**: Quick prototyping, simple inference tasks, no custom preprocessing needed.
+
+See `(see docs)` for comprehensive task coverage and optimization.
+
+### 2. Model Loading and Management
+
+Load pre-trained models with fine-grained control over configuration, device placement, and precision.
+
+**When to use**: Custom model initialization, advanced device management, model inspection.
+
+See `(see docs)` for loading patterns and best practices.
+
+### 3. Text Generation
+
+Generate text with LLMs using various decoding strategies (greedy, beam search, sampling) and control parameters (temperature, top-k, top-p).
+
+**When to use**: Creative text generation, code generation, conversational AI, text completion.
+
+See `(see docs)` for generation strategies and parameters.
+
+### 4. Training and Fine-Tuning
+
+Fine-tune pre-trained models on custom datasets using the Trainer API with automatic mixed precision, distributed training, and logging.
+
+**When to use**: Task-specific model adaptation, domain adaptation, improving model performance.
+
+See `(see docs)` for training workflows and best practices.
+
+### 5. Tokenization
+
+Convert text to tokens and token IDs for model input, with padding, truncation, and special token handling.
+
+**When to use**: Custom preprocessing pipelines, understanding model inputs, batch processing.
+
+See `(see docs)` for tokenization details.
+
+## Common Patterns
+
+### Pattern 1: Simple Inference
+For straightforward tasks, use pipelines:
+```python
+pipe = pipeline("task-name", model="model-id")
+output = pipe(input_data)
+```
+
+### Pattern 2: Custom Model Usage
+For advanced control, load model and tokenizer separately:
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+tokenizer = AutoTokenizer.from_pretrained("model-id")
+model = AutoModelForCausalLM.from_pretrained("model-id", device_map="auto")
+
+inputs = tokenizer("text", return_tensors="pt")
+outputs = model.generate(**inputs, max_new_tokens=100)
+result = tokenizer.decode(outputs[0])
+```

package/skills/treatment-plans/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: treatment-plans
+description: Generate concise (3-4 page), focused medical treatment plans in LaTeX/PDF format for all clinical specialties. Supports general medical treatment, rehabilitation therapy, mental health care, chronic disease management, perioperative care, and pain management. Includes SMART goal frameworks, evidence-based interventions with minimal text citations, regulatory compliance (HIPAA), and professional formatting. Prioritizes brevity and clinical actionability.
+---
+
+# Treatment Plan Writing
+
+## Overview
+
+Treatment plan writing is the systematic documentation of clinical care strategies designed to address patient health conditions through evidence-based interventions, measurable goals, and structured follow-up. This skill provides comprehensive LaTeX templates and validation tools for creating **concise, focused** treatment plans (3-4 pages standard) across all medical specialties with full regulatory compliance.
+
+**Critical Principles:**
+1. **CONCISE & ACTIONABLE**: Treatment plans default to 3-4 pages maximum, focusing only on clinically essential information that impacts care decisions
+2. **Patient-Centered**: Plans must be evidence-based, measurable, and compliant with healthcare regulations (HIPAA, documentation standards)
+3. **Minimal Citations**: Use brief in-text citations only when needed to support clinical recommendations; avoid extensive bibliographies
+
+Every treatment plan should include clear goals, specific interventions, defined timelines, monitoring parameters, and expected outcomes that align with patient preferences and current clinical guidelines - all presented as efficiently as possible.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Creating individualized treatment plans for patient care
+- Documenting therapeutic interventions for chronic disease management
+- Developing rehabilitation programs (physical therapy, occupational therapy, cardiac rehab)
+- Writing mental health and psychiatric treatment plans
+- Planning perioperative and surgical care pathways
+- Establishing pain management protocols
+- Setting patient-centered goals using SMART criteria
+- Coordinating multidisciplinary care across specialties
+- Ensuring regulatory compliance in treatment documentation
+- Generating professional treatment plans for medical records
+
+## Visual Enhancement with Scientific Schematics
+
+**⚠️ MANDATORY: Every treatment plan MUST include at least 1 AI-generated figure using the scientific-schematics skill.**
+
+This is not optional. Treatment plans benefit greatly from visual elements. Before finalizing any document:
+1. Generate at minimum ONE schematic or diagram (e.g., treatment pathway flowchart, care coordination diagram, or therapy timeline)
+2. For complex plans: include decision algorithm flowchart
+3. For rehabilitation plans: include milestone progression diagram
+
+**How to generate figures:**
+- 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
+
+**How to generate schematics:**
+
+## Document Format and Best Practices
+
+### Document Length Options
+
+Treatment plans come in three format options based on clinical complexity and use case:
+
+#### Option 1: One-Page Treatment Plan (PREFERRED for most cases)
+
+**When to use**: Straightforward clinical scenarios, standard protocols, busy clinical settings
+
+**Format**: Single page containing all essential treatment information in scannable sections
+- No table of contents needed
+- No extensive narratives
+- Focused on actionable items only
+- Similar to precision oncology reports or treatment recommendation cards
+
+**Required sections** (all on one page):
+
+### First Page Summary (Foundation Medicine Model)
+
+**CRITICAL REQUIREMENT: All treatment plans MUST have a complete executive summary on the first page ONLY, before any table of contents or detailed sections.**
+
+Following the Foundation Medicine model for precision medicine reporting and clinical summary documents, treatment plans begin with a one-page executive summary that provides immediate access to key actionable information. This entire summary must fit on the first page.
+
+**Required First Page Structure (in order):**
+
+1. **Title and Subtitle**
+   - Main title: Treatment plan type (e.g., "Comprehensive Treatment Plan")
+   - Subtitle: Specific condition or focus (e.g., "Type 2 Diabetes Mellitus - Young Adult Patient")
+
+2. **Report Information Box** (using `\begin{infobox}` or `\begin{patientinfo}`)
+   - Report type/document purpose
+   - Date of plan creation
+
+### Concise Documentation
+
+**CRITICAL: Treatment plans MUST prioritize brevity and clinical relevance. Default to 3-4 pages maximum unless clinical complexity absolutely demands more detail.**
+
+Treatment plans should prioritize **clarity and actionability** over exhaustive detail:
+
+- **Focused**: Include only clinically essential information that impacts care decisions
+- **Actionable**: Emphasize what needs to be done, when, and why
+- **Efficient**: Facilitate quick decision-making without sacrificing clinical quality
+- **Target length options**:
+  - **1-page format** (preferred for straightforward cases): Quick-reference card with all essential information
+  - **3-4 pages standard**: Standard format with first-page summary + supporting details
+  - **5-6 pages** (rare): Only for highly complex cases with multiple comorbidities or multidisciplinary interventions
+
+**Streamlining Guidelines:**
+
+### Quality Over Quantity
+
+The goal is professional, clinically complete documentation that respects clinicians' time while ensuring comprehensive patient care. Every section should add value; remove or condense sections that don't directly inform treatment decisions.
+
+### Citations and Evidence Support
+
+**Use minimal, targeted citations to support clinical recommendations:**
+
+- **Text Citations Preferred**: Use brief in-text citations (Author Year) or simple references rather than extensive bibliographies unless specifically requested
+- **When to Cite**:
+  - Clinical practice guideline recommendations (e.g., "per ADA 2024 guidelines")
+  - Specific medication dosing or protocols (e.g., "ACC/AHA recommendations")
+  - Novel or controversial interventions requiring evidence support
+  - Risk stratification tools or validated assessment scales
+- **When NOT to Cite**:
+  - Standard-of-care interventions widely accepted in the field
+  - Basic medical facts and routine clinical practices
+  - General patient education content
+- **Citation Format**: 
+
+

package/skills/ui-render-performance/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ui-render-performance
+description: Non-blocking Pi TUI render workflow. Use when changing widgets, powerbar/statusbar segments, dashboard panes, overlays, snapshot caches, or live UI refresh behavior.
+---
+
+
+# ui-render-performance
+
+Use this skill for Pi/pi-crew TUI work.
+
+## Source patterns distilled
+
+- Pi TUI is synchronous immediate-mode/string rendering: `source/pi-mono/packages/coding-agent/src/modes/interactive/interactive-mode.ts`
+- Pi extension examples use event-driven state updates, not render-time loading.
+- pi-crew UI: `src/extension/register.ts`, `src/ui/run-dashboard.ts`, `src/ui/run-snapshot-cache.ts`, `src/ui/crew-widget.ts`, `src/ui/powerbar-publisher.ts`, `src/ui/render-scheduler.ts`
+
+## Rules
+
+- Treat every `render(width)` and widget/powerbar update as a hot synchronous path.
+- Render from in-memory snapshots only. Preload config, manifests, snapshots, agents, and mailbox counts asynchronously.
+- Use `RenderScheduler.schedule()` to coalesce renders; avoid direct repeated rendering.
+- Prefer `snapshotCache.get(runId)` in render paths. If a sync fallback is unavoidable, classify it as first-load/rare and document why.
+- Keep dashboard panes pure: accept a snapshot/model and format strings; do not call `fs.readFileSync`, `fs.readdirSync`, `fs.statSync`, or network APIs from pane render methods.
+- On session switch, cancel timers and ensure in-flight async preloads cannot update stale session UI.
+- Watch TTL interactions: a preload interval shorter than cache TTL prevents render-time refresh gaps.
+
+## Anti-patterns
+
+- Do not call `loadConfig()`, `manifestCache.list()`, or `refreshIfStale()` repeatedly inside `renderTick()` unless backed by preloaded frame data.
+- Do not do large JSON parsing or directory scans inside widget render/update functions.
+- Do not show stale health warnings for completed/cancelled/failed runs.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/run-snapshot-cache.test.ts test/unit/crew-widget.test.ts test/unit/powerbar-publisher.test.ts test/unit/run-dashboard.test.ts
+npm test
+```
+