docs: consolidate pipeline references and remove stale guides

Author: RandomOscillations

README.md

@@ -31,6 +31,7 @@ Extropy creates synthetic populations grounded in real-world distributions, conn
 ```bash
 pip install extropy-run
 export OPENAI_API_KEY=sk-...
+# or: ANTHROPIC_API_KEY=... / AZURE_OPENAI_API_KEY=...
 ```
 
 Requires Python 3.11+. [uv](https://github.com/astral-sh/uv) recommended.
@@ -61,7 +62,7 @@ extropy results segment income
 ## How It Works
 
 1. **Population** — LLM discovers attributes, researches real-world distributions, samples agents
-2. **Network** — Connects agents by similarity; edge types affect information flow
+2. **Network** — Builds structural + similarity edges; edge types affect information flow
 3. **Two-pass reasoning** — Agent role-plays reaction, then classifier extracts outcomes
 4. **Propagation** — Opinions spread through network; agents update after hearing from peers
 
@@ -79,9 +80,9 @@ extropy results segment income
 | Similarity edges | Acquaintances and online contacts from attribute similarity |
 | Small-world | Calibrated clustering coefficient and path lengths |
 | **Simulation** | |
-| Two-pass reasoning | Role-play first, classify second — eliminates central tendency bias |
+| Two-pass reasoning | Role-play first, classify second — reduces schema anchoring in outcome extraction |
 | Conversations | Agents talk to each other; both update state independently |
-| Memory | Full reasoning history with emotional trajectory |
+| Memory | Persistent memory traces with fidelity-based prompt trimming |
 | Conviction | Affects sharing probability and flip resistance |
 | THINK vs SAY | Internal monologue separate from public statement |
 | Timeline events | New information injected at specified timesteps |

docs/architecture.md

@@ -10,6 +10,28 @@ extropy spec → extropy scenario → extropy persona → extropy sample → ext
 
 All commands operate within a **study folder** — a directory containing `study.db` and scenario subdirectories. Data is keyed by `scenario_id` rather than `population_id`.
 
+## Reference Study Blueprints
+
+These are the canonical study patterns consolidated from prior showcase and study docs.
+
+| Study Type | Population | Scenario Mode | Horizon | Typical Scale |
+|------------|------------|---------------|---------|---------------|
+| ASI announcement + societal transition | National population | Evolving | Monthly, 6 steps | 5,000 agents |
+| Geopolitical shock (for example Iran strikes) | National population | Evolving | Weekly, 12 steps | 5,000 agents |
+| Asset/market mania shock (for example BTC extreme rally) | National population | Evolving | Weekly, 8-12 steps | 5,000 agents |
+| Election projection (house control / state race) | National or state electorate | Static or lightly evolving | Decision-focused | 1,000-5,000 agents |
+
+## Operational Quality Gates
+
+Before moving forward to the next stage, the architecture assumes these checks:
+
+1. `spec` gate: distribution realism and dependency coherence.
+2. `scenario` gate: timeline/outcome consistency and no contradictory rules.
+3. `persona` gate: natural language quality and no contradictory rendering.
+4. `sample` gate: no impossible household or demographic combinations.
+5. `network` gate: topology pass with realistic structural edge mix.
+6. `simulate` gate: expected timestep dynamics, checkpoint integrity, and tracked outputs.
+
 ---
 
 ## Phase 1: Population Creation (`extropy/population/`)
@@ -353,8 +375,8 @@ Resolution order: programmatic > env vars > config file > defaults
 |-------|---------|-------------|
 | `fast` | `= models.fast` | Fast model for Pass 2 |
 | `strong` | `= models.strong` | Strong model for Pass 1 |
-| `max_concurrent` | 50 | Max concurrent LLM calls |
-| `rate_tier` | 1 | Provider rate limit tier |
+| `max_concurrent` | `null` (auto from RPM) | Max concurrent LLM calls |
+| `rate_tier` | `null` | Provider rate limit tier |
 
 ### Providers
 

docs/capabilities.md

@@ -8,8 +8,6 @@ Complete reference for all Extropy CLI commands, flags, and options.
 
 ```
 extropy spec ──> extropy scenario ──> extropy persona ──> extropy sample ──> extropy network ──> extropy simulate ──> extropy results
-                                                                                                      │
-                                                                                               extropy estimate
 ```
 
 All commands operate within a **study folder** — a directory containing `study.db` and scenario subdirectories. Commands auto-detect the study folder from the current working directory.
@@ -35,13 +33,10 @@ All commands support these global options:
 
 | Flag | Description |
 |------|-------------|
-| `--json` | Output machine-readable JSON instead of human-friendly text |
 | `--version` | Show version and exit |
 | `--cost` | Show cost summary after command completes |
 | `--study PATH` | Study folder path (auto-detected from cwd if not specified) |
 
-**Note:** These are root-level Typer options. Place them before the subcommand, e.g. `extropy --json spec "Austin commuters" -o study`.
-
 ---
 
 ## extropy spec
@@ -630,28 +625,6 @@ Only `SELECT`, `WITH`, and `EXPLAIN` queries are allowed.
 
 ---
 
-## extropy estimate
-
-Predict simulation cost without making API calls.
-
-```bash
-extropy estimate -s ai-adoption
-extropy estimate -s ai-adoption --strong openai/gpt-5
-extropy estimate -s ai-adoption --strong openai/gpt-5 --fast openai/gpt-5-mini -v
-```
-
-### Options
-
-| Flag | Short | Type | Default | Description |
-|------|-------|------|---------|-------------|
-| `--scenario` | `-s` | string | auto | Scenario name |
-| `--strong` | | string | config | Strong model for Pass 1 |
-| `--fast` | | string | config | Fast model for Pass 2 |
-| `--threshold` | `-t` | int | 3 | Multi-touch threshold |
-| `--verbose` | `-v` | flag | false | Show per-timestep breakdown |
-
----
-
 ## extropy validate
 
 Validate a population or scenario spec.
@@ -818,9 +791,6 @@ extropy persona -s congestion-tax -y
 extropy sample -s congestion-tax -n 500 --seed 42
 extropy network -s congestion-tax --seed 42
 
-# Estimate cost before running
-extropy estimate -s congestion-tax
-
 # Run simulation
 extropy simulate -s congestion-tax --seed 42
 
@@ -847,3 +817,37 @@ extropy config set simulation.strong anthropic/claude-sonnet-4-6
 extropy config set cli.mode agent  # for AI harnesses
 extropy config set cli.mode human  # for terminal users (default)
 ```
+
+---
+
+## Reference Study Recipes
+
+### ASI (Evolving, Monthly, 6 timesteps)
+
+```bash
+extropy scenario "ASI announcement with escalating social/economic impacts over 6 months" \
+  --timeline evolving \
+  --timestep-unit month \
+  --max-timesteps 6 \
+  -o asi-announcement -y
+
+extropy persona -s asi-announcement -y
+extropy sample -s asi-announcement -n 5000 --seed 42
+extropy network -s asi-announcement --seed 42
+extropy simulate -s asi-announcement --seed 42 --fidelity high --early-convergence off
+```
+
+### Iran Strikes (Evolving, Weekly, 12 timesteps)
+
+```bash
+extropy scenario "US strikes on Iran with 12-week escalation and partial de-escalation timeline" \
+  --timeline evolving \
+  --timestep-unit week \
+  --max-timesteps 12 \
+  -o iran-strikes -y
+
+extropy persona -s iran-strikes -y
+extropy sample -s iran-strikes -n 5000 --seed 42
+extropy network -s iran-strikes --seed 42
+extropy simulate -s iran-strikes --seed 42 --fidelity high --early-convergence off
+```

docs/commands.md

@@ -423,9 +423,6 @@ Need:
 ### `chat` and agent-level introspection
 Indirectly depend on simulation dynamics that are shaped by network structure.
 
-### `estimate`
-Does not directly depend on network internals, but simulation runtime quality/cost behavior is affected by network density and connectedness.
-
 ---
 
 ## Working Invariants Draft (Network-Oriented)

docs/pipeline/network.md

@@ -560,10 +560,6 @@ Needs:
 - optional extraction instructions,
 - identity dimensions.
 
-### `estimate`
-Needs:
-- scenario simulation/time parameters + spread/exposure assumptions.
-
 ### `results`, `query`, `chat`
 Depend on scenario-defined outcome schema and timeline semantics for interpretation and querying consistency.