@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/nk-cell-therapy-agent/SKILL.md

@@ -0,0 +1,186 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: 'nk-cell-therapy-agent'
+description: 'AI-powered NK cell therapy design for cancer immunotherapy including CAR-NK engineering, memory-like NK generation, and KIR/HLA matching optimization.'
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+
+# NK Cell Therapy Agent
+
+The **NK Cell Therapy Agent** provides AI-driven design and optimization of natural killer cell therapies for cancer treatment. It covers CAR-NK engineering, cytokine-induced memory-like (CIML) NK generation, KIR/HLA matching, and NK cell expansion optimization.
+
+## When to Use This Skill
+
+* When designing CAR-NK constructs for tumor targeting.
+* To optimize KIR/HLA mismatch for allogeneic NK therapy.
+* For generating memory-like NK cells with enhanced persistence.
+* When predicting NK cell activation against specific tumor types.
+* To analyze NK cell receptor repertoires and function.
+
+## Core Capabilities
+
+1. **CAR-NK Design**: Design chimeric antigen receptors optimized for NK cell biology (NK-specific signaling domains).
+
+2. **KIR/HLA Matching**: Predict KIR-HLA interactions for donor selection in allogeneic therapy.
+
+3. **Memory-Like NK Generation**: Optimize CIML protocol with IL-12/15/18 cytokine preactivation.
+
+4. **Expansion Optimization**: ML models for feeder-free NK expansion conditions.
+
+5. **Tumor Target Prediction**: Match NK receptor profiles to tumor ligand expression.
+
+6. **Persistence Enhancement**: Engineering strategies for improved in vivo survival.
+
+## NK Cell Advantages Over T Cells
+
+| Feature | NK Cells | T Cells |
+|---------|----------|---------|
+| MHC requirement | No | Yes |
+| Allogeneic use | Yes (no GVHD) | Limited (GVHD risk) |
+| CRS risk | Lower | Higher |
+| Off-the-shelf | Yes | Autologous typical |
+| Antigen escape | Multiple receptors | Single CAR |
+| Persistence | Shorter | Longer |
+
+## CAR-NK Architecture
+
+```
+[scFv] - [Hinge] - [Transmembrane] - [Costimulatory] - [Signaling]
+
+NK-Optimized Domains:
+- Transmembrane: NKG2D, CD8α, or CD28
+- Costimulatory: 2B4, DAP10, or CD28
+- Signaling: CD3ζ (with NK-specific adaptations)
+- Additional: Cytokine secretion (IL-15), suicide switch
+```
+
+## Workflow
+
+1. **Input**: Target antigen, tumor type, NK source (PB, UCB, iPSC, cell line).
+
+2. **CAR Design**: Generate optimized CAR-NK construct sequence.
+
+3. **KIR Analysis**: Determine KIR genotype and HLA matching for donors.
+
+4. **Activation Protocol**: Optimize cytokine cocktail for desired phenotype.
+
+5. **Expansion**: Design feeder-based or feeder-free expansion protocol.
+
+6. **Quality Prediction**: Predict NK product functionality.
+
+7. **Output**: CAR sequence, donor recommendations, expansion protocol, QC metrics.
+
+## Example Usage
+
+**User**: "Design a CAR-NK targeting CD19 for B-cell malignancies with enhanced persistence."
+
+**Agent Action**:
+```bash
+python3 Skills/Immunology_Vaccines/NK_Cell_Therapy_Agent/nk_designer.py \
+    --target CD19 \
+    --tumor_type b_cell_lymphoma \
+    --nk_source ucb \
+    --persistence_strategy il15_secretion \
+    --costimulatory 2B4_DAP10 \
+    --donors donor_hla_kir.json \
+    --output carnk_design/
+```
+
+## NK Receptor-Ligand Interactions
+
+**Activating Receptors**:
+
+| Receptor | Ligands | Tumor Expression |
+|----------|---------|------------------|
+| NKG2D | MICA/B, ULBPs | Stress-induced |
+| DNAM-1 | CD155, CD112 | Broadly expressed |
+| NKp30 | B7-H6, BAG6 | Tumor-specific |
+| NKp46 | Unknown tumor | Variable |
+| CD16 | IgG Fc | ADCC trigger |
+
+**Inhibitory Receptors**:
+
+| Receptor | Ligands | Function |
+|----------|---------|----------|
+| KIR2DL1 | HLA-C2 | Self tolerance |
+| KIR2DL2/3 | HLA-C1 | Self tolerance |
+| KIR3DL1 | HLA-Bw4 | Self tolerance |
+| NKG2A | HLA-E | Checkpoint |
+
+## Memory-Like NK (CIML) Protocol
+
+**Cytokine Preactivation**:
+- IL-12 (10 ng/mL) + IL-15 (50 ng/mL) + IL-18 (50 ng/mL)
+- 16-18 hour stimulation
+- Enhanced IFN-γ, cytotoxicity upon restimulation
+- Improved in vivo persistence
+
+**Clinical Evidence**: Effective in relapsed/refractory AML
+
+## KIR/HLA Matching Optimization
+
+**Missing-Self Recognition**:
+- Donor KIR + / Patient HLA -
+- Enhanced NK cytotoxicity
+- Important for allo-HSCT
+
+**Prediction Model**:
+- Input: Donor KIR genotype, patient HLA
+- Output: Predicted NK alloreactivity score
+- Validated in transplant outcomes
+
+## AI/ML Components
+
+**CAR-NK Optimization**:
+- Adapted CARMSeD for NK biology
+- NK-specific signaling domain preferences
+- Tonic signaling prediction
+
+**Expansion Prediction**:
+- Fold-expansion from culture conditions
+- Phenotype shift modeling
+- Exhaustion marker prediction
+
+## Prerequisites
+
+* Python 3.10+
+* HLA/KIR databases
+* NK receptor databases
+* Flow cytometry analysis tools
+
+## Related Skills
+
+* CART_Design_Optimizer_Agent - For CAR engineering principles
+* Epitope_Prediction_Agent - For target selection
+* Flow_Cytometry_AI - For NK phenotyping
+
+## Clinical Development
+
+**Current CAR-NK Programs**:
+- CD19 CAR-NK (MD Anderson - AML, lymphoma)
+- NKG2D CAR-NK (various solid tumors)
+- CD70 CAR-NK (renal cell carcinoma)
+- HER2 CAR-NK (breast cancer)
+
+## Author
+
+AI Group - Biomedical AI Platform
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

