@monoes/monomindcli 2.15.3 → 2.15.5

package/org-skills/experiment-designer/references/statistics-reference.md

@@ -0,0 +1,56 @@
+# Statistics Reference for Product Managers
+
+## p-value
+
+The p-value is the probability of observing data at least as extreme as yours if there were no true effect.
+
+- Small p-value means data is less consistent with "no effect".
+- It does not tell you the probability that the variant is best.
+
+## Confidence Interval (CI)
+
+A CI gives a plausible range for the true effect size.
+
+- Narrow interval: more precise estimate.
+- Wide interval: uncertain estimate.
+- If CI includes zero (or no-effect), directional confidence is weak.
+
+## Minimum Detectable Effect (MDE)
+
+The smallest effect worth detecting.
+
+- Set MDE by business value threshold, not wishful optimism.
+- Smaller MDE requires larger sample size.
+
+## Statistical Power
+
+Power is the probability of detecting a true effect of at least MDE.
+
+- Common target: 80% (0.8)
+- Higher power increases sample requirements.
+
+## Type I and Type II Errors
+
+- Type I (false positive): claim effect when none exists (controlled by alpha).
+- Type II (false negative): miss a real effect (controlled by power).
+
+## Practical Significance
+
+An effect can be statistically significant but too small to matter.
+
+Always ask:
+- Does the effect clear implementation cost?
+- Does it move strategic KPIs materially?
+
+## Power Analysis Inputs
+
+For conversion experiments (two proportions):
+- Baseline conversion rate
+- MDE (absolute points or relative uplift)
+- Alpha (e.g., 0.05)
+- Power (e.g., 0.8)
+
+Output:
+- Required sample size per variant
+- Total sample size
+- Approximate runtime based on traffic volume

package/{dist/src/orgrt/role-skills/experiment-tracker.md → org-skills/experiment-tracker/SKILL.md}

@@ -1,3 +1,11 @@
+---
+name: experiment-tracker
+description: "Experiment Tracker role best practices. Records and organizes every experiment (ML training run, A/B test, feature trial) — parameters, code version, data, environment, and results — so outcomes are reproducible, comparable, and auditable."
+tags: ["ai-ml","engineering"]
+tools: ["monograph_query","monograph_context","monograph_impact"]
+license: Apache-2.0
+source: https://github.com/monoes/monomind
+---
 # Experiment Tracker — Best Practices
 
 ## Focus