package/data/skills/nonlinear-solvers/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: nonlinear-solvers
+description: Select and configure nonlinear solvers for f(x)=0 or min F(x). Use for Newton methods, quasi-Newton (BFGS, L-BFGS), Broyden, Anderson acceleration, diagnosing convergence issues, choosing line search vs trust region, and analyzing Jacobian quality.
+allowed-tools: Read, Bash, Write, Grep, Glob
+---
+
+# Nonlinear Solvers
+
+## Goal
+
+Provide a universal workflow to select a nonlinear solver, configure globalization strategies, and diagnose convergence for root-finding, optimization, and least-squares problems.
+
+## Requirements
+
+- Python 3.8+
+- NumPy (for Jacobian diagnostics)
+- SciPy (optional, for advanced analysis)
+
+## Inputs to Gather
+
+| Input | Description | Example |
+|-------|-------------|---------|
+| Problem type | Root-finding, optimization, least-squares | `root-finding` |
+| Problem size | Number of unknowns | `n = 10000` |
+| Jacobian availability | Analytic, finite-diff, unavailable | `analytic` |
+| Jacobian cost | Cheap or expensive to compute | `expensive` |
+| Constraints | None, bounds, equality, inequality | `none` |
+| Smoothness | Is objective/residual smooth? | `yes` |
+| Residual history | Sequence of residual norms | `1,0.1,0.01,...` |
+
+## Decision Guidance
+
+### Solver Selection Flowchart
+
+```
+Is Jacobian available and cheap?
+├── YES → Problem size?
+│   ├── Small (n < 1000) → Newton (full)
+│   └── Large (n ≥ 1000) → Newton-Krylov
+└── NO → Is objective smooth?
+    ├── YES → Memory limited?
+    │   ├── YES → L-BFGS or Broyden
+    │   └── NO → BFGS
+    └── NO → Anderson acceleration or Picard
+```
+
+### Quick Reference
+
+| Problem Type | First Choice | Alternative | Globalization |
+|--------------|--------------|-------------|---------------|
+| Small root-finding | Newton | Broyden | Line search |
+| Large root-finding | Newton-Krylov | Anderson | Trust region |
+| Optimization | L-BFGS | BFGS | Wolfe line search |
+| Least-squares | Levenberg-Marquardt | Gauss-Newton | Trust region |
+| Bound constrained | L-BFGS-B | Trust-region reflective | Projected |
+
+## Script Outputs (JSON Fields)
+
+| Script | Key Outputs |
+|--------|-------------|
+| `scripts/solver_selector.py` | `recommended`, `alternatives`, `notes` |
+| `scripts/convergence_analyzer.py` | `converged`, `convergence_type`, `estimated_rate`, `diagnosis` |
+| `scripts/jacobian_diagnostics.py` | `condition_number`, `jacobian_quality`, `rank_deficient` |
+| `scripts/globalization_advisor.py` | `strategy`, `line_search_type`, `trust_region_type`, `parameters` |
+| `scripts/residual_monitor.py` | `patterns_detected`, `alerts`, `recommendations` |
+| `scripts/step_quality.py` | `ratio`, `step_quality`, `accept_step`, `trust_radius_action` |
+
+## Workflow
+
+1. **Characterize problem** - Identify type, size, Jacobian availability
+2. **Select solver** - Run `scripts/solver_selector.py`
+3. **Choose globalization** - Run `scripts/globalization_advisor.py`
+4. **Analyze Jacobian** - If available, run `scripts/jacobian_diagnostics.py`
+5. **Monitor residuals** - During solve, use `scripts/residual_monitor.py`
+6. **Analyze convergence** - Run `scripts/convergence_analyzer.py`
+7. **Evaluate steps** - For trust region, use `scripts/step_quality.py`
+
+## Conversational Workflow Example
+
+**User**: My Newton solver for a phase-field simulation is converging very slowly. After 50 iterations, the residual only dropped from 1 to 0.1.
+
+**Agent workflow**:
+1. Analyze convergence:
+   ```bash
+   python3 scripts/convergence_analyzer.py --residuals 1,0.8,0.6,0.5,0.4,0.3,0.2,0.15,0.12,0.1 --json
+   ```
+2. Check globalization strategy:
+   ```bash
+   python3 scripts/globalization_advisor.py --problem-type root-finding --jacobian-quality ill-conditioned --previous-failures 0 --json
+   ```
+3. Recommend: Switch to trust region with Levenberg-Marquardt regularization, or use Newton-Krylov with better preconditioning.
+
+## Pre-Solve Checklist
+
+- [ ] Confirm problem type (root-finding, optimization, least-squares)
+- [ ] Assess Jacobian availability and cost
+- [ ] Check initial guess quality
+- [ ] Set appropriate tolerances
+- [ ] Choose globalization strategy
+- [ ] Prepare to monitor convergence
+
+## CLI Examples
+
+```bash
+# Select solver for large unconstrained optimization
+python3 scripts/solver_selector.py --size 50000 --smooth --memory-limited --json
+
+# Analyze convergence from residual history
+python3 scripts/convergence_analyzer.py --residuals 1,0.1,0.01,0.001,0.0001 --tolerance 1e-6 --json
+
+# Diagnose Jacobian quality
+python3 scripts/jacobian_diagnostics.py --matrix jacobian.txt --json
+
+# Get globalization recommendation
+python3 scripts/globalization_advisor.py --problem-type optimization --jacobian-quality good --json
+
+# Monitor residual patterns
+python3 scripts/residual_monitor.py --residuals 1,0.8,0.9,0.7,0.75,0.6 --target-tolerance 1e-8 --json
+
+# Evaluate step quality for trust region
+python3 scripts/step_quality.py --predicted-reduction 0.5 --actual-reduction 0.4 --step-norm 0.8 --gradient-norm 1.0 --trust-radius 1.0 --json
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `problem_size must be positive` | Invalid size | Check problem dimension |
+| `constraint_type must be one of...` | Unknown constraint | Use: none, bound, equality, inequality |
+| `residuals must be non-negative` | Invalid residual data | Check residual computation |
+| `Matrix file not found` | Invalid path | Verify Jacobian file exists |
+
+## Interpretation Guidance
+
+### Convergence Type
+
+| Type | Meaning | Action |
+|------|---------|--------|
+| quadratic | Optimal Newton | Continue, near solution |
+| superlinear | Quasi-Newton working | Monitor for stagnation |
+| linear | Acceptable | May improve with preconditioner |
+| sublinear | Too slow | Change method or formulation |
+| stagnated | No progress | Check Jacobian, preconditioner |
+| diverged | Increasing residual | Add globalization, check Jacobian |
+
+### Jacobian Quality
+
+| Quality | Condition Number | Action |
+|---------|------------------|--------|
+| good | < 10⁶ | Standard Newton works |
+| moderately-conditioned | 10⁶ - 10¹⁰ | Consider scaling |
+| ill-conditioned | > 10¹⁰ | Use regularization |
+| near-singular | ∞ | Reformulate or use LM |
+
+### Step Quality (Trust Region)
+
+| Ratio ρ | Quality | Trust Radius |
+|---------|---------|--------------|
+| ρ < 0 | very_poor | Shrink aggressively |
+| ρ < 0.25 | marginal | Shrink |
+| 0.25 ≤ ρ < 0.75 | good | Maintain |
+| ρ ≥ 0.75 | excellent | Expand if at boundary |
+
+## Limitations
+
+- **No global convergence guarantee**: All methods may fail for pathological problems
+- **Jacobian accuracy**: Finite-difference Jacobian may be inaccurate near discontinuities
+- **Large dense problems**: May require specialized solvers not covered here
+- **Constrained optimization**: Complex constraints need SQP or interior point methods
+
+## References
+
+- `references/solver_decision_tree.md` - Problem-based solver selection
+- `references/method_catalog.md` - Method details and parameters
+- `references/convergence_diagnostics.md` - Diagnosing convergence issues
+- `references/globalization_strategies.md` - Line search and trust region
+
+## Version History
+
+- **v1.0.0** : Initial release with 6 analysis scripts

package/data/skills/numerical-integration/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: numerical-integration
+description: Select and configure time integration methods for ODE/PDE simulations. Use when choosing explicit/implicit schemes, setting error tolerances, adapting time steps, diagnosing integration accuracy, planning IMEX splitting, or handling stiff/non-stiff coupled systems.
+allowed-tools: Read, Bash, Write, Grep, Glob
+---
+
+# Numerical Integration
+
+## Goal
+
+Provide a reliable workflow to select integrators, set tolerances, and manage adaptive time stepping for time-dependent simulations.
+
+## Requirements
+
+- Python 3.8+
+- NumPy (for some scripts)
+- No heavy dependencies for core functionality
+
+## Inputs to Gather
+
+| Input | Description | Example |
+|-------|-------------|---------|
+| Problem type | ODE/PDE, stiff/non-stiff | `stiff PDE` |
+| Jacobian available | Can compute ∂f/∂u? | `yes` |
+| Target accuracy | Desired error level | `1e-6` |
+| Constraints | Memory, implicit allowed? | `implicit OK` |
+| Time scale | Characteristic time | `1e-3 s` |
+
+## Decision Guidance
+
+### Choosing an Integrator
+
+```
+Is the problem stiff?
+├── YES → Is Jacobian available?
+│   ├── YES → Use Rosenbrock or BDF
+│   └── NO → Use BDF with numerical Jacobian
+└── NO → Is high accuracy needed?
+    ├── YES → Use RK45 or DOP853
+    └── NO → Use RK4 or Adams-Bashforth
+```
+
+### Stiff vs Non-Stiff Detection
+
+| Symptom | Likely Stiff | Action |
+|---------|--------------|--------|
+| dt shrinks to tiny values | Yes | Switch to implicit |
+| Eigenvalues span many decades | Yes | Use BDF/Radau |
+| Smooth solution, reasonable dt | No | Stay explicit |
+
+## Script Outputs (JSON Fields)
+
+| Script | Key Outputs |
+|--------|-------------|
+| `scripts/error_norm.py` | `error_norm`, `scale_min`, `scale_max` |
+| `scripts/adaptive_step_controller.py` | `accept`, `dt_next`, `factor` |
+| `scripts/integrator_selector.py` | `recommended`, `alternatives`, `notes` |
+| `scripts/imex_split_planner.py` | `implicit_terms`, `explicit_terms`, `splitting_strategy` |
+| `scripts/splitting_error_estimator.py` | `error_estimate`, `substeps` |
+
+## Workflow
+
+1. **Classify stiffness** - Check eigenvalue spread or use stiffness_detector
+2. **Choose tolerances** - See `references/tolerance_guidelines.md`
+3. **Select integrator** - Run `scripts/integrator_selector.py`
+4. **Compute error norms** - Use `scripts/error_norm.py` for step acceptance
+5. **Adapt step size** - Use `scripts/adaptive_step_controller.py`
+6. **Plan IMEX/splitting** - If mixed stiff/nonstiff, use `scripts/imex_split_planner.py`
+7. **Validate convergence** - Repeat with tighter tolerances
+
+## Conversational Workflow Example
+
+**User**: I'm solving the Allen-Cahn equation with a stiff double-well potential. What integrator should I use?
+
+**Agent workflow**:
+1. Check integrator options:
+   ```bash
+   python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json
+   ```
+2. Plan the IMEX splitting (diffusion implicit, reaction explicit):
+   ```bash
+   python3 scripts/imex_split_planner.py --stiff-terms diffusion --nonstiff-terms reaction --coupling weak --json
+   ```
+3. Recommend: Use IMEX-BDF2 with diffusion term implicit, double-well reaction explicit.
+
+## Pre-Integration Checklist
+
+- [ ] Identify stiffness and dominant time scales
+- [ ] Set `rtol`/`atol` consistent with physics and units
+- [ ] Confirm integrator compatibility with stiffness
+- [ ] Use error norm to accept/reject steps
+- [ ] Verify convergence with tighter tolerance run
+
+## CLI Examples
+
+```bash
+# Select integrator for stiff problem with Jacobian
+python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json
+
+# Compute scaled error norm
+python3 scripts/error_norm.py --error 0.01,0.02 --solution 1.0,2.0 --rtol 1e-3 --atol 1e-6 --json
+
+# Adaptive step control with PI controller
+python3 scripts/adaptive_step_controller.py --dt 1e-2 --error-norm 0.8 --order 4 --controller pi --json
+
+# Plan IMEX splitting
+python3 scripts/imex_split_planner.py --stiff-terms diffusion,elastic --nonstiff-terms reaction --coupling strong --json
+
+# Estimate splitting error
+python3 scripts/splitting_error_estimator.py --dt 1e-4 --scheme strang --commutator-norm 50 --target-error 1e-6 --json
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `rtol and atol must be positive` | Invalid tolerances | Use positive values |
+| `error-norm must be positive` | Negative error norm | Check error computation |
+| `Unknown controller` | Invalid controller type | Use `i`, `pi`, or `pid` |
+| `Splitting requires at least one term` | Empty term list | Specify stiff or nonstiff terms |
+
+## Interpretation Guidance
+
+### Error Norm Values
+
+| Error Norm | Meaning | Action |
+|------------|---------|--------|
+| < 1.0 | Step acceptable | Accept, maybe increase dt |
+| ≈ 1.0 | At tolerance boundary | Accept with current dt |
+| > 1.0 | Step rejected | Reject, reduce dt |
+
+### Controller Selection
+
+| Controller | Properties | Best For |
+|------------|------------|----------|
+| I (integral) | Simple, some overshoot | Non-stiff, moderate accuracy |
+| PI (proportional-integral) | Smooth, robust | General use |
+| PID | Aggressive adaptation | Rapidly varying dynamics |
+
+### IMEX Strategy
+
+| Coupling | Strategy |
+|----------|----------|
+| Weak | Simple operator splitting |
+| Moderate | Strang splitting |
+| Strong | Fully coupled IMEX-RK |
+
+## Limitations
+
+- **No automatic stiffness detection**: Use stiffness_detector from numerical-stability
+- **Splitting assumes separability**: Terms must be cleanly separable
+- **Jacobian requirement**: Some methods need analytical or numerical Jacobian
+
+## References
+
+- `references/method_catalog.md` - Integrator options and properties
+- `references/tolerance_guidelines.md` - Choosing rtol/atol
+- `references/error_control.md` - Error norm and adaptation formulas
+- `references/imex_guidelines.md` - Stiff/non-stiff splitting
+- `references/splitting_catalog.md` - Operator splitting patterns
+- `references/multiphase_field_patterns.md` - Phase-field specific splits
+
+## Version History
+
+- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples
+- **v1.0.0**: Initial release with 5 integration scripts

package/data/skills/numerical-stability/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: numerical-stability
+description: Analyze and enforce numerical stability for time-dependent PDE simulations. Use when selecting time steps, choosing explicit/implicit schemes, diagnosing numerical blow-up, checking CFL/Fourier criteria, von Neumann analysis, matrix conditioning, or detecting stiffness in advection/diffusion/reaction problems.
+allowed-tools: Read, Bash, Write, Grep, Glob
+---
+
+# Numerical Stability
+
+## Goal
+
+Provide a repeatable checklist and script-driven checks to keep time-dependent simulations stable and defensible.
+
+## Requirements
+
+- Python 3.8+
+- NumPy (for matrix_condition.py and von_neumann_analyzer.py)
+- See `scripts/requirements.txt` for dependencies
+
+## Inputs to Gather
+
+| Input | Description | Example |
+|-------|-------------|---------|
+| Grid spacing `dx` | Spatial discretization | `0.01 m` |
+| Time step `dt` | Temporal discretization | `1e-4 s` |
+| Velocity `v` | Advection speed | `1.0 m/s` |
+| Diffusivity `D` | Thermal/mass diffusivity | `1e-5 m²/s` |
+| Reaction rate `k` | First-order rate constant | `100 s⁻¹` |
+| Dimensions | 1D, 2D, or 3D | `2` |
+| Scheme type | Explicit or implicit | `explicit` |
+
+## Decision Guidance
+
+### Choosing Explicit vs Implicit
+
+```
+Is the problem stiff (fast + slow dynamics)?
+├── YES → Use implicit or IMEX scheme
+│         └── Check conditioning with matrix_condition.py
+└── NO → Is CFL/Fourier satisfied with reasonable dt?
+    ├── YES → Use explicit scheme (cheaper per step)
+    └── NO → Consider implicit or reduce dx
+```
+
+### Stability Limit Quick Reference
+
+| Physics | Number | Explicit Limit (1D) | Formula |
+|---------|--------|---------------------|---------|
+| Advection | CFL | C ≤ 1 | `C = v·dt/dx` |
+| Diffusion | Fourier | Fo ≤ 0.5 | `Fo = D·dt/dx²` |
+| Reaction | Reaction | R ≤ 1 | `R = k·dt` |
+
+**Multi-dimensional correction**: For d dimensions, diffusion limit is `Fo ≤ 1/(2d)`.
+
+## Script Outputs (JSON Fields)
+
+| Script | Key Outputs |
+|--------|-------------|
+| `scripts/cfl_checker.py` | `metrics.cfl`, `metrics.fourier`, `recommended_dt`, `stable` |
+| `scripts/von_neumann_analyzer.py` | `results.max_amplification`, `results.stable` |
+| `scripts/matrix_condition.py` | `results.condition_number`, `results.is_symmetric` |
+| `scripts/stiffness_detector.py` | `results.stiffness_ratio`, `results.stiff`, `results.recommendation` |
+
+## Workflow
+
+1. **Identify dominant physics** (advection vs diffusion vs reaction)
+2. **Run CFL checker** with `scripts/cfl_checker.py`
+3. **Compare to limits** and adjust `dt` if needed
+4. **Check stiffness** with `scripts/stiffness_detector.py` if multiple scales
+5. **Analyze custom schemes** with `scripts/von_neumann_analyzer.py`
+6. **Check conditioning** with `scripts/matrix_condition.py` for implicit solves
+7. **Document** the stability verdict and recommended time step
+
+## Conversational Workflow Example
+
+**User**: My phase-field simulation is blowing up after 100 steps. I'm using explicit Euler with dx=0.01, dt=1e-4, and diffusivity D=1e-3.
+
+**Agent workflow**:
+1. Check stability criteria:
+   ```bash
+   python3 scripts/cfl_checker.py --dx 0.01 --dt 1e-4 --diffusivity 1e-3 --dimensions 2 --json
+   ```
+2. Interpret results:
+   - Fourier number: `Fo = 1e-3 × 1e-4 / (0.01)² = 1.0`
+   - 2D limit: `Fo ≤ 0.25`
+   - **Violation**: Fo = 1.0 > 0.25, unstable!
+3. Recommend fix:
+   - Reduce dt to `2.5e-5` (to get Fo = 0.25)
+   - Or increase dx, or switch to implicit
+
+## Pre-Simulation Stability Checklist
+
+- [ ] Identify dominant physics and nondimensional groups
+- [ ] Compute CFL/Fourier/Reaction numbers with `cfl_checker.py`
+- [ ] If explicit and limit violated, reduce `dt` or change scheme
+- [ ] If stiffness ratio > 1000, select implicit/stiff integrator
+- [ ] For custom schemes, verify amplification factor ≤ 1
+- [ ] Document stability reasoning with inputs and outputs
+
+## CLI Examples
+
+```bash
+# Check CFL/Fourier for 2D diffusion-advection
+python3 scripts/cfl_checker.py --dx 0.1 --dt 0.01 --velocity 1.0 --diffusivity 0.1 --dimensions 2 --json
+
+# Von Neumann analysis for custom 3-point stencil
+python3 scripts/von_neumann_analyzer.py --coeffs 0.2,0.6,0.2 --dx 1.0 --nk 128 --json
+
+# Detect stiffness from eigenvalue estimates
+python3 scripts/stiffness_detector.py --eigs=-1,-1000 --json
+
+# Check matrix conditioning for implicit system
+python3 scripts/matrix_condition.py --matrix A.npy --norm 2 --json
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `dx and dt must be positive` | Zero or negative values | Provide valid positive numbers |
+| `No stability criteria applied` | Missing velocity/diffusivity | Provide at least one physics parameter |
+| `Matrix file not found` | Invalid path | Check matrix file exists |
+| `Could not compute eigenvalues` | Singular or ill-formed matrix | Check matrix validity |
+
+## Interpretation Guidance
+
+| Scenario | Meaning | Action |
+|----------|---------|--------|
+| `stable: true` | All checked criteria satisfied | Proceed with simulation |
+| `stable: false` | At least one limit violated | Reduce dt or change scheme |
+| `stable: null` | No criteria could be applied | Provide more physics inputs |
+| Stiffness ratio > 1000 | Problem is stiff | Use implicit integrator |
+| Condition number > 10⁶ | Ill-conditioned | Use scaling/preconditioning |
+
+## Limitations
+
+- **Explicit schemes only** for CFL/Fourier checks (implicit is unconditionally stable)
+- **Von Neumann analysis** assumes linear, constant-coefficient, periodic BCs
+- **Stiffness detection** requires eigenvalue estimates from user
+
+## References
+
+- `references/stability_criteria.md` - Decision thresholds and formulas
+- `references/common_pitfalls.md` - Frequent failure modes and fixes
+- `references/scheme_catalog.md` - Stability properties of common schemes
+
+## Version History
+
+- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples
+- **v1.0.0**: Initial release with 4 stability analysis scripts