package/org-skills/experimental-design/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 K-Dense Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/org-skills/experimental-design/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: experimental-design
+description: "Design experiments and studies BEFORE data is collected — choosing a design, randomizing, blocking, and laying out treatment combinations so results are interpretable."
+tags: ["science","research","data"]
+tools: []
+license: MIT
+source: https://github.com/K-Dense-AI/scientific-agent-skills
+source_path: "skills/experimental-design"
+source_commit: 49c6e97775eaa18ba791bebe23162a70ae601c18
+---
+# Experimental Design
+
+## Overview
+
+The design of a study — how units are assigned to conditions, what is held constant, what is varied, and in what structure — determines what questions the data can answer. No analysis can rescue a confounded or pseudoreplicated design after the fact. This skill is about the decisions made *before* data collection: picking a design that isolates the effect of interest, randomizing to license causal claims, blocking to remove known nuisance variation, and structuring multi-factor experiments so effects are estimable rather than tangled together.
+
+The three ideas behind almost every good design (Fisher's principles):
+- **Randomization** — assign treatments at random so that confounders, known and unknown, are balanced in expectation. This is what turns a comparison into a causal claim.
+- **Replication** — independent repetition at the right level, so you can estimate variability and your effects aren't artifacts of a single unit. The most common fatal error is **pseudoreplication**: counting repeated measurements on the same unit as independent replicates.
+- **Blocking / local control** — group similar units (by batch, day, site, litter) and randomize within blocks, removing that nuisance variation from the error term instead of letting it inflate noise.
+
+This skill helps you choose among design types, generate the actual randomization or DOE layout (with reproducible scripts), and avoid the structural mistakes that make data uninterpretable.
+
+## When to Use This Skill
+
+- Planning any comparative experiment or trial and deciding how to assign units
+- Randomizing subjects/samples to arms (simple, blocked, stratified, or cluster)
+- Removing nuisance variation by blocking or stratification
+- Designing multi-factor experiments: full or fractional factorial, screening designs
+- Optimizing a response over continuous factors (response-surface designs)
+- Within-subject / repeated-measures, crossover, split-plot, or Latin-square designs
+- Cluster- or group-randomized designs (sites, clinics, classrooms, litters)
+- Deciding the number and level of replicates and avoiding pseudoreplication
+- Sequential, group-sequential, or adaptive designs with interim analyses
+- Laying out plates/batches and randomizing run order to defeat drift
+
+## Installation
+
+```bash
+uv pip install "numpy>=1.26" "pandas>=2.0" pyDOE3
+```
+
+`pyDOE3` is the maintained successor to pyDOE/pyDOE2 and supplies factorial,
+fractional-factorial, Plackett-Burman, central-composite, Box-Behnken, and
+Latin-hypercube generators. The bundled scripts wrap it to return designs in real
+factor units with named columns and randomized run order.
+
+---
+
+## Choosing a design
+
+Start from the question and the structure of your units, not from a favorite design.
+
+```
+What are you trying to learn?
+│
+├─ Compare a few predefined conditions (A vs B vs C)?
+│   ├─ Units independent, possibly with a known nuisance factor (day, batch, site)?
+│   │     → Completely randomized (no nuisance) or RANDOMIZED BLOCK design.
+│   ├─ Each unit can receive every condition in sequence (washout possible)?
+│   │     → CROSSOVER / repeated-measures design (more power, watch carry-over).
+│   └─ You can only randomize groups, not individuals (schools, clinics)?
+│         → CLUSTER-randomized design (analyze at the cluster level; see pseudoreplication).
+│
+├─ Screen MANY factors (5+) to find the few that matter?
+│     → FRACTIONAL FACTORIAL or PLACKETT-BURMAN screening design.
+│
+├─ Quantify main effects AND interactions among a handful of factors?
+│     → FULL 2^k FACTORIAL design.
+│
+├─ Find the settings that OPTIMIZE a response (curvature matters)?
+│     → RESPONSE-SURFACE design: central composite or Box-Behnken.
+│
+└─ Explore a simulation/computer model over a continuous space?
+      → SPACE-FILLING design: Latin hypercube.
+```
+
+Detailed guidance per branch:
+- **Randomization, blocking, stratification, controls** → `references/randomization_and_blocking.md`
+- **Factorial, fractional-factorial, screening, response-surface, DOE concepts (aliasing, resolution)** → `references/factorial_and_doe.md`
+- **Crossover, repeated-measures, split-plot, Latin-square, cluster, nested designs** → `references/design_types.md`
+- **Sequential, group-sequential, and adaptive designs (interim analyses)** → `references/sequential_and_adaptive.md`
+
+---
+
+## Generating the design
+
+Two scripts produce ready-to-use, reproducible layouts. Run them from the skill's
+`scripts/` directory or add it to `sys.path`. Everything is seeded so the exact
+schedule can be archived and regenerated — a requirement for trial registration
+and good lab practice.
+
+### Randomization / allocation schedules — `scripts/randomization.py`
+
+```python
+from randomization import (
+    simple_randomization, block_randomization,
+    stratified_block_randomization, cluster_randomization,
+    assign_factorial_runs, arm_balance,
+)
+
+# Permuted blocks keep the arms balanced throughout enrollment (use for n < ~100
+# or sequential intake — simple randomization can drift out of balance with small n)
+sched = block_randomization(n=60, arms=["treatment", "control"], seed=42)
+
+# Balance a prognostic variable across arms by randomizing within each stratum
+sched = stratified_block_randomization({"siteA": 30, "siteB": 30},
+                                       arms=["drug", "placebo"], ratio=(2, 1), seed=42)
+
+# Randomize whole clusters, not individuals (the cluster is the unit)
+sched = cluster_randomization(["clinic1", "clinic2", "clinic3", "clinic4"], seed=42)
+
+arm_balance(sched)            # sanity-check the counts per arm
+sched.to_csv("allocation_schedule.csv", index=False)
+```
+
+Choosing among them: **simple** is fine for large n but can produce imbalance with
+small n; **block** guarantees balance throughout; **stratified block** additionally
+balances a known prognostic factor; **cluster** is mandatory when the intervention
+is delivered at a group level. See `references/randomization_and_blocking.md`.
+
+### DOE matrices — `scripts/doe_designs.py`
+
+```python
+from doe_designs import (
+    full_factorial, two_level_factorial, fractional_factorial,
+    plackett_burman, central_composite, box_behnken, latin_hypercube,
+)
+
+# Factors as real-world (low, high) ranges -> design comes back in real units
+factors = {"temp_C": (20, 60), "conc_mM": (1, 10), "pH": (6, 8)}
+
+# Full 2^3: all main effects + all interactions (8 runs), run order randomized
+design = two_level_factorial(factors, seed=42)
+
+# Screen 7 factors cheaply (main effects only)
+many = {f"factor_{i}": (0, 1) for i in range(7)}
+design = plackett_burman(many, seed=42)
+
+# Optimize over 2 factors with curvature (response-surface)
+design = central_composite({"temp_C": (20, 60), "conc_mM": (1, 10)}, seed=42)
+
+design.to_csv("experimental_runs.csv", index=False)
+```
+
+Run order is randomized by default so factors aren't confounded with time/drift
+(machine warm-up, reagent aging). See `references/factorial_and_doe.md` for picking
+generators, reading the alias structure, and choosing resolution.
+
+---
+
+## The mistakes that ruin studies
+
+These are structural — they can't be fixed in analysis, only in design.
+
+1. **Pseudoreplication.** Treating repeated measurements of one unit as independent
+   replicates: 3 mice with 100 cells each is n = 3 (mice), not n = 300 (cells), for
+   any treatment applied to the mouse. The replicate must be at the level the
+   treatment is randomized. This single error invalidates a large share of published
+   experiments. Randomize and replicate at the right level; analyze with the nesting
+   respected (mixed model). See `references/design_types.md`.
+2. **Confounding by a nuisance variable.** Running all treatment samples on Monday
+   and all controls on Tuesday confounds treatment with day. Randomize across, or
+   block on, every nuisance factor you can name (batch, day, plate, technician,
+   instrument, position).
+3. **No or broken randomization.** Convenience assignment (first-come → treatment)
+   lets confounders sneak in. Use a seeded schedule and follow it.
+4. **No proper control.** Without a concurrent control (and, where relevant, a
+   vehicle/sham and blinding), you can't separate the treatment effect from time,
+   placebo, or handling effects.
+5. **Batch effects mistaken for biology.** In omics especially, process samples in a
+   randomized/blocked order across batches; never let batch align with the condition.
+6. **Edge/position effects on plates.** Evaporation and thermal gradients make plate
+   edges differ. Randomize or block sample positions; don't put all controls in
+   column 1.
+7. **Aliasing ignored in fractional designs.** A low-resolution fractional factorial
+   confounds main effects with interactions; know your alias structure before
+   concluding a factor "has no effect."
+8. **Optimizing without curvature.** A two-level factorial can't detect a curved
+   response; you'll miss an interior optimum. Use a response-surface design.
+
+---
+
+## Workflow
+
+1. **State the question, the unit, and the response.** What is randomized? What is
+   measured? At what level is a true independent replicate? This determines everything.
+2. **List nuisance factors** (batch, day, site, operator, position) — plan to block,
+   stratify, or randomize across each.
+3. **Pick the design** using the decision tree and reference files.
+4. **Decide replication** at the correct level (and get n from the
+   **statistical-power** skill for the chosen design).
+5. **Generate the layout** with `randomization.py` / `doe_designs.py`, seeded.
+6. **Randomize run/processing order** and plate/batch positions.
+7. **Document** the design, seed, and schedule (pre-register if possible) so the
+   analysis is confirmatory and the layout is auditable.
+8. **Match the analysis to the design** — blocks, strata, clusters, and nesting must
+   appear in the model (hand off to **statistical-analysis** / **statsmodels**).
+
+---
+
+## Resources
+
+### Scripts
+- `scripts/randomization.py` — seeded allocation schedules: `simple_randomization`,
+  `block_randomization`, `stratified_block_randomization`, `cluster_randomization`,
+  `assign_factorial_runs`, `arm_balance`.
+- `scripts/doe_designs.py` — DOE matrices in real units: `full_factorial`,
+  `two_level_factorial`, `fractional_factorial`, `plackett_burman`,
+  `central_composite`, `box_behnken`, `latin_hypercube`.
+
+### References
+- `references/randomization_and_blocking.md` — randomization methods, blocking,
+  stratification, controls, blinding, batch/plate layout.
+- `references/factorial_and_doe.md` — factorial and fractional designs, resolution
+  and aliasing, screening, and response-surface methodology.
+- `references/design_types.md` — completely randomized, randomized block, crossover,
+  repeated-measures, split-plot, Latin-square, cluster, and nested designs; the
+  pseudoreplication problem in depth.
+- `references/sequential_and_adaptive.md` — group-sequential designs, alpha spending,
+  interim stopping, and adaptive sample-size re-estimation.
+
+### Related skills
+- **statistical-power** — required sample size / power for the design you've chosen.
+- **statistical-analysis** — running and reporting the analysis after collection.
+- **statsmodels** / **pymc** — fitting the models the design implies.
+
+### Key references
+- Fisher, R. A. (1935). *The Design of Experiments*.
+- Montgomery, D. C. (2019). *Design and Analysis of Experiments* (10th ed.).
+- Hurlbert, S. H. (1984). Pseudoreplication and the design of ecological field
+  experiments. *Ecological Monographs*, 54(2), 187–211.
+- Lazic, S. E. (2016). *Experimental Design for Laboratory Biologists*.
+
+## Citing Scientific Agent Skills
+
+This skill is part of Scientific Agent Skills by K-Dense. If it materially contributed to a
+manuscript, report, presentation, or code release, add the paper to the references or
+software section and tell the user you did so:
+
+> Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent
+> Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065.
+> https://doi.org/10.48550/arXiv.2609.00065
+
+Always cite the current version. The DOI and https://arxiv.org/abs/2609.00065 resolve to the
+latest arXiv version, so never append a version suffix such as `v1`. When network access is
+available, fetch https://arxiv.org/abs/2609.00065 (or
+http://export.arxiv.org/api/query?id_list=2609.00065) before writing the reference and take
+the author list, year, and version from that record. If the record lists a journal reference
+or publisher DOI, cite the published version instead.

package/org-skills/experimental-design/references/design_types.md

@@ -0,0 +1,129 @@
+# Design Types and the Replication Structure
+
+Choosing the right design structure is mostly about matching the *unit of
+randomization* and the *unit of replication* to your question, and respecting any
+nesting in the analysis. This file walks through the standard structures and then
+treats the single most common fatal error — pseudoreplication — in depth.
+
+## Table of contents
+- [Completely randomized design](#completely-randomized-design)
+- [Randomized complete block design](#randomized-complete-block-design)
+- [Latin square](#latin-square)
+- [Repeated-measures and crossover](#repeated-measures-and-crossover)
+- [Split-plot designs](#split-plot-designs)
+- [Cluster / group-randomized designs](#cluster--group-randomized-designs)
+- [Nested designs and pseudoreplication](#nested-designs-and-pseudoreplication)
+
+## Completely randomized design
+
+Units are assigned to treatments purely at random, no blocking. Simplest design;
+appropriate when units are homogeneous and there's no identifiable nuisance factor.
+Analyze with one-way ANOVA / regression. If units are *not* homogeneous, the
+nuisance variation inflates error — block instead.
+
+## Randomized complete block design
+
+Group units into **blocks** of similar units (day, batch, litter), and randomize all
+treatments *within* each block. Every treatment appears once per block. The
+between-block variation is removed from the error term, sharply increasing precision
+when blocks differ. Analyze with `treatment + block` in the model. This is the
+default upgrade over a completely randomized design whenever a nuisance factor exists.
+
+## Latin square
+
+Controls **two** nuisance factors simultaneously with a square layout: each treatment
+appears exactly once in every row and every column. Classic uses: row = day, column =
+position/order, cell = treatment. Requires #treatments = #rows = #columns, and assumes
+no interactions between the blocking factors and treatment. Efficient when both
+nuisance dimensions matter and runs are limited. (Graeco-Latin squares extend this to
+three nuisance factors.)
+
+## Repeated-measures and crossover
+
+Each subject receives more than one condition, serving as its own control. This
+removes between-subject variation — usually the largest noise source — so these
+designs are far more powerful per subject.
+
+- **Repeated measures:** the same units measured under several conditions or over
+  time.
+- **Crossover:** each subject receives each treatment in sequence, with **washout**
+  periods between to clear carry-over. Subjects are randomized to treatment *orders*
+  (e.g. an AB/BA crossover; or a Williams square for ≥3 treatments to balance order).
+
+Watch for:
+- **Carry-over / residual effects** — an effect of the previous treatment persisting
+  into the next period. Adequate washout is essential; otherwise the design is biased.
+- **Period effects** — systematic change over time (learning, fatigue, disease
+  progression). Balanced orders let you separate period from treatment.
+- **Correlation within subject** — the repeated observations are not independent; the
+  analysis must model it (mixed model / repeated-measures ANOVA). Sample-size/power
+  for these depends on the within-subject correlation — use simulation in the
+  **statistical-power** skill.
+
+## Split-plot designs
+
+Arises when some factors are **hard to change** (applied to large units) and others
+are **easy to change** (applied to sub-units). The hard-to-change factor is randomized
+to whole plots; the easy factor is randomized to subplots within each whole plot.
+Example: oven temperature (whole plot — you can't re-set it per sample) × coating type
+(subplot — applied per sample). Crucially there are **two different error terms** — one
+for whole-plot factors, one for subplot factors — and the analysis must use both.
+Treating a split-plot as a completely randomized factorial gives wrong (usually
+anticonservative) tests for the whole-plot factor. Industrial DOE and agricultural
+trials are full of accidental split-plots; recognize when a factor can't be reset per
+run.
+
+## Cluster / group-randomized designs
+
+When the intervention is delivered to a *group* (a clinic's protocol, a classroom
+curriculum, a village water supply), you can only randomize at the group level. The
+**cluster is the unit of randomization**, and because members of a cluster are
+correlated, it is effectively the unit of replication too.
+
+- Power depends on the number of **clusters** far more than the number of individuals,
+  and on the **intraclass correlation (ICC)**. Adding people to existing clusters
+  helps much less than adding clusters.
+- The **design effect** `DEFF = 1 + (m − 1)·ICC` (m = cluster size) quantifies how
+  much the effective sample size shrinks; even a small ICC with large clusters costs
+  dearly. Power these by simulation (see **statistical-power**).
+- Analyze with a method that accounts for clustering (mixed model with a cluster
+  random effect, or GEE). Analyzing individuals as independent is pseudoreplication.
+
+## Nested designs and pseudoreplication
+
+**Pseudoreplication** is treating non-independent measurements as independent
+replicates. It is the most common and most damaging design error in experimental
+biology, and it cannot be fixed after data collection — only by designing and
+analyzing at the correct level.
+
+The principle: **the replicate is whatever the treatment is independently applied
+and randomized to.** Measurements taken below that level are *technical replicates* —
+they improve the precision of a single unit's value but do **not** add degrees of
+freedom for testing the treatment.
+
+Worked examples:
+- **One dish per treatment, 50 cells imaged.** Treatment applied to the dish ⇒ n = 1
+  per treatment. The 50 cells describe that one dish; they are not 50 independent
+  tests of the treatment. You need multiple independently treated dishes.
+- **3 mice per group, 100 cells each.** n = 3 (mice) for a treatment given to the
+  mouse, not 300 (cells). Average within mouse, or use a mixed model with mouse as a
+  random effect.
+- **One tank of fish given a diet, every fish measured.** The tank is the unit (the
+  diet was randomized to the tank) ⇒ n = number of tanks, not number of fish. Shared
+  tank water, temperature, and social effects make fish within a tank correlated.
+- **Repeated measurements over time on the same subject** are nested within subject;
+  the subject is the replicate.
+
+How to avoid it:
+1. **Identify the experimental unit** = the smallest physical entity to which a
+   treatment level is independently and randomly assigned.
+2. **Replicate at that level** — more independently treated units, not more
+   measurements per unit (though technical replicates can reduce measurement noise).
+3. **Analyze with the nesting respected** — average to the unit level, or fit a mixed
+   model with random effects for the nesting (cells in mice, fish in tanks, time in
+   subjects). The fixed-effect treatment test then uses the correct, larger error and
+   correct degrees of freedom.
+
+Technical replicates are still worth taking — they sharpen each unit's estimate — but
+report and analyze them as what they are, never as independent biological replicates.
+For sample size of nested/clustered designs, use simulation in **statistical-power**.

package/org-skills/experimental-design/references/factorial_and_doe.md

@@ -0,0 +1,130 @@
+# Factorial and Design-of-Experiments (DOE)
+
+When several factors might affect a response, testing them **one factor at a time
+(OFAT)** is both wasteful and blind to interactions. Factorial designs vary factors
+*together*, so you estimate every main effect and interaction from the same runs,
+with better precision per run. This file covers the family of DOE designs and the
+concepts (resolution, aliasing) needed to read them. Generate them with
+`scripts/doe_designs.py`.
+
+## Table of contents
+- [Why factorial beats OFAT](#why-factorial-beats-ofat)
+- [Full factorial (2^k)](#full-factorial)
+- [Fractional factorial (2^(k-p))](#fractional-factorial)
+- [Resolution and aliasing](#resolution-and-aliasing)
+- [Screening designs (Plackett-Burman)](#screening-designs)
+- [Response-surface designs](#response-surface-designs)
+- [Space-filling designs](#space-filling-designs)
+- [Choosing a design](#choosing-a-design)
+
+## Why factorial beats OFAT
+
+Vary one factor while holding others fixed and you (1) spend runs inefficiently and
+(2) can never see **interactions** — cases where the effect of A depends on the level
+of B, which are the rule, not the exception, in real systems. A factorial varies all
+factors simultaneously across runs; each effect is estimated using *all* the data, so
+a 2^k factorial is more precise than k separate OFAT studies of the same size.
+
+## Full factorial
+
+A **2^k** design runs every combination of k factors at two levels (low/high, coded
+−1/+1). It estimates all k main effects and all 2^k − k − 1 interactions.
+
+- Runs = 2^k: 8 for 3 factors, 16 for 4, 32 for 5. Practical to ~5 factors.
+- Use when you have a handful of factors and want a full picture including
+  interactions.
+- `two_level_factorial({"temp": (20,60), "conc": (1,10), "pH": (6,8)})` → 8 runs.
+- For factors with more than two levels, use `full_factorial` with explicit level
+  lists (runs = product of level counts — grows fast).
+
+Add **center points** (all factors at their midpoint) to a two-level design to get a
+cheap check for curvature: if the center response departs from the factorial average,
+a linear model is inadequate and you need a response-surface design.
+
+## Fractional factorial
+
+When k is large, 2^k is too many runs — but most high-order interactions are
+negligible (the *sparsity-of-effects* principle). A **2^(k−p)** fractional factorial
+runs a carefully chosen fraction (1/2, 1/4, ...) of the full design, trading the
+ability to estimate some interactions for far fewer runs.
+
+- `fractional_factorial(factors, generator="a b c abc")` builds a half-fraction of 4
+  factors in 8 runs. The generator string (Yates notation) assigns each factor to a
+  column; a multi-letter token aliases that factor with an interaction.
+- The price is **aliasing**: some effects become indistinguishable. You must know
+  which.
+
+## Resolution and aliasing
+
+**Aliasing** (confounding) means two effects are estimated by the same contrast — the
+data cannot separate them. Which effects are aliased is summarized by the design's
+**resolution**:
+
+| Resolution | Aliasing | Interpretation |
+|------------|----------|----------------|
+| **III** | main effects aliased with 2-factor interactions | Screening only; a "significant" main effect might be an interaction |
+| **IV** | main effects clear of 2FI, but 2FIs aliased with each other | Good for screening; main effects trustworthy |
+| **V** | main effects and 2FIs all clear of each other (aliased with 3FI+) | Can model main effects and 2-factor interactions confidently |
+
+Always state the resolution and inspect the alias structure before interpreting a
+fractional design. Concluding "factor C has no effect" is unsafe if C is aliased with
+a real interaction (it could cancel out). When in doubt, choose a higher-resolution
+generator (more runs) or add runs to **de-alias** (fold-over / augment the design).
+
+## Screening designs
+
+When the goal is to **find the vital few** factors out of many (5, 10, 20+), use a
+screening design that estimates main effects only, as cheaply as possible:
+- **Plackett-Burman** (`plackett_burman`): runs = the next multiple of 4 above k
+  (e.g. 12 runs for up to 11 factors). Resolution III — two-factor interactions are
+  heavily confounded with main effects. Perfect for triage: run it, keep the few
+  factors with large effects, then study those with a full or higher-resolution
+  factorial.
+- Resolution III fractional factorials serve the same purpose.
+
+Screen first, optimize later — don't try to learn interactions and find the optimum
+in one cheap design.
+
+## Response-surface designs
+
+Two-level designs fit only a flat (linear + interaction) model; they cannot locate an
+interior optimum or describe **curvature**. To fit a quadratic and optimize, use a
+response-surface methodology (RSM) design over continuous factors:
+
+- **Central composite design (CCD)** (`central_composite`): a 2^k factorial + center
+  points + axial ("star") points. The axial points add the levels needed to estimate
+  quadratic terms. With `face="circumscribed"` (default) the axial points sit
+  *outside* the factorial box (so actual factor levels exceed your stated low/high);
+  use `face="inscribed"` or `"faced"` to keep everything within the original range.
+- **Box-Behnken** (`box_behnken`, needs ≥3 factors): a quadratic design that avoids
+  the extreme all-low/all-high corners — useful when those corners are unsafe,
+  expensive, or infeasible. More economical than a CCD for 3–5 factors.
+
+Workflow: screen → factorial (find important factors & rough region) → response
+surface (model curvature, locate optimum), often moving the experimental region
+between steps (path of steepest ascent).
+
+## Space-filling designs
+
+For **computer experiments / simulations** (deterministic or expensive models) where
+classical replication and blocking don't apply, you want even coverage of a
+high-dimensional input space:
+- **Latin hypercube** (`latin_hypercube`): each factor's range is divided into
+  n_samples equal bins, sampled once each, arranged to spread points apart
+  (`criterion="maximin"`). Gives good coverage with relatively few points and is the
+  standard input design for surrogate/emulator modeling and sensitivity analysis.
+
+## Choosing a design
+
+| Goal | Factors | Design | Script function |
+|------|---------|--------|-----------------|
+| Screen many factors | 5–20+ | Plackett-Burman / Res III | `plackett_burman` |
+| Main effects, some interactions, few runs | 4–8 | Res IV/V fractional | `fractional_factorial` |
+| All effects + interactions | 2–5 | Full 2^k factorial | `two_level_factorial` |
+| Multi-level categorical | few | Full factorial | `full_factorial` |
+| Optimize a response (curvature) | 2–5 | Central composite / Box-Behnken | `central_composite`, `box_behnken` |
+| Cover a simulation input space | any | Latin hypercube | `latin_hypercube` |
+
+In all cases, **randomize run order** (the scripts do by default) so factors aren't
+confounded with time-related drift, and add center points to two-level designs as a
+curvature check.