diff --git a/sample-template/README.md b/sample-template/README.md
index bcf59d3b..0af47d19 100644
--- a/sample-template/README.md
+++ b/sample-template/README.md
@@ -36,6 +36,7 @@ Use language that’s accessible to a broad audience.
 
 - **Model**: (what logic/relations are implemented)
 - **Runner**: (how to execute: Python script / CLI commands / notebook)
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills. The recommended way to learn how it is built; as important a reference as the script itself.
 - **Sample data**: (what it represents)
 - **Outputs**: (what results are produced and where)
 
@@ -114,7 +115,7 @@ Provide a short annotated tree. Keep it to the top level and the most important
 └─ ...
 ```
 
-**Start here**: point to the one command/script that runs end-to-end.
+**Start here**: name the one command/script that runs end-to-end, and point to `runbook.md` to reproduce the template step by step with the RAI skills.
 
 ## Sample data
 
@@ -122,51 +123,17 @@ Describe what the sample data represents, and any important notes about its stru
 
 ## Model overview
 
-Describe the main entities and the most important relationships.
+Give the reader the shape of the model at a glance — the README is the map, not the schema. Keep this to the three intro bullets; the full concept-and-property definitions live in the script, so don't restate them here.
 
-- **Key entities**: (e.g., `product`, `warehouse`, `lane`)
+- **Key entities**: (e.g., `product`, `warehouse`, `lane`) — name the concepts and, in a phrase each, what they represent
 - **Primary identifiers**: what uniquely identifies each entity
 - **Important invariants**: (e.g., demand non-negative; capacity limits)
 
-Document the data model concept-by-concept.
-
-### Concepts (one table per concept)
-
-For each key concept/type:
-
-1. Write a brief sentence *outside the table* describing what the concept represents and how it’s used.
-2. Add a table with **one row per property**.
-
-Suggested table shape:
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `product_id` | int | Yes | Loaded from `data/products.csv` |
-| `name` | string | No | Human-readable name |
-| `category` | string | No | Used for grouping/filters |
-
-Repeat this table for each concept (e.g., `product`, `warehouse`, `lane`).
-
-### Relationships (only if there are non-property relations)
-
-Only include a Relationships table if the model defines relations **beyond concept properties** (e.g., standalone predicates like `demand(product, date, units)` or recursive relations).
-
-| Relationship | Schema (reading string fields) | Notes |
-|---|---|---|
-| `demand(product, date, units)` | `product`, `date`, `units` | Units are weekly; non-negative |
-| `lane(source, destination, capacity)` | `source`, `destination`, `capacity` | Capacity is per day |
+For the full concept and property definitions, read `<template>.py`; to see them built step by step with the RAI skills, follow `runbook.md`.
 
 ## How it works
 
-Give a short, end-to-end walkthrough of the template, with relevant code examples. Example:
-
-- Ingest sample CSVs into relations
-- Derive intermediate relations (feature engineering / aggregations)
-- Apply constraints/objective (if optimization)
-- Compute outputs (recommended actions / assignments)
-- Export results to CSV / print summary
-
-If helpful, add a small diagram:
+Give a short, plain-language walkthrough of the chain — what each stage reads and produces and why — so a reader understands the flow without opening the code. Keep code out of this section: point to the script for the implementation and to `runbook.md` for the skill-driven reproduction. One small flow diagram is welcome:
 
 ```text
 CSV inputs → load → base relations → model logic → results → export
diff --git a/v1/ad_spend_allocation/README.md b/v1/ad_spend_allocation/README.md
index 88c8d091..1c447877 100644
--- a/v1/ad_spend_allocation/README.md
+++ b/v1/ad_spend_allocation/README.md
@@ -1,93 +1,103 @@
 ---
 title: "Ad Spend Allocation"
-description: "Allocate marketing budget across channels and campaigns to maximize conversions."
+description: "Allocate a marketing budget across advertising channels and campaigns to maximize expected conversions. Sweeps three budget levels in a single solve to show where extra budget stops paying off."
 featured: false
 experience_level: intermediate
 industry: "Retail & Consumer"
 reasoning_types:
   - Prescriptive
 tags:
-  - budget-allocation
-  - mixed-integer-programming
-  - marketing
-  - what-if-analysis
+  - Budget Allocation
+  - Mixed-Integer Programming (MIP)
+  - Marketing
+  - What-If Analysis
+  - Scenario Analysis
 ---
 
-# Ad Spend Allocation
-
 ## What this template is for
 
-Marketing teams face a recurring challenge: how to distribute a limited budget across multiple advertising channels and campaigns to get the most conversions. Each channel (search, social, display, video, email) has different minimum and maximum spend thresholds, and each channel-campaign combination has a different conversion rate. The goal is to find the spend allocation that maximizes total expected conversions while respecting per-channel bounds, per-campaign budgets, and an overall budget cap.
+Marketing teams face a recurring challenge: how to distribute a limited budget across multiple advertising channels and campaigns to get the most conversions. Each channel (search, social, display, video, email) has different minimum and maximum spend thresholds, and each channel-campaign combination has a different conversion rate. The goal is to find the spend allocation that maximizes total expected conversions while respecting per-channel bounds, per-campaign budgets, and an overall budget cap. Guessing at this by hand leaves conversions on the table; a small change in the mix can move the outcome more than a small change in the total budget.
 
-This template formulates the ad spend allocation problem as a mixed-integer program. Binary variables determine which channel-campaign combinations are active, while continuous variables set the spend levels. Constraints enforce minimum/maximum spend per channel (when active), per-campaign budget limits, and a global budget ceiling. The objective maximizes the total expected conversions computed from spend times conversion rate.
+This template also answers the follow-up question every planner asks: if we had more budget, would it help? It sweeps three total-budget levels ($35K, $45K, $55K) so you can see how additional budget translates into incremental conversions and which channels the optimizer activates at each level — often revealing that beyond a point the extra money buys nothing.
 
-The template includes scenario analysis that sweeps over three total budget levels ($35K, $45K, $55K), letting you see how additional budget translates into incremental conversions and which channels the optimizer activates at each budget level.
+**Under the hood it uses prescriptive reasoning: a mixed-integer program where binary variables decide which channel-campaign pairs to fund and continuous variables set the spend, solved for all three budget levels at once.**
 
 ## Who this is for
 
-- Marketing analysts optimizing media spend across channels
-- Growth teams evaluating budget scenarios for campaign planning
-- Data scientists building prescriptive models for ad optimization
-- Developers learning mixed-integer programming with RelationalAI
+- Marketing analysts optimizing media spend across channels.
+- Growth teams evaluating budget scenarios for campaign planning.
+- Data scientists building prescriptive models for advertising optimization.
+- Developers learning mixed-integer programming (MIP) with RelationalAI.
+- **Assumed knowledge**: comfortable reading Python. The marketing and optimization terms are explained as they come up, and no prior RelationalAI experience is required to run it.
 
 ## What you'll build
 
-- A mixed-integer optimization model for multi-channel, multi-campaign budget allocation
-- Channel activation logic with minimum/maximum spend enforcement
-- Per-campaign budget constraints and a global budget cap
-- Scenario analysis across three budget levels with comparison of results
+- A funded spend allocation across every channel-campaign pair that maximizes total expected conversions within per-channel, per-campaign, and total-budget limits, produced by **prescriptive reasoning** (mixed-integer program).
+- Channel activation logic that enforces minimum and maximum spend only when a pair is funded, using binary decision variables.
+- A `Scenario` concept that drives three budget levels through a single solve, so the whole what-if sweep is one optimization rather than three.
+- A per-scenario allocation table you can query from the ontology after the run, showing which pairs are funded and at what spend.
 
 ## What's included
 
-- `ad_spend_allocation.py` -- main script with ontology, formulation, and scenario loop
-- `data/channels.csv` -- 5 channels with spend bounds and ROI coefficients
-- `data/campaigns.csv` -- 3 campaigns with budgets and target conversions
-- `data/effectiveness.csv` -- 15 channel-campaign conversion rates
-- `pyproject.toml` -- Python package configuration
+- **Model**: a single ontology with `Channel`, `Campaign`, `Effectiveness`, `Scenario`, and an `Allocation` decision concept — plus the prescriptive formulation (decision variables, constraints, objective) that runs on it.
+- **Runner**: `ad_spend_allocation.py` — one Python script that loads the CSVs, builds the model, solves all scenarios at once, and prints the allocation table.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: 5 channels with spend bounds, 3 campaigns with budgets, and the 15 channel-campaign conversion rates. See *Sample data* below.
+- **Outputs**: solver termination status, objective value, and a per-scenario table of non-trivial spend allocations printed to stdout; the spend and funding decisions are also written back to the ontology as queryable properties.
 
 ## Prerequisites
 
 ### Access
-- A Snowflake account that has the RAI Native App installed.
-- A Snowflake user with permissions to access the RAI Native App.
+
+- A Snowflake account with the RelationalAI Native App installed.
+- A Snowflake user with permissions to access the RelationalAI Native App.
 
 ### Tools
-- Python >= 3.10
+
+- Python >= 3.10.
+- RelationalAI Python SDK (`relationalai == 1.0.14`).
 
 ## Quickstart
 
-1. Download ZIP:
+1. Download the template and extract it:
+
    ```bash
    curl -O https://docs.relational.ai/templates/zips/v1/ad_spend_allocation.zip
    unzip ad_spend_allocation.zip
    cd ad_spend_allocation
    ```
+
    > [!TIP]
    > You can also download the template ZIP using the "Download ZIP" button at the top of this page.
 
-2. Create venv:
+2. Create a virtual environment and activate it:
+
    ```bash
    python -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade pip
    ```
 
-3. Install:
+3. Install dependencies:
+
    ```bash
    python -m pip install .
    ```
 
-4. Configure:
+4. Configure your RelationalAI connection:
+
    ```bash
    rai init
    ```
 
-5. Run:
+5. Run the template end-to-end:
+
    ```bash
    python ad_spend_allocation.py
    ```
 
-6. Expected output:
+6. Expected output. A per-scenario allocation table confirms a successful run (trimmed to the first budget level here; the full run also prints the $45K and $55K scenarios):
+
    ```text
    Spend allocation per scenario:
        scenario channel         campaign    spend
@@ -97,102 +107,107 @@ The template includes scenario analysis that sweeps over three total budget leve
      budget_35k  Search    Seasonal_Sale   8000.0
      budget_35k  Social  Brand_Awareness   3000.0
      budget_35k   Video   Product_Launch  10000.0
-     budget_45k   Email  Brand_Awareness   2000.0
-     budget_45k   Email    Seasonal_Sale   2000.0
-     budget_45k  Search  Brand_Awareness   5000.0
-     budget_45k  Search   Product_Launch  10000.0
-     budget_45k  Search    Seasonal_Sale   8000.0
-     budget_45k  Social  Brand_Awareness   8000.0
-     budget_45k   Video   Product_Launch  10000.0
-     budget_55k   Email  Brand_Awareness   2000.0
-     budget_55k   Email    Seasonal_Sale   2000.0
-     budget_55k  Search  Brand_Awareness   5000.0
-     budget_55k  Search   Product_Launch  10000.0
-     budget_55k  Search    Seasonal_Sale   8000.0
-     budget_55k  Social  Brand_Awareness   8000.0
-     budget_55k   Video   Product_Launch  10000.0
    ```
 
-   All three budgets invest heavily in Search and Video (highest ROI channels).
-   The $35K budget activates 6 channel-campaign pairs. The $45K and $55K
-   budgets add Search Brand_Awareness ($5K) and increase Social Brand_Awareness
-   to $8K -- diminishing returns mean the extra $10K from $45K to $55K produces
-   no new activations.
+   All three budgets invest heavily in Search and Video (highest ROI channels). The $35K budget activates 6 channel-campaign pairs. The $45K and $55K budgets add Search Brand_Awareness ($5K) and increase Social Brand_Awareness to $8K — diminishing returns mean the extra $10K from $45K to $55K produces no new activations. See `runbook.md` for the full printout and a step-by-step walkthrough.
 
 ## Template structure
+
+The tree below shows the top-level layout:
+
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── ad_spend_allocation.py
-└── data/
-    ├── channels.csv
-    ├── campaigns.csv
-    └── effectiveness.csv
+ad_spend_allocation/
+├── ad_spend_allocation.py   # Main script (ontology, formulation, single-solve scenario sweep)
+├── data/
+│   ├── channels.csv         # 5 channels with min/max spend and ROI coefficient
+│   ├── campaigns.csv        # 3 campaigns with budget and target conversions
+│   └── effectiveness.csv    # 15 channel-campaign conversion rates
+├── README.md                # this file
+├── runbook.md               # analyst-facing paste-testable walkthrough
+└── pyproject.toml           # dependencies
 ```
 
+**Start here**: run `python ad_spend_allocation.py` for the full run end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
+
+## Sample data
+
+The bundled data is synthetic and illustrative — designed to teach the optimization flow, not to match a specific advertiser's account.
+
+- **`channels.csv`** (5 rows) — the marketing channels (Search, Social, Display, Video, Email), each with a minimum and maximum spend and an ROI coefficient.
+- **`campaigns.csv`** (3 rows) — the campaigns (Brand_Awareness, Product_Launch, Seasonal_Sale), each with a budget and a target-conversions figure.
+- **`effectiveness.csv`** (15 rows) — one row per channel-campaign pair, giving the conversion rate (conversions per dollar spent) for that pair.
+
+The three budget levels ($35K, $45K, $55K) that drive the scenario sweep are defined in the script, not in a CSV.
+
+## Model overview
+
+One ontology holds the inputs and the decision variables. The three source CSVs load into `Channel`, `Campaign`, and `Effectiveness`; `Scenario` carries the budget levels; and `Allocation` holds the per-pair decision variables the solver sets.
+
+- **Key entities**: `Channel` — a marketing channel with spend bounds and an ROI coefficient; `Campaign` — a campaign with a budget and a conversion target; `Effectiveness` — the conversion rate for one channel-campaign pair (also the link between a channel and a campaign); `Scenario` — a budget level in the what-if sweep; and the decision concept `Allocation` — one per channel-campaign pair, holding the spend and funding variables the solver sets (indexed by `Scenario`, so a single solve covers all budget levels).
+- **Primary identifiers**: integer `id` on `Channel` and `Campaign`; a composite `channel_id` + `campaign_id` on `Effectiveness`; a string `name` on `Scenario`; and the linked `Effectiveness` on `Allocation`.
+- **Important invariants**: spend is non-negative; `x_active` is binary (0/1); spend on a pair sits within its channel's min/max only when the pair is active; per-campaign spend stays within the campaign budget; every campaign has at least one funded channel; and total spend stays within the scenario's total budget.
+
+For the full concept and property definitions, see `ad_spend_allocation.py`; `runbook.md` builds them step by step with the RAI skills.
+
 ## How it works
 
-**1. Define the ontology.** Channels, campaigns, and their effectiveness (conversion rates) are modeled as concepts:
+The script loads the CSVs into concepts, defines the decision variables, adds the constraints and objective, and solves all budget levels in one call.
 
-```python
-Channel = Concept("Channel", identify_by={"id": Integer})
-Channel.min_spend = Property(f"{Channel} has {Float:min_spend}")
-Channel.max_spend = Property(f"{Channel} has {Float:max_spend}")
+1. **Define the ontology.** Channels, campaigns, and their per-pair effectiveness (conversion rates) load into concepts, with the effectiveness rows linking each channel to each campaign.
 
-Campaign = Concept("Campaign", identify_by={"id": Integer})
-Campaign.budget = Property(f"{Campaign} has {Float:budget}")
+2. **Model budget levels as a concept.** `Scenario` carries the three total-budget levels, so the what-if sweep is data rather than a Python loop.
 
-Effectiveness = Concept("Effectiveness", identify_by={"channel_id": Integer, "campaign_id": Integer})
-Effectiveness.conversion_rate = Property(f"{Effectiveness} has {Float:conversion_rate}")
-```
+3. **Define decision variables.** For each channel-campaign pair the solver sets a continuous spend amount and a binary activation indicator, both indexed by scenario so one solve covers every budget level.
+
+4. **Add constraints.** Spend must fall within a channel's min/max only when its pair is active, per-campaign spend stays within the campaign budget, every campaign keeps at least one active channel, and total spend stays within the scenario's total budget — each scoped per scenario.
 
-**2. Define decision variables.** Continuous spend amounts and binary activation indicators per channel-campaign pair:
+5. **Maximize conversions.** The objective sums spend times conversion rate across all allocations, so the solver funds the highest-return pairs first.
 
-```python
-Allocation = Concept("Allocation", identify_by={"effectiveness": Effectiveness})
-Allocation.x_spend = Property(f"{Allocation} has {Float:spend}")
-Allocation.x_active = Property(f"{Allocation} is {Float:active}")
+6. **Solve once for all scenarios.** A single HiGHS solve covers all three budget levels; results are extracted per scenario and printed as a table.
 
-problem.solve_for(Allocation.x_spend, name=[...], lower=0)
-problem.solve_for(Allocation.x_active, type="bin", name=[...])
+See `ad_spend_allocation.py` for the implementation and `runbook.md` for the skill-driven reproduction. The end-to-end flow:
+
+```text
+CSV inputs → load into concepts → decision variables (spend + funding, per scenario)
+   → constraints + objective → single HiGHS solve → per-scenario allocation table
 ```
 
-**3. Add constraints.** Minimum/maximum spend when active, per-campaign budget limits, at least one active channel per campaign, and a global budget cap:
+## Customize this template
 
-```python
-problem.satisfy(model.require(Allocation.x_spend >= Allocation.effectiveness.channel.min_spend * Allocation.x_active))
-problem.satisfy(model.require(Allocation.x_spend <= Allocation.effectiveness.channel.max_spend * Allocation.x_active))
+Focus on the first changes most users will make.
 
-campaign_spend = sum(Allocation.x_spend).where(Allocation.effectiveness.campaign == Campaign).per(Campaign)
-problem.satisfy(model.require(campaign_spend <= Campaign.budget))
-problem.satisfy(model.require(sum(Allocation.x_spend) <= total_budget))
-```
+### Use your own data
 
-**4. Maximize conversions.** The objective sums spend times conversion rate across all active allocations:
+- Replace the CSVs in `data/` with your own; keep the column names listed in *Sample data* above (`channels.csv`: `id`, `name`, `min_spend`, `max_spend`, `roi_coefficient`; `campaigns.csv`: `id`, `name`, `budget`, `target_conversions`; `effectiveness.csv`: `channel_id`, `campaign_id`, `conversion_rate`).
+- Add or remove channels by editing `channels.csv` with new spend bounds and ROI coefficients; add campaigns by extending `campaigns.csv` and adding the corresponding rows in `effectiveness.csv`.
+- Change the conversion rates in `effectiveness.csv` to reflect your own channel-campaign performance data. Rates are conversions per dollar (a rate of 0.10 means 0.10 conversions per dollar), so keep min/max spend bounds and campaign budgets in the same currency units.
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)` calls.
 
-```python
-total_conversions = sum(Allocation.x_spend * Allocation.effectiveness.conversion_rate)
-problem.maximize(total_conversions)
-```
+### Tune parameters
 
-**5. Run scenarios.** The loop iterates over budget levels, building a fresh Problem for each and comparing results.
+- **Budget levels** — the three scenarios (`budget_35k`, `budget_45k`, `budget_55k`) are defined in the `scenario_data` block near the top of the script. Add, remove, or change levels there to sweep a different range.
+- **Spend bounds and budgets** — per-channel `min_spend` / `max_spend` live in `channels.csv`; per-campaign `budget` lives in `campaigns.csv`. These are usually the binding limits, so they are the first knobs to adjust when the total-budget cap stops mattering.
+- **Solver settings** — the solve uses HiGHS with a 60-second time limit (`problem.solve("highs", time_limit_sec=60)`); adjust the limit for larger instances.
 
-## Customize this template
+### Extend the model
 
-- **Add or modify channels** by editing `channels.csv` with new spend bounds and ROI coefficients.
-- **Add campaigns** by extending `campaigns.csv` and adding corresponding rows in `effectiveness.csv`.
-- **Change conversion rates** to reflect your own channel-campaign performance data.
-- **Add diminishing returns** by introducing piecewise linear or concave conversion functions.
-- **Add channel-level constraints** such as maximum total spend per channel across all campaigns.
+- **Add diminishing returns** by introducing piecewise-linear or concave conversion functions in place of the flat per-dollar rate.
+- **Add channel-level constraints** such as a maximum total spend per channel across all campaigns.
 - **Add temporal dimensions** to model multi-period budget allocation with carry-over effects.
+- **Add a coverage floor** such as a minimum spend or minimum conversion target per campaign.
+
+### Scale up / productionize
+
+- Replace the `data/` CSV bundle with data loaded directly from Snowflake tables via `model.data(...)`.
+- Pin the `relationalai` SDK version (see *Prerequisites*) so runs are reproducible; the single-solve `Scenario` design keeps the whole sweep deterministic within a solve.
+- Schedule the run as part of a planning pipeline and read the written-back `Allocation.x_spend` / `Allocation.x_active` properties from the ontology for downstream reporting.
 
 ## Troubleshooting
 
 <details>
   <summary>Solver returns INFEASIBLE</summary>
 
-- Check that `total_budget` is large enough to satisfy the minimum-spend requirements for at least one channel per campaign.
+- Check that each scenario's total budget is large enough to satisfy the minimum-spend requirements for at least one channel per campaign.
 - Verify that per-campaign budgets in `campaigns.csv` are consistent with channel minimum spends.
 - Ensure every campaign has at least one channel in `effectiveness.csv`.
 
@@ -209,7 +224,7 @@ problem.maximize(total_conversions)
 <details>
   <summary>Authentication or configuration errors</summary>
 
-- Run `rai init` to create or update your RelationalAI/Snowflake configuration.
+- Run `rai init` to create or update your RelationalAI / Snowflake configuration.
 - If you have multiple profiles, set `export RAI_PROFILE=<your_profile>`.
 
 </details>
@@ -222,3 +237,21 @@ problem.maximize(total_conversions)
 - Check that channel min/max spend bounds are in the same units as campaign budgets.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)`, `model.select(...)`, and aggregation used to build and read the model.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives used in this template.
+
+### CLI / SDK guides
+
+- [RelationalAI setup and configuration](https://docs.relational.ai/) — installing the SDK and running `rai init`.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/bom-reachability/README.md b/v1/bom-reachability/README.md
index e5990253..68f1faa2 100644
--- a/v1/bom-reachability/README.md
+++ b/v1/bom-reachability/README.md
@@ -18,10 +18,9 @@ sidebar:
 
 ## What this template is for
 
-A bill of materials (BOM) defines how finished products are built from components and raw materials through multiple assembly stages. Understanding the full transitive dependency tree -- not just direct inputs -- is critical for supply chain risk management. This template demonstrates two graph analysis techniques on a BOM structure:
+A bill of materials (BOM) defines how finished products are built from components and raw materials through multiple assembly stages. When a supplier slips, a plant goes down, or a part is recalled, the pressing question is not "what does this product use directly?" but "which finished goods ultimately depend on this part, and how far up the chain does the damage travel?" Direct inputs are easy to read off a spreadsheet; the full transitive dependency tree — and the shared components that quietly sit on everyone's critical path — are not.
 
-1. **Reachability** (`reachable(full=True)`) -- Trace all transitive dependencies to answer "What does Product X ultimately depend on?" across multiple assembly tiers.
-2. **Betweenness Centrality** -- Identify structural bottleneck components that sit on the most dependency paths between finished goods and raw materials.
+This template turns a BOM into a dependency graph so you can trace those transitive dependencies, pinpoint the components that are structural bottlenecks across product lines, and enumerate the end-to-end assembly chains that build each finished good. **It runs on RelationalAI's graph reasoner, using reachability, betweenness centrality, and path enumeration directly over the ontology.**
 
 ## Who this is for
 
@@ -32,20 +31,21 @@ A bill of materials (BOM) defines how finished products are built from component
 
 ## What you'll build
 
-- Load a 9-SKU, 14-BOM-entry product structure from CSV (consumer electronics: smartphones, tablets, components, raw materials)
-- Construct a directed dependency graph where edges point from output SKU to input SKU ("depends on")
-- Compute all-pairs reachability to map full transitive dependency trees
-- List dependencies per finished good, broken down by type (COMPONENT vs RAW_MATERIAL)
-- Rank components by how many other SKUs depend on them
-- Compute betweenness centrality to identify structural bottlenecks
-- Enumerate the end-to-end assembly chains that build each finished good and persist each one's assembly depth
+- A directed dependency graph over the BOM (SKU nodes, output-to-input "depends on" edges) built with the graph reasoner's `Graph` construction.
+- A full transitive dependency tree per finished good, broken down by type (component vs raw material), from all-pairs `reachable(full=True)`.
+- A most-depended-on ranking of SKUs and a betweenness-centrality ranking that flags the structural bottleneck components.
+- An enumeration of the end-to-end assembly chains that build each finished good, reduced to the maximal (non-extendable) chains via path enumeration.
+- An `assembly_depth` property persisted back onto each SKU, so the longest chain terminating at each finished good is queryable as ontology after the run.
 
 Built on RelationalAI's graph reasoner: **reachability** for transitive dependencies, **betweenness centrality** for bottlenecks, and **path enumeration** for assembly chains.
 
 ## What's included
 
-- **Self-contained script**: `bom_reachability.py` -- Runs the full analysis end-to-end
-- **Data**: `data/skus.csv` (9 SKUs across 3 tiers) and `data/bill_of_materials.csv` (14 BOM entries with site-specific assembly)
+- **Model**: two concepts (`SKU` and `BillOfMaterials`) wired into a directed dependency graph, plus a derived `feeds` self-relationship on `SKU` and a persisted `assembly_depth` property.
+- **Runner**: `bom_reachability.py` — a single self-contained Python script that runs reachability, betweenness centrality, and assembly-path enumeration end to end.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: `data/skus.csv` (9 SKUs across 3 tiers) and `data/bill_of_materials.csv` (14 BOM entries with site-specific assembly). See *Sample data* below.
+- **Outputs**: printed transitive-dependency lists per finished good, a most-depended-on and betweenness ranking, the maximal assembly chains, and an `assembly_depth` property written back onto the SKU ontology.
 
 ## Prerequisites
 
@@ -125,13 +125,13 @@ Built on RelationalAI's graph reasoner: **reachability** for transitive dependen
     └── bill_of_materials.csv    # 14 site-specific BOM entries (output SKU requires input SKU)
 ```
 
-**Start here**: run `python bom_reachability.py` for the full analysis end to end (reachability, betweenness centrality, and assembly-path enumeration), or follow `runbook.md` to rebuild it step by step with a coding agent.
+**Start here**: run `python bom_reachability.py` for the full analysis end to end (reachability, betweenness centrality, and assembly-path enumeration), or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Sample data
 
 `data/skus.csv` holds 9 SKUs spanning the three assembly tiers: 4 `RAW_MATERIAL` (silicon wafer, display glass, lithium-ion cells, NAND flash), 3 `COMPONENT` (mobile processor, OLED display, battery pack), and 2 `FINISHED_GOOD` (a smartphone and a tablet). Each row carries an `ID`, `NAME`, `TYPE`, `CATEGORY`, `UNIT_OF_MEASURE`, `LEAD_TIME_DAYS`, `UNIT_COST`, and `UNIT_PRICE`; the graph analysis uses `ID`, `NAME`, `TYPE`, and `CATEGORY`.
 
-`data/bill_of_materials.csv` holds 14 BOM entries, each linking an `OUTPUT_SKU_ID` (what is produced) to an `INPUT_SKU_ID` (what it requires), with `ID`, `SITE_ID`, and `INPUT_QUANTITY`. The same output-to-input pair is recorded once per `SITE_ID`, so multi-site assemblies appear as duplicate edges (for example, `SKU001` is assembled at both `S001` and `S012`). The graph deduplicates these automatically -- see the multi-edges note under Troubleshooting.
+`data/bill_of_materials.csv` holds 14 BOM entries, each linking an `OUTPUT_SKU_ID` (what is produced) to an `INPUT_SKU_ID` (what it requires), with `ID`, `SITE_ID`, and `INPUT_QUANTITY`. The same output-to-input pair is recorded once per `SITE_ID`, so multi-site assemblies appear as duplicate edges (for example, `SKU001` is assembled at both `S001` and `S012`). The graph deduplicates these automatically — see the multi-edges note under Troubleshooting.
 
 ## Model overview
 
@@ -139,107 +139,39 @@ Built on RelationalAI's graph reasoner: **reachability** for transitive dependen
 - **Primary identifiers**: `SKU` by `id`; `BillOfMaterials` by `id`.
 - **Important invariants**: each `BillOfMaterials` row points an output SKU at one input SKU ("depends on"); the BOM is acyclic (raw materials feed components feed finished goods, never back).
 
-### `SKU`
+The model also derives a `feeds` self-relationship on `SKU` (input SKU feeds output SKU), built from the `BillOfMaterials` intermediary and used to enumerate assembly paths, plus a persisted `assembly_depth` property (the longest assembly chain terminating at each SKU).
 
-One stock-keeping unit at any assembly tier (raw material, component, or finished good).
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | string | Yes | Loaded from `data/skus.csv` (`ID`) |
-| `name` | string | No | Human-readable name (`NAME`) |
-| `type` | string | No | `RAW_MATERIAL`, `COMPONENT`, or `FINISHED_GOOD` (`TYPE`) |
-| `category` | string | No | Used for grouping/filters (`CATEGORY`) |
-| `assembly_depth` | int | No | Derived and persisted: longest assembly chain terminating at this SKU (PREVIEW stage) |
-
-The model also derives a `feeds` self-relationship on `SKU` (`SKU feeds into SKU`): a binary input-feeds-output edge built from the `BillOfMaterials` intermediary and used to enumerate assembly paths.
-
-### `BillOfMaterials`
-
-One link in the bill of materials, recorded per assembly site and used as the graph's edge concept.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | string | Yes | Loaded from `data/bill_of_materials.csv` (`ID`) |
-
-| Relationship | Schema | Notes |
-|---|---|---|
-| `output_sku` | `BillOfMaterials produces SKU` | The SKU this entry produces; graph edge source |
-| `input_sku` | `BillOfMaterials requires SKU` | The SKU this entry requires; graph edge destination |
+For the full concept and property definitions, see `bom_reachability.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
-```text
-CSV files --> Define SKU + BOM concepts --> Build directed graph --> Reachability analysis --> Betweenness centrality --> Display results
-```
-
-### 1. Load Ontology
-
-SKU and BillOfMaterials concepts are loaded from CSV. Each BOM entry links an output SKU (what is produced) to an input SKU (what is required):
+The pipeline loads the ontology, builds a directed graph, then runs three graph analyses over it:
 
-```python
-SKU = model.Concept("SKU", identify_by={"id": String})
-BillOfMaterials = model.Concept("BillOfMaterials", identify_by={"id": String})
-BillOfMaterials.output_sku = model.Relationship(f"{BillOfMaterials} produces {SKU}")
-BillOfMaterials.input_sku = model.Relationship(f"{BillOfMaterials} requires {SKU}")
+```text
+CSV files --> Define SKU + BOM concepts --> Build directed graph --> Reachability analysis --> Betweenness centrality --> Assembly-path enumeration --> Display results
 ```
 
-### 2. Build Directed Graph
+### 1. Load ontology
 
-The graph uses BillOfMaterials as the edge concept, with edges pointing from output to input ("depends on"):
+The `SKU` and `BillOfMaterials` concepts load from CSV. Each BOM entry links an output SKU (what is produced) to an input SKU (what is required), which becomes the directed "depends on" edge.
 
-```python
-graph = Graph(
-    model, directed=True, weighted=False,
-    node_concept=SKU,
-    edge_concept=BillOfMaterials,
-    edge_src_relationship=BillOfMaterials.output_sku,
-    edge_dst_relationship=BillOfMaterials.input_sku,
-)
-```
+### 2. Build directed graph
 
-### 3. Trace Dependencies
+The graph uses `BillOfMaterials` as the edge concept, with edges pointing from output SKU to input SKU — so following an edge means following a dependency.
 
-`reachable(full=True)` computes all-pairs reachability -- every (source, destination) pair where a directed path exists:
+### 3. Trace dependencies
 
-```python
-reachable = graph.reachable(full=True)
+All-pairs reachability computes every source-and-destination pair where a directed path exists, giving the full transitive dependency tree behind each finished good rather than just its direct inputs.
 
-src, dst = graph.Node.ref("src"), graph.Node.ref("dst")
-all_deps_df = where(reachable(src, dst)).select(
-    src.id.alias("product_id"),
-    dst.id.alias("dep_id"),
-    ...
-).to_df()
-```
+### 4. Identify bottlenecks
 
-### 4. Identify Bottlenecks
+Betweenness centrality ranks components by how many shortest dependency paths pass through them. Components with high betweenness are structural bottlenecks — disrupting them affects the most product lines.
 
-Betweenness centrality ranks components by how many shortest dependency paths pass through them:
+### 5. Enumerate assembly paths (PREVIEW, requires `relationalai>=1.15`)
 
-```python
-betweenness = graph.betweenness_centrality()
-```
+Where reachability returns dependency *pairs*, path enumeration returns the actual *build sequences*. It walks the derived `feeds` edge to enumerate every assembly path; because the BOM is acyclic, this yields exactly the simple paths with no cycle risk. A maximal-paths view keeps only the longest non-extendable chains, and the longest assembly depth is persisted as `SKU.assembly_depth`.
 
-Components with high betweenness are structural bottlenecks -- disrupting them affects the most product lines.
-
-### 5. Enumerate Assembly Paths (PREVIEW, requires `relationalai>=1.15`)
-
-Where reachability returns dependency *pairs*, path enumeration returns the actual *build sequences*. It derives a SKU-to-SKU `feeds` edge from the `BillOfMaterials` intermediary (input SKU feeds output SKU) and enumerates every assembly path; because the BOM is acyclic, `.all_paths()` yields exactly the simple paths -- no cycle risk. A maximal-paths view keeps only the longest non-extendable chains, and the longest assembly depth is persisted as `SKU.assembly_depth`.
-
-```python
-SKU.feeds = model.Relationship(f"{SKU} feeds into {SKU}", short_name="feeds")
-p = model.path(SKU.feeds.repeat(1, MAX_ASSEMBLY_HOPS)).all_paths()
-assembly_df = (
-    model.where(p)
-    .select(
-        p.alias("path"),
-        p.nodes["index"].alias("step"),
-        SKU(p.nodes).id.alias("sku_id"),
-        SKU(p.nodes).name.alias("sku_name"),
-    )
-    .to_df()
-)
-```
+See `bom_reachability.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
 ## Customize this template
 
@@ -271,23 +203,33 @@ Focus on the first changes most users will make.
 <details>
   <summary>Why do I see a "multi-edges" warning?</summary>
 
-- The BOM data includes site-specific entries (e.g., SKU001 is assembled at both S001 and S012). This creates duplicate edges between the same SKU pair. The warning is informational -- the graph deduplicates automatically. To suppress it, add `aggregator="sum"` to the Graph constructor.
+- The BOM data includes site-specific entries (e.g., SKU001 is assembled at both S001 and S012). This creates duplicate edges between the same SKU pair. The warning is informational — the graph deduplicates automatically. To suppress it, add `aggregator="sum"` to the Graph constructor.
 
 </details>
 
 <details>
   <summary>Why does authentication/configuration fail?</summary>
 
-- Run `rai init` to create/update `raiconfig.toml`.
+- Run `rai init` to create/update `raiconfig.yaml`.
 - If you have multiple profiles, set `RAI_PROFILE` or switch profiles in your config.
 
 </details>
 
 ## Learn more
 
+### Core concepts
+
 - [RelationalAI documentation](https://docs.relational.ai/) — language, modeling, and reasoner reference.
+
+### Reasoner reference
+
+- [Graph reasoner](https://docs.relational.ai/) — node-concept and edge-concept graph construction, reachability, betweenness centrality, and path enumeration.
+
+### More templates
+
 - [Template gallery](https://docs.relational.ai/build/templates) — other runnable templates, including graph, rules, and prescriptive examples.
 
 ## Support
 
 - Questions or issues: [support.relational.ai](https://support.relational.ai).
+- File issues at the RelationalAI templates repository.
diff --git a/v1/book_slate_recommendation/README.md b/v1/book_slate_recommendation/README.md
index 28520c26..df895340 100644
--- a/v1/book_slate_recommendation/README.md
+++ b/v1/book_slate_recommendation/README.md
@@ -1,8 +1,8 @@
 ---
 title: "Book Slate Recommendation"
-description: "Recommend K books per reader and order them by slot, under diversity, freshness, and explainability constraints."
+description: "Recommend a ranked slate of books for each reader that balances relevance, diversity, and freshness. Produces an ordered, explainable set of picks per reader."
 featured: false
-private: true
+private: false
 experience_level: advanced
 industry: "Retail & Consumer"
 reasoning_types:
@@ -11,155 +11,95 @@ reasoning_types:
 tags:
   - Multi-Reasoner
   - Recommendation
-  - Slate
-  - constraint-programming
+  - Slate Optimization
+  - Constraint Programming
   - Explainability
-  - KG-Paths
+  - Knowledge-Graph Paths
 ---
 
-# Book Slate Recommendation
-
 ## What this template is for
 
-Every consumer-facing platform with a "row of K things" surface --
-streaming homepages, e-commerce cross-sell carousels, news feeds,
-learning-platform course slates -- has the same problem: pick K items
-per user that are *individually* relevant, *collectively* diverse,
-and *explainable* enough to meet platform business rules.
-
-This template solves that problem in one declarative model:
-
-- **Bounded KG walks via the paths library (architectural
-  centerpiece)** — `Item.connected_to.repeat(1, 2).all_paths()`
-  combined with direct shared-author / shared-subject joins
-  produces the Candidate concept and its per-`(user, candidate)`
-  typed-evidence counts. The paths library lives in PyRel `std`,
-  not a separate reasoner.
-- **Graph reasoner (hero pin)** computes per-Book triangle counts
-  over the similarity graph and pins slot 1 (the top-of-row
-  position with the most engagement) to a Book whose triangle count
-  clears `HERO_EMBEDDEDNESS_THRESHOLD`. Distinct from a per-book
-  popularity scalar: it depends on the graph topology, not on a
-  value that can be substituted from retrieval. Tying the metric to
-  the hero slot (rather than a "somewhere in the slate" floor)
-  concentrates the Graph contribution at the highest-impression
-  position.
-- **Prescriptive reasoner (CSP, MiniZinc)** decides each Candidate's slot in
-  `{1, 2, ..., K, K+1}` -- slot 1..K are slate positions (1 = hero),
-  slot K+1 is the unpicked sentinel. Constraints: cardinality, slot
-  uniqueness, already-read exclusion, author uniqueness, subject-
-  concentration cap, freshness, originals-exposure, cold-start, hero
-  pin, and explanation-path floor. Objective maximizes
-  `sum((K+1-slot) * path_count_total)` -- the canonical position-
-  decay engagement model. Pure-integer model -- multi-valued integer
-  decisions, integer coefficients, no float blend; lowers cleanly to
-  MiniZinc's CSP / CP-SAT propagators (in particular the GCC-style
-  per-pair cardinality constraints used for slot, author, and
-  subject uniqueness).
-
-The same shape ports to e-commerce ("frequently bought together"
-with category coverage), course slates (career-navigation over a
-skills graph with prerequisite respect), and news feed optimization
-under topic / source / recency caps.
+Every consumer-facing platform with a "row of K things" surface — a streaming homepage, an e-commerce cross-sell carousel, a news feed, a learning-platform course slate — faces the same decision: pick K items per user that are individually relevant, collectively diverse, and explainable enough to satisfy the platform's business rules. Getting the composition right at the top-of-row (hero) position matters most, because that is where engagement concentrates. Doing this by post-processing a ranked list rarely respects the diversity, freshness, and exposure floors that editorial, curation, and compliance teams need on every slate.
+
+This template composes the slate as a single optimization decision rather than a filtering pass, so relevance, diversity, freshness, exposure, and explainability are all enforced jointly. **It chains RelationalAI's reasoners — knowledge-graph path walks and graph analytics feeding a constraint-programming optimizer — through one shared ontology, so every recommended item carries a decomposable, graph-grounded explanation without leaving the model.**
 
 ## Who this is for
 
-- Recsys engineers building constrained slate-composition stages
-- Editorial and curation teams who need diversity / freshness /
-  exposure floors enforced on every slate
-- Compliance and transparency teams who want KG-grounded,
-  decomposable explanations for every recommended item
-- Operations researchers exploring multi-reasoner pipelines (Graph
-  analytics → KG paths → prescriptive optimization) on RelationalAI
+- Recommender-systems engineers building the constrained slate-composition stage of a ranking funnel.
+- Editorial and curation teams who need diversity, freshness, and exposure floors enforced on every slate.
+- Compliance and transparency teams who want knowledge-graph-grounded, decomposable explanations for each recommended item.
+- Operations researchers exploring multi-reasoner pipelines on RelationalAI.
+- **Assumed knowledge**: comfortable reading Python; the recommender-systems, graph, and optimization terms are explained as they come up. As an advanced multi-reasoner template it goes faster if you have followed a single-reasoner template first, but no deep RelationalAI experience is required to run it.
 
 ## What you'll build
 
-- A heterogeneous knowledge graph over `User`, `Book`, `Author`,
-  `Subject` with typed edges (`read`, `written_by`, `about`,
-  `similar_to`)
-- A unified `Item.connected_to` super-edge used by the path walker
-- A `Candidate` concept generated by bounded `Item.connected_to`
-  walks of depth ≤ 2 -- candidates are *defined* by paths
-- Per-`(user, candidate)` typed-evidence counts:
-  `path_count_via_author`, `path_count_via_subject`,
-  `path_count_via_kg_walk`, summed into `path_count_total`
-- `Book.triangle_count` derived from
-  `Graph(Book.similar_to).triangle_count()` -- a structural-
-  embeddedness measure used by the hero-pin IC
-- An integer-decision CSP on MiniZinc with ten ICs (cardinality, slot
-  uniqueness, already-read exclusion, author uniqueness, subject-
-  concentration cap, freshness floor, originals-exposure floor,
-  cold-start cap, hero pin, explanation-path floor) and a position-
-  weighted engagement-decay objective `sum((K+1-slot) *
-  path_count_total)`
-- Customer-readable result tables: chosen slate (ordered by slot),
-  per-user subject distribution, per-pick explanation-path support
+- A heterogeneous knowledge graph over `User`, `Book`, `Author`, and `Subject` with typed edges (`read`, `written_by`, `about`, `similar_to`), plus a unified `Item.connected_to` super-edge the path walker traverses.
+- A `Candidate` concept generated by bounded knowledge-graph walks (the PyRel paths library), with per-`(user, candidate)` typed-evidence counts (`path_count_via_author`, `path_count_via_subject`, `path_count_via_kg_walk`, summed into `path_count_total`).
+- A `Book.triangle_count` structural-embeddedness measure from **graph analysis** over the similarity graph, used to pin the hero slot to a structurally central book.
+- A **prescriptive** constraint-programming model on MiniZinc that assigns each candidate a slot and enforces ten rules (cardinality, slot uniqueness, already-read exclusion, author uniqueness, subject-concentration cap, freshness floor, originals-exposure floor, cold-start cap, hero pin, explanation-path floor) under a position-weighted engagement-decay objective.
+- Customer-readable result tables: the chosen slate ordered by slot, the per-user subject distribution, and per-pick explanation-path support.
 
 ## What's included
 
-- `book_slate_recommendation.py` -- main script with the full
-  paths-walk + Graph + Prescriptive pipeline
-- `data/fetch_open_library_slice.py` -- Open Library (CC0) slice
-  fetcher with caching under `data/_cache/`; supports
-  `--size sm|md|lg`
-- `data/*.csv` -- bundled `sm` slice (~59 books, ~52 authors,
-  12 subjects, 25 synthetic users with read events)
-- `pyproject.toml` -- Python package configuration
+- **Model**: a three-stage pipeline (knowledge-graph path walks, then graph analysis, then prescriptive optimization) on a single shared ontology, wired to the bundled CSVs.
+- **Runner**: `book_slate_recommendation.py` — a single Python script that runs end-to-end against a Snowflake-connected RAI account.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: a deterministic Open Library (CC0 public domain) slice of roughly 59 books, 52 authors, and 12 subjects, with synthetic users and read events layered on top. See *Sample data* below.
+- **Outputs**: the formulation, the solve-result block, the chosen slate (with per-book `path_count_total` and `triangle_count`), the per-user subject distribution, per-pick explanation-path support, and diagnostic candidate-set and structural-embeddedness tables.
 
 ## Prerequisites
 
 ### Access
-- A Snowflake account that has the RAI Native App installed.
-- A Snowflake user with permissions to access the RAI Native App.
+
+- A Snowflake account with the RelationalAI Native App installed.
+- A Snowflake user with permissions to access the RelationalAI Native App.
 
 ### Tools
-- Python >= 3.10
+
+- Python 3.10 or newer.
+- RelationalAI Python SDK (`relationalai == 1.1.0`).
 
 ## Quickstart
 
-1. Download ZIP:
+1. Download the template and extract it:
+
    ```bash
    curl -O https://docs.relational.ai/templates/zips/v1/book_slate_recommendation.zip
    unzip book_slate_recommendation.zip
    cd book_slate_recommendation
    ```
+
    > [!TIP]
    > You can also download the template ZIP using the "Download ZIP" button at the top of this page.
 
-2. Create venv:
+2. Create a virtual environment and activate it:
+
    ```bash
    python -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade pip
    ```
 
-3. Install:
+3. Install dependencies:
+
    ```bash
    python -m pip install .
    ```
 
 4. Configure (prompts for Snowflake account, role, and profile name):
+
    ```bash
    rai init
    ```
 
-5. Run:
+5. Run the template end-to-end:
+
    ```bash
    python book_slate_recommendation.py
    ```
 
-6. Expected output. The bundled `data/` directory carries a
-   deterministic Open Library (CC0) slice (~59 books, ~52 authors,
-   12 subjects); synthetic users and read events are layered on
-   top, and `similar_to` edges are derived from shared-author /
-   shared-subject overlap. The runner prints the formulation, the
-   solve-result block, the chosen slate (with per-book
-   `path_count_total` and `triangle_count`), per-user subject
-   distribution, per-pick explanation-path support, and a verbose
-   diagnostic block (candidate set + structural-embeddedness map)
-   at the end. Solver build strings and exact wall times will vary;
-   `status: OPTIMAL` and the chosen slate are stable for the
-   bundled slice:
+6. Expected output (a few lines confirm a successful run). Solver build strings and exact wall times vary, but `status: OPTIMAL` and the chosen slate are stable for the bundled slice:
+
    ```text
    Solve result:
    • status: OPTIMAL
@@ -173,366 +113,167 @@ under topic / source / recency caps.
          1    2     ...               ...             ...
          1    3     ...               ...             ...
    ...
-
-   Explanation-path support per picked item (ordered by slot):
-   user_id slot book_id paths_via_kg_walk paths_via_author paths_via_subject
-         1    1     ...               ...              ...               ...
-   ...
    ```
 
-   To pull a larger Open Library slice, see "Scaling the bundled
-   data" below.
+   To pull a larger Open Library slice, see *Scale up / productionize* below.
 
 ## Template structure
 
-```
+Short annotated tree of the template folder:
+
+```text
 book_slate_recommendation/
-├── data/
-│   ├── fetch_open_library_slice.py    # CC0 slice fetcher
-│   ├── users.csv
-│   ├── books.csv
-│   ├── authors.csv
-│   ├── subjects.csv
-│   ├── read.csv
-│   ├── book_author.csv
-│   ├── book_subject.csv
-│   └── book_similar.csv
-├── book_slate_recommendation.py
-├── pyproject.toml
-└── README.md
+├── book_slate_recommendation.py     # Main script (paths walk + graph + prescriptive)
+├── runbook.md                       # paste-testable walkthrough (RAI skills)
+├── pyproject.toml                   # dependencies
+├── README.md                        # this file
+└── data/
+    ├── fetch_open_library_slice.py  # CC0 Open Library slice fetcher (--size sm|md|lg)
+    ├── users.csv                    # 25 synthetic readers
+    ├── books.csv                    # ~59 books (title, age_days, in_house flag)
+    ├── authors.csv                  # ~52 authors
+    ├── subjects.csv                 # 12 subjects
+    ├── read.csv                     # 150 read events (user, book, rating)
+    ├── book_author.csv              # book-to-author edges
+    ├── book_subject.csv             # book-to-subject edges
+    └── book_similar.csv             # derived book-to-book similarity edges
 ```
 
-Bibliographic data is sourced from
-[Open Library](https://openlibrary.org/dev/docs/api), released
-under CC0 (public domain). Synthetic users and read events, plus
-the derived `similar_to` edges, are generated deterministically by
-the fetch script.
+**Start here**: run `python book_slate_recommendation.py` for the full three-stage pipeline end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
+
+## Sample data
+
+The bibliographic data is a deterministic slice of [Open Library](https://openlibrary.org/dev/docs/api), released under CC0 (public domain), pulled by `data/fetch_open_library_slice.py`. Synthetic users and read events, plus the derived `similar_to` edges, are generated deterministically by the fetch script, so reruns are reproducible. The bundled `sm` slice carries roughly 59 books, 52 authors, and 12 subjects with 25 users and 150 read events.
+
+- **`users.csv`** (25 rows) — synthetic readers (`id`, `name`).
+- **`books.csv`** (59 rows) — catalog items with `title`, `age_days` (recency), and an `in_house` 0/1 flag (1 = an in-house / originals item, 0 = third party).
+- **`authors.csv`** (52 rows) — book authors (`id`, `name`).
+- **`subjects.csv`** (12 rows) — topical categories (`id`, `name`).
+- **`read.csv`** (150 rows) — read events (`user_id`, `book_id`, `rating`); the user's read history and the already-read exclusion source.
+- **`book_author.csv`** (71 rows) — book-to-author edges.
+- **`book_subject.csv`** (128 rows) — book-to-subject edges.
+- **`book_similar.csv`** (400 rows) — book-to-book similarity edges, derived from shared-author or shared-subject overlap. In production-recommender terms this is the retrieval artifact: swap it for a learned embedding's nearest neighbors, a behavioral co-engagement matrix, or a third-party recommendation API. The model treats it as input; the upstream choice is independent of the slate-stage logic.
+
+## Model overview
+
+One shared ontology threads all three stages. The path-walk stage derives candidates and their evidence, the graph stage adds a structural measure, and the prescriptive stage reads both to compose the slate.
+
+- **Key entities**: `User` — a reader; `Book` — a catalog title (an `Item` sub-concept); `Author` and `Subject` — a book's authors and topics; `Slot` — one of the K ordered recommendation positions in a user's slate; the derived `Candidate` — a (user, unread book) pair scored by its knowledge-graph explanation paths.
+- **Primary identifiers**: integer `id` on `User`, `Book`, `Author`, `Subject`; `pos` on `Slot`; composite `(user_id, book_id)` on `Candidate`.
+- **Important invariants**: `Book.in_house` is a 0/1 flag; `Book.age_days` is non-negative; similarity edges are unique on `(src_book_id, dst_book_id)`; every foreign key resolves; slot decisions take values in `1..K+1`, where slot 1 is the hero position and slot K+1 is the unpicked sentinel.
+
+The typed edges (`read`, `written_by`, `about`, `similar_to`) carry the graph structure; the unified `Item.connected_to` super-edge is their symmetric union, so the path walker can traverse one 2-arity relationship across the heterogeneous graph. Each `Candidate` carries typed evidence counts (`path_count_via_author`, `path_count_via_subject`, `path_count_via_kg_walk`, summed into `path_count_total`) and a `slot` decision.
+
+For the full concept and property definitions, see `book_slate_recommendation.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
-### Schema
-
-- `Item` super-concept; `User`, `Book`, `Author`, `Subject` all
-  `extends=[Item]` so the path walker can chain across the whole
-  heterogeneous KG via a single 2-arity edge.
-- `User(id, name)`
-- `Book(id, title, age_days, in_house)` -- `in_house` is an
-  `Integer` 0/1 flag (1 = an in-house / originals item, 0 = third
-  party).
-- `Author(id, name)`, `Subject(id, name)`
-- Typed edges: `User.read(Book, rating)`,
-  `Book.written_by(Author)`, `Book.about(Subject)`,
-  `Book.similar_to(Book)`.
-- Unified KG edge: `Item.connected_to(Item, Item)` populated as the
-  symmetric union of the typed edges. The unified-edge layer is
-  needed because a `path()` call walks one 2-arity relationship at a
-  time, so the symmetric union of typed edges is pre-materialised
-  onto `Item.connected_to`.
-
-### Pipeline
-
-1. **Bounded KG walks via the paths library + typed evidence joins
-   (architectural centerpiece).** The path walker traverses `Item.connected_to`
-   (the symmetric union of `read | written_by | about | similar_to`)
-   anchored at each `User` up to `MAX_HOPS = 2` hops. With a Book
-   endpoint at length 2, the candidate set is the union of
-   `User -> read_Book` (length 1; pruned by the already-read
-   exclusion) and `User -> read_Book -> similar_Book` (length 2).
-   Author / Subject hubs participate via the `similar_to` edges the
-   data pipeline derives from shared author / subject (see
-   `book_similar.csv`); 3-hop walks
-   (`User -> read_Book -> Author -> candidate_Book`) are not
-   enumerated because the heterogeneous KG saturates fast at that
-   depth and `MAX_HOPS = 2` is the runtime sweet spot. The
-   per-`(user, candidate)` typed-evidence counts
-   (`path_count_via_author`, `_via_subject`) are *direct shared-
-   entity joins* between the candidate and the user's read history
-   rather than walks themselves; `path_count_via_kg_walk` is the
-   actual count of walker-enumerated paths. The composite
-   `path_count_total` feeds the cold-start cap, the explanation
-   floor, and the CSP objective.
-
-   The book-similarity input (`data/book_similar.csv`) is the
-   *retrieval* artifact in production-recsys terms: the data
-   pipeline ships one CC0-derived recipe (shared-author-OR-shared-
-   subject), but customers swap it for any retrieval source -- a
-   learned embedding's k-NN, a behavioral co-engagement matrix, a
-   third-party recommendation API. The model treats it as input
-   data; the upstream choice is independent of the slate-stage
-   logic this template encodes.
-
-2. **Graph: hero-slot pin via triangle count.** A `Graph` is built
-   from `Book.similar_to`; `triangle_count()` returns the per-Book
-   count of similar-to triangles each book participates in, stored
-   as `Book.triangle_count` (Integer). The signal feeds the
-   `hero_pin_ic` IC -- the slot-1 (hero) pick must come from a Book
-   whose triangle count clears `HERO_EMBEDDEDNESS_THRESHOLD`. Tying
-   the metric to the hero slot rather than a "somewhere in the
-   slate" floor concentrates the Graph contribution at the
-   highest-impression position, which is where structural quality
-   matters most for engagement. Triangle count is graph-derived: it
-   depends on the topology of the similarity graph, not on a value
-   the customer can supply externally. That's what makes it an
-   irreducible Graph contribution rather than a swappable per-Book
-   scalar.
-
-3. **Prescriptive: CSP slot assignment.** Decisions:
-   `Candidate.slot in {1, 2, ..., K, K+1}` (`type="int"`, `lower=1`,
-   `upper=K+1`). Slot 1..K are slate positions (1 = hero, K = bottom
-   of row); slot K+1 is the unpicked sentinel. Constraints:
-   - Cardinality: `count(Candidate, slot <= K) per user == K`
-     (exactly K picks).
-   - Slot uniqueness:
-     `count(Candidate, slot == Slot.pos) per (user, Slot) <= 1`
-     (no two picks share a position).
-   - Already-read exclusion: `User.read(user, book) => slot == K+1`.
-   - Author uniqueness: at most 1 picked per `(user, Author)`
-     (per-pair count cap).
-   - Subject-concentration cap: at most `MAX_PER_SUBJECT` picked per
-     `(user, Subject)` (per-pair count cap).
-   - Freshness floor: at least `FRESHNESS_FLOOR` picked items with
-     `age_days <= FRESH_WINDOW_DAYS`.
-   - Originals exposure floor: at least `ORIGINALS_FLOOR` in-house
-     picked items (`Book.in_house == 1`).
-   - Cold-start cap: at most `COLD_START_CAP` weakly-explained
-     picks (those with
-     `path_count_total < WEAK_EXPLANATION_THRESHOLD`).
-   - Hero pin: the slot-1 pick must come from a Book with
-     `triangle_count >= HERO_EMBEDDEDNESS_THRESHOLD`.
-   - Explanation-path floor:
-     `sum((K+1-slot) * path_count_total) per user >=
-     EXPLANATION_FLOOR`. The position weight `(K+1-slot)` is
-     `K..1` at slots `1..K` and `0` at slot `K+1` (unpicked) -- so
-     the sum naturally ignores unpicked Candidates without an
-     auxiliary indicator.
-
-   Objective: maximize `sum((K + 1 - slot) * path_count_total)`.
-   The position weight is the canonical engagement-decay model --
-   higher path-support items gravitate toward slot 1 (top of row,
-   the hero position) because the weight is largest there, which
-   maximizes the weighted sum.
-
-### Why CSP (MiniZinc), not MIP
-
-The model is pure integer with multi-valued integer decision
-variables. MiniZinc's CSP / CP-SAT propagators handle this shape
-natively without LP relaxation overhead, and the per-pair count
-caps used for slot, author, and subject uniqueness map directly
-to MiniZinc's GCC (global cardinality constraint) propagators.
-Slot-equality reification (`slot == 1` inside a count predicate
-for the hero pin) and the conditional domain rule
-(`User.read => slot == K+1`) are also CSP-native. The same
-prescriptive layer would run HiGHS if a future customer layers in
-a float-coefficient scalar (see "Custom scoring signal" in
-Customize) -- the formulation extends without restructure.
-
-### Encoding choices for an ordered slate
-
-This template encodes an *ordered* slate; three choices follow from
-that:
-
-- **Unified `Item.connected_to` super-edge** so the path walker
-  (one 2-arity relationship at a time) can traverse the
-  heterogeneous KG.
-- **Integer slot in `{1..K+1}` with K+1 = unpicked**, so the
-  position weight `(K+1-slot)` is 0 at unpicked and no auxiliary
-  picked-indicator is needed.
-- **Per-pair count caps (GCC idiom)** for slot / author / subject
-  uniqueness, plus a per-user existential count for the hero pin
-  (`count(picked at slot 1 from eligible Books) per user >= 1`).
-  `all_different` would conflict with the shared K+1 sentinel.
-
-### A note on count idioms
-
-PyRel's prescriptive rewriter does *not* currently support distinct
-aggregates in IC compilation (`count(model.distinct(X), ...)`
-raises `NotImplementedError: Distinct aggregates not yet supported`
-when passed to `problem.satisfy`). Distinct counting in ICs is
-therefore expressed indirectly via per-pair count caps: instead of
-`count(distinct Author) per user == K`, we use
-`count(Candidate, slot <= K) per (user, Author) <= 1` (no Author
-repeats) and lean on `slate_size_ic` to fix the pick count. Both
-encode the same constraint; the per-pair cap form is what compiles
-today and is also what MiniZinc consumes most efficiently
-(GCC-style propagation).
-
-## Where this fits in production recsys
-
-Production recommender systems run a multi-stage funnel: *catalog
-(10^6+) -> retrieval (10^3) -> pre-ranking (10^2) -> ranking (float
-utility) -> slate optimization (final K)*. The slate stage is where
-business rules, diversity, exposure floors, and explainability
-constraints land. PyRel's prescriptive reasoner fits this stage
-directly, with the upstream graph and KG-walk signals in the same
-declarative model. The per-typed evidence counts the runner emits
-per picked item (`paths_via_author`, `paths_via_subject`,
-`paths_via_kg_walk`) are a KG-grounded, decomposable justification
-suitable for transparency workflows.
+The pipeline runs in three stages over the shared ontology. Its architectural centerpiece is the bounded knowledge-graph walk: without the paths library there are no candidates and no optimization variables.
+
+**Stage 1 — Knowledge-graph path walks (candidate generation).** The path walker traverses `Item.connected_to` (the symmetric union of `read`, `written_by`, `about`, and `similar_to`) from each user up to `MAX_HOPS = 2` hops. With a `Book` endpoint, the candidate set is the union of length-1 walks (`User -> read_Book`, later excluded because already read) and length-2 walks (`User -> read_Book -> similar_Book`). Each reachable `(user, book)` becomes a `Candidate`. The per-`(user, candidate)` typed counts — shared-author and shared-subject joins against the user's read history, plus the count of walker-enumerated paths — feed the explanation floor, the cold-start cap, and the objective. Each count is defined for every candidate so a candidate with no matches still gets a value, and `path_count_total` sums the three.
+
+**Stage 2 — Graph analysis (hero-slot embeddedness).** A `Graph` is built from `Book.similar_to`, and triangle count returns the per-book count of similarity triangles each book participates in, stored as `Book.triangle_count`. Triangle count is graph-derived: it depends on the topology of the similarity graph, not on a per-book scalar that could be supplied externally. Stage 3 uses it to pin the hero slot to a densely embedded book.
+
+**Stage 3 — Prescriptive constraint program (slot assignment).** Each candidate's slot is a decision in `1..K+1`, where slots `1..K` are slate positions (1 = hero, K = bottom of row) and slot K+1 is the unpicked sentinel. The K+1 encoding lets the position weight `(K + 1 - slot)` be zero for unpicked candidates, so no auxiliary picked/unpicked indicator is needed. The model enforces ten constraints — cardinality (exactly K picks per user), slot uniqueness, already-read exclusion, author uniqueness, subject-concentration cap, freshness floor, originals-exposure floor, cold-start cap, hero pin, and explanation-path floor — under a position-weighted engagement-decay objective. The objective weights each pick by `(K + 1 - slot) * path_count_total`, largest at slot 1, so the solver places the highest-path-support candidates at the top of the row — the canonical position-decay engagement model. After the solve, the runner verifies every constraint, requires an `OPTIMAL` status, and prints the chosen slate, subject distribution, and per-pick explanation support.
+
+See `book_slate_recommendation.py` for the implementation and `runbook.md` for the skill-driven reproduction.
+
+**Where this fits in production.** Production recommender systems run a multi-stage funnel: catalog, then retrieval, then pre-ranking, then ranking, then slate optimization. This template implements the final slate-optimization stage — where business rules, diversity, exposure floors, and explainability constraints land — with the upstream graph and path-walk signals in the same declarative model. The per-typed evidence counts the runner emits for each pick (`paths_via_author`, `paths_via_subject`, `paths_via_kg_walk`) are a decomposable, graph-grounded justification suitable for transparency workflows.
+
+### Why constraint programming (MiniZinc), not mixed-integer programming
+
+The model is pure integer with multi-valued integer decisions. MiniZinc's constraint-programming propagators handle this shape natively without linear-programming relaxation overhead, and the per-pair count caps used for slot, author, and subject uniqueness map directly to MiniZinc's global-cardinality-constraint (GCC) propagators. Slot-equality reification (for the hero pin) and the conditional domain rule (already-read implies slot K+1) are also native to constraint programming. The same prescriptive layer would run on HiGHS if you later add a float-coefficient scalar to the objective (see *Extend the model*), so the formulation extends without restructuring.
 
 ## Customize this template
 
-Six common variations:
-
-- **Tighten or relax the constraint dials.** `MAX_PER_SUBJECT`,
-  `FRESHNESS_FLOOR`, `ORIGINALS_FLOOR`, `COLD_START_CAP`,
-  `EXPLANATION_FLOOR`, `WEAK_EXPLANATION_THRESHOLD`,
-  `HERO_EMBEDDEDNESS_THRESHOLD` are top-of-file constants. See
-  Troubleshooting for joint-feasibility relations between them.
-- **Add a per-Book popularity scalar to the objective.** Layer in
-  a per-book Float (collaborative-filtering co-occurrence, learned-
-  embedding k-NN affinity, third-party recommendation API score) by
-  declaring `Book.cf_score`, populating it from your retrieval
-  stage, and rewriting the objective as
-  `sum((K+1-slot) * (PATH_WEIGHT * path_count_total + CF_WEIGHT * cf_score))`.
-  HiGHS handles the float-coefficient blend natively; the rest of
-  the pipeline (path-derived candidates, hero pin, position-decay
-  weighting) is unchanged. Note that this signal is *additive* to
-  the path evidence -- the structural Graph contribution
-  (`Book.triangle_count`, `hero_pin_ic`) stays in regardless, since
-  it constrains the slate rather than scoring it.
-- **A/B candidate slate enumeration.**
-  `solve("minizinc", solution_limit=K_alt)` returns K alternative
-  slates for downstream A/B exposure or human-in-the-loop
-  curation -- the production-deployed shape for editorial-review
-  platforms (kids content, regulated regions).
-- **LLM-grounded explanation surfacing.** Pipe each picked item's
-  per-typed counts (and, optionally, materialized top-N paths via
-  a small extension of the final `inspect()` selecting on
-  `kg_paths(p_s)`) into an LLM call to render natural-language
-  explanations grounded in KG facts.
-- **Retarget to e-commerce.** Replace `Book` with `Product`,
-  `read` with `purchased`, `similar_to` with co-purchase. The
-  template runs as a "frequently bought together" slate composer
-  with category coverage, brand exclusivity, and price-tier mix.
-- **Retarget to course slates / career paths.** Replace `Book`
-  with `Course`, add prerequisite edges, run a career-navigation
-  pattern with prerequisite respect and credit-hour caps.
-
-### Scaling the bundled data
-
-To pull a larger Open Library slice for a more realistic instance:
-```bash
-python data/fetch_open_library_slice.py --size md   # ~250 books
-python data/fetch_open_library_slice.py --size lg   # ~600 books
-```
-The fetch script is idempotent and caches API responses under
-`data/_cache/`, so reruns are reproducible and offline-friendly
-after the first pull. After bumping size, re-run
-`python book_slate_recommendation.py`. Two things to retune at
-larger sizes: (1) the `EXPLANATION_FLOOR` /
-`WEAK_EXPLANATION_THRESHOLD` constants in the runner are tuned
-for `sm`'s `path_count_total` distribution (range 2-12); larger
-slices produce much higher walk counts and these thresholds
-become trivially satisfied unless rescaled. (2) MiniZinc
-`time_limit_sec=180` is comfortable at `sm` (~1k integer
-decisions, each with K+1=4 values); raise it for `lg` (~120k
-decisions × 10 ICs).
+Focus on the first changes most users will make.
+
+### Use your own data
+
+- Replace the CSVs in `data/` with your own, keeping the column names listed in *Sample data* above.
+- The runner runs pre-solve validation before installing any model rules: it checks for unique keys, no null required columns, resolving foreign keys, non-negative `age_days`, and an `in_house` value in `{0, 1}`. Each failing check raises a focused error naming the offending rows.
+- The `book_similar.csv` similarity edges are the retrieval artifact. Swap the bundled shared-author-or-shared-subject recipe for any retrieval source (learned-embedding nearest neighbors, a behavioral co-engagement matrix, a third-party recommendation API); the rest of the pipeline is unchanged.
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)` calls.
+
+### Tune parameters
+
+The constraint dials are top-of-file constants in `book_slate_recommendation.py`:
+
+- **Slate size** — `SLATE_SIZE_K` (default `3`), the K of "row of K things".
+- **Walk depth** — `MAX_HOPS` (default `2`); bumping to 3 or more saturates fast on a heterogeneous graph.
+- **Diversity and exposure** — `MAX_PER_SUBJECT` (default `2`), `FRESHNESS_FLOOR` (default `1`), `FRESH_WINDOW_DAYS` (default `365 * 30`), `ORIGINALS_FLOOR` (default `1`), `COLD_START_CAP` (default `2`).
+- **Explainability** — `EXPLANATION_FLOOR` (default `8`), `WEAK_EXPLANATION_THRESHOLD` (default `2`), `HERO_EMBEDDEDNESS_THRESHOLD` (default `4`).
+
+See *Troubleshooting* for the joint-feasibility relationships between these dials. The explainability and threshold defaults are tuned to the bundled `sm` slice's `path_count_total` distribution (range 2 to 12); rescale them when you change the data size.
+
+### Extend the model
+
+- **Add a per-book popularity scalar to the objective.** Declare a `Book.cf_score` Float (from collaborative filtering, learned-embedding affinity, or a third-party score), populate it from your retrieval stage, and rewrite the objective as `sum((K+1-slot) * (PATH_WEIGHT * path_count_total + CF_WEIGHT * cf_score))`. HiGHS handles the float-coefficient blend natively; the structural graph contribution (`triangle_count`, hero pin) stays in place because it constrains the slate rather than scoring it.
+- **Enumerate alternative slates.** `solve("minizinc", solution_limit=N)` returns N alternative slates for A/B exposure or human-in-the-loop editorial review.
+- **Surface natural-language explanations.** Pipe each pick's per-typed counts (and, optionally, materialized top-N paths) into a language-model call to render explanations grounded in graph facts.
+- **Retarget to another domain.** Replace `Book` with `Product`, `read` with `purchased`, and `similar_to` with co-purchase for a "frequently bought together" slate with category coverage and brand exclusivity; or replace `Book` with `Course`, add prerequisite edges, and run a career-navigation slate with prerequisite respect.
+
+### Scale up / productionize
+
+- **Pull a larger data slice.** Fetch a bigger Open Library slice for a more realistic instance:
+
+  ```bash
+  python data/fetch_open_library_slice.py --size md   # ~250 books
+  python data/fetch_open_library_slice.py --size lg   # ~600 books
+  ```
+
+  The fetch script is idempotent and caches API responses under `data/_cache/`, so reruns are reproducible and offline after the first pull. After changing size, rerun `python book_slate_recommendation.py`. Two things to retune at larger sizes: the `EXPLANATION_FLOOR` and `WEAK_EXPLANATION_THRESHOLD` constants (larger slices produce much higher walk counts, so these thresholds become trivially satisfied unless rescaled), and the MiniZinc `time_limit_sec` (default `180`, comfortable at `sm`; raise it for `lg`).
+- **Replace CSVs with live data.** Point the loaders at Snowflake tables so the pipeline reads current read history and retrieval edges from your warehouse.
 
 ## Troubleshooting
 
 <details>
-<summary>Solve returns INFEASIBLE / Final slate is empty</summary>
-
-The runner enforces ten ICs and an `OPTIMAL` post-solve
-requirement. If your data is too sparse or too clustered, the
-joint constraints can be jointly infeasible. The dominant causes
-on customer slices are:
-
-1. **Too few candidates after exclude_read.** Each user must have
-   at least `SLATE_SIZE_K` candidates in their 2-hop reach AFTER
-   the already-read exclusion. The exclude prunes aggressively:
-   every length-1 walk `User -> read_Book` lands a read book in
-   `Candidate`, and these are all forced to `slot == K+1`. The
-   recommendable candidates come from length-2
-   `read_Book -> similar_Book` walks, so a user whose reads have
-   no `similar_to` neighbors will be infeasible. Inspect the
-   diagnostic `Candidate set per user` block printed at the end
-   of the runner.
-2. **Disjoint floors.** `FRESHNESS_FLOOR` and `ORIGINALS_FLOOR`
-   are independent. A user with no candidate that is BOTH fresh
-   AND in-house must spend `FRESHNESS_FLOOR + ORIGINALS_FLOOR`
-   distinct picks on the disjoint pools, not
-   `max(FRESHNESS_FLOOR, ORIGINALS_FLOOR)`.
-3. **Author-uniqueness vs slate size.** Author uniqueness is
-   hardcoded to "at most 1 per (user, Author)", so each user
-   needs at least `SLATE_SIZE_K` distinct authors in their reach.
-   A user whose reach concentrates in fewer authors is infeasible
-   even when total candidate count is large.
-4. **Cold-start cap × explanation floor.** `EXPLANATION_FLOOR` is
-   position-weighted (weights `K..1` at slots `1..K`); a slate
-   with three picks of `path_count_total=2` at slots 1, 2, 3
-   contributes `2*3 + 2*2 + 2*1 = 12`. With at most
-   `COLD_START_CAP` weakly-explained picks (each contributing at
-   most `(WEAK_EXPLANATION_THRESHOLD - 1) * (K+1-slot)`), the
-   floor must be reachable. Customers raising `EXPLANATION_FLOOR`
-   should inspect the per-user path-count distribution first.
-5. **Missing edges.** Every Book picked must have at least one
-   `Book.about(Subject)` and one `Book.written_by(Author)` row,
-   else the diversity / uniqueness caps silently exempt that
-   Book.
-6. **Hero pin.** Each user needs at least one candidate whose
-   Book has `triangle_count >= HERO_EMBEDDEDNESS_THRESHOLD`. A
-   user whose 2-hop reach lands only on isolated similarity-
-   graph regions (low or zero triangle counts) is infeasible
-   because there's no eligible book for slot 1. Inspect the
-   "Book structural embeddedness" diagnostic table at the end of
-   the runner, and either drop `HERO_EMBEDDEDNESS_THRESHOLD` or
-   densify the similarity input.
-
-The runner runs a Python-level pre-solve assertion (in
-`book_slate_recommendation.py` immediately before
-`problem.solve(...)`) that materialises the Candidate set,
-anti-joins against `User.read`, and raises `ValueError` if any
-user has fewer than `SLATE_SIZE_K` unread candidates, fewer than
-`FRESHNESS_FLOOR` unread fresh candidates, fewer than
-`ORIGINALS_FLOOR` unread in-house candidates, fewer than
-`SLATE_SIZE_K` distinct unread authors, fewer than
-`ceil(K/MAX_PER_SUBJECT)` distinct unread subjects, fewer than
-`K - COLD_START_CAP` strongly-explained candidates, a max
-achievable position-weighted explanation score below
-`EXPLANATION_FLOOR`, or zero unread hero-eligible candidates. The
-assertion's error message lists the affected users per shortfall
-and a strategy block keyed by which condition fired. The runner also prints
-an "Unread candidate count per user" table just before solving,
-so dense reach can be inspected even when the assert passes. For post-solve diagnostics
-on a non-OPTIMAL run: `problem.verify(...)` already prints
-per-IC violation messages on the failing constraints; if the
-script then exits at the `model.require(... == "OPTIMAL")` line
-you can comment that line out to let the post-solve inspect
-blocks fire (note: with no successful solve, the "Final slate
-per user" table will be empty and the candidate-set diagnostic
-at the end mirrors the pre-solve one).
+<summary>Solve returns INFEASIBLE / the final slate is empty</summary>
+
+The runner enforces ten constraints and requires an `OPTIMAL` status. If the data is too sparse or too clustered, the joint constraints can be infeasible. The dominant causes on customer slices are:
+
+1. **Too few candidates after the already-read exclusion.** Each user needs at least `SLATE_SIZE_K` candidates in their 2-hop reach after already-read books are excluded. Recommendable candidates come from length-2 `read_Book -> similar_Book` walks, so a user whose reads have no `similar_to` neighbors will be infeasible. Inspect the candidate-set diagnostic printed at the end of the runner.
+2. **Disjoint floors.** `FRESHNESS_FLOOR` and `ORIGINALS_FLOOR` are independent. A user with no candidate that is both fresh and in-house must spend `FRESHNESS_FLOOR + ORIGINALS_FLOOR` distinct picks, not the maximum of the two.
+3. **Author uniqueness versus slate size.** Author uniqueness caps at one pick per `(user, author)`, so each user needs at least `SLATE_SIZE_K` distinct authors in reach.
+4. **Cold-start cap and explanation floor.** `EXPLANATION_FLOOR` is position-weighted. With at most `COLD_START_CAP` weakly-explained picks, the floor must still be reachable; inspect the per-user path-count distribution first.
+5. **Missing edges.** Every picked book must have at least one `Book.about(Subject)` and one `Book.written_by(Author)` row, or the diversity and uniqueness caps silently exempt it.
+6. **Hero pin.** Each user needs at least one candidate whose book has `triangle_count >= HERO_EMBEDDEDNESS_THRESHOLD`, or there is no eligible book for slot 1. Inspect the structural-embeddedness diagnostic table, then either lower `HERO_EMBEDDEDNESS_THRESHOLD` or densify the similarity input.
+
+The runner runs a Python-level pre-solve assertion just before `problem.solve(...)` that materializes the candidate set, anti-joins against the read history, and raises a `ValueError` naming the affected users per shortfall, with a strategy block keyed by which condition fired. It also prints an unread-candidate-count table before solving.
 
 </details>
 
 <details>
 <summary>Slow or timing out at <code>--size lg</code></summary>
 
-The default `time_limit_sec=180` is sized for the bundled `sm`
-slice. At `lg` (~600 books, ~120k integer-domain decisions × 10
-ICs), raise it to 600 and watch the MiniZinc propagation progress
-in the solver log. If the solve still times out, drop
-`SLATE_SIZE_K` or relax `EXPLANATION_FLOOR` so propagation can
-prune harder.
+The default `time_limit_sec=180` is sized for the bundled `sm` slice. At `lg`, raise it and watch the MiniZinc propagation progress in the solver log. If the solve still times out, drop `SLATE_SIZE_K` or relax `EXPLANATION_FLOOR` so propagation can prune harder.
 
 </details>
 
 <details>
 <summary>Open Library fetch script slow or rate-limited</summary>
 
-The fetcher caches every API response under `data/_cache/` keyed
-by URL. On a fresh `--size lg` pull the script makes a few
-hundred requests at the Open Library default rate. Subsequent
-runs are offline. If your network blocks Open Library, point the
-fetcher at a snapshot of the
-<https://openlibrary.org/data/ol_dump_latest.txt.gz> bulk
-download.
+The fetcher caches every API response under `data/_cache/` keyed by URL, so subsequent runs are offline. On a fresh `--size lg` pull the script makes a few hundred requests at the Open Library default rate. If your network blocks Open Library, point the fetcher at a snapshot of the <https://openlibrary.org/data/ol_dump_latest.txt.gz> bulk download.
 
 </details>
 
+## Learn more
+
+### Core concepts
+
+- [Multi-reasoner workflows](https://docs.relational.ai/) — chained reasoner patterns and ontology enrichment across stages.
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)`, aggregates, and result selection.
+
+### Reasoner reference
+
+- [Paths library](https://docs.relational.ai/) — bounded knowledge-graph walks with `.repeat(...)` and `all_paths()`.
+- [Graph reasoner](https://docs.relational.ai/) — building a `Graph`, node-concept binding, and structural metrics such as triangle count.
+- [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API, integer decisions, constraints, and objectives on MiniZinc and HiGHS.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
+
 ## References
 
-- *Open Library Developer API* (CC0) --
-  <https://openlibrary.org/dev/docs/api>. Bibliographic catalog
-  used by the bundled slice; `data/fetch_open_library_slice.py`
-  pulls deterministic cuts.
+- *Open Library Developer API* (CC0) — <https://openlibrary.org/dev/docs/api>. Bibliographic catalog used by the bundled slice; `data/fetch_open_library_slice.py` pulls deterministic cuts.
diff --git a/v1/campaign_roi/README.md b/v1/campaign_roi/README.md
index c79abe95..486615ee 100644
--- a/v1/campaign_roi/README.md
+++ b/v1/campaign_roi/README.md
@@ -14,39 +14,33 @@ tags:
   - Conversion Maximization
 ---
 
-# Campaign ROI
-
 ## What this template is for
 
-This template uses **Prescriptive** reasoning to reallocate a marketing budget across an existing portfolio of campaigns to maximize total expected conversions, subject to three real-world constraints:
-
-- **Per-campaign floor** — no campaign can drop below a fixed fraction of its current spend (institutional inertia: account managers, vendor commitments, brand presence).
-- **Per-campaign cap** — no campaign can exceed a multiple of its current spend (creative-fatigue, audience-saturation guardrails).
-- **Regional cap** — total spend in one designated *paused* region cannot exceed a configurable share of the total budget (organizational pause: regulatory, reputational, or capacity reasons).
+Every marketing team eventually faces the same question: the portfolio of campaigns is already running and the quarterly budget is fixed, so where should the next dollar go? Some campaigns convert far better than others, but you cannot simply pour everything into the winners. Account managers, vendor commitments, and brand presence set a floor under each campaign; creative fatigue and audience saturation set a cap; and a region under an organizational pause (regulatory, reputational, or capacity reasons) can only absorb so much of the total. Return on investment (ROI) depends on respecting all of those limits at once while still moving money toward what works.
 
-The decision: pick a new dollar budget for every campaign such that total spend respects the overall budget, every campaign respects its floor and cap, the paused region stays within its share, and total expected conversions are maximized.
-
-This is the **portfolio rebalancing** counterpart to [`ad_spend_allocation`](../ad_spend_allocation/), which decides spend across channel × campaign pairs from scratch. Here the question is "we have a working portfolio — where should the next dollar go?" rather than "design the portfolio from zero."
+**This template uses prescriptive reasoning to pick a new dollar budget for every campaign that maximizes total expected conversions while honoring the overall budget, each campaign's floor and cap, and the paused region's share limit.** The result is a defensible reallocation plan you can act on, not just a ranking of which campaigns look good.
 
 ## Who this is for
 
-- Marketing analytics teams reshaping campaign portfolios under fixed quarterly budgets
-- Operations researchers learning continuous LP with bound constraints derived from per-entity data
-- Data scientists exploring the floor-cap-regional-cap pattern that recurs across portfolio decisions (advertising, R&D, vendor allocation)
+- Marketing analytics teams reshaping campaign portfolios under fixed quarterly budgets.
+- Operations researchers learning continuous linear programming (LP) with bound constraints derived from per-entity data.
+- Data scientists exploring the floor-cap-regional-cap pattern that recurs across portfolio decisions (advertising, research and development, vendor allocation).
+- **Assumed knowledge**: comfortable reading Python; the LP and marketing terms are explained as they come up. No prior RelationalAI experience is required to run it.
 
 ## What you'll build
 
-- A continuous LP that reallocates budget across 12 marketing campaigns
-- Per-campaign floor and cap bounds derived from each campaign's current spend
-- A total budget constraint
-- A regional cap constraint that limits the paused region's share of total spend
-- An objective that maximizes total expected conversions = `sum(budget × conversion_rate)`
+- A reallocation plan that maximizes total expected conversions across 12 marketing campaigns while holding total spend constant, produced by RelationalAI's **prescriptive reasoner**.
+- Per-campaign floor and cap bounds derived automatically from each campaign's current spend, expressed as decision-variable constraints.
+- A regional cap constraint that keeps the paused region within a configurable share of the total budget.
+- A per-campaign, per-region summary of the optimized budget versus current spend, with the binding constraints called out.
 
 ## What's included
 
-- `campaign_roi.py` — main script (single end-to-end run)
-- `data/campaigns.csv` — 12 campaigns across 5 regions with current budgets and conversion rates
-- `pyproject.toml` — Python package configuration with dependencies
+- **Model**: a continuous LP over a single `Campaign` concept, with per-campaign floor and cap bounds, a total-budget constraint, a paused-region share cap, and a conversion-maximizing objective.
+- **Runner**: `campaign_roi.py` — a single Python script that runs end-to-end against a Snowflake-connected RAI account.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: `data/campaigns.csv` — 12 campaigns across 5 regions with current budgets and empirical conversion rates.
+- **Outputs**: solver status, optimized-versus-current conversions and lift, a per-campaign reallocation table, and a regional-spend summary against the paused-region cap.
 
 ## Prerequisites
 
@@ -57,8 +51,8 @@ This is the **portfolio rebalancing** counterpart to [`ad_spend_allocation`](../
 
 ### Tools
 
-- Python >= 3.10
-- RelationalAI Python SDK (`relationalai`) == 1.0.14
+- Python >= 3.10.
+- RelationalAI Python SDK (`relationalai == 1.0.14`).
 
 ## Quickstart
 
@@ -87,7 +81,7 @@ This is the **portfolio rebalancing** counterpart to [`ad_spend_allocation`](../
    python -m pip install .
    ```
 
-4. Configure Snowflake connection and RAI profile:
+4. Configure the Snowflake connection and RAI profile:
 
    ```bash
    rai init
@@ -99,7 +93,7 @@ This is the **portfolio rebalancing** counterpart to [`ad_spend_allocation`](../
    python campaign_roi.py
    ```
 
-6. Expected output (truncated):
+6. Expected output (a few lines confirm a successful run):
 
    ```text
    Status: OPTIMAL
@@ -107,28 +101,10 @@ This is the **portfolio rebalancing** counterpart to [`ad_spend_allocation`](../
    Total expected conversions (current):   2,691.0
    Lift: +17.1%
 
-   Budget reallocation per campaign (sorted by largest absolute change):
-                   campaign  region  current  optimized  rate  delta  multiple
-       WEST_Premium_Upgrade    WEST     80.0      240.0   3.2  160.0     3.000
-          SOUTH_Retention_4   SOUTH    160.0       16.0   2.2 -144.0     0.100
-        CENTRAL_Retention_3 CENTRAL     70.0      210.0   2.7  140.0     3.000
-          CENTRAL_WinBack_7 CENTRAL    140.0       14.0   2.3 -126.0     0.100
-   WEST_Retention_Emergency    WEST    200.0      325.0   2.9  125.0     1.625
-            SOUTH_WinBack_6   SOUTH     50.0      150.0   2.6  100.0     3.000
-   ...
-
-   Regional spend (optimized):
-    region  current  optimized  share_of_total
-      WEST    280.0      565.0        0.500000
-   CENTRAL    260.0      229.0        0.202655
-     SOUTH    250.0      170.0        0.150442
-     NORTH    140.0      146.0        0.129204
-      EAST    200.0       20.0        0.017699
-
    Paused region 'WEST' cap: 565.0 (50% of $1,130K total)
    ```
 
-   The optimum hits the WEST regional cap exactly (50% of $1,130K = $565K), reaches the 3× cap on three high-performing campaigns (`WEST_Premium_Upgrade`, `CENTRAL_Retention_3`, `SOUTH_WinBack_6`), and pushes six low-performing campaigns down to the 10% floor. Despite holding total spend constant, conversions increase by 17.1%.
+   The optimum hits the WEST regional cap exactly (50% of $1,130K = $565K), reaches the 3x cap on three high-performing campaigns (`WEST_Premium_Upgrade`, `CENTRAL_Retention_3`, `SOUTH_WinBack_6`), and pushes six low-performing campaigns down to the 10% floor. Despite holding total spend constant, conversions increase by 17.1%. The full printout, including the per-campaign reallocation table and regional-spend summary, is in `runbook.md`.
 
 ## Template structure
 
@@ -136,121 +112,94 @@ This is the **portfolio rebalancing** counterpart to [`ad_spend_allocation`](../
 .
 ├── README.md               # this file
 ├── pyproject.toml          # dependencies
+├── runbook.md              # analyst-facing walkthrough
 ├── campaign_roi.py         # main script (end-to-end)
 └── data/
     └── campaigns.csv       # 12 campaigns across 5 regions
 ```
 
-**Start here:** `python campaign_roi.py`.
+**Start here**: run `python campaign_roi.py` for the full reallocation end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Sample data
 
-12 marketing campaigns across 5 regions (NORTH, SOUTH, CENTRAL, EAST, WEST). Each campaign has:
+The bundled data is synthetic and illustrative — designed to teach the reallocation pattern, not to match a specific advertiser's portfolio. It describes 12 marketing campaigns across 5 regions (NORTH, SOUTH, CENTRAL, EAST, WEST). Each campaign has:
 
 | Column | Type | Notes |
 |---|---|---|
 | `id` | Integer | Primary key |
-| `name` | String | Campaign name (region prefix + type + id) |
+| `name` | String | Campaign name (region prefix, then type, then id) |
 | `region` | String | Region tag — drives the regional-cap constraint |
 | `current_budget` | Float | Current spend in $K |
 | `conversion_rate` | Float | Conversions per $K (empirical, varies 1.5 to 3.2) |
 
-Total current budget across all campaigns: $1,130K. WEST has the two highest-rate campaigns (3.2 and 2.9) — without the regional cap, the optimum would push almost all budget into WEST.
+Total current budget across all campaigns: $1,130K. WEST has the two highest-rate campaigns (3.2 and 2.9), so without the regional cap the optimum would push almost all budget into WEST.
 
 ## Model overview
 
-### Campaign
+The model is a single concept: one `Campaign` per row of `campaigns.csv`, enriched with a decision-variable property after the solve.
 
-A marketing campaign with a current budget, region tag, and an empirical conversion rate.
+- **Key entities**: `Campaign` — a marketing campaign with a current budget, region tag, and empirical conversion rate; its optimized budget is the decision variable populated after the solve.
+- **Primary identifiers**: integer `id` on `Campaign`, loaded from `data/campaigns.csv`.
+- **Important invariants**: `current_budget` and `conversion_rate` are non-negative; the optimized budget `x_budget` stays between the per-campaign floor and cap; total spend does not exceed `TOTAL_BUDGET`; and the paused region's spend does not exceed its share cap.
 
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | Integer | Yes | Loaded from `data/campaigns.csv` |
-| `name` | String | No | Human-readable name |
-| `region` | String | No | One of NORTH / SOUTH / CENTRAL / EAST / WEST |
-| `current_budget` | Float | No | Current spend in $K |
-| `conversion_rate` | Float | No | Conversions per $K of spend |
+For the full concept and property definitions, see `campaign_roi.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
-### 1. Decision variable
-
-A continuous budget variable per campaign. The lower bound 0 is permissive — the per-campaign floor (below) tightens it from the data.
+The script loads the campaigns into a single `Campaign` concept, defines one continuous decision variable per campaign, adds the floor, cap, total-budget, and regional-cap constraints, maximizes conversions, and prints the reallocation.
 
-```python
-Campaign.x_budget = model.Property(f"{Campaign} has new budget {Float:budget}")
+### 1. Decision variable
 
-problem.solve_for(
-    Campaign.x_budget,
-    lower=0,
-    name=["budget", Campaign.name],
-)
-```
+One continuous budget variable per campaign, with a permissive lower bound of 0 that the per-campaign floor (below) tightens from the data.
 
 ### 2. Constraints
 
-**Per-campaign floor and cap**, derived from each campaign's current spend:
-
-```python
-problem.satisfy(model.require(
-    Campaign.x_budget >= FLOOR_FRACTION * Campaign.current_budget,
-    Campaign.x_budget <= CAP_MULTIPLIER * Campaign.current_budget,
-))
-```
-
-**Total budget**:
-
-```python
-problem.satisfy(model.require(sum(Campaign.x_budget) <= TOTAL_BUDGET))
-```
-
-**Paused-region cap** — single constraint summing only campaigns in the paused region:
-
-```python
-problem.satisfy(model.require(
-    sum(Campaign.x_budget).where(Campaign.region == PAUSED_REGION)
-    <= PAUSED_CAP_FRACTION * TOTAL_BUDGET
-))
-```
+The per-campaign floor and cap are derived from each campaign's current spend: the floor reflects institutional inertia (account managers, vendor commitments, brand presence), and the cap reflects creative-fatigue and audience-saturation guardrails. A total-budget constraint caps combined spend across all campaigns. The paused-region cap sums only campaigns in the paused region and keeps that total within a configurable share of the budget (an organizational pause for regulatory, reputational, or capacity reasons).
 
 ### 3. Objective
 
-```python
-problem.maximize(sum(Campaign.x_budget * Campaign.conversion_rate))
-```
+The objective maximizes total expected conversions — the sum over campaigns of budget times conversion rate.
+
+See `campaign_roi.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
 ## Customize this template
 
 ### Use your own data
 
-Replace `data/campaigns.csv` with your own. Required columns: `id`, `name`, `region`, `current_budget`, `conversion_rate`. The model loads region as a free string — any region naming convention works.
+Replace `data/campaigns.csv` with your own. Required columns: `id`, `name`, `region`, `current_budget`, `conversion_rate`. The model loads region as a free string, so any region naming convention works.
 
 ### Tune parameters
 
-All four are at the top of the script under `# Configure inputs`:
+All parameters live at the top of the script under `# Configure inputs`:
 
 | Parameter | Default | Effect |
 |---|---|---|
 | `TOTAL_BUDGET` | 1130 ($K) | Cap on total spend across all campaigns |
 | `FLOOR_FRACTION` | 0.10 | Each campaign cannot drop below 10% of current |
-| `CAP_MULTIPLIER` | 3.0 | Each campaign cannot exceed 3× current |
+| `CAP_MULTIPLIER` | 3.0 | Each campaign cannot exceed 3 times current |
 | `PAUSED_REGION` | `"WEST"` | Which region is subject to the share cap |
 | `PAUSED_CAP_FRACTION` | 0.5 | Paused region cannot exceed 50% of total spend |
 
-Tightening `CAP_MULTIPLIER` toward 1.5 will distribute increases across more campaigns. Loosening `FLOOR_FRACTION` toward 0 lets the optimizer fully shut down poor performers.
+Tightening `CAP_MULTIPLIER` toward 1.5 distributes increases across more campaigns. Loosening `FLOOR_FRACTION` toward 0 lets the optimizer fully shut down poor performers.
 
 ### Extend the model
 
 - **Conversion saturation.** The current model assumes linear conversions (each $1K adds the same number of conversions). For more realistic diminishing returns, replace `Campaign.conversion_rate` with a piecewise-linear or logarithmic function and add SOS2 constraints. See `traveling_salesman` and `supply_chain_transport` for piecewise-linear examples in this portfolio.
 - **Multiple paused regions.** Generalize the regional cap to a parameterized `RegionCap` concept and apply the constraint per region.
-- **Forecast uncertainty.** Add a Scenario Concept with conversion-rate multipliers (low / base / high) and solve all scenarios in one pass — see `ad_spend_allocation` for the Scenario pattern.
+- **Forecast uncertainty.** Add a Scenario concept with conversion-rate multipliers (low / base / high) and solve all scenarios in one pass — see `ad_spend_allocation` for the Scenario pattern.
+
+### Scale up / productionize
+
+- For Snowflake-backed runs, swap the `read_csv(...)` call for a `model.data(snowflake_table)` call so the campaigns load directly from your warehouse.
+- The LP scales comfortably to thousands of campaigns; solve time grows with the number of decision variables and constraints, not the budget size.
+- Pin `relationalai` (see Prerequisites) and keep the parameters under `# Configure inputs` in version control so runs are reproducible.
 
 ## Troubleshooting
 
 <details>
   <summary>Why is the WEST allocation exactly $565K?</summary>
 
-  WEST has the two highest conversion rates (3.2 and 2.9). Without the regional cap, the optimum would push WEST_Premium_Upgrade to its 3× cap ($240K) and WEST_Retention_Emergency toward its 3× cap ($600K), totaling $840K. The 50% regional cap binds at $565K, so the optimizer fills WEST_Premium_Upgrade to its 3× cap first (highest rate) and then takes WEST_Retention_Emergency up to $325K to exactly hit the regional cap.
+  WEST has the two highest conversion rates (3.2 and 2.9). Without the regional cap, the optimum would push WEST_Premium_Upgrade to its 3x cap ($240K) and WEST_Retention_Emergency toward its 3x cap ($600K), totaling $840K. The 50% regional cap binds at $565K, so the optimizer fills WEST_Premium_Upgrade to its 3x cap first (highest rate) and then takes WEST_Retention_Emergency up to $325K to exactly hit the regional cap.
 </details>
 
 <details>
@@ -262,17 +211,32 @@ Tightening `CAP_MULTIPLIER` toward 1.5 will distribute increases across more cam
 <details>
   <summary>Why are six campaigns at exactly 10% of current?</summary>
 
-  These are campaigns whose conversion rates are below the marginal rate of the binding budget constraint. The optimizer can't fully shut them down because the floor constraint forces 10%. If you set `FLOOR_FRACTION = 0`, those campaigns would go to zero.
+  These are campaigns whose conversion rates are below the marginal rate of the binding budget constraint. The optimizer cannot fully shut them down because the floor constraint forces 10%. If you set `FLOOR_FRACTION = 0`, those campaigns would go to zero.
 </details>
 
 <details>
   <summary>The optimizer returns INFEASIBLE.</summary>
 
-  The most likely cause is that the floor sums exceed the total budget. Check: `sum(FLOOR_FRACTION * current_budget for all campaigns) <= TOTAL_BUDGET`. Loosen the floor or raise the total budget.
+  The most likely cause is that the floor sums exceed the total budget. Check that the sum of `FLOOR_FRACTION * current_budget` across all campaigns is at most `TOTAL_BUDGET`. Loosen the floor or raise the total budget.
 </details>
 
 ## Related templates
 
-- [`ad_spend_allocation`](../ad_spend_allocation/) — channel × campaign spend from scratch (designs the portfolio rather than rebalancing it)
-- [`portfolio_balancing`](../portfolio_balancing/) — financial portfolio rebalancing with rules, graph clustering, and bi-objective Markowitz
-- [`hospital_staffing`](../hospital_staffing/) — bi-objective LP for resource allocation under multiple competing goals
+- [`ad_spend_allocation`](../ad_spend_allocation/) — channel-by-campaign spend from scratch (designs the portfolio rather than rebalancing it).
+- [`portfolio_balancing`](../portfolio_balancing/) — financial portfolio rebalancing with rules, graph clustering, and bi-objective Markowitz.
+- [`hospital_staffing`](../hospital_staffing/) — bi-objective LP for resource allocation under multiple competing goals.
+
+## Learn more
+
+### Core concepts
+
+- [RelationalAI documentation](https://docs.relational.ai/) — concepts, properties, and how models load and query data.
+- [Prescriptive reasoning](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives used throughout this template.
+
+### Language / modeling reference
+
+- [PyRel query language](https://docs.relational.ai/) — `model.define`, `model.require`, `model.select`, and aggregations such as `sum(...)`.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/cell_tower_coverage/README.md b/v1/cell_tower_coverage/README.md
index dd0867bd..f57953ed 100644
--- a/v1/cell_tower_coverage/README.md
+++ b/v1/cell_tower_coverage/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Cell Tower Coverage"
-description: "Select candidate cell tower sites and assign demand zones to maximize covered population under budget, tower-count, and capacity limits."
+description: "Choose which candidate cell tower sites to build and assign demand zones to them, maximizing covered population under budget, tower-count, and capacity limits."
 featured: false
 experience_level: beginner
 industry: "Technology & Telecom"
@@ -16,117 +16,87 @@ tags:
   - HiGHS
 ---
 
-# Cell Tower Coverage
-
 ## What this template is for
 
-Telecommunications and infrastructure teams often need to decide where to build the next set of wireless sites. Candidate locations differ in cost and serving capacity, and each site can cover only a subset of demand zones based on distance, terrain, signal quality, or planning rules. This template chooses tower sites and assigns covered demand zones to selected towers, maximizing covered population while respecting a fixed build budget, a maximum number of new towers, and tower capacity limits.
-
-The model uses RelationalAI's **prescriptive** reasoner to solve a maximum-coverage mixed-integer program with single assignment. Binary variables choose which tower sites to build, mark which demand zones are covered, and assign each covered demand zone to exactly one selected tower that can serve it.
-
-## Why this problem matters
-
-Coverage planning is a common capital allocation problem for wireless network expansion, public safety communications, rural broadband programs, and temporary network deployments. The challenge is that every candidate tower covers a different overlapping set of zones and has finite serving capacity. The best plan is not always the cheapest tower or the tower covering the largest single zone; the selected sites need to work together as a portfolio, and assigned demand cannot overload any selected tower.
+Telecommunications and infrastructure teams routinely have to decide where to build the next set of wireless sites. Candidate locations differ in build cost and serving capacity, and each site can cover only a subset of demand zones based on distance, terrain, signal quality, or planning rules. Picking the cheapest tower or the one covering the single largest zone rarely gives the best plan — the selected sites have to work together as a portfolio, and the demand assigned to a tower cannot exceed its capacity. This template chooses tower sites and assigns each covered demand zone to a serving tower so that covered population is as large as possible within a fixed build budget and a cap on the number of new towers.
 
-### Key design patterns demonstrated
-
-- **Maximum coverage** -- maximize covered population under a limited budget.
-- **Linked binary decisions** -- a zone can count as covered only if it is assigned to a selected tower that can serve it.
-- **Single assignment** -- every covered demand zone is assigned to exactly one serving tower.
-- **Capacity constraints** -- each selected tower can serve assigned population only up to its capacity.
-- **Budget-constrained selection** -- tower build costs must stay under a capital limit.
-- **Cardinality constraint** -- the plan can select at most a fixed number of towers.
-- **Many-to-many coverage relationships** -- tower-zone coverage pairs are represented explicitly in the ontology.
-- **Post-solve coverage reporting** -- report selected sites, tower utilization, assigned zones, uncovered zones, and total coverage rate.
+**The model uses RelationalAI's prescriptive reasoner to solve a maximum-coverage mixed-integer program in which binary variables select tower sites, mark demand zones as covered, and assign each covered zone to exactly one selected tower that can serve it.** The result is a defensible capital plan: which sites to build, which zones they serve, how loaded each tower is, and which population remains uncovered.
 
 ## Who this is for
 
-- Network planners evaluating candidate tower sites
-- Infrastructure teams prioritizing capital projects
-- Public-sector analysts studying emergency communications coverage
-- Data scientists learning set-covering and maximum-coverage optimization
-- Engineers modeling binary selection decisions with RelationalAI
+- Network planners evaluating candidate tower sites and infrastructure teams prioritizing capital projects.
+- Public-sector analysts studying emergency-communications or rural-broadband coverage.
+- Data scientists and engineers learning set-covering and maximum-coverage optimization with RelationalAI.
+- **Assumed knowledge**: comfortable reading Python; the optimization terms (decision variables, constraints, objective) are explained as they come up. As a beginner-level single-reasoner template, no prior RelationalAI experience is required to run it.
 
 ## What you'll build
 
-- A semantic model for candidate tower sites, demand zones, and feasible coverage pairs
-- A mixed-integer optimization model with tower-selection, zone-coverage, and zone-assignment variables
-- A budget constraint and a maximum-tower constraint
-- A coverage-linking constraint that assigns each covered zone to exactly one selected tower
-- A tower-capacity constraint that prevents overloaded serving plans
-- A covered-population objective
-- A coverage summary and CSV output for downstream mapping or reporting
+- A funded tower-build plan that maximizes covered population within a fixed capital budget and a cap on new towers, produced by **prescriptive reasoning** (a mixed-integer program).
+- A semantic model of candidate tower sites, demand zones, and feasible tower-zone coverage pairs, expressed as RelationalAI concepts and relationships.
+- A coverage-linking rule that counts a zone as covered only when it is assigned to exactly one selected, serving tower, plus a capacity rule that prevents any tower from being overloaded.
+- A coverage report — selected sites with utilization, assigned zones, uncovered zones, and total coverage rate — written to `data/coverage_solution.csv` for downstream mapping or reporting.
 
 ## What's included
 
-- `cell_tower_coverage.py` -- Main script with the semantic model, optimization model, solve, and reporting
-- `data/tower_sites.csv` -- Candidate tower sites with build costs, capacities, and site metadata
-- `data/demand_zones.csv` -- Demand zones with region and population
-- `data/coverage_pairs.csv` -- Feasible tower-zone service pairs with distance and signal score
-- `pyproject.toml` -- Python package configuration with dependencies
-
-## Template structure
-
-```text
-.
-├─ README.md                       # this file
-├─ pyproject.toml                  # dependencies
-├─ cell_tower_coverage.py          # main entrypoint: model, solve, report
-└─ data/
-   ├─ tower_sites.csv              # candidate build sites
-   ├─ demand_zones.csv             # population demand zones
-   ├─ coverage_pairs.csv           # feasible tower-zone coverage pairs
-   └─ coverage_solution.csv        # written by the script after solving
-```
-
-**Start here**: run `python cell_tower_coverage.py`.
+- **Model**: `cell_tower_coverage.py` builds the semantic model (three concepts, two coverage relationships), the mixed-integer optimization problem (three binary variable families, four constraints, one objective), the solve, and the reporting.
+- **Runner**: `cell_tower_coverage.py` — a single Python script that runs end-to-end against a Snowflake-connected RAI account.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: 6 candidate tower sites, 10 demand zones, and 19 feasible tower-zone coverage pairs. See *Sample data* below.
+- **Outputs**: stdout tables (selected sites, assigned zones, uncovered zones, coverage summary) plus `data/coverage_solution.csv`.
 
 ## Prerequisites
 
 ### Access
 
-- A Snowflake account that has the RAI Native App installed.
-- A Snowflake user with permissions to access the RAI Native App.
+- A Snowflake account with the RelationalAI Native App installed.
+- A Snowflake user with permissions to access the RelationalAI Native App.
 
 ### Tools
 
-- Python >= 3.10
-- RelationalAI Python SDK (`relationalai`) == 1.0.14
+- Python >= 3.10.
+- RelationalAI Python SDK (`relationalai == 1.0.14`).
 
 ## Quickstart
 
-1. Download ZIP:
+1. Download the template and extract it:
+
    ```bash
    curl -O https://docs.relational.ai/templates/zips/v1/cell_tower_coverage.zip
    unzip cell_tower_coverage.zip
    cd cell_tower_coverage
    ```
+
    > [!TIP]
    > You can also download the template ZIP using the "Download ZIP" button at the top of this page.
 
-2. Create venv:
+2. Create a virtual environment and activate it:
+
    ```bash
    python -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade pip
    ```
 
-3. Install:
+3. Install dependencies:
+
    ```bash
    python -m pip install .
    ```
 
 4. Configure:
+
    ```bash
    rai init
    ```
 
-5. Run:
+5. Run the template end-to-end:
+
    ```bash
    python cell_tower_coverage.py
    ```
 
-6. Expected output:
+6. Expected output (a few lines confirm a successful run):
+
    ```text
    ======================================================================
    CELL TOWER COVERAGE
@@ -140,108 +110,117 @@ Coverage planning is a common capital allocation problem for wireless network ex
    Status: OPTIMAL
    Objective: covered population = ...
 
-   === Selected Tower Sites ===
-   site_id                    name site_type  region build_cost capacity assigned_population utilization
-      ...                     ...       ...     ...        ...
-
-   === Assigned Demand Zones ===
-   zone_id                 name  region population              assigned_site
-      ...                  ...     ...        ...                         ...
-
-   === Uncovered Demand Zones ===
-   zone_id                 name  region population
-      ...                  ...     ...        ...
-
    === Coverage Summary ===
    Selected build cost: ...
    Covered population: ...
    Coverage rate: ...
-   Uncovered population: ...
 
    Wrote coverage solution to: data/coverage_solution.csv
    ```
 
-## How It Works
+## Template structure
+
+```text
+cell_tower_coverage/
+  cell_tower_coverage.py          # Main script: model, solve, report
+  data/
+    tower_sites.csv               # 6 candidate build sites
+    demand_zones.csv              # 10 population demand zones
+    coverage_pairs.csv            # 19 feasible tower-zone coverage pairs
+    coverage_solution.csv         # written by the script after solving
+  README.md                       # this file
+  runbook.md                      # paste-testable walkthrough (RAI skills)
+  pyproject.toml                  # dependencies
+```
+
+**Start here**: run `python cell_tower_coverage.py` for the full model, solve, and report end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-### 1. Load the planning data
+## Sample data
 
-The template loads a compact synthetic dataset:
+The bundled data is synthetic and illustrative — a compact network-expansion screen shaped like a real one, not a specific operator's network. The coverage pairs could come from a radio-frequency planning tool, a distance threshold, a terrain model, or engineering judgment.
 
-- `tower_sites.csv`: candidate tower sites, regions, site types, build costs, and serving capacities
-- `demand_zones.csv`: demand zones with population counts
-- `coverage_pairs.csv`: feasible service pairs from tower sites to demand zones
+- **`tower_sites.csv`** (6 rows) — candidate tower sites across five regions, with site type (macro or small cell), build cost, and serving capacity.
+- **`demand_zones.csv`** (10 rows) — demand zones with region and population count.
+- **`coverage_pairs.csv`** (19 rows) — feasible tower-zone service pairs, each with a distance and a signal score. Every demand zone appears in at least one pair, so every zone is reachable by some tower.
+- **`coverage_solution.csv`** — written after the solve; one row per demand zone with its covered flag and assigned site.
 
-The data is synthetic but shaped like a real network expansion screen. The coverage pairs could come from a radio-frequency planning tool, a distance threshold, a terrain model, or engineering judgment.
+## Model overview
 
-### 2. Define selection, coverage, and assignment variables
+Three concepts describe the planning problem; the optimization adds one binary decision property to each.
 
-The model has three binary decision variables:
+- **Key entities**: `TowerSite` — a candidate infrastructure location that may be built (site type, build cost, serving capacity); `DemandZone` — a population area that may be covered by a selected tower; `CoveragePair` — a feasible tower-zone service relationship, where only paired zones can be served and only by their paired towers.
+- **Primary identifiers**: `site_id` on `TowerSite`, `zone_id` on `DemandZone`, and a composite `site_id` + `zone_id` key on `CoveragePair`.
+- **Important invariants**: build costs, capacities, and populations are non-negative; every demand zone is reachable by at least one coverage pair (the script raises an error otherwise); the decision variables (`selected`, `covered`, `assigned`) are binary; total build cost stays at or under the budget and the number of selected towers stays at or under the cap.
 
-```python
-TowerSite.x_selected = model.Property(f"{TowerSite} selected if {Float:selected}")
-DemandZone.y_covered = model.Property(f"{DemandZone} covered if {Float:covered}")
-CoveragePair.z_assigned = model.Property(f"{CoveragePair} assigned if {Float:assigned}")
-```
+`CoveragePair` links each pair to its `TowerSite` and `DemandZone`, so only zones that appear as a pair can be served, and only by the towers they are paired with.
 
-`x_selected` chooses candidate tower sites. `y_covered` records whether each demand zone is covered by the selected plan. `z_assigned` chooses the specific selected tower that serves a covered demand zone.
+For the full concept and property definitions, see `cell_tower_coverage.py`; `runbook.md` builds them step by step with the RAI skills.
 
-### 3. Link coverage to serving assignments
+## How it works
 
-A demand zone can only count as covered if it is assigned to exactly one feasible tower-zone coverage pair:
+The pipeline runs in one script, from CSV inputs to a solved plan and an exported solution:
 
 ```text
-sum_j assigned[i,j] = covered[i]
+CSV inputs -> load and validate -> concepts and coverage pairs -> decision variables -> constraints and objective -> solve (HiGHS) -> report and export
 ```
 
-This prevents the objective from marking a zone as covered unless the physical network plan gives it a serving tower. Assignment variables exist only for rows in `coverage_pairs.csv`, so a zone can only be assigned to a tower that can physically cover it.
+### 1. Load and validate the planning data
 
-### 4. Assign zones only to selected towers
+The script reads the three CSVs and runs feasibility checks before building the model: each file is non-empty, the parameters are positive, coverage pairs reference known site and zone IDs, and every demand zone is reachable by at least one pair. Any violation raises a clear error rather than producing a silently wrong plan.
 
-Each assignment must use a selected tower:
+### 2. Define selection, coverage, and assignment variables
 
-```text
-assigned[i,j] <= selected[j]
-```
+The model has three families of binary decision variables. `x_selected` chooses which candidate sites to build. `y_covered` records whether each demand zone ends up covered. `z_assigned` chooses the specific selected tower that serves a covered zone; assignment variables exist only on rows of `coverage_pairs.csv`, so a zone can only be assigned to a tower that can physically cover it.
 
-### 5. Respect tower capacity
+### 3. Link coverage to serving assignments
 
-Each selected tower can serve assigned population only up to its capacity:
+A zone counts as covered only when it is assigned to exactly one feasible coverage pair. This per-zone rule prevents the objective from marking a zone as covered without a physical serving tower.
 
-```text
-sum_i population[i] * assigned[i,j] <= capacity[j] * selected[j]
-```
+### 4. Assign zones only to selected towers
 
-If a tower is not selected, the right side is zero, so no demand zone can be assigned to it.
+Each assignment must use a selected tower, so `assigned` cannot exceed `selected` for the pair's tower. If a tower is not selected, none of its pairs can be assigned.
 
-### 6. Respect capital and rollout limits
+### 5. Respect tower capacity
 
-The formulation limits both total build cost and the number of tower sites selected:
+Each selected tower can serve assigned population only up to its capacity, summed per tower over its assigned zones. If a tower is not built, its capacity term is zero and no zone can be assigned to it.
 
-```text
-sum_j build_cost[j] * selected[j] <= BUILD_BUDGET
-sum_j selected[j] <= MAX_NEW_TOWERS
-```
+### 6. Respect capital and rollout limits
 
-### 7. Maximize covered population
+Two portfolio constraints bound the plan: total build cost stays at or under `BUILD_BUDGET`, and the number of selected towers stays at or under `MAX_NEW_TOWERS`.
 
-The objective rewards covering high-population zones:
+### 7. Maximize covered population
 
-```text
-maximize sum_i population[i] * covered[i]
-```
+The objective rewards covering high-population zones, weighting each covered zone by its population. Because each zone has a single binary covered variable and each covered zone has exactly one assignment, the model handles overlapping tower coverage without double-counting population or overloading selected towers. After the solve, the script builds report tables (selected sites with utilization, assigned zones, uncovered zones, coverage summary) and writes `data/coverage_solution.csv`.
 
-Because every demand zone has a binary covered variable and each covered zone has exactly one assignment, the model naturally handles overlapping tower coverage without double-counting population or overloading selected towers.
+See `cell_tower_coverage.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
 ## Customize this template
 
-- **Change the rollout budget** by editing `BUILD_BUDGET` in `cell_tower_coverage.py`.
-- **Limit or expand the build plan** by changing `MAX_NEW_TOWERS`.
-- **Add more candidate tower sites** in `tower_sites.csv`.
-- **Add more demand zones** in `demand_zones.csv`.
-- **Regenerate coverage pairs** using your preferred distance, signal-strength, or engineering threshold.
-- **Adjust capacity assumptions** by editing the `capacity` column in `tower_sites.csv`.
-- **Add regional fairness** by requiring a minimum number of covered zones or covered population per region.
-- **Allow fractional assignment** by replacing binary assignment with continuous fractions if zones can split demand across multiple serving towers.
+Focus on the first changes most users will make.
+
+### Use your own data
+
+- Replace the CSVs in `data/` with your own; keep the column names listed in *Sample data* above.
+- Regenerate coverage pairs with your preferred distance, signal-strength, or engineering threshold, and make sure every demand zone appears in at least one pair (the script requires it).
+- Adjust the `capacity` column in `tower_sites.csv` to reflect real serving capacity, and the `build_cost` column to reflect real capital cost.
+
+### Tune parameters
+
+- **Build budget** — `BUILD_BUDGET` (default `650,000`) caps total capital spend.
+- **Rollout size** — `MAX_NEW_TOWERS` (default `3`) caps how many sites the plan may select.
+- **Solve budget** — `time_limit_sec` on the `problem.solve("highs", ...)` call (default `60` seconds).
+
+### Extend the model
+
+- **Add regional fairness** — require a minimum number of covered zones or a minimum covered population per region.
+- **Allow fractional assignment** — replace the binary assignment variable with a continuous fraction if a zone's demand can split across multiple serving towers.
+- **Add more candidates or zones** — grow `tower_sites.csv` and `demand_zones.csv`, then extend `coverage_pairs.csv` accordingly.
+
+### Scale up / productionize
+
+- For Snowflake-backed runs, swap the `pd.read_csv(...)` calls for `model.data(snowflake_table)` calls so inputs arrive from live tables rather than the bundled CSVs.
+- The model scales to whatever fits the prescriptive engine's solve budget; the default HiGHS solve carries a 60-second time limit that you can raise for larger networks.
+- Pin dependencies (see `pyproject.toml`) for reproducible runs.
 
 ## Troubleshooting
 
@@ -278,3 +257,21 @@ Because every demand zone has a binary covered variable and each covered zone ha
 - If you have multiple profiles, set `export RAI_PROFILE=<your_profile>`.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [RelationalAI documentation](https://docs.relational.ai/) — concepts, relationships, and the semantic model used throughout this template.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives that drive the maximum-coverage program.
+
+### CLI / SDK guides
+
+- [RelationalAI setup and `rai init`](https://docs.relational.ai/) — connecting the SDK to a Snowflake-backed RAI account.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/cicd_runner_allocation/README.md b/v1/cicd_runner_allocation/README.md
index d83ccf16..dc734dcc 100644
--- a/v1/cicd_runner_allocation/README.md
+++ b/v1/cicd_runner_allocation/README.md
@@ -1,6 +1,6 @@
 ---
 title: "CI/CD Runner Allocation"
-description: "Assign CI/CD workflow jobs to the cheapest compatible runner type, subject to concurrency limits, with scenario analysis across capacity levels and conflict analysis to diagnose an infeasible outage."
+description: "Assign continuous-integration and continuous-delivery (CI/CD) workflow jobs to the cheapest compatible runner within concurrency limits. Sweep capacity scenarios and diagnose an infeasible maintenance outage with conflict analysis."
 featured: false
 experience_level: intermediate
 industry: "Technology & Telecom"
@@ -16,123 +16,92 @@ tags:
   - HiGHS
 ---
 
-# CI/CD Runner Allocation
-
 ## What this template is for
 
-This template uses **prescriptive reasoning (optimization)** to assign CI/CD workflow jobs to runner types at minimum cost. Given a set of runners (GitHub Actions runner types with CPU, memory, OS, and per-minute cost) and workflow jobs (with resource requirements and estimated durations), the optimizer assigns each job to the cheapest compatible runner while respecting per-runner concurrency limits.
-
-The template also demonstrates **scenario analysis** by sweeping concurrency multipliers (0.5x, 1.0x, 1.5x) to show how pipeline cost changes under capacity constraints -- useful for evaluating maintenance windows, cost reduction, or burst provisioning.
+Every merge kicks off a pipeline of build, test, and deploy jobs, and each job can run on several kinds of runner — hosted Linux, Windows, or macOS machines, or self-hosted hardware — that differ in cost, capacity, and what they can execute. Picking the cheapest runner for each job while staying inside each runner's concurrency limit is a real budgeting problem for any platform team, and it gets harder the moment a runner goes offline for maintenance. This template answers two questions an operator actually asks: what is the least-cost way to schedule this pipeline, and when a runner outage makes the pipeline unschedulable, exactly which cap or runner is to blame.
 
-Finally, it shows **conflict analysis (infeasibility diagnosis)**. A maintenance outage takes two well-connected Linux runners offline, which funnels every high-CPU Linux job onto the one surviving large runner -- whose concurrency cap cannot hold them all, so the schedule is impossible. Rather than just reporting "infeasible," the outage solve requests `solve(conflict=True)`, which returns an **irreducible infeasible subsystem (IIS)**: the minimal set of rules that cannot all hold at once. The diagnosis names the *stranded jobs* and the *binding runner cap*, so an operator knows exactly which cap to raise or which runner to restore.
+**It uses RelationalAI's prescriptive reasoner to solve the assignment as a cost-minimizing optimization, then reruns it across capacity scenarios and, on an infeasible outage, reads back the minimal set of rules that cannot all hold at once — so the answer is not just "infeasible" but a named list of stranded jobs and the one binding runner cap.**
 
 ## Who this is for
 
-- DevOps engineers optimizing CI/CD runner costs
-- Platform teams sizing runner fleets for GitHub Actions or similar CI systems
-- Anyone learning resource assignment optimization with RelationalAI
+- DevOps and platform engineers optimizing CI/CD runner costs or sizing a runner fleet for GitHub Actions or a similar CI system.
+- Operations researchers exploring resource-assignment optimization and infeasibility diagnosis in RelationalAI.
+- **Assumed knowledge**: comfortable reading Python; the CI/CD, optimization, and conflict-analysis terms are explained as they come up. No prior RelationalAI experience is required to run it.
 
 ## What you'll build
 
-- A binary assignment model that maps each workflow job to a compatible runner type
-- Per-runner concurrency constraints scaled by a scenario parameter
-- Cost minimization objective (runner cost_per_minute * job estimated_minutes)
-- Scenario comparison showing cost impact of halving or increasing runner capacity
-- A maintenance-outage diagnosis that reads the IIS (stranded jobs + binding cap) back by entity key
+- A least-cost assignment plan mapping each workflow job to a compatible runner, built with the **prescriptive reasoner** as binary decision variables under an exactly-one-runner-per-job rule.
+- Per-runner concurrency constraints scaled by a scenario parameter, so the same model answers "what does half capacity cost?" or "what does burst capacity save?"
+- A scenario comparison across concurrency multipliers (half, full, and burst capacity) showing how pipeline cost moves with runner capacity.
+- A maintenance-outage diagnosis that requests an **irreducible infeasible subsystem (IIS)** and reads it back by entity key — the stranded jobs and the binding runner cap — so an operator knows precisely which cap to raise or which runner to restore.
 
 ## What's included
 
-- `cicd_runner_allocation.py` -- Main script with optimization and scenario analysis
-- `data/runners.csv` -- 8 runner types with CPU, memory, OS, cost, and concurrency limits
-- `data/workflows.csv` -- 20 CI/CD workflow jobs with resource requirements and durations
-- `data/compatibility.csv` -- Pre-computed runner-workflow compatibility pairs (OS + resource match)
-- `pyproject.toml` -- Python package configuration with dependencies
+- **Model**: three source concepts (`Runner`, `Workflow`, `Compatibility`) plus an `Assignment` decision concept, with a binary assignment variable, an assign-one-runner rule, a per-runner concurrency rule, and a cost-minimizing objective.
+- **Runner**: `cicd_runner_allocation.py` — a single Python script that runs the scenario sweep and the outage diagnosis end to end against a Snowflake-connected RAI account.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: 8 runner types, 20 workflow jobs, and their pre-computed compatibility pairs. See *Sample data* below.
+- **Outputs**: per-scenario solver status, total pipeline cost, and the runner-to-workflow assignment table printed to stdout; then the outage diagnosis naming the stranded jobs and the binding concurrency cap.
 
 ## Prerequisites
 
 ### Access
-- A Snowflake account that has the RAI Native App installed.
-- A Snowflake user with permissions to access the RAI Native App.
+
+- A Snowflake account with the RelationalAI Native App installed.
+- A Snowflake user with permissions to access the RelationalAI Native App.
 
 ### Tools
-- Python >= 3.10
-- RelationalAI Python SDK (`relationalai`) == 1.11.0
+
+- Python >= 3.10.
+- RelationalAI Python SDK (`relationalai == 1.11.0`).
 
 ## Quickstart
 
-1. Download ZIP:
+1. Download the template and extract it:
+
    ```bash
    curl -O https://docs.relational.ai/templates/zips/v1/cicd_runner_allocation.zip
    unzip cicd_runner_allocation.zip
    cd cicd_runner_allocation
    ```
+
    > [!TIP]
    > You can also download the template ZIP using the "Download ZIP" button at the top of this page.
 
-2. Create venv:
+2. Create a virtual environment and activate it:
+
    ```bash
    python -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade pip
    ```
 
-3. Install:
+3. Install dependencies:
+
    ```bash
    python -m pip install .
    ```
 
-4. Configure:
+4. Configure credentials:
+
    ```bash
    rai init
    ```
 
-5. Run:
+5. Run the template end to end:
+
    ```bash
    python cicd_runner_allocation.py
    ```
 
-6. Expected output (representative -- equal-cost runners may be swapped between tied optima, and the IIS may name a different six of the seven stranded jobs; the statuses, costs, and binding runner cap are stable):
-   ```text
-   Running scenario: concurrency_multiplier = 0.5
-   --------------------------------------------------
-     Status: OPTIMAL
-     Total pipeline cost: $10.18
-
-     Assignments:
-       macos-large (1 jobs): ios-testflight
-       macos-latest (2 jobs): build-mobile-ios, e2e-tests-safari
-       self-hosted-linux (4 jobs): e2e-tests-chrome, integration-tests, nightly-build, performance-tests
-       ubuntu-22.04 (2 jobs): build-api, release-notes
-       ubuntu-large (3 jobs): build-mobile-android, docker-build, unit-tests-api
-       ubuntu-latest (7 jobs): build-frontend, dependency-audit, deploy-production, deploy-staging, lint-and-format, security-scan, unit-tests-frontend
-       windows-latest (1 jobs): windows-installer
+6. Expected output (a few representative lines confirm a successful run):
 
+   ```text
    Running scenario: concurrency_multiplier = 1.0
    --------------------------------------------------
      Status: OPTIMAL
      Total pipeline cost: $9.62
 
-     Assignments:
-       macos-large (1 jobs): ios-testflight
-       macos-latest (2 jobs): build-mobile-ios, e2e-tests-safari
-       self-hosted-linux (8 jobs): build-api, build-mobile-android, docker-build, e2e-tests-chrome, integration-tests, nightly-build, performance-tests, unit-tests-api
-       ubuntu-22.04 (1 jobs): release-notes
-       ubuntu-latest (7 jobs): build-frontend, dependency-audit, deploy-production, deploy-staging, lint-and-format, security-scan, unit-tests-frontend
-       windows-latest (1 jobs): windows-installer
-
-   Running scenario: concurrency_multiplier = 1.5
-   --------------------------------------------------
-     Status: OPTIMAL
-     Total pipeline cost: $9.53
-
-     Assignments:
-       macos-large (1 jobs): ios-testflight
-       macos-latest (2 jobs): build-mobile-ios, e2e-tests-safari
-       self-hosted-linux (12 jobs): build-api, build-frontend, build-mobile-android, dependency-audit, docker-build, e2e-tests-chrome, integration-tests, nightly-build, performance-tests, security-scan, unit-tests-api, unit-tests-frontend
-       ubuntu-22.04 (2 jobs): deploy-production, release-notes
-       ubuntu-latest (2 jobs): deploy-staging, lint-and-format
-       windows-latest (1 jobs): windows-installer
-
    ==================================================
    Scenario Analysis Summary
    ==================================================
@@ -143,235 +112,125 @@ Finally, it shows **conflict analysis (infeasibility diagnosis)**. A maintenance
    ==================================================
    Maintenance outage: ubuntu-large, self-hosted-linux offline
    ==================================================
-   Solve result:
    • status: INFEASIBLE
-   • primal status: NO_SOLUTION
-   • dual status: INFEASIBILITY_CERTIFICATE
    • conflict status: CONFLICT_FOUND
-   ...
-
-   Stranded jobs (assign-one rule in conflict):
-               workflow
-   build-mobile-android
-           docker-build
-       e2e-tests-chrome
-      integration-tests
-      performance-tests
-         unit-tests-api
 
    Binding runner caps (concurrency rule in conflict):
           runner max_concurrent
    ubuntu-xlarge              5
-
-   To restore feasibility, relax one member of the conflict: bring ubuntu-large or
-   self-hosted-linux back online, or raise ubuntu-xlarge's concurrency cap. ...
    ```
 
-   At full capacity (1.0x), self-hosted-linux absorbs 8 of 20 jobs at
-   $0.005/min -- the cheapest runner. At half capacity (0.5x), its 4-job
-   cap forces overflow to ubuntu-large and ubuntu-22.04, raising cost by
-   6%. Burst mode (1.5x) pushes 12 jobs to self-hosted, saving another
-   $0.09 by pulling four more low-CPU jobs off the pricier ubuntu runners
-   (the high-CPU jobs already fit on self-hosted at 1.0x). (How the cheap,
-   low-CPU jobs split between the two equal-cost ubuntu runners is one of several
-   tied optima -- a different HiGHS build may place them differently at the same
-   total cost.)
-
-   **The maintenance outage** is infeasible: with `ubuntu-large` and
-   `self-hosted-linux` offline, the seven high-CPU Linux jobs can only run on
-   `ubuntu-xlarge` (cap 5). `solve(conflict=True)` returns the IIS -- six of the
-   seven stranded jobs plus the `ubuntu-xlarge` concurrency rule (which six is
-   solver-dependent, since any six already exceed the cap). The diagnosis points an
-   operator straight at the fix: restore a runner or raise that one cap.
+   Equal-cost runners may be swapped between tied optima, and the IIS may name a different six of the seven stranded jobs; the statuses, costs, and the binding runner cap are stable. The full printout and a step-by-step walkthrough are in `runbook.md`.
 
 ## Template structure
 
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── cicd_runner_allocation.py
-└── data/
-    ├── runners.csv
-    ├── workflows.csv
-    └── compatibility.csv
+cicd_runner_allocation/
+  cicd_runner_allocation.py       # Main script (scenario sweep + outage diagnosis)
+  data/
+    runners.csv                   # 8 runner types (specs, cost, concurrency cap)
+    workflows.csv                 # 20 CI/CD jobs (requirements, duration)
+    compatibility.csv             # pre-computed (workflow, runner) compatible pairs
+  README.md                       # this file
+  runbook.md                      # analyst-facing paste-testable walkthrough
+  pyproject.toml                  # dependencies
 ```
 
-## How it works
+**Start here**: run `python cicd_runner_allocation.py` for the full scenario sweep and outage diagnosis end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-This section walks through the highlights in `cicd_runner_allocation.py`.
+## Sample data
 
-### Define concepts and load CSV data
+The bundled data is synthetic and illustrative — designed to teach the reasoning flow on a Snowflake-connected RAI account, not to match a specific team's CI fleet. The three CSVs load into the three source concepts described under *Model overview*.
 
-The model defines three concepts. `Runner` represents CI/CD runner types with resource specs and cost:
+- **`runners.csv`** (8 rows) — CI/CD runner types (hosted Linux, Windows, macOS, and self-hosted), each with CPU count, memory, operating system, per-minute cost, and a concurrency cap. `self-hosted-linux` is the cheapest at `$0.005/min`; `ubuntu-xlarge` is the only surviving high-CPU Linux runner in the outage scenario, with a concurrency cap of 5.
+- **`workflows.csv`** (20 rows) — CI/CD jobs (builds, tests, deploys, and packaging) with a triggering event, required operating system, minimum CPU and memory, and an estimated duration in minutes. Seven jobs are high-CPU Linux jobs (`min_cpu` at least 4), the set that funnels onto one runner during the outage.
+- **`compatibility.csv`** — pre-computed `(workflow_id, runner_id)` pairs, one per runner that meets a workflow's operating-system and resource requirements. These pairs define the assignment decision space: only compatible pairs can be chosen.
 
-```python
-Runner = model.Concept("Runner", identify_by={"runner_id": Integer})
-Runner.name = model.Property(f"{Runner} has {String:runner_name}")
-Runner.os = model.Property(f"{Runner} has {String:runner_os}")
-Runner.cpu = model.Property(f"{Runner} has {Integer:cpu}")
-Runner.memory_gb = model.Property(f"{Runner} has {Integer:memory_gb}")
-Runner.cost_per_minute = model.Property(f"{Runner} has {Float:cost_per_minute}")
-Runner.max_concurrent = model.Property(f"{Runner} has {Integer:max_concurrent}")
-```
+## Model overview
 
-`Workflow` represents CI/CD jobs with resource requirements:
-
-```python
-Workflow = model.Concept("Workflow", identify_by={"workflow_id": Integer})
-Workflow.name = model.Property(f"{Workflow} has {String:workflow_name}")
-Workflow.event = model.Property(f"{Workflow} has {String:workflow_event}")
-Workflow.required_os = model.Property(f"{Workflow} has {String:required_os}")
-Workflow.min_cpu = model.Property(f"{Workflow} has {Integer:min_cpu}")
-Workflow.min_memory_gb = model.Property(f"{Workflow} has {Integer:min_memory_gb}")
-Workflow.estimated_minutes = model.Property(
-    f"{Workflow} has {Integer:estimated_minutes}"
-)
-```
+The model has three source concepts loaded from the CSVs plus one decision concept derived from them.
 
-`Compatibility` links workflows to runners that meet their OS and resource requirements. `Assignment` is the decision concept -- only compatible (workflow, runner) pairs exist:
+- **Key entities**: `Runner`, `Workflow`, `Compatibility` (the eligible pairings), and `Assignment` (the decision — one binary variable per compatible pair).
+- **Primary identifiers**: integer `runner_id` on `Runner` and `workflow_id` on `Workflow`; `Compatibility` and `Assignment` are each identified by the composite `(workflow, runner)` pair.
+- **Important invariants**: `cost_per_minute`, CPU, memory, durations, and concurrency caps are non-negative; each workflow is assigned to exactly one runner; each runner's assigned job count stays within its concurrency cap scaled by the scenario multiplier; assignment variables are binary.
 
-```python
-Compatibility = model.Concept(
-    "Compatibility", identify_by={"workflow": Workflow, "runner": Runner}
-)
+`Compatibility` is a standalone relation, not a set of properties on `Runner` or `Workflow`: it enumerates which runners can execute which workflows (operating-system and resource match), and it seeds the `Assignment` decision space — `Assignment` is defined over exactly the `Compatibility` pairs.
 
-Assignment = model.Concept(
-    "Assignment", identify_by={"workflow": Workflow, "runner": Runner}
-)
-Assignment.x_assigned = model.Property(f"{Assignment} assigned {Float:x_assigned}")
-model.define(
-    Assignment.new(workflow=Compatibility.workflow, runner=Compatibility.runner)
-)
-```
-
-### Define decision variables, constraints, and objective
+For the full concept and property definitions, see `cicd_runner_allocation.py`; `runbook.md` builds them step by step with the RAI skills.
 
-Each assignment is a binary variable -- assign this workflow to this runner or not:
-
-```python
-problem.solve_for(
-    Assignment.x_assigned,
-    type="bin",
-    name=["assign", Assignment.workflow.name, Assignment.runner.name],
-)
-```
+## How it works
 
-Two constraints enforce feasibility. Each is **captured as a handle**, **named per entity** (a readable label), and declared with **`keyed_by`** -- the entity key its conflict membership reads back through if the model turns out infeasible. First, each workflow must be assigned to exactly one runner:
+The script defines the source concepts, seeds the decision space, adds the constraints and objective, sweeps the capacity scenarios, and finally diagnoses a maintenance outage.
 
-```python
-assign_one = problem.satisfy(
-    model.require(
-        sum(AssignRef.x_assigned).where(AssignRef.workflow == Workflow).per(Workflow) == 1
-    ),
-    name=["assign_one", Workflow.name],
-    keyed_by={"workflow": Workflow},
-)
-```
+### Define concepts and load CSV data
 
-Second, the number of workflows assigned to each runner cannot exceed its concurrency limit, scaled by the scenario multiplier:
-
-```python
-conc = problem.satisfy(
-    model.require(
-        sum(AssignRef.x_assigned).where(AssignRef.runner == Runner).per(Runner)
-        <= concurrency_multiplier * Runner.max_concurrent
-    ),
-    name=["concurrency", Runner.name],
-    keyed_by={"runner": Runner},
-)
-```
+The model defines three source concepts — `Runner` (runner types with resource specs and cost), `Workflow` (CI/CD jobs with resource requirements), and `Compatibility` (which runners can execute which workflows). `Assignment` is the decision concept, defined over exactly the compatible `(workflow, runner)` pairs.
 
-The objective minimizes total pipeline cost -- the sum of (runner cost per minute * job duration) across all assignments:
+### Define decision variables, constraints, and objective
 
-```python
-problem.minimize(
-    sum(
-        Assignment.x_assigned
-        * Assignment.runner.cost_per_minute
-        * Assignment.workflow.estimated_minutes
-    )
-)
-```
+Each assignment is a binary variable — assign this workflow to this runner or not. Two constraints enforce feasibility; each is captured as a handle, named per entity (a readable label), and declared with `keyed_by` — the entity key its conflict membership reads back through if the model turns out infeasible. First, each workflow must be assigned to exactly one runner. Second, the number of workflows assigned to each runner cannot exceed its concurrency limit, scaled by the scenario multiplier. The objective minimizes total pipeline cost — the sum of runner cost per minute times job duration across all assignments.
 
 ### Solve with scenario analysis
 
-The script loops over three concurrency multipliers (0.5x, 1.0x, 1.5x), creating a fresh Problem for each. This reveals the cost of operating at reduced capacity (maintenance window) versus full or burst capacity:
+The script loops over three concurrency multipliers (0.5x, 1.0x, 1.5x), creating a fresh Problem for each. This reveals the cost of operating at reduced capacity (maintenance window) versus full or burst capacity.
 
-```python
-SCENARIO_VALUES = [0.5, 1.0, 1.5]
+At full capacity (1.0x), `self-hosted-linux` absorbs 8 of 20 jobs at `$0.005/min` — the cheapest runner. At half capacity (0.5x), its 4-job cap forces overflow to `ubuntu-large` and `ubuntu-22.04`, raising cost by 6%. Burst mode (1.5x) pushes 12 jobs to self-hosted, saving another `$0.09` by pulling four more low-CPU jobs off the pricier ubuntu runners (the high-CPU jobs already fit on self-hosted at 1.0x). How the cheap, low-CPU jobs split between the two equal-cost ubuntu runners is one of several tied optima — a different HiGHS build may place them differently at the same total cost. A summary table then compares status and cost across the scenarios.
 
-for multiplier in SCENARIO_VALUES:
-    alloc = solve_allocation(multiplier)
-```
+### Diagnose a maintenance outage with conflict analysis
 
-After all scenarios, a summary table compares status and cost:
+The final section models a maintenance outage: `ubuntu-large` and `self-hosted-linux` go offline (their assignments are dropped with a filter). Every high-CPU Linux job (`min_cpu` at least 4) is compatible only with runners in `{ubuntu-large, ubuntu-xlarge, self-hosted-linux}` (the two heaviest jobs with just the latter two), so with two of those three down, all seven funnel onto `ubuntu-xlarge` — whose concurrency cap of 5 cannot hold them. The solve requests a conflict diagnosis.
 
-```python
-for r in scenario_results:
-    print(f"  {SCENARIO_PARAM}={r['scenario']}: "
-          f"{r['status']}, cost=${r['objective']:.2f}")
-```
+A `conflict_status` field gates whether an irreducible infeasible subsystem (IIS) is available: on `CONFLICT_FOUND` the script reads back the stranded jobs and binding cap; otherwise it reports the status rather than reading an IIS that is not there. (The template's own branch raises in that case, because its outage is infeasible by construction, but code where infeasibility is not guaranteed should report and move on.)
 
-### Diagnose a maintenance outage with conflict analysis
+Each constraint's declared key gives it an entity back-pointer (`assign_one.workflow`, `conc.runner`), mirroring the variable's automatic back-pointer, so the conflict reads back as the actual stranded jobs and the binding runner cap, joined by key — no rule-name parsing.
 
-The final section models a maintenance outage: `ubuntu-large` and `self-hosted-linux` go offline (their assignments are dropped with a `where=` filter). Every high-CPU Linux job (`min_cpu >= 4`) is compatible only with runners in `{ubuntu-large, ubuntu-xlarge, self-hosted-linux}` (the two heaviest jobs with just the latter two), so with two of those three down, all seven funnel onto `ubuntu-xlarge` -- whose concurrency cap of 5 cannot hold them. The solve requests a conflict diagnosis:
+The IIS is minimal: it names six of the seven high-CPU jobs (any six already exceed the cap of five, so which six is solver-dependent) plus the `ubuntu-xlarge` concurrency rule. To restore feasibility, relax one member — bring a runner back online or raise the cap. Because all seven jobs share the one survivor, lift the cap enough for all of them (or restore a runner) and re-solve to confirm; clearing a single job only resolves that one row of the conflict.
 
-```python
-outage = solve_allocation(1.0, offline_runners=["ubuntu-large", "self-hosted-linux"], conflict=True)
+See `cicd_runner_allocation.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
-assert outage.si.conflict is True
-assert outage.si.termination_status in ("INFEASIBLE", "INFEASIBLE_OR_UNBOUNDED")
+> [!NOTE]
+> Conflict analysis works for mixed-integer models like this one (unlike sensitivity analysis, which needs a linear or quadratic program). It requires no objective — it diagnoses feasibility. Request `conflict=True` on the solve whose infeasibility you want to explain — up front, or on a fresh build: a `Problem` already solved without it cannot add it on a re-solve.
 
-# conflict_status gates whether an IIS is available -- dispatch on it.
-if outage.si.conflict_status == "CONFLICT_FOUND":
-    ...  # read the stranded jobs and the binding cap (below)
-else:
-    # NO_CONFLICT_EXISTS (the model was feasible) or NOT_SUPPORTED / FAILED (this solver
-    # build produced no IIS, e.g. needs HiGHS >= 1.13) -- report the status, don't read it.
-    print(f"No IIS to inspect: {outage.si.conflict_status}")
-```
+## Customize this template
 
-(The template's own `else` branch raises instead of printing: its outage is infeasible by construction, so a missing IIS there is a regression. The `print` form above is the one to copy when infeasibility is not guaranteed.)
+Focus on the first changes most users will make.
 
-`in_conflict` is a bare predicate on each constraint instance -- true when the solver reports that instance in the conflict (it collapses the solver's `IN_CONFLICT` and `MAYBE_IN_CONFLICT` into one membership). Each constraint's declared key gives it an **entity back-pointer** (`assign_one.workflow`, `conc.runner`), mirroring the variable's automatic back-pointer, so the conflict reads back as the actual stranded jobs and the binding runner cap, joined by KEY -- no rule-name parsing:
+### Use your own data
 
-```python
-# Stranded jobs (their assign-one rule is in the conflict):
-model.select(outage.assign_one.workflow.name).where(outage.assign_one.in_conflict).inspect()
-# The binding runner cap (its concurrency rule is in the conflict):
-model.select(outage.conc.runner.name, outage.conc.runner.max_concurrent).where(
-    outage.conc.in_conflict
-).inspect()
-```
+- Replace the CSVs in `data/` with your own; keep the column headers listed in *Sample data* (`runners.csv`, `workflows.csv`, `compatibility.csv`).
+- `compatibility.csv` must hold one `(workflow_id, runner_id)` row per runner that can execute a workflow (operating-system and resource match). If a workflow has no compatible runner, it cannot be assigned and the model becomes infeasible — see *Troubleshooting*.
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)` calls.
 
-(`.inspect()` prints the rows for a quick look; the script materializes the same selects as DataFrames with `.to_df()` for its printed report and assertions.)
+### Tune parameters
 
-The IIS is minimal: it names **six of the seven** high-CPU jobs (any six already exceed the cap of five, so which six is solver-dependent) plus the `ubuntu-xlarge` concurrency rule. To restore feasibility, relax one member -- bring a runner back online or raise the cap. Because all seven jobs share the one survivor, lift the cap enough for all of them (or restore a runner) and re-solve to confirm; clearing a single job only resolves that one row of the conflict.
+- **Concurrency scenarios** — `SCENARIO_VALUES` (default `[0.5, 1.0, 1.5]`) is the list of concurrency multipliers swept; each scales every runner's `max_concurrent`.
+- **Per-runner caps** — change `max_concurrent` in `runners.csv` to model a different fleet size or capacity policy.
+- **Solve budget** — the solve uses `time_limit_sec=60`; raise it for larger fleets.
 
-> [!NOTE]
-> Conflict analysis works for mixed-integer models like this one (unlike sensitivity analysis, which needs an LP/QP). It requires no objective -- it diagnoses feasibility. Request `conflict=True` on the solve whose infeasibility you want to explain -- up front, or on a fresh build: a `Problem` already solved without it cannot add it on a re-solve.
+### Extend the model
 
-## Customize this template
+- **Add runners** — extend `runners.csv` with new runner types (for example, GPU runners for machine-learning workflows) and their compatibility rows.
+- **Weight by priority** — add a priority column to `workflows.csv` and fold it into the objective to prefer assigning critical jobs to faster runners.
+- **Model time windows** — add time-slot concepts to schedule across discrete time periods, not just assignment.
 
-- **Add runners**: Extend `runners.csv` with new runner types (e.g., GPU runners for ML workflows).
-- **Adjust concurrency**: Change `max_concurrent` in `runners.csv` or modify `SCENARIO_VALUES` to test different capacity levels.
-- **Weight by priority**: Add a priority column to `workflows.csv` and incorporate it into the objective to prefer assigning critical jobs to faster runners.
-- **Time windows**: Add time slot concepts to model scheduling across discrete time periods, not just assignment.
-- **Real data**: Replace CSVs with queries against your CI/CD platform's API or data warehouse.
+### Scale up / productionize
+
+- Replace the `data/` CSV bundle with queries against your CI/CD platform's API or data warehouse.
+- The model scales to whatever fits the prescriptive engine's solve budget; raise `time_limit_sec` and the concurrency caps together as the fleet grows.
+- Pin dependencies (the template pins `relationalai == 1.11.0`) for reproducible runs across environments.
 
 ## Troubleshooting
 
 <details>
 <summary>Problem is infeasible</summary>
 
-The concurrency limits are too tight for the number of workflows. Rather than guess, request a conflict diagnosis -- `solve(conflict=True)` returns the irreducible infeasible subsystem (the stranded jobs and the binding runner cap), as shown in the maintenance-outage section. Then increase `max_concurrent` for the named runner in `runners.csv`, reduce the number of workflows competing for it, or raise the concurrency multiplier.
+The concurrency limits are too tight for the number of workflows, or a workflow has no compatible runner. Rather than guess, request a conflict diagnosis — `solve(conflict=True)` returns the irreducible infeasible subsystem (the stranded jobs and the binding runner cap), as shown in the maintenance-outage section. Then increase `max_concurrent` for the named runner in `runners.csv`, reduce the number of workflows competing for it, or raise the concurrency multiplier.
 </details>
 
 <details>
 <summary>rai init fails or connection errors</summary>
 
-Ensure your Snowflake credentials are configured correctly and that the RAI Native App is installed on your account. Run `rai init` again and verify the connection settings.
+Ensure your Snowflake credentials are configured correctly and that the RelationalAI Native App is installed on your account. Run `rai init` again and verify the connection settings.
 </details>
 
 <details>
@@ -383,5 +242,24 @@ Make sure you activated the virtual environment and ran `python -m pip install .
 <details>
 <summary>All workflows assigned to the same runner</summary>
 
-This is expected if one runner is cheapest and has enough concurrency. Check that `compatibility.csv` correctly restricts which runners can handle each workflow's OS and resource requirements.
+This is expected if one runner is cheapest and has enough concurrency. Check that `compatibility.csv` correctly restricts which runners can handle each workflow's operating-system and resource requirements.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [RelationalAI documentation](https://docs.relational.ai/) — concepts, properties, and the semantic model that this template builds on.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives used here.
+- [Conflict analysis (IIS)](https://docs.relational.ai/) — diagnosing infeasibility and reading back an irreducible infeasible subsystem by entity key.
+
+### CLI / SDK guides
+
+- [RelationalAI CLI and setup](https://docs.relational.ai/) — `rai init`, credentials, and connecting to your Snowflake account.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/commercial_underwriting/README.md b/v1/commercial_underwriting/README.md
index e950231d..3c660dc3 100644
--- a/v1/commercial_underwriting/README.md
+++ b/v1/commercial_underwriting/README.md
@@ -15,19 +15,13 @@ tags:
   - Insurance to Value
 ---
 
-# Commercial Underwriting
-
 ## What this template is for
 
-This template uses **Rules-based** reasoning to underwrite a portfolio of commercial property/casualty submissions. It demonstrates how to express real-world insurance rules as declarative derived properties on a four-level hierarchy:
+Commercial property and casualty carriers triage every submission against a book of underwriting rules — insurance-to-value adequacy, fire-protection class, year-built floors, occupancy restrictions, industry appetite, operating history — and the answer for each account depends on the worst thing found anywhere beneath it. One old building or one restricted industry can decline an otherwise clean insured. Encoding that judgment as maintainable, auditable logic (rather than a tangle of procedural if-checks) is the hard part.
 
-```text
-InsuredEntity -> Policy -> Location -> Coverage
-```
+This template shows how to express that rulebook as declarative logic on a four-level hierarchy of insured entity, policy, location, and coverage, so lower-level eligibility checks roll up automatically into a per-entity risk tier. The result is an underwriting view that says not just which tier each account lands in, but exactly which rule put it there.
 
-Each level carries its own eligibility checks. A coverage is checked for insurance-to-value (ITV) adequacy. A location is checked for fire-protection class, year-built, and occupancy class. An insured entity is checked for industry and operating history. Then those flags roll up: any decline factor at any level pushes the entity to the **Decline** tier; marginal factors push it to **Non-Standard**; clean entities are **Standard**, and clean long-tenured entities with the highest fire-protection grades are **Preferred**.
-
-Everything is declarative — no procedural rule chains, no explicit ordering. PyRel resolves dependencies automatically. Rules at lower levels feed entity-level rollup rules, which in turn feed the tier classification.
+**The reasoning approach is rules-based: every eligibility check and rollup is a declarative derived property, and PyRel resolves the dependencies between levels automatically — no procedural rule chains, no explicit ordering.**
 
 ## Who this is for
 
@@ -45,12 +39,11 @@ Everything is declarative — no procedural rule chains, no explicit ordering. P
 
 ## What's included
 
-- `commercial_underwriting.py` — main script (single end-to-end run)
-- `data/insured_entities.csv` — 8 insured businesses across 5 industries
-- `data/policies.csv` — 8 commercial property policies (one per insured)
-- `data/locations.csv` — 11 scheduled locations across the policies (some entities have multiple)
-- `data/coverages.csv` — 33 coverage lines (BUILDING / BUSINESS_PERSONAL_PROPERTY / BUSINESS_INTERRUPTION at every location)
-- `pyproject.toml` — Python package configuration with dependencies
+- **Model**: the four-level `InsuredEntity` / `Policy` / `Location` / `Coverage` ontology, eight lower-level eligibility rules, two entity-level rollup rules (decline factors, marginal factors), and four mutually exclusive risk-tier subtype concepts — all as declarative derived Relationships.
+- **Runner**: `commercial_underwriting.py` — a single Python script that loads the CSVs, applies the rules, and prints results end to end.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: four CSVs under `data/` — 8 insured businesses across 5 industries (`insured_entities.csv`), 8 commercial property policies one per insured (`policies.csv`), 11 scheduled locations (`locations.csv`), and 33 coverage lines at every location (`coverages.csv`).
+- **Outputs**: the printed eligibility flag matrix, the final per-entity tier classification, and the premium-by-tier business rollup.
 
 ## Prerequisites
 
@@ -161,7 +154,7 @@ Everything is declarative — no procedural rule chains, no explicit ordering. P
     └── coverages.csv               # coverage lines at each location
 ```
 
-**Start here:** `python commercial_underwriting.py`.
+**Start here:** run `python commercial_underwriting.py` for the full run end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Sample data
 
@@ -180,147 +173,23 @@ The eight insureds are designed so each tier is represented and every rule fires
 
 ## Model overview
 
-### InsuredEntity
-
-The named insured business at the top of the hierarchy.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | Integer | Yes | |
-| `name` | String | No | |
-| `industry_code` | String | No | Drives industry-based rules (RESTRICTED, MARGINAL) |
-| `years_in_business` | Integer | No | Drives the insufficient-history and preferred-eligibility rules |
-| `annual_revenue` | Float | No | Carried for reporting; not used by current rules |
-
-### Policy
-
-A commercial property policy bound to one insured entity. Acts as the connector between an entity and its scheduled locations.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | Integer | Yes | |
-| `insured_entity` | InsuredEntity | No | Relationship to the named insured |
-| `policy_type` | String | No | E.g., `COMMERCIAL_PROPERTY` |
-| `effective_date` | String | No | ISO date |
-| `total_premium` | Float | No | Used for the premium-by-tier rollup |
-
-### Location
+- **Key entities**: `InsuredEntity`, `Policy`, `Location`, and `Coverage` — a four-level property/casualty hierarchy, plus four mutually exclusive risk-tier subtype concepts (`RiskTier_Decline`, `RiskTier_NonStandard`, `RiskTier_Standard`, `RiskTier_Preferred`) that extend `InsuredEntity`.
+- **Primary identifiers**: each level has an integer `id`; the hierarchy is threaded by relationships (`Policy.insured_entity`, `Location.policy`, `Coverage.location`) rather than by shared keys.
+- **Important invariants**: every policy belongs to exactly one insured entity, every location to one policy, every coverage to one location; the ITV check applies to `BUILDING` coverages only; the four risk tiers partition the `InsuredEntity` set (each entity lands in exactly one).
 
-A physical location/building scheduled on a policy.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | Integer | Yes | |
-| `policy` | Policy | No | Relationship to the parent policy |
-| `address` | String | No | |
-| `occupancy_class` | String | No | Drives the high-risk-occupancy rule |
-| `year_built` | Integer | No | Drives the old-construction rule |
-| `square_feet` | Integer | No | Carried for reporting |
-| `fire_protection_class` | Integer | No | ISO Public Protection Class 1-10; drives multiple rules |
-| `replacement_value` | Float | No | The denominator for the ITV calculation |
-
-### Coverage
-
-A coverage line scheduled on a location.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | Integer | Yes | |
-| `location` | Location | No | Relationship to the parent location |
-| `coverage_type` | String | No | One of `BUILDING`, `BUSINESS_PERSONAL_PROPERTY`, `BUSINESS_INTERRUPTION` |
-| `coverage_limit` | Float | No | Drives the ITV rule (BUILDING coverages only) |
-| `deductible` | Float | No | Carried for reporting |
+For the full concept and property definitions, see `commercial_underwriting.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
-### 1. Lower-level eligibility flags
-
-Boolean flags as unary `Relationship` declarations. Each rule is a single declarative `where(...).define(...)`.
-
-```python
-Location.has_poor_fire_protection = model.Relationship(
-    f"{Location} has poor fire protection"
-)
-model.where(
-    Location.fire_protection_class > MAX_FP_CLASS_FOR_ELIGIBILITY,
-).define(Location.has_poor_fire_protection())
-```
-
-For list-based membership (industry, occupancy class), the same flag is defined once per list member — PyRel collects the union of matching rows:
-
-```python
-for occ in HIGH_RISK_OCCUPANCIES:
-    model.where(Location.occupancy_class == occ).define(
-        Location.has_high_risk_occupancy()
-    )
-```
-
-The ITV check joins across two concept levels in a single `where()`:
+Rules run at three altitudes on the hierarchy and feed each other. A coverage is checked for insurance-to-value (ITV) adequacy; a location for fire-protection class, year-built, and occupancy class; an insured entity for industry and operating history. Each check is a declarative flag: a single `where(...).define(...)`, defined once per member for list-based checks (industry, occupancy) so PyRel unions the matches, and joining across concept levels in one clause for the ITV check.
 
-```python
-Coverage.is_underinsured = model.Relationship(f"{Coverage} is underinsured")
-model.where(
-    Coverage.coverage_type == "BUILDING",
-    Coverage.coverage_limit < ITV_THRESHOLD * Coverage.location.replacement_value,
-).define(Coverage.is_underinsured())
-```
-
-### 2. Entity-level rollups
-
-Rollup rules traverse the four-level chain `InsuredEntity → Policy → Location → Coverage` to declare an entity-level flag if any descendant satisfies the lower-level rule:
-
-```python
-InsuredEntity.has_underinsured_coverage = model.Relationship(
-    f"{InsuredEntity} has underinsured coverage"
-)
-model.where(
-    Policy.insured_entity(InsuredEntity),
-    Location.policy(Policy),
-    Coverage.location(Location),
-    Coverage.is_underinsured(),
-).define(InsuredEntity.has_underinsured_coverage())
-```
-
-A single OR-style aggregator flag (`has_decline_factor`, `has_marginal_factor`) is then defined four times — once per contributing flag — using PyRel's set-union semantics for relationships:
-
-```python
-InsuredEntity.has_decline_factor = model.Relationship(
-    f"{InsuredEntity} has any decline factor"
-)
-model.where(InsuredEntity.has_restricted_industry()).define(InsuredEntity.has_decline_factor())
-model.where(InsuredEntity.has_insufficient_history()).define(InsuredEntity.has_decline_factor())
-model.where(InsuredEntity.has_unprotected_location()).define(InsuredEntity.has_decline_factor())
-model.where(InsuredEntity.has_old_construction_location()).define(InsuredEntity.has_decline_factor())
-```
-
-### 3. Risk-tier classification via subtype concepts
-
-The four tiers are typed sub-concepts that extend `InsuredEntity`. Each rule populates exactly one of them, and the conditions are written so the four sets partition the `InsuredEntity` set:
-
-```python
-RiskTier_Decline = model.Concept("RiskTier_Decline", extends=[InsuredEntity])
-RiskTier_NonStandard = model.Concept("RiskTier_NonStandard", extends=[InsuredEntity])
-RiskTier_Standard = model.Concept("RiskTier_Standard", extends=[InsuredEntity])
-RiskTier_Preferred = model.Concept("RiskTier_Preferred", extends=[InsuredEntity])
-
-model.where(
-    InsuredEntity.has_decline_factor(),
-).define(RiskTier_Decline(InsuredEntity))
-
-model.where(
-    model.not_(InsuredEntity.has_decline_factor()),
-    InsuredEntity.has_marginal_factor(),
-).define(RiskTier_NonStandard(InsuredEntity))
+Those lower-level flags then roll up. Entity-level rollup rules traverse the `InsuredEntity → Policy → Location → Coverage` chain to raise a flag on the entity if any descendant matches, and an OR-style aggregator (`has_decline_factor`, `has_marginal_factor`) unions the contributing flags via PyRel's set-union semantics. The tiers themselves are typed sub-concepts that extend `InsuredEntity`: any decline factor pushes the entity to **Decline**, marginal factors to **Non-Standard**, clean entities are **Standard**, and clean long-tenured entities with the highest fire-protection grades are **Preferred**. The tier conditions are written with explicit exclusions so the four sets partition the `InsuredEntity` set — Preferred being a tightened subset of "no decline, no marginal." Everything is declarative: lower-level rules feed entity-level rollups, which feed the tier classification, and PyRel resolves the ordering.
 
-model.where(
-    model.not_(InsuredEntity.has_decline_factor()),
-    model.not_(InsuredEntity.has_marginal_factor()),
-    model.not_(InsuredEntity.has_non_preferred_location()),
-    InsuredEntity.years_in_business >= PREFERRED_MIN_YEARS,
-).define(RiskTier_Preferred(InsuredEntity))
+```text
+InsuredEntity -> Policy -> Location -> Coverage
 ```
 
-The script then post-processes by subtracting the Preferred set from the Standard set, since Preferred is a tightened subset of "no decline, no marginal."
+See `commercial_underwriting.py` for the implementation and `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Customize this template
 
@@ -351,6 +220,12 @@ All thresholds are at the top of the script under `# Configure inputs`:
 - **Pricing factor derivation.** Currently the template only classifies risk tier. Add a derived `Property` (not `Relationship`) on `Policy` for `pricing_factor`, computed from a sum of additive multipliers per matched flag. See the `derivation` rule pattern in the [`shipment_compliance`](../shipment_compliance/) template.
 - **Subline expansion.** Add `GENERAL_LIABILITY`, `UMBRELLA`, `WORKERS_COMP` policies alongside `COMMERCIAL_PROPERTY`. The four-level structure carries over directly.
 
+### Scale up / productionize
+
+- **Point at Snowflake tables.** Swap the CSV `model.data(...)` calls for `model.Table(...)` references to your submission tables; the ontology, rules, and tier classification are unchanged. Size the RAI engine to the submission volume — rules-based classification is lightweight, so a small engine handles large books.
+- **Schedule triage runs.** Wire the script into your submission-intake pipeline (nightly batch or on-submission trigger) so every new account is scored as it arrives, and persist the per-entity tier and flag matrix for downstream underwriting review.
+- **Pin dependencies for reproducibility.** Keep the `relationalai` version pinned in `pyproject.toml` so rule outcomes stay stable across runs, and version-control your threshold constants (top of the script) as auditable underwriting parameters.
+
 ## Troubleshooting
 
 <details>
@@ -383,6 +258,26 @@ All thresholds are at the top of the script under `# Configure inputs`:
   Decline-factor membership is the union of all `has_decline_factor()` definitions. Add a new flag rule on the appropriate level (e.g., `Location.has_seismic_exposure`), add an entity-level rollup (`InsuredEntity.has_seismic_exposure_location`), then add one more `model.where(InsuredEntity.has_seismic_exposure_location()).define(InsuredEntity.has_decline_factor())` line. PyRel automatically unions all definitions of the same Relationship.
 </details>
 
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 modeling](https://docs.relational.ai/) — concepts, properties, and derived Relationships, the building blocks this template uses at every level.
+- [Rules-based reasoning](https://docs.relational.ai/) — authoring declarative business rules and letting the engine resolve their dependencies.
+
+### Language / modeling reference
+
+- [Derived Relationships and set-union semantics](https://docs.relational.ai/) — how defining the same Relationship multiple times unions the matches, the pattern behind the OR-style rollups.
+- [Subtype concepts (`extends`)](https://docs.relational.ai/) — modeling mutually exclusive risk tiers as sub-concepts of `InsuredEntity`.
+
+### CLI / SDK guides
+
+- [`rai init` and `raiconfig.yaml`](https://docs.relational.ai/) — connecting the template to your RelationalAI account.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
+
 ## Related templates
 
 - [`shipment_compliance`](../shipment_compliance/) — flat rules-based template (single-level entity, no hierarchy)
diff --git a/v1/cybersecurity-attack-paths/README.md b/v1/cybersecurity-attack-paths/README.md
index 049dee03..f6c74273 100644
--- a/v1/cybersecurity-attack-paths/README.md
+++ b/v1/cybersecurity-attack-paths/README.md
@@ -31,16 +31,16 @@ This template enumerates multi-step attack paths across an enterprise asset grap
 
 ## What you'll build
 
-- Load a 12-asset enterprise estate (perimeter hosts, internal services and workstations, restricted crown jewels) and 16 directed attack steps from CSV
-- Model three distinct attacker techniques as separate edges between assets: vulnerability exploitation, credential reuse, and network pivoting
-- Enumerate kill-chain attack paths with RelationalAI multi-relationship path enumeration, a multi-edge pattern that fixes the technique order
-- Run a point query that lists every route between one named entry point and one named crown jewel
-- Rank the kill-chains by the asset exposure summed along each one
-- Persist which assets lie on a crown-jewel attack path back onto the ontology
+- An enterprise asset graph (perimeter hosts, internal services and workstations, restricted crown jewels) with three distinct attacker techniques — vulnerability exploitation, credential reuse, and network pivoting — modeled as separate directed edges between assets
+- An enumerated set of kill-chain attack paths, produced by RelationalAI multi-relationship path enumeration (a multi-edge pattern that fixes the technique order)
+- A point-query result listing every route between one named entry point and one named crown jewel over the technique-agnostic union edge
+- A ranking of the kill-chains by the asset exposure summed along each one
+- An `Asset.on_attack_path` flag persisted back onto the ontology, marking every asset that lies on a crown-jewel-reaching chain
 
 ## What's included
 
 - **Self-contained script**: `cybersecurity_attack_paths.py` runs the full analysis end-to-end
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Data**: `data/assets.csv` (12 assets) and `data/attack_steps.csv` (16 technique-tagged edges)
 
 ## Prerequisites
@@ -131,30 +131,7 @@ cybersecurity-attack-paths/
 - **Primary identifiers**: `Asset` by `id`.
 - **Important invariants**: the three technique edges are directed (`src` reaches `dst`, not the reverse); `internet_facing` and `crown_jewel` are `yes`/`no` flags that pin the kill-chain endpoints; `on_attack_path` is set only on assets that lie on a crown-jewel-reaching chain.
 
-### `Asset`
-
-A host, service, or account in the enterprise estate. Its flags mark where attack paths can start (`internet_facing`) and end (`crown_jewel`), and `on_attack_path` is persisted back onto the asset after the kill-chains are enumerated.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | string | Yes | Loaded from `data/assets.csv` |
-| `name` | string | No | Human-readable asset name |
-| `zone` | string | No | `dmz`, `internal`, or `restricted` |
-| `internet_facing` | string | No | `yes`/`no`; a kill-chain source must be `yes` |
-| `crown_jewel` | string | No | `yes`/`no`; a kill-chain destination must be `yes` |
-| `exposure_score` | int | No | Per-asset risk score summed along each chain for ranking |
-| `on_attack_path` | string | No | `yes`, persisted onto assets that lie on a crown-jewel chain |
-
-### Relationships
-
-Four directed self-relationships between assets. The first three are the technique-tagged kill-chain edges; `can_reach` is the technique-agnostic union used by the point query.
-
-| Relationship | Schema (reading string fields) | Notes |
-|---|---|---|
-| `exploit_to(Asset, Asset)` | `src`, `dst` | Vulnerability exploitation step |
-| `cred_to(Asset, Asset)` | `src`, `dst` | Credential-reuse step |
-| `pivot_to(Asset, Asset)` | `src`, `dst` | Network lateral-movement step |
-| `can_reach(Asset, Asset)` | `src`, `dst` | Union of all steps (any technique); used by the point query |
+For the full concept and property definitions — including the four directed self-relationships (`exploit_to`, `cred_to`, `pivot_to`, and the technique-agnostic `can_reach` union edge) — see `cybersecurity_attack_paths.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
@@ -163,77 +140,13 @@ CSV files --> Define Asset + technique edges --> Kill-chain enumeration (multi-e
           --> Point query (entry to crown jewel) --> Exposure ranking --> Persist Asset.on_attack_path
 ```
 
-### 1. Model assets and one edge per technique
+The analysis starts by modeling each attacker technique as its own directed relationship between assets — `exploit_to`, `cred_to`, `pivot_to` — plus a technique-agnostic `can_reach` union edge that the point query uses.
 
-Each attacker technique is its own directed relationship between assets, plus a technique-agnostic union edge for the point query:
+The centerpiece is a multi-edge path pattern (which needs `relationalai>=1.15`) that composes the techniques in series: an exploit first, then credential reuse, then one or more lateral pivots, ending at an explicit destination. Filtering the source to an internet-facing asset and the destination to a crown jewel pins the threat model. Enforcing edge order is the whole point — a single union edge or a flat join cannot express "exploit first, then credentials, then pivots," which is exactly the kill-chain signature analysts care about, and each hop records the technique it used.
 
-```python
-Asset.exploit_to = model.Relationship(f"{Asset} exploits to {Asset}", short_name="exploit_to")
-Asset.cred_to = model.Relationship(f"{Asset} reuses credentials to {Asset}", short_name="cred_to")
-Asset.pivot_to = model.Relationship(f"{Asset} pivots to {Asset}", short_name="pivot_to")
-# Technique-agnostic union edge: an attacker can move from src to dst by SOME
-# technique. Used for the point query (any route between two named assets).
-Asset.can_reach = model.Relationship(f"{Asset} can reach {Asset}", short_name="can_reach")
-```
+A separate point query pins both endpoints by id to enumerate every route between a chosen entry point and a chosen crown jewel over the union edge. The kill-chains are then ranked by the exposure summed along each one. Finally, the assets lying on any crown-jewel chain are flagged back onto the ontology as `Asset.on_attack_path`, so a later query can pull them without re-enumerating paths.
 
-### 2. Enumerate kill-chain attack paths (multi-edge, requires `relationalai>=1.15`)
-
-The path pattern composes the three techniques in series. The first hop is an exploit, the second is credential reuse, then one or more lateral pivots, ending at an explicit destination. Filtering the source to an internet-facing asset and the destination to a crown jewel pins the threat model:
-
-```python
-a, b, c, dst = Asset.ref(), Asset.ref(), Asset.ref(), Asset.ref()
-kill = model.path(a.exploit_to, b.cred_to, c.pivot_to.repeat(1, MAX_PIVOTS), dst).all_paths()
-kill_df = (
-    model.where(
-        kill,
-        a.internet_facing == "yes",
-        dst.crown_jewel == "yes",
-    )
-    .select(
-        kill.alias("path_id"),
-        kill.nodes["index"].alias("step"),
-        Asset(kill.nodes).id.alias("asset_id"),
-        Asset(kill.nodes).name.alias("asset_name"),
-    )
-    .to_df()
-)
-```
-
-The edge order is enforced by the pattern. A single "can move" union edge or a flat join cannot express "exploit first, then credentials, then pivots", which is exactly the kill-chain signature analysts care about. `kill.relationships["relationship"]` reads the technique used at each hop.
-
-### 3. Point query between two named assets
-
-Pinning both endpoints by id enumerates every route between a chosen entry point and a chosen crown jewel over the union edge:
-
-```python
-src_pt, dst_pt = Asset.ref(), Asset.ref()
-route = model.path(src_pt.can_reach.repeat(1, MAX_ROUTE_HOPS), dst_pt).all_paths()
-route_df = (
-    model.where(
-        route,
-        src_pt.id == ENTRY_ASSET,
-        dst_pt.id == TARGET_ASSET,
-    )
-    .select(
-        route.alias("path_id"),
-        route.nodes["index"].alias("step"),
-        Asset(route.nodes).id.alias("asset_id"),
-    )
-    .to_df()
-)
-```
-
-### 4. Persist the assets on a crown-jewel attack path
-
-The assets along the kill-chains are flagged back onto the ontology so a later query can pull them without re-enumerating paths:
-
-```python
-Asset.on_attack_path = model.Property(f"{Asset} on attack path {String:on_attack_path}")
-on_path_ids = sorted({i for ch in chains for i in ch["asset_ids"]})
-flag_data = model.data(pd.DataFrame({"id": on_path_ids}))
-fa = Asset.ref()
-model.where(fa.id == flag_data["id"]).define(fa.on_attack_path("yes"))
-```
+See `cybersecurity_attack_paths.py` for the implementation and `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Customize this template
 
@@ -270,7 +183,7 @@ model.where(fa.id == flag_data["id"]).define(fa.on_attack_path("yes"))
 <details>
   <summary>Why does authentication or configuration fail?</summary>
 
-- Run `rai init` to create or update `raiconfig.toml`.
+- Run `rai init` to create or update `raiconfig.yaml`.
 - If you have multiple profiles, set `RAI_PROFILE` or switch profiles in your config.
 
 </details>
diff --git a/v1/datacenter_compute_allocation/README.md b/v1/datacenter_compute_allocation/README.md
index b7ceecf3..144684bb 100644
--- a/v1/datacenter_compute_allocation/README.md
+++ b/v1/datacenter_compute_allocation/README.md
@@ -1,8 +1,8 @@
 ---
 title: "Datacenter Compute Allocation"
-description: "Inside-the-fence GPU allocation across hyperscaler campuses, a chain follow-up to energy_grid_planning: GNN-predicted per-workload utilization, hardware-compatibility rules, dependency PageRank, and a 24-cell scenario MIP."
+description: "Allocate GPU capacity across hyperscaler campuses using a graph neural network (GNN) that predicts per-workload utilization, hardware-compatibility rules, dependency PageRank, and a 24-cell scenario mixed-integer program (MIP). Picks up where energy_grid_planning leaves off."
 featured: false
-private: true
+private: false
 experience_level: advanced
 industry: "Technology & Telecom"
 reasoning_types:
@@ -27,44 +27,13 @@ tags:
   - Capacity Planning
 ---
 
-# Datacenter Compute Allocation
-
-This template demonstrates the operator-side decision that picks up where **[energy_grid_planning](https://github.com/RelationalAI/templates/tree/main/v1/energy_grid_planning)** leaves off. That upstream template solves the multi-year capex / interconnect question — which AI campuses get built and energized at what MW envelope — across ~50 binaries. This template zooms into the *energized* campus and decides which AI lab's individual training, fine-tune, inference, and eval workloads get which GPUs in which pool *now*. The bundled `data_centers.csv` is a snapshot of the upstream $300M-approved campus set; the two templates form a conceptual sequence over the same domain, not a literal engine-level chain.
-
 ## What this template is for
 
-The 5 hyperscaler campuses in the bundled snapshot — xAI Colossus, Microsoft Horizon, CoreWeave Austin, Crusoe Permian, Oracle Coastal — are energized and stocked with GPU pools. The DC operator (a neocloud / colocation provider, or the hyperscaler operating its own campus) has to allocate that GPU capacity across the AI labs renting time on it. Frontier model labs want long-running training reservations on the largest contiguous H100 / H200 / GB200 pools at preferential anchor-customer rates. Inference customers want a steady slice of right-sized GPUs in low-latency regions. Research orgs want bursty best-effort capacity. They all compete for the same physical pools under the same power envelope.
-
-The decision is **multi-objective and operationally pressing**. Every major hyperscaler now reports AI compute as a binding constraint on growth (Microsoft has disclosed an $80B Azure backlog blocked specifically by power constraints). The operator is accountable on three publicly-discussed dimensions:
-
-1. **Power envelope as cone of uncertainty.** Each campus has a substation-bound MW cap (`approved_mw`, set by the interconnection-planning decision the upstream template represents). Two envelope cells trace the cone direction: 85% is the lower-cone curtailment day (heat-wave or grid-stress de-rating), 100% is the expected grid-approved cap. Hyperscaler compute is exponential and unstable; planning to the midpoint is how operators end up under-provisioned to anchors.
-2. **Gross-margin discipline at the envelope, not per-token.** SemiAnalysis quantifies neocloud BMaaS at 55-65% gross margin pre-depreciation but only **14-16% net** after labor, power, and depreciation, so even a single MWh-cost mis-allocation is meaningful to the P&L. The discipline lives at the *envelope* — return on the full compute base across all uses — not on each individual workload-pool placement.
-3. **Anchor concentration as a strategic floor.** CoreWeave's Q2 2025 10-Q discloses **71% of revenue from a single customer (Microsoft)** and an $11.9B OpenAI commitment booked through October 2030 — the canonical example of the concentration risk that caps equity value. Operators win anchors (because they underwrite debt-financed buildouts) AND dilute them (because investor-visible concentration risk caps equity value). Anchor contracts also act as a *hard floor* — they must be served wherever feasible, even when serving them squeezes margin elsewhere; under-provisioning an anchor is more costly than under-provisioning an opportunistic workload, because the penalty is contractual and reputational, not just foregone revenue.
-4. **Generational layer cake.** A hyperscaler's GPU fleet is itself a portfolio. H100, H200, and GB200 pools sit at different points on the price-per-effective-GPU-hour curve ($1.14, $1.52, $2.66 per GPU-hour at capex/3-year amortization in the bundled data). The optimizer's job is to deploy each generation against the workload type that gets the best return per dollar of depreciation + power — not to treat all GPU-hours as fungible. Effective capacity is `gpu_count × generation_efficiency`, not nameplate.
-
-This template combines three Scenario Concepts — `PowerEnvelopeLevel`, `MarginFloor`, and `DiversityCap` — into a **scenario sweep (2 × 3 × 4 = 24 cells)** that traces two Pareto frontiers the operator already discusses publicly: margin-floor vs. achievable revenue, and diversity-cap vs. achievable revenue, with envelope as outer sensitivity. The strictest cells return `INFEASIBLE` — this is the intended diagnostic signal showing which constraint combinations cannot be satisfied simultaneously. After the main solve, a `DemandScenario` overlay replays the chosen plan under risk scenarios (diffusion slowdown, scaling-law plateau, frontier loss) so the operator sees stranded-capacity exposure if lab-side demand softens.
+A datacenter operator — a neocloud, a colocation provider, or a hyperscaler running its own campuses — has energized GPU pools across several sites and must decide which AI lab's workloads get which GPUs in which pool right now. Frontier labs want long-running training reservations on the largest contiguous pools at anchor-customer rates; inference customers want a steady slice of right-sized GPUs; research orgs want bursty best-effort capacity. They all compete for the same physical pools under the same power envelope, and the operator has to keep three tensions in balance at once: staying under each campus's substation-bound power cap, holding gross margin after energy and depreciation, and serving anchor customers without letting any one customer's share grow into a concentration risk. Getting the allocation wrong strands expensive capacity — depreciation accruing on GPUs that sit idle — which is the operator's biggest economic exposure.
 
-This template demonstrates a multi-reasoner workflow combining **predictive** (per-workload utilization-probability classification GNN — predicts which workloads will actually use their allocated capacity at high duty cycle vs stall or be repaced; stranded-capacity exposure is the operator's biggest economic risk), **rules** (hardware compatibility + priority-tier classification), **graph** (downstream-gating score on the workload-dependency DAG), and **prescriptive** (assignment MIP under a 3D Scenario sweep) reasoning on a single shared ontology — each stage's output narrows or scores the next.
+This template models that allocation as a scenario sweep across three axes (power envelope, margin floor, and anchor-diversity cap, for 24 combinations in all), tracing the trade-off frontiers the operator actually reasons about: how much revenue a tighter margin floor costs, and how much a tighter anchor cap costs. The strictest combinations come back infeasible, which is itself the answer — a signal that those constraints cannot all be met at once. A follow-on demand overlay then replays the chosen plan under softening-demand scenarios so the operator can see stranded-capacity exposure before committing. It picks up where the [energy_grid_planning](https://github.com/RelationalAI/templates/tree/main/v1/energy_grid_planning) template leaves off: that upstream template decides which campuses get built and energized, and the bundled `data_centers.csv` here is a snapshot of its approved campus set.
 
-## Reasoner overview: inputs, outputs, and role
-
-| Stage | Reasoner | Reads from ontology | Writes to ontology | Role |
-|-------|----------|---------------------|--------------------|------|
-| 1. Predictive | **Heterogeneous-graph temporal GNN** (binary classification) | `LabMetric` activity features (time-aligned via `metric_date`) + `Workload` features + three edge types: intra-lab `lab_workloads`, `WorkloadDependency.blocks` (shared with Stage 3), cross-lab `co_dated` (LOAD-BEARING) | `Workload.utilization_probability` per workload (positive-class probability) | Predict per-workload utilization probability for the current period: will this workload actually use its allocated capacity at high duty cycle, or stall / be repaced? Trained on 770 historical `(workload, month, is_high_utilization)` observations over 7 prior months + 1 validation month; the GNN uses `has_time_column=True` to align workload-period predictions with same-period LabMetric activity. Stranded-capacity exposure is the operator's biggest economic risk. Cross-concept message passing is genuinely load-bearing — utilization depends on the lab's broader activity at the prediction date (lab→workload), what upstream pretrains produced (dep DAG), and industry-wide trends (cross-lab co_dated). Bound directly as a per-workload signal Stage 4's objective consumes. |
-| 2. Rules | **Rules** (declarative) | `Workload` requirements, `GpuPool` specs | `Workload.fails_memory`, `.passes_gpu_type`, `.is_eligible` Relationships; `Workload.priority_tier`, `.priority_weight`, and `.under_provisioning_penalty` Properties; `Compatibility(workload, gpu_pool)` precompute | Classify which (Workload, GpuPool) pairs are technically eligible (memory + GPU-type allowlist). Assign priority tier P0/P1/P2 from `contract_tier`, with a numeric weight (100/10/1) and an asymmetric under-provisioning penalty (1.0/0.3/0.0) that amplifies the Stage 4 reward for assigning anchor-tier workloads. The Compatibility precompute keeps the Stage 4 MIP linear. |
-| 3. Graph | **Reverse-PageRank** | `Workload` nodes, `WorkloadDependency.blocks` edges | `Workload.gating_score` | Score how much downstream work each workload unblocks. A frontier pretrain that gates 14 fine-tunes and evals lands high; an isolated inference workload sits at baseline. |
-| 4. Prescriptive | **MIP** | `Compatibility`, `priority_weight`, `under_provisioning_penalty`, `gating_score`, `utilization_probability`, `dollars_per_mwh`, `hourly_depreciation_rate`, `approved_mw`, `is_strategic_anchor`, the three Scenario Concepts | `Assignment.x_assign` per `(PowerEnvelopeLevel, MarginFloor, DiversityCap)`; `AllocationPlan` singleton; `Assignment.is_chosen`; `DemandScenario` + `DemandScenarioOutlook` (4 risk scenarios) | Assign each workload to one (DC, GpuPool) under power, GPU-count, gross-margin-floor (energy + depreciation cost), and anchor / workload-type-diversity constraints. Maximizes a four-factor strategic value amplified by the under-provisioning penalty: priority × gating × utilization_probability × strategic_value × (1 + penalty). 24-cell sweep; strictest cells return INFEASIBLE as designed signal. The headline cell (`100pct / unconstrained / none`) is persisted as the `AllocationPlan` singleton, its decision rows flagged via `Assignment.is_chosen`, and the chosen plan is replayed under four demand-risk scenarios (expected / diffusion_slowdown / scaling_break / frontier_loss) with realized + stranded revenue persisted as `DemandScenarioOutlook` per scenario. All queryable as ontology after the script exits. |
-
-**Key design patterns demonstrated:**
-
-- **One ontology relationship, two reasoners.** `WorkloadDependency.blocks` carries information into both the Stage 1 GNN (as a heterogeneous edge) and the Stage 3 PageRank (as the dependency DAG). Defined once in the ontology, consumed without duplication or DataFrame round-trips.
-- **Per-cell aggregates queried from the ontology.** Stage 4's per-cell summary table (revenue, energy + depreciation cost, anchor share, workload-type counts) comes from `sum(...).where(Assignment.x_assign(env, mar, div, x), x > 0.5).per(env, mar, div)` aggregate expressions assembled inside a single `model.select()` call — mirroring `energy_grid_planning`'s `rev_per_level` pattern. No pandas-side groupby of raw assignments.
-- **Headline plan persisted as ontology.** After the 24-cell sweep, the chosen baseline cell (`100pct / unconstrained / none`) is written back as a singleton `AllocationPlan` Concept carrying revenue, total_cost, realized_margin, anchor_share, n_assigned, status, and binding_axis — plus an `Assignment.is_chosen` unary Relationship that flags the decision rows in that cell. The plan is queryable as ontology after the script exits, mirroring the `RestorePlan` / `is_selected_upgrade` pattern in `telco_network_recovery`.
-- **Heterogeneous GNN, not time-series-on-rails.** Stage 1 connects `LabMetric` to `Workload`, to other `LabMetric` rows on the same date (when their labs share a workload_type), and reuses `WorkloadDependency` — in addition to same-lab temporal lags. Pure same-entity temporal-lag topology is a misuse of the GNN reasoner; the cross-concept edges are what give it lift.
-- **Three-dimensional Scenario Concept design.** `PowerEnvelopeLevel` (outer capacity sensitivity), `MarginFloor` (primary Pareto axis), `DiversityCap` (primary Pareto axis). Decision variable `Assignment.x_assign` is indexed by all three; the Pareto frontier emerges from constraint relaxation across cells, not from a multi-objective solve.
-- **Lex-emulating priority weights.** P0 workloads carry weight 100, P1 carry 10, P2 carry 1, plus a hard P0-must-be-assigned constraint. This mirrors how production cluster schedulers (Borg, Singularity, MAST) balance priority dominance with throughput optimization.
-- **Four-factor MIP objective as envelope-level ROI.** `priority_weight × gating_score × utilization_probability × strategic_value_usd` — one factor per upstream reasoner (Stage 2 / Stage 3 / Stage 1) plus the raw dollar baseline. Single-MIP, weighted-sum; the multi-objective Pareto emerges from constraint relaxation, not the objective. The operator's discipline lives at the envelope — return on the full compute base across anchor / opportunistic / research uses — not on each individual workload-pool placement.
-- **Asymmetric failure-mode pricing.** Under-provisioning an anchor is more costly than missing a research eval: the SLA / contract / reputational penalty is a multiple of the raw revenue at stake. Stage 2 derives a `Workload.under_provisioning_penalty` from the priority tier; Stage 4's objective amplifies the reward for assigning high-penalty workloads, so the solver treats anchor under-provisioning as the asymmetric failure mode it is, not as a symmetric foregone-revenue line item.
+**The reasoning approach chains four reasoners on one shared ontology — a graph neural network (GNN) predicting per-workload utilization, declarative hardware-compatibility and priority rules, dependency-graph PageRank scoring how much downstream work each workload unblocks, and a scenario-parameterized mixed-integer program (MIP) that makes the assignment — with each stage writing signals the next stage reads.**
 
 ## Who this is for
 
@@ -172,101 +141,14 @@ Set `EXP_DATABASE` at the top of `datacenter_compute_allocation.py` to that data
 7. Expected output (abbreviated):
 
    ```text
-   STAGE 0: LOAD ONTOLOGY
-     Ontology loaded: 6 labs, 28 pools, 110 workloads, 138 dep edges, 2x3x4=24 scenario cells
-
-   STAGE 1: PREDICT -- per-workload utilization-probability GNN
-     Workload utilization-probability distribution: n_total=110, n>=0.5: 95, n<0.5: 15
-     Top 5 (most likely to be high-utilization):
-       + GPT-Next pretrain shard 05                    p=0.781
-       + GPT-Next pretrain shard 02                    p=0.780
-       + GPT-Next pretrain shard 03                    p=0.777
-       + Claude-Next pretrain shard 04                 p=0.775
-       + Claude-Next pretrain shard 05                 p=0.774
-     Bottom 5 (most likely to stall / be repaced):
-       - Stability eval batch 11                       p=0.381
-       - Stability eval batch 15                       p=0.382
-       - Stability eval batch 12                       p=0.384
-       - Stability eval batch 14                       p=0.385
-       - Stability eval batch 04                       p=0.385
-
-   STAGE 2: RULES -- eligibility + priority classification
-     Compatibility table: 1918 eligible (Workload, GpuPool) pairs
-     Priority tier counts: P0=15, P1=80, P2=15
-
-   STAGE 3: GRAPH -- workload-dependency PageRank (gating score)
-     Top-10 gating workloads (frontier pretrains expected to dominate):
-       GPT-Next pretrain shard 02                    score=0.0310
-       Grok-Next pretrain shard 04                   score=0.0266
-       Grok-Next pretrain shard 03                   score=0.0259
-       Grok-Next pretrain shard 01                   score=0.0253
-       GPT-Next pretrain shard 04                    score=0.0244
-       Claude-Next pretrain shard 02                 score=0.0227
-       ...
-
    STAGE 4: PRESCRIPTIVE -- compute allocation MIP (24-cell sweep)
-     Solving 24-cell scenario sweep with gurobi...
      Termination status: OPTIMAL
-     Solve time:         6.3s
-     Objective:          543,436,742.28
-
-     Per-cell summary (24 cells: 16 optimal, 8 infeasible):
-       100pct unconstrained             none    OPTIMAL  110  25,277,810.94  4,180,500.79  0.83  0.95
-       100pct         80pct             none    OPTIMAL  110  25,277,810.94  4,224,313.30  0.83  0.95
-       100pct         85pct             none    OPTIMAL   20  22,032,951.05  3,304,939.27  0.85  1.00
-       100pct unconstrained anchor_max_70pct    OPTIMAL   97   4,437,625.19    891,678.81  0.80  0.70
-       100pct unconstrained anchor_max_50pct    OPTIMAL   97   2,598,602.50    598,727.11  0.77  0.49
-       100pct         85pct anchor_max_70pct    OPTIMAL   70   4,053,503.29    608,011.98  0.85  0.70
-       100pct         85pct anchor_max_50pct INFEASIBLE    0           0.00          0.00   NaN   NaN
-       (*, *, anchor_max_40pct_with_type_floor): all 6 cells INFEASIBLE
-       ...
-
-     Pareto frontier 1: Margin floor <-> Revenue (envelope=100pct, diversity=none)
-              margin  n_assigned  revenue_usd  realized_margin  anchor_share
-       unconstrained         110   25,277,811             0.83          0.95
-                80pct        110   25,277,811             0.83          0.95
-                85pct         20   22,032,951             0.85          1.00
-
-     Pareto frontier 2: Diversity cap <-> Revenue (envelope=100pct, margin=unconstrained)
-                              diversity  n_assigned  revenue_usd  realized_margin  anchor_share
-                                   none         110   25,277,811             0.83          0.95
-                       anchor_max_70pct          97    4,437,625             0.80          0.70
-                       anchor_max_50pct          97    2,598,602             0.77          0.49
-       anchor_max_40pct_with_type_floor           0            0              NaN           NaN
-
-     AllocationPlan singleton (queryable as ontology):
-       plan_id        envelope        margin     diversity  status   n_assigned   revenue_usd   total_cost_usd   realized_margin   anchor_share    binding_axis
-       DCCA_BASELINE    100pct  unconstrained         none  OPTIMAL         110   25277810.94      4180500.79         0.834618          0.947251  power_envelope
-
-     Assignment.is_chosen rows: 110 (matches n_assigned above)
-
-     DemandScenario overlay (chosen plan replayed under risk):
-                scenario  factor  realized_revenue_usd  stranded_revenue_usd  stranded_pct
-                expected    1.00         25,277,810.94                  0.00          0.00
-       diffusion_slowdown    0.85         25,077,803.64            200,007.30          0.79
-            scaling_break    0.70         24,877,796.35            400,014.59          1.58
-            frontier_loss    0.50         24,611,119.95            666,690.99          2.64
+     Per-cell summary (24 cells: 16 optimal, 8 infeasible)
+     AllocationPlan singleton (100pct / unconstrained / none):
+       110 workloads assigned, $25.28M revenue, 83% margin, 95% anchor share
    ```
 
-   GNN probabilities depend on seed and predictive engine; the `--no-gnn` fallback values are deterministic. Stage 4 reaches `OPTIMAL` in seconds with Gurobi; the open-source HiGHS default returns a feasible solution at the `time_limit_sec=240` wall and may surface `TIME_LIMIT` (signal, not failure, per `rai-prescriptive-results-interpretation`). Set `SOLVER` in `datacenter_compute_allocation.py` to switch.
-
-   **Expected runtime** (full pipeline, GNN on `GPU_NV_S` + Gurobi on prescriptive engine):
-   - Stage 0 (ontology load): a few seconds
-   - Stage 1 (GNN training + prediction): ~3–4 min on `GPU_NV_S` (training prep ~40 s, training ~20 s, prediction ~75 s)
-   - Stages 2–3 (rules + PageRank): a few seconds combined
-   - Stage 4 (24-cell MIP): ~6 s with Gurobi, OPTIMAL across all 24 cells; up to 240 s wall with HiGHS
-   - Total wall time: ~4–5 min end-to-end (Stage 1 GNN dominates)
-
-   **Expected per-cell behavior** (24 cells = 16 OPTIMAL + 8 INFEASIBLE):
-   - `(*, unconstrained / 80% margin, none diversity)` — full assignment of all 110 workloads, $25.28M revenue, 83% margin, 95% anchor. The 80% floor is not binding; the unconstrained solution naturally lands at 83% margin.
-   - `(*, 85% margin, none)` — tight floor binds: drops 90 lower-margin workloads, retains 14 of 15 frontier P0 pretrains plus 4 P1 finetunes and 2 P2 evals that fit under the floor. Revenue $22.03M @ 85% margin / 100% anchor.
-   - `(*, unconstrained / 80% margin, anchor_max_70pct)` — 97 workloads, $4.44M revenue, 70% anchor. The anchor cap forces most P0 pretrains out; revenue is cut 82% but margin holds.
-   - `(*, unconstrained / 80% margin, anchor_max_50pct)` — 97 workloads, $2.60M revenue, 49% anchor. CoreWeave-target cap; only 2 of 15 P0 pretrains fit.
-   - `(*, 85% margin, anchor_max_70pct)` — 70 workloads, $4.05M revenue. The two constraints partially compose; some pretrains fit, some get dropped.
-   - `(*, 85% margin, anchor_max_50pct)` — INFEASIBLE. High margin floor wants pretrain-heavy, anchor cap forbids that mix.
-   - `(*, *, anchor_max_40pct_with_type_floor)` — all 6 cells INFEASIBLE. Combined cap + workload-type floor too tight for this lab roster.
-
-   **Headline result.** At the chosen baseline (`100pct / unconstrained / none`): 110 workloads assigned → $25.28M revenue, $4.18M cost, 83% realized margin, 95% anchor share, power envelope as the binding axis. The two Pareto frontiers cliff at **85% margin** (−13% revenue, 90 workloads dropped) and at **any anchor cap** (−82% revenue at 70%, −90% at 50%, INFEASIBLE at 40% + type floor). The `DemandScenario` overlay shows only $200K / $400K / $667K stranded under softening scenarios because the plan is anchor-heavy and P0 anchor revenue is contractually locked — `DemandScenarioOutlook(scenario)` ontology rows make this queryable post-run.
+   Full stage-by-stage log (GNN distribution, PageRank scores, both Pareto frontiers, the demand-scenario overlay, and expected per-cell behavior) is in `runbook.md`. GNN probabilities depend on seed and predictive engine; the `--no-gnn` fallback values are deterministic. Stage 4 reaches `OPTIMAL` in seconds with Gurobi; the open-source HiGHS default returns a feasible solution at the `time_limit_sec=240` wall and may surface `TIME_LIMIT` (signal, not failure, per `rai-prescriptive-results-interpretation`). Set `SOLVER` in `datacenter_compute_allocation.py` to switch.
 
 ## Template structure
 
@@ -293,151 +175,54 @@ datacenter_compute_allocation/
   pyproject.toml                    # dependencies
 ```
 
+**Start here**: run `python datacenter_compute_allocation.py` for the full four-stage chain end to end (add `--no-gnn` to skip Stage 1's GNN and load the deterministic fallback), or follow `runbook.md` to rebuild it step by step.
+
+## Sample data
+
+The bundled data is synthetic and illustrative — designed to teach the four-stage reasoning flow on a Snowflake-connected RAI account, not to match a specific operator's fleet. The five campuses, six labs, GPU generations, and workload mix are shaped so every stage does visible work and the Pareto frontiers and infeasible cells show up as intended.
+
+- **`data_centers.csv`** (5 rows) — campuses (snapshot of the upstream $300M-approved set), each with an approved power cap, PUE, and energy cost.
+- **`gpu_pools.csv`** (28 rows) — GPU pools across the 5 campuses (H100 / H200 / GB200 mix), each with a per-GPU hourly depreciation rate.
+- **`ai_labs.csv`** (6 rows) — labs: 3 frontier anchors, 2 applied, 1 research, each with a contract tier and anchor flag.
+- **`workloads.csv`** (110 rows) — training, fine-tune, inference, and eval workloads with GPU and memory requirements and a strategic dollar value.
+- **`workload_gpu_compatibility.csv`** — the per-workload GPU-type allowlist (multi-valued, so it lives as its own concept).
+- **`workload_dependencies.csv`** (138 rows) — directed dependency edges (`blocks` / `informs`), DAG depth 4-5 rooted at frontier pretrains.
+- **`lab_metrics.csv`** (2,190 rows) — 365 days x 6 labs of daily lab-activity KPIs with cross-lab co-movement, the GNN's temporal feature source.
+- **`workload_utilization_train.csv` / `_val.csv` / `_test.csv`** — the GNN's temporal binary-classification splits (7 historical months / 1 validation month / current period, no label).
+- **`workload_utilization_fallback.csv`** — the deterministic Stage 1 fallback used when `--no-gnn` is set.
+- **`power_envelope_levels.csv` / `margin_floors.csv` / `diversity_caps.csv`** — the three scenario-axis tables (2 / 3 / 4 rows) that index the 24-cell sweep.
+
+## Model overview
+
+One shared ontology threads all four stages: each stage reads concepts and properties earlier stages wrote and writes new ones for downstream stages.
+
+- **Key entities**: `DataCenterRequest` (a campus), `GpuPool`, `AILab`, `Workload`, `WorkloadGpuCompat` and `WorkloadDependency` (workload relationships as their own concepts), the three scenario concepts `PowerEnvelopeLevel` / `MarginFloor` / `DiversityCap`, plus the derived `Compatibility` and `Assignment` (decision space), the `AllocationPlan` singleton, and the `DemandScenario` overlay.
+- **Primary identifiers**: string ids on `DataCenterRequest`, `GpuPool`, `AILab`, and `Workload`; the scenario concepts are identified by `name`; `WorkloadGpuCompat`, `WorkloadDependency`, `Compatibility`, and `Assignment` carry composite keys.
+- **Important invariants**: `envelope_multiplier`, `fraction`, and `anchor_max_share` are fractions; a negative sentinel on `MarginFloor.fraction` / `DiversityCap.anchor_max_share` marks the unconstrained row (its constraint is skipped); the `is_high_utilization` label is binary; `Assignment.x_assign` decision variables are binary; power / cost / GPU counts are non-negative.
+
+For the full concept and property definitions — the entity concepts, the three scenario concepts, and the derived `Compatibility` / `Assignment` / `AllocationPlan` / `DemandScenario` concepts each stage writes — see `datacenter_compute_allocation.py`; `runbook.md` builds them step by step with the RAI skills.
+
 ## How it works
 
 ### Stage 1: Predictive — per-workload utilization-probability GNN
 
 Binary node classification on `Workload`: predict the probability that each workload will be high-utilization (actually use its allocated capacity at high duty cycle) vs stall or be repaced. Stranded capacity (depreciation accruing without offsetting revenue) is the operator's biggest economic exposure, so this is the chain's load-bearing forward-looking signal.
 
-The graph is heterogeneous with three cross-concept edge types:
-
-```python
-gnn_graph = Graph(model, directed=False, weighted=False)
-
-# Edge 1: LabMetric -> Workload owned by the same lab.
-# Carries lab-side recent activity into the per-workload prediction
-# neighborhood -- a workload owned by a fast-ramping lab inherits signal.
-model.define(gnn_graph.Edge.new(src=LabMetric, dst=Workload)).where(
-    LabMetric.lab == Workload.lab.name,
-)
-
-# Edge 2: WorkloadDependency.blocks DAG (shared with Stage 3).
-# A workload downstream of a high-utilization gating pretrain inherits
-# signal through the dep chain.
-dep_ref = WorkloadDependency.ref()
-model.define(
-    gnn_graph.Edge.new(src=dep_ref.predecessor, dst=dep_ref.successor)
-).where(dep_ref.dependency_type == "blocks")
-
-# Edge 3: LabMetric -> LabMetric, cross-lab same-date pairs sharing a workload_type.
-# LOAD-BEARING -- carries cross-lab co-movement (funding waves, supply shocks).
-co_pairs = _build_codated_pairs()
-co_src = model.data(co_pairs)
-LM_a, LM_b = LabMetric.ref(), LabMetric.ref()
-model.define(gnn_graph.Edge.new(src=LM_a, dst=LM_b)).where(
-    LM_a.lab == co_src.lab_a, LM_a.metric_date == co_src.shared_date,
-    LM_b.lab == co_src.lab_b, LM_b.metric_date == co_src.shared_date,
-)
-```
-
-The task tables carry per-`(workload, observation_date)` historical labels (`workload_utilization_*.csv`). Each row is one monthly utilization observation; the same workload appears in 7 training rows (one per historical month), giving the GNN per-period variety to learn from instead of a single label per entity. Train (7 months × 110 = 770) / Val (1 month × 110 = 110) / Test (current month × 110, no label — every workload gets a probability for the upcoming period). The task relationships use `at {Date:obs_date}` time slots and the GNN runs with `has_time_column=True` so LabMetric features are time-aligned with each (workload, month) prediction:
-
-```python
-Train = model.Relationship(f"{Workload} at {Date:obs_date} has {Any:label}")
-model.define(Train(
-    Workload, TrainTable.observation_date, TrainTable.is_high_utilization
-)).where(Workload.id == TrainTable.workload_id)
-
-Test = model.Relationship(f"{Workload} at {Date:obs_date}")
-model.define(Test(
-    Workload, TestTable.observation_date
-)).where(Workload.id == TestTable.workload_id)
-
-pt = PropertyTransformer(
-    ...
-    datetime=[LabMetric.metric_date],
-    time_col=[LabMetric.metric_date],
-)
-
-gnn = GNN(
-    ...
-    task_type="binary_classification",
-    eval_metric="roc_auc",
-    has_time_column=True,
-    ...
-)
-gnn.fit()
-Workload.predictions = gnn.predictions(domain=Test)
-```
+The graph is heterogeneous with three cross-concept edge types: a `LabMetric → Workload` edge that carries lab-side recent activity into a workload's prediction neighborhood (a workload owned by a fast-ramping lab inherits its signal); the `WorkloadDependency.blocks` DAG shared with Stage 3, so a workload downstream of a high-utilization gating pretrain inherits signal through the dependency chain; and a load-bearing `LabMetric → LabMetric` edge between cross-lab same-date pairs sharing a workload type, which carries cross-lab co-movement (funding waves, supply shocks).
 
-The positive-class probability is bound back to the ontology as `Workload.utilization_probability` and consumed by Stage 4's objective.
+The task tables carry per-`(workload, observation_date)` historical labels. Each row is one monthly utilization observation, so the same workload appears in 7 training rows (one per historical month), giving the GNN per-period variety to learn from instead of a single label per entity — Train (7 months × 110 = 770) / Val (1 month × 110 = 110) / Test (current month × 110, no label, so every workload gets a probability for the upcoming period). The task relationships use `at` time slots and the GNN runs with `has_time_column=True` so LabMetric features are time-aligned with each (workload, month) prediction. The positive-class probability is bound back to the ontology as `Workload.utilization_probability` and consumed by Stage 4's objective.
 
 ### Stage 2: Rules — eligibility + priority tiers + Compatibility precompute
 
-Two rule families run on the workload-pool product. The eligibility rule joins through the `WorkloadGpuCompat(workload, gpu_type)` composite-key concept (per the GNN-node FD trap: multi-valued allowlists on a GNN-node concept must live as their own concept, not as a Workload Relationship) and enforces both the memory check and the GPU-type allowlist:
-
-```python
-Workload.is_eligible = model.Relationship(
-    f"{Workload} is eligible on {GpuPool}"
-)
-model.where(
-    WorkloadGpuCompat.workload == Workload,
-    WorkloadGpuCompat.gpu_type == GpuPool.gpu_type,
-    Workload.mem_required_gb <= GpuPool.mem_per_gpu_gb,
-).define(Workload.is_eligible(GpuPool))
-
-# Compatibility precompute -- keeps the Stage 4 MIP linear and small.
-Compatibility = model.Concept(
-    "Compatibility",
-    identify_by={"workload": Workload, "gpu_pool": GpuPool},
-)
-model.where(Workload.is_eligible(GpuPool)).define(
-    Compatibility.new(workload=Workload, gpu_pool=GpuPool)
-)
-```
-
-Priority tier classification reads `AILab.contract_tier` and writes both `Workload.priority_tier` (string) and `Workload.priority_weight` (100 / 10 / 1) — the numeric form is what Stage 4's objective consumes.
+Two rule families run on the workload-pool product. The eligibility rule joins through the `WorkloadGpuCompat(workload, gpu_type)` composite-key concept (per the GNN-node FD trap: multi-valued allowlists on a GNN-node concept must live as their own concept, not as a Workload Relationship) and enforces both the memory check and the GPU-type allowlist. Eligible pairs are then materialized into a `Compatibility(workload, gpu_pool)` concept — a precompute that keeps the Stage 4 MIP linear and small. Priority tier classification reads `AILab.contract_tier` and writes both `Workload.priority_tier` (string) and `Workload.priority_weight` (100 / 10 / 1) — the numeric form is what Stage 4's objective consumes.
 
 ### Stage 3: Graph — reverse-PageRank for downstream gating
 
-A directed `Workload` graph is built with edge reversal (successor → predecessor) so a node's PageRank accumulates flow from everything it gates downstream:
-
-```python
-dag = Graph(model, directed=True, weighted=False, node_concept=Workload)
-dep_ref = WorkloadDependency.ref()
-model.define(
-    dag.Edge.new(src=dep_ref.successor, dst=dep_ref.predecessor)
-).where(dep_ref.dependency_type == "blocks")
-
-pagerank = dag.pagerank()
-Workload.gating_score = model.Property(
-    f"{Workload} has {Float:gating_score} gating score"
-)
-score_ref = Float.ref("g")
-wl_ref = Workload.ref()
-model.define(wl_ref.gating_score(score_ref)).where(pagerank(wl_ref, score_ref))
-```
-
-Workloads absent from the DAG get a backstop `gating_score = 1.0` so they enter the Stage 4 objective product without zeroing out.
+A directed `Workload` graph is built with edge reversal (successor → predecessor) so a node's PageRank accumulates flow from everything it gates downstream. The resulting score lands on `Workload.gating_score`. Workloads absent from the DAG get a backstop `gating_score = 1.0` so they enter the Stage 4 objective product without zeroing out.
 
 ### Stage 4: Prescriptive — assignment MIP under a 3D Scenario sweep
 
-The decision variable `Assignment.x_assign` is indexed by the three Scenario Concepts so the MIP solves all 24 cells in a single pass:
-
-```python
-Assignment = model.Concept(
-    "Assignment",
-    identify_by={"workload": Workload, "gpu_pool": GpuPool},
-)
-model.define(
-    Assignment.new(workload=Compatibility.workload, gpu_pool=Compatibility.gpu_pool)
-)
-Assignment.x_assign = model.Property(
-    f"{Assignment} per {PowerEnvelopeLevel} per {MarginFloor} per {DiversityCap} "
-    f"assigned {Float:x_assign}"
-)
-
-problem = Problem(model, Float)
-x = Float.ref("x")
-problem.solve_for(
-    Assignment.x_assign(PowerEnvelopeLevel, MarginFloor, DiversityCap, x),
-    type="bin",
-    name=["assign", PowerEnvelopeLevel.name, MarginFloor.name, DiversityCap.name,
-          Assignment.workload.id, Assignment.gpu_pool.id],
-)
-```
-
-Constraint families (one per scenario axis):
+The decision variable `Assignment.x_assign` is a binary variable indexed by the three scenario concepts (`PowerEnvelopeLevel`, `MarginFloor`, `DiversityCap`), so the MIP solves all 24 cells in a single pass. Constraint families run one per scenario axis:
 
 - **C1+C2** at-most-one per workload per cell (soft P0; priority_weight = 100 drives P0 from the objective).
 - **C3** per-pool GPU-count capacity.
@@ -446,31 +231,34 @@ Constraint families (one per scenario axis):
 - **C6** anchor-concentration cap (skipped when `DiversityCap.anchor_max_share < 0`).
 - **C7** workload-type floor (skipped unless `DiversityCap.workload_type_floor >= 0`).
 
-The four-factor objective is what makes this a real chain rather than four disjoint reasoners:
-
-```python
-problem.maximize(
-    sum(x_obj
-        * Assignment.workload.priority_weight       # Stage 2 (rules)
-        * Assignment.workload.gating_score          # Stage 3 (graph)
-        * Assignment.workload.utilization_probability  # Stage 1 (predictive)
-        * Assignment.workload.strategic_value_usd)   # raw $ baseline
-    .where(Assignment.x_assign(PowerEnvelopeLevel, MarginFloor, DiversityCap, x_obj))
-)
-```
-
-After the solve, the per-cell summary table is assembled inside a single `model.select(...)` — `sum(...).where(Assignment.x_assign(env, mar, div, x), x > 0.5).per(env, mar, div)` aggregates run on the ontology, no pandas-side groupby. The chosen baseline cell (`100pct / unconstrained / none`) is persisted as a singleton `AllocationPlan` Concept with revenue / total_cost / margin / anchor_share / n_assigned / status / binding_axis, plus an `Assignment.is_chosen` unary Relationship over its decision rows.
+The objective is what makes this a real chain rather than four disjoint reasoners: it maximizes the sum over chosen assignments of `priority_weight` (Stage 2) × `gating_score` (Stage 3) × `utilization_probability` (Stage 1) × `strategic_value_usd` (raw $ baseline) — every prior stage's signal enters the same product. After the solve, the per-cell summary is assembled with ontology-side aggregation (no pandas groupby). The chosen baseline cell (`100pct / unconstrained / none`) is persisted as a singleton `AllocationPlan` concept with revenue / total_cost / margin / anchor_share / n_assigned / status / binding_axis, plus an `Assignment.is_chosen` flag over its decision rows.
 
 Finally, a `DemandScenario` overlay replays the locked-in plan under four risk scenarios. Anchor (P0) revenue is treated as contractual (factor 1.0) — the operator gets paid for the seat regardless of utilization — while opportunistic (P1/P2) seats realize only the scenario factor of their assigned revenue. The overlay reports realized and stranded revenue per scenario and persists each as a `DemandScenarioOutlook(scenario)` concept row, so the stranded-capacity exposure of the chosen plan is queryable as ontology, not just printed.
 
+See `datacenter_compute_allocation.py` for the implementation and `runbook.md` to reproduce each stage step by step with the RAI skills.
+
 ## Customize this template
 
-- **Add or remove DCs** by editing `data_centers.csv`. The bundled set is a snapshot of the upstream $300M-approved campuses; re-running `energy_grid_planning` at a different `InvestmentLevel` produces a different approved set you can copy in.
-- **Adjust the lab roster** in `ai_labs.csv`. Anchor flag drives the `DiversityCap` constraint.
-- **Tune scenario axes**: edit `power_envelope_levels.csv`, `margin_floors.csv`, `diversity_caps.csv`. Adding rows scales the cell count multiplicatively.
-- **Change the priority spread** by editing the weights in the `# Stage 2: Rules` section (default 100 / 10 / 1).
-- **Replace the GNN with the deterministic fallback** by setting `--no-gnn` and editing `workload_utilization_fallback.csv` directly.
-- **Tune the Stage 4 solve** by adjusting the solver name or `time_limit_sec` in `problem.solve(...)`. The default works on any prescriptive engine; faster commercial solvers (when licensed) can reach OPTIMAL in a fraction of the time.
+### Use your own data
+
+- Add or remove campuses by editing `data_centers.csv`. The bundled set is a snapshot of the upstream $300M-approved campuses; re-running `energy_grid_planning` at a different `InvestmentLevel` produces a different approved set you can copy in.
+- Adjust the lab roster in `ai_labs.csv`. The anchor flag drives the `DiversityCap` constraint.
+- Replace the GNN with the deterministic fallback by setting `--no-gnn` and editing `workload_utilization_fallback.csv` directly.
+
+### Tune parameters
+
+- Tune the scenario axes: edit `power_envelope_levels.csv`, `margin_floors.csv`, and `diversity_caps.csv`. Adding rows scales the cell count multiplicatively.
+- Change the priority spread by editing the weights in the `# Stage 2: Rules` section (default 100 / 10 / 1).
+
+### Extend the model
+
+- Add a fourth GNN edge type, a new dependency relation, or extra scenario axes; the accretive-ontology pattern means downstream stages pick up new signals without restructuring.
+
+### Scale up / productionize
+
+- Tune the Stage 4 solve by adjusting the solver name or `time_limit_sec` in `problem.solve(...)`. The default works on any prescriptive engine; faster commercial solvers (when licensed) can reach OPTIMAL in a fraction of the time.
+- Replace the bundled CSVs with CDC ingestion from the operator's inventory, telemetry, and contract systems; the ontology shape is independent of the load pipeline.
+
 ## Troubleshooting
 
 <details>
@@ -506,7 +294,7 @@ Some cell's constraints are mutually unsatisfiable AND the C1 P0 commitment is a
 <details>
 <summary>Solver returns <code>TIME_LIMIT</code> with sensible per-cell results</summary>
 
-Expected at the default `time_limit_sec=120`. Per-cell numbers remain valid with `TIME_LIMIT` (`rai-prescriptive-results-interpretation`: `TIME_LIMIT` is signal, not error). Raise `time_limit_sec` or switch to a faster solver in the `# Stage 4: Prescriptive` section if you need a tighter MIP gap.
+Expected at the default `time_limit_sec=240`. Per-cell numbers remain valid with `TIME_LIMIT` (`rai-prescriptive-results-interpretation`: `TIME_LIMIT` is signal, not error). Raise `time_limit_sec` or switch to a faster solver in the `# Stage 4: Prescriptive` section if you need a tighter MIP gap.
 </details>
 
 <details>
diff --git a/v1/defect_root_cause/README.md b/v1/defect_root_cause/README.md
index db1cb219..90bd9cdf 100644
--- a/v1/defect_root_cause/README.md
+++ b/v1/defect_root_cause/README.md
@@ -46,6 +46,7 @@ At a high level, this exercises three RelationalAI capabilities on one shared mo
 ## What's included
 
 - **Model and pipeline** (`defect_root_cause.py`): a single script that defines the ontology and runs all three reasoning stages end to end.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Data generator** (`generate_data.py`): rebuilds the sample corpus deterministically from a fixed seed. The generated files are already included, so you do not need to run it to use the template.
 - **Sample data** (`data/`): ten CSV files describing the product structure, the material lots and their genealogy, the finished units and their test results, the process history, and the list of candidate causes.
 - **Outputs**: the diagnosis is printed to the console and written back into the model as a `DiagnosisResult` summary and an `is_root_cause` flag on each named factor, so the result can be queried after the run rather than only read from the console.
@@ -135,7 +136,7 @@ defect_root_cause/
     └── factors.csv           # 118 candidate causes (lots, machines, and shifts)
 ```
 
-**Start here:** `python defect_root_cause.py` runs the whole pipeline end to end.
+**Start here:** run `python defect_root_cause.py` for the whole pipeline end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Sample data
 
@@ -145,77 +146,17 @@ The bundled corpus is a serialized-unit manufacturing genealogy for a consumer-e
 
 The model represents a manufacturing genealogy: finished units built from material lots through a multi-tier bill of materials, each with a full process history.
 
-The genealogy is the backbone: a built `Lot` consumes its input lots, so following those links from a finished unit reaches every material beneath it. The sections below document the model concept by concept.
+The genealogy is the backbone: a built `Lot` consumes its input lots, so following those links from a finished unit reaches every material beneath it.
 
-### SKU
+- **Key entities**: `SKU`, `Lot`, `Unit`, `Machine`, and `Factor` (a candidate root cause — any lot, machine, or shift, put on a common footing); plus a `DiagnosisResult` summary the prescriptive stage writes back.
+- **Primary identifiers**: every concept carries a string `id` (for example `LOT::SP-0423` on `Factor`); the genealogy and process history are threaded by relationships (`Lot consumes Lot`, `Unit consumes Lot`, `Unit ran on Machine`) rather than shared keys.
+- **Important invariants**: `Unit.defective` is `0` or `1`; `Factor.lift` is the touched-unit defect rate over the plant baseline (≈ 1.0 for non-causal high-volume factors); the `is_root_cause` decision variable is binary; a defective unit is either explained by a named cause it touches or marked unexplained.
 
-An item in the product structure. SKUs, and the bill of materials between them, define the product's type-level structure that the lot genealogy instantiates.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | string | Yes | Loaded from `data/skus.csv` |
-| `name` | string | No | Human-readable name |
-| `tier` | string | No | One of `FINISHED`, `SUBASSEMBLY`, `COMPONENT`, or `RAW` |
-
-### Lot
-
-A specific received or produced batch of a SKU. Lots form the genealogy the diagnosis traces backward.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | string | Yes | Loaded from `data/lots.csv` |
-| `sku` | SKU | No | Which SKU this lot is a batch of |
-| `supplier` | Supplier | No | Who supplied the lot |
-| `received_date` | string | No | When the lot was received; corroborating evidence |
-
-### Unit
-
-A serialized finished unit and its final-test outcome. Defective units are the symptoms the diagnosis must explain.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | string | Yes | Loaded from `data/units.csv` |
-| `sku` | SKU | No | The finished product built |
-| `defective` | int | No | 1 if the unit failed final test, otherwise 0 |
-| `defect_type` | string | No | Failure signature, for example `COLD_SOLDER` |
-| `build_week` | int | No | Week index used by the timeline step |
-| `shift` | string | No | Shift that built the unit |
-
-### Machine
-
-A piece of process equipment. Calibration age corroborates a machine-as-cause finding.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | string | Yes | Loaded from `data/machines.csv` |
-| `machine_type` | string | No | The operation it performs (placement, reflow, assembly, test) |
-| `calibration_age_days` | int | No | Days since last calibration |
-
-### Factor
-
-A candidate root cause: any lot, machine, or shift, put on a common footing so the diagnosis can range over all three. The rules and optimization stages enrich each factor with derived properties.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | string | Yes | Loaded from `data/factors.csv`, for example `LOT::SP-0423` |
-| `kind` | string | No | `LOT`, `MACHINE`, or `SHIFT` |
-| `lift` | float | No | Derived: defect rate among touched units versus the plant baseline |
-| `is_root_cause` | float (binary) | No | Decision variable: named in the diagnosis |
-
-### Relationships
-
-The reasoning relies on a few relations beyond concept properties:
-
-| Relationship | Reading | Notes |
-|---|---|---|
-| `Lot consumes Lot` | parent lot, child lot | The genealogy; closed transitively in the graph stage |
-| `Unit consumes Lot` | unit, lot | Top-tier lots the unit consumed directly |
-| `Unit ran on Machine` | unit, machine | Process history (one per operation) |
-| `Factor touches Unit` | factor, unit | Derived incidence the diagnosis ranges over |
+For the full concept and property definitions — including the relations the reasoning traces (`Lot consumes Lot`, `Unit consumes Lot`, `Unit ran on Machine`, and the derived `Factor touches Unit` incidence) — see `defect_root_cause.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
-This section walks through the highlights in `defect_root_cause.py`. The pipeline moves from the failure timeline to a ranked diagnosis:
+The pipeline moves from the failure timeline to a ranked diagnosis:
 
 ```text
 failure timeline -> genealogy graph -> contrast scoring -> minimal-diagnosis optimization -> ranked root causes
@@ -223,75 +164,21 @@ failure timeline -> genealogy graph -> contrast scoring -> minimal-diagnosis opt
 
 ### Locate the spike onset
 
-First, a real investigation starts on the timeline rather than the genealogy. Rolling failures up by build week locates the onset, the first week whose rate runs well above the opening baseline, which tells the rest of the chain which window to interrogate. Here the rate steps from 1.9 percent in week one to 6.6 percent in week two, so the onset is week two:
-
-```python
-wk = model.select(Unit.build_week.alias("week"), Unit.defective.alias("defective")).to_df()
-wk["defective"] = wk["defective"].astype(int)
-timeline = wk.groupby("week").agg(units=("defective", "size"), defects=("defective", "sum"))
-timeline["rate"] = timeline["defects"] / timeline["units"]
-opening = timeline["rate"].iloc[0]
-onset = next((int(w) for w, r in timeline["rate"].items() if r > 2 * opening), None)
-```
+A real investigation starts on the timeline rather than the genealogy. Rolling failures up by build week locates the onset — the first week whose rate runs well above the opening baseline — which tells the rest of the chain which window to interrogate. Here the rate steps from 1.9 percent in week one to 6.6 percent in week two, so the onset is week two.
 
 ### Trace the genealogy backward (Graph)
 
-Next, the lot genealogy is a directed parent-to-child graph: a built lot consumes its input lots. Closing it transitively with `reachable(full=True)` links each unit to every lot beneath the top-tier lots it consumed, so a contaminated component lot two tiers down is still attributed to every finished unit that carries it:
-
-```python
-graph = Graph(model, directed=True, weighted=False, node_concept=Lot)
-parent, child = Lot.ref(), Lot.ref()
-model.where(parent.consumes(child)).define(graph.Edge.new(src=parent, dst=child))
-
-reach = graph.reachable(full=True)
-
-Unit.touches_lot = model.Relationship(f"{Unit} touches {Lot:lot}")
-model.where((u := Unit.ref()).consumes_lot(top := Lot.ref())).define(Unit.touches_lot(u, top))
-model.where(
-    (u := Unit.ref()).consumes_lot(top := Lot.ref()),
-    reach(top, deep := Lot.ref())
-).define(Unit.touches_lot(u, deep))
-```
-
-A unified `Factor.touches` relationship then puts lots, machines, and shifts on the same footing: lot factors inherit the genealogy closure, while machine and shift factors come straight from process history.
+The lot genealogy is a directed parent-to-child graph: a built lot consumes its input lots. Closing it transitively with `reachable(full=True)` links each unit to every lot beneath the top-tier lots it consumed, so a contaminated component lot two tiers down is still attributed to every finished unit that carries it. A unified `Factor.touches` relationship then puts lots, machines, and shifts on the same footing: lot factors inherit the genealogy closure, while machine and shift factors come straight from process history.
 
 ### Score the candidates (Rules)
 
-Then each candidate is scored by how concentrated defects are among the units it touches. The `lift` is the candidate's defect rate divided by the plant-wide baseline, and a candidate becomes a suspect only when its lift, its support, and its defect count all clear a threshold. This is what screens out the high-coverage, low-lift factors that dominate a raw count but explain nothing:
-
-```python
-model.define(Factor.touched_count(aggs.count(Unit).per(Factor).where(Factor.touches(Unit))))
-model.define(Factor.defect_count(aggs.count(Unit).per(Factor).where(Factor.touches(Unit), Unit.is_defective())))
-model.where(Factor.defect_count > 0).define(
-    Factor.lift((floats.float(Factor.defect_count) / floats.float(Factor.touched_count)) / BASELINE_RATE)
-)
-model.where(
-    Factor.lift >= LIFT_THRESHOLD,
-    Factor.touched_count >= MIN_SUPPORT,
-    Factor.defect_count >= MIN_DEFECTS
-).define(Factor.is_suspect(Factor))
-```
+Each candidate is scored by how concentrated defects are among the units it touches. The `lift` is the candidate's defect rate divided by the plant-wide baseline, and a candidate becomes a suspect only when its lift, its support, and its defect count all clear a threshold. This is what screens out the high-coverage, low-lift factors that dominate a raw count but explain nothing.
 
 ### Find the minimal diagnosis (Prescriptive)
 
-Finally, a binary decision variable names each suspect a root cause, and a binary slack lets a defective unit be left unexplained. The coverage constraint requires every defective unit to be explained by a named cause it touches or else marked unexplained. The objective trades off three things: a cost for each named cause (so the diagnosis stays small), a penalty for naming a cause that also touches many good units (so it stays specific), and a cost for leaving a defect unexplained. Together these make the optimizer prefer the single deep root over the several proximate sub-assemblies that merely carry it:
-
-```python
-problem = Problem(model, Float)
-problem.solve_for(Factor.is_root_cause, where=[Factor.is_suspect()], type="bin", name=["pick", Factor.id])
-problem.solve_for(Unit.unexplained, where=[Unit.is_defective()], type="bin", name=["slack", Unit.id])
-
-cover = problem.satisfy(
-    model.where(Unit.is_defective()).require(
-        (aggs.sum(Factor.is_root_cause).per(Unit).where(Factor.touches(Unit)) | 0) + Unit.unexplained >= 1.0
-    ),
-    name=["cover", Unit.id],
-)
-problem.minimize(
-    aggs.sum(Factor.is_root_cause * Factor.select_cost) + W_UNEXPLAINED * aggs.sum(Unit.unexplained)
-)
-problem.solve("highs", time_limit_sec=120)
-```
+A binary decision variable names each suspect a root cause, and a binary slack lets a defective unit be left unexplained. The coverage constraint requires every defective unit to be explained by a named cause it touches or else marked unexplained. The objective trades off three things: a cost for each named cause (so the diagnosis stays small), a penalty for naming a cause that also touches many good units (so it stays specific), and a cost for leaving a defect unexplained. Together these make the optimizer prefer the single deep root over the several proximate sub-assemblies that merely carry it.
+
+See `defect_root_cause.py` for the implementation and `runbook.md` to reproduce each stage step by step with the RAI skills.
 
 ## Sample output
 
@@ -359,6 +246,12 @@ The diagnosis names a contaminated solder-paste lot (`SP-0423`) and a reflow ove
 - Run `python generate_data.py` to rebuild the sample corpus. Edit the planted causes, decoys, and volumes near the top of the file to author your own scenario.
 - The timeline step is a natural place to add a more formal change-point test; the contrast step is where you would add a statistical significance test alongside the lift threshold.
 
+### Scale up / productionize
+
+- **Point at Snowflake tables.** Swap the CSV loads for `model.Table(...)` references to your traceability tables (genealogy, process history, test results). The graph, rules, and optimization stages are unchanged. Size the prescriptive engine to the number of suspect factors and defective units — the set-cover grows with those, not with total production volume.
+- **Schedule the investigation.** Wire the pipeline into a yield-monitoring cadence so a diagnosis runs whenever the failure timeline crosses its onset threshold, and persist the `DiagnosisResult` and `is_root_cause` flags for downstream review.
+- **Pin dependencies for reproducibility.** Keep the `relationalai` version pinned in `pyproject.toml` and the data-generator seed fixed so a given corpus yields the same diagnosis run to run.
+
 ## Troubleshooting
 
 <details>
@@ -380,7 +273,24 @@ The diagnosis names a contaminated solder-paste lot (`SP-0423`) and a reflow ove
 <details>
   <summary>Why does authentication or configuration fail?</summary>
 
-- Run <code>rai init</code> to create or update <code>raiconfig.toml</code>.
+- Run <code>rai init</code> to create or update <code>raiconfig.yaml</code>.
 - If you have multiple profiles, set <code>RAI_PROFILE</code> or switch profiles in your configuration.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Multi-reasoner workflows](https://docs.relational.ai/) — how graph, rules, and prescriptive stages share one ontology, the pattern this template follows.
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)`, `aggs`, and `.define()`, used throughout the pipeline.
+
+### Reasoner reference
+
+- [Graph reasoner](https://docs.relational.ai/) — `Graph`, edges, and `reachable(full=True)`, the transitive closure behind the genealogy stage.
+- [Rules and derived properties](https://docs.relational.ai/) — deriving `lift` and the `is_suspect` flag from base relations.
+- [Prescriptive reasoner](https://docs.relational.ai/) — `Problem`, decision variables, `satisfy`, and `minimize`, used for the minimal-diagnosis set cover.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/demand_forecasting/README.md b/v1/demand_forecasting/README.md
index 2f3a335b..adddac93 100644
--- a/v1/demand_forecasting/README.md
+++ b/v1/demand_forecasting/README.md
@@ -1,21 +1,19 @@
 ---
 title: "Demand Forecasting"
-description: "Forecast next-period unit sales per (store, item, day) with a regression GNN over a heterogeneous retail graph linking sales to stores, items, and item families."
+description: "Forecast next-period unit sales per store, item, and day with a regression graph neural network (GNN) over a heterogeneous retail graph linking sales to stores, items, and item families."
 featured: false
 experience_level: advanced
 industry: "Retail & Consumer"
 reasoning_types:
   - Predictive
 tags:
-  - GNN
+  - GNN (graph neural network)
   - Regression
   - Demand Forecasting
   - Time Series
   - Retail
 ---
 
-# Demand Forecasting
-
 ## What this template is for
 
 Retail planners forecast unit sales at fine granularity — per store, per item, per day — to drive replenishment, promotions, and labour planning. Classical demand-forecasting models score one (store, item) series in isolation; they miss the fact that store A's sales of bread move with bakery sales across the chain, and that bakery sells through similarly to dairy. This template wires those hierarchies into a **Predictive** reasoner: a regression GNN trained over a heterogeneous Sale → Store, Sale → Item, Item → ItemFamily graph, so the model propagates signal through the store and product hierarchies while predicting per-Sale unit sales.
@@ -38,6 +36,7 @@ Assumes familiarity with Python, basic ML concepts (regression, RMSE), and time-
 ## What's included
 
 - **Runner**: `demand_forecasting.py` — runs the full pipeline (graph build, GNN training, predictions, weekly aggregation) on the bundled CSVs
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Synthetic data generator**: `data/generate_favorita_mini.py` — reproducible Favorita-shaped data generator (run once if you need to regenerate; output is committed under `data/favorita_mini/`)
 - **Model**: `Store`, `Item`, `ItemFamily`, `Sale`, plus three task-table concepts (`TrainTable`, `ValTable`, `TestTable`) carrying the unit-sales targets
 - **Sample data**: bundled synthetic Favorita-shaped dataset (3 stores × 25 items × 365 days); see [Sample data](#sample-data)
@@ -162,6 +161,8 @@ Test-set RMSE (per (city, family, week)): 150.8997
         └── sales.csv               # ~27K daily (store, item, date) rows with unit_sales + onpromotion
 ```
 
+**Start here**: run `python demand_forecasting.py` for the full pipeline — graph build, GNN training, predictions, and weekly aggregation — end to end on the bundled CSVs, or follow `runbook.md` to reproduce it step by step with the RAI skills.
+
 ## Sample data
 
 Two ways to feed this template:
@@ -181,126 +182,57 @@ Customers adapting this template would replace these CSVs with a real Favorita s
 
 ## Model overview
 
-### Key entities
+The model is a small retail ontology whose only purpose is to give the graph neural network (GNN) a heterogeneous neighborhood: sales linked to their store and item, and items rolled up to a family.
 
-- **Store** (`store_id`): one physical retail store with city, state, store type, and a cluster identifier
-- **Item** (`item_id`): one SKU with family, item-class, and a perishable flag
-- **ItemFamily** (`family`): derived from the unique `Item.family` values; gives the GNN a hierarchical edge structure (Item → ItemFamily) that lets signal propagate across items within a family
-- **Sale** (`sale_id`): one row per (store, item, date) with `unit_sales` target and an `onpromotion` flag
+- **Key entities**: `Store`, `Item`, `ItemFamily`, `Sale`, plus three task-table concepts (`TrainTable`, `ValTable`, `TestTable`) that carry the split targets into the trainer.
+- **Primary identifiers**: `Store.store_id`, `Item.item_id`, `Sale.sale_id` (all integers); `ItemFamily.family` (the family string).
+- **Important invariants**: `unit_sales` is a non-negative integer and is the regression target (dropped from features to prevent leakage); every `Sale` links to exactly one `Store` and one `Item`; every `Item` links to exactly one `ItemFamily`; `ItemFamily` is derived from the distinct `Item.family` values rather than loaded.
 
-### Pipeline stages
+For the full concept and property definitions — including the GNN edges (`Sale → Store`, `Sale → Item`, `Item → ItemFamily`) and the Train/Val/Test task relationships — see `demand_forecasting.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ```text
 Stores + Items + Sales (bundled CSVs)
-  → Build heterogeneous graph: Sale → Store, Sale → Item, Item → ItemFamily
-  → Temporal train/val/test split in pandas (last 60 days = test, previous 60 = val)
-  → Predictive: GNN regression on Sale.unit_sales
-  → Reporting: aggregate per-Sale predictions to weekly per-(city, family) forecasts
+  -> Build heterogeneous graph: Sale -> Store, Sale -> Item, Item -> ItemFamily
+  -> Temporal train/val/test split in pandas (last 60 days = test, previous 60 = val)
+  -> Predictive: GNN regression on Sale.unit_sales
+  -> Reporting: aggregate per-Sale predictions to weekly per-(city, family) forecasts
 ```
 
 ## How it works
 
-### 1. Build the heterogeneous graph
+The pipeline builds a heterogeneous graph, trains a regression GNN over it, and aggregates the per-Sale predictions into a weekly forecast.
 
-Each Sale connects to its Store and its Item; each Item connects to its ItemFamily. The GNN aggregates over these neighborhoods so signal propagates: e.g., a Cuenca BAKERY sale's prediction is influenced by other Cuenca sales (via Store), by other items in the BAKERY family (via Item → ItemFamily), and by the broader BAKERY family base rate.
+**Build the heterogeneous graph.** Each Sale connects to its Store and its Item; each Item connects to its ItemFamily. The GNN aggregates over these neighborhoods so signal propagates: a Cuenca BAKERY sale's prediction is influenced by other Cuenca sales (via Store), by other items in the BAKERY family (via Item → ItemFamily), and by the broader BAKERY family base rate.
 
-```python
-gnn_graph = Graph(model, directed=True, weighted=False)
-Edge = gnn_graph.Edge
-model.define(Edge.new(src=Sale, dst=Store)).where(Sale.store_id == Store.store_id)
-model.define(Edge.new(src=Sale, dst=Item)).where(Sale.item_id == Item.item_id)
-model.define(Edge.new(src=Item, dst=ItemFamily)).where(Item.family == ItemFamily.family)
-```
+**Declare features and target.** Primary and foreign keys are dropped because the graph carries identity, and `Sale.unit_sales` is dropped from the features because it is the regression target — keeping it would leak the answer. The remaining columns are declared explicitly as categorical, continuous, integer, or datetime features.
 
-### 2. Declare features and target (PropertyTransformer)
+**Split temporally.** Forecasting requires training on the past and evaluating on the future; a random split would leak future signal into training. The split is done in pandas before the task tables are built — the last 60 days become the test window and the 60 before that the validation window.
 
-PKs / FKs are dropped (the graph carries identity). `Sale.unit_sales` is dropped from features (it's the target — keeping it would leak). Categorical, continuous, integer, and datetime feature types are declared explicitly.
+**Train and predict.** The GNN runs a regression task with `has_time_column=False`, a deliberate simplicity choice (the temporal split is preserved at the pandas level above; the GNN just doesn't use the date as a temporal index inside the graph — see [Customize this template](#customize-this-template) for the temporal-indexing variant). Predictions are attached back to each Sale.
 
-```python
-pt = PropertyTransformer(
-    drop=[
-        Sale.sale_id, Sale.store_id, Sale.item_id,
-        Store.store_id, Item.item_id,
-        Sale.unit_sales,   # target — drop to prevent leakage
-    ],
-    category=[Store.city, Store.state, Store.store_type,
-              Item.family, Item.perishable, Sale.onpromotion],
-    continuous=[Store.cluster],
-    integer=[Item.item_class],
-    datetime=[Sale.date],
-)
-```
-
-### 3. Temporal train / val / test split
+**Aggregate to a weekly forecast.** A single declarative query pulls the per-Sale predictions and joins them to store and item metadata; pandas then rolls them up into weekly per-(city, family) buckets against the actuals.
 
-Forecasting requires a temporal split: training on the past, evaluating on the future. Random splits leak future signal into training. The split is done in pandas before the task tables are built:
-
-```python
-max_date = sales_df["date"].max()
-test_start = max_date - pd.Timedelta(days=TEST_DAYS - 1)
-val_start = test_start - pd.Timedelta(days=VAL_DAYS)
+See `demand_forecasting.py` for the implementation and `runbook.md` to reproduce it step by step with the RAI skills.
 
-train_mask = sales_df["date"] < val_start
-val_mask = (sales_df["date"] >= val_start) & (sales_df["date"] < test_start)
-test_mask = sales_df["date"] >= test_start
-```
+## Customize this template
 
-### 4. Train and predict (GNN regression)
+### Use your own data
 
-```python
-gnn = GNN(
-    exp_database=EXP_DATABASE,
-    exp_schema=EXP_SCHEMA,
-    graph=gnn_graph,
-    property_transformer=pt,
-    train=Train,
-    validation=Val,
-    task_type="regression",
-    eval_metric="rmse",
-    has_time_column=False,
-    seed=SEED,
-    device="cpu",
-    n_epochs=20,
-    lr=0.005,
-)
-gnn.fit()
-Sale.predictions = gnn.predictions(domain=Test)
-```
+- **Repoint to your own retail data** — replace the CSVs under `data/favorita_mini/` with your real store / item / sales exports (matching column names) and re-run.
+- **Add weather, promotions calendar, holiday flags** — extend `Sale` with extra columns and add them to `PropertyTransformer.category` or `.continuous` as appropriate. The same hierarchical-graph plus GNN scaffold absorbs new features without restructuring.
 
-`has_time_column=False` is a deliberate choice — see [Customize this template](#customize-this-template). The temporal split is still preserved at the pandas level above; the GNN just doesn't use the date as a temporal index inside the graph.
+### Tune parameters
 
-### 5. Aggregate to weekly per-(city, family) forecast
+- **Forecast different granularity** — change `TEST_DAYS` / `VAL_DAYS` at the top of the script. Default is a 60-day test window after a 60-day val window.
+- **Use temporal indexing instead** — for tighter holiday/seasonal spike capture, set `has_time_column=True`, restore `time_col=[Sale.date]` in the PropertyTransformer, restore the date arg in the Train/Val/Test relationships (`f"{Sale} at {Any:date} has {Any:value}"`), and add `temporal_strategy="last"` to the `GNN(...)` constructor. Trades simplicity for the GNN aggregating over time windows.
 
-A single declarative query pulls per-Sale predictions and joins them back to store/item metadata; pandas then aggregates to weekly buckets:
+### Extend the model
 
-```python
-sale_ref = Sale.ref()
-predicted_value_ref = Float.ref()
-results_df = (
-    select(
-        sale_ref.sale_id.alias("sale_id"),
-        sale_ref.date.alias("date"),
-        sale_ref.store_id.alias("store_id"),
-        sale_ref.item_id.alias("item_id"),
-        sale_ref.unit_sales.alias("actual"),
-        predicted_value_ref.alias("predicted"),
-    )
-    .where(sale_ref.predictions.predicted_value(predicted_value_ref))
-    .to_df()
-)
-
-# join store + item metadata
-# week_start = results_df["date"].dt.to_period("W").dt.start_time
-# weekly = results_df.groupby(["city", "family", "week_start"])[...].sum()
-```
+- **Bring more hierarchy in** — the bundled data has Item → ItemFamily. Real Favorita data has Item → Class → Family → Department. Define a `Class` and `Department` concept the same way `ItemFamily` is defined, add `Class → Family` and `Family → Department` edges, and the GNN propagates through deeper product hierarchies.
 
-## Customize this template
+### Scale up / productionize
 
-- **Use temporal indexing instead** — for tighter holiday/seasonal spike capture, set `has_time_column=True`, restore `time_col=[Sale.date]` in the PropertyTransformer, restore the date arg in the Train/Val/Test relationships (`f"{Sale} at {Any:date} has {Any:value}"`), and add `temporal_strategy="last"` to the `GNN(...)` constructor. Trades simplicity for the GNN aggregating over time windows.
-- **Forecast different granularity** — change `TEST_DAYS` / `VAL_DAYS` at the top of the script. Default is a 60-day test window after a 60-day val window.
-- **Add weather, promotions calendar, holiday flags** — extend `Sale` with extra columns and add them to `PropertyTransformer.category` or `.continuous` as appropriate. The same hierarchical-graph + GNN scaffold absorbs new features without restructuring.
-- **Bring more hierarchy in** — the bundled data has Item → ItemFamily. Real Favorita data has Item → Class → Family → Department. Define a `Class` and `Department` concept the same way `ItemFamily` is defined, add `Class → Family` and `Family → Department` edges, and the GNN propagates through deeper product hierarchies.
-- **Repoint to your own retail data** — replace the CSVs under `data/favorita_mini/` with your real store / item / sales exports (matching column names) and re-run.
+- **Run on the full public Favorita dataset** — the bundled `favorita_mini` is intentionally tiny so the template runs in minutes on CPU. See the walkthrough below to point the pipeline at the full Kaggle corpus on a GPU-backed engine.
 
 ### Run on the full public Favorita dataset
 
@@ -347,3 +279,22 @@ model = Model("demand_forecasting_local_v2")  # bump on each re-run if needed
 
 - **`subscriber_retention`** — sibling Predictive template using a regression GNN on a homogeneous call graph (no time column); useful as a comparison for the simpler-graph case
 - **`fraud-detection`** — the canonical multi-reasoner GNN template (Graph + Rules + Predictive + Prescriptive); use as the reference for adding a Prescriptive optimization stage on top of forecasting predictions (e.g., truck-routing or replenishment optimization driven by predicted demand)
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.define(...)`, `.where(...)`, and `select(...)`, used to build the graph and pull predictions.
+- [Graph construction](https://docs.relational.ai/) — building the heterogeneous `Graph` and its edges that the GNN aggregates over.
+
+### Reasoner reference
+
+- [Predictive reasoner (GNN)](https://docs.relational.ai/) — `GNN`, `PropertyTransformer`, regression tasks, and temporal handling.
+
+### CLI / SDK guides
+
+- [Setup and configuration](https://docs.relational.ai/) — `rai init`, `raiconfig.yaml`, and granting the Native App access to an experiments schema.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/demand_planning_temporal/README.md b/v1/demand_planning_temporal/README.md
index 1221cd85..e6897444 100644
--- a/v1/demand_planning_temporal/README.md
+++ b/v1/demand_planning_temporal/README.md
@@ -10,11 +10,9 @@ tags:
   - Multi-Period
   - Temporal-Filtering
   - Inventory
-  - LP
+  - LP (linear programming)
 ---
 
-# Demand Planning Temporal
-
 ## What this template is for
 
 Manufacturing and distribution companies must decide how much to produce at each site every week to satisfy customer demand while keeping production and inventory holding costs low. When demand spans many months but the planning team only wants to optimize over a specific window, temporal filtering becomes essential: scope the data to a planning horizon before building the optimization model.
@@ -30,20 +28,18 @@ Prescriptive reasoning makes this practical because the solver simultaneously ba
 - **Data scientists** who need to scope optimization to a configurable date window
 - **Operations researchers** looking for a multi-period flow-conservation pattern in RelationalAI
 
-## What you'll build
+- A cost-minimizing weekly production plan per (site, SKU, week), produced by **prescriptive** decision variables and a HiGHS solve.
+- A date-filtered planning horizon: only demand orders inside the configured window enter the model, with due dates mapped to integer week periods via `std.common.range()`.
+- An inventory schedule that satisfies flow conservation (`inv[t] = inv[t-1] + production[t] - demand[t]`) enforced as prescriptive constraints.
+- A service-level guarantee (a 95% minimum-fulfillment constraint) plus an unmet-demand report showing whether any demand went unserved.
+- A three-scenario what-if sweep that shows how total cost changes as the planning horizon extends, all sharing one model.
 
-- Load sites, SKUs, demand orders, production capacity, and initial inventory from CSV files
-- Filter demand orders to a configurable planning horizon using date comparisons
-- Map due dates to integer week numbers for use with `std.common.range()`
-- Define continuous decision variables for production quantities, inventory levels, and unmet demand
-- Enforce inventory flow conservation: `inv[t] = inv[t-1] + production[t] - demand[t]`
-- Set a 95% minimum service level constraint on total demand fulfillment
-- Minimize total cost (production + holding + unmet-demand penalty) using `model.union()` to combine per-entity costs
-- Solve with HiGHS and inspect the production plan, inventory levels, and unmet demand
+Built using **prescriptive reasoning**: continuous decision variables for production, inventory, and unmet demand; a multi-period flow-conservation constraint; and a total-cost objective assembled with `model.union()`.
 
 ## What's included
 
 - **Script**: `demand_planning_temporal.py` -- end-to-end model, solve, and results
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Data**: `data/sites.csv`, `data/skus.csv`, `data/demand_orders.csv`, `data/production_capacity.csv`, `data/initial_inventory.csv`
 - **Config**: `pyproject.toml`
 
@@ -90,34 +86,16 @@ Prescriptive reasoning makes this practical because the solver simultaneously ba
    python demand_planning_temporal.py
    ```
 
-6. Expected output:
+6. Expected output. Each scenario prints its status, cost, and plan; the run ends with a summary sweep. A few representative lines confirm a successful run:
+
    ```text
    Running scenario: planning_end = 2026-01-31
      Status: OPTIMAL
      Total cost: $26,137.50
      Planning horizon: 2025-11-01 to 2026-01-31 (14 weeks)
      Demand orders in scope: 14 (of 25 total)
-     === Production Plan (non-zero weeks) ===
-     === Inventory Levels (selected weeks) ===
-     === Unmet Demand ===
-     All demand fulfilled!
-
-   Running scenario: planning_end = 2026-02-28
-     Status: OPTIMAL
-     Total cost: $30,863.50
-     Planning horizon: 2025-11-01 to 2026-02-28 (18 weeks)
-     Demand orders in scope: 18 (of 25 total)
-     ...
      All demand fulfilled!
-
-   Running scenario: planning_end = 2026-03-31
-     Status: OPTIMAL
-     Total cost: $34,768.00
-     Planning horizon: 2025-11-01 to 2026-03-31 (22 weeks)
-     Demand orders in scope: 20 (of 25 total)
-     ...
-     All demand fulfilled!
-
+   ...
    ==================================================
    Scenario Analysis Summary
    ==================================================
@@ -127,133 +105,86 @@ Prescriptive reasoning makes this practical because the solver simultaneously ba
    ```
 
    Extending the planning horizon from January to March increases cost from
-   $26,138 to $34,768 as more demand orders come into scope (14 to 20).
+   $26,138 to $34,768 as the horizon lengthens (14 to 22 weeks, 14 to 20
+   demand orders); demand is met entirely from opening inventory, so the
+   increase is holding cost accrued over the longer horizon.
    All demand is fulfilled in every scenario -- no unmet demand penalties.
 
 ## Template structure
 
 ```text
 .
-├── README.md
-├── pyproject.toml
-├── demand_planning_temporal.py
+├── README.md                     # this file
+├── pyproject.toml                # dependencies
+├── demand_planning_temporal.py   # end-to-end model, scenario sweep, solve, results
 └── data/
-    ├── sites.csv
-    ├── skus.csv
-    ├── demand_orders.csv
-    ├── production_capacity.csv
-    └── initial_inventory.csv
+    ├── sites.csv                 # warehouse/distribution sites
+    ├── skus.csv                  # products with unit and holding costs
+    ├── demand_orders.csv         # dated demand orders (Oct 2025 - Mar 2026)
+    ├── production_capacity.csv    # per-(site, SKU) weekly capacity and production cost
+    └── initial_inventory.csv     # per-(site, SKU) starting inventory
 ```
 
-## How it works
+**Start here**: run `python demand_planning_temporal.py` to solve all three horizon scenarios end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-### 1. Scenario loop -- sweep planning horizons
+## Sample data
 
-The script sweeps over three `planning_end` dates to analyze how the planning horizon affects cost. Each iteration filters demand orders to the horizon, recomputes week mappings, and solves a fresh problem:
+The bundled data is a small, illustrative multi-site production dataset covering three warehouse sites and two SKUs, with demand orders spanning October 2025 through March 2026. It is synthetic and sized to run the temporal-filtering and multi-period optimization pattern quickly, not to match any real plant.
 
-```python
-planning_start = "2025-11-01"
-SCENARIO_VALUES = ["2026-01-31", "2026-02-28", "2026-03-31"]
+- **`sites.csv`** — warehouse/distribution sites (`Chicago_DC`, `Atlanta_DC`, …) with a weekly throughput capacity.
+- **`skus.csv`** — products (`Widget_A`, `Widget_B`) with a unit cost and a weekly holding cost.
+- **`demand_orders.csv`** — dated demand orders (`id`, `sku_id`, `site_id`, `quantity`, `due_date`); only orders inside the configured horizon enter each scenario.
+- **`production_capacity.csv`** — per-(site, SKU) maximum weekly production and production cost.
+- **`initial_inventory.csv`** — per-(site, SKU) starting inventory, used as the week-0 condition.
 
-for scenario_value in SCENARIO_VALUES:
-    planning_end = scenario_value
-    filtered_orders = orders_df[
-        (orders_df["due_date"] >= planning_start)
-        & (orders_df["due_date"] <= planning_end)
-    ].copy()
-```
+## Model overview
 
-This removes orders outside the horizon so the solver only sees relevant demand.
+The model is a multi-period production and inventory ontology. Sites and SKUs are reference entities; demand orders are the dated event table that temporal filtering scopes; production capacity carries the pre-joined data the solver's decision variables attach to.
 
-### 2. Date-to-period mapping -- convert dates to integer weeks
+- **Key entities**: `Site`, `SKU`, `DemandOrder`, `ProdCapacity`, and `WeeklyDemand` (a per-scenario concept that pre-aggregates orders into weekly buckets, including zero-demand weeks).
+- **Primary identifiers**: `Site.id` and `SKU.id` (integers); `DemandOrder.id` (integer); the composite key `ProdCapacity(site_id, sku_id)`; the composite key `WeeklyDemand(wk_site_id, wk_sku_id, wk_week_num)`.
+- **Important invariants**: quantities, costs, production, and inventory are non-negative; inventory obeys flow conservation (`inv[t] = inv[t-1] + production[t] - demand[t]`); week 0 inventory equals the initial inventory; unmet demand per order is bounded by the order quantity; total unmet demand is capped by the 95% service level.
 
-`std.common.range()` requires integer periods. Inside each scenario iteration, the script computes the number of weeks and converts each order's due date into a week number relative to the planning start:
+For the full concept and property definitions — including the time-indexed `x_production` / `x_inventory` decision variables on `ProdCapacity` and the relationships linking orders and capacity to their `Site` and `SKU` — see `demand_planning_temporal.py`; `runbook.md` builds them step by step with the RAI skills.
 
-```python
-    start_date = datetime.strptime(planning_start, "%Y-%m-%d")
-    end_date = datetime.strptime(planning_end, "%Y-%m-%d")
-    num_weeks = int((end_date - start_date).days / 7) + 1
+## How it works
 
-    filtered_orders["week_num"] = (
-        (filtered_orders["due_date"] - pd.Timestamp(planning_start)).dt.days // 7 + 1
-    ).astype(int)
-```
+**Sweep planning horizons.** The script loops over three `planning_end` dates to analyze how the horizon length affects cost. Each iteration filters demand orders to the window (dropping orders outside it so the solver sees only relevant demand), recomputes the week mapping, and solves a fresh problem.
 
-The number of weeks varies by scenario (e.g. 13 weeks for January, 18 for February, 22 for March).
-
-### 3. Multi-arity decision variables indexed by time
-
-Production and inventory variables are indexed by both concept (site x SKU) and time period. The `x_production` variable uses a multi-arity property pattern:
-
-```python
-ProdCapacity.x_production = Property(
-    f"{ProdCapacity} in week {Integer:t} produces {Float:production}"
-)
-production_ref = Float.ref()
-problem.solve_for(
-    ProdCapacity.x_production(week_ref, production_ref),
-    type="cont",
-    lower=0,
-    upper=ProdCapacity.max_production_per_week,
-    name=["prod", ProdCapacity.site_id, ProdCapacity.sku_id, week_ref],
-    where=[week_ref == weeks],
-)
-```
+**Map dates to integer weeks.** `std.common.range()` requires integer periods, so each order's due date is converted into a week number relative to the planning start, and the number of weeks is derived from the horizon length. The week count varies by scenario (14 weeks for January, 18 for February, 22 for March).
 
-This creates one continuous variable per (site, SKU, week) combination.
+**Index decision variables by time.** Production and inventory variables are indexed by both concept (site × SKU) and time period via a multi-arity property pattern, creating one continuous variable per (site, SKU, week) combination, bounded by the per-line weekly capacity.
 
-### 4. Flow conservation constraint
+**Enforce flow conservation.** The core multi-period constraint ties adjacent weeks together: inventory at the end of week `t` equals inventory at the end of week `t-1` plus production in week `t` minus demand in week `t`. A `WeeklyDemand` concept pre-aggregates orders into weekly buckets — including zero-demand weeks — so the constraint covers every period.
 
-The core multi-period pattern ties adjacent weeks together. Inventory at the end of week `t` must equal inventory at the end of week `t-1` plus production in week `t` minus demand in week `t`:
+**Minimize total cost.** The objective combines production cost, holding cost, and an unmet-demand penalty from different concepts using `model.union()`, and the solver minimizes their sum subject to the flow-conservation and service-level constraints.
 
-```python
-problem.satisfy(model.where(
-    ProdCapacity.x_inventory(week_ref, x_inv_curr),
-    ProdCapacity.x_inventory(week_ref - 1, x_inv_prev),
-    ProdCapacity.x_production(week_ref, production_ref),
-    WeeklyDemand.wk_site_id == ProdCapacity.site_id,
-    WeeklyDemand.wk_sku_id == ProdCapacity.sku_id,
-    WeeklyDemand.wk_week_num == week_ref,
-    week_ref >= 1,
-).require(
-    x_inv_curr == x_inv_prev + production_ref - WeeklyDemand.wk_quantity
-))
-```
+The script also includes a commented-out Pattern B for data that carries Unix epoch-second timestamps instead of date strings: convert the horizon boundaries to epochs and filter identically.
 
-A `WeeklyDemand` concept pre-aggregates orders into weekly buckets (including zero-demand weeks) so the constraint covers every period.
+See `demand_planning_temporal.py` for the implementation and `runbook.md` to reproduce it step by step with the RAI skills.
 
-### 5. Cost objective with model.union()
+## Customize this template
 
-The objective combines three cost components from different concepts using `model.union()`:
+### Use your own data
 
-```python
-prod_cost = ProdCapacity.production_cost * sum(production_ref).per(ProdCapacity).where(...)
-hold_cost = ProdCapacity.holding_cost_per_week * sum(inventory_ref).per(ProdCapacity).where(...)
-unmet_cost = unmet_penalty * DemandOrder.x_unmet
+- **Add more sites or SKUs**: Append rows to `sites.csv`, `skus.csv`, `production_capacity.csv`, and `initial_inventory.csv`. The model generalizes to any number of site-SKU combinations.
+- **Switch to epoch timestamps**: Follow the commented Pattern B code to adapt the template for data with Unix epoch integer columns.
 
-problem.minimize(sum(model.union(prod_cost, hold_cost, unmet_cost)))
-```
+### Tune parameters
 
-### Epoch timestamp alternative
+- **Change the planning horizon**: Edit `planning_start` and the `SCENARIO_VALUES` list to shift the optimization window. Values must be in increasing date order (each scenario extends the previous horizon). The week count and date filter update automatically per scenario.
+- **Adjust service level**: Change `min_service_level` (default 0.95) to require higher or lower demand fulfillment.
+- **Adjust safety stock**: The `safety_stock_weeks` parameter (default 1) requires inventory at the end of each week to be at least `safety_stock_weeks × average weekly demand` per site-SKU pair. Set to 0 to disable, or increase for more conservative buffering.
 
-The script includes commented-out examples of Pattern B (epoch integer timestamps). If your data uses Unix epoch seconds instead of date strings, convert the planning horizon boundaries to epochs and filter identically:
+### Extend the model
 
-```python
-start_epoch = int(datetime.strptime(planning_start, "%Y-%m-%d").timestamp())
-end_epoch = int(datetime.strptime(planning_end, "%Y-%m-%d").timestamp()) + 86399
-filtered_orders = orders_df[
-    (orders_df["created_at"] >= start_epoch) &
-    (orders_df["created_at"] <= end_epoch)
-].copy()
-```
+- Add new cost components (for example a per-site fixed operating cost) as additional terms in the `model.union()` objective, following the `prod_cost` / `hold_cost` / `unmet_cost` pattern.
+- Add new constraints (for example a per-site total-capacity cap across SKUs) with additional `problem.satisfy(...)` calls alongside the flow-conservation constraint.
 
-## Customize this template
+### Scale up / productionize
 
-- **Change the planning horizon**: Edit `planning_start` and the `SCENARIO_VALUES` list to shift the optimization window. Values must be in increasing date order (each scenario extends the previous horizon). The week count and date filter update automatically per scenario.
-- **Add more sites or SKUs**: Append rows to `sites.csv`, `skus.csv`, `production_capacity.csv`, and `initial_inventory.csv`. The model generalizes to any number of site-SKU combinations.
-- **Adjust service level**: Change `min_service_level` (default 0.95) to require higher or lower demand fulfillment.
-- **Adjust safety stock**: The `safety_stock_weeks` parameter (default 1) requires inventory at the end of each week to be at least `safety_stock_weeks × average weekly demand` per site-SKU pair. Set to 0 to disable, or increase for more conservative buffering.
-- **Switch to epoch timestamps**: Follow the commented Pattern B code to adapt the template for data with Unix epoch integer columns.
+- The scenario sweep shares one model across horizons; for production, replace the CSV loads with Snowflake-backed `model.data(...)` sources and schedule the run.
+- Solve time is controlled by `time_limit_sec` on `problem.solve("highs", ...)`; raise it if larger site/SKU/week grids need more time.
 
 ## Troubleshooting
 
@@ -285,3 +216,19 @@ Verify that `planning_start` and the `SCENARIO_VALUES` dates overlap with the `d
 
 Ensure your Snowflake account has the RAI Native App installed and your user has the required permissions. Run `rai init` to configure your connection profile. See the [RelationalAI documentation](https://docs.relational.ai) for setup details.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — concepts, properties, `model.define(...)`, and `model.where(...)`, used to load and link the entities.
+- [Temporal periods with `std.common.range()`](https://docs.relational.ai/) — building the integer week ranges the multi-period variables and constraints index over.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) — `Problem`, `solve_for` decision variables, `satisfy` constraints, `minimize` objectives, and `model.union()`.
+- [Solver management](https://docs.relational.ai/) — configuring the HiGHS solve and `time_limit_sec`.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/diet/README.md b/v1/diet/README.md
index 52fea1aa..1b2d6f57 100644
--- a/v1/diet/README.md
+++ b/v1/diet/README.md
@@ -12,15 +12,11 @@ tags:
   - Scenario Analysis
 ---
 
-# Diet Optimization
-
 ## What this template is for
 
-Choosing a balanced diet that meets nutritional requirements while staying within a budget is a classic optimization problem. Given a set of foods with known costs and nutrient contents, and a set of nutrients with minimum and maximum daily intake bounds, the goal is to find the cheapest combination of foods that satisfies all nutritional constraints.
-
-This template uses **Prescriptive** reasoning to formulate and solve the diet problem as a linear program. Each food has a continuous decision variable representing how much of it to include. Constraints enforce that the total nutrient intake from the selected foods falls within the required bounds for every nutrient.
+Choosing a balanced diet that meets nutritional requirements while staying within a budget is a classic optimization problem. Given a set of foods with known costs and nutrient contents, and a set of nutrients with minimum and maximum daily intake bounds, the goal is to find the cheapest combination of foods that satisfies all nutritional constraints. It also shows how the same model answers a "what if" question — how cost moves as requirements tighten or loosen — without re-modeling anything.
 
-The template also demonstrates scenario analysis by scaling nutritional requirements up and down (0.8x, 1.0x, 1.2x) and solving independently for each scenario. This lets you compare how dietary cost changes as requirements become more or less restrictive.
+**The template uses prescriptive reasoning to formulate the diet problem as a linear program and solve several requirement scenarios in a single solve.**
 
 ## Who this is for
 
@@ -31,16 +27,19 @@ The template also demonstrates scenario analysis by scaling nutritional requirem
 
 ## What you'll build
 
-- A linear programming model that selects foods to minimize total cost
-- Nutritional constraints ensuring minimum and maximum daily intake for calories, protein, fat, and sodium
-- Scenario analysis that scales nutritional requirements and compares results across scenarios
+- A least-cost diet plan — the amount of each food that meets every nutrient bound at minimum total cost — produced by **prescriptive reasoning** (a linear program).
+- Nutritional constraints holding total intake within minimum and maximum daily bounds for calories, protein, fat, and sodium.
+- A scenario comparison showing how least-cost changes as requirements scale, built with a first-class `Scenario` concept so all cases solve at once.
+
+Built using **prescriptive reasoning** (linear programming with continuous decision variables and a `Scenario` concept for multi-case solves).
 
 ## What's included
 
-- `diet.py` -- Main script defining the optimization model, constraints, and scenario analysis
-- `data/foods.csv` -- Food items with cost and nutrient content per serving
-- `data/nutrients.csv` -- Nutrient names with minimum and maximum daily intake bounds
-- `pyproject.toml` -- Python package configuration with dependencies
+- **Model**: two concepts (`Food`, `Nutrient`), a `Scenario` concept, per-food decision variables, nutrient-bound constraints, and a cost-minimizing objective — all in `diet.py`.
+- **Runner**: `diet.py`, a single Python script that runs end-to-end against a Snowflake-connected RAI account.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: `data/foods.csv` (foods with cost and per-nutrient content) and `data/nutrients.csv` (nutrient min/max bounds).
+- **Outputs**: per-scenario termination status, objective cost, and a table of the foods (and amounts) in each least-cost basket, printed to stdout.
 
 ## Prerequisites
 
@@ -84,143 +83,94 @@ The template also demonstrates scenario analysis by scaling nutritional requirem
    python diet.py
    ```
 
-6. Expected output:
+6. Expected output — a few lines confirm a successful run:
+
    ```text
-   Running scenario: nutrient_scaling = 0.8
-     Status: OPTIMAL, Objective: $6.53
-     Diet plan:
-        name  value
-     chicken   0.52
-        milk  10.41
-    icecream   1.37
-
-   Running scenario: nutrient_scaling = 1.0
-     Status: OPTIMAL, Objective: $8.20
-     Diet plan:
-        name  value
-     chicken   0.65
-        milk  13.01
-    icecream   1.71
-
-   Running scenario: nutrient_scaling = 1.2
-     Status: OPTIMAL, Objective: $9.87
-     Diet plan:
-        name  value
-     chicken   0.78
-        milk  15.62
-    icecream   2.06
-
-   ==================================================
-   Scenario Analysis Summary
-   ==================================================
-     scaling=0.8: OPTIMAL, cost=$6.53
-     scaling=1.0: OPTIMAL, cost=$8.20
-     scaling=1.2: OPTIMAL, cost=$9.87
+   Solve result:
+   • status: OPTIMAL
+   • objective: 35.49
+
+   Diet plan per scenario (0.8 / 1.0 / 1.2 demand): the same baseline
+   basket — hamburger + icecream + milk — scaled per scenario, for a
+   per-scenario cost of $9.46 / $11.83 / $14.19.
    ```
 
+   The full per-scenario diet plan prints above; see `runbook.md` for the complete log.
+
 ## Template structure
 
 ```text
 .
-├── README.md
-├── pyproject.toml
-├── diet.py
+├── README.md          # this file
+├── runbook.md         # step-by-step analyst walkthrough
+├── pyproject.toml     # dependencies
+├── diet.py            # main script (model, constraints, scenarios, solve)
 └── data/
-    ├── foods.csv
-    └── nutrients.csv
+    ├── foods.csv      # foods with cost and per-nutrient content
+    └── nutrients.csv  # nutrient min/max bounds
 ```
 
-## How it works
+**Start here**: run `python diet.py` for the full model and scenario solve end to end, or follow `runbook.md` to rebuild it step by step.
 
-### 1. Define concepts and map data
+## Sample data
 
-The model defines two concepts: `Nutrient` (with min/max bounds) and `Food` (with cost and nutrient content). A ternary property links each food to its nutrient quantities:
+The bundled data is small and illustrative — a handful of foods and four nutrients, sized to teach the linear-program formulation, not to represent a clinically complete diet.
 
-```python
-Nutrient = model.Concept("Nutrient", identify_by={"name": String})
-Nutrient.min = model.Property(f"{Nutrient} has {Float:min}")
-Nutrient.max = model.Property(f"{Nutrient} has {Float:max}")
+- **`data/foods.csv`** — one row per food, with a `cost` per serving and one column per nutrient (`calories`, `protein`, `fat`, `sodium`) giving that food's content per serving. Each food's nutrient columns must match the nutrient `name`s in `nutrients.csv`.
+- **`data/nutrients.csv`** — one row per nutrient, with `min` and `max` daily-intake bounds. The scenario scaling factor multiplies these bounds up and down.
 
-Food = model.Concept("Food", identify_by={"name": String})
-Food.cost = model.Property(f"{Food} has {Float:cost}")
-Food.contains = model.Property(f"{Food} contains {Nutrient} in {Float:qty}")
-```
+## Model overview
 
-### 2. Decision variables
+The model is small and self-contained: two source concepts plus a `Scenario` concept that parameterizes the solve.
 
-Each food gets a continuous decision variable representing the amount to include in the diet:
+- **Key entities**: `Food` — a food with a per-serving cost and a per-nutrient content, carrying a continuous decision variable for the amount to include; `Nutrient` — a nutrient with minimum and maximum daily-intake bounds (the constraint bounds, scaled per scenario); and `Scenario` — a requirement-scaling case that scales every nutrient bound by its factor, with all scenarios solving together in one solve.
+- **Primary identifiers**: `Food.name` and `Nutrient.name` (both strings); `Scenario.scenario_name` (string).
+- **Important invariants**: nutrient `min` and `max` bounds are non-negative and `min <= max`; each food's decision amount is non-negative (`lower=0`); each food's per-nutrient content is keyed by a nutrient that exists in `nutrients.csv`.
 
-```python
-Food.x_amount = model.Property(f"{Food} has {Float:amount}")
-problem.solve_for(Food.x_amount, name=Food.name, lower=0, populate=False)
-```
+For the full concept and property definitions, see `diet.py`; `runbook.md` builds them step by step with the RAI skills.
 
-### 3. Constraints and objective
+## How it works
 
-Nutritional constraints ensure total intake from all foods falls within bounds for each nutrient. The objective minimizes total food cost:
+The model reads two source tables, adds a scenario axis, and hands a single parameterized linear program to the prescriptive solver:
 
-```python
-nutrient_qty = Float.ref()
-nutrient_total = sum(nutrient_qty * Food.x_amount).where(Food.contains(Nutrient, nutrient_qty)).per(Nutrient)
-problem.satisfy(model.require(
-    nutrient_total >= Nutrient.min * scenario_value,
-    nutrient_total <= Nutrient.max * scenario_value
-))
-problem.minimize(sum(Food.cost * Food.x_amount))
+```text
+foods.csv + nutrients.csv → concepts → decision variables → constraints + objective → multi-scenario solve → per-scenario baskets
 ```
 
-### 4. Scenario analysis
+1. **Define concepts and map data.** `Nutrient` carries min/max daily-intake bounds; `Food` carries a per-serving cost and a per-nutrient content (a ternary `contains` property linking each food to a nutrient quantity).
 
-The template solves three scenarios by scaling nutritional requirements to 80%, 100%, and 120% of their base values, demonstrating how tighter or looser requirements affect total cost.
+2. **Decision variables.** Each food gets a continuous, non-negative decision variable — the amount to include in the diet — created per scenario so all cases share one formulation.
 
-### 5. Inspect the model schema
+3. **Constraints and objective.** For each nutrient, total intake across foods (quantity times amount, summed) must fall between the scenario-scaled min and max bounds. The objective minimizes total cost (cost times amount, summed over foods).
 
-`relationalai.semantics.inspect` (available in `relationalai>=1.0.14`) surfaces a typed view of the registered concepts, properties, relationships, and data sources. It's handy for sanity-checking a model before handing it to the solver:
+4. **Scenario analysis.** A first-class `Scenario` concept scales every nutrient bound by a factor (0.8 / 1.0 / 1.2 here), so tighter and looser requirements solve together in a single solve and their costs are directly comparable.
 
-```python
-from relationalai.semantics import inspect
+The prescriptive decision variable appears in the model schema alongside the source-data properties — a unified view of everything the model knows, including variables added by `solve_for()`. See `diet.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
-print(inspect.schema(model))
-```
+## Customize this template
 
-Excerpt of the user-declared part of the output:
+Focus on the first changes most users will make.
 
-```text
-Model: diet
-===========
-
-  Nutrient
-    Identity:
-      name: String
-    Properties:
-      min: Float
-      max: Float
-
-  Food
-    Identity:
-      name: String
-    Properties:
-      cost: Float
-      contains(Nutrient) -> Float
-      x_amount(Scenario) -> Float
-
-  Scenario
-    Identity:
-      scenario_name: String
-    Properties:
-      nutrient_scaling: Float
-```
+### Use your own data
 
-Notice that the prescriptive decision variable (`Food.x_amount(Scenario) -> Float`) appears alongside the source-data properties -- the schema is a unified view of everything the model knows, including variables added by `solve_for()`.
+- Replace `data/foods.csv` and `data/nutrients.csv` with your own; keep the column names described in *Sample data* above. Each food's nutrient columns must match the nutrient `name`s in `nutrients.csv` — the model reads one food column per nutrient row.
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)` calls.
 
-After calling `Problem(...)` and `problem.solve_for / satisfy / minimize`, the prescriptive reasoner also registers root concepts named `Variable`, `Expression`, `Constraint`, and `Objective` (plus per-solve `Variable_<id>` subconcepts). They appear below the user-declared concepts in the full output; filter them out with a list-based check if you want a user-facing view (see the `machine_maintenance` template for the recipe).
+### Tune parameters
 
-## Customize this template
+- Edit the scenario rows in `diet.py` (the `("scaling_80pct", 0.8)`, `("baseline", 1.0)`, `("scaling_120pct", 1.2)` tuples) to test different scaling factors, or add rows for finer resolution.
+- Adjust the solver time limit (`time_limit_sec`) if you scale up to many foods and nutrients.
+
+### Extend the model
+
+- Add dietary preferences: introduce upper bounds on specific foods (for example, limiting red meat), or add binary variables to model food inclusion/exclusion.
+- Weight the objective: add a secondary term to penalize undesirable foods alongside cost minimization.
+- Add a second scenario axis (for example, budget caps) as another `Scenario`-style concept.
 
-- **Add more foods or nutrients**: Extend the CSV files with additional rows and columns. The model automatically picks up new data.
-- **Change scenario parameters**: Modify `SCENARIO_VALUES` to test different scaling factors or introduce entirely different scenario dimensions (e.g., budget caps).
-- **Add dietary preferences**: Introduce upper bounds on specific foods (e.g., limit red meat) or add binary variables to model food inclusion/exclusion.
-- **Weight objectives**: Add a secondary objective term to penalize undesirable foods alongside cost minimization.
+### Scale up / productionize
+
+- Pin `relationalai` and schedule the run as a pipeline step for reproducible, deterministic re-runs.
+- Size the prescriptive engine up if the food and nutrient counts grow the linear program substantially.
 
 ## Troubleshooting
 
@@ -247,3 +197,23 @@ Make sure you activated the virtual environment and ran `python -m pip install .
 
 Foods with zero in the solution are not cost-effective given the constraints. This is expected behavior. If you want to force inclusion of specific foods, add a minimum bound on their decision variables.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)` / `model.select(...)` / `.per(...)` and result extraction.
+- [Concepts and properties](https://docs.relational.ai/) — modeling entities like `Food` and `Nutrient` with typed properties.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) — `Problem` API, decision variables, constraints, and objectives.
+- [Scenario modeling](https://docs.relational.ai/) — parameterizing one solve across cases with a `Scenario` concept.
+
+### CLI / SDK guides
+
+- [RelationalAI setup](https://docs.relational.ai/) — `rai init`, profiles, and `raiconfig.yaml`.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/disease-outbreak-prevention/README.md b/v1/disease-outbreak-prevention/README.md
index f34cdae3..3cd90db5 100644
--- a/v1/disease-outbreak-prevention/README.md
+++ b/v1/disease-outbreak-prevention/README.md
@@ -29,29 +29,34 @@ By analyzing a network of hospitals, clinics, testing centers, and community org
 
 ## What you'll build
 
-- Load a public health network with 10 facilities and 15 directed connections with transfer volume and contact intensity metrics
-- Use RelationalAI's Graph API to model the healthcare network with weighted edges
-- Calculate risk-weighted degree centrality for each facility based on connection weights (transfer_volume × contact_intensity)
-- Track incoming and outgoing connections (indegree and outdegree)
-- Rank facilities by their cumulative risk (weighted degree centrality scores)
-- Identify top priority facilities for resource deployment
-- Generate a detailed prioritized list to guide outbreak response decisions
+- A risk-weighted facility ranking — every facility scored by weighted degree centrality (`transfer_volume x contact_intensity` summed over its edges) — produced by **graph analysis**.
+- Per-facility connectivity signals: incoming and outgoing connection counts (indegree and outdegree) alongside the centrality score.
+- A prioritized shortlist of the highest-risk facilities to guide where limited outbreak-response resources go first.
+- An optional interactive Streamlit view of the same ranking, with a network visualization and CSV export.
 
-This template uses **RelationalAI's graph modeling** capabilities with the Graph class to represent the network, and built-in weighted graph algorithms to compute degree centrality that accounts for transmission risk factors.
+Built using **graph analysis** (a directed, weighted graph with `Facility` as the node concept and built-in weighted degree centrality).
 
 ## What's included
 
-- **Shared model setup**: `model_setup.py` - Common model configuration and graph creation (used by both scripts)
-- **Command-line script**: `disease_outbreak_prevention_network.py` - CLI analysis script with detailed output
-- **Interactive app**: `app.py` - Streamlit web application with visualizations and interactive analysis
-- **Data**: `data/facilities.csv` and `data/connections.csv`
+- **Model**: shared setup in `model_setup.py` — the `Facility` concept, the `FacilityConnection` edge concept (with `transfer_volume`, `contact_intensity`, and a derived `risk_weight`), and the directed weighted `Graph` built from them.
+- **Runner**: `disease_outbreak_prevention_network.py` (command-line analysis with detailed output) and `app.py` (optional Streamlit web app), both driven by the same shared model.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: `data/facilities.csv` and `data/connections.csv`.
+- **Outputs**: a ranked facility table, a top-priority breakdown, and network summary statistics printed to stdout; the Streamlit app adds an interactive network graph and CSV export.
 
 ## Prerequisites
 
-- Python >= 3.10
+### Access
+
 - A Snowflake account that has the RAI Native App installed.
 - A Snowflake user with permissions to access the RAI Native App.
 
+### Tools
+
+- Python >= 3.10
+- RelationalAI Python SDK (`relationalai == 1.11.0`).
+- Optional: `streamlit`, `plotly`, `numpy` for the interactive app (installed via the `visualization` extra).
+
 ## Quickstart
 
 Follow these steps to run the template with the included sample data.
@@ -114,132 +119,101 @@ You can customize the data and model as needed after you have it running end-to-
    - Detailed priority facility analysis
    - CSV export functionality
 
-## How it works
+6. Expected output — a few lines confirm a successful run:
+
+   ```text
+   Top facilities by weighted degree centrality (transmission risk):
+     1. Central Hospital        260
+     2. Public Health Dept      260
+     3. Regional Testing Lab    218
+     4. Emergency Response Hub  188
+   ```
+
+   The full ranked table, top-priority breakdown, and network summary print above and below this; see `runbook.md` for the complete walkthrough.
 
-The template follows this flow:
+## Template structure
 
 ```text
-CSV files → model_setup.create_model() → Calculate metrics → Analyze strategic priorities → Display results
+disease-outbreak-prevention/
+  disease_outbreak_prevention_network.py  # main CLI analysis script
+  app.py                                  # optional Streamlit web app
+  model_setup.py                          # shared model + graph setup (used by both)
+  data/
+    facilities.csv                        # 10 facilities (id, name, type, region)
+    connections.csv                       # 15 directed connections with risk metrics
+  README.md                               # this file
+  runbook.md                              # step-by-step analyst walkthrough
+  pyproject.toml                          # dependencies
 ```
 
-### 1. Shared Model Setup
+**Start here**: run `python disease_outbreak_prevention_network.py` for the full ranking end to end, or follow `runbook.md` to rebuild it step by step.
 
-Both the CLI script and Streamlit app use the same model setup from `model_setup.py`:
+## Sample data
 
-```python
-from model_setup import create_model
+The bundled data is small and illustrative — a 10-facility regional health network, sized to teach the weighted-centrality flow, not to match a specific jurisdiction's network.
 
-# Create the model, concepts, relationships, and graph (all in one call)
-model, graph, Facility = create_model()
-```
+- **`data/facilities.csv`** (10 rows) — one row per facility, with `id`, `name`, `type` (hospital, clinic, testing center, government, emergency services), and `region`.
+- **`data/connections.csv`** (15 rows) — one row per directed connection, with `from_facility_id`, `to_facility_id`, `transfer_volume`, and `contact_intensity`. The model derives each connection's `risk_weight` as `transfer_volume x contact_intensity`. Every id must reference a valid facility in `facilities.csv`.
 
-The `create_model()` function handles:
-- Creating the RelationalAI model container
-- Defining the `Facility` concept with all properties
-- Loading facilities from CSV
-- Defining the `FacilityConnection` concept for edges with transfer_volume, contact_intensity, and risk_weight properties
-- Loading connections from CSV with their risk metrics
-- Calculating risk_weight as transfer_volume × contact_intensity for each connection
-- Creating the directed, weighted graph using risk_weight as edge weights
-- Returning all components for use in analysis
+## Model overview
 
-### 2. Calculate Graph Metrics
+The model is a directed, weighted graph with one node concept and one edge concept.
 
-Use RelationalAI's Graph API to define weighted centrality metrics:
+- **Key entities**: `Facility` — a healthcare facility, testing center, or community organization (the graph's node); `FacilityConnection` — a directed transfer link between two facilities, weighted by transmission risk (the graph's edge).
+- **Primary identifiers**: `Facility.id` (integer); `FacilityConnection` is identified by its `(from_facility, to_facility)` pair.
+- **Important invariants**: `transfer_volume` and `contact_intensity` are non-negative; `risk_weight` is derived, not loaded (`transfer_volume x contact_intensity`); every connection endpoint references an existing `Facility`.
 
-```python
-# Weighted degree centrality (sum of risk-weighted edge weights)
-degree_centrality = graph.degree_centrality()
+For the full concept and property definitions, see `model_setup.py`; `runbook.md` builds them step by step with the RAI skills.
 
-# Incoming edges (indegree count)
-incoming_edges = graph.indegree()
+## How it works
 
-# Outgoing edges (outdegree count)
-outgoing_edges = graph.outdegree()
-```
+Both runners share one model builder, then compute weighted centrality on the resulting graph and rank facilities:
 
-The weighted degree centrality incorporates the risk weights (transfer_volume × contact_intensity) from each edge, providing a measure of cumulative transmission risk rather than just connectivity count.
-
-### 3. Query and Rank Facilities
-
-Query the graph to retrieve all metrics and rank facilities:
-
-```python
-from relationalai.semantics import where, Float, Integer
-
-# Create variable references
-facility = graph.Node.ref("facility")
-centr_score = Float.ref("centr_score")
-in_edges = Integer.ref("in_edges")
-out_edges = Integer.ref("out_edges")
-
-# Query the graph
-results = where(
-    degree_centrality(facility, centr_score),
-    incoming_edges(facility, in_edges),
-    outgoing_edges(facility, out_edges)
-).select(
-    facility.id,
-    facility.name,
-    facility.type,
-    facility.region,
-    centr_score.alias("degree_centrality"),
-    in_edges.alias("incoming_connections"),
-    out_edges.alias("outgoing_connections")
-).to_df()
-
-# Sort by degree centrality (descending)
-results = results.sort_values("degree_centrality", ascending=False)
-results.insert(0, "rank", range(1, len(results) + 1))
+```text
+CSV files → model_setup.create_model() → weighted centrality + degree metrics → rank facilities → display / export
 ```
 
-### 4. CLI Script Analysis
+1. **Shared model setup.** `model_setup.create_model()` builds everything both runners need in one call: the RelationalAI model, the `Facility` node concept, the `FacilityConnection` edge concept, the CSV loads, the derived `risk_weight` (`transfer_volume x contact_intensity`), and the directed, weighted graph that uses `risk_weight` as its edge weight.
 
-The `disease_outbreak_prevention_network.py` script displays:
-- A ranked table of all facilities with their metrics
-- Detailed breakdown of the top 3 priority facilities
-- Network-wide summary statistics
-- Actionable recommendations for outbreak response
+2. **Calculate graph metrics.** The Graph API computes weighted degree centrality (summing risk-weighted edges, so the score reflects cumulative transmission risk rather than a raw connection count) alongside indegree and outdegree counts.
 
-### 5. Interactive Streamlit App
+3. **Query and rank.** A single query pulls each facility's identity, type, region, centrality score, and in/out connection counts, then sorts descending by centrality to produce the ranked shortlist.
 
-The included `app.py` provides an interactive web interface using the same shared model:
+4. **Present results.** The CLI script prints the ranked table, a top-priority breakdown, network summary statistics, and response recommendations. The optional Streamlit app renders the same ranking as an interactive network graph with a filterable table and CSV export.
 
-```python
-import streamlit as st
-from model_setup import create_model
+See `model_setup.py` and `disease_outbreak_prevention_network.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
-# Load the same model and query results
-model, graph, Facility = create_model()
-results = get_results(model, graph, Facility)
-```
+## Customize this template
 
-The Streamlit app features:
-- **Interactive network graph**: Directed edges with arrows, hover for facility details, region-based layout
-- **Filterable rankings table**: Filter by facility type and region, download as CSV
-- **Priority facility analysis**: Expandable sections with detailed metrics and role analysis
-- **Summary statistics**: Sidebar with key network metrics
+Focus on the first changes most users will make.
 
-## Customize this template
+### Use your own data
+
+- Replace the CSV files in `data/` with your own network, keeping the same column names (or update the loading logic in `model_setup.py`).
+- Make sure every facility referenced in `connections.csv` is a valid id in `facilities.csv`.
+- For Snowflake-backed runs, swap the `pd.read_csv(...)` calls in `model_setup.py` for `model.data(snowflake_table)` calls.
 
-**Use your own data:**
+### Tune parameters
 
-- Replace the CSV files in the `data/` directory with your own network, keeping the same column names (or update the logic in disease_outbreak_prevention_network.py).
-- Make sure that the facilities in **connections.csv** only references valid facility IDs.
+- The risk formula is `risk_weight = transfer_volume x contact_intensity`, defined in `model_setup.py`. Change how the two factors combine (for example, a weighted average) to reweight what "risk" means.
+- Switch the graph's centrality metric if you want a different notion of importance (for example, betweenness or eigenvector centrality) in place of weighted degree.
 
-**Extend the model:**
+### Extend the model
 
-**Add more risk factors**: The template already uses weighted connections (transfer_volume × contact_intensity). You could extend this by:
-- Adding additional risk metrics to connections (e.g., disease prevalence, facility bed capacity)
-- Creating a more sophisticated risk formula (e.g., weighted average of multiple factors)
-- Adding temporal aspects (e.g., seasonal variation in transmission rates)
+- Add more risk factors to `FacilityConnection` (for example, disease prevalence or facility bed capacity) and fold them into `risk_weight`.
+- Add temporal aspects (for example, seasonal variation in transmission rates) as additional edge properties.
+
+### Scale up / productionize
+
+- Replace the CSV bundle with CDC ingestion from your health-network systems; the graph shape is independent of the load pipeline.
+- Pin `relationalai` (this template targets `1.11.0`) and schedule the run as a pipeline step for reproducible re-runs.
 
 ## Troubleshooting
 
 <details>
   <summary>Why does authentication/configuration fail?</summary>
 
-- Run `rai init` to create/update `raiconfig.toml`.
+- Run `rai init` to create/update `raiconfig.yaml`.
 - If you have multiple profiles, set `RAI_PROFILE` or switch profiles in your config.
 
 </details>
@@ -247,7 +221,33 @@ The Streamlit app features:
 <details>
   <summary>Why does the script fail to connect to the RAI Native App?</summary>
 
-- Verify the Snowflake account/role/warehouse and `rai_app_name` are correct in `raiconfig.toml`.
+- Verify the Snowflake account/role/warehouse and `rai_app_name` are correct in `raiconfig.yaml`.
 - Ensure the RAI Native App is installed and you have access.
 
-</details>
\ No newline at end of file
+</details>
+
+<details>
+  <summary>Why is the Streamlit app missing dependencies?</summary>
+
+- Install the visualization extra: `python -m pip install .[visualization]` (adds `streamlit`, `plotly`, `numpy`).
+
+</details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — `where(...)` / `select(...)` and result extraction.
+- [Concepts and relationships](https://docs.relational.ai/) — modeling entities and edges like `Facility` and `FacilityConnection`.
+
+### Reasoner reference
+
+- [Graph reasoner](https://docs.relational.ai/) — node-concept and edge-concept patterns, degree centrality, and other graph algorithms.
+
+### CLI / SDK guides
+
+- [RelationalAI setup](https://docs.relational.ai/) — `rai init`, profiles, and `raiconfig.yaml`.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
\ No newline at end of file
diff --git a/v1/energy_grid_planning/README.md b/v1/energy_grid_planning/README.md
index 4c9c3fe2..614e50e5 100644
--- a/v1/energy_grid_planning/README.md
+++ b/v1/energy_grid_planning/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Energy Grid Planning"
-description: "AI data center interconnection planning on the ERCOT (Texas) grid: demand forecasting, grid-vulnerability analysis, compliance rules, and multi-objective optimization."
+description: "Plan how to connect AI data centers to the Electric Reliability Council of Texas (ERCOT) power grid. Forecasts demand, finds vulnerable parts of the grid, applies compliance rules, and balances competing objectives to recommend where to interconnect."
 featured: true
 experience_level: intermediate
 industry: "Energy & Utilities"
@@ -27,29 +27,10 @@ A defensible answer needs all four signals at once: which substations will run o
 
 ## Why this problem matters
 
-ERCOT -- the Electric Reliability Council of Texas -- operates an isolated grid that is not interconnected with the Eastern or Western Interconnections. This isolation means Texas cannot import power from neighboring grids during demand spikes, making capacity planning uniquely consequential. Winter Storm Uri (2021) demonstrated the vulnerability: grid failures cascaded without external relief, causing widespread blackouts.
+ERCOT -- the Electric Reliability Council of Texas -- operates an isolated grid not interconnected with the Eastern or Western Interconnections, so Texas cannot import power during demand spikes. That makes capacity planning uniquely consequential, as Winter Storm Uri (2021) showed when grid failures cascaded without external relief.
 
 Texas is now the fastest-growing market for AI data center development. Hyperscalers are requesting multi-hundred-megawatt interconnections at substations designed for decades of steady organic growth. The ERCOT grid must absorb 2,930 MW of new data center load -- equivalent to roughly 3 nuclear reactors -- while maintaining reliability for 30 million existing customers.
 
-This is not a single-reasoner problem. Approving a data center at a structurally critical substation like Dallas-Fort Worth (graph) without sufficient capacity headroom (predictive) violates reliability rules (rules) and may not be economically justified at lower budget levels (prescriptive). The value of the multi-reasoner approach is that each stage's output constrains the next -- predictions inform rules, rules inform optimization, and the optimizer respects all upstream signals.
-
-## Reasoner overview: inputs, outputs, and role
-
-| Stage | Reasoner | Reads from ontology | Writes to ontology | Role |
-|-------|----------|--------------------|--------------------|------|
-| 1. Predict | **Predictive** | `DemandForecast` table (historical load + DC announcements) | `Substation.predicted_load` (derived Property) | Forecast which substations hit capacity limits. DFW breaches at 24 months (54.6% growth); Houston, San Antonio, Austin grow 32-44% but remain within capacity. |
-| 2. Graph | **Graph** (WCC, Louvain, centrality) | `Substation` nodes, `TransmissionLine` edges | `Substation.betweenness`, `.grid_community` (Properties), `Substation.is_structurally_critical` (Relationship) | Map ERCOT grid topology into 3 regions (North Texas, West Texas, Gulf Coast). DFW and Houston are the top structural bottlenecks. 7 of 10 DC requests target critical substations. |
-| 3. Paths | **Graph** (paths, PREVIEW) | `Substation.betweenness` (Stage 2), `connects_to` grid edges | `Substation.fragility_load` (Property) | Score the most-fragile generator-to-DC transmission corridor by betweenness summed along the route. The most fragile carries a betweenness-load of 99.833 through Dallas-Fort Worth / Abilene Central / Houston Ship Channel. |
-| 4. Rules | **Rules** (declarative) | `predicted_load` (Stage 1), `is_structurally_critical` (Stage 2), DC request properties | `DataCenterRequest.fails_capacity`, `.fails_structural`, `.fails_low_carbon`, `.is_compliant` (Relationships) | Check each request against interconnection compliance. 2 compliant (Crusoe, Oracle), 8 flagged. Every flag is a derived Relationship consuming upstream enrichments. |
-| 5. Prescriptive | **Prescriptive** (MIP, Scenario Concept) | `predicted_load` (Stage 1), `InvestmentLevel` budget scenarios, upgrade costs/capacities | `DataCenterRequest.x_approve`, `SubstationUpgrade.x_upgrade` per InvestmentLevel (Properties) | Jointly optimize approvals + upgrades across budget levels. One solve produces the full Pareto frontier. Knee at $300M (5 DCs, $264M net value). All results queryable via `model.select()`. |
-
-**Key design patterns demonstrated:**
-- **Accretive ontology enrichment** -- each stage writes derived properties that downstream stages consume as first-class ontology attributes. Stage 1's `predicted_load` flows into both Stage 4 rules and Stage 5 optimization constraints, ensuring consistent capacity signals across the pipeline.
-- **Multi-scenario / multi-objective via Scenario Concept** -- `InvestmentLevel` is a Scenario Concept: 5 budget entities ($200M-$600M) that parameterize the optimization. One MIP solve produces the entire Pareto frontier simultaneously (not a re-solve loop). Decision variables `x_approve` and `x_upgrade` are indexed per InvestmentLevel, and results are queryable ontology properties -- not parsed from solver output.
-- **Ontology as shared state** -- each stage writes derived properties/relationships that downstream stages read; no Python dicts or DataFrames carry state between stages
-- **Graph directly on domain concept** -- the Graph reasoner uses `Substation` as its node concept, so centrality and community results are stored as native Substation properties with no mirror concept or enrichment rules
-- **Marginal analysis from ontology queries** -- the per-level DC approvals, upgrade selections, and net value are all queried from the ontology via `model.select(...).where(x_approve > 0.5)` per InvestmentLevel, enabling marginal return analysis across the frontier
-
 ## Who this is for
 
 - Utility planners and grid operators managing interconnection queues (especially ERCOT)
@@ -70,6 +51,7 @@ This is not a single-reasoner problem. Approving a data center at a structurally
 ## What's included
 
 - `energy_grid_planning.py` -- Main script with five chained reasoning stages
+- `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself
 - `data/substations.csv` -- 12 Texas substations with capacity, load, and coordinates
 - `data/generators.csv` -- 15 generators (2 nuclear: STP + Comanche Peak, plus gas, coal, wind, solar, battery)
 - `data/transmission_lines.csv` -- 18 transmission lines forming a connected ERCOT grid
@@ -200,254 +182,52 @@ Optional GNN training splits, **not loaded by the main script**: `train_forecast
 
 ## Model overview
 
-One shared ontology threads all four stages. Each stage reads concepts and properties earlier stages wrote, and writes new ones for downstream stages — the accretive-enrichment pattern described above.
+One shared ontology threads all five stages. Each stage reads concepts and properties earlier stages wrote, and writes new ones for downstream stages — the accretive-enrichment pattern described above.
 
 - **Key entities**: `Substation`, `Generator`, `TransmissionLine`, `DataCenterRequest`, `SubstationUpgrade`, `DemandForecast`; plus the Stage 5 Scenario Concept `InvestmentLevel` and the results concept `InvestmentPortfolio`. Supporting concepts (`LoadZone`, `DemandPeriod`, `RenewableProfile`, `MaintenanceWindow`, `Customer`, `LoadHistory`, `DCAnnouncement`) mirror their CSVs and back the aggregations.
 - **Primary identifiers**: string `id` on the base entities (e.g. `SUB-001`, `TL-001`); `name` on `InvestmentLevel` (e.g. `"$300M"`); `investment_level_name` on `InvestmentPortfolio`.
 - **Important invariants**: `predicted_load`, `max_capacity_mw`, `current_load_mw`, `requested_mw`, and `capacity_increase_mw` are non-negative MW; `low_carbon_requirement_pct` is a percentage; a generator is low-carbon when `emissions_rate == 0`; Stage 5 decision variables (`x_approve`, `x_upgrade`) are binary.
 
-### Concepts
-
-**`Substation`** — a grid node. The hub of the model: Stages 1-3 enrich it with forecast, topology, and corridor-fragility properties that Stages 4-5 consume.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | String | Yes | `ID` from `data/substations.csv` |
-| `name` | String | No | Human-readable name |
-| `voltage_kv` | Float | No | Operating voltage |
-| `max_capacity_mw` | Float | No | Capacity ceiling |
-| `current_load_mw` | Float | No | Present load (fallback when no forecast) |
-| `latitude`, `longitude` | Float | No | Coordinates |
-| `predicted_load` | Float | No | **Stage 1** max forecast per substation |
-| `grid_community` | Integer | No | **Stage 2** Louvain region label |
-| `betweenness`, `degree_centrality`, `eigenvector_centrality` | Float | No | **Stage 2** centrality scores |
-| `betweenness_rank`, `degree_rank`, `eigenvector_rank`, `combined_rank`, `critical_rank` | Integer | No | **Stage 2** rank derivations |
-| `is_structurally_critical` | Relationship | — | **Stage 2** top-`CRITICAL_THRESHOLD` flag |
-| `connects_to` | Relationship | — | **Stage 3** bidirectional substation-to-substation grid edge |
-| `fragility_load` | Float | No | **Stage 3** (PREVIEW) most-fragile corridor's summed betweenness |
-| `low_carbon_gen_mw`, `total_gen_mw` | Float | No | **Stage 4** per-substation generation aggregates |
-
-**`Generator`** — a generation unit connected to a substation. Stage 4's low-carbon rule sums its capacity by emissions.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | String | Yes | `ID` from `data/generators.csv` |
-| `name`, `gen_type` | String | No | `gen_type` is one of nuclear/gas/coal/wind/solar/battery/hydro |
-| `capacity_mw`, `min_output_mw`, `ramp_rate_mw_per_hr` | Float | No | Output characteristics |
-| `startup_cost`, `marginal_cost` | Float | No | Cost characteristics |
-| `min_up_time_hrs`, `min_down_time_hrs` | Integer | No | Commitment constraints |
-| `emissions_rate` | Float | No | tons/MWh; `0` means low-carbon |
-| `is_renewable` | Boolean | No | Renewable flag |
-| `substation` | Relationship | — | Link to hosting `Substation` |
-
-**`TransmissionLine`** — a directed line between two substations; the Stage 2 graph edges (when `is_active`).
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | String | Yes | `ID` from `data/transmission_lines.csv` |
-| `from_substation` | Relationship | — | Origin `Substation` |
-| `to_substation` | Relationship | — | Terminating `Substation` |
-| `capacity_mw`, `length_km`, `impedance` | Float | No | Line characteristics |
-| `is_active` | Boolean | No | Only active lines become graph edges |
-| `maintenance_priority` | String | No | `high` / `medium` / `low` |
-
-**`DataCenterRequest`** — a hyperscaler interconnection request targeting one substation. The MIP approves a subset; Stage 4 flags compliance.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | String | Yes | `ID` from `data/data_center_requests.csv` |
-| `name`, `hyperscaler` | String | No | Project and operator |
-| `requested_mw` | Float | No | Interconnection size |
-| `substation` | Relationship | — | Target `Substation` |
-| `annual_revenue_per_mw` | Float | No | Interconnection capacity revenue ($/MW/yr) |
-| `pue` | Float | No | Power usage effectiveness |
-| `is_ai_workload` | Boolean | No | AI workload flag |
-| `cooling_type` | String | No | Cooling technology |
-| `low_carbon_requirement_pct` | Float | No | Required low-carbon generation fraction |
-| `queue_position` | Integer | No | Interconnection-queue order |
-| `status` | String | No | Request status |
-| `fails_capacity`, `fails_structural`, `fails_low_carbon`, `is_compliant` | Relationship | — | **Stage 4** compliance flags |
-| `x_approve` | Float | No | **Stage 5** binary approval per `InvestmentLevel` |
-
-**`SubstationUpgrade`** — a candidate capacity upgrade on one substation. The MIP's build decisions.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | String | Yes | `ID` from `data/substation_upgrades.csv` |
-| `substation` | Relationship | — | Upgraded `Substation` |
-| `capacity_increase_mw` | Float | No | MW added if built |
-| `cost_million` | Float | No | Cost in $M |
-| `lead_time_months` | Integer | No | Build lead time |
-| `enables_low_carbon` | Boolean | No | Whether it unlocks low-carbon supply |
-| `x_upgrade` | Float | No | **Stage 5** binary build decision per `InvestmentLevel` |
-
-**`DemandForecast`** — a per-substation load forecast at a horizon. Stage 1 aggregates the max per substation into `Substation.predicted_load`.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | String | Yes | `ID` from `data/demand_forecasts.csv` |
-| `substation` | Relationship | — | Forecasted `Substation` |
-| `forecast_period` | Integer | No | Horizon in months (6/12/18/24) |
-| `predicted_load_mw` | Float | No | Forecasted load |
-| `confidence` | Float | No | Forecast confidence |
-| `includes_dc_growth` | Boolean | No | Whether DC growth is folded in |
-
-**`InvestmentLevel`** — the Stage 5 Scenario Concept; 5 budget entities ($200M-$600M) that parameterize one MIP solve into a Pareto frontier.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `name` | String | Yes | Budget label (e.g. `"$300M"`) |
-| `budget_cap` | Float | No | Upgrade-spend ceiling in $M |
-
-**`InvestmentPortfolio`** — one results row per `InvestmentLevel`, materialized after the solve so the Pareto frontier is queryable as ontology rather than parsed from solver output.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `investment_level_name` | String | Yes | Matches the `InvestmentLevel.name` |
-| `investment_level` | Relationship | — | Link to the `InvestmentLevel` |
-| `dc_count` | Integer | No | DCs approved at this level |
-| `total_mw` | Float | No | Approved MW |
-| `annual_revenue` | Float | No | Annual interconnection revenue |
-| `upgrade_cost` | Float | No | Upgrade spend (dollars) |
-| `net_value` | Float | No | Revenue minus amortized upgrade cost |
-| `marginal_per_m_to_next_level` | Float | No | Marginal net value per $M to the next level |
-| `is_knee_point` | Boolean | No | Pareto-frontier knee flag |
-
-The Stage 3 paths analysis also derives two transient sub-concepts, `GeneratorSubstation` and `DCSubstation` (both `extends=[Substation]`), to type the corridor endpoints — substations hosting a generator (source) and substations hosting a DC request (sink).
-
-### Relationships
-
-- `Generator.substation -> Substation` — each generator's hosting substation; Stage 3 sums generation per substation along it.
-- `TransmissionLine.from_substation` / `.to_substation -> Substation` — directed grid edge; active lines become the Stage 2 graph edges.
-- `Substation.connects_to -> Substation` — **Stage 3** bidirectional substation-to-substation edge derived from active transmission lines; the corridor enumeration walks it.
-- `DataCenterRequest.substation -> Substation` — the substation a request targets; the capacity, structural, and low-carbon rules all join through it.
-- `SubstationUpgrade.substation -> Substation` — the substation an upgrade expands; the Stage 5 capacity constraint nets its `capacity_increase_mw` against load.
-- `DemandForecast.substation -> Substation` — the forecasted substation; Stage 1's `aggs.max(...).per(Substation)` reads it.
-- `InvestmentPortfolio.investment_level -> InvestmentLevel` — links each results row to its budget scenario.
+`Substation` is the hub: Stages 1-3 enrich it with forecast, topology, and corridor-fragility properties that Stages 4-5 consume. The Stage 3 paths analysis also derives two transient sub-concepts, `GeneratorSubstation` and `DCSubstation` (both `extends=[Substation]`), to type the corridor endpoints. For the full concept and property definitions, see `energy_grid_planning.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
-### Stage 1: Predict -- Substation Load Forecasting
+One shared ontology threads all five stages. Each stage reads properties earlier stages wrote and writes new ones for downstream stages — the accretive-enrichment pattern, so capacity, criticality, and compliance signals stay consistent end to end without DataFrame hand-offs.
 
-Derives `Substation.predicted_load` as an ontology property from the `DemandForecast` table using `aggs.max().per(Substation)`. Substations near announced data center projects show 32-55% growth depending on location and announced capacity. Dallas-Fort Worth is the only substation predicted to breach capacity (1,700 MW predicted vs 1,600 MW capacity at 24 months, 54.6% growth). Houston Ship Channel shows the highest absolute load (1,797 MW) but remains within its larger capacity. This predicted load feeds both Stage 4's capacity rule and Stage 5's capacity constraint -- the first link in the accretive chain. Because both downstream reasoners read `predicted_load` as a first-class ontology attribute, changing the demand forecast automatically propagates through the rules engine and optimizer without any code changes.
-
-The `predicted_load` derived property aggregates the max forecasted load per substation:
-
-```python
-Substation.predicted_load = model.Property(f"{Substation} has {Float:predicted_load}")
-model.define(
-    Substation.predicted_load(
-        aggs.max(DemandForecast.predicted_load_mw)
-        .where(DemandForecast.substation(Substation))
-        .per(Substation)
-    )
-)
+```text
+demand forecasts → predicted_load → grid topology + centrality → corridor fragility
+   → compliance rules → multi-objective MIP → Pareto frontier
 ```
 
-### Stage 2: Graph -- Grid Topology & Structural Vulnerability
-
-The Graph reasoner uses `Substation` directly as its node concept — no mirror concept needed. Edges connect substations that share an active transmission line. Centrality and community results are stored as native Substation properties. Computes:
-- Weakly connected components (grid connectivity -- confirms all 12 substations are reachable)
-- Louvain community detection (3 ERCOT regions: North Texas, West Texas, Gulf Coast)
-- Betweenness, degree, and eigenvector centrality combined into a critical rank
-- 7 of 10 DC requests target structurally critical substations -- a key input to the rules engine
+### Stage 1: Predict -- Substation Load Forecasting
 
-```python
-grid_graph = Graph(
-    model, directed=False, weighted=False, node_concept=Substation, aggregator="sum"
-)
+Derives `Substation.predicted_load` as an ontology property by taking the max `DemandForecast` per substation. Substations near announced data center projects show 32-55% growth; Dallas-Fort Worth is the only substation predicted to breach capacity (1,700 MW predicted vs 1,600 MW capacity at 24 months, 54.6% growth), while Houston Ship Channel shows the highest absolute load (1,797 MW) but stays within its larger capacity. Because both downstream reasoners read `predicted_load` as a first-class attribute, changing the forecast propagates through the rules engine and optimizer without code changes — the first link in the accretive chain.
 
-line_ref = TransmissionLine.ref()
-model.define(
-    grid_graph.Edge.new(src=line_ref.from_substation, dst=line_ref.to_substation)
-).where(line_ref.is_active == True)
+### Stage 2: Graph -- Grid Topology & Structural Vulnerability
 
-community = grid_graph.louvain()
-betweenness = grid_graph.betweenness_centrality()
-```
+The Graph reasoner uses `Substation` directly as its node concept, with edges between substations that share an active transmission line, and stores results back as native `Substation` properties. It computes weakly connected components (confirming all 12 substations are reachable), Louvain community detection (3 ERCOT regions), and betweenness/degree/eigenvector centrality combined into a critical rank. 7 of 10 DC requests target structurally critical substations — a key input to the rules engine.
 
 ### Stage 3: Paths -- Transmission Corridors & Contingency
 
 > PREVIEW capability; requires `relationalai>=1.15`.
 
-Where Stage 2 scores a *substation*, the **Graph** paths capability scores the *corridor* feeding each data center. It derives a bidirectional substation-to-substation edge from active transmission lines, enumerates generator-substation to DC-substation routes, and ranks each by the Stage 2 betweenness summed along its hops — the most fragile corridor is the one carrying the greatest through-traffic exposure. A contingency pass removes the highest-betweenness substation and re-enumerates to show which data centers reroute. The most-fragile load is persisted as `Substation.fragility_load`. On the bundled grid this enumerates 421 generator-to-DC corridors; the most fragile carries a betweenness-load of 99.833 through the Dallas-Fort Worth, Abilene Central, and Houston Ship Channel hubs.
-
-```python
-corridor_df = model.where(
-    corridor := model.path(
-        corridor_src, Substation.connects_to.repeat(1, MAX_CORRIDOR_HOPS), corridor_dst
-    ).all_paths(),
-).select(
-    corridor.alias("corridor"),
-    corridor.nodes["index"].alias("hop"),
-    Substation(corridor.nodes).id.alias("substation_id"),
-    Substation(corridor.nodes).name.alias("substation_name"),
-).to_df()
-```
+Where Stage 2 scores a *substation*, the paths capability scores the *corridor* feeding each data center. It derives a bidirectional substation-to-substation edge from active transmission lines, enumerates generator-substation to DC-substation routes, and ranks each by the Stage 2 betweenness summed along its hops — the most fragile corridor carries the greatest through-traffic exposure. A contingency pass removes the highest-betweenness substation and re-enumerates to show which data centers reroute; the most-fragile load is persisted as `Substation.fragility_load`. On the bundled grid this enumerates 421 generator-to-DC corridors; the most fragile carries a betweenness-load of 99.833 through the Dallas-Fort Worth, Abilene Central, and Houston Ship Channel hubs.
 
 ### Stage 4: Rules -- Interconnection Queue Compliance
 
-Three declarative rules (RAI Relationships) consume upstream outputs:
-- **Capacity check**: `requested_mw + predicted_load > max_capacity_mw` (uses Stage 1). Most requests fail because the existing grid lacks headroom for new AI load without upgrades.
-- **Structural risk**: DC request targets a structurally critical substation (uses Stage 2 centrality). 7 of 10 requests fail this check.
-- **Low-carbon mandate**: substation's low-carbon generation fraction < DC's requirement (nuclear + renewable). All requests pass -- ERCOT's nuclear plants (STP, Comanche Peak) and extensive wind/solar fleet provide sufficient low-carbon generation.
-- **Composite**: `is_compliant` = passes all checks. Only Crusoe Permian DC and Oracle Coastal DC are fully compliant.
-
-The capacity rule demonstrates the accretive pattern, consuming `predicted_load` from Stage 1 with a fallback to `current_load_mw`:
-
-```python
-DataCenterRequest.fails_capacity = model.Relationship(f"{DataCenterRequest} fails capacity check")
-SubRef_rule = Substation.ref()
-effective_load_rule = SubRef_rule.predicted_load | SubRef_rule.current_load_mw
-model.where(
-    DataCenterRequest.substation(SubRef_rule),
-    DataCenterRequest.requested_mw + effective_load_rule > SubRef_rule.max_capacity_mw,
-).define(DataCenterRequest.fails_capacity())
-```
+Three declarative rules consume upstream outputs, then a composite flag combines them:
+- **Capacity check**: `requested_mw + predicted_load > max_capacity_mw` (uses Stage 1, with a `current_load_mw` fallback). Most requests fail — the existing grid lacks headroom for new AI load without upgrades.
+- **Structural risk**: request targets a structurally critical substation (uses Stage 2 centrality). 7 of 10 requests fail.
+- **Low-carbon mandate**: substation's low-carbon generation fraction below the DC's requirement. All requests pass — ERCOT's nuclear plants (STP, Comanche Peak) and wind/solar fleet supply enough low-carbon generation.
+- **Composite**: `is_compliant` passes all checks. Only Crusoe Permian DC and Oracle Coastal DC are fully compliant.
 
 ### Stage 5: Prescriptive -- Multi-Objective Optimization
 
-Uses the **InvestmentLevel Scenario Concept** pattern:
-- 5 budget levels ($200M-$600M) as Scenario entities
-- Binary variables `x_approve` and `x_upgrade` indexed by InvestmentLevel
-- Substation capacity constraints use `predicted_load` from Stage 1 (not raw historical load), ensuring the optimizer sees the same forecasted headroom as the rules engine
-- Budget constraints scoped `.per(InvestmentLevel)`
-- Revenue values reflect annual interconnection capacity revenue ($145K-$210K per MW/yr), not energy revenue
-- One solve produces the entire Pareto frontier -- the knee point at $300M (5 DCs, 1,500 MW, $264M net value) shows the highest marginal return, unlocking xAI Colossus ($105M/yr) as the single highest-revenue request
-- At $200M, 4 DCs are approved (Microsoft, CoreWeave, Crusoe, Oracle); each additional $100M budget increment adds 1 more DC with diminishing marginal returns ($995K/$M at the knee vs $400K/$M at $600M)
-- Google Metroplex DC (400 MW) and Lambda Labs DFW (200 MW) are never approved at any budget level -- DFW substation capacity is fully consumed
-- Per-level details (which DCs approved, which upgrades selected, upgrade MW) are all queried from the ontology via `model.select()`, not parsed from solver output
-- All decision variables (`x_approve`, `x_upgrade`) are ontology properties indexed by InvestmentLevel, making the full Pareto frontier queryable without any output parsing
-
-The `Problem` setup defines the InvestmentLevel Scenario Concept with binary decision variables, and the capacity constraint uses `predicted_load` from Stage 1:
-
-```python
-problem = Problem(model, Float)
-
-problem.solve_for(DataCenterRequest.x_approve(InvestmentLevel, x_a), type="bin",
-            name=["approve", InvestmentLevel.name, DataCenterRequest.id])
-problem.solve_for(SubstationUpgrade.x_upgrade(InvestmentLevel, x_u), type="bin",
-            name=["upgrade", InvestmentLevel.name, SubstationUpgrade.id])
-
-# C1: Substation capacity per investment level
-# Uses predicted_load from Stage 1 (with current_load fallback) — the accretive chain.
-x_a_c = Float.ref("xa_c")
-x_u_c = Float.ref("xu_c")
-effective_load = Substation.predicted_load | Substation.current_load_mw
-
-problem.satisfy(model.where(
-    DataCenterRequest.x_approve(InvestmentLevel, x_a_c),
-    SubstationUpgrade.x_upgrade(InvestmentLevel, x_u_c),
-    DataCenterRequest.substation(Substation),
-    SubstationUpgrade.substation(Substation),
-).require(
-    Substation.max_capacity_mw - effective_load
-    + sum(x_u_c * UpgRef.capacity_increase_mw).where(
-        UpgRef.substation == Substation).per(Substation, InvestmentLevel)
-    >= sum(x_a_c * DCRef.requested_mw).where(
-        DCRef.substation == Substation).per(Substation, InvestmentLevel)
-))
-```
+An `InvestmentLevel` Scenario Concept holds 5 budget levels ($200M-$600M), each parameterizing one MIP solve into a Pareto frontier. Binary variables `x_approve` (per DC request) and `x_upgrade` (per substation upgrade) are indexed by investment level; substation-capacity constraints use `predicted_load` from Stage 1 so the optimizer sees the same forecasted headroom as the rules engine, and budget constraints are scoped `.per(InvestmentLevel)`. Revenue reflects annual interconnection capacity revenue ($145K-$210K per MW/yr), not energy revenue.
+
+One solve produces the entire frontier. The knee point at $300M (5 DCs, 1,500 MW, $264M net value) shows the highest marginal return, unlocking xAI Colossus ($105M/yr). At $200M, 4 DCs are approved (Microsoft, CoreWeave, Crusoe, Oracle); each additional $100M adds one more DC with diminishing returns ($995K/$M at the knee vs $400K/$M at $600M). Google Metroplex DC (400 MW) and Lambda Labs DFW (200 MW) are never approved at any budget — DFW capacity is fully consumed. Per-level results (approvals, upgrades, MW) are all queried from the ontology via `model.select()` rather than parsed from solver output.
+
+See `energy_grid_planning.py` for the implementation of all five stages and `runbook.md` for the skill-driven reproduction.
 
 ## Customize this template
 
diff --git a/v1/entity_resolution/README.md b/v1/entity_resolution/README.md
index 69e0c07a..e25b0196 100644
--- a/v1/entity_resolution/README.md
+++ b/v1/entity_resolution/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Entity Resolution"
-description: "Resolve duplicate policyholder records scattered across an insurer's policy systems and acquired books into one insured party, then total each household's exposure, flag accumulation-limit breaches, and choose the lowest-cost reinsurance cessions to clear them."
+description: "Resolve duplicate policyholder records across an insurer's policy systems and acquired books into one insured party. Total each household's exposure, flag accumulation-limit breaches, and choose the lowest-cost reinsurance cessions to clear them."
 featured: false
 experience_level: intermediate
 industry: "Financial Services"
@@ -135,94 +135,34 @@ Three cases are placed deliberately:
 - **Primary identifiers**: `Record` by `record_id`; `CandidateMatch`/`ReviewPair` by `pair_id`; `ResolvedParty` by integer `key`.
 - **Important invariants**: every record in a party shares one `entity_key`; a party breaches when its summed coverage exceeds the accumulation limit; only breached parties carry an `excess`, `premium`, and `cede` decision.
 
-### `Record`
-
-A raw policy record before resolution. `email`, `phone`, `date_of_birth`, and `gov_id_last4` are optional.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `record_id` | int | Yes | Loaded from `data/records.csv` |
-| `source_system` | string | No | `AUTO`, `HOME`, `LIFE`, or `LEGACY` |
-| `full_name` / address fields | string | No | Raw, uncleaned |
-| `coverage_amount` | float | No | Per-policy sum insured |
-| `date_of_birth` / `gov_id_last4` / `email` / `phone` | string | No | Optional matching identifiers |
-| `entity_id` (graph) / `entity_key` | (node) / int | No | Resolved party — WCC label and its integer key (Stage 1) |
-| `is_duplicate` | flag | No | Record shares its party with another (Stage 2) |
-
-### `ResolvedParty`
-
-One real insured, created from the distinct party keys.
-
-| Property | Type | Notes |
-|---|---|---|
-| `key` | int | Identifying; the party's representative record id |
-| `total_exposure` | float | Sum of coverage across the party's resolved policies |
-| `is_over_limit` | flag | Total exposure exceeds the accumulation limit |
-| `excess` / `premium` | float | Excess over the limit and premium to cede it (breached parties) |
-| `cede` | float (binary) | Prescriptive decision: cede this party to reinsurance (Stage 3) |
+For the full concept and property definitions, see `entity_resolution.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
 Blocking and fuzzy scoring run in pandas (no string-similarity primitive in any query language); the engine does the parts that need reasoning -- transitive clustering, declarative aggregation, and optimization.
 
+```text
+records (CSV) -> block + score (pandas) -> auto edges + review queue
+   -> WCC clusters -> per-party exposure + breach flag -> reinsurance cession plan
+```
+
 ### Candidate generation (pandas)
 
 Blocking groups records sharing an email handle, phone, name+postal key, or date of birth, so only 28 candidate pairs are scored instead of 1,275. Each candidate's weighted field-similarity score lands it in one of two bands: at or above `AUTO_MERGE` it becomes a match edge; in `[REVIEW_FLOOR, AUTO_MERGE)` it is held for a steward instead of merged.
 
 ### Stage 1 -- Graph: transitive clustering
 
-Each auto-merge match is an undirected edge; weakly-connected-components collapses connected records into one party. Because WCC returns the representative node, the script derives a stable integer party key from it:
-
-```python
-graph = Graph(model, directed=False, weighted=False, node_concept=Record)
-
-match_ref = CandidateMatch.ref()
-rec_a, rec_b = Record.ref(), Record.ref()
-model.where(
-    match_ref.rec_a == rec_a,
-    match_ref.rec_b == rec_b
-).define(graph.Edge.new(src=rec_a, dst=rec_b))
-
-graph.Node.entity_id = graph.weakly_connected_component()
-```
+Each auto-merge match becomes an undirected edge between two records, and weakly-connected-components collapses every connected group into one party — closing over transitive chains that a pairwise comparison would miss. WCC returns the representative node, from which the script derives a stable integer party key.
 
 ### Stage 2 -- Rules-based: exposure per resolved party
 
-A `ResolvedParty` is created per party key; its total exposure is the summed coverage of its records, and it breaches when that total exceeds the limit:
-
-```python
-model.where(party_rec.entity_key == ResolvedParty.key).define(
-    ResolvedParty.total_exposure(aggregates.sum(party_rec.coverage_amount).per(ResolvedParty))
-)
-model.define(ResolvedParty.is_over_limit(ResolvedParty)).where(
-    ResolvedParty.total_exposure > ACCUMULATION_LIMIT
-)
-```
+A `ResolvedParty` is created per party key; its total exposure is the summed coverage of its records, and it is flagged over-limit when that total exceeds the accumulation limit.
 
 ### Stage 3 -- Prescriptive: reinsurance cession knapsack
 
-A binary cede decision per breached party, maximizing excess exposure transferred within the premium budget:
-
-```python
-problem.solve_for(
-    ResolvedParty.cede,
-    where=[ResolvedParty.is_over_limit()],
-    name=["cede", ResolvedParty.key],
-    type="bin",
-    lower=0.0,
-    upper=1.0,
-)
-problem.satisfy(
-    model.require(aggregates.sum(ResolvedParty.premium * ResolvedParty.cede) <= REINSURANCE_BUDGET),
-    name=["reinsurance_budget"],
-)
-problem.maximize(aggregates.sum(ResolvedParty.excess * ResolvedParty.cede))
-```
+A binary cede decision per breached party maximizes the excess exposure transferred to reinsurance, subject to keeping total cession premium within the budget — a knapsack over the over-limit households.
 
-```text
-records (CSV) -> block + score (pandas) -> auto edges + review queue
-   -> WCC clusters -> per-party exposure + breach flag -> reinsurance cession plan
-```
+See `entity_resolution.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
 ## Customize this template
 
diff --git a/v1/entity_resolution/runbook.md b/v1/entity_resolution/runbook.md
index 90b685f6..452f613e 100644
--- a/v1/entity_resolution/runbook.md
+++ b/v1/entity_resolution/runbook.md
@@ -7,7 +7,7 @@ An insurer holds the same customer many times over: a household carries auto, ho
 ```
 Ontology: Record (51 policy records with per-policy coverage), CandidateMatch
 (25 auto-merge pairs) and ReviewPair (1 held pair). The chain resolves 51 records
-into 30 insured parties, flags 4 accumulation breaches that are invisible at the
+into 31 insured parties, flags 4 accumulation breaches that are invisible at the
 record level, and cedes $927k of excess exposure to reinsurance for $111k.
 
   ─────────────────────────────────────────────────────────────────
diff --git a/v1/factory_production/README.md b/v1/factory_production/README.md
index 73bdd679..98555b1c 100644
--- a/v1/factory_production/README.md
+++ b/v1/factory_production/README.md
@@ -14,22 +14,11 @@ tags:
   - Shadow Prices
 ---
 
-# Factory Production
-
 ## What this template is for
 
-This template uses **Prescriptive** reasoning to maximize factory production profit under resource constraints, and then to read back the **sensitivity marginals** a planner asks next -- all from a single solve. It is a compact, textbook **product-mix linear program**: a small, fully hand-checkable setting for learning what shadow prices and reduced costs mean.
-
-Manufacturing operations must decide how much of each product to produce at each factory to maximize profit, given limited resources and bounded demand. Each product has a production rate (units per hour of resource), a profit per unit, and a maximum demand. Each factory has a fixed number of available resource-hours.
-
-This template formulates the problem as a linear program. Decision variables represent the quantity of each product to produce, bounded above by demand. A per-factory constraint keeps total resource usage within availability, and the objective maximizes total profit.
-
-A plain solve answers *"what is the most profitable production plan?"*. Adding `sensitivity=True` to the solve ALSO answers the marginal questions -- in the same solve, with the answers read straight off the variable and constraint objects:
+Manufacturing operations must decide how much of each product to make at each factory to maximize profit, given limited resources and bounded demand. Answering "what is the most profitable plan?" is only half the job. The planner's next questions are marginal ones: which factory's capacity is the bottleneck worth expanding, and which products are held back by demand rather than by the plant. This template answers both from a single solve, on a small, fully hand-checkable product-mix problem that makes shadow prices and reduced costs concrete.
 
-- **Capacity shadow price** (`cap.shadow_price`): how much total profit moves per extra hour at a factory. A capacity with idle hours prices at **zero** (it is not the bottleneck); a positive price flags a binding capacity worth expanding -- so this ranks which factory to expand first. (The rule is one-way: slack ⇒ zero price, and a positive price ⇒ binding.)
-- **Product reduced cost** and **basis status** (`quantity_var.reduced_cost` / `quantity_var.basis_status`): a product held at its demand cap shows a positive reduced cost here (the extra profit per unit of demand allowed); the swing product that sets the binding factory's marginal price is `BASIC` at ~0.
-
-Because the objective is a **maximization**, the *capacity shadow price* is the mirror image of a minimize-cost model -- a binding `<=` capacity prices `>= 0` here, versus `<= 0` in the cost-minimizing [`supplier_reliability`](../supplier_reliability/) template. The nonbasic bound marginals shown in *both* tables are non-negative; what flips for the *product* marginal is the active bound -- a demand-capped product sits at its upper bound (`NONBASIC_AT_UPPER`) here, while a priced-out supply lane sits at its lower bound of zero (`NONBASIC_AT_LOWER`) there. Laying the two reduced-cost tables side by side is the fastest way to internalize the conventions.
+**It uses Prescriptive reasoning to solve a product-mix linear program and, with one `sensitivity=True` flag on the same solve, reads the capacity shadow prices and product reduced costs straight off the constraint and variable objects.**
 
 > **Production-planning learning ladder**
 > 1. **Factory Production** *(this template)* -- single-period product-mix LP with sensitivity analysis.
@@ -53,6 +42,7 @@ Because the objective is a **maximization**, the *capacity shadow price* is the
 ## What's included
 
 - `factory_production.py` -- Main script defining the optimization model, constraints, objective, and sensitivity read-back
+- `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself
 - `data/factories.csv` -- Factory names and available resource-hours
 - `data/products.csv` -- Products with factory assignment, production rate, profit, and demand cap
 - `pyproject.toml` -- Python package configuration with dependencies
@@ -133,98 +123,90 @@ Because the objective is a **maximization**, the *capacity shadow price* is the
      steel_factory   40.0        40.0   0.0
    ```
 
-   Reading the result: `steel_factory` fills all 40 hours (it is the binding factory, so its capacity prices at **+4200/hour** -- the per-hour profit of the swing product `coils`, i.e. its 30/unit profit × 140 units/hour rate). `amazing_brewery` meets all demand in 25 of its 30 hours, so its capacity is **slack** and prices at **0** -- its bottleneck is demand, not capacity. Each of these demand-capped products (`bands`, `stouts`, `ales`) carries a positive reduced cost here: the profit you would gain per extra unit of demand allowed.
+   Reading the result: `steel_factory` fills all 40 hours (it is the binding factory, so its capacity prices at **+4200/hour** -- the per-hour profit of the swing product `coils`, i.e. its 30/unit profit times its 140 units/hour rate). `amazing_brewery` meets all demand in 25 of its 30 hours, so its capacity is **slack** and prices at **0** -- its bottleneck is demand, not capacity. Each of these demand-capped products (`bands`, `stouts`, `ales`) carries a positive reduced cost here: the profit you would gain per extra unit of demand allowed.
 
 ## Template structure
 
 ```text
 .
-├── README.md
-├── pyproject.toml
-├── factory_production.py
+├── README.md                 # this file
+├── runbook.md                # step-by-step analyst walkthrough
+├── pyproject.toml            # dependencies
+├── factory_production.py     # main script (LP model + sensitivity read-back)
 └── data/
-    ├── factories.csv
-    └── products.csv
+    ├── factories.csv         # factory names and available resource-hours
+    └── products.csv          # products with factory, rate, profit, demand cap
 ```
 
-## How it works
+**Start here**: run `python factory_production.py` for the full solve and sensitivity report end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-### 1. Define concepts and load data
+## Sample data
 
-The model defines `Factory` (with available resource-hours) and `Product` (with factory assignment, production rate, profit, and demand). A relationship links products to their factory:
+The bundled data is a small, hand-checkable product-mix setting -- two factories that share no resources, so the joint optimum is each factory solved independently, but one solve reads every factory's marginals side by side.
 
-```python
-Factory = Concept("Factory", identify_by={"name": String})
-Factory.avail = Property(f"{Factory} has {Float:avail}")
+- **`data/factories.csv`** (2 rows) -- `steel_factory` (40 available hours) and `amazing_brewery` (30 available hours).
+- **`data/products.csv`** (4 rows) -- `bands` and `coils` at `steel_factory`, `stouts` and `ales` at `amazing_brewery`, each with a production `rate` (units per hour), a unit `profit`, and a `demand` cap.
 
-Product = Concept("Product", identify_by={"name": String, "factory_name": String})
-Product.factory = Property(f"{Product} is produced by {Factory}")
-Product.rate = Property(f"{Product} has {Float:rate}")
-Product.profit = Property(f"{Product} has {Float:profit}")
-Product.demand = Property(f"{Product} has {Integer:demand}")
-```
+Product names are unique across factories, so the plan can be keyed by product name alone. The script asserts the expected factory and product names on load, so an edit to `data/` fails loudly rather than silently passing the name-gated sensitivity checks on zero rows.
 
-### 2. Decision variables
+## Model overview
 
-Each product gets a continuous variable bounded between 0 and its demand cap. The demand cap is the variable's **upper bound** (not a separate constraint), so its marginal surfaces later as the variable's *reduced cost*:
+The model has two concepts and one relationship linking them; the decision variable and its marginals hang off `Product`.
 
-```python
-quantity_var = problem.solve_for(
-    Product.x_quantity,
-    name=["qty", Product.factory.name, Product.name],
-    lower=0,
-    upper=Product.demand,
-    populate=False,
-)
-```
+- **Key entities**: `Factory` (a plant with an hourly resource budget) and `Product` (an item made at one factory).
+- **Primary identifiers**: `Factory` by `name`; `Product` by `name` plus `factory_name` (a composite identity).
+- **Important invariants**: production quantities are non-negative and capped at each product's demand; each factory's total resource usage stays within its available hours; profit and rate are positive.
 
-### 3. Capacity constraint and objective
+For the full concept and property definitions, see `factory_production.py`; `runbook.md` builds them step by step with the RAI skills.
 
-Each factory's total resource usage must not exceed its availability. The constraint is captured as a handle (`cap`), named per factory (a readable label), and declared with `keyed_by={"factory": Factory}`, so each instance's shadow price reads back through that **entity key** (`cap.factory`) rather than by parsing a name string. The objective maximizes total profit across all factories:
+## How it works
 
-```python
-cap = problem.satisfy(
-    model.require(
-        sum(Product.x_quantity / Product.rate)
-        .where(Product.factory == Factory)
-        .per(Factory)
-        <= Factory.avail
-    ),
-    name=["cap", Factory.name],
-    keyed_by={"factory": Factory},
-)
+The template loads two source tables, sets up one product-mix LP, and reads the marginals off the same solve:
 
-problem.maximize(sum(Product.profit * Product.x_quantity))
-problem.solve("highs", time_limit_sec=60, sensitivity=True)
+```text
+factories.csv + products.csv → decision variables → capacity constraint + profit objective → sensitivity solve → shadow prices + reduced costs
 ```
 
-### 4. Read the sensitivity marginals
+1. **Define concepts and load data.** `Factory` carries its available resource-hours; `Product` carries a per-hour production rate, unit profit, and demand cap, and links to the factory that produces it (a composite `(name, factory_name)` identity).
 
-After a `sensitivity=True` solve, the marginals are attributes on the captured handles. A constraint carries the entity back-pointer declared with `keyed_by` (`cap.factory`) and a variable carries an automatic one to its product (`quantity_var.product`), so each marginal joins to that entity's own data by key -- no pandas, no name parsing:
+2. **Decision variables.** Each product gets a continuous quantity variable bounded between 0 and its demand cap. The demand cap is the variable's *upper bound* (not a separate constraint), so its marginal surfaces as the variable's reduced cost.
 
-```python
-# Which factory's capacity to expand first?
-model.select(cap.factory.name, cap.factory.avail, cap.shadow_price).inspect()
+3. **Capacity constraint and objective.** Each factory's total resource usage (quantity over rate, summed) must stay within its available hours. The constraint is captured as a handle keyed by `Factory`, so each instance's shadow price reads back through the entity key rather than by parsing a name string. The objective maximizes total profit, and the solve runs with `sensitivity=True`.
 
-# Which products are pinned at their demand cap, and which is the swing product?
-model.select(
-    quantity_var.product.factory.name,
-    quantity_var.product.name,
-    quantity_var.reduced_cost,
-    quantity_var.basis_status,
-).inspect()
-```
+4. **Read the sensitivity marginals.** After the solve, marginals are attributes on the captured handles: each constraint carries an entity back-pointer to its factory and each variable an automatic one to its product, so every marginal joins to that entity's own data by key — no pandas, no name parsing.
+
+### Reading the marginals: two objects, one sign convention
 
-(`.inspect()` prints the rows for a quick look; the script materializes the same selects as DataFrames with `.to_df()` for its printed report and assertions.)
+The two sensitivity objects come from two different modeling choices. Capacity is a *constraint*, so its marginal is a shadow price; the demand cap is a variable *upper bound*, so its marginal is a reduced cost. A capacity shadow price answers "how much profit per extra hour at this factory", and a positive value flags the binding capacity to expand first. A product reduced cost answers "how much profit per extra unit of demand allowed" for a product pinned at its cap; the swing product that sets the binding factory's marginal price is `BASIC` at about zero.
+
+Because the objective is a maximization, the signs mirror a minimize-cost model: a binding capacity prices at zero or above here, versus zero or below in the cost-minimizing [`supplier_reliability`](../supplier_reliability/) template, and a demand-capped product sits at its upper bound (`NONBASIC_AT_UPPER`) here while a priced-out supply lane there sits at its lower bound of zero (`NONBASIC_AT_LOWER`). Laying the two reduced-cost tables side by side is the fastest way to internalize the conventions.
 
 Sensitivity marginals are exact for a linear program. They describe the rate of change at the current optimum -- the range over which that rate holds is not reported (there is no RHS/coefficient ranging) -- and a large, discrete change (adding a factory, removing a product) is a structural change best answered by re-solving.
 
+See `factory_production.py` for the implementation and `runbook.md` for the skill-driven reproduction.
+
 ## Customize this template
 
-- **Find the demand bottleneck**: Raise `amazing_brewery`'s demand caps in `products.csv`. Once its 30 hours bind, its capacity shadow price jumps from 0 to positive -- capacity becomes the bottleneck.
-- **Shift the swing product**: Lower `steel_factory`'s `avail` in `factories.csv`. `coils` (the basic, swing product) shrinks but stays the swing down to just above 30 hours, so the shadow price holds at 4200. At exactly 30 hours `coils` hits zero -- a degenerate breakpoint where the marginal is one-sided -- and below 30 hours `bands` becomes the swing and the price rises to 5000.
-- **Add more factories and products**: Extend the CSV files. The model and the per-factory marginals pick up new rows automatically.
-- **Integer production**: Change the variable type from continuous to integer if products must be produced in whole units. Note that sensitivity marginals are an LP concept -- they are reported only for continuous (LP/QP) problems, and are empty for integer models.
+### Use your own data
+
+- Replace `data/factories.csv` (columns `name`, `avail`) and `data/products.csv` (columns `factory_name`, `name`, `rate`, `profit`, `demand`) with your own rows. The model and the per-factory marginals pick up new factories and products automatically.
+- Keep product names unique across factories, or key the plan by the composite `(factory_name, name)` instead of by name alone.
+- Update the `EXPECTED_FACTORIES` / `EXPECTED_PRODUCTS` guard sets at the top of the script (or remove them) so the load-time assertions match your data.
+
+### Tune parameters
+
+- **Find the demand bottleneck**: raise `amazing_brewery`'s demand caps in `products.csv`. Once its 30 hours bind, its capacity shadow price jumps from zero to positive -- capacity becomes the bottleneck.
+- **Shift the swing product**: lower `steel_factory`'s `avail` in `factories.csv`. `coils` (the basic, swing product) shrinks but stays the swing down to just above 30 hours, so the shadow price holds at 4200. At exactly 30 hours `coils` hits zero -- a degenerate breakpoint where the marginal is one-sided -- and below 30 hours `bands` becomes the swing and the price rises to 5000.
+
+### Extend the model
+
+- **Add more factories and products**: extend the CSV files. The model and the per-factory marginals pick up new rows automatically.
+- **Add shared resources**: today the factories share no resources. Add a constraint over a resource used across factories to couple their plans and make the joint solve more than the sum of independent ones.
+
+### Scale up / productionize
+
+- **Integer production**: change the variable type from continuous to integer if products must be produced in whole units. Sensitivity marginals are an LP concept -- they are reported only for continuous (LP/QP) problems, and are empty for integer models.
+- Point the `read_csv` calls at Snowflake tables via `model.data(...)` to run the same model over warehouse-scale reference data.
 
 ## Troubleshooting
 
@@ -257,3 +239,23 @@ Make sure you activated the virtual environment and ran `python -m pip install .
 
 A product with zero quantity is not profitable enough to justify its resource usage given tighter, more profitable competitors. Its reduced cost tells you how far its economics are from being worth producing. Increase factory `avail`, raise the product's profit, or lower its production rate to bring it into the plan.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Prescriptive reasoning](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives used throughout this template.
+- [Sensitivity analysis](https://docs.relational.ai/) — shadow prices, reduced costs, and basis status on a solved linear program.
+
+### Language / modeling reference
+
+- [PyRel v1 language](https://docs.relational.ai/) — concepts, properties, and relationships as used in the model definition.
+
+### Deeper dives
+
+- [`supplier_reliability`](../supplier_reliability/) — a cost-minimizing companion whose sign conventions mirror this one; reading the two side by side clarifies the marginals.
+- [`production_planning`](../production_planning/) and [`demand_planning_temporal`](../demand_planning_temporal/) — the next rungs of the production-planning learning ladder.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/financial_index_replication/README.md b/v1/financial_index_replication/README.md
index 49c28ef6..6cc558cf 100644
--- a/v1/financial_index_replication/README.md
+++ b/v1/financial_index_replication/README.md
@@ -19,29 +19,13 @@ tags:
   - HiGHS
 ---
 
-# Financial Index Replication
-
 ## What this template is for
 
-Index funds and separately managed accounts often need to track a broad benchmark without holding every constituent. This template builds a sparse replication basket: from 50 S&P 500-like stocks, select exactly 20 names and their weights so the portfolio follows the benchmark's historical returns as closely as possible.
-
-The model uses RelationalAI's **prescriptive** reasoner to optimize both selection and sizing in one mixed-integer program. It includes practical portfolio constraints: long-only weights, max position size, sector neutrality, and per-name ADV participation limits.
-
-## Why this problem matters
-
-Holding every index constituent can be operationally expensive, especially for smaller accounts, tax-aware portfolios, or products with custody and trading constraints. A sparse replicating basket gives most of the benchmark exposure while reducing the number of positions to trade and maintain.
+Index funds and separately managed accounts often need to track a broad benchmark without holding every constituent. Full replication is operationally expensive, especially for smaller accounts, tax-aware portfolios, or products with custody and trading constraints. A sparse replicating basket captures most of the benchmark exposure while cutting the number of positions to trade and maintain.
 
-The hard part is that name selection and weight optimization interact. The best 20 names are not simply the largest constituents or the highest-correlated stocks; they need to work together as a portfolio while respecting sector and per-name trading-capacity rules.
+The hard part is that name selection and weight sizing interact. The best 20 names are not simply the largest constituents or the highest-correlated stocks; they have to work together as a portfolio while respecting sector and per-name trading-capacity rules. This template builds that basket from a 50-stock, S&P 500-like universe: it selects exactly 20 names and their weights so the portfolio follows the benchmark's historical returns as closely as possible.
 
-### Key design patterns demonstrated
-
-- **Cardinality-constrained selection** -- binary variables choose exactly 20 stocks.
-- **Linked binary and continuous decisions** -- a stock can carry weight only if selected.
-- **Tracking objective** -- the solver minimizes absolute tracking residuals while the script reports realized RMS tracking error after solving.
-- **Sector neutrality** -- replicated sector exposure must stay within a fixed active band around benchmark sector weights.
-- **ADV participation control** -- ADV stands for average daily dollar volume; each stock's buy or sell amount is capped as a fraction of ADV.
-- **Full-history evaluation** -- optimize across the entire return history and report realized tracking quality.
-- **Baseline comparison** -- compare against equal-weight top-20 stocks by full-history correlation.
+**It uses Prescriptive reasoning to co-optimize selection and sizing in a single mixed-integer program that minimizes tracking residuals subject to long-only weights, a maximum position size, sector neutrality, and per-name average-daily-volume (ADV) participation limits.**
 
 ## Who this is for
 
@@ -62,27 +46,12 @@ The hard part is that name selection and weight optimization interact. The best
 ## What's included
 
 - `financial_index_replication.py` -- Main script with the semantic model, optimization model, solve, and reporting
+- `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself
 - `data/stocks.csv` -- 50-stock universe with ticker, sector, benchmark weight, liquidity, and previous weight
 - `data/index_returns.csv` -- Monthly S&P 500-like benchmark returns
 - `data/stock_returns.csv` -- Monthly historical returns by stock
 - `pyproject.toml` -- Python package configuration with dependencies
 
-## Template structure
-
-```text
-.
-├─ README.md                            # this file
-├─ pyproject.toml                       # dependencies
-├─ financial_index_replication.py      # main entrypoint: model, solve, report
-└─ data/
-   ├─ stocks.csv                        # 50-stock universe
-   ├─ index_returns.csv                 # benchmark monthly returns
-   ├─ stock_returns.csv                 # per-stock monthly returns
-   └─ replica_returns.csv               # written by the script after solving
-```
-
-**Start here**: run `python financial_index_replication.py`.
-
 ## Prerequisites
 
 ### Access
@@ -128,7 +97,8 @@ The hard part is that name selection and weight optimization interact. The best
    python financial_index_replication.py
    ```
 
-6. Expected output:
+6. Expected output (a few lines confirm a successful run; exact figures depend on the data):
+
    ```text
    ======================================================================
    FINANCIAL INDEX REPLICATION
@@ -137,119 +107,118 @@ The hard part is that name selection and weight optimization interact. The best
    Selected names: exactly 20
    Max position: 10%
    Sector active band: +/- 4%
-   Portfolio value: $10,000,000
-   Max ADV participation per name: 5%
 
    Status: OPTIMAL
    Objective: total absolute residual = ...
 
    === Selected Replication Basket ===
-   ticker                  sector weight benchmark_weight previous_weight avg_dollar_volume
-     ...                     ...   ...          ...             ...              ...
+   ticker  sector  weight  benchmark_weight  previous_weight  avg_dollar_volume
+   ...
 
-   === Sector Exposure ===
-                    sector weight benchmark_weight active_weight
-     Consumer Discretionary  ...        ...             ...
-     ...
+   Wrote benchmark-vs-replica returns to: data/replica_returns.csv
+   ```
 
-   === Tracking Quality ===
-   Annualized tracking error: ...
-   Mean abs monthly residual: ...
-   Implied turnover: ...
+   The solve selects exactly 20 names, reports the basket, sector exposures, tracking quality, and a baseline comparison, and writes `data/replica_returns.csv` for plotting. The full printout is in `runbook.md`.
 
-   === Baseline Comparison ===
-   Baseline: equal-weight top-20 stocks by full-history correlation
-   Baseline annualized tracking error: ...
+## Template structure
 
-   Wrote benchmark-vs-replica returns to: data/replica_returns.csv
-   ```
+```text
+.
+├─ README.md                            # this file
+├─ runbook.md                           # step-by-step analyst walkthrough
+├─ pyproject.toml                       # dependencies
+├─ financial_index_replication.py      # main entrypoint: model, solve, report
+└─ data/
+   ├─ stocks.csv                        # 50-stock universe
+   ├─ index_returns.csv                 # benchmark monthly returns
+   ├─ stock_returns.csv                 # per-stock monthly returns
+   └─ replica_returns.csv               # written by the script after solving
+```
 
-## How It Works
+**Start here**: run `python financial_index_replication.py` for the full solve and reporting end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-### 1. Load the universe
+## Sample data
 
-The template loads a compact synthetic dataset:
+The bundled data is synthetic but shaped like an S&P 500 replication problem, so the template runs without licensed market data.
 
-- `stocks.csv`: identifiers, sectors, benchmark weights, liquidity, and previous holdings
-- `index_returns.csv`: monthly benchmark returns
-- `stock_returns.csv`: monthly returns for each stock
+- **`data/stocks.csv`** (50 rows) -- the investable universe: `ticker`, `name`, `sector`, `benchmark_weight`, `avg_dollar_volume`, and `previous_weight` (the prior-period holding).
+- **`data/index_returns.csv`** -- monthly benchmark returns keyed by `date` (`index_return`).
+- **`data/stock_returns.csv`** -- monthly per-stock returns keyed by `date` and `ticker` (`return`).
+- **`data/replica_returns.csv`** -- written by the script after solving, with `date`, `index_return`, and `replica_return` for downstream plotting.
 
-The data is synthetic but shaped like an S&P 500 replication problem, so the template is runnable without licensed market data.
+The benchmark constituent weights were generated by first assigning broad target sector allocations, then drawing uneven positive stock weights within each sector and scaling each sector back to its target. The benchmark return each month is the weighted sum of all constituent returns, plus a small noise term so the sparse 20-name replication problem is realistic rather than perfectly mechanical.
 
-The benchmark constituent weights were generated by first assigning broad target
-sector allocations, then drawing uneven positive stock weights within each
-sector and scaling those names so each sector sums back to its target. This
-creates a market-cap-like benchmark shape without using licensed constituent
-weights. The benchmark return for each month is then calculated from the stock
-return table as the weighted sum of all constituent returns, with a small random
-noise term added so the sparse 20-name replication problem is realistic rather
-than perfectly mechanical.
+## Model overview
 
-### 2. Define selection and weight variables
+Four concepts describe the universe, its sector grouping, and the historical return panel; the decision variables attach to `Stock` and `ReturnDate`.
 
-The model has two main decisions per stock:
+- **Key entities**: `Stock` (a constituent in the investable universe), `Sector` (a grouping used for the neutrality constraint), and `ReturnDate` (a month in the return panel).
+- **Primary identifiers**: `Stock` by `ticker`; `Sector` by `sector_name`; `ReturnDate` by `date`.
+- **Important invariants**: exactly `N_REPLICATION_NAMES` stocks are selected; weights are non-negative, at most `MAX_WEIGHT` each, and sum to 100%; a stock can carry weight only if selected; each sector's weight stays within `SECTOR_ACTIVE_BAND` of its benchmark weight.
 
-```python
-Stock.x_selected = model.Property(f"{Stock} selected if {Float:selected}")
-Stock.x_weight = model.Property(f"{Stock} has replication weight {Float:weight}")
-```
+For the full concept and property definitions, see `financial_index_replication.py`; `runbook.md` builds them step by step with the RAI skills.
+
+## How it works
 
-`x_selected` is binary. `x_weight` is continuous. The linking constraint keeps unselected names at zero weight:
+The design patterns worth noting: **cardinality-constrained selection** (binary variables choose exactly 20 stocks), **linked binary and continuous decisions** (a stock carries weight only if selected), an **L1 tracking objective** (minimize absolute residuals to keep the problem linear with binary selection), **sector neutrality** (replicated sector exposure stays within a fixed active band), **ADV participation control** (each name's buy or sell is capped as a fraction of average daily dollar volume), and a **baseline comparison** against an equal-weight top-correlation basket.
 
-```python
-weight <= MAX_WEIGHT * selected
+```text
+stocks + returns → selection + weight variables → tracking residuals → cardinality/sector/ADV constraints → MIP solve → basket + tracking report
 ```
 
-### 3. Match benchmark returns
+### 1. Define selection and weight variables
+
+Each stock carries two linked decisions: a binary `x_selected` (in the basket or not) and a continuous `x_weight` (portfolio weight). A linking constraint holds `weight <= MAX_WEIGHT * selected`, so an unselected name is forced to zero weight.
+
+### 2. Match benchmark returns
 
-For each historical month, the model creates positive and negative residual variables:
+For each historical month, the model creates positive and negative residual variables that absorb the gap between the benchmark return and the replica's weighted return:
 
 ```text
 index_return[t] - sum_i weight[i] * stock_return[i,t] = pos_error[t] - neg_error[t]
 ```
 
-The objective minimizes total absolute residual:
+The objective minimizes the total absolute residual:
 
 ```text
 minimize sum_t pos_error[t] + neg_error[t]
 ```
 
-This keeps the solver problem linear and mixed-integer. After solving, the script computes the standard RMS tracking error across the full history.
+This L1 formulation keeps the problem linear and mixed-integer with the binary selection variables; after solving, the script computes the standard RMS tracking error across the full history. A classic L2 objective (squared residuals) is also a natural tracking-error formulation if the selected solver supports the resulting mixed-integer quadratic problem.
 
-This template uses an L1 tracking objective because absolute residuals keep the model linear with binary selection variables. A classic L2 objective, minimizing squared residuals, is also a natural tracking-error formulation if the selected solver supports the resulting mixed-integer quadratic problem.
+### 3. Add portfolio realism
 
-### 4. Add portfolio realism
+The template layers on the constraints practitioners expect: exactly 20 selected stocks; weights sum to 100%; no shorting; max 10% per selected stock; sector weights within +/- 4% of benchmark sector weights; and per-name buy and sell amounts no more than 5% of average daily dollar volume (ADV).
 
-The template includes constraints practitioners expect:
+### 4. Evaluate the portfolio
 
-- exactly 20 selected stocks
-- weights sum to 100%
-- no shorting
-- max 10% per selected stock
-- sector weights within +/- 4% of benchmark sector weights
-- per-name buy and sell amounts no more than 5% of average daily dollar volume (ADV)
+After solving, the script reports the selected names and weights, sector exposures and active sector weights, annualized tracking error, mean absolute residual, implied turnover, and a comparison to a simple top-correlation baseline. It also writes `data/replica_returns.csv` (`date`, `index_return`, `replica_return`) so you can plot the benchmark series against the optimized replica.
 
-### 5. Evaluate the portfolio
+See `financial_index_replication.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
-After solving, the script reports:
+## Customize this template
 
-- selected names and weights
-- sector exposures and active sector weights
-- annualized tracking error
-- mean absolute residual
-- implied turnover
-- comparison to a simple top-correlation baseline
-- `data/replica_returns.csv` with `date`, `index_return`, and `replica_return`
+### Use your own data
 
-You can use `data/replica_returns.csv` to plot the original benchmark return series against the optimized replica return series.
+- Replace the synthetic CSVs with real benchmark and constituent returns if your data license allows it. Keep the headers: `ticker`, `sector`, `benchmark_weight`, `avg_dollar_volume`, `previous_weight` for `stocks.csv`; `date`, `index_return` for `index_returns.csv`; `date`, `ticker`, `return` for `stock_returns.csv`.
+- Make sure all three files cover the same date range and use the same return convention (simple or log); a mismatch silently drops months from the join or inflates residuals.
 
-## Customize
+### Tune parameters
 
-- Change `N_REPLICATION_NAMES` to select more or fewer names.
-- Change `MAX_WEIGHT` to tighten or relax the largest allowed position size.
-- Tighten `SECTOR_ACTIVE_BAND` for stricter sector neutrality.
-- Lower `MAX_ADV_PARTICIPATION` for stricter per-name trading capacity.
-- Replace the synthetic CSVs with real benchmark and constituent returns if your data license allows it.
+- `N_REPLICATION_NAMES` sets how many names the basket holds.
+- `MAX_WEIGHT` tightens or relaxes the largest allowed position size.
+- `SECTOR_ACTIVE_BAND` controls sector neutrality; tighten it for stricter tracking to benchmark sector weights.
+- `MAX_ADV_PARTICIPATION` sets per-name trading capacity; lower it for stricter ADV limits.
+
+### Extend the model
+
+- Swap the L1 tracking objective for an L2 (squared-residual) objective if your solver supports the resulting mixed-integer quadratic problem.
+- Add constraints practitioners expect, such as a turnover cap against `previous_weight` or a minimum position size for selected names.
+
+### Scale up / productionize
+
+- Point the `pd.read_csv` calls at Snowflake tables via `model.data(...)` to run over a larger universe and longer return history.
+- Pin dependencies and fix any random seed in the data-generation step for reproducible baskets across runs.
 
 ## Troubleshooting
 
@@ -284,3 +253,22 @@ You can use `data/replica_returns.csv` to plot the original benchmark return ser
     - Re-extract the template ZIP if any file looks truncated.
     - On Windows, ensure files are UTF-8 encoded with no BOM.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Prescriptive reasoning](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives used to co-optimize selection and weights.
+- [Mixed-integer optimization](https://docs.relational.ai/) — binary selection variables linked to continuous weights, and the cardinality constraint.
+
+### Language / modeling reference
+
+- [PyRel v1 language](https://docs.relational.ai/) — concepts, properties, and relationships as used to model stocks, sectors, and the return panel.
+
+### CLI / SDK guides
+
+- [`rai init` and configuration](https://docs.relational.ai/) — connecting the template to your Snowflake-backed RAI account.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/fraud-detection/README.md b/v1/fraud-detection/README.md
index 6f7531bc..22a87968 100644
--- a/v1/fraud-detection/README.md
+++ b/v1/fraud-detection/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Fraud Detection"
-description: "Transaction-fraud pipeline: account PageRank and high-volume account flags feed a GNN binary classifier whose per-transaction scores drive a knapsack investigator-budget MILP."
+description: "Transaction-fraud pipeline where account PageRank and high-volume account flags feed a graph neural network (GNN) binary classifier whose per-transaction scores drive a knapsack investigator-budget mixed-integer linear program (MILP)."
 featured: true
 experience_level: advanced
 industry: "Financial Services"
@@ -22,13 +22,11 @@ sidebar:
 
 ## What this template is for
 
-Fraud and risk teams face four interconnected problems: discovering suspicious structure in the identity / transaction graph, classifying accounts by behavior rules, scoring transactions as they come in, and deciding which alerts to investigate given finite human capacity. Traditionally these live in separate tools. This template shows all four working together on one semantic model in RelationalAI, wiring the **Graph → Rules → Predictive → Prescriptive** reasoners into a single pipeline.
+Fraud and risk teams face four interconnected problems: discovering suspicious structure in the transaction graph, classifying accounts by their behavior, scoring transactions as they arrive, and deciding which alerts to investigate given finite human capacity. Traditionally these live in separate tools, so the signal from one rarely informs the next, and the investigator queue is set by a naive sort rather than by the value at stake.
 
-**Start with `fraud_detection_local.py`** -- it runs the full five-stage pipeline on a small bundled demo dataset (CPU, no external data): compute account PageRank, derive high-volume account flags, train a GNN binary classifier on the Account-Transaction graph, blend its probability with a rule-based heuristic flag, and solve a knapsack investigator-budget MILP. A few minutes end-to-end.
+This template shows all four working together on one semantic model in RelationalAI: graph structure feeds behavioral rules, both feed a learned per-transaction fraud score, and that score drives an investigator-budget allocation that captures the most expected loss the audit team's hours can reach.
 
-**Adapt the pattern to your own Snowflake data** using `fraud_detection.py` as a reference -- same five stages, loaded from Snowflake and trained on GPU.
-
-**For the older rule-based-only take** (no ML), see `fraud_detection_rules.ipynb` -- a standalone notebook using Weakly Connected Components on shared-identifier edges to flag suspicious users.
+**It chains RelationalAI's graph, rules, predictive, and prescriptive reasoners into a single predict-then-optimize pipeline over a shared ontology** — from account PageRank through a graph neural network (GNN) classifier to a mixed-integer linear programming (MILP) audit allocation.
 
 ## Who this is for
 
@@ -54,6 +52,7 @@ Assumes familiarity with Python, basic ML concepts (binary classification, ROC A
   - `fraud_detection_local.py` -- **primary, runnable out of the box.** Runs all five stages (Graph / Rules / Predictive / Bridge / Prescriptive) end-to-end on the bundled demo CSVs.
   - `fraud_detection.py` -- **reference pattern** for adapting the pipeline to your own Snowflake data. Same five stages, GPU-trained.
   - `fraud_detection_rules.ipynb` -- original rule-based identity-graph notebook, kept as a complementary intro.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Model**: `Account`, `Transaction`, plus two graphs (Account-Account for PageRank; Transaction-to-Account for the GNN), derived account properties, and the alert-score bridge
 - **Sample data**: a small class-balanced transactions subset sampled from a public mobile-money dataset (CC BY-SA 4.0) -- see [Sample data](#sample-data) below for details and attribution
 - **Outputs**: class-balance profile, GNN ROC-AUC, top-K alert queue, optimal audit schedule, MILP-vs-naive uplift
@@ -189,41 +188,22 @@ external data, no GPU). Exact scores shift a little with numerical noise
 between CPU and GPU runs, but the structure and magnitude are consistent.
 
 ```text
-=== Fraud class balance (train split) ===
-  n=11498  fraud=4339  fraud_rate=37.7%
-  Baseline ROC_AUC = 0.5
-
-============================================================
-Stage 3: Predictive -- fraud binary-classification GNN (CPU)
-============================================================
-=== Start GNN Training ===
-  ✓ Step 1 completed (~20s)   # prepare dataset + GNN tables
-  ✓ Step 2 completed (~2s)    # trainer config
-  ✓ Step 3 completed (~5s)    # submit training job
-=== Start GNN Prediction ===
-  ✓ GNN Prediction Complete (~85s)
-
-============================================================
 Stage 5: Prescriptive -- investigator-budget allocation
-============================================================
-MILP Status: OPTIMAL
-Captured expected loss (optimal within budget): $111,854,667
-  MILP (cost-aware + per-receiver cap) -> $111,854,667 captured across the audit queue
-  Naive top-by-alert-score (budget only, same hours) -> $67,947,657 captured across 16 audits
+  MILP Status: OPTIMAL
+  MILP (cost-aware + per-receiver cap) -> $111,854,667 captured
+  Naive top-by-alert-score (same 80 hours)  -> $67,947,657 captured
   MILP uplift over naive sort: $+43,907,010
-
-=== Selected audit queue ===
-  16 audits scheduled; 80.0/80 investigator hours used
-  By trans_type:
-    TRANSFER    11
-    CASH_OUT     5
 ```
 
-The MILP captures ~65% more expected loss than a naive sort-by-alert-score
+The MILP captures materially more expected loss than a naive sort-by-alert-score
 under the same 80-hour budget, because it trades off per-audit cost (audit
 hours scale with transaction size) against catch value and respects the
-per-receiver cap. Natural type diversity falls out of the solve without any
-per-type constraint.
+per-receiver cap. GNN training on GPU is not bit-for-bit reproducible even with
+a fixed seed, so the exact captured and uplift dollars shift from run to run
+(a separate run gave $117.3M captured against a $60.2M naive baseline); the
+large MILP-over-naive uplift is the stable result. The `runbook.md` walkthrough
+covers `fraud_detection.py`, the same chain run against the full PaySim schema
+on Snowflake at a much larger scale.
 
 ## Template structure
 
@@ -245,10 +225,12 @@ per-type constraint.
         └── LICENSE.txt             # CC BY-SA 4.0 + PaySim attribution
 ```
 
-**Start here**: `fraud_detection_local.py` (CPU, no external setup). Use
-`fraud_detection.py` (requires GPU) as the adaptation reference when you wire
-this pattern into your own Snowflake data. Explore
-`fraud_detection_rules.ipynb` for a rule-based-only take on identity graphs.
+**Start here**: run `python fraud_detection_local.py` for the full five-stage
+pipeline end to end (CPU, no external setup), or follow `runbook.md` to
+reproduce it step by step with the RAI skills. Use `fraud_detection.py`
+(requires GPU) as the adaptation reference when you wire this pattern into your
+own Snowflake data, and explore `fraud_detection_rules.ipynb` for a
+rule-based-only take on identity graphs.
 
 ## Sample data
 
@@ -269,12 +251,17 @@ Edgar Lopez-Rojas, released under
 
 ## Model overview
 
-### Key entities
+Two concepts carry the pipeline: `Account` and `Transaction`. Each stage enriches them with new properties the next stage reads, so the model grows accretively across the run.
+
+- **Key entities**: `Account` (a participant in the transaction network) and `Transaction` (one transfer between two accounts).
+- **Primary identifiers**: `Account.account_id` (string, e.g. customer prefix `C` or merchant prefix `M`); `Transaction.transaction_id` (integer).
+- **Important invariants**: `is_flagged_fraud` and the GNN's `is_fraud` label are 0/1; `alert_score` is a `[0, 1]` blend of the flag and the GNN probability; audit-cost hours and transaction amounts are non-negative; the MILP's audit decision is binary.
 
-- **Account** (`account_id`): one participant in the transaction network -- customer (ID prefix `C`) or merchant (prefix `M`) in the demo dataset. Appears as either sender (`name_orig`) or receiver (`name_dest`) on transactions. Enriched at pipeline time with `pagerank` (from Stage 1) and `activity_count` (from Stage 2).
-- **Transaction**: one transfer with amount, sender balance delta, receiver balance delta, transaction type, and a pre-existing rule-based flag `is_flagged_fraud` used as the heuristic comparator.
+For the full concept and property definitions, see `fraud_detection_local.py`; `runbook.md` builds them step by step with the RAI skills (covering the Snowflake-scale `fraud_detection.py` path).
+
+## How it works
 
-### Pipeline stages
+The five stages thread through the shared ontology, each stage's output becoming a property the next stage reads.
 
 ```text
 Accounts + Transactions (Snowflake tables or bundled CSVs)
@@ -285,139 +272,36 @@ Accounts + Transactions (Snowflake tables or bundled CSVs)
   → Stage 5 -- Prescriptive: knapsack MILP (hours budget + per-receiver cap)
 ```
 
-## How it works
+**Build the graphs.** `Account` and `Transaction` are populated from CSVs (local) or Snowflake (full), then two graphs are constructed for different reasoners: a directed Transaction-to-Account bipartite graph that the GNN consumes, and a directed Account-Account funds-flow graph the graph reasoner runs PageRank over.
 
-### 1. Build the graphs
+**Stage 1 -- Graph reasoner: account PageRank.** PageRank runs on the funds-flow graph, and each account's score is bound to an explicit `Account.pagerank` property so it surfaces as a GNN feature column.
 
-`Account` and `Transaction` concepts are populated from CSVs (local) or
-Snowflake (full). The template constructs two graphs serving different
-reasoners. A directed Transaction-to-Account bipartite graph used by the GNN:
+**Stage 2 -- Rules reasoner: account activity.** A derived property aggregates each sending account's transaction count into `Account.activity_count`. Both `pagerank` (continuous) and `activity_count` (integer) go into the `PropertyTransformer` so the GNN sees them as features alongside the raw transaction fields.
 
-```python
-gnn_graph = Graph(model, directed=True, weighted=False)
-Edge = gnn_graph.Edge
-model.define(Edge.new(src=Transaction, dst=Account)).where(
-    Transaction.name_orig == Account.account_id)
-model.define(Edge.new(src=Transaction, dst=Account)).where(
-    Transaction.name_dest == Account.account_id)
-```
+**Stage 3 -- Predictive: GNN binary classifier.** Task relationships encode the `is_fraud` label on the train/validation splits and omit it on test. The GNN trains on the Transaction-to-Account graph with the enriched features and emits a per-transaction fraud probability. Both scripts use temporal task relationships keyed on the transaction timestamp.
 
-And a directed Account-Account funds-flow graph used by the graph reasoner
-(`node_concept=Account` means `acct_graph.Node` binds directly to `Account`):
-
-```python
-acct_graph = Graph(
-    model, directed=True, weighted=False,
-    node_concept=Account, aggregator="sum",
-)
-_sender, _receiver = Account.ref(), Account.ref()
-_txn = Transaction.ref()
-model.define(acct_graph.Edge.new(src=_sender, dst=_receiver)).where(
-    _txn.name_orig == _sender.account_id,
-    _txn.name_dest == _receiver.account_id,
-)
-```
+**Stage 4 -- Bridge: blend GNN probability with heuristic flag.** The dataset carries an `is_flagged_fraud` heuristic. A convex mix (weighted by `ALPHA_FLAG`) combines it with the GNN probability into a per-transaction `alert_score` in `[0, 1]`.
 
-### 2. Stage 1 -- Graph reasoner: account PageRank
+**Stage 5 -- Prescriptive: knapsack MILP investigator-budget allocation.** An auditor's time is the scarce resource: the total investigation budget is fixed in hours, and the time to audit a transaction grows with its size. The MILP maximizes expected loss averted (`alert_score × amount`) subject to that budget, plus a per-receiver cap to prevent flooding one account. Because cost and value both scale with transaction size, ranking by `alert_score` alone is provably suboptimal -- a high-score $5M transfer consumes 5 hours but may yield less value per hour than three medium-score $500K transfers at 1 hour each. The MILP trades them off correctly; the output prints both the MILP objective and a naive sort-and-take baseline so the tradeoff is visible.
 
-Run PageRank on the funds-flow graph and bind the score to an explicit
-`Account.pagerank` property so it surfaces as a GNN feature column:
-
-```python
-pagerank_rel = acct_graph.pagerank()
-Account.pagerank = model.Property(f"{Account} has {Float:pagerank}")
-a, score = Account.ref(), Float.ref()
-model.define(a.pagerank(score)).where(pagerank_rel(a, score))
-```
-
-### 3. Stage 2 -- Rules reasoner: account activity
-
-Canonical PyRel derivation rule -- a `Property` whose value comes from an
-aggregation over related instances:
-
-```python
-# Aggregate transaction count per sending account
-Account.activity_count = model.Property(
-    f"{Account} has {Integer:activity_count}")
-model.define(Account.activity_count(
-    count(Transaction).per(Account)
-)).where(Transaction.name_orig == Account.account_id)
-```
-
-Both `Account.pagerank` (continuous) and `Account.activity_count` (integer)
-get included in the `PropertyTransformer` so the GNN sees them as features
-alongside the raw transaction fields.
-
-### 4. Stage 3 -- Predictive: GNN binary classifier
-
-Task relationships encode the `isFraud` label on train/val and omit it on
-test. Both the local and Snowflake reference scripts use temporal
-Relationships (`at {Any:step_ts}`) and `has_time_column=True`.
-
-```python
-Train = Relationship(f"{Transaction} at {Any:step_ts} has {Any:label}")
-model.define(Train(Transaction, TrainTable.step_ts, TrainTable.is_fraud))
-    .where(Transaction.transaction_id == TrainTable.transaction_id)
-
-gnn = GNN(
-    exp_database=..., exp_schema=...,
-    graph=gnn_graph, property_transformer=pt,
-    train=Train, validation=Val,
-    task_type="binary_classification", eval_metric="roc_auc",
-    has_time_column=True, stream_logs=False, seed=42,
-    device="cpu", n_epochs=10, lr=0.005, temporal_strategy="last",
-)
-gnn.fit()
-Transaction.predictions = gnn.predictions(domain=Test)
-```
-
-### 5. Stage 4 -- Bridge: blend GNN probability with heuristic flag
-
-The bundled dataset carries an `is_flagged_fraud` heuristic from the source
-dataset. Combine it with the GNN probability via a convex mix:
-
-```python
-model.define(Transaction.alert_score(
-    ALPHA_FLAG * Transaction.is_flagged_fraud
-    + (1 - ALPHA_FLAG) * Transaction.predictions.probs
-)).where(Transaction.predictions)
-```
-
-### 6. Stage 5 -- Prescriptive: knapsack MILP investigator-budget allocation
-
-An auditor's time is the scarce resource: the total investigation budget is
-fixed in hours, and the time to audit a transaction grows with its size.
-Maximize expected loss averted (score × amount) subject to that budget, plus
-a per-receiver cap to prevent flooding one account.
-
-```python
-problem.satisfy(...).require(
-    sum(Txn_ref, Txn_ref.audit_cost * select_ref) <= AUDIT_BUDGET_HOURS
-)
-# per-receiver cap: at most 1 audit per destination account
-problem.maximize(sum(Txn_obj.alert_score * Txn_obj.amount * sel_obj))
-```
-
-Because cost and value both scale with transaction size, ranking by
-`alert_score` alone is provably suboptimal -- a high-score $5M transfer
-consumes 5 hours but may yield less value per hour than three medium-score
-$500K transfers at 1 hour each. The MILP trades them off correctly; the
-output prints both the MILP objective and a naive sort-and-take baseline so
-the tradeoff is visible.
+See `fraud_detection_local.py` (and `fraud_detection.py` for the Snowflake path) for the implementation, and `runbook.md` for the skill-driven reproduction.
 
 ## Customize this template
 
-**Use your own data:**
+Focus on the first changes most users will make.
+
+### Use your own data
 
-- Replace the bundled CSVs (or Snowflake tables) with your own accounts /
-  transactions. Keep `customer_id`-style string PKs and a stable transaction
-  PK.
-- The PropertyTransformer is the main place to localize: drop your PKs/FKs,
-  list your categorical vs continuous fields.
+- Replace the bundled CSVs (or Snowflake tables) with your own accounts and
+  transactions. Keep `customer_id`-style string primary keys and a stable
+  transaction primary key.
+- The `PropertyTransformer` is the main place to localize: drop your primary
+  and foreign keys, and list your categorical versus continuous fields.
 
-**Tune knobs:**
+### Tune parameters
 
-- `ALPHA_FLAG` (0..1) -- weight on the rule-based flag vs the GNN prob.
+- `ALPHA_FLAG` (0..1) -- weight on the rule-based flag versus the GNN
+  probability.
 - `AUDIT_BUDGET_HOURS` / `PER_ACCOUNT_CAP` -- investigator budget knobs.
   Raise the budget to audit more transactions; tighten the cap to spread
   audits across more receivers.
@@ -427,7 +311,7 @@ the tradeoff is visible.
 - GNN hyperparameters (`n_epochs`, `lr`, `train_batch_size`, ...) -- see the
   `rai-predictive-training` skill for tuning guidance.
 
-**Extend the model:**
+### Extend the model
 
 - Swap PageRank for other centrality measures (betweenness, eigenvector) or
   add community labels (Louvain / Infomap) as a categorical GNN feature.
@@ -437,6 +321,15 @@ the tradeoff is visible.
   never skip an already-`is_flagged_fraud=True` transaction) rather than as
   an alert-score contributor.
 
+### Scale up / productionize
+
+- Use `fraud_detection.py` as the reference for running against a full
+  Snowflake dataset on a GPU-enabled RAI engine (see *Adapting to your own
+  Snowflake data* under Quickstart).
+- Pin `relationalai` in `pyproject.toml` and set a fixed GNN `seed` for
+  reproducible runs; schedule the pipeline to refresh the audit queue as new
+  transactions land.
+
 ## Troubleshooting
 
 <details>
@@ -467,3 +360,24 @@ the tradeoff is visible.
 
 Set `STREAM_LOGS = False` at the top of the script (the default). The GNN continues training server-side; only the client-side log stream is suppressed.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Multi-reasoner workflows](https://docs.relational.ai/) — chaining reasoners and enriching a shared ontology, as this predict-then-optimize pipeline does.
+- [PyRel v1 modeling](https://docs.relational.ai/) — concepts, properties, and derived rules.
+
+### Reasoner reference
+
+- [Graph reasoner](https://docs.relational.ai/) — building graphs from an ontology and running PageRank and centrality.
+- [Predictive reasoner (GNN)](https://docs.relational.ai/) — graph neural network classification, the `PropertyTransformer`, and temporal task relationships.
+- [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives for the knapsack MILP.
+
+### Deeper dives
+
+- [GNN training and tuning](https://docs.relational.ai/) — hyperparameters, evaluation metrics, and predictions; see also the `rai-predictive-training` skill.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/hospital_staffing/README.md b/v1/hospital_staffing/README.md
index 326f1a20..b5d43198 100644
--- a/v1/hospital_staffing/README.md
+++ b/v1/hospital_staffing/README.md
@@ -13,8 +13,6 @@ tags:
   - Multi-Objective
 ---
 
-# Hospital Staffing
-
 ## What this template is for
 
 This template uses **prescriptive reasoning (optimization)** to frame hospital nurse scheduling as a bi-objective problem with two competing objectives: minimize overtime cost versus minimize unmet patient demand. The original single-objective formulation bundled both goals into one weighted penalty sum, forcing the modeler to choose a penalty weight up front. This version unbundles them using the epsilon constraint method: it sweeps a range of caps on allowable unmet demand, and at each cap the solver minimizes overtime cost subject to that service-level constraint.
@@ -40,6 +38,7 @@ The result is a Pareto frontier that reveals exactly how much overtime cost each
 ## What's included
 
 - `hospital_staffing.py` -- Main script with model definition, epsilon constraint sweep, and Pareto analysis
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/nurses.csv` -- Nurse roster with skill levels, hourly costs, and overtime parameters
 - `data/shifts.csv` -- Shift definitions with timing, staffing requirements, and patient demand
 - `data/availability.csv` -- Nurse-to-shift availability matrix
@@ -119,10 +118,10 @@ The result is a Pareto frontier that reveals exactly how much overtime cost each
      4          eps_3           65.0 $         0.00
      5          eps_4           43.3 $         0.00
      6          eps_5           21.7 $       336.00
-     7   best_service            0.0 $      1116.00
+     7   best_service            0.0 $      1728.00
 
    Overtime Cost
-   $ 1,116.00 |7                                                 |
+   $ 1,728.00 |7                                                 |
               |                                                  |
               |                                                  |
               |                                                  |
@@ -141,7 +140,7 @@ The result is a Pareto frontier that reveals exactly how much overtime cost each
    Marginal analysis (cost of reducing unmet demand by 1 patient):
        cheapest -> eps_4         : $0.00/patient (free capacity available)
           eps_4 -> eps_5         : $15.51/patient
-          eps_5 -> best_service  : $36.00/patient
+          eps_5 -> best_service  : $64.25/patient
 
      Knee: Point 5 (eps_4) -- marginal cost jumps 15.5x beyond this point
      Recommendation: Target 43 unmet patients at $0.00 overtime cost --
@@ -158,8 +157,8 @@ The result is a Pareto frontier that reveals exactly how much overtime cost each
 
    The Pareto frontier reveals a sharp knee at point 5: the first 67% of
    demand reduction (130 to 43 patients) is free, but reducing the last 43
-   patients costs $1,116 in overtime -- the marginal cost jumps from $0 to
-   $15.51 then $36.00 per patient.
+   patients costs $1,728 in overtime -- the marginal cost jumps from $0 to
+   $15.51 then $64.25 per patient.
 
 ## Template structure
 ```text
@@ -173,136 +172,63 @@ The result is a Pareto frontier that reveals exactly how much overtime cost each
     └── availability.csv
 ```
 
-## How it works
-
-This section walks through the highlights in `hospital_staffing.py`.
+**Start here**: run `python hospital_staffing.py` for the full anchor-solve, epsilon-sweep, and Pareto analysis end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-### Define concepts and load CSV data
+## Sample data
 
-The model defines three core concepts: nurses with skill levels and cost parameters, shifts with coverage requirements and patient demand, and an availability relationship linking nurses to shifts.
+The bundled data is small and illustrative — a single hospital day with a handful of nurses and shifts, sized so the whole epsilon sweep solves in seconds. It is designed to make the cost-service tradeoff visible, not to match a specific hospital's roster.
 
-```python
-Nurse = Concept("Nurse", identify_by={"id": Integer})
-Nurse.name = Property(f"{Nurse} has {String:name}")
-Nurse.skill_level = Property(f"{Nurse} has {Integer:skill_level}")
-Nurse.hourly_cost = Property(f"{Nurse} has {Float:hourly_cost}")
+- **`nurses.csv`** — the nurse roster: skill level, hourly cost, regular-hour limit, and an overtime pay multiplier per nurse.
+- **`shifts.csv`** — shift definitions: start hour, duration, minimum nurses, minimum skill, patient demand, and the patients each nurse-hour can serve.
+- **`availability.csv`** — a nurse-to-shift availability matrix; `available = 1` means the nurse can work that shift.
 
-Shift = Concept("Shift", identify_by={"id": Integer})
-Shift.min_nurses = Property(f"{Shift} has {Integer:min_nurses}")
-Shift.min_skill = Property(f"{Shift} has {Integer:min_skill}")
-Shift.patient_demand = Property(f"{Shift} has {Integer:patient_demand}")
-```
+## Model overview
 
-### Define decision variables, constraints, and objective
+The model is a small optimization ontology: two entities (nurses, shifts) linked by an availability matrix, with a per-availability assignment decision the solver fills in.
 
-The `solve_staffing` helper encapsulates the full formulation. It registers four variable types and applies all constraints, then switches between objectives and an optional epsilon bound on unmet demand.
+- **Key entities**: `Nurse` — a nurse with a skill level and cost parameters (the solver adds overtime hours); `Shift` — a shift with coverage requirements and patient demand (the solver adds patients-served and unmet-demand quantities); `Availability` — a nurse's eligibility for a shift; `Assignment` — the decision to staff a nurse on a shift, the MILP's decision space.
+- **Primary identifiers**: `Nurse.id` and `Shift.id` (integers); `Availability` is keyed by the `(nurse_id, shift_id)` pair; `Assignment` is keyed by its `Availability`.
+- **Important invariants**: overtime hours, patients served, and unmet demand are non-negative continuous quantities; each nurse works one to two shifts; every shift meets its minimum-nurse and minimum-skill floor; assignment decisions are binary.
 
-The original single-objective template bundled overtime cost and unmet demand into one weighted penalty sum (`problem.minimize(overtime_cost + PENALTY * sum(Shift.x_unmet_demand))`). The bi-objective version splits them: the primary objective minimizes overtime cost, while unmet demand is bounded by an epsilon constraint. This eliminates the arbitrary penalty weight and reveals the true tradeoff.
+For the full concept and property definitions, see `hospital_staffing.py`; `runbook.md` builds them step by step with the RAI skills.
 
-```python
-def solve_staffing(objective="min_overtime", eps_unmet=None):
-    problem = Problem(model, Float)
-
-    problem.solve_for(Assignment.x_assigned, type="bin", populate=False,
-                name=["assigned", Assignment.availability.nurse.name,
-                      Assignment.availability.shift.name])
-    problem.solve_for(Nurse.x_overtime_hours, type="cont", populate=False,
-                name=["ot", Nurse.name], lower=0)
-    problem.solve_for(Shift.x_patients_served, type="cont", populate=False,
-                name=["pt", Shift.name], lower=0)
-    problem.solve_for(Shift.x_unmet_demand, type="cont", populate=False,
-                name=["ud", Shift.name], lower=0)
-```
+## How it works
 
-Constraints enforce availability, minimum staffing, skill coverage, overtime tracking, and patient demand accounting.
+**Define concepts and load CSV data.** The model defines three core concepts: nurses with skill levels and cost parameters, shifts with coverage requirements and patient demand, and an availability relationship linking nurses to shifts. A per-availability `Assignment` carries the binary staffing decision the solver fills in.
 
-```python
-    # Each nurse works 1-2 shifts
-    nurse_shift_count = sum(AssignmentRef.x_assigned).where(
-        AssignmentRef.availability.nurse == Nurse).per(Nurse)
-    problem.satisfy(model.require(nurse_shift_count >= 1))
-    problem.satisfy(model.require(nurse_shift_count <= 2))
+**Define decision variables, constraints, and objective.** A `solve_staffing` helper encapsulates the full formulation. It registers four variable types -- the binary assignment, each nurse's overtime hours, and each shift's patients-served and unmet-demand quantities -- and applies all constraints: availability, minimum staffing, skill coverage, overtime tracking, and patient-demand accounting (each nurse works one to two shifts; every shift meets its minimum-nurse floor). The original single-objective template bundled overtime cost and unmet demand into one weighted penalty sum, forcing the modeler to pick a penalty weight up front. The bi-objective version splits them: the primary objective minimizes overtime cost, while unmet demand is bounded by an epsilon constraint that caps total unmet demand across all shifts. This eliminates the arbitrary penalty weight and reveals the true tradeoff.
 
-    # Minimum nurses per shift with skill requirements
-    shift_staff_count = sum(AssignmentRef.x_assigned).where(
-        AssignmentRef.availability.shift == Shift).per(Shift)
-    problem.satisfy(model.require(shift_staff_count >= Shift.min_nurses))
-```
+**Solve anchor points and run the epsilon sweep.** Two anchor solves establish the feasible unmet-demand range: anchor 1 minimizes overtime with no demand constraint (the cheapest schedule, which may leave patients unserved), and anchor 2 minimizes unmet demand (the best achievable service level). The epsilon sweep then traces interior points between the anchors, each solve minimizing overtime cost subject to a progressively tighter cap on unmet demand.
 
-When `eps_unmet` is provided, a constraint caps total unmet demand across all shifts.
+**Pareto analysis output.** The script prints the efficient frontier showing how overtime cost rises as the unmet-demand cap tightens. Marginal analysis computes the cost of reducing unmet demand by one patient, and a knee detector flags the point where that marginal cost jumps sharply -- recommending the best cost-service balance.
 
-```python
-    if eps_unmet is not None:
-        problem.satisfy(model.require(sum(Shift.x_unmet_demand) <= eps_unmet))
-```
+See `hospital_staffing.py` for the implementation, and `runbook.md` for the skill-driven reproduction.
 
-The objective switches between minimizing overtime cost (primary) and minimizing unmet demand (used for anchor solve 2).
+## Customize this template
 
-```python
-    overtime_cost = sum(Nurse.x_overtime_hours * Nurse.hourly_cost * Nurse.overtime_multiplier)
+Focus on the first changes most users will make.
 
-    if objective == "min_overtime":
-        problem.minimize(overtime_cost)
-    elif objective == "min_unmet":
-        problem.minimize(sum(Shift.x_unmet_demand))
+### Use your own data
 
-    problem.solve("highs", time_limit_sec=60)
-```
+- Replace the CSVs in `data/` with your own roster, shifts, and availability; keep the column names listed in *Sample data* above.
+- Ensure `availability.csv` only references valid nurse and shift IDs, and that available nurses provide enough coverage to meet each shift's `min_nurses` and `min_skill` requirements.
+- Add more nurses or shifts simply by appending rows to the CSVs.
 
-### Solve anchor points and run the epsilon sweep
+### Tune parameters
 
-Two anchor solves establish the feasible unmet demand range. Anchor 1 minimizes overtime with no demand constraint (finding the cheapest schedule, which may leave patients unserved). Anchor 2 minimizes unmet demand (finding the best achievable service level).
+- **Frontier resolution** — increase `n_interior` for a finer-grained Pareto frontier (more interior epsilon points between the two anchors).
+- **Solve budget** — `time_limit_sec` on `problem.solve("highs", ...)` caps each solve; raise it if larger rosters time out.
 
-```python
-result1 = solve_staffing("min_overtime", eps_unmet=None)
-result2 = solve_staffing("min_unmet", eps_unmet=None)
-```
+### Extend the model
 
-The epsilon sweep then traces interior points between the anchors. Each solve minimizes overtime cost subject to a progressively tighter cap on unmet demand.
+- **Add shift preferences** by introducing a preference weight per nurse-shift pair and folding it into the objective.
+- **Model consecutive-shift restrictions** by adding constraints that prevent nurses from working back-to-back shifts without rest.
+- **Introduce part-time nurses** with different regular-hour limits and availability patterns.
 
-```python
-n_interior = 5
-epsilon_values = [
-    unmet_max - i * (unmet_max - unmet_min) / (n_interior + 1)
-    for i in range(1, n_interior + 1)
-]
+### Scale up / productionize
 
-for i, eps in enumerate(epsilon_values):
-    result = solve_staffing("min_overtime", eps_unmet=eps)
-```
-
-### Pareto analysis output
-
-The script prints the efficient frontier showing how overtime cost increases as the unmet demand cap tightens. Marginal analysis computes the cost of reducing unmet demand by one patient, and a knee detector identifies the point where the marginal cost jumps sharply -- recommending the best cost-service balance.
-
-```python
-print(f"{'#':>3} {'Label':>14} {'Unmet Demand':>14} {'Overtime Cost':>14}")
-for j, pt in enumerate(pareto):
-    print(f"{j+1:>3} {pt['label']:>14} {pt['unmet_demand']:>14.1f} ${pt['overtime_cost']:>13.2f}")
-
-# Marginal analysis (cost of reducing unmet demand by 1 patient)
-for j in range(len(pareto) - 1):
-    d_cost = pareto[j+1]['overtime_cost'] - pareto[j]['overtime_cost']
-    d_unmet = pareto[j]['unmet_demand'] - pareto[j+1]['unmet_demand']
-    if abs(d_unmet) > 1e-6:
-        rate = d_cost / d_unmet
-        # ...
-
-# Knee detection
-print(f"\n  Knee: Point {knee_idx + 1} ({pareto[knee_idx]['label']}) "
-      f"— marginal cost jumps {max_jump:.1f}x beyond this point")
-print(f"  Recommendation: Target {pareto[knee_idx]['unmet_demand']:.0f} unmet patients "
-      f"at ${pareto[knee_idx]['overtime_cost']:.2f} overtime cost — "
-      f"further service improvement costs significantly more per patient.")
-```
-
-## Customize this template
-
-- **Add more nurses or shifts** by extending the CSV files with additional rows.
-- **Adjust frontier resolution**: Increase `n_interior` for a finer-grained Pareto frontier.
-- **Add shift preferences** by introducing a preference weight per nurse-shift pair and including it in the objective.
-- **Model consecutive shift restrictions** by adding constraints that prevent nurses from working back-to-back shifts without rest.
-- **Introduce part-time nurses** with different regular hour limits and availability patterns.
+- Swap the `read_csv(...)` loads for `model.data(snowflake_table)` calls to run against roster and demand tables maintained in Snowflake.
+- Pin `relationalai` in `pyproject.toml` for reproducible solves, and schedule the run to refresh the frontier as demand forecasts update.
 
 ## Troubleshooting
 
@@ -329,3 +255,22 @@ Run `rai init` to configure your Snowflake connection. Verify that the RAI Nativ
 
 Ensure you activated the virtual environment and ran `python -m pip install .` to install all dependencies listed in `pyproject.toml`.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Prescriptive reasoning](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives.
+- [PyRel v1 modeling](https://docs.relational.ai/) — concepts, properties, and loading CSV data into relations.
+
+### Modeling reference
+
+- [Multi-objective optimization](https://docs.relational.ai/) — trading off competing objectives, including epsilon-constraint sweeps.
+
+### Deeper dives
+
+- [Sensitivity and marginal analysis](https://docs.relational.ai/) — reading shadow prices and marginal costs, as the Pareto knee detection does here.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/humanitarian-aid-supply-chain/README.md b/v1/humanitarian-aid-supply-chain/README.md
index f1b68449..6434766a 100644
--- a/v1/humanitarian-aid-supply-chain/README.md
+++ b/v1/humanitarian-aid-supply-chain/README.md
@@ -31,29 +31,36 @@ PageRank simulates how aid flows through the network using iterative random walk
 
 ## What you'll build
 
-- Load a humanitarian aid network with 18 distribution points and 28 directed supply routes from CSV files
-- Use RelationalAI's Graph API to model a weighted, directed supply chain network
-- Calculate PageRank to identify where aid flows naturally concentrate (influence)
-- Calculate Weighted Degree Centrality to find highly connected coordination nodes (network hubs)
-- Analyze strategic categories: critical coordination hubs, influential endpoints, and network connectors
-- Generate actionable recommendations for resource deployment and network resilience
-- Compare multiple graph metrics to make informed strategic decisions
+- A weighted, directed supply-chain graph over distribution points and routes, built with RelationalAI's Graph API
+- A per-node PageRank score identifying where aid naturally concentrates (influence)
+- A per-node Weighted Degree Centrality score surfacing highly connected coordination hubs
+- A strategic classification of every distribution point (critical coordination hub, influential endpoint, or network connector) from the two metrics together
+- A ranked deployment-priority table with actionable recommendations, exportable to CSV
+- An optional Streamlit dashboard visualizing the network and rankings interactively
 
-This template uses **RelationalAI's advanced graph algorithms** including PageRank (an iterative algorithm requiring multiple passes over the network) and Weighted Degree Centrality (analyzing network connectivity patterns).
+Built using **graph analysis** — PageRank (an iterative random-walk algorithm) and Weighted Degree Centrality (network-connectivity analysis) on a shared supply-chain ontology.
 
 ## What's included
 
 - **Shared model setup**: `model_setup.py` - Common model configuration and graph creation (used by both scripts)
 - **Command-line script**: `humanitarian_aid_supply_chain.py` - CLI analysis script with detailed output
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Interactive app**: `app.py` - Streamlit web application with visualizations and interactive analysis
 - **Data**: `data/distribution_points.csv` and `data/supply_routes.csv`
 
 ## Prerequisites
 
-- Python >= 3.10
+### Access
+
 - A Snowflake account that has the RAI Native App installed.
 - A Snowflake user with permissions to access the RAI Native App.
 
+### Tools
+
+- Python >= 3.10
+- RelationalAI Python SDK (`relationalai == 1.11.0`)
+- For the interactive app only: the `visualization` extra (`python -m pip install .[visualization]`)
+
 ## Quickstart
 
 Follow these steps to run the template with the included sample data.
@@ -116,213 +123,117 @@ You can customize the data and model as needed after you have it running end-to-
    - Detailed strategic-category analysis
    - CSV export functionality
 
-## Model overview
+6. Expected output (a few lines confirm a successful run):
 
-The `SupplyRoute` concept represents directed supply routes between distribution points with weighted attributes.
+   ```text
+   By PageRank (where aid concentrates):
+     Emergency Field Hospital   0.1097
+   By weighted degree centrality (coordination hubs):
+     Central Warehouse          794.81  (9 routes)
 
-| Property | Type | Notes |
-|---|---|---|
-| `from_point` | DistributionPoint | Source point in the supply route |
-| `to_point` | DistributionPoint | Destination point in the supply route |
-| `route_capacity` | Integer | Maximum throughput (units/day) |
-| `reliability_score` | Float | Route reliability (0-1 scale) |
-| `distance_km` | Integer | Physical distance for routing calculations |
+   Strategic categories: 2 critical coordination hubs,
+     4 influential endpoints, 4 network connectors
+   ```
 
-### Flow Weight Property
+   See `runbook.md` for the full ranked tables and the strategic-category walkthrough.
 
-The flow weight property represents expected aid throughput considering capacity, reliability, and distance and is calculated using the following formula:
+## Template structure
 
 ```text
-flow_weight = (route_capacity * reliability_score) / distance_km
+humanitarian-aid-supply-chain/
+├── README.md                          # this file
+├── pyproject.toml                     # dependencies
+├── model_setup.py                     # shared model + graph construction
+├── humanitarian_aid_supply_chain.py   # CLI analysis script
+├── app.py                             # optional Streamlit dashboard
+├── runbook.md                         # analyst-facing walkthrough
+└── data/
+    ├── distribution_points.csv        # 18 distribution points
+    └── supply_routes.csv              # 28 directed supply routes
 ```
 
-### Graph Metrics
+**Start here**: run `python humanitarian_aid_supply_chain.py` for the full command-line analysis end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills. You can also launch `streamlit run app.py` for the interactive dashboard. All paths build the model through `model_setup.create_model()`.
 
-The template calculates these advanced metrics using RelationalAI's Graph API:
+## Sample data
 
-| Metric | Type | Description |
-|---|---|---|
-| `pagerank` | Float | Influence score (0-1) based on iterative random walk simulation. Higher = more aid naturally flows here |
-| `degree_centrality` | Float | Sum of flow weights for all connected routes. Higher = more influential hub |
-| `incoming_routes` | Integer | Indegree: number of supply routes delivering TO this point |
-| `outgoing_routes` | Integer | Outdegree: number of supply routes originating FROM this point |
+The bundled data is small and illustrative — an 18-node humanitarian relief network sized to make the two centrality metrics tell contrasting stories, not to match a specific operation.
 
-## How it works
-
-The template follows this flow:
+- **`distribution_points.csv`** (18 rows) — airports, warehouses, border crossings, and relief camps, each with a type, region, capacity, and population served.
+- **`supply_routes.csv`** (28 rows) — directed routes between points, each carrying a throughput capacity, a reliability score, and a physical distance used to derive the flow weight.
 
-```text
-CSV files → model_setup.create_model() → Calculate PageRank → Calculate Degree Centrality → Analyze strategic categories → Display results
-```
+## Model overview
 
-### 1. Shared Model Setup
+The model is a small graph ontology: distribution points connected by directed, weighted supply routes. Graph metrics are computed at query time from the route graph rather than stored on the point.
 
-Both the CLI script and Streamlit app use the same model setup from `model_setup.py`:
+- **Key entities**: `DistributionPoint` — a node in the relief network (airport, warehouse, border crossing, or relief camp); `SupplyRoute` — a directed route between two distribution points, with weighted attributes (throughput capacity, reliability, distance).
+- **Primary identifiers**: `DistributionPoint.id` (integer); `SupplyRoute` is keyed by its `(from_point, to_point)` pair.
+- **Important invariants**: `reliability_score` is a fraction in `[0, 1]`; capacity and distance are positive; the derived `flow_weight` combines all three into the edge weight the graph algorithms read.
 
-```python
-from model_setup import create_model
+The two centrality metrics (`pagerank`, `degree_centrality`) and the degree counts (`incoming_routes`, `outgoing_routes`) are computed by the Graph API over the route graph at query time, not stored as `DistributionPoint` properties.
 
-# Create the model, concepts, relationships, and graph (all in one call)
-model, graph, DistributionPoint, SupplyRoute = create_model()
-```
+For the full concept and property definitions, see `model_setup.py`; `runbook.md` builds them step by step with the RAI skills.
 
-The `create_model()` function handles:
-- Creating the RelationalAI model container
-- Defining the `DistributionPoint` concept with all properties
-- Loading distribution points from CSV
-- Defining the `SupplyRoute` concept with weighted properties
-- Loading supply routes from CSV
-- Creating the weighted, directed graph
-- Returning all components for use in analysis
-
-### 2. Calculate PageRank (Iterative Algorithm)
+## How it works
 
-PageRank simulates random walks through the network to identify influential nodes:
+The template follows this flow:
 
-```python
-# Calculate PageRank with damping factor 0.85
-# Damping factor models probability of continuing along routes vs. teleporting
-pagerank = graph.pagerank(damping_factor=0.85, tolerance=1e-6, max_iter=100)
+```text
+CSV files → model_setup.create_model() → Calculate PageRank → Calculate Degree Centrality → Analyze strategic categories → Display results
 ```
 
-**How PageRank works:**
-1. Start with equal probability at all nodes
-2. Iteratively propagate probability along edges
-3. Apply damping factor: 85% chance of following an edge, 15% chance of "teleporting" to random node
-4. Converge when probabilities stabilize (tolerance threshold)
-5. Higher PageRank = more "important" in the network flow
-
-### 3. Calculate Weighted Degree Centrality
-
-Degree Centrality identifies highly connected network hubs:
+**Shared model setup.** Both the CLI script and the Streamlit app build the model through `model_setup.create_model()`, which creates the model container, defines the `DistributionPoint` and weighted `SupplyRoute` concepts, loads both CSVs, and constructs the weighted, directed route graph — returning every component the analysis needs.
 
-```python
-# Calculate Degree Centrality
-degree_centrality = graph.degree_centrality()
-
-# Also calculate degree metrics for context
-indegree = graph.indegree()   # Incoming routes
-outdegree = graph.outdegree()  # Outgoing routes
-```
+**Calculate PageRank.** PageRank simulates random walks through the network to find where aid naturally concentrates. Starting from equal probability at every node, it iteratively propagates probability along edges, applying a damping factor (85% chance of following a route, 15% chance of teleporting to a random node) until the scores stabilize. A higher score means a node is more central to network flow.
 
-**How Weighted Degree Centrality works:**
-1. Sum the flow weights for all connected routes (capacity × reliability) for each node
-2. Higher weighted degree = more influential hub with greater aid throughput capacity
-3. Accounts for both connectivity AND the strength/importance of those connections
-4. Identifies nodes that serve as critical coordination hubs with substantial flow capacity
-
-### 4. Query and analyze strategic categories
-
-Query both metrics and assign a strategic category to each distribution point.
-
-```python
-from relationalai.semantics import where, select
-
-# Create variable references
-point = graph.Node.ref("point")
-pr_score = Float.ref("pr_score")
-dc_score = Float.ref("dc_score")
-in_routes = Integer.ref("in_routes")
-out_routes = Integer.ref("out_routes")
-
-# Query all metrics together
-results = where(
-    pagerank(point, pr_score),
-    degree_centrality(point, dc_score),
-    indegree(point, in_routes),
-    outdegree(point, out_routes)
-).select(
-    point.id,
-    point.name,
-    point.type,
-    point.region,
-    point.capacity,
-    point.population_served,
-    pr_score.alias("pagerank"),
-    dc_score.alias("degree_centrality"),
-    in_routes.alias("incoming_routes"),
-    out_routes.alias("outgoing_routes")
-).to_df()
-
-# Assign a strategic category based on both metrics
-pr_threshold = results['pagerank'].quantile(0.70)
-dc_threshold = results['degree_centrality'].quantile(0.70)
-
-# Critical Coordination Hubs: High PageRank + High Degree Centrality
-critical_hubs = results[
-    (results['pagerank'] >= pr_threshold) &
-    (results['degree_centrality'] >= dc_threshold)
-]
-
-# Influential Endpoints: High PageRank + Lower Degree Centrality
-influential_endpoints = results[
-    (results['pagerank'] >= pr_threshold) &
-    (results['degree_centrality'] < dc_threshold)
-]
-
-# Network Connectors: Lower PageRank + High Degree Centrality
-connectors = results[
-    (results['pagerank'] < pr_threshold) &
-    (results['degree_centrality'] >= dc_threshold)
-]
-```
+**Calculate weighted degree centrality.** This sums each node's flow weights (capacity × reliability across its routes), so it rewards not just how many connections a node has but how strong they are. A high weighted degree marks a coordination hub with substantial aid throughput. Indegree and outdegree are also computed for context.
 
-### 5. Display strategic analysis and recommendations
+**Query and analyze strategic categories.** Both metrics are queried together into a DataFrame, then each distribution point is classified against the 70th-percentile thresholds on the two scores: critical coordination hubs (high on both), influential endpoints (high PageRank, lower degree), and network connectors (lower PageRank, high degree).
 
-**CLI script** (`humanitarian_aid_supply_chain.py`) prints:
-- Ranked table of all distribution points with both metrics
-- Strategic category analysis (Critical Coordination Hubs, Influential Endpoints, Network Connectors)
-- Network-wide and regional statistics
-- Actionable recommendations for emergency response teams
+**Display strategic analysis and recommendations.** The CLI script prints a ranked table of all points with both metrics, the strategic-category breakdown, network-wide and regional statistics, and recommendations for response teams. The Streamlit app adds an interactive overview, a color-coded network visualization, filterable rankings with CSV export, and per-category detail.
 
-**Streamlit app** (`app.py`) provides:
-- Interactive overview with top-5 rankings
-- Network visualization with color-coded nodes by strategic category
-- Detailed filterable rankings with CSV export
-- Strategic analysis with expandable details for each category
-- Regional distribution statistics
+See `model_setup.py` and `humanitarian_aid_supply_chain.py` for the implementation, and `runbook.md` for the skill-driven reproduction.
 
 ## Customize this template
 
-**Use your own data:**
-
-- Replace the CSV files in the `data/` directory with your own supply chain network, keeping the same column names (or update the logic in `model_setup.py`).
-- Ensure that supply routes only reference valid distribution point IDs.
-- You can add additional properties to distribution points (organization, contact info, GPS coordinates) by adding columns to the CSV and corresponding properties to the model in `model_setup.py`.
-
-**Extend the model:**
+Focus on the first changes most users will make.
 
-- **Adjust PageRank parameters**: Experiment with different damping factors:
+### Use your own data
 
-  - Higher damping (0.90-0.95): More emphasis on network structure, less on random teleportation
-  - Lower damping (0.70-0.80): More emphasis on direct connections, less on global influence
+- Replace the CSVs in `data/` with your own network, keeping the same column names (or update the loading logic in `model_setup.py`).
+- Ensure supply routes only reference valid distribution-point IDs.
+- Add properties to distribution points (organization, contact info, GPS coordinates) by adding CSV columns and the corresponding properties in `model_setup.py`.
 
-- **Add different edge weights**: Change the graph edge weight formula in `model_setup.py` to optimize for different factors. Remember: **for PageRank, use direct multipliers**—higher weights indicate stronger connections that PageRank will favor.
+### Tune parameters
 
-  Current formula: `(route_capacity * reliability_score) / distance_km` — good for balanced optimization
+- **PageRank damping factor** — higher damping (0.90-0.95) emphasizes network structure over teleportation; lower damping (0.70-0.80) emphasizes direct connections over global influence.
+- **Edge-weight formula** — change the `flow_weight` formula in `model_setup.py` to reweight the graph. Higher weights indicate stronger connections that PageRank favors.
 
-  Alternative formulas (all using direct multipliers):
+  The current formula `(route_capacity * reliability_score) / distance_km` balances all three factors. Alternatives:
   - Capacity-focused: `route_capacity` (maximize throughput)
   - Reliability-focused: `reliability_score` (emphasize route stability)
   - Simple combined: `route_capacity * reliability_score` (ignore distance)
 
-- **Try additional algorithms**:
+### Extend the model
 
-  - `graph.louvain()` - Community detection to identify regional aid distribution clusters
-  - `graph.is_reachable(point1, point2)` - Verify connectivity between specific locations
-  - `graph.distance(point1, point2)` - Calculate shortest path length between points
-  - `graph.weakly_connected_components()` - Identify disconnected network regions
+- **Try additional algorithms**:
+  - `graph.louvain()` — community detection to find regional distribution clusters
+  - `graph.is_reachable(point1, point2)` — verify connectivity between two locations
+  - `graph.distance(point1, point2)` — shortest-path length between points
+  - `graph.weakly_connected_components()` — identify disconnected network regions
+- **Add temporal analysis** — include route availability schedules or seasonal variations to model time-dependent supply chains.
+- **Incorporate risk factors** — add node properties for conflict zones, disease prevalence, or disaster risk to prioritize safe routes.
 
-**Add temporal analysis**: Include route availability schedules or seasonal variations to model time-dependent supply chains.
+### Scale up / productionize
 
-**Incorporate risk factors**: Add node properties for conflict zones, disease prevalence, or natural disaster risk to prioritize safe routes.
+- Swap the `read_csv(...)` loads in `model_setup.py` for `model.data(snowflake_table)` calls to run against a network catalog maintained in Snowflake.
+- Pin `relationalai` in `pyproject.toml` for reproducible runs, and schedule the CLI script to refresh rankings as the network changes.
 
 ## Troubleshooting
 
 <details>
   <summary>Why does authentication/configuration fail?</summary>
 
-- Run `rai init` to create/update `raiconfig.toml`.
+- Run `rai init` to create/update `raiconfig.yaml`.
 - If you have multiple profiles, set `RAI_PROFILE` or switch profiles in your config.
 
 </details>
@@ -330,7 +241,7 @@ connectors = results[
 <details>
   <summary>Why does the script fail to connect to the RAI Native App?</summary>
 
-- Verify the Snowflake account/role/warehouse and `rai_app_name` are correct in `raiconfig.toml`.
+- Verify the Snowflake account/role/warehouse and `rai_app_name` are correct in `raiconfig.yaml`.
 - Ensure the RAI Native App is installed and you have access.
 
 </details>
@@ -364,3 +275,22 @@ connectors = results[
   - Just update the CSV data and entity names to match your domain.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Graph analysis](https://docs.relational.ai/) — building graphs from an ontology and running centrality and community algorithms.
+- [PyRel v1 modeling](https://docs.relational.ai/) — concepts, properties, and loading CSV data into relations.
+
+### Modeling reference
+
+- [PageRank and centrality](https://docs.relational.ai/) — influence and connectivity measures, damping, and convergence.
+
+### Deeper dives
+
+- [Querying graph results](https://docs.relational.ai/) — selecting, aliasing, and exporting metric results to DataFrames and CSV.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/it-dependency-mapping/README.md b/v1/it-dependency-mapping/README.md
index f9af79d9..ff76dce2 100644
--- a/v1/it-dependency-mapping/README.md
+++ b/v1/it-dependency-mapping/README.md
@@ -1,6 +1,6 @@
 ---
 title: "IT Dependency Mapping"
-description: "Map the downstream dependency structure of a software and data-pipeline estate by enumerating variable-length traversal paths over an acyclic dependency graph, then surface the longest end-to-end chains and the owners along them."
+description: "Map the downstream dependency structure of a software and data-pipeline estate by enumerating variable-length paths over an acyclic dependency graph. Surface the longest end-to-end chains and the owners along them to see a change or outage's full blast radius."
 experience_level: intermediate
 industry: "Technology & Telecom"
 featured: false
@@ -45,6 +45,7 @@ Built using RelationalAI's **variable-length path enumeration** (`model.path(...
 ## What's included
 
 - **Self-contained script**: `it_dependency_mapping.py` -- Runs the full analysis end-to-end
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Data**: `data/features.csv` (14 features across tiers) and `data/dependencies.csv` (15 dependency edges)
 
 ## Prerequisites
@@ -152,23 +153,7 @@ A single concept, `Feature`, represents every node in the estate, and one self-r
 - **Primary identifiers**: the string `id` on `Feature`.
 - **Important invariants**: the `contributes_to` graph is acyclic — a feature does not depend on itself, so every enumerated traversal path is a simple chain.
 
-### `Feature`
-
-A node in the estate -- a raw source, ingestion pipeline, feature job, service, or dashboard.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | string | Yes | Loaded from `data/features.csv` |
-| `name` | string | No | Human-readable name |
-| `owner` | string | No | Person responsible for the feature |
-| `deploy_tier` | string | No | Criticality tier: `critical`, `high`, or `standard` |
-| `max_downstream_depth` | int | No | Longest downstream dependency depth, persisted back to the ontology after path enumeration |
-
-### Relationships
-
-| Relationship | Schema | Notes |
-|---|---|---|
-| `contributes_to(Feature, Feature)` | upstream `Feature`, downstream `Feature` | A Feature -> Feature self-relationship: the upstream feature feeds the downstream one. Acyclic, so it forms a dependency DAG. |
+For the full concept and property definitions, see `it_dependency_mapping.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
@@ -176,84 +161,15 @@ A node in the estate -- a raw source, ingestion pipeline, feature job, service,
 CSV files --> Define Feature + contributes_to --> Enumerate downstream paths --> Reduce to maximal chains --> Trace owners along longest chain
 ```
 
-### 1. Load Ontology
+**Load the ontology.** A `Feature` is any node in the estate -- a raw source, pipeline, feature job, service, or dashboard -- with `id`, `name`, `owner`, and `deploy_tier` loaded from `data/features.csv`. The `contributes_to` self-relationship records that an upstream feature feeds a downstream one, forming the dependency DAG from `data/dependencies.csv`.
 
-A `Feature` is any node in the estate -- a raw source, pipeline, feature job, service, or dashboard. The `contributes_to` self-relationship records that an upstream feature feeds a downstream one, forming the dependency DAG:
+**Enumerate downstream paths.** A variable-length traversal of 1 to `MAX_DEPTH` `contributes_to` edges, enumerated with `.all_paths()`, walks every downstream dependency path. Each path arrives as one row per visited node; grouping by path reassembles the ordered chain, and the hop count comes from the maximum node index. (Selecting the path length alongside the nodes would fan the rows out, so the code derives hops from the index and dedupes before reassembly.)
 
-```python
-Feature = model.Concept("Feature", identify_by={"id": String})
-Feature.name = model.Property(f"{Feature} has {String:name}")
-Feature.owner = model.Property(f"{Feature} owned by {String:owner}")
-Feature.deploy_tier = model.Property(f"{Feature} has deploy tier {String:deploy_tier}")
+**Persist longest downstream depth.** The longest path starting at each feature is its downstream depth. RelationalAI computes it in PyRel — a max over path length per source endpoint — and defines it straight onto the feature as a first-class `max_downstream_depth` property, with no DataFrame round-trip, so later queries can rank features by reach without re-enumerating paths.
 
-Feature.contributes_to = model.Relationship(
-    f"{Feature} contributes to {Feature}", short_name="contributes_to"
-)
-```
-
-### 2. Enumerate Downstream Paths
-
-`model.path(Feature.contributes_to.repeat(1, MAX_DEPTH))` describes a variable-length traversal of 1 to `MAX_DEPTH` `contributes_to` edges. `all_paths()` enumerates every such path. Each result is a `PathTraversal`; project `p.nodes` to get the ordered features it visits. Do not also select `p.length` alongside `p.nodes` -- that fans the node rows out; derive the hop count from the maximum node index instead:
-
-```python
-p_pattern = model.path(Feature.contributes_to.repeat(1, MAX_DEPTH))
-paths_df = (
-    model.where(p := p_pattern.all_paths())
-    .select(
-        p.alias("path_id"),
-        p.nodes["index"].alias("step"),
-        Feature(p.nodes).id.alias("feature_id"),
-        Feature(p.nodes).name.alias("feature_name"),
-    )
-    .to_df()
-)
-paths_df["step"] = paths_df["step"].astype(int)
-# Projecting p.nodes can emit duplicate (path, step) rows -- dedupe before reassembly.
-paths_df = paths_df.drop_duplicates(["path_id", "step"]).sort_values(["path_id", "step"])
-```
-
-Each path arrives as one row per visited node. Grouping on the path-id column reassembles the ordered chain; the hop count is the maximum node index:
-
-```python
-chains = (
-    paths_df.groupby("path_id")
-    .agg(
-        hops=("step", "max"),
-        node_ids=("feature_id", lambda s: tuple(s)),
-        chain=("feature_name", lambda s: " -> ".join(s)),
-    )
-    .reset_index()
-)
-```
-
-### 3. Persist Longest Downstream Depth
-
-The longest path starting at each feature is its downstream depth. RelationalAI computes it in PyRel with `aggregates.max(p.length).per(src)` over a typed source endpoint and defines it straight onto the feature as a first-class property — no DataFrame round-trip — so a downstream query can rank features by reach without re-enumerating paths:
-
-```python
-Feature.max_downstream_depth = model.Property(
-    f"{Feature} has {Integer:max_downstream_depth}"
-)
-src = Feature.ref()
-p = model.path(src, Feature.contributes_to.repeat(1, MAX_DEPTH)).all_paths()
-model.define(src.max_downstream_depth(aggs.max(p.length).per(src))).where(p)
-```
-
-### 4. Reduce to Maximal Chains
-
-The full path set contains every sub-chain. A path is *maximal* when its node sequence is not a contiguous sub-chain of any other enumerated path -- it cannot be extended upstream or downstream. Filtering to maximal chains leaves only the end-to-end propagation paths:
-
-```python
-maximal = chains[
-    chains["node_ids"].apply(
-        lambda seq: not any(
-            is_sub_chain(seq, other) for other in all_sequences if other != seq
-        )
-    )
-].copy()
-```
+**Reduce to maximal chains.** The full path set contains every sub-chain. A path is *maximal* when its node sequence is not a contiguous sub-chain of any other enumerated path -- it cannot be extended upstream or downstream. Filtering to maximal chains leaves only the end-to-end propagation paths. The single longest maximal chain is the worst-case blast radius: joining owner metadata onto its features shows every person a change at the root would have to clear before it reaches the final consumer.
 
-The single longest maximal chain is the worst-case blast radius: joining owner metadata onto its features shows every person a change at the root would have to clear before it reaches the final consumer.
+See `it_dependency_mapping.py` for the implementation, and `runbook.md` for the skill-driven reproduction.
 
 ## Expected output
 
@@ -322,7 +238,7 @@ The deepest chain runs five hops from a raw source all the way to a downstream d
 <details>
   <summary>Why does authentication/configuration fail?</summary>
 
-- Run `rai init` to create/update `raiconfig.toml`.
+- Run `rai init` to create/update `raiconfig.yaml`.
 - If you have multiple profiles, set `RAI_PROFILE` or switch profiles in your config.
 
 </details>
diff --git a/v1/memory_supply_allocation/README.md b/v1/memory_supply_allocation/README.md
index 21a25884..12e98deb 100644
--- a/v1/memory_supply_allocation/README.md
+++ b/v1/memory_supply_allocation/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Memory Supply Allocation"
-description: "Monthly rolling-horizon allocation of constrained memory-chip supply across customers with supplier dependencies, named foundries, and raw-material inputs: predicted supplier capability feeds the optimization, customer-customer paths surface single points of failure, and two what-if scenarios trace supplier-offline and input-shortage cascades."
+description: "Allocate limited memory-chip supply across customers month by month to maximize margin while protecting key accounts. Also surfaces which suppliers and raw materials put the plan most at risk."
 featured: false
 experience_level: intermediate
 industry: "Technology & Telecom"
@@ -44,7 +44,8 @@ This template shows how RelationalAI answers that question on a single shared mo
 ## What's included
 
 - **Model**: `memory_supply_allocation.py` — the four-reasoner chain end-to-end on one ontology
-- **Runner**: a single Python script (`python memory_supply_allocation.py`); `runbook.md` gives an analyst-facing, paste-testable walkthrough with one prompt per stage
+- **Runner**: a single Python script (`python memory_supply_allocation.py`)
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills, one prompt per stage; as important a reference as the script itself.
 - **Sample data**: 13 CSVs under `data/` (customers, products, periods, demand, suppliers, capacity, inputs, dependencies, and the disruption schedule)
 - **Outputs**: per-iteration LP status and margin, plan-diffs, service levels, dependency chains, and what-if rankings — all printed and persisted back to the ontology for later querying
 
@@ -147,7 +148,7 @@ Then provision a GPU-sized predictive reasoner (`GPU_NV_S`) and reference it in
     └── disruption_reveal.csv
 ```
 
-**Start here**: `python memory_supply_allocation.py` runs all four reasoners end-to-end.
+**Start here**: run `python memory_supply_allocation.py` for all four reasoners end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Sample data
 
@@ -170,111 +171,11 @@ The sample data models a memory-chip maker allocating constrained supply across
 
 The model is one shared ontology that all four reasoners read and write.
 
-- **Key entities**: `Customer`, `Product`, `Period`, `Supplier`, `Input`, and the junction concepts `Demand`, `SupplierProductCapacity`, `InputUsage`, and `Dependency`.
+- **Key entities**: `Customer` — a chip buyer; `Product` — a memory SKU; `Period` — a monthly bucket in the horizon; `Supplier` — a foundry/fab; `Input` — a raw material; plus junction concepts `Demand` (requested USD per customer/product/period, carrying the LP decision variable), `SupplierProductCapacity` (monthly capacity per supplier/product/period), `InputUsage` (each SKU's exposure to each input), and `Dependency` (a customer-to-customer protection edge).
 - **Primary identifiers**: single-column integer ids for the base entities; composite keys for the junctions (e.g. `Demand` is keyed by `(customer_id, product_id, period_id)`).
 - **Important invariants**: demand and capacity are non-negative USD; `base_service_floor_pct`, `elevated_floor_pct`, `declared_yield_pct`, `intensity`, and `capability_pct` are fractions in `[0, 1]`; each customer's allocation must lie between its service floor and its yield-adjusted demand.
 
-### Concepts
-
-**`Customer`** — a chip buyer. The first four properties are loaded from CSV; the rest are **rules-authored** in Stage 1 and queryable after the run.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | int | Yes | Loaded from `data/customers.csv` |
-| `name` | string | No | Human-readable name |
-| `industry` | string | No | Buyer segment (e.g. Hyperscaler, Foundry Equipment, Precision Optics) |
-| `base_service_floor_pct` | float | No | Minimum share of demand the customer must receive |
-| `max_declared_yield_pct` | float | No | Derived: max share this customer will yield to upstream |
-| `elevated_floor_pct` | float | No | Derived: lifted floor from incoming dependencies |
-| `n_incoming_dependencies` | int | No | Derived: count of protecting edges |
-| `has_elevated_floor` | bool | No | Derived: effective floor exceeds base |
-| `is_dependency_spof` | bool | No | Derived: single protecting edge → single point of failure |
-
-**`Product`** — a memory SKU.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | int | Yes | Loaded from `data/products.csv` |
-| `name` | string | No | e.g. `HBM3E` |
-| `family` | string | No | Product family (HBM / DDR / LPDDR / NAND) |
-| `unit_price_usd_per_gb` | float | No | List price |
-| `margin_pct` | float | No | Objective weight in the LP |
-
-**`Period`** — a monthly bucket in the horizon.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | int | Yes | Loaded from `data/periods.csv` |
-| `month_num` | int | No | 1…36 |
-| `label` | string | No | e.g. `2026-01` |
-
-**`Supplier`** — a foundry/fab. Base properties load from `suppliers.csv`; static features load from `supplier_features.csv`; the last two are what-if outputs persisted in Stage 4.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | int | Yes | Loaded from `data/suppliers.csv` |
-| `name` | string | No | e.g. `Orion Foundry` |
-| `type` | string | No | Foundry / Memory Fab / NAND Fab |
-| `equipment_age_months` | int | No | GNN feature |
-| `geopolitical_exposure_score` | float | No | GNN feature |
-| `region` | string | No | GNN feature (categorical) |
-| `process_node_nm` | int | No | GNN feature |
-| `workforce_size_k` | int | No | GNN feature |
-| `offline_impact_cells` | int | No | What-if output: cells affected if offline |
-| `offline_max_cap_drop_pct` | float | No | What-if output: max capacity drop |
-
-**`Demand`** — requested USD per customer/product/period; also carries the LP decision variable.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `customer_id` | int | Yes | Loaded from `data/demand.csv` |
-| `product_id` | int | Yes | Loaded from `data/demand.csv` |
-| `period_id` | int | Yes | Loaded from `data/demand.csv` |
-| `demand_usd` | float | No | Requested USD |
-| `x_alloc` | float | No | Decision variable: allocated USD |
-
-**`SupplierProductCapacity`** — nominal monthly capacity per supplier/product/period.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `supplier_id` | int | Yes | Loaded from `data/supplier_product_capacity.csv` |
-| `product_id` | int | Yes | Loaded from `data/supplier_product_capacity.csv` |
-| `period_id` | int | Yes | Loaded from `data/supplier_product_capacity.csv` |
-| `nominal_capacity_usd` | float | No | Capacity before capability/input scaling |
-
-**`Input`** — a raw material. `shortage_impact_cells` is a Stage-4 what-if output.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | int | Yes | Loaded from `data/inputs.csv` |
-| `name` | string | No | Helium / Neon / Palladium |
-| `description` | string | No | What the material is used for |
-| `shortage_impact_cells` | int | No | What-if output: cells affected by a shortage |
-
-**`InputUsage`** — how exposed each SKU is to each input.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `product_id` | int | Yes | Loaded from `data/input_usage.csv` |
-| `input_id` | int | Yes | Loaded from `data/input_usage.csv` |
-| `intensity` | float | No | Exposure fraction (0 = none, 1 = full) |
-
-**`Dependency`** — a directed customer-customer protection edge that Stage 1 turns into derived floors and the `Customer.depends_on` graph.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `downstream_id` | int | Yes | Customer that yields (loaded from `data/dependencies.csv`) |
-| `upstream_id` | int | Yes | Customer that is protected |
-| `declared_yield_pct` | float | No | Share the downstream customer will give up |
-| `elevated_floor_pct` | float | No | Floor the upstream customer is lifted to |
-
-### Relationships
-
-| Relationship | Schema | Notes |
-|---|---|---|
-| `Customer.depends_on(downstream, upstream)` | `Customer`, `Customer` | Materialized from `Dependency`; traversed in Stage 4 with the paths library |
-
-Stages 2–4 also create intermediate/output concepts — `SupplierCapabilityForecast` `(supplier_id, period_id) → capability_pct`, `EffectiveCapacity` `(iter_id, product_id, period_id) → effective_capacity_usd`, and `ScenarioOutcome` `(iter_id) → total_margin_usd` — all of which persist in the ontology for later querying.
+Alongside the base entities, Stage 1 rules-authors several derived `Customer` attributes (yield limits, elevated floors, single-point-of-failure flags), and Stages 2–4 create intermediate and output concepts — a supplier-capability forecast, per-iteration effective capacity, and per-scenario margin — that persist in the ontology for later querying. For the full concept and property definitions, see `memory_supply_allocation.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
diff --git a/v1/money_laundering_motif_detection/README.md b/v1/money_laundering_motif_detection/README.md
index c295fa99..92b0015d 100644
--- a/v1/money_laundering_motif_detection/README.md
+++ b/v1/money_laundering_motif_detection/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Money-Laundering Motif Detection"
-description: "Detect three classes of layering motif on the same transaction ledger, each demonstrating a different CSP technique that rules / paths / graph reasoning alone cannot enforce: per-vertex aggregate equality (butterfly), pairwise distinctness over a chosen subset (smurf army), and cardinality on a chosen subset (KYC-mix burst)."
+description: "Detect three classes of money-laundering layering motif on one transaction ledger using constraint-satisfaction (CSP) reasoning. Each motif enforces a joint condition across a solver-chosen subset of accounts and edges."
 featured: false
 experience_level: intermediate
 industry: "Financial Services"
@@ -14,21 +14,19 @@ tags:
   - financial-crime
 ---
 
-# Money-Laundering Motif Detection
-
 ## What this template is for
 
-Banking compliance and financial-crime teams hunt for "layering" -- the obfuscation phase of money laundering, where a launderer routes funds across a coordinated cohort of intermediary accounts so no single transaction triggers a [FinCEN currency-transaction-report](https://www.ecfr.gov/current/title-31/subtitle-B/chapter-X/part-1010/subpart-C/section-1010.311) (CTR) filing. The template ships **three motifs** -- each a different layering shape, each anchoring a distinct CSP technique class -- that share an ontology and run as three independent scripts:
+Banking compliance and financial-crime teams hunt for "layering" -- the obfuscation phase of money laundering, where a launderer routes funds across a coordinated cohort of intermediary accounts so no single transaction triggers a [FinCEN currency-transaction-report](https://www.ecfr.gov/current/title-31/subtitle-B/chapter-X/part-1010/subpart-C/section-1010.311) (CTR) filing. Launderers hide these schemes behind ordinary-looking transaction shapes, padding them with decoy edges and lookalike account clusters so the fraudulent cohort blends into the noise. What separates a real motif from its lookalikes is a condition that must hold jointly across the whole cohort the detector picks, not any single account or transaction on its own.
 
-| Motif | CSP technique class | Topology | Runner |
-|---|---|---|---|
-| **Butterfly** with per-hub flow conservation | Per-vertex equality of two aggregates over a decision-selected edge subset | Scatter-gather (one source -> K hubs -> one destination), per-hub conservation in dollar amount | `motif_butterfly.py` |
-| **Smurf army** with pairwise distinct beneficial owners | Pairwise constraints over decision-selected vertices + sum-equals-target | Fan-in (K sources -> one destination) with pairwise-distinct `bo_id`, sum-to-target, tight time window | `motif_smurf_army.py` |
-| **KYC-mix burst** with cardinality on a chosen subset | Cardinality constraint over a decision-selected vertex subset | Fan-in with KYC-tier floor (>= 4 retail) within a tight time window | `motif_kyc_burst.py` |
+**This template detects three classes of layering motif on one shared transaction ledger using constraint-satisfaction (CSP) reasoning, which enforces such joint conditions across a solver-chosen subset of accounts and edges.** The three motifs run as independent scripts over a shared ontology:
 
-The structural shape of a layering scheme -- fan-out, fan-in, scatter-gather -- is what graph-pattern matchers handle well, and it's exactly what launderers hide behind by adding decoy edges and lookalike clusters. The signal that *separates* a real motif from its lookalikes is **a constraint that has to hold jointly across whichever subset of accounts and edges the detector picks** -- arithmetic across the chosen edges, pairwise distinctness across the chosen accounts, or a count distribution over the chosen subset. None of those are expressible in a graph pattern or a path query: those see one edge or one walk at a time, never "this set of K elements, taken together, satisfies the joint condition." Each motif is grounded in a documented AML typology -- the eight-pattern taxonomy from [IBM AMLworld](https://arxiv.org/abs/2306.16424) (Altman et al., NeurIPS 2023) and the structuring / smurf-army typology from FATF and FinCEN (31 CFR § 1010.311).
+| Motif | Joint condition it enforces | Topology | Runner |
+|---|---|---|---|
+| **Butterfly** | Per-hub flow balance: each chosen hub's incoming dollars equal its outgoing dollars | Scatter-gather (one source -> K hubs -> one destination) | `motif_butterfly.py` |
+| **Smurf army** | Pairwise-distinct beneficial owners across the chosen cohort, plus a sum-to-target within a tight time window | Fan-in (K sources -> one destination) | `motif_smurf_army.py` |
+| **KYC-mix burst** | Cardinality: at least a floor number of the chosen accounts are retail-tier | Fan-in within a tight time window | `motif_kyc_burst.py` |
 
-The same patterns apply outside banking. Per-vertex aggregate equality detects collusion rings in marketplace fraud and recurring-billing abuse with fee splitting. Pairwise distinctness over a chosen subset detects ration-card sharing in welfare fraud and identity-cohort scams in subscription services. Cardinality distribution over a chosen subset detects compliance-mix violations in regulatory audits and KYC-cohort coordination in any structuring-style scheme.
+Each motif is grounded in a documented anti-money-laundering (AML) typology -- the eight-pattern taxonomy from [IBM AMLworld](https://arxiv.org/abs/2306.16424) (Altman et al., NeurIPS 2023) and the structuring / smurf-army typology from FATF and FinCEN (31 CFR § 1010.311). The same joint-condition patterns generalize beyond banking: per-hub flow balance surfaces collusion rings in marketplace fraud, pairwise distinctness surfaces identity-cohort scams in subscription services, and cardinality floors surface compliance-mix violations in regulatory audits.
 
 ## Who this is for
 
@@ -46,7 +44,7 @@ Shared ontology (in `model_setup.py`):
 - `Account` concept with `bo_id` (beneficial owner cluster), `kyc_tier`, and `jurisdiction` properties
 - `Transaction` concept with `src`, `dst`, `amount_dollars`, `ts_minutes`
 
-Each motif owns its own decisions and constraints. The bullets below summarise the load-bearing CSP integrity constraint per motif (the part that rules / paths / graph reasoning cannot enforce); the "How it works" section walks each one with code.
+Each motif owns its own decisions and constraints. The bullets below summarise the integrity constraints per motif, with the load-bearing joint condition in bold; the "How it works" section walks each one with code.
 
 - **Butterfly** (`motif_butterfly.py`):
   - Decisions: `Transaction.is_motif`, `Account.is_source` / `is_hub` / `is_dest`
@@ -80,6 +78,7 @@ Multi-solution enumeration via `problem.solve(..., solution_limit=K)` is availab
 - `motif_butterfly.py` -- per-hub flow conservation over a decision-selected edge subset.
 - `motif_smurf_army.py` -- pairwise distinct beneficial owners + sum-target + tight time window.
 - `motif_kyc_burst.py` -- cardinality on the chosen subset + tight time window.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/accounts.csv` -- 90 accounts across 69 beneficial-owner clusters, including two butterfly-cluster hubs (`bo_id=100`, `bo_id=200`), a five-account smurf cohort with pairwise-distinct BOs (`bo_id=1701..1705`), a five-account KYC-mix burst cohort (4 retail + 1 business across 4 jurisdictions), plus dup-BO / out-of-window / over-amount decoys for each motif and 30 unrelated noise accounts.
 - `data/transactions.csv` -- 138 directed transactions: 12 butterfly motif edges, 5 smurf motif edges, 5 KYC-burst motif edges, named decoys / cross-cluster traffic, and 60 noise transactions deterministically generated via `data/generate.py`.
 - `data/generate.py` -- the deterministic generator that produced the bundled CSVs. Re-run only if you change the planted-motif design or want to regenerate at a different size; the template ships its outputs so users don't need to run it.
@@ -200,69 +199,62 @@ Multi-solution enumeration via `problem.solve(..., solution_limit=K)` is availab
     └── generate.py            # deterministic generator (one-time, not runtime)
 ```
 
-## How it works
+**Start here**: run `python motif_butterfly.py` (or `motif_smurf_army.py` / `motif_kyc_burst.py`) for a motif detector end to end, or follow `runbook.md` to reproduce the template step by step with the RAI skills. Each runner is self-contained -- it imports the shared ontology from `model_setup.py`, loads the bundled data, and solves its own motif independently.
 
-The three motifs share an `Account` / `Transaction` ontology defined in `model_setup.py`. Each runner adds its own decision-valued properties, builds its own `Problem`, and constrains it with a different *class* of CSP technique. The "What you'll build" section above lists every constraint per motif; below is the load-bearing CSP IC for each, with the part that rules / paths / graph reasoning cannot express called out explicitly.
+## Sample data
 
-### Butterfly: per-vertex aggregate equality over a decision-selected edge subset
+The bundled CSVs are synthetic and tuned so each of the three motifs is visible against realistic decoys. `data/generate.py` produced them deterministically; it ships alongside its outputs, so you do not need to run it. For production-style validation against a public dataset, see [Test against real public data](#customize-this-template).
 
-For every account the solver picks as a hub, the dollar amount it receives via motif edges must equal what it forwards, within `CONSERVATION_TOLERANCE_DOLLARS`. The constraint is arithmetic over a *decision-selected subset* of edges -- it cannot be evaluated until the solver has chosen which transactions are in the motif and which accounts are hubs. Written in big-M form so the constraint is active when `is_hub == 1` and vacuous when `is_hub == 0`, with the M coefficient computed from the data:
+- **`data/accounts.csv`** (90 rows) -- accounts across 69 beneficial-owner clusters, including two butterfly-cluster hubs (`bo_id=100`, `bo_id=200`), a five-account smurf cohort with pairwise-distinct owners (`bo_id=1701..1705`), a five-account KYC-mix burst cohort (4 retail + 1 business across 4 jurisdictions), plus dup-owner / out-of-window / over-amount decoys for each motif and 30 unrelated noise accounts.
+- **`data/transactions.csv`** (138 rows) -- directed transactions: 12 butterfly motif edges, 5 smurf motif edges, 5 KYC-burst motif edges, named decoys, cross-cluster traffic, and 60 noise transactions.
 
-```python
-T_out = Transaction.ref()
-conservation_pos_ic = model.where(Transaction.dst == Account, T_out.src == Account).require(
-    sum(Transaction.amount_dollars * Transaction.is_motif).per(Transaction.dst)
-    - sum(T_out.amount_dollars * T_out.is_motif).per(T_out.src)
-    + CONSERVATION_BIG_M * Account.is_hub
-    <= CONSERVATION_TOLERANCE_DOLLARS + CONSERVATION_BIG_M
-)
-```
+## Model overview
 
-A path enumeration sees one walk at a time and never the joint condition; a rules-only encoding can sum-per-vertex but cannot bind that sum to "the chosen subset of edges, where the chosen accounts are hubs."
+All three runners share one ontology, defined in `model_setup.py`: `Account` vertices and `Transaction` directed edges. Each runner adds its own decision-valued properties (which account or transaction is part of the motif) on top of these base concepts at solve time.
 
-> We use big-M rather than a half-reified `implies(Account.is_hub == 1, ...)` for this constraint. Half-reification introduces a free Boolean auxiliary per non-hub account that MiniZinc treats as part of the search space, returning thousands of trivially-distinct solutions for the same role/motif assignment. Big-M with a data-computed bound has no auxiliary, so enumeration stays clean and the solver exhausts after the data's actual motifs.
+- **Key entities**: `Account` (a bank account) and `Transaction` (a directed transfer between two accounts).
+- **Primary identifiers**: integer `id` on `Account`; integer `tx_id` on `Transaction`.
+- **Important invariants**: `Transaction.src` and `Transaction.dst` reference existing accounts; `amount_dollars` is positive; layering edges sit under the `AMOUNT_THRESHOLD_DOLLARS` CTR line (default `$10,000`); `ts_minutes` is non-negative.
 
-### Smurf army: pairwise constraints over a decision-selected vertex subset
+`Account` carries `name`, `bo_id` (beneficial-owner cluster), `kyc_tier`, and `jurisdiction`; `Transaction` carries `src`, `dst`, `amount_dollars`, and `ts_minutes`. Each runner then adds its own motif-specific decision properties on top -- e.g. `Account.is_hub` / `is_smurf` / `is_burst` and `Transaction.is_motif` / `is_smurf_tx` / `is_burst_tx` -- populated by the solver. For the full concept and property definitions, see `model_setup.py`; `runbook.md` builds them step by step with the RAI skills.
 
-Among the N chosen smurfs, no two may share a beneficial owner. The constraint is over the *selected* subset, not an edge filter: an account is allowed to exist in the same `bo_id` cluster as another, but cannot be a smurf *in the same cohort*. A second `Account.ref()` handle plus the bare `Account` lets the constraint range over ordered pairs, with `Account.id < S2.id` to avoid double-counting:
+## How it works
 
-```python
-S2 = Account.ref()
-distinct_bo_ic = model.where(Account.id < S2.id, Account.bo_id == S2.bo_id).require(
-    Account.is_smurf + S2.is_smurf <= 1
-)
-```
+The three motifs share an `Account` / `Transaction` ontology defined in `model_setup.py`. Each runner adds its own decision-valued properties, builds its own `Problem`, and constrains it with a different *class* of CSP technique. The "What you'll build" section above lists every constraint per motif; below is the load-bearing joint condition for each, with the part that rules / paths / graph reasoning cannot express called out explicitly.
 
-Pre-filtered pair tables can't bind to "the K-subset the solver itself picks." Combined with sum-equals-target on the chosen smurf-tx amounts and a tight pairwise time window, this motif's CSP shape is two joint conditions on the same chosen subset: the *sum* must hit a known launder target while the *pairwise distinctness* holds on the same chosen set.
+**Butterfly: per-vertex aggregate equality over a decision-selected edge subset.** For every account the solver picks as a hub, the dollars it receives via motif edges must equal what it forwards, within `CONSERVATION_TOLERANCE_DOLLARS`. The constraint is arithmetic over a *decision-selected subset* of edges -- it cannot be evaluated until the solver has chosen which transactions are in the motif and which accounts are hubs. It is written in big-M form so it is active when an account is a hub and vacuous otherwise, with the M coefficient computed from the data. (Big-M rather than half-reification: a half-reified `implies` introduces a free Boolean auxiliary per non-hub account that the solver treats as search space, returning thousands of trivially-distinct solutions; big-M with a data-computed bound has no auxiliary, so enumeration stays clean and the solver exhausts after the data's actual motifs.) A path enumeration sees one walk at a time and never the joint condition; a rules-only encoding can sum-per-vertex but cannot bind that sum to "the chosen subset of edges, where the chosen accounts are hubs."
 
-### KYC-mix burst: cardinality over a decision-selected vertex subset
+**Smurf army: pairwise constraints over a decision-selected vertex subset.** Among the N chosen smurfs, no two may share a beneficial owner. The constraint is over the *selected* subset, not an edge filter: an account may exist in the same `bo_id` cluster as another, but cannot be a smurf *in the same cohort*. A second account handle lets the constraint range over ordered pairs without double-counting. Pre-filtered pair tables can't bind to "the K-subset the solver itself picks." Combined with sum-equals-target on the chosen smurf-tx amounts and a tight pairwise time window, this motif's CSP shape is two joint conditions on the same chosen subset: the *sum* must hit a known launder target while the *pairwise distinctness* holds on the same chosen set.
 
-Among the N chosen burst accounts, at least `RETAIL_FLOOR` must be retail-tier. Rules can label each account's tier; only CSP enforces the count *over the selected subset*:
+**KYC-mix burst: cardinality over a decision-selected vertex subset.** Among the N chosen burst accounts, at least `RETAIL_FLOOR` must be retail-tier. Rules can label each account's tier; only CSP enforces the count *over the selected subset*. The launder-grade burst signature is "K accounts with a retail-tier floor transacting together in a tight window." A graph-pattern matcher can find the time-window cluster but has no way to express "and at least M of the chosen K are retail-tier."
 
-```python
-retail_floor_ic = model.require(
-    sum(Account.is_burst).where(Account.kyc_tier == "retail") >= RETAIL_FLOOR
-)
-```
+**Solver call and enumeration.** Every runner calls the MiniZinc solver with a `solution_limit`. The variable subconcept returned by `solve_for(...)` exposes a per-solution values relationship; filtering on the chosen rows surfaces what the solver picked, since the populated property reflects only the first solution. These are pure satisfaction problems with no objective, so `status: OPTIMAL` means the solver enumerated all feasible motifs up to `solution_limit` -- not an optimisation verdict -- while `SOLUTION_LIMIT` means the limit was hit before enumeration exhausted (raise `MAX_*_MOTIFS` to surface more).
 
-The launder-grade burst signature is "K accounts with a retail-tier floor transacting together in a tight window." A graph-pattern matcher can find the time-window cluster but has no way to express "and at least M of the chosen K are retail-tier."
+See `model_setup.py` and the three motif runners for the implementation, and `runbook.md` for the skill-driven reproduction.
 
-### Solver call and enumeration
+## Customize this template
 
-Every runner calls `problem.solve("minizinc", time_limit_sec=60, solution_limit=...)`. The variable subconcept returned by `solve_for(...)` exposes a `.values(solution_index, value)` relationship that indexes per-solution outputs; filtering on `value == 1` surfaces the rows the solver picked. The populated property reflects only the first solution, so for multi-solution output the inspect blocks always go through `.values(...)`.
+### Use your own data
 
-These are pure satisfaction problems with no objective, so `status: OPTIMAL` in the `solve_info().display()` output means the solver enumerated all feasible motifs up to `solution_limit`. It is not an optimisation verdict. `SOLUTION_LIMIT` means the limit was hit before enumeration exhausted -- raise `MAX_*_MOTIFS` to surface more.
+- Replace the two CSV files with your own accounts and transactions; every runner picks them up automatically. The shared ontology in `model_setup.py` reads columns by name (`id`, `name`, `bo_id`, `kyc_tier`, `jurisdiction`, `tx_id`, `src_id`, `dst_id`, `amount_dollars`, `ts_minutes`). Drop a column you don't have by deleting the corresponding `Account.<name> = model.Property(...)` line and any constraint that references it.
+- Point the smurf and burst runners at a different target merchant by editing `SMURF_TARGET_DESTINATION_ID` in `motif_smurf_army.py` and `BURST_TARGET_DESTINATION_ID` in `motif_kyc_burst.py`. On a real ledger you would set these from your watchlist of known-launder destinations.
 
-## Customize this template
+**Test against real public data.** The bundled CSVs are synthetic and tuned to make the three motifs visible. For production-style validation, point the runners at a slice of [IBM AMLworld HI-Small / LI-Small](https://github.com/IBM/AML-Data) (CDLA-Sharing-1.0; the dataset paper is Altman et al., NeurIPS 2023). AMLworld natively labels the eight-pattern taxonomy used in the butterfly motif (scatter-gather), and a 500-2000 transaction slice will solve in seconds. KYC tiers and jurisdictions are not in AMLworld natively; the smurf-army and KYC-burst runners would need either synthetic augmentation columns or a different vertex category mapped from AMLworld's `Bank` / `Payment Format` columns.
+
+### Tune parameters
 
-- **Use your own data** by replacing the two CSV files with your accounts and transactions; every runner picks them up automatically. The shared ontology in `model_setup.py` reads columns by name (`id`, `name`, `bo_id`, `kyc_tier`, `jurisdiction`, `tx_id`, `src_id`, `dst_id`, `amount_dollars`, `ts_minutes`). Drop a column you don't have by deleting the corresponding `Account.<name> = model.Property(...)` line and any constraint that references it.
-- **Test against real public data.** The bundled CSVs are synthetic and tuned to make the three motifs visible. For production-style validation, point the runners at a slice of [IBM AMLworld HI-Small / LI-Small](https://github.com/IBM/AML-Data) (CDLA-Sharing-1.0; the dataset paper is Altman et al., NeurIPS 2023). AMLworld natively labels the eight-pattern taxonomy used in the butterfly motif (scatter-gather), and a ~500-2000 transaction slice will solve in seconds. KYC tiers and jurisdictions are not in AMLworld natively; the smurf-army and KYC-burst runners would need either synthetic augmentation columns or a different vertex category mapped from AMLworld's `Bank` / `Payment Format` columns.
-- **Raise the solution limit on a real ledger.** Each runner's `MAX_*_MOTIFS` is sized for the demo. On a production ledger with thousands of accounts you may want 100+ so the analyst inbox surfaces the full population of candidates. The `time_limit_sec` argument to `problem.solve` is your safety net.
-- **Point the smurf and burst runners at a different target merchant** by editing `SMURF_TARGET_DESTINATION_ID` in `motif_smurf_army.py` and `BURST_TARGET_DESTINATION_ID` in `motif_kyc_burst.py`. On a real ledger you would set these from your watchlist of known-launder destinations.
-- **Tune the thresholds** by editing the per-runner constants. The FinCEN CTR threshold (`AMOUNT_THRESHOLD_DOLLARS = 10_000`) lives in `model_setup.py`. Per-hub conservation tolerance, smurf target dollars, smurf window, burst window, and retail floor are at the top of each motif's runner.
-- **Add a temporal-ordering IC to the butterfly** (so hubs must receive before they forward) by declaring two `Transaction.ref()` handles and a pairwise time constraint on hub-incoming vs hub-outgoing motif edges. Useful when your scheme runs on a known cadence.
-- **Sweep the smurf target** by parameterizing `SMURF_TARGET_DOLLARS` and re-running; alternatively, replace the equality with a *minimum* cumulative deposit constraint (`>= SMURF_TARGET_DOLLARS - tol`) if your watchlist tracks "at least $X laundered through this merchant" rather than a known exact total.
-- **Add a jurisdiction-diversity floor to the KYC-mix burst** with a per-jurisdiction sum + a global count: declare an auxiliary `Account.is_burst_in_<j>` per jurisdiction `j` reified as `is_burst * (jurisdiction == j)`, then constrain the count of jurisdictions with at least one chosen account to be `>= 3`. The bundled data already plants four distinct jurisdictions in the burst cohort; this would make that distribution a hard constraint.
+- Edit the per-runner constants to tune the thresholds. The FinCEN CTR threshold (`AMOUNT_THRESHOLD_DOLLARS = 10_000`) lives in `model_setup.py`. Per-hub conservation tolerance, smurf target dollars, smurf window, burst window, and retail floor are at the top of each motif's runner.
+- Sweep the smurf target by parameterizing `SMURF_TARGET_DOLLARS` and re-running; alternatively, replace the equality with a minimum cumulative deposit constraint (`>= SMURF_TARGET_DOLLARS - tol`) if your watchlist tracks "at least $X laundered through this merchant" rather than a known exact total.
+
+### Extend the model
+
+- Add a temporal-ordering integrity constraint to the butterfly (so hubs must receive before they forward) by declaring two `Transaction.ref()` handles and a pairwise time constraint on hub-incoming vs hub-outgoing motif edges. Useful when your scheme runs on a known cadence.
+- Add a jurisdiction-diversity floor to the KYC-mix burst with a per-jurisdiction sum plus a global count: declare an auxiliary `Account.is_burst_in_<j>` per jurisdiction `j` reified as `is_burst * (jurisdiction == j)`, then constrain the count of jurisdictions with at least one chosen account to be at least 3. The bundled data already plants four distinct jurisdictions in the burst cohort; this would make that distribution a hard constraint.
+
+### Scale up / productionize
+
+- Raise the solution limit on a real ledger. Each runner's `MAX_*_MOTIFS` is sized for the demo. On a production ledger with thousands of accounts you may want 100+ so the analyst inbox surfaces the full population of candidates. The `time_limit_sec` argument to `problem.solve` is your safety net.
+- Pin `relationalai` to a known-good version for reproducible runs, and schedule the runners after each ledger refresh so candidate cases stay current for analyst triage.
 
 ## References
 
@@ -320,3 +312,17 @@ These are pure satisfaction problems with no objective, so `status: OPTIMAL` in
 - HiGHS is not appropriate here -- this is a discrete satisfaction model with categorical decisions and structural propagation, not LP/MILP.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) -- `model.where(...)`, `.require(...)`, aggregates, and `.ref()` handles for ranging over pairs and subsets.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) -- the `Problem` API, decision variables, integrity constraints, and multi-solution enumeration with `solution_limit`, as all three motif runners use.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/network_flow_planning/README.md b/v1/network_flow_planning/README.md
index 5ecdb722..2ac24448 100644
--- a/v1/network_flow_planning/README.md
+++ b/v1/network_flow_planning/README.md
@@ -14,8 +14,6 @@ tags:
   - Cost Minimization
 ---
 
-# Network Flow Planning
-
 ## What this template is for
 
 This template uses **Prescriptive** reasoning to solve a multi-tier supply-chain network design problem in a single MILP. Distribution networks usually decide two things at once:
@@ -52,6 +50,7 @@ The objective minimizes transport cost plus fixed-cost FC opening cost.
 ## What's included
 
 - `network_flow_planning.py` — main script (single end-to-end run)
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/sites.csv` — 12 sites: 3 warehouses, 3 transit hubs, 3 fulfillment centers, 3 customers
 - `data/lanes.csv` — 17 directed lanes connecting the tiers, each with a cost-per-unit and capacity
 - `data/demand.csv` — 3 customer demands (NYC 180, LA 120, Houston 150)
@@ -145,7 +144,7 @@ The objective minimizes transport cost plus fixed-cost FC opening cost.
     └── demand.csv                  # 3 customer demands
 ```
 
-**Start here:** `python network_flow_planning.py`.
+**Start here:** run `python network_flow_planning.py` for the full run end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Sample data
 
@@ -163,136 +162,30 @@ Lane costs are set so that opening FC_West would unlock the cheapest LA route (`
 
 ## Model overview
 
-### Site
-
-A node in the distribution network. The `type` property distinguishes the role each site plays.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | Integer | Yes | Loaded from `data/sites.csv` |
-| `name` | String | No | Human-readable name |
-| `type` | String | No | One of `WAREHOUSE`, `HUB`, `FULFILLMENT_CENTER`, `CUSTOMER` |
-| `inventory` | Float | No | Available supply (warehouses only; 0 elsewhere) |
-| `capacity` | Float | No | Throughput cap (FCs only; 0 elsewhere) |
-| `fixed_cost` | Float | No | Fixed cost when opened (FCs only; 0 elsewhere) |
-
-### Lane
-
-A directed transport link between two sites with a per-unit cost and a flow capacity.
+The model uses three concepts. A single `Site` concept carries all four network tiers, distinguished by a `type` property, so warehouses, hubs, fulfillment centers, and customers share one entity and each contributes the constraint that matches its role.
 
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | Integer | Yes | Loaded from `data/lanes.csv` |
-| `source` | Site | No | Origin site (Relationship) |
-| `dest` | Site | No | Destination site (Relationship) |
-| `cost_per_unit` | Float | No | Transport cost per unit of flow |
-| `capacity` | Float | No | Maximum flow on this lane |
+- **Key entities**: `Site` — a node in the distribution network, its `type` distinguishing the role each plays (warehouse, hub, fulfillment center, customer); `Lane` — a directed transport link between two sites with a per-unit cost and a flow capacity; `Demand` — a customer order placed at a particular site.
+- **Primary identifiers**: integer `id` on each of `Site`, `Lane`, and `Demand`, loaded from the corresponding CSV.
+- **Important invariants**: `inventory`, `capacity`, `fixed_cost`, `cost_per_unit`, and `quantity` are non-negative; only fulfillment centers carry a positive `fixed_cost` (that is what scopes the binary open decision); every `Lane.source` / `Lane.dest` and every `Demand.site` resolves to a real `Site`.
 
-### Demand
-
-A customer order placed at a particular site.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | Integer | Yes | Loaded from `data/demand.csv` |
-| `site` | Site | No | Customer site (Relationship) |
-| `quantity` | Float | No | Units required |
-| `customer` | String | No | Order identifier (free text) |
-| `priority` | Integer | No | Priority tier (not used by the model in this version) |
+For the full concept and property definitions, see `network_flow_planning.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
-### 1. Decision variables
-
-Two variables drive the model:
-
-```python
-Lane.x_flow = model.Property(f"{Lane} carries {Float:flow}")
-Site.x_open = model.Property(f"{Site} is open {Float:open}")
-
-problem.solve_for(
-    Lane.x_flow,
-    lower=0,
-    upper=Lane.capacity,
-    name=["flow", Lane.id],
-)
-
-problem.solve_for(
-    Site.x_open,
-    type="bin",
-    name=["open", Site.name],
-    where=[Site.fixed_cost > 0],
-)
-```
-
-The `where=[Site.fixed_cost > 0]` clause restricts the binary `x_open` to fulfillment centers only — warehouses, hubs, and customers don't get open-decision variables.
-
-### 2. Constraints
-
-Each site type contributes the constraint that matches its role.
-
-**Source supply** at warehouses:
-
-```python
-out_lane = Lane.ref()
-problem.satisfy(model.where(
-    Site.inventory > 0,
-).require(
-    sum(out_lane.x_flow).where(out_lane.source == Site).per(Site) <= Site.inventory
-))
-```
-
-**Flow conservation** at hubs and fulfillment centers (one per type):
-
-```python
-in_lane = Lane.ref()
-out_lane = Lane.ref()
-problem.satisfy(model.where(
-    Site.type == "HUB",
-).require(
-    sum(in_lane.x_flow).where(in_lane.dest == Site).per(Site)
-    == sum(out_lane.x_flow).where(out_lane.source == Site).per(Site)
-))
-```
+The model runs as a single MILP that decides flow on every lane and which fulfillment centers to open, in one solve.
 
-**FC capacity gated by open decision**:
+**Decision variables.** Each lane carries a continuous `x_flow` bounded by its capacity. Each fulfillment center carries a binary `x_open`; the open decision is scoped to sites with a positive `fixed_cost`, so warehouses, hubs, and customers never get an open variable.
 
-```python
-in_lane = Lane.ref()
-problem.satisfy(model.where(
-    Site.fixed_cost > 0,
-).require(
-    sum(in_lane.x_flow).where(in_lane.dest == Site).per(Site)
-    <= Site.capacity * Site.x_open
-))
-```
-
-**Demand satisfaction** at customers:
-
-```python
-in_lane = Lane.ref()
-demand_ref = Demand.ref()
-problem.satisfy(model.where(
-    Site.type == "CUSTOMER",
-).require(
-    sum(in_lane.x_flow).where(in_lane.dest == Site).per(Site)
-    >= sum(demand_ref.quantity).where(demand_ref.site == Site).per(Site)
-))
-```
+**Constraints.** Each site type contributes the constraint that matches its role. Warehouses cap total outflow at their inventory. Transit hubs and fulfillment centers conserve flow — inflow equals outflow. A fulfillment center's inflow is bounded by `capacity × x_open`, so an unopened FC (open = 0) can carry no flow and the fixed cost is only incurred when it is opened. Customers require inflow to meet their aggregate demand.
 
-### 3. Objective
+**Objective.** Minimize transport cost (per-unit lane cost times flow, summed over lanes) plus the fixed cost of every opened fulfillment center. The two cost terms live on different concepts (`Lane` and `Site`), so they are combined into one per-entity sum that the objective minimizes.
 
-The combined objective uses `model.union` so PyRel can sum two per-entity expressions of different concepts in one minimize call:
+For the exact PyRel formulation, see `network_flow_planning.py`; `runbook.md` reproduces the model step by step with the RAI skills.
 
-```python
-problem.minimize(sum(model.union(
-    Lane.cost_per_unit * Lane.x_flow,
-    Site.fixed_cost * Site.x_open,
-)))
+```text
+CSV inputs → load Site / Lane / Demand → flow + open decisions → role-based constraints → minimize transport + fixed cost → solve → export
 ```
 
-Each branch is a per-entity expression (per `Lane` and per `Site`), aggregated by the outer `sum`.
-
 ## Customize this template
 
 ### Use your own data
@@ -315,6 +208,13 @@ Replace the three CSVs in `data/` with your own:
 - **Service-level constraints.** Replace the hard demand-satisfaction constraint with a soft one and a slack variable, and add a service-level threshold.
 - **Multi-period planning.** Index `Lane.x_flow` by a time period concept and add inventory carry-over constraints between periods.
 
+### Scale up / productionize
+
+- For a live network, replace the three `data/` CSVs with `model.data(snowflake_table)` calls so the model reads sites, lanes, and demand directly from your warehouse tables.
+- The bundled data is 12 sites and 17 lanes; the MILP scales to whatever fits the prescriptive engine's solve budget. If solves grow slow, tighten lane capacities to prune the flow space or size up the engine.
+- The template solves with HiGHS by default (`problem.solve("highs")`); swap to `"gurobi"` for larger integer programs if a Gurobi-enabled engine is available.
+- Pin `relationalai` (see Prerequisites) so runs stay reproducible across environments.
+
 ## Troubleshooting
 
 <details>
@@ -341,6 +241,26 @@ Replace the three CSVs in `data/` with your own:
   PyRel disallows `+` between aggregated terms of different concepts. `model.union` lets the outer `sum` aggregate per-Lane and per-Site cost terms in a single objective. Each branch must be a per-entity expression, not a fully-aggregated scalar.
 </details>
 
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)`, `sum(...).per(...)`, and `model.union` for multi-concept objectives.
+- [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API: decision variables (`solve_for`), constraints (`satisfy`), and objectives (`minimize` / `maximize`).
+
+### Language / modeling reference
+
+- [Concepts and properties](https://docs.relational.ai/) — modeling multiple roles on one concept via a typed property, as `Site.type` does here.
+- [Relationships](https://docs.relational.ai/) — directed links like `Lane.source` / `Lane.dest` and `Demand.site`.
+
+### Deeper dives
+
+- [Solver selection and diagnostics](https://docs.relational.ai/) — choosing HiGHS vs. Gurobi, reading termination status, and diagnosing infeasibility.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
+
 ## Related templates
 
 - [`factory_production`](../factory_production/) — simpler single-site LP (no facility-open decision)
diff --git a/v1/patient_cohort_recruitment/README.md b/v1/patient_cohort_recruitment/README.md
index b587d21c..9eda2246 100644
--- a/v1/patient_cohort_recruitment/README.md
+++ b/v1/patient_cohort_recruitment/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Patient Cohort Recruitment"
-description: "Build a clinical-research cohort over a patient knowledge graph: close a kinase-pathway sub-ontology, lift the closure to per-patient eligibility and coverage facts, then pick K patients whose joint coverage spans enough distinct genes, therapies, and adverse events to generalize."
+description: "Build a clinical-research cohort over a patient knowledge graph. It selects a small set of eligible patients that together span enough distinct genes, therapies, and adverse events for a study to generalize."
 featured: false
 experience_level: intermediate
 industry: "Healthcare & Life Sciences"
@@ -16,17 +16,13 @@ tags:
   - clinical-research
 ---
 
-# Patient Cohort Recruitment
-
 ## What this template is for
 
-Clinical research and pharma R&D teams build patient cohorts to power studies. A typical ask: *"find patients with a mutation in some gene from the kinase pathway who received a therapy and developed an adverse event within 90 days, and pick K of them so the cohort spans enough distinct genes, therapies, and toxicity profiles for the analysis to generalize."*
-
-The pieces are recognizable across healthcare data. A gene ontology with `is_a` edges defines the pathway. A patient knowledge graph carries mutations / therapies / adverse events with timestamps. The cohort itself is a small set of patients chosen against multiple coverage criteria.
+Clinical research and pharma R&D teams build patient cohorts to power studies. A typical ask: find patients who carry a mutation in a gene from a target pathway, received a therapy, and then developed an adverse event within a set window, and pick a handful of them so the cohort spans enough distinct genes, therapies, and toxicity profiles for the later analysis to generalize. Getting this right by hand is slow and error-prone, because eligibility depends on tracing an ontology and the cohort must be balanced across several dimensions at once.
 
-This template encodes that ask as a three-reasoner pipeline. The **Graph** reasoner runs a single `reachable(full=True)` call to close `is_a` over the gene ontology, returning every gene in the kinase-pathway sub-ontology in one step. Pure relational **Rules** then lift the closure to per-patient eligibility -- represented as a sub-concept `EligiblePatient extends Patient` whose membership is the eligibility conjunction -- and to per-(patient, gene), per-(patient, therapy), and per-(patient, adverse-event) coverage facts. The **Prescriptive** reasoner (CSP, MiniZinc / Chuffed) selects the cohort: binary `is_in_cohort` decisions are scoped to `EligiblePatient` rows only, plus `is_covered` indicators on three sub-concepts (`CoverableGene`, `CoverableTherapy`, `CoverableAdverseEvent`) that the upper-bound ICs link back to the patient decisions.
+The same shape recurs across knowledge-graph cohort and set-cover problems where eligibility is a rule over a labelled subgraph and the chosen set must span a minimum spread on several attributes: insurance claim audits (members spanning procedures and comorbidities), grant-applicant diversification (applicants spanning institutions, fields, and career stages), or security-alert triage (alerts spanning attack categories and asset classes).
 
-The same pattern applies to other knowledge-graph cohort / set-cover problems where eligibility is a relational predicate over a labelled subgraph and the chosen set must witness a minimum spread on several attributes: insurance claim audits (find K members spanning N procedures and M comorbidities), grant-applicant diversification (find K applicants spanning institutions, fields, and career stages), security alert triage (find K alerts spanning attack categories and asset classes).
+**The template chains three RelationalAI reasoners on one ontology: the graph reasoner closes the gene pathway, relational rules derive per-patient eligibility and coverage, and the prescriptive reasoner selects a cohort that meets every coverage floor.**
 
 ## Who this is for
 
@@ -51,6 +47,7 @@ The same pattern applies to other knowledge-graph cohort / set-cover problems wh
 The bundled CSVs are illustrative, fully synthetic demo data (e.g. patient names `P_Alpha`...`P_Oscar`, fictional gene/therapy/AE labels) sized so the pipeline runs end-to-end in a few seconds; swap in your own ontology and patient KG to apply the template to real cohorts.
 
 - `patient_cohort_recruitment.py` -- main script with concepts, the Graph closure, the rules, the decisions and constraints, and the solver call
+- **Runbook**: `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/genes.csv` -- 10 sample genes: 7 in the kinase pathway sub-ontology (a root plus two intermediate sub-roots and four leaves) and 3 unrelated metabolism genes
 - `data/gene_is_a.csv` -- 8 `is_a` edges that lay out the kinase-pathway tree and a parallel unrelated tree
 - `data/patients.csv` -- 15 synthetic patients with names and ages
@@ -69,6 +66,7 @@ The bundled CSVs are illustrative, fully synthetic demo data (e.g. patient names
 
 ### Tools
 - Python >= 3.10
+- RelationalAI Python SDK (`relationalai == 1.1.0`)
 
 ## Quickstart
 
@@ -103,7 +101,8 @@ The bundled CSVs are illustrative, fully synthetic demo data (e.g. patient names
    python patient_cohort_recruitment.py
    ```
 
-6. Expected output (the bundled data has eight eligible patients and several feasible cohorts that hit the coverage floors -- the exact choice may vary across solver versions):
+6. Expected output — a few lines confirm a successful run (the script also prints the gene closure, the eligible-patient set, and the per-axis coverage tally):
+
    ```text
    Solve result:
    • status: OPTIMAL
@@ -112,55 +111,15 @@ The bundled CSVs are illustrative, fully synthetic demo data (e.g. patient names
    • num_points: 1
    • solver: MiniZinc_unknown
 
-   Kinase-pathway gene closure (reachable from KINASE_ROOT_GENE_ID):
-     gene_id              gene_name
-           1      KinasePathwayRoot
-           2  SerineThreonineKinase
-           3         TyrosineKinase
-           4                   EGFR
-           5                   HER2
-           6                   BRAF
-           7                   MEK1
-
-   Eligible patients (carry a kinase mutation and have a qualifying pair):
-      patient_id patient_name
-               1      P_Alpha
-               2      P_Bravo
-               3    P_Charlie
-               4      P_Delta
-               5       P_Echo
-               7       P_Golf
-               8      P_Hotel
-               9      P_India
-
    Selected cohort:
      patient_id patient_name age_years
               2      P_Bravo        61
               7       P_Golf        63
               8      P_Hotel        49
               9      P_India        57
-
-   Kinase-pathway genes covered by the cohort:
-     gene_id gene_name
-           4      EGFR
-           5      HER2
-           6      BRAF
-           7      MEK1
-
-   Therapies covered by the cohort:
-     therapy_id    therapy_name
-              1  EGFR_Inhibitor
-              2  HER2_Inhibitor
-              3   MEK_Inhibitor
-
-   Adverse events covered by the cohort:
-     ae_id         ae_term
-         1            Rash
-         2  Hepatotoxicity
-         3  Cardiomyopathy
    ```
 
-   Eight of the 15 patients are eligible (the seven excluded patients each fail either the kinase-mutation test or the qualifying-pair test within the 90-day window). The kinase-pathway closure transitively covers the root, the two sub-roots, and all four leaves. Several four-patient cohorts hit the `MIN_GENES_COVERED = 3` / `MIN_THERAPIES_COVERED = 2` / `MIN_AES_COVERED = 2` floors; the solver returns one of them (the specific cohort can vary across runs). `Statin` and `GLP1_Agonist` (therapies 4 and 5) and `Myalgia` (AE 4) appear in the data but are unreachable for any cohort because no eligible patient has a qualifying-pair on them -- the `Coverable*` sub-concepts correctly exclude them from the count.
+   Eight of the 15 patients are eligible (the seven excluded patients each fail either the kinase-mutation test or the qualifying-pair test within the 90-day window). Several four-patient cohorts hit the `MIN_GENES_COVERED = 3` / `MIN_THERAPIES_COVERED = 2` / `MIN_AES_COVERED = 2` floors; the solver returns one of them, so the specific cohort can vary across runs.
 
 ## Template structure
 ```text
@@ -179,117 +138,78 @@ The bundled CSVs are illustrative, fully synthetic demo data (e.g. patient names
     └── ae_terms.csv
 ```
 
+**Start here**: run `python patient_cohort_recruitment.py` for the full three-stage pipeline (graph closure, rules, then the cohort-selection solve) end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
+
+## Sample data
+
+The bundled CSVs are illustrative, fully synthetic demo data (patient names `P_Alpha`...`P_Oscar`, fictional gene / therapy / adverse-event labels) sized so the pipeline runs end-to-end in a few seconds. The shape mirrors an OMOP / FHIR-class patient store: a gene ontology with `is_a` edges, plus event tables (mutations, therapies, adverse events) that reference patients and dictionary concepts by foreign key.
+
+- **`genes.csv`** (10 rows) — 7 genes in the kinase-pathway sub-ontology (a root, two intermediate sub-roots, four leaves) and 3 unrelated metabolism genes.
+- **`gene_is_a.csv`** (8 rows) — `is_a` edges (child, parent) laying out the kinase-pathway tree and a parallel unrelated tree.
+- **`patients.csv`** (15 rows) — synthetic patients with names and ages.
+- **`mutation_events.csv`** (26 rows) — mutation events spanning kinase and non-kinase genes; some patients carry only non-kinase mutations and are correctly excluded.
+- **`therapy_events.csv`** (15 rows) — therapy events across 5 therapies.
+- **`adverse_events.csv`** (12 rows) — adverse-event occurrences across 4 AE terms; some fall outside the 90-day window from any therapy and are excluded by the qualifying-pair rule.
+- **`therapies.csv`** (5 rows) — therapy concepts (3 kinase inhibitors, 2 unrelated).
+- **`ae_terms.csv`** (4 rows) — adverse-event terms.
+
+Event timestamps are integer `t_days` (days since the patient's index date); a pre-solve pass validates unique keys, foreign-key integrity, the presence of the pathway root, and non-negative timestamps before the rules install.
+
+## Model overview
+
+One ontology threads all three stages: the graph closure writes a `KinaseGene` sub-concept, the rules derive eligibility and coverage sub-concepts, and the CSP scopes its decisions to those sub-concepts.
+
+- **Key entities**: base concepts — `Gene` (an ontology node), `GeneIsA` (a gene-ontology `is_a` edge, stored child-to-parent), `Therapy` and `AdverseEvent` (small dictionary concepts), `Patient` (a patient), and the event tables `MutationEvent`, `TherapyEvent`, `AdverseEventOcc` (a mutation, therapy, or adverse-event observed in a patient at a point in time); derived sub-concepts — `KinaseGene` (genes reachable from the pathway root, from the graph closure), `KinaseMutationCarrier` and `QualifyingPairPatient` (the two eligibility halves), `EligiblePatient` (their conjunction, and the target of the `is_in_cohort` decision), and `CoverableGene`, `CoverableTherapy`, `CoverableAdverseEvent` (values coverable by an eligible patient, each the target of an `is_covered` decision).
+- **Primary identifiers**: integer `id` on each base concept, loaded from the corresponding CSV; `GeneIsA` is keyed by the composite `(child_id, parent_id)`.
+- **Important invariants**: every foreign key resolves (event tables reference real patients and dictionary concepts); event `t_days` values are non-negative; the pathway root gene exists; a sub-concept's membership *is* its predicate (a patient is eligible exactly when they are a `KinaseMutationCarrier` and a `QualifyingPairPatient`).
+
+For the full concept and property definitions, see `patient_cohort_recruitment.py`; `runbook.md` builds them step by step with the RAI skills.
+
 ## How it works
 
 The pipeline runs three stages in order: Graph closes the ontology, Rules lift the closure to patient-level facts, and the CSP solver selects the cohort.
 
-**Graph reasoner: one call to close the ontology.** The `is_a` CSV is in OMOP / SNOMED convention (child -> parent), but the `Graph` constructor takes the same edge concept with `edge_src_relationship=GeneIsA.parent` and `edge_dst_relationship=GeneIsA.child` -- so reachability from a root flows downwards through the subclass tree onto every member. `reachable(full=True)` returns every (ancestor, descendant) pair, the full transitive closure. The closure is then materialized as a sub-concept `KinaseGene extends Gene`:
-
-```python
-gene_reachable = Graph(
-    model, directed=True, weighted=False, node_concept=Gene,
-    edge_concept=GeneIsA,
-    edge_src_relationship=GeneIsA.parent,
-    edge_dst_relationship=GeneIsA.child,
-).reachable(full=True)
-
-KinaseGene = model.Concept("KinaseGene", extends=[Gene])
-KinaseRootGene = Gene.ref()
-model.define(KinaseGene(Gene)).where(
-    KinaseRootGene.id == KINASE_ROOT_GENE_ID,
-    gene_reachable(KinaseRootGene, Gene),
-)
+```text
+gene ontology → graph closure (KinaseGene) → rules (eligibility + coverage sub-concepts) → CSP cohort selection → verify
 ```
 
-**Rules: lift the closure to patient-level sub-concepts.** Pure relational arithmetic, no decisions. Predicates are encoded as sub-concepts -- their *membership* is the predicate -- so downstream rules and the CSP just check `Sub(Parent)` to test the predicate (cheaper and clearer than Boolean indicator properties). The qualifying-pair AE-window predicate is lifted into a 3-arity `Patient.qualifying_pair(TherapyEvent, AdverseEventOcc)` relationship and the three downstream rules (eligibility, therapy coverage, AE coverage) all project from it -- changing the qualifying-pair definition (severity matching, treatment duration, multi-event sequencing) is then an edit to one rule rather than three:
-
-```python
-KinaseMutationCarrier = model.Concept("KinaseMutationCarrier", extends=[Patient])
-model.define(KinaseMutationCarrier(Patient)).where(
-    MutationEvent.patient == Patient,
-    KinaseGene(MutationEvent.gene),
-)
-
-Patient.qualifying_pair = model.Relationship(
-    f"{Patient} qualifies on {TherapyEvent:therapy_event} and {AdverseEventOcc:ae_occ}"
-)
-model.define(Patient.qualifying_pair(TherapyEvent, AdverseEventOcc)).where(
-    TherapyEvent.patient == Patient,
-    AdverseEventOcc.patient == Patient,
-    AdverseEventOcc.t_days - TherapyEvent.t_days >= 0,
-    AdverseEventOcc.t_days - TherapyEvent.t_days <= MAX_THERAPY_TO_AE_DAYS,
-)
-
-QualifyingPairPatient = model.Concept("QualifyingPairPatient", extends=[Patient])
-model.define(QualifyingPairPatient(Patient)).where(
-    Patient.qualifying_pair(TherapyEvent, AdverseEventOcc),
-)
-
-EligiblePatient = model.Concept("EligiblePatient", extends=[Patient])
-model.define(EligiblePatient(Patient)).where(
-    KinaseMutationCarrier(Patient),
-    QualifyingPairPatient(Patient),
-)
-
-# Per-axis coverage projects from `qualifying_pair`:
-Patient.covers_therapy = model.Relationship(f"{Patient} covers {Therapy:therapy}")
-model.define(Patient.covers_therapy(Therapy)).where(
-    Patient.qualifying_pair(TherapyEvent, AdverseEventOcc),
-    TherapyEvent.therapy == Therapy,
-)
-```
+**Graph reasoner: one call to close the ontology.** The `is_a` CSV is in OMOP / SNOMED convention (child -> parent), but the graph is built with source and destination swapped, so reachability from the pathway root flows *downwards* through the subclass tree onto every descendant gene. The full transitive closure (every ancestor-descendant pair) is materialized as a sub-concept `KinaseGene extends Gene` — the genes reachable from the configured pathway root.
 
-**Prescriptive reasoner: cohort selection as a CSP.** Decisions target the sub-concept directly (`EligiblePatient.is_in_cohort`, `CoverableTherapy.is_covered`, ...), which creates one binary variable per sub-concept row. The `Coverable*` sub-concepts are themselves scoped to *eligible-patient* coverage, not any-patient coverage: a Y covered only by ineligible patients would otherwise sit in `Coverable*` with no upper-bound IC binding (the per-pair `where` body has no eligible-patient row for it), and the solver would mark it covered to satisfy the lower bound trivially. Scoping `Coverable*` to `EligiblePatient.covers_*` closes that gap; scoping `solve_for` to `Coverable*` then ensures every `is_covered` decision has a real upper bound.
-
-```python
-problem.solve_for(
-    EligiblePatient.is_in_cohort, type="bin",
-    name=["is_in_cohort", EligiblePatient.id],
-)
-problem.solve_for(
-    CoverableTherapy.is_covered, type="bin",
-    name=["therapy_covered", CoverableTherapy.id],
-)
-```
+**Rules: lift the closure to patient-level sub-concepts.** Pure relational arithmetic, no decisions. Predicates are encoded as sub-concepts — a patient's *membership* in `KinaseMutationCarrier`, `QualifyingPairPatient`, or `EligiblePatient` is the predicate itself, which downstream rules and the CSP test by a simple membership check. The AE-window predicate ("an adverse event follows a therapy within `MAX_THERAPY_TO_AE_DAYS`") is lifted once into a 3-arity `Patient.qualifying_pair` relationship, and the three downstream rules (eligibility, therapy coverage, AE coverage) all project from it — so redefining the qualifying pair is an edit to one rule rather than three. A patient is eligible exactly when they are both a kinase-mutation carrier and a qualifying-pair patient.
 
-**Coverage upper bound + per-pair lower bound + floor is the CSP signature.** For each coverable Y, `Y.is_covered` is bounded above by the number of in-cohort patients that cover it (so an unsupported Y cannot be marked covered) AND bounded below per pair by `EligiblePatient.is_in_cohort` (so any in-cohort patient covering Y forces `is_covered` to saturate to 1). The two bounds together pin `is_covered` to the actual coverage. The floor IC `sum(is_covered) >= MIN_*` then constrains the cohort to span at least `MIN_*` distinct values. Without the per-pair lower bound the solver could leave indicators at 0 even when the cohort actually covers them, making the inspect() output underreport.
+**Prescriptive reasoner: cohort selection as a CSP.** Decisions target the sub-concepts directly (`EligiblePatient.is_in_cohort`, `CoverableTherapy.is_covered`, and the gene/AE analogues), creating one binary variable per sub-concept row. The `Coverable*` sub-concepts are scoped to *eligible-patient* coverage, not any-patient coverage: a value covered only by ineligible patients would otherwise have no upper-bound constraint binding it and the solver could mark it covered for free. Scoping coverage to eligible patients, and scoping the decisions to `Coverable*`, ensures every `is_covered` decision has a real upper bound.
 
-```python
-gene_cover_ub_ic = model.where(EligiblePatient.covers_kinase_gene(CoverableGene)).require(
-    CoverableGene.is_covered <= sum(EligiblePatient.is_in_cohort).per(CoverableGene)
-)
-gene_cover_lb_ic = model.where(EligiblePatient.covers_kinase_gene(CoverableGene)).require(
-    CoverableGene.is_covered >= EligiblePatient.is_in_cohort
-)
-gene_min_ic = model.require(sum(CoverableGene.is_covered) >= MIN_GENES_COVERED)
-```
+The CSP signature is coverage upper bound + per-pair lower bound + floor. For each coverable value, `is_covered` is bounded above by the number of in-cohort patients that cover it (an unsupported value can't be marked covered) and bounded below per pair by each covering in-cohort patient (any in-cohort patient covering it forces `is_covered` to 1). The two bounds pin the indicator to the actual coverage; the floor constraint (`sum(is_covered) >= MIN_*`) then forces the cohort to span at least the required number of distinct genes, therapies, and adverse events. Every constraint is pure relational arithmetic, so `problem.verify()` re-evaluates all of them in the returned solution.
 
-All ten ICs are pure relational arithmetic, so `problem.verify()` re-evaluates every one in the returned solution -- no constraint is solver-only.
+For the exact PyRel formulation, see `patient_cohort_recruitment.py`; `runbook.md` reproduces the three stages step by step with the RAI skills.
 
 ## Customize this template
 
-- **Use your own data** by replacing the eight CSV files with your gene ontology and patient knowledge graph. The constraint structure does not change. If your ontology already stores `is_a` parent -> child, drop the `parent` / `child` flip in the `Graph` constructor. If you don't have ontology data, define `KinaseGene` membership directly on the genes you care about and skip the Graph step.
-- **Change the cohort target** by adjusting `COHORT_SIZE` and the three `MIN_*_COVERED` floors at the top. Tightening any one of them shrinks the feasible region; setting `MIN_GENES_COVERED = COHORT_SIZE` forces every patient in the cohort to cover a distinct gene (rules out two patients with identical mutation patterns).
-- **Move from feasibility to optimization.** This template is a satisfaction model -- any cohort that hits the floors is correct. To rank, swap `problem.solve(...)` for `problem.maximize(sum(CoverableGene.is_covered) + sum(CoverableTherapy.is_covered) + sum(CoverableAdverseEvent.is_covered))` to find the cohort with the broadest joint span, or `problem.minimize(sum(EligiblePatient.is_in_cohort * EligiblePatient.age_years))` for a younger cohort. MiniZinc / Chuffed handles both.
-- **Keep aggregates on a single sub-concept.** Aggregations over a decision must reference the sub-concept the decision was scoped to -- mixing parent and sub-concept references in a single aggregate triggers a TypeError.
-- **Tighten the qualifying window** by editing `MAX_THERAPY_TO_AE_DAYS`. The 90-day window is a common attribution choice for treatment-emergent AEs in oncology trials; some indications use 28 days for acute toxicity, others 180 days for late-onset events.
-- **Add patient-level eligibility rules** -- minimum age, treatment-naive status, organ-function thresholds -- by adding more conjuncts to the `EligiblePatient` definition (or by introducing further `extends=[Patient]` sub-concepts). Each extra rule narrows the eligible set; the CSP automatically drops decisions for newly-ineligible patients.
-- **Add cohort-level fairness rules.** A balanced-cohort study might require a minimum count from each of two demographic strata. Add a stratum property (`Patient.stratum`) and an IC `sum(EligiblePatient.is_in_cohort).per(EligiblePatient.stratum) >= MIN_PER_STRATUM` to enforce minimum representation per stratum. The decision-side aggregate must key on the sub-concept (`EligiblePatient`), not the parent (`Patient`).
-- **Anchor on a different ontology root** by changing `KINASE_ROOT_GENE_ID`. Multi-pathway studies can run several queries with different roots and union the results.
+### Use your own data
 
-## Learn more
+- Replace the eight CSV files with your gene ontology and patient knowledge graph. The constraint structure does not change.
+- If your ontology already stores `is_a` parent-to-child, drop the `parent` / `child` flip in the `Graph` constructor.
+- If you don't have ontology data, define `KinaseGene` membership directly on the genes you care about and skip the Graph step.
+- Anchor on a different ontology root by changing `KINASE_ROOT_GENE_ID`. Multi-pathway studies can run several queries with different roots and union the results.
 
-**Cohort discovery and patient knowledge graphs** (the domain background for relational cohort enumeration on a labelled patient graph):
-- Wang, W. et al., [*Building Patient Cohorts with NLP and Knowledge Graphs*](https://www.databricks.com/blog/building-patient-cohorts-nlp-and-knowledge-graphs). End-to-end pipeline shape, ontology-driven cohort enumeration.
-- Xu et al., [*Enhanced pre-recruitment framework through KG + LLMs*](https://www.nature.com/articles/s41598-025-11876-0). Knowledge-graph-driven trial-eligibility screening.
+### Tune parameters
 
-**Subgraph and set-cover techniques** (the academic backbone for "find K nodes whose joint coverage spans enough labels"):
-- McCreesh, Prosser & Trimble, [*The Glasgow Subgraph Solver*](https://link.springer.com/chapter/10.1007/978-3-030-51372-6_19). State-of-the-art constraint-based subgraph isomorphism.
-- Caprara, Toth & Fischetti, [*Algorithms for the Set Covering Problem*](https://link.springer.com/article/10.1023/A:1018984712387). The classical IP/CP encoding behind the coverage upper-bound + lower-bound pattern.
+- **Cohort target** — adjust `COHORT_SIZE` and the three `MIN_*_COVERED` floors at the top. Tightening any one shrinks the feasible region; setting `MIN_GENES_COVERED = COHORT_SIZE` forces every patient in the cohort to cover a distinct gene (rules out two patients with identical mutation patterns).
+- **Qualifying window** — edit `MAX_THERAPY_TO_AE_DAYS`. The 90-day window is a common attribution choice for treatment-emergent AEs in oncology trials; some indications use 28 days for acute toxicity, others 180 days for late-onset events.
 
-**Healthcare data standards** (the data shapes the patient KG mirrors):
-- OHDSI, [*OMOP Common Data Model v6*](https://ohdsi.github.io/CommonDataModel/). The standardised relational schema for observational patient data.
-- HL7, [*FHIR R5*](https://hl7.org/fhir/R5/). The FHIR resource graph for clinical data exchange.
+### Extend the model
+
+- **Move from feasibility to optimization.** This template is a satisfaction model — any cohort that hits the floors is correct. To rank, swap `problem.solve(...)` for `problem.maximize(sum(CoverableGene.is_covered) + sum(CoverableTherapy.is_covered) + sum(CoverableAdverseEvent.is_covered))` to find the cohort with the broadest joint span, or `problem.minimize(sum(EligiblePatient.is_in_cohort * EligiblePatient.age_years))` for a younger cohort. MiniZinc / Chuffed handles both.
+- **Add patient-level eligibility rules** — minimum age, treatment-naive status, organ-function thresholds — by adding more conjuncts to the `EligiblePatient` definition (or by introducing further `extends=[Patient]` sub-concepts). Each extra rule narrows the eligible set; the CSP automatically drops decisions for newly-ineligible patients.
+- **Add cohort-level fairness rules.** A balanced-cohort study might require a minimum count from each of two demographic strata. Add a stratum property (`Patient.stratum`) and an IC `sum(EligiblePatient.is_in_cohort).per(EligiblePatient.stratum) >= MIN_PER_STRATUM` to enforce minimum representation per stratum. The decision-side aggregate must key on the sub-concept (`EligiblePatient`), not the parent (`Patient`).
+- **Keep aggregates on a single sub-concept.** Aggregations over a decision must reference the sub-concept the decision was scoped to — mixing parent and sub-concept references in a single aggregate triggers a TypeError.
+
+### Scale up / productionize
+
+- For a live patient store, replace the `read_csv(...)` loads with `model.data(snowflake_table)` calls so the ontology reads directly from your OMOP / FHIR tables; the rules and CSP are unchanged.
+- The pre-solve invariants (unique keys, foreign-key integrity, root presence, non-negative timestamps) become your first-pass data-quality gate on real feeds — keep them.
+- The bundled data runs in seconds; larger cohorts scale to whatever the constraint solver's budget allows. Raise `time_limit_sec` in the `problem.solve(...)` call for bigger eligible sets.
+- Pin `relationalai` (see Prerequisites) so runs stay reproducible across environments.
 
 ## Troubleshooting
 
@@ -351,3 +271,21 @@ Two encoding pitfalls produce this symptom; both must be guarded against.
 - HiGHS is not appropriate here -- this is a discrete satisfaction model with categorical decisions and structural propagation, not LP/MILP.
 
 </details>
+
+## Learn more
+
+**Cohort discovery and patient knowledge graphs** (the domain background for relational cohort enumeration on a labelled patient graph):
+- Wang, W. et al., [*Building Patient Cohorts with NLP and Knowledge Graphs*](https://www.databricks.com/blog/building-patient-cohorts-nlp-and-knowledge-graphs). End-to-end pipeline shape, ontology-driven cohort enumeration.
+- Xu et al., [*Enhanced pre-recruitment framework through KG + LLMs*](https://www.nature.com/articles/s41598-025-11876-0). Knowledge-graph-driven trial-eligibility screening.
+
+**Subgraph and set-cover techniques** (the academic backbone for "find K nodes whose joint coverage spans enough labels"):
+- McCreesh, Prosser & Trimble, [*The Glasgow Subgraph Solver*](https://link.springer.com/chapter/10.1007/978-3-030-51372-6_19). State-of-the-art constraint-based subgraph isomorphism.
+- Caprara, Toth & Fischetti, [*Algorithms for the Set Covering Problem*](https://link.springer.com/article/10.1023/A:1018984712387). The classical IP/CP encoding behind the coverage upper-bound + lower-bound pattern.
+
+**Healthcare data standards** (the data shapes the patient KG mirrors):
+- OHDSI, [*OMOP Common Data Model v6*](https://ohdsi.github.io/CommonDataModel/). The standardised relational schema for observational patient data.
+- HL7, [*FHIR R5*](https://hl7.org/fhir/R5/). The FHIR resource graph for clinical data exchange.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/planogram_optimization/README.md b/v1/planogram_optimization/README.md
index 1264db92..3455f500 100644
--- a/v1/planogram_optimization/README.md
+++ b/v1/planogram_optimization/README.md
@@ -2,7 +2,7 @@
 title: "Planogram Optimization"
 description: "Decide integer facing counts per SKU to maximize predicted weekly demand under shelf capacity and category cardinality limits, where per-(SKU, facing_count) demand comes from a regression model."
 featured: false
-private: true
+private: false
 experience_level: intermediate
 industry: "Retail & Consumer"
 reasoning_types:
@@ -16,8 +16,6 @@ tags:
   - shelf-space-allocation
 ---
 
-# Planogram Optimization
-
 ## What this template is for
 
 Retailers running grocery, mass-merchandise, drug, and CPG categories decide how many *facings* (front-row product positions) to allocate per SKU on each shelf. More facings of a hot product lift its weekly sales; more facings of a slow mover wastes shelf length that could carry a faster competitor. The right answer differs by category, by SKU within a category, and by the diminishing-returns curve each SKU exhibits as you give it more space.
@@ -47,6 +45,7 @@ The same pattern applies to any predict-then-optimize problem where the predicti
 ## What's included
 
 - `planogram_optimization.py` -- main script with ontology, decisions, constraints, and solver call
+- **Runbook**: `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/skus.csv` -- 18 SKUs across 4 categories (snacks, beverages, candy, household_paper) with width, max-facings, and pre-assigned shelf; `sku_id` must be unique, `category` must match a `categories.csv` name, and `assigned_shelf_id` must reference a `shelves.csv` id. The `brand` column is loaded but not used by the bundled CSP -- it is reserved for the brand-block contiguity customization described under "Customize this template"
 - `data/shelves.csv` -- 4 shelves (Top Eye-Level 100cm, Upper-Middle 80cm, Lower-Middle 80cm, Bottom 90cm); `id` must be unique and is the foreign-key target of `skus.assigned_shelf_id`
 - `data/categories.csv` -- per-category min/max active SKU bounds; `name` must be unique and is the foreign-key target of `skus.category`
@@ -61,6 +60,7 @@ The same pattern applies to any predict-then-optimize problem where the predicti
 
 ### Tools
 - Python >= 3.10
+- RelationalAI Python SDK (`relationalai == 1.1.0`)
 
 ## Quickstart
 
@@ -155,63 +155,58 @@ The same pattern applies to any predict-then-optimize problem where the predicti
     └── predicted_demand_table.csv
 ```
 
-## How it works
+**Start here**: run `python planogram_optimization.py` for the full predict-then-optimize run end to end — it validates the data, binds each SKU's demand from the prediction table, solves the facing-count CSP, and prints the allocation — or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-The CSP picks integer facings per SKU; the predictive output binds the realized-demand decision via a decision-indexed table lookup. The script consists of these patterns:
+## Sample data
 
-**Element-style decision-indexed table lookup is the predict->CSP hand-off.** For each SKU, `Sku.realized_demand` is pinned to the `demand_units` row of `PredictedDemand` whose `facings_count` matches the chosen `Sku.facings`. The `implies` cascade lowers per row of `PredictedDemand` into one half-reified linear equality `implies(k == Sku.facings, Sku.realized_demand == table[sku, k])`; only the row with `k == Sku.facings` activates:
+The bundled CSVs are illustrative, fully synthetic demo data sized so the model runs in seconds. The `predicted_demand_table.csv` is a vendored stand-in for the output of any per-(SKU, facings-count) demand regressor, so the predict-to-CSP hand-off can be inspected and run without a training arm. A pre-solve pass validates unique keys, category and shelf foreign keys, and that the demand table is complete over every SKU's `[0, max_facings]` range with `demand_units = 0` at `facings_count = 0`.
 
-```python
-demand_lookup_ic = model.where(PredictedDemand.sku_id == Sku.id).require(
-    implies(
-        PredictedDemand.facings_count == Sku.facings,
-        Sku.realized_demand == PredictedDemand.demand_units,
-    )
-)
-```
+- **`skus.csv`** (18 rows) — SKUs across 4 categories (snacks, beverages, candy, household_paper) with `width_cm`, `max_facings`, `category`, and a pre-assigned `assigned_shelf_id`. The `brand` column is loaded but unused by the bundled CSP (reserved for the brand-block-contiguity customization).
+- **`shelves.csv`** (4 rows) — shelves with fixed lengths (Top Eye-Level 100cm, Upper-Middle 80cm, Lower-Middle 80cm, Bottom 90cm); `shelf_id` is the foreign-key target of `skus.assigned_shelf_id`.
+- **`categories.csv`** (4 rows) — per-category minimum and maximum active-SKU bounds; `category` is the foreign-key target of `skus.category`.
+- **`predicted_demand_table.csv`** — one row per `(sku_id, facings_count)` for every `facings_count` in `{0, 1, ..., sku.max_facings}`, with concave per-SKU demand curves; the `facings_count = 0` row is `demand_units = 0`.
 
-The natural relational form -- `where(PredictedDemand.facings_count == Sku.facings).require(Sku.realized_demand == PredictedDemand.demand_units)` -- equates a data property with a decision variable inside a `where` binding, which the prescriptive rewriter doesn't lower today. Pushing the decision-vs-data equality into the predicate of an `implies` lets the rewriter expand into the canonical per-`k` form.
+## Model overview
 
-**Active iff facings is a pair of linear inequalities.** `Sku.active` is a 0/1 integer (declared as `solve_for(..., type="bin")`) because the per-category cardinality is written as `sum(Sku.active).per(Category)`, and a relational sum over a Boolean expression like `Sku.facings >= 1` is not a valid form. Two linear constraints couple the indicator to `Sku.facings`:
+The model has four concepts. The predictive output (`PredictedDemand`) is a data table that the CSP reads through a decision-indexed lookup; the decision lives on `Sku`.
 
-```python
-active_lower_ic = model.require(Sku.facings >= Sku.active)
-active_upper_ic = model.require(Sku.facings <= Sku.max_facings * Sku.active)
-```
+- **Key entities**: `Sku` — a product with a width, max-facings cap, category, and assigned shelf (its facing count is the CSP decision); `Shelf` — a shelf with a fixed length that facings must fit within; `Category` — a product category with minimum and maximum active-SKU bounds; `PredictedDemand` — the predicted demand for each `(sku, facings_count)`, read by the CSP through a decision-indexed lookup.
+- **Primary identifiers**: integer `id` on `Sku` and `Shelf`; string `name` on `Category`; composite `(sku_id, facings_count)` on `PredictedDemand`.
+- **Important invariants**: `width_cm`, `max_facings`, and `length_cm` are non-negative integers; every `Sku.category` matches a `Category`, and every `Sku.assigned_shelf_id` matches a `Shelf`; `PredictedDemand` covers every `(sku_id, facings_count)` over `[0, max_facings]` with `demand_units = 0` at `facings_count = 0`; the CSP decisions `facings`, `realized_demand`, and `active` are integers (`active` is 0/1).
 
-`Sku.facings >= Sku.active` forces `facings >= 1` when `active == 1`; `Sku.facings <= Sku.max_facings * Sku.active` forces `facings == 0` when `active == 0`. Together they pin `active = 1` whenever `facings >= 1` and `active = 0` otherwise. Both ICs are pure relational arithmetic, so they get re-evaluated by `problem.verify()` below.
+For the full concept and property definitions, see `planogram_optimization.py`; `runbook.md` builds them step by step with the RAI skills.
 
-Once `active` is bound, the per-category cardinality reads as a plain relational sum:
+## How it works
 
-```python
-category_min_ic = model.where(Sku.category == Category.name).require(
-    sum(Sku.active).per(Category) >= Category.min_skus_active
-)
-```
+The CSP picks integer facings per SKU; the predictive output binds each SKU's realized demand via a decision-indexed table lookup, and the solver maximizes total predicted demand under shelf and category limits.
 
-**The `implies`-bodied table lookup is solver-only.** It goes to `satisfy()` but must NOT be passed to `verify()` -- implies-bodied ICs are solver-only and `verify()` returns silently-OK without actually evaluating them. The relational-arithmetic ICs (capacity, cardinality, active coupling) ARE re-evaluated by `verify()`, and a post-solve Python dict lookup re-checks the table lookup against the input CSV:
-
-```python
-problem.solve("minizinc", time_limit_sec=60)
-problem.verify(
-    shelf_capacity_ic,
-    category_min_ic,
-    category_max_ic,
-    active_lower_ic,
-    active_upper_ic,
-)
-model.require(problem.termination_status() == "OPTIMAL")
-# ... post-solve Python dict lookup verifies (sku_id, facings) -> demand_units ...
+```text
+skus + shelves + categories + predicted-demand table → facings / realized_demand / active decisions → lookup + capacity + cardinality constraints → maximize demand → solve → verify
 ```
 
+**The decision-indexed table lookup is the predict-to-CSP hand-off.** For each SKU, `realized_demand` must equal the `PredictedDemand` row whose `facings_count` matches the chosen `facings`. Because equating a data property with a decision variable inside a `where` binding isn't a form the prescriptive rewriter lowers today, the lookup is written with an `implies` cascade — one half-reified equality per candidate facing count, of which only the row matching the chosen `facings` activates. This is the element-style lookup: no bilinearity, no big-M, no SOS2.
+
+**An `active` indicator couples to `facings` via two linear inequalities.** The per-category cardinality is a relational sum over a 0/1 `active` variable (a sum over a Boolean expression like `facings >= 1` is not a valid form). Two linear constraints pin `active = 1` whenever `facings >= 1` and `active = 0` otherwise, after which the per-category count reads as a plain `sum(active).per(Category)` with min/max bounds. Shelf capacity is likewise a plain relational inequality: facings times width, summed per shelf, cannot exceed the shelf length.
+
+**Verification is split by constraint kind.** The `implies`-bodied lookup is solver-only — it goes to the solver but is not passed to `verify()`, which would return silently OK without evaluating it; instead a post-solve Python dict re-checks each `(sku_id, facings) -> demand_units` against the input table. The pure relational-arithmetic constraints (capacity, cardinality, active coupling) *are* re-evaluated by `verify()`, and a post-solve assertion confirms the solver reached `OPTIMAL`.
+
+For the exact PyRel formulation, see `planogram_optimization.py`; `runbook.md` reproduces the pipeline step by step with the RAI skills.
+
 ## Customize this template
 
-- **Replace the vendored table with your own per-(SKU, k) demand model.** In production, `PredictedDemand` is the output of any model that predicts weekly demand at each candidate facings count -- linear or GBM regression over engineered features, a per-tier head, or a graph-aware regressor over `(sku, week, facings_count, units_sold)` history. The structural requirement is that `facings_count` is a feature (or there is a head per tier) so the model can be queried at every `k`.
+### Use your own data
+
+- Replace the four CSV files with your SKUs, shelves, categories, and predicted demand table. The constraint structure does not change. The data invariant: `predicted_demand_table.csv` must contain a row for every `(sku_id, k)` for `k in {0, 1, ..., sku.max_facings}` — if a row is missing, the implies cascade leaves `Sku.realized_demand` unconstrained for that combination and the solver may pick an arbitrary value.
+- **Wire in a real demand model.** In production, `PredictedDemand` is the output of any model that predicts weekly demand at each candidate facing count — linear or GBM (gradient-boosted machine) regression over engineered features, a per-tier head, or a graph-aware regressor over `(sku, week, facings_count, units_sold)` history. The structural requirement is that `facings_count` is a feature (or there is a head per tier) so the model can be queried at every `k`. Produce `data/predicted_demand_table.csv` in the format `sku_id,facings_count,demand_units` (integer demand) from your inference pipeline and drop it in — the script picks it up unchanged. To call inference inline, replace the `read_csv(DATA_DIR / "predicted_demand_table.csv")` line with code that returns a DataFrame with those three columns.
+
+### Tune parameters
 
-  The path of least friction is to produce `data/predicted_demand_table.csv` in the format `sku_id,facings_count,demand_units` (integer demand) from your inference pipeline and drop it in -- the script picks it up unchanged. To call inference inline, replace the `read_csv(DATA_DIR / "predicted_demand_table.csv")` line with code that returns a DataFrame with those three columns. The CSP shape below is unchanged.
-- **Use your own data** by replacing the four CSV files with your SKUs, shelves, categories, and predicted demand table. The constraint structure does not change. The data invariant: `predicted_demand_table.csv` MUST contain a row for every `(sku_id, k)` for `k in {0, 1, ..., sku.max_facings}` -- if a row is missing, the implies cascade leaves `Sku.realized_demand` unconstrained for that combination and the solver may pick an arbitrary value.
-- **Per-SKU minimum facings** by tightening the lower-coupling IC to `model.require(Sku.facings >= Sku.min_facings * Sku.active)` after adding a `Sku.min_facings` data property. (Removing disallowed `(sku, k)` rows from `predicted_demand_table.csv` would trip `_assert_demand_table_complete`; the lookup formulation requires the table to cover the full `[0, max_facings]` range.)
-- **Eye-level priority** is a constraint over the *static* shelf assignment in the bundled model -- it validates that every premium SKU's `assigned_shelf_id` already points to the eye-level shelf and fails otherwise. Reassigning premium SKUs at solve time requires the multi-shelf reformulation below.
+- **Per-SKU minimum facings** — tighten the lower-coupling IC to `model.require(Sku.facings >= Sku.min_facings * Sku.active)` after adding a `Sku.min_facings` data property. (Removing disallowed `(sku, k)` rows from `predicted_demand_table.csv` would trip `_assert_demand_table_complete`; the lookup formulation requires the table to cover the full `[0, max_facings]` range.)
+- **Category cardinality** — adjust `min_skus_active` / `max_skus_active` in `categories.csv` to change how many SKUs each category may keep active.
+
+### Extend the model
+
+- **Eye-level priority** is a constraint over the *static* shelf assignment in the bundled model — it validates that every premium SKU's `assigned_shelf_id` already points to the eye-level shelf and fails otherwise. Reassigning premium SKUs at solve time requires the multi-shelf reformulation below.
   ```python
   Sku.is_premium = model.Property(f"{Sku} has {Integer:is_premium}")
   # ... populate from a column on skus.csv ...
@@ -221,8 +216,15 @@ model.require(problem.termination_status() == "OPTIMAL")
   )
   problem.satisfy(eye_level_ic)
   ```
-- **Multi-shelf reassignment** changes the shape of the model meaningfully. `solve_for` accepts only `int`/`cont`/`bin`, not relationship-valued domains, so shelf assignment cannot be a `Sku.shelf` decision directly. The same decision-vs-data-equality limitation that drives the `implies`-cascade table lookup also blocks `model.define(Sku.shelf(Shelf)).where(Shelf.id == Sku.shelf_id)` when `Sku.shelf_id` is a decision variable. The principled rewrite introduces a per-`(SKU, Shelf)` integer facing decision (e.g. `SkuShelf.facings`), uses `sum(SkuShelf.facings).per(Sku)` as the SKU's total facings, and writes capacity as `sum(SkuShelf.facings * Sku.width_cm).per(Shelf) <= Shelf.length_cm`. This is more involved than the bundled CSP and is left as an exercise.
-- **Brand-block contiguity** -- same-brand SKUs must occupy adjacent facings on the shelf -- requires a per-shelf SKU position decision variable with adjacency constraints (more involved; the basic facing-count CSP above is unchanged but augmented).
+- **Multi-shelf reassignment** changes the shape of the model meaningfully. `solve_for` accepts only `int` / `cont` / `bin`, not relationship-valued domains, so shelf assignment cannot be a `Sku.shelf` decision directly. The same decision-vs-data-equality limitation that drives the `implies`-cascade table lookup also blocks `model.define(Sku.shelf(Shelf)).where(Shelf.id == Sku.shelf_id)` when `Sku.shelf_id` is a decision variable. The principled rewrite introduces a per-`(SKU, Shelf)` integer facing decision (e.g. `SkuShelf.facings`), uses `sum(SkuShelf.facings).per(Sku)` as the SKU's total facings, and writes capacity as `sum(SkuShelf.facings * Sku.width_cm).per(Shelf) <= Shelf.length_cm`. This is more involved than the bundled CSP and is left as an exercise.
+- **Brand-block contiguity** — same-brand SKUs must occupy adjacent facings on the shelf — requires a per-shelf SKU position decision variable with adjacency constraints (more involved; the basic facing-count CSP above is unchanged but augmented).
+
+### Scale up / productionize
+
+- For a live catalog, replace the `read_csv(...)` loads with `model.data(snowflake_table)` calls so the SKUs, shelves, categories, and predicted-demand table read directly from your warehouse; the CSP is unchanged.
+- The vendored `predicted_demand_table.csv` becomes a materialized inference output on a schedule — refresh it from your demand model, and the pre-solve completeness guard (`_assert_demand_table_complete`) gates each run.
+- The bundled data is 18 SKUs across 4 shelves; the CSP scales to whatever the constraint solver's budget allows. Raise `time_limit_sec` in the `problem.solve(...)` call for larger catalogs.
+- Pin `relationalai` (see Prerequisites) so runs stay reproducible across environments.
 
 ## Troubleshooting
 
@@ -275,3 +277,23 @@ model.require(problem.termination_status() == "OPTIMAL")
 - To pin a single answer, add a tie-breaker to the objective -- e.g. `problem.maximize(sum(Sku.realized_demand) * 1000 - sum(Sku.facings))` prefers fewer facings among equal-demand allocations.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Predict-then-optimize patterns](https://docs.relational.ai/) — feeding a predictive model's output into a prescriptive solve on one ontology.
+- [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API: integer decisions (`solve_for`), constraints (`satisfy`), objective (`maximize`), and `verify`.
+
+### Language / modeling reference
+
+- [Concepts and properties](https://docs.relational.ai/) — modeling `Sku`, `Shelf`, `Category`, and the composite-keyed `PredictedDemand`.
+- [Integrity constraints and `implies`](https://docs.relational.ai/) — half-reified linear equalities behind the decision-indexed table lookup.
+
+### Deeper dives
+
+- [Constraint-solver selection (MiniZinc)](https://docs.relational.ai/) — why a pure CSP formulation avoids big-M and SOS2, and when to reformulate for a linear backend.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/pod_placement/README.md b/v1/pod_placement/README.md
index a755f2d2..838b0daf 100644
--- a/v1/pod_placement/README.md
+++ b/v1/pod_placement/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Pod Placement"
-description: "Assign pods to nodes in a Kubernetes-style cluster subject to per-node CPU / memory / GPU bin-packing, pairwise tenant anti-affinity, deployment co-location affinity, failure-domain spread, gang-placement atomicity, and topology rack-clique rules. Pure CSP via MiniZinc / Chuffed."
+description: "Assign pods to nodes in a Kubernetes-style cluster subject to per-node CPU, memory, and GPU bin-packing, pairwise tenant anti-affinity, deployment co-location affinity, failure-domain spread, gang-placement atomicity, and topology rack-clique rules, solved as a pure constraint satisfaction problem (CSP)."
 featured: false
 experience_level: intermediate
 industry: "Technology & Telecom"
@@ -15,20 +15,18 @@ tags:
   - kubernetes
 ---
 
-# Pod Placement
-
 ## What this template is for
 
-Multi-tenant Kubernetes / SaaS / HPC platform teams place pods (containerised workloads) onto cluster nodes against a stack of rules that don't fit a clean linear program:
+Multi-tenant Kubernetes, SaaS, and HPC platform teams place pods (containerized workloads) onto cluster nodes against a stack of rules that don't fit a clean linear program:
 
 - **Resource bin-packing** -- each node has fixed CPU / memory / GPU capacity, and the sum of pod demands on a node can't exceed it.
-- **Tenant anti-affinity** -- regulated workloads (SEC / OCC / NAIC / FedRAMP) require pairs of tenants to never share a host, so a single noisy-neighbour or compromised node can't span the isolation boundary.
+- **Tenant anti-affinity** -- regulated workloads (SEC / OCC / NAIC / FedRAMP) require pairs of tenants to never share a host, so a single noisy-neighbor or compromised node can't span the isolation boundary.
 - **Deployment co-location affinity** -- deployments declared affinity-paired (e.g. shared storage class, low-latency RDMA peering) must co-locate (same node) or share their unplaced state: the `xi == xj` IC forces both to agree on every node's assignment bit, which means they share a single node when placed and are simultaneously unplaced otherwise.
 - **Failure-domain spread** -- replicas of one deployment fan out across zones so a single-zone outage can't take down a quorum.
 - **Gang-placement atomicity** -- a multi-replica deployment is either fully placed (every replica scheduled) or fully unplaced; a partial schedule is worse than nothing for stateful systems with leader elections, quorums, and shared-state protocols.
 - **Topology rack-clique** -- distributed-training pods need NVLink-class bandwidth between every pair, so the whole group must land on hosts within the same rack.
 
-This template encodes that stack as a pure constraint satisfaction / optimisation problem: the **Prescriptive** reasoner (MiniZinc / Chuffed) maximises the number of placed deployments subject to all six rules as hard constraints. The shape applies to every multi-tenant K8s shop, financial-services regulated multi-tenancy, defence / FedRAMP-cleared environments, telco 5G network slicing, and HPC + AI infrastructure that runs gang-scheduled distributed training.
+This template encodes that stack as a pure constraint satisfaction and optimization problem. **The prescriptive reasoner (MiniZinc / Chuffed) maximizes the number of placed deployments subject to all six rules as hard constraints.** The shape applies to every multi-tenant Kubernetes shop, financial-services regulated multi-tenancy, defense / FedRAMP-cleared environments, telco 5G network slicing, and HPC and AI infrastructure that runs gang-scheduled distributed training.
 
 ## Who this is for
 
@@ -47,14 +45,15 @@ This template encodes that stack as a pure constraint satisfaction / optimisatio
 - A per-(deployment, zone) failure-domain spread IC bounded by `Deployment.max_per_zone` -- by default `ceil(replicas / num_zones)`, with a per-row `max_per_zone_override` column in `deployments.csv` for deployments (e.g. distributed-training groups) that need a wider blast radius to remain feasible
 - A reified-cardinality gang-placement IC `sum(Pod.placed).per(Deployment) == Deployment.replicas * Deployment.placed`
 - A pairwise topology rack-clique IC for distributed-training groups -- `xa + xb <= 1` for every (Pa, Pb, Na, Nb) tuple where the pods are in the same training group and the nodes are in different racks
-- A linear `maximize(sum(Deployment.placed))` objective the CSP optimises
+- A linear `maximize(sum(Deployment.placed))` objective the CSP optimizes
 - Post-solve verification via `problem.verify()` confirming every IC holds in the returned solution, plus a `termination_status() == "OPTIMAL"` assertion
 
 ## What's included
 
-The bundled CSVs are illustrative, fully synthetic demo data tuned so multiple ICs bind at the optimum -- rack-clique forces the distributed-training group onto one rack, CPU / memory / GPU bin-packing then pin it to a single node at exact 100% utilisation on all three resources, anti-affinity partitions the alpha-beta and gamma-delta tenant pods across disjoint node sets, deployment co-location affinity co-locates the cache pair, and the spread cap binds for every multi-replica non-overridden deployment. Swap in your own cluster topology and workload to apply the template to a real cluster.
+The bundled CSVs are illustrative demo data tuned so multiple ICs bind at the optimum -- rack-clique forces the distributed-training group onto one rack, CPU / memory / GPU bin-packing then pin it to a single node at exact 100% utilization on all three resources, anti-affinity partitions the alpha-beta and gamma-delta tenant pods across disjoint node sets, deployment co-location affinity co-locates the cache pair, and the spread cap binds for every multi-replica non-overridden deployment. Swap in your own cluster topology and workload to apply the template to a real cluster.
 
 - `pod_placement.py` -- main script with concepts, decisions, constraints, the solver call, and the post-solve inspection
+- **Runbook**: `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/nodes.csv` -- 8 nodes across 2 zones (`us-east-1a`, `us-east-1b`) and 4 racks; six general-purpose nodes (12000 millicores, 49152 MiB) and two GPU nodes (8000 millicores, 32768 MiB, 4 GPUs each). Total cluster: 88000 millicores, 360448 MiB, 8 GPUs
 - `data/tenants.csv` -- 4 tenants (`tenant_alpha`, `tenant_beta`, `tenant_gamma`, `tenant_delta`)
 - `data/tenant_anti_affinity.csv` -- 2 anti-affine pairs (`tenant_alpha` x `tenant_beta`, `tenant_gamma` x `tenant_delta`)
@@ -72,6 +71,7 @@ The bundled CSVs are illustrative, fully synthetic demo data tuned so multiple I
 
 ### Tools
 - Python >= 3.10
+- RelationalAI Python SDK (`relationalai == 1.1.0`)
 
 ## Quickstart
 
@@ -106,7 +106,7 @@ The bundled CSVs are illustrative, fully synthetic demo data tuned so multiple I
    python pod_placement.py
    ```
 
-6. Expected output (the solver maximises the number of placed deployments; the specific (pod, node) tuples and per-node utilisation may vary across solver versions when multiple placements tie at the optimum). The script first prints the formulation (a few thousand lines for the bundled data, omitted here for brevity), then the solve-result block, then the per-node utilisation, the per-pod placement, and any unplaced deployments. A representative run looks like:
+6. Expected output (the solver maximizes the number of placed deployments; the specific (pod, node) tuples and per-node utilization may vary across solver versions when multiple placements tie at the optimum). The script first prints the formulation (a few thousand lines for the bundled data, omitted here for brevity), then the solve-result block, then the per-node utilization, the per-pod placement, and any unplaced deployments. A representative run looks like:
    ```text
    Solve result:
    • status: OPTIMAL
@@ -134,124 +134,95 @@ The bundled CSVs are illustrative, fully synthetic demo data tuned so multiple I
    (empty)
    ```
 
-   The optimum places all `12` deployments and binds **four** ICs at the chosen GPU node: rack-clique pins `ml_gamma_train`'s 4 pods onto a single rack, and CPU / memory / GPU bin-packing then pin them all to one node within that rack at exactly 100% utilisation on every resource (`gpu-b2-n1` here: 4 × 2000m = 8000m CPU = the node's CPU cap, 4 × 8192 MiB = 32768 MiB memory = the node's memory cap, 4 × 1 = 4 GPUs = the node's GPU cap -- a tight three-resource fit). The training group could equivalently land on `gpu-b1-n1` (same shape, other GPU rack) and the solver may tie-break either way across versions; what's solver-invariant is "all 4 pods on the same rack on a single node, 100% utilised on three resources". The `max_per_zone_override = 4` in `deployments.csv` is what unlocks this: without it, the default spread cap `ceil(4 / 2) = 2` plus the all-or-nothing gang rule plus the rack-clique requirement plus the GPU racks all sitting in `us-east-1b` (a rack belongs to exactly one zone, so all-pods-on-one-rack implies all-pods-in-one-zone) would make `ml_gamma_train` fully unplaced and the objective `11`. The override is the operator's explicit acceptance of a wider blast radius for the training group: a single-zone outage takes the whole training job, which is the standard tradeoff for an NVLink-tight ML deployment. The other bound counts that remain solver-invariant across the optimum: each multi-replica non-overridden deployment lands at exactly `ceil(replicas / 2)` pods per zone (the spread cap binds for `web_*` at 4+4, `api_*` at 2+2, `db_gamma` at 3+3), the affinity-paired caches (`cache_alpha`, `cache_delta`) co-locate on a single node, and alpha/beta and gamma/delta tenant pods partition the cluster into disjoint node sets.
+   The optimum places all `12` deployments and binds **four** ICs at the chosen GPU node: rack-clique pins `ml_gamma_train`'s 4 pods onto a single rack, and CPU / memory / GPU bin-packing then pin them all to one node within that rack at exactly 100% utilization on every resource (`gpu-b2-n1` here: 4 × 2000m = 8000m CPU = the node's CPU cap, 4 × 8192 MiB = 32768 MiB memory = the node's memory cap, 4 × 1 = 4 GPUs = the node's GPU cap -- a tight three-resource fit). The training group could equivalently land on `gpu-b1-n1` (same shape, other GPU rack) and the solver may tie-break either way across versions; what's solver-invariant is "all 4 pods on the same rack on a single node, 100% utilized on three resources". The `max_per_zone_override = 4` in `deployments.csv` is what unlocks this: without it, the default spread cap `ceil(4 / 2) = 2` plus the all-or-nothing gang rule plus the rack-clique requirement plus the GPU racks all sitting in `us-east-1b` (a rack belongs to exactly one zone, so all-pods-on-one-rack implies all-pods-in-one-zone) would make `ml_gamma_train` fully unplaced and the objective `11`. The override is the operator's explicit acceptance of a wider blast radius for the training group: a single-zone outage takes the whole training job, which is the standard tradeoff for an NVLink-tight ML deployment. The other bound counts that remain solver-invariant across the optimum: each multi-replica non-overridden deployment lands at exactly `ceil(replicas / 2)` pods per zone (the spread cap binds for `web_*` at 4+4, `api_*` at 2+2, `db_gamma` at 3+3), the affinity-paired caches (`cache_alpha`, `cache_delta`) co-locate on a single node, and alpha/beta and gamma/delta tenant pods partition the cluster into disjoint node sets.
 
 ## Template structure
+
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── pod_placement.py
-└── data/
-    ├── nodes.csv
-    ├── tenants.csv
-    ├── tenant_anti_affinity.csv
-    ├── deployments.csv
-    ├── deployment_affinity.csv
-    ├── pods.csv
-    └── distributed_training.csv
+pod_placement/
+  pod_placement.py              # Main script (concepts, decisions, constraints, solve, inspection)
+  data/
+    nodes.csv                   # 8 nodes across 2 zones and 4 racks
+    tenants.csv                 # 4 tenants
+    tenant_anti_affinity.csv    # 2 anti-affine tenant pairs
+    deployments.csv             # 12 deployments (with max_per_zone_override column)
+    deployment_affinity.csv     # 1 affinity-paired deployment pair
+    pods.csv                    # 50 pods with per-pod CPU / memory / GPU demands
+    distributed_training.csv    # 6 pairs forming the 4-pod NVLink clique
+  README.md                     # this file
+  runbook.md                    # analyst-facing paste-testable walkthrough
+  pyproject.toml                # dependencies
 ```
 
-## How it works
+**Start here**: run `python pod_placement.py` for the full formulation, solve, and post-solve inspection, or follow `runbook.md` to rebuild it step by step.
 
-The CSP picks a node for each pod via a binary 2D assignment matrix; everything else is plain relational arithmetic over that matrix. The script consists of these patterns:
+## Sample data
 
-**Binary 2D matrix as the primary decision.** Each pod gets one binary `x` per node, materialised as `Pod.on_node(Node, x)`. A per-pod cardinality IC pins the row sum to a 0/1 placement indicator:
+The bundled CSVs are illustrative demo data for one small cluster, tuned so several constraints bind at the optimum (see *What's included* for the exact shapes). Swap in your own cluster topology and workload to apply the template to a real cluster.
 
-```python
-Pod.on_node = model.Property(f"{Pod} runs on {Node} if {Integer:assigned}")
-Pod.placed = model.Property(f"{Pod} has {Integer:placed}")
+- **`nodes.csv`** (8 rows) — cluster compute hosts across 2 zones (`us-east-1a`, `us-east-1b`) and 4 racks; six general-purpose nodes and two GPU nodes.
+- **`tenants.csv`** (4 rows) — the tenants that own deployments.
+- **`tenant_anti_affinity.csv`** (2 rows) — tenant pairs that must never share a host; stored once per pair and closed symmetrically in the model.
+- **`deployments.csv`** (12 rows) — deployments across the four tenants, each with a replica count and a nullable `max_per_zone_override` spread cap.
+- **`deployment_affinity.csv`** (1 row) — a deployment pair that must co-locate on a single node.
+- **`pods.csv`** (50 rows) — pods with per-pod CPU / memory / GPU demands, each linked to a deployment.
+- **`distributed_training.csv`** (6 rows) — all `C(4, 2)` pod pairs of the 4-pod NVLink clique for `ml_gamma_train`; the rack-clique IC fires once per pair.
 
-x = Integer.ref()
-problem.solve_for(Pod.on_node(Node, x), type="bin", name=["x", Pod.id, Node.id])
-problem.solve_for(Pod.placed, type="bin", name=["placed", Pod.id])
+## Model overview
 
-placement_coupling_ic = model.where(Pod.on_node(Node, x)).require(
-    sum(x).per(Pod) == Pod.placed
-)
-```
+The script builds one semantic model from the CSVs, then layers the decision variables and constraints on top.
 
-An integer-valued `Pod.node_id` decision would read more naturally for the "different-node" pairwise pattern (`Pi.node_id != Pj.node_id`), but per-node aggregates would then force a `where(Pod.node_id == Node.id)`-shaped binding that mixes a decision variable with a data property -- the prescriptive rewriter does not lower that form today (the planogram template's `implies`-cascade table lookup is the canonical workaround). The 2D matrix sidesteps the rewriter limitation: every aggregate becomes a plain relational sum over `x`.
+- **Key entities**: `Node` — a compute host in the cluster, with its resource capacities and topology placement; `Pod` — a single workload replica to be placed on a node; `Deployment` — a group of replica pods owned by one tenant; `Tenant` — an account whose deployments may be anti-affine to another tenant's; `Zone` and `Rack` — failure-domain and NVLink-island concepts, with `Rack.zone` linking each rack to its containing zone.
+- **Primary identifiers**: integer `id` on `Node`, `Pod`, `Deployment`, `Tenant`; string `name` on `Zone` and `Rack` (both derived from the unique `zone` / `rack` columns of `nodes.csv`).
+- **Important invariants**: node capacities are positive; pod row counts per `deployment_id` equal that deployment's `replicas` (the gang IC pins them); each rack belongs to exactly one zone; `max_per_zone_override`, when present, is a positive integer no greater than the row's `replicas`.
 
-**Bin-packing is one `sum(... * x).per(Node)` per resource.** Three near-identical ICs, one for each of CPU / memory / GPU:
+For the full concept and property definitions — including the three symmetric data relationships (`TenantAntiAffinity`, `DeploymentAffinity`, `DistributedTraining`) — see `pod_placement.py`; `runbook.md` builds them step by step with the RAI skills.
 
-```python
-cpu_capacity_ic = model.where(Pod.on_node(Node, x)).require(
-    sum(Pod.cpu_millicores * x).per(Node) <= Node.cpu_millicores
-)
-```
+## How it works
+
+The CSP picks a node for each pod via a binary 2D assignment matrix; every other rule is plain relational arithmetic over that matrix, and the solver maximizes the number of placed deployments.
 
-**Pairwise anti-affinity is the CSP signature.** For every ordered pod-pair `(Pi, Pj)` whose deployments' tenants are anti-affine, at most one of `(Pi, Pj)` is on any given node:
-
-```python
-Pi = Pod
-Pj = Pod.ref()
-xi = Integer.ref()
-xj = Integer.ref()
-anti_affinity_ic = model.where(
-    Pi.id < Pj.id,
-    TenantAntiAffinity(Pi.deployment.tenant, Pj.deployment.tenant),
-    Pi.on_node(Node, xi),
-    Pj.on_node(Node, xj),
-).require(xi + xj <= 1)
+```text
+nodes + pods + deployments + affinity / anti-affinity / training relations → 2D on_node matrix + placement indicators → bin-packing / anti-affinity / affinity / spread / gang / rack-clique constraints → maximize placed deployments → solve → verify
 ```
 
-The ordered `Pi.id < Pj.id` filter canonicalises each pair so the IC fires once per `{Pi, Pj}` unordered pair. `TenantAntiAffinity` is closed symmetrically at definition time (the two `model.define` rules), so the predicate matches in either argument order. The same pairwise-pod / pairwise-node shape encodes the deployment co-location affinity IC (`xi == xj` on every node) and the topology rack-clique IC (`xa + xb <= 1` whenever the two pods are in a distributed-training group and the two nodes are in different racks).
+**A binary 2D matrix is the primary decision.** Each pod gets one binary variable per node (`Pod.on_node(Node, x)`), and a per-pod cardinality constraint pins each pod's row sum to a 0/1 placement indicator. An integer-valued node-id decision would read more naturally for the "different node" pairwise patterns, but per-node aggregates over it would mix a decision variable with a data property inside a `where` binding — a form the prescriptive rewriter doesn't lower today. The 2D matrix sidesteps that: every constraint becomes a plain relational sum over `x`.
 
-**Gang placement is a reified cardinality IC.** A deployment is either fully placed (`sum(Pod.placed).per(Deployment) == Deployment.replicas`) or fully unplaced (`sum(Pod.placed).per(Deployment) == 0`). The unified form uses a 0/1 deployment-level indicator:
+**Bin-packing is one aggregate per resource.** For CPU, memory, and GPU alike, the sum of pod demand times the assignment bit, per node, must stay within that node's capacity.
 
-```python
-Deployment.placed = model.Property(f"{Deployment} has {Integer:placed}")
-problem.solve_for(Deployment.placed, type="bin", name=["dep_placed", Deployment.id])
+**Pairwise rules are the CSP signature.** For every canonicalized pod pair whose tenants are anti-affine, at most one of the two may sit on any given node. The symmetric relations are closed in both argument orders at definition time so the predicate matches either way. The same pairwise-pod / pairwise-node shape encodes deployment co-location affinity (the two pods agree on every node's assignment bit) and the topology rack-clique rule (two training-group pods may not sit on nodes in different racks).
 
-gang_placement_ic = model.where(Pod.deployment == Deployment).require(
-    sum(Pod.placed).per(Deployment) == Deployment.replicas * Deployment.placed
-)
-```
+**Gang placement is a reified cardinality constraint.** A 0/1 deployment-level indicator forces every replica of a deployment to be placed together or not at all — the per-deployment placed-pod count equals `replicas × placed`, so a partial schedule is impossible. No big-M, no auxiliary indicator stack.
 
-`Deployment.placed == 0` forces every replica's `Pod.placed == 0` (sum == 0); `Deployment.placed == 1` forces every replica's `Pod.placed == 1` (sum == replicas). No big-M, no aux indicator stack.
+**Failure-domain spread is a two-key aggregate.** With `max_per_zone` precomputed (default `ceil(replicas / num_zones)`, or the row's `max_per_zone_override`), the count of a deployment's pods per zone must stay under its cap. The override is a per-deployment escape hatch: the bundled data uses it on the distributed-training job, whose rack-clique requirement forces all its pods onto one rack — and therefore one zone — which would otherwise collide with the default spread cap.
 
-**Failure-domain spread is a two-key `sum(x).per(Deployment, Zone)`.** With `max_per_zone` pre-computed (default `ceil(replicas / num_zones)`, or the `max_per_zone_override` value when set on the row) and joined onto `Deployment`, the IC reads as a plain relational inequality:
+Every constraint is pure relational arithmetic (no `implies` bodies), so `problem.verify()` re-evaluates all of them in the returned solution, and a post-solve assertion confirms the solver proved `OPTIMAL` rather than timing out.
 
-```python
-spread_ic = model.where(
-    Pod.on_node(Node, x),
-    Pod.deployment == Deployment,
-    Node.zone == Zone,
-).require(sum(x).per(Deployment, Zone) <= Deployment.max_per_zone)
-```
+For the exact PyRel formulation, see `pod_placement.py`; `runbook.md` reproduces the model step by step with the RAI skills.
 
-The override is a deployment-level escape hatch for cases where the default spread cap collides with another constraint -- the bundled data uses it on `ml_gamma_train` so the rack-clique IC (which forces all distributed-training pods onto a single rack, and therefore into a single zone) doesn't make the deployment infeasible.
+## Customize this template
 
-**All nine ICs are pure relational arithmetic.** None of them carry an `implies` body, so `problem.verify()` re-evaluates every constraint in the returned solution. The post-solve assertion `model.require(problem.termination_status() == "OPTIMAL")` then guarantees the solver actually proved optimality rather than timing out.
+### Use your own data
 
-## Customize this template
+- Replace the seven CSV files with your cluster topology and workload; the constraint structure does not change.
+- The data requirements are: primary keys must be unique across `nodes.csv` / `tenants.csv` / `deployments.csv` / `pods.csv`; every foreign key (`deployments.tenant_id`, `pods.deployment_id`, `tenant_anti_affinity.tenant_*`, and the like) must resolve; node capacities must be positive; `pods.csv` row counts per `deployment_id` must equal `deployments.csv`.`replicas` (the gang IC pins them); each rack belongs to exactly one zone; and any `max_per_zone_override` value, when present, must be a positive integer no greater than the row's `replicas`.
+
+### Tune parameters
+
+- **Tighten or loosen the spread cap.** The default `max_per_zone = ceil(replicas / num_zones)` is the loosest spread that still admits a placement when replicas fan out evenly across zones. For a strict 1-per-zone policy (so even a hot zone can't host two replicas of the same service), set `max_per_zone_override = 1` for that row in `deployments.csv`. For a deployment whose other ICs force same-zone placement (the bundled `ml_gamma_train` is the canonical example -- rack-clique plus all-GPU-racks-in-one-zone), set `max_per_zone_override = replicas` to opt out of spread for that deployment alone, leaving the cluster-wide default intact for everything else.
+- **Change the objective.** `problem.maximize(sum(Deployment.placed))` maximizes the number of placed deployments. Swap for `problem.maximize(sum(Deployment.replicas * Deployment.placed))` to weight by replica count, `problem.minimize(...)` over a per-node fragmentation cost (sum-of-squared-utilization-gaps), or pure satisfaction (`problem.satisfy()` with a `Deployment.placed == 1` hard floor) when every deployment must run.
+
+### Extend the model
 
-- **Use your own data** by replacing the seven CSV files with your cluster topology and workload. The constraint structure does not change. The data requirements are: primary keys must be unique across `nodes.csv` / `tenants.csv` / `deployments.csv` / `pods.csv`; every foreign key (`deployments.tenant_id`, `pods.deployment_id`, `tenant_anti_affinity.tenant_*`, etc.) must resolve; node capacities must be positive; `pods.csv` row counts per `deployment_id` must equal `deployments.csv`.`replicas` (the gang IC pins them); each rack belongs to exactly one zone; and any `max_per_zone_override` value, when present, must be a positive integer no greater than the row's `replicas`.
-- **Change the objective.** `problem.maximize(sum(Deployment.placed))` maximises the number of placed deployments. Swap for `problem.maximize(sum(Deployment.replicas * Deployment.placed))` to weight by replica count, `problem.minimize(...)` over a per-node fragmentation cost (sum-of-squared-utilisation-gaps), or pure satisfaction (`problem.satisfy()` with a `Deployment.placed == 1` hard floor) when every deployment must run.
 - **Tier-aware placement.** Mark pods with `gpu_units > 0` and add an IC forcing them onto GPU-capable nodes only -- e.g. `model.where(Pod.on_node(Node, 1), Pod.gpu_units >= 1).require(Node.gpu_units >= 1)` (matches the `model.where(...).require(...)` chaining used by every IC in `pod_placement.py`). Conversely, mark some nodes as "general-purpose only" and forbid GPU workloads there.
-- **Migration cost under churn.** Add a `Pod.current_node` data property reflecting the existing assignment, then introduce a per-pod "moved" indicator (`moved = (1 - Pod.on_node(current_node, x))`) and minimise the total move count -- multi-solution then enumerates the N least-disruptive placements.
+- **Migration cost under churn.** Add a `Pod.current_node` data property reflecting the existing assignment, then introduce a per-pod "moved" indicator (`moved = (1 - Pod.on_node(current_node, x))`) and minimize the total move count -- multi-solution then enumerates the N least-disruptive placements.
 - **NVLink-clique with explicit edges.** The bundled `data/distributed_training.csv` lists every pair in the training group, encoding rack-clique implicitly via the pairwise IC. To model a true edge-restricted clique (e.g. NVLink-2 connectivity between specific GPU pairs only), pre-compute the set of `(node_a, node_b)` pairs that lack a direct NVLink edge in Python and load them as a `NoNVLink` data relationship; then drop the `Na.rack != Nb.rack` clause from `rack_clique_ic` and replace it with `NoNVLink(Na, Nb)` to forbid co-placement on any pair of hosts without a direct NVLink path.
 - **Spot / preemptible tier.** Mark a subset of pods as preemptible (`Pod.is_preemptible == 1`) and let them displace lower-priority workloads when capacity is tight. Express as a per-node tiered capacity: preemptible pods consume "remaining" capacity, on-demand pods consume the primary allotment.
-- **Tighten or loosen the spread cap.** The default `max_per_zone = ceil(replicas / num_zones)` is the loosest spread that still admits a placement when replicas fan out evenly across zones. For a strict 1-per-zone policy (so even a hot zone can't host two replicas of the same service), set `max_per_zone_override = 1` for that row in `deployments.csv`. For a deployment whose other ICs force same-zone placement (the bundled `ml_gamma_train` is the canonical example -- rack-clique plus all-GPU-racks-in-one-zone), set `max_per_zone_override = replicas` to opt out of spread for that deployment alone, leaving the cluster-wide default intact for everything else.
-- **Multi-cluster (federated placement).** Add a `Cluster` concept above `Zone` and an outer `Pod.on_cluster(Cluster)` decision; spread / anti-affinity then have to lift to cluster-level constraints. Karmada-style multi-cluster placement is the standard precedent.
 
-## Learn more
+### Scale up / productionize
 
-**Production cluster managers** (the field this template models):
-- Verma et al., [*Large-scale cluster management at Google with Borg*](https://research.google/pubs/large-scale-cluster-management-at-google-with-borg/), EuroSys 2015. Constraint-driven cluster scheduling at scale; affinity / anti-affinity / failure-domain spread as first-class concepts.
-- Hindman et al., [*Mesos: A Platform for Fine-Grained Resource Sharing in the Data Center*](https://www.usenix.org/legacy/event/nsdi11/tech/full_papers/Hindman_new.pdf), NSDI 2011. Two-level resource scheduling -- the conceptual predecessor of every modern cluster manager.
-- [Volcano](https://volcano.sh/en/docs/), open-source batch scheduler for Kubernetes (CNCF incubating) with first-class gang-scheduling, queue fairness, and topology-aware placement.
-
-**Kubernetes scheduling surface** (the canonical vocabulary):
-- [Kubernetes scheduler framework: affinity & anti-affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). Official documentation of `nodeAffinity`, `podAffinity`, `podAntiAffinity`.
-- [Kubernetes topology-spread constraints](https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/). Failure-domain spread as a first-class Kubernetes API.
-- [Kueue documentation](https://kueue.sigs.k8s.io/docs/concepts/). Kubernetes-native queueing with placement constraints.
-- [Karmada multi-cluster placement](https://karmada.io/docs/userguide/scheduling/cluster-affinity/). Cluster-affinity scheduling for multi-cluster Kubernetes deployments.
-
-**Constraint-programming background** (the academic backbone for the encoding choices):
-- [CSPLib problem 057 -- RCPSP](https://www.csplib.org/Problems/prob057/). Resource-constrained project scheduling -- the closest classical CSP benchmark to multi-resource bin-packing with side constraints.
-- Mehta & van Beek, [*Mapping Problems with Side Constraints to SAT*](https://cs.uwaterloo.ca/~vanbeek/Publications/cp07.pdf), CP 2007. Academic precedent for mapping placement problems with pairwise / clique / cardinality side constraints to discrete satisfaction.
+- **Multi-cluster (federated placement).** Add a `Cluster` concept above `Zone` and an outer `Pod.on_cluster(Cluster)` decision; spread / anti-affinity then have to lift to cluster-level constraints. Karmada-style multi-cluster placement is the standard precedent.
+- The bundled cluster is small (8 nodes, 50 pods); the encoding scales to whatever the MiniZinc / Chuffed solver proves optimal within `time_limit_sec`. Raise the limit for larger clusters, or soften the post-solve `OPTIMAL` assertion (see *Troubleshooting*) to accept the best feasible placement found.
 
 ## Troubleshooting
 
@@ -327,3 +298,24 @@ The override is a deployment-level escape hatch for cases where the default spre
 - To model an N-pod training group, enumerate all `C(N, 2)` pairs in `distributed_training.csv`. Alternatively, pre-compute the transitive closure of the group graph in Python before passing it to `model.data(...)`.
 
 </details>
+
+## Learn more
+
+**Production cluster managers** (the field this template models):
+- Verma et al., [*Large-scale cluster management at Google with Borg*](https://research.google/pubs/large-scale-cluster-management-at-google-with-borg/), EuroSys 2015. Constraint-driven cluster scheduling at scale; affinity / anti-affinity / failure-domain spread as first-class concepts.
+- Hindman et al., [*Mesos: A Platform for Fine-Grained Resource Sharing in the Data Center*](https://www.usenix.org/legacy/event/nsdi11/tech/full_papers/Hindman_new.pdf), NSDI 2011. Two-level resource scheduling -- the conceptual predecessor of every modern cluster manager.
+- [Volcano](https://volcano.sh/en/docs/), open-source batch scheduler for Kubernetes (CNCF incubating) with first-class gang-scheduling, queue fairness, and topology-aware placement.
+
+**Kubernetes scheduling surface** (the canonical vocabulary):
+- [Kubernetes scheduler framework: affinity & anti-affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). Official documentation of `nodeAffinity`, `podAffinity`, `podAntiAffinity`.
+- [Kubernetes topology-spread constraints](https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/). Failure-domain spread as a first-class Kubernetes API.
+- [Kueue documentation](https://kueue.sigs.k8s.io/docs/concepts/). Kubernetes-native queueing with placement constraints.
+- [Karmada multi-cluster placement](https://karmada.io/docs/userguide/scheduling/cluster-affinity/). Cluster-affinity scheduling for multi-cluster Kubernetes deployments.
+
+**Constraint-programming background** (the academic backbone for the encoding choices):
+- [CSPLib problem 057 -- RCPSP](https://www.csplib.org/Problems/prob057/). Resource-constrained project scheduling -- the closest classical CSP benchmark to multi-resource bin-packing with side constraints.
+- Mehta & van Beek, [*Mapping Problems with Side Constraints to SAT*](https://cs.uwaterloo.ca/~vanbeek/Publications/cp07.pdf), CP 2007. Academic precedent for mapping placement problems with pairwise / clique / cardinality side constraints to discrete satisfaction.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/portfolio_balancing/README.md b/v1/portfolio_balancing/README.md
index 0a5c2844..61477ede 100644
--- a/v1/portfolio_balancing/README.md
+++ b/v1/portfolio_balancing/README.md
@@ -9,54 +9,19 @@ reasoning_types:
   - Rules-based
   - Graph
 tags:
-  - Quadratic Programming
-  - Risk Minimization
-  - Portfolio Optimization
-  - Multi-Objective
-  - Sensitivity Analysis
-  - Shadow Prices
-  - Scenario Analysis
-  - HiGHS
   - Multi-Reasoner
-  - Chained Reasoning
-  - Compliance
-  - Graph Analysis
+  - Portfolio Optimization
+  - Quadratic Programming
   - Community Detection
+  - Sensitivity Analysis
   - Stress Testing
 ---
 
-# Portfolio Balancing
-
 ## What this template is for
 
-Portfolio managers don't want to pay twice for the same exposure -- if two funds track nearly the same benchmark, owning both is one bet with worse bookkeeping. This template chains four reasoning stages on a single shared ontology to build compliant, risk-optimized portfolios across an 8-stock universe and stress-test them under a crisis regime.
-
-It uses RelationalAI's **rules**, **graph**, and **prescriptive** reasoners in a chained workflow:
-
-1. **Rules** scan the current book for compliance violations -- overconcentrated holdings (> 15% of balance), sector concentration (> 30%), and high-risk traders -- as derived Relationships.
-2. **Graph** builds a correlation graph from the covariance matrix, runs Louvain clustering, and picks the highest-Sharpe stock per cluster as the cluster's **representative**. 8 stocks collapse to 5 distinct bets; near-duplicates are dropped from the investable universe rather than capped within it.
-3. **Prescriptive optimization** solves a bi-objective Markowitz QP on the representative-only universe under position and sector caps, using the solver's shadow prices (constraint duals) to trace the efficient frontier efficiently across a `Scenario` Concept that combines three budgets and two regimes.
-4. **Crisis stress test** is the same `solve_epsilon` call -- no separate model -- but `Scenario.regime` picks a PSD-preserving shrinkage covariance, so base and crisis frontiers come out of one pipeline.
-
-Each stage writes derived properties the next reads directly: Rules define the thresholds Stage 3 enforces as constraints, Stage 2's `Stock.is_representative` shapes the decision space, and the stress test reads `Stock.regime_covar` keyed by `Scenario.regime`. See "How it works" for the full data flow.
+Portfolio managers don't want to pay twice for the same exposure -- if two funds track nearly the same benchmark, owning both is one bet with worse bookkeeping. Sector labels alone miss this: two tech funds can share a Technology label and still be near-duplicates, or two instruments from different sectors can co-move strongly enough that owning both is redundant. And a base-case optimization is optimistic -- under a crisis regime, correlations spike toward one and everything that hasn't been deduplicated hurts twice.
 
-## Why this problem matters
-
-The cost of paying twice for one exposure is concrete: allocating $4k to one fund and $5k to a near-identical one is functionally a single $9k bet with worse bookkeeping. Sector labels alone miss this: two tech ETFs can share a Technology label and still be near-duplicates, or two instruments from different sectors can co-move strongly enough that owning both is redundant. And base-case optimization is optimistic -- under crisis regimes (correlations spike toward 1), everything that hasn't been deduplicated hurts twice.
-
-The four-stage approach addresses each gap. Stage 1 surfaces existing violations in the current book (diagnostic). Stage 2 clusters by return covariance and picks the highest-Sharpe representative per cluster, collapsing redundant bets. Stage 3 optimizes over the representative-only universe under position and sector limits. Stage 4 re-solves under a PSD-preserving crisis covariance to stress the resulting portfolio.
-
-### Key design patterns demonstrated
-
-- **Shared compliance thresholds** -- `SECTOR_LIMIT` is defined once and enforced in both stages. `POSITION_LIMIT` (Stage 1 per-stock compliance) and `REP_POSITION_LIMIT` (Stage 3 per-representative cap) are deliberately different: a representative carries its cluster's combined exposure, so the construction-side cap is higher than the holdings-side compliance cap
-- **Graph results feed optimization** -- Louvain cluster ids and per-cluster argmax (highest Sharpe) both persist on `Stock`, and the optimizer's `Stock.is_non_representative()` constraint forces non-reps to zero (complement defined positively because the prescriptive rewriter doesn't accept `model.not_()` in a solver `.where()`)
-- **Collapse, don't cap** -- the graph stage reduces the investable universe to distinct bets rather than allowing all N stocks and capping within redundant groups
-- **Scenario Concept for parameter sweeps** -- `Scenario` entities combine budget ($500, $1,000, $2,000) and regime (base, crisis) so each epsilon solve handles all six combinations in one call
-- **Shadow-price-guided frontier** -- each `solve(sensitivity=True)` returns the return-constraint's dual (shadow price), which IS the frontier's local slope d(variance)/d(return). Three drivers (grid, adaptive, dichotomic) use that dual to place sample points; at equal solve budget the dual-guided drivers approximate the frontier far more tightly than blind even spacing
-- **Epsilon constraint method** -- `solve_epsilon(eps_rate)` minimizes variance subject to a return-target floor, producing one Pareto point per call without manually fixing return values
-- **PSD-preserving stress covariance** -- correlation shrinkage toward all-ones keeps the QP convex at every point, unlike naive off-diagonal scaling
-- **Quadratic programming via HiGHS** -- the risk objective is quadratic (`x' * Cov * x`); HiGHS solves the convex QP to a global optimum and, with `sensitivity=True`, returns the duals the frontier search relies on
-- **Anchor solves establish feasible range** -- Anchor 1 (minimize risk) and Anchor 2 (maximize return) bracket the return range before the frontier search
+This template builds compliant, risk-optimized portfolios that avoid that trap, then stress-tests them under a crisis regime, all on one shared ontology across an 8-stock universe. **It chains RelationalAI's rules, graph, and prescriptive reasoners: rules flag compliance violations in the current book, a covariance graph collapses near-duplicate bets via Louvain clustering, and a bi-objective Markowitz quadratic program (QP) traces the risk-return frontier using solver shadow prices — then re-solves the same model under a crisis covariance.** See *How it works* for the stage-by-stage data flow.
 
 ## Who this is for
 
@@ -64,6 +29,7 @@ The four-stage approach addresses each gap. Stage 1 surfaces existing violations
 - Data scientists learning quadratic programming with RelationalAI
 - Finance students studying the Markowitz efficient frontier
 - Anyone interested in risk-return trade-off analysis with scenario comparisons
+- **Assumed knowledge**: comfortable reading Python; the Markowitz, covariance, and optimization terms are explained as they come up. As a multi-reasoner template, it goes faster if you have followed a single-reasoner template first, but no deep RelationalAI experience is required to run it.
 
 ## What you'll build
 
@@ -79,6 +45,7 @@ The four-stage approach addresses each gap. Stage 1 surfaces existing violations
 ## What's included
 
 - `portfolio_balancing.py` -- Main script with all four stages: rules-based compliance, covariance clustering (Louvain), bi-objective QP with shadow-price-guided frontier tracing, and crisis-regime stress test
+- **Runbook**: `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/returns.csv` -- Stock universe: index, ticker, sector, expected returns (8 stocks)
 - `data/covar.csv` -- Covariance matrix entries (i, j, covariance value)
 - `data/users.csv` -- User profiles with risk scores
@@ -131,144 +98,67 @@ The four-stage approach addresses each gap. Stage 1 surfaces existing violations
    python portfolio_balancing.py
    ```
 
-6. Expected output (sample -- full output covers all four stages):
+6. Expected output. The script prints all four stages in turn; the tail of the run confirms a successful frontier trace and stress test. A few representative lines:
+
    ```text
-   ======================================================================
-   STAGE 1: COMPLIANCE ANALYSIS (rules)
-   ======================================================================
-
-   --- Rule 1: Overconcentrated Holdings (position > 15% of balance) ---
-     holding_id=1, ticker=AAPL, account_id=1, value=18000.00, balance=100000.00, pct=18.0%
-     ...
-   --- Rule 2: Sector Concentration (sector > 30% of balance) ---
-     account_id=1, sector=Technology, sector_value=34000.00, pct=34.0%
-     ...
-   --- Rule 3: High Risk Traders (risk_score > 0.8 AND >5 flagged txns) ---
-     user_id=1, name=Alice Chen, risk_score=0.85
-     ...
-
-   ======================================================================
    STAGE 2: GRAPH -- Covariance Clustering (Louvain)
-   ======================================================================
-     Correlation graph: 4 edges (|correlation| >= 0.3)
      Louvain communities: 5 cluster(s)
-       Cluster 1 (size 3): AAPL (Technology), MSFT (Technology), GOOGL (Technology)
-       Cluster 2 (size 2): JNJ (Healthcare), PFE (Healthcare)
-       Cluster 3 (size 1): XOM (Energy)
-       Cluster 4 (size 1): PG (Consumer Staples)
-       Cluster 5 (size 1): JPM (Financials)
-
-     Avg correlation: intra-cluster = +0.683, inter-cluster = +0.131
-
-     Cluster representatives (5 of 8 stocks, picked by highest Sharpe):
-       Cluster 1: GOOGL (Technology) -- Sharpe = 0.605
-       Cluster 2: PFE (Healthcare) -- Sharpe = 0.530
-       Cluster 3: XOM (Energy) -- Sharpe = 0.588
-       Cluster 4: PG (Consumer Staples) -- Sharpe = 0.444
-       Cluster 5: JPM (Financials) -- Sharpe = 0.500
-
-   ======================================================================
-   STAGE 3: BI-OBJECTIVE OPTIMIZATION
-   (position + sector limits on representative universe; base & crisis regimes)
-   ======================================================================
-
-   ANCHOR SOLVE 1: Minimize risk (no return constraint)
-   Status: OPTIMAL
-     base_500:    return = 32.4336, risk =   1160.3926
-     base_1000:   return = 64.8673, risk =   4641.5705
-     base_2000:   return = 129.7346, risk =  18566.2819
-     crisis_500:  return = 31.6873, risk =   1913.5995
-     crisis_1000: return = 63.3745, risk =   7654.3981
-     crisis_2000: return = 126.7490, risk =  30617.5925
-
-   ANCHOR SOLVE 2: Maximize return (swap objective)
-   Status: OPTIMAL
-     base_500:    return = 42.0000
-     base_1000:   return = 84.0000
-     base_2000:   return = 168.0000
-     crisis_500:  return = 42.0000
-     crisis_1000: return = 84.0000
-     crisis_2000: return = 168.0000
-
-   Reference scenario 'base_1000': frontier spans expected return [64.8673, 84.0000]
-
-   ======================================================================
-   SENSITIVITY-GUIDED FRONTIER  (reference 'base_1000', 6-solve budget per method)
-   ======================================================================
-     running grid driver ...
-     running adaptive driver ...
-     running dichotomic driver ...
+     Cluster representatives (5 of 8 stocks, picked by highest Sharpe): ...
 
-   Frontier approximation quality (same solve budget, lower gap = better):
+   SENSITIVITY-GUIDED FRONTIER  (reference 'base_1000', 6-solve budget per method)
      method        solves     max chord-gap
-     --------------------------------------
      grid               6          557.9250
      adaptive           6          415.1730
      dichotomic         6          202.2972  <- tightest
 
-   Shadow price = frontier slope (exact dual vs finite-difference secant):
-     (dual = extra variance incurred per unit of additional required return)
-         return      variance   dual (lambda)        secant
-     ------------------------------------------------------
-        64.8673     4641.5705            0.00            --
-        71.2734     5181.9733          134.83         84.36
-        75.9396     5946.0980          192.68        163.75
-        80.4605     6944.2401          250.64        220.79
-        83.1779     7809.1748          650.79        318.29
-        84.0000     8528.0000         1098.00        874.39
-
-   ======================================================================
    STAGE 4: CRISIS REGIME STRESS TEST
-   (PSD-preserving correlation shrinkage, alpha = 0.7)
-   ======================================================================
-
-   EFFICIENT FRONTIER: Risk vs Return (per scenario, exact dual marginals)
-
-     base_1000 (budget=1000, regime=base):
-       #     Label     Return         Risk    Marginal   Knee
-     --------------------------------------------------------
-       1  min_risk      64.87    4641.5705        0.00
-       2        p1      71.27    5181.9733      134.83
-       3        p2      75.94    5946.0980      192.68
-       4        p3      80.46    6944.2401      250.64  <--
-       5        p4      83.18    7809.1748      650.79
-       6        p5      84.00    8528.0000     1098.00
-
-     (similar tables for base_500, base_2000, crisis_500, crisis_1000, crisis_2000)
-
-     Volatility (sqrt risk) -- base vs crisis at each frontier point:
-
-     Budget 1000:
-         Label     vol_base   vol_crisis        gap    gap_%
-     -------------------------------------------------------
-      min_risk      68.1291      87.4894   +19.3603   +28.4%
-            p1      71.9859      93.2657   +21.2798   +29.6%
-            p2      77.1109      98.5270   +21.4161   +27.8%
-            p3      83.3321     104.3961   +21.0640   +25.3%
-            p4      88.3695     109.1925   +20.8230   +23.6%
-            p5      92.3472     112.3478   +20.0006   +21.7%
-
-     (similar tables for Budget 500 and Budget 2000, identical gap_% pattern)
+     Crisis volatility ~22-30% above base at every frontier point.
    ```
 
-   Crisis volatility sits ~22-30% above base at every frontier point and the gap peaks in the middle of the frontier (p1 at +29.6%), not at the concentrated end (p5 at +21.7%). That inversion is the payoff of the representative-only universe: at the concentrated end the optimizer is picking the highest-Sharpe distinct bet per cluster, which incidentally sits in sectors with lower crisis correlations (Energy, Consumer Staples). Without the representative collapse, the concentrated end would stack near-duplicates and see the crisis gap grow, not shrink.
+   Crisis volatility sits ~22-30% above base at every frontier point and the gap peaks in the middle of the frontier, not at the concentrated end. That inversion is the payoff of the representative-only universe: at the concentrated end the optimizer picks the highest-Sharpe distinct bet per cluster, which sits in sectors with lower crisis correlations (Energy, Consumer Staples). The full stage-by-stage printout and a step-by-step walkthrough are in `runbook.md`.
 
 ## Template structure
 
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── portfolio_balancing.py
-└── data/
-    ├── returns.csv
-    ├── covar.csv
-    ├── users.csv
-    ├── accounts.csv
-    ├── holdings.csv
-    └── transactions.csv
+portfolio_balancing/
+  portfolio_balancing.py    # Main script (4 chained stages: rules, graph, QP, stress test)
+  data/
+    returns.csv             # 8-stock universe: index, ticker, sector, expected returns
+    covar.csv               # covariance matrix entries (i, j, covar)
+    users.csv               # user profiles with risk scores
+    accounts.csv            # account balances
+    holdings.csv            # current holdings per account and stock
+    transactions.csv        # transaction history with flagged-transaction indicators
+  README.md                 # this file
+  runbook.md                # analyst-facing paste-testable walkthrough
+  pyproject.toml            # dependencies
 ```
 
+**Start here**: run `python portfolio_balancing.py` for the full four-stage chain end to end, or follow `runbook.md` to rebuild it step by step.
+
+## Sample data
+
+The bundled CSVs are illustrative demo data over a compact 8-stock universe, sized so the covariance clustering, frontier trace, and crisis stress test all produce a readable, interpretable result. Swap in your own universe and book to apply the template to a real portfolio.
+
+- **`returns.csv`** (8 rows) — the stock universe: an integer `index`, `ticker`, `sector`, and expected `returns`.
+- **`covar.csv`** — one row per `(i, j)` covariance-matrix entry; must be symmetric (`covar(i, j) == covar(j, i)`) and cover every pair.
+- **`users.csv`** — user profiles with a `risk_score`.
+- **`accounts.csv`** — account balances, each linked to a user.
+- **`holdings.csv`** — current holdings per account and stock, with quantity and purchase price.
+- **`transactions.csv`** — transaction history with an `is_flagged` indicator used by the high-risk-trader rule.
+
+## Model overview
+
+One shared ontology threads all four stages. Each stage reads properties earlier stages wrote and writes new ones for downstream stages.
+
+- **Key entities**: `Stock`, `Sector`, `User`, `Account`, `Holding`, `Transaction`; plus the derived `Regime`, `Scenario`, and `FrontierPoint` concepts the optimization stages build.
+- **Primary identifiers**: integer `index` on `Stock`; integer ids on `User`, `Account`, `Holding`, `Transaction`; string `sector_name` on `Sector`, `regime_name` on `Regime`, `name` on `Scenario`; composite key (`scenario_label` + `eps_label`) on `FrontierPoint`.
+- **Important invariants**: the covariance matrix is symmetric and positive semi-definite; expected returns and balances are per-row data; `Stock.correlation` and `Stock.regime_covar` are derived in PyRel from the base covariance; non-representative stocks are forced to zero allocation at solve time.
+
+The derived concepts the optimization stages build are `Regime` (`base` / `crisis`), `Scenario` (a `(budget, regime)` tuple — three budgets × two regimes give six tuples so one epsilon solve prices every combination at once), and `FrontierPoint` (a materialized Pareto point with return, risk, marginal, and knee flag).
+
+For the full concept and property definitions — including every property each stage writes onto `Stock` — see `portfolio_balancing.py`; `runbook.md` builds them step by step with the RAI skills.
+
 ## How it works
 
 This section walks through the highlights in `portfolio_balancing.py`.
@@ -297,242 +187,27 @@ Each stage writes derived properties the next reads directly. Stage 1's threshol
 
 ### Stage 1: Rules-based compliance analysis
 
-The first stage defines compliance flags as RAI derived properties and Relationships. The model loads portfolio data (users, accounts, holdings, transactions) alongside the stock universe, then evaluates three rules using two configurable thresholds:
-
-```python
-POSITION_LIMIT = 0.15   # max fraction of budget per stock
-SECTOR_LIMIT = 0.30     # max fraction of budget per sector
-```
-
-**Rule 1 -- Overconcentrated holdings**: a holding whose value exceeds `POSITION_LIMIT` of the account balance. The holding value is a derived property:
+The first stage defines compliance flags as RAI derived properties and Relationships. The model loads portfolio data (users, accounts, holdings, transactions) alongside the stock universe, then evaluates three rules using two configurable thresholds — `POSITION_LIMIT` (max fraction of budget per stock, default 0.15) and `SECTOR_LIMIT` (max fraction per sector, default 0.30):
 
-```python
-Holding.value = model.Property(f"{Holding} has value {Float:holding_value}")
-model.define(Holding.value(Holding.quantity * Holding.purchase_price))
-
-Holding.is_overconcentrated = model.Relationship(f"{Holding} is overconcentrated")
-AccountR1 = Account.ref()
-model.where(
-    Holding.account(AccountR1),
-    Holding.value > POSITION_LIMIT * AccountR1.balance,
-).define(Holding.is_overconcentrated())
-```
-
-**Rule 2 -- Sector concentration**: total holdings in a sector exceeding `SECTOR_LIMIT` of the account balance. Uses aggregation to sum holding values per (account, sector):
-
-```python
-sector_exposure = sum(HoldingSC.value).where(
-    HoldingSC.account(AccountSC),
-    HoldingSC.stock(StockSC),
-    StockSC.sector_ref(SectorSC),
-).per(AccountSC, SectorSC)
-
-model.where(
-    Holding.account(AccountSC),
-    Holding.stock(StockR2),
-    StockR2.sector_ref(SectorSC),
-    sector_exposure > SECTOR_LIMIT * AccountSC.balance,
-).define(Holding.is_sector_concentrated())
-```
-
-**Rule 3 -- High-risk traders**: users with `risk_score > 0.8` and more than 5 flagged transactions. Flagged transaction count is computed via aggregation:
-
-```python
-flagged_count = sum(TransactionHR.is_flagged_val).where(
-    TransactionHR.user(User),
-).per(User)
-
-model.where(
-    User.risk_score > 0.8,
-    flagged_count > 5,
-).define(User.is_high_risk_trader())
-```
+- **Rule 1 — Overconcentrated holdings**: flag any holding whose value (a derived `quantity × purchase_price`) exceeds `POSITION_LIMIT` of its account balance.
+- **Rule 2 — Sector concentration**: sum holding values per (account, sector) and flag every holding in a sector whose total exceeds `SECTOR_LIMIT` of the account balance.
+- **Rule 3 — High-risk traders**: flag users with `risk_score > 0.8` and more than 5 flagged transactions (the flagged count is an aggregation per user).
 
 ### Stage 2: Graph -- covariance clustering
 
-Volatility and correlation are derived in PyRel from the base covariance, so the ontology is the single source of truth for every similarity metric. `Stock.variance` picks the covariance diagonal, `Stock.volatility` applies `sqrt(variance)` via `relationalai.semantics.std.math.sqrt`, and `Stock.correlation(i, j) = covar(i, j) / (vol_i * vol_j)`:
-
-```python
-Stock.volatility = model.Property(f"{Stock} has {Float:stock_volatility}")
-model.define(Stock.volatility(sqrt(Stock.variance)))
-
-Stock.correlation = model.Property(
-    f"{Stock} and {Stock} have correlation {Float:stock_correlation}"
-)
-PairedStockCorr = Stock.ref()
-cov_ij_ref = Float.ref()
-model.where(
-    Stock.covar(PairedStockCorr, cov_ij_ref),
-).define(
-    Stock.correlation(
-        PairedStockCorr,
-        cov_ij_ref / (Stock.volatility * PairedStockCorr.volatility),
-    )
-)
-```
-
-The `Graph` reasoner builds an undirected graph with `Stock` as the node concept. Edges are filtered in PyRel directly against the derived correlation property -- no upstream edge list required:
-
-```python
-corr_graph = Graph(
-    model,
-    directed=False,
-    weighted=False,
-    node_concept=Stock,
-    aggregator="sum",
-)
-
-stock_i_ref = Stock.ref()
-stock_j_ref = Stock.ref()
-corr_ref = Float.ref()
-model.define(corr_graph.Edge.new(src=stock_i_ref, dst=stock_j_ref)).where(
-    stock_i_ref.correlation(stock_j_ref, corr_ref),
-    stock_i_ref.index < stock_j_ref.index,
-    math_abs(corr_ref) >= CORR_THRESHOLD,
-)
-```
-
-Louvain community detection runs directly on the graph and returns (node, cluster_id) pairs. The cluster id is persisted as a `Stock` property so downstream stages can consume it:
-
-```python
-community = corr_graph.louvain()
-cluster_label = Integer.ref("cluster_label")
-Stock.cluster = model.Property(f"{Stock} in cluster {Integer:cluster_id}")
-stock_clust_ref = Stock.ref()
-model.define(stock_clust_ref.cluster(cluster_label)).where(
-    community(stock_clust_ref, cluster_label)
-)
-```
+Volatility and correlation are derived in PyRel from the base covariance, so the ontology is the single source of truth for every similarity metric: `variance` is the covariance diagonal, `volatility` is its square root, and `correlation(i, j) = covar(i, j) / (vol_i · vol_j)`. The graph reasoner then builds an undirected graph over `Stock`, with edges filtered directly against the derived correlation — an edge exists between two stocks whose absolute correlation clears `CORR_THRESHOLD`, so no upstream edge list is needed.
 
-The script reports cluster sizes and intra- vs inter-cluster average correlation as a sanity check that the clustering separates co-moving stocks from independent ones.
-
-After clustering, Stage 2 picks one representative per cluster -- the stock with the highest Sharpe ratio -- using per-group argmax in PyRel. Only the representatives will be eligible for allocation in Stage 3:
-
-```python
-Stock.sharpe = model.Property(f"{Stock} has Sharpe {Float:stock_sharpe}")
-model.define(Stock.sharpe(Stock.returns / Stock.volatility))
-
-peer_for_max = Stock.ref()
-Stock.cluster_max_sharpe = model.Property(
-    f"{Stock} has cluster max Sharpe {Float:cluster_max_sharpe}"
-)
-model.define(
-    Stock.cluster_max_sharpe(
-        aggs.max(peer_for_max.sharpe)
-        .where(peer_for_max.cluster == Stock.cluster)
-        .per(Stock)
-    )
-)
-
-Stock.is_representative = model.Relationship(f"{Stock} is cluster representative")
-model.where(Stock.sharpe == Stock.cluster_max_sharpe).define(
-    Stock.is_representative()
-)
-```
+Louvain community detection runs on that graph and the resulting cluster id is persisted as a `Stock` property. The script reports cluster sizes and intra- vs inter-cluster average correlation as a sanity check that co-moving stocks group together. Finally, Stage 2 picks one representative per cluster — the highest-Sharpe stock (`returns / volatility`), via per-group argmax — and only those representatives are eligible for allocation in Stage 3. Singletons are their own representative.
 
 ### Stage 3: Bi-objective optimization
 
-#### Scenario concept and decision variables
-
-The `Stock` concept (defined earlier for all stages) carries ticker, sector, expected returns, and the base covariance matrix. Stage 2 added `Stock.variance`, `Stock.volatility`, `Stock.correlation`, `Stock.cluster`, `Stock.sharpe`, `Stock.cluster_max_sharpe`, `Stock.is_representative`, and `Stock.is_non_representative` on top. Stage 3 consumes the representative flag via its compliance constraints, and adds budget-and-regime scenarios, regime-conditioned covariance, and decision variables.
-
-Scenarios combine budget and regime so each epsilon solve handles all six (budget, regime) combinations simultaneously:
-
-```python
-Regime = model.Concept("Regime", identify_by={"regime_name": String})
-model.define(Regime.new(regime_name="base"))
-model.define(Regime.new(regime_name="crisis"))
-
-Scenario = model.Concept("Scenario", identify_by={"name": String})
-Scenario.budget = model.Property(f"{Scenario} has {Float:budget}")
-Scenario.regime = model.Property(f"{Scenario} in {Regime}")
-scenario_data = model.data(
-    [
-        ("base_500", 500, "base"),
-        ("base_1000", 1000, "base"),
-        ("base_2000", 2000, "base"),
-        ("crisis_500", 500, "crisis"),
-        ("crisis_1000", 1000, "crisis"),
-        ("crisis_2000", 2000, "crisis"),
-    ],
-    columns=["name", "budget", "regime"],
-)
-model.define(
-    s := Scenario.new(name=scenario_data["name"]),
-    s.budget(scenario_data["budget"]),
-)
-# Link Scenario to Regime by matching the regime name from the data.
-scenario_link_ref = Scenario.ref()
-regime_link_ref = Regime.ref()
-model.where(
-    scenario_link_ref.name == scenario_data["name"],
-    regime_link_ref.regime_name == scenario_data["regime"],
-).define(scenario_link_ref.regime(regime_link_ref))
-```
-
-#### Define decision variables, constraints, and objective
-
-Each stock gets a continuous quantity variable indexed by Scenario (multi-argument Property).
-
-```python
-Stock.x_quantity = model.Property(f"{Stock} in {Scenario} has {Float:quantity}")
-x_qty = Float.ref()
-```
-
-Two concentration limits plus a representative-only filter are added via `_add_compliance_constraints`. Position and sector caps behave as before; the `Stock.is_non_representative()` relation forces every non-representative stock to zero allocation, which is how the graph stage's redundancy removal shows up at solve time. The complement is defined positively because the prescriptive rewriter can't accept `model.not_(...)` inside a solver constraint:
-
-```python
-def _add_compliance_constraints(problem):
-    # Position limit: each representative <= REP_POSITION_LIMIT * budget.
-    problem.satisfy(model.where(
-        Stock.x_quantity(Scenario, x_qty),
-    ).require(x_qty <= REP_POSITION_LIMIT * Scenario.budget))
-
-    # Sector limit: total allocation to stocks in same sector <= SECTOR_LIMIT * budget.
-    sector_alloc = sum(x_qty).where(
-        Stock.x_quantity(Scenario, x_qty),
-        Stock.sector == s_sector_ref.sector,
-    ).per(Scenario, s_sector_ref.sector)
-    problem.satisfy(model.where(
-        Stock.x_quantity(Scenario, x_qty),
-    ).require(sector_alloc <= SECTOR_LIMIT * Scenario.budget))
-
-    # Representative-only: non-representative stocks forced to zero.
-    problem.satisfy(model.where(
-        Stock.x_quantity(Scenario, x_qty),
-        Stock.is_non_representative(),
-    ).require(x_qty == 0))
-```
-
-The risk objective is quadratic in the decision variables and uses the regime-conditioned covariance: each Scenario picks its matching regime's covariance, so base and crisis scenarios solve against different covariances in the same call.
-
-```python
-problem.minimize(
-    sum(regime_cov_val * x_qty * x_qty_paired)
-    .where(
-        Stock.regime_covar(PairedStock, Scenario.regime, regime_cov_val),
-        Stock.x_quantity(Scenario, x_qty),
-        PairedStock.x_quantity(Scenario, x_qty_paired),
-    )
-)
-```
-
-#### Solve anchors, then trace the frontier with shadow prices
-
-Two anchor solves establish the feasible return range. Anchor 1 minimizes risk with no return constraint; Anchor 2 maximizes return. The span is measured on a single reference scenario (`base_1000`).
-
-```python
-result1 = solve_epsilon(eps_rate=None)   # min-risk anchor
-```
+**Scenarios and decision variables.** Stage 3 consumes the representative flag from Stage 2 and adds budget-and-regime scenarios, regime-conditioned covariance, and the decision variables. A `Scenario` combines a budget and a regime, so the six `(budget, regime)` tuples are all priced in one epsilon solve. Each stock carries a continuous quantity variable indexed by `Scenario`.
 
-Each interior solve minimizes variance subject to a return-target floor and requests sensitivity information, so HiGHS returns the return constraint's **dual** -- the shadow price. By the envelope theorem that dual is exactly the frontier's local slope d(variance)/d(return), so one solve yields both a Pareto point and the slope there, with no finite differencing.
+**Constraints.** Three constraints shape the allocation: a position cap (each representative ≤ `REP_POSITION_LIMIT` of budget), a sector cap (total allocation per sector ≤ `SECTOR_LIMIT` of budget), and a representative-only filter that forces every non-representative stock to zero — this is how the graph stage's redundancy removal shows up at solve time. The complement (`is_non_representative`) is defined positively because the prescriptive rewriter can't accept a negation inside a solver constraint.
 
-```python
-problem.solve("highs", time_limit_sec=60, sensitivity=True)
-# shadow_price = dual of the return-floor constraint = d(variance)/d(return)
-```
+**Objective.** The risk objective is quadratic in the decision variables and uses the regime-conditioned covariance, so each scenario solves against its own regime's covariance in the same call.
 
-Sign convention: minimizing variance subject to `return >= target`, the dual is non-negative with units of variance per unit return, and it rises monotonically along the frontier (variance gets more expensive as you demand more return).
+**Anchors, then shadow-price-guided frontier tracing.** Two anchor solves bracket the feasible return range (min-risk with no return floor, then max-return), measured on the reference scenario `base_1000`. Each interior solve then minimizes variance subject to a return-target floor and requests sensitivity, so HiGHS returns the return constraint's **dual** — the shadow price. By the envelope theorem that dual is exactly the frontier's local slope d(variance)/d(return), so one solve yields both a Pareto point and its slope with no finite differencing. The dual is non-negative (variance per unit return) and rises monotonically along the frontier as return gets more expensive.
 
 Three drivers spend the same solve budget differently and are compared head-to-head:
 
@@ -542,55 +217,42 @@ Three drivers spend the same solve budget differently and are compared head-to-h
 
 Quality is scored by **max chord-gap**: the largest variance error of linearly interpolating between solved points. At equal 6-solve budget the dual-guided drivers win decisively (dichotomic 202 vs grid 558), because the duals tell the search where the frontier curves most.
 
-#### Pareto analysis output
-
-The script prints the three-driver quality comparison, the shadow-price-vs-secant table (each exact dual next to the finite-difference slope it brackets), the efficient frontier per (budget, regime) scenario, and programmatic knee detection at the last point before the exact dual's largest ratio jump (where diminishing returns accelerate, not where the absolute dual is highest). The dichotomic frontier is materialized as the `FrontierPoint` Concept, with integrity constraints asserting that neither return nor risk decreases along it -- a relational statement of Pareto-efficiency.
+**Pareto analysis output.** The script prints the three-driver quality comparison, the shadow-price-vs-secant table (each exact dual next to the finite-difference slope it brackets), the efficient frontier per (budget, regime) scenario, and programmatic knee detection at the last point before the exact dual's largest ratio jump (where diminishing returns accelerate, not where the absolute dual is highest). The dichotomic frontier is materialized as the `FrontierPoint` Concept, with integrity constraints asserting that neither return nor risk decreases along it -- a relational statement of Pareto-efficiency.
 
 ### Stage 4: Crisis regime stress test
 
-Crisis covariance is derived in PyRel via PSD-preserving correlation shrinkage, keyed by a `Regime` concept. The shrinkage formula `rho_crisis = alpha * rho + (1 - alpha) * J` re-expressed in covariance units becomes `cov_crisis(i, j) = alpha * cov(i, j) + (1 - alpha) * vol_i * vol_j` -- a convex combination of PSD matrices, so PSD is preserved by construction:
-
-```python
-Stock.regime_covar = model.Property(
-    f"{Stock} and {Stock} in {Regime} have {Float:regime_covar}"
-)
-
-# Base regime: covariance unchanged.
-model.where(
-    Stock.covar(PairedStockBase, base_cov_ref),
-    base_regime_ref.regime_name == "base",
-).define(Stock.regime_covar(PairedStockBase, base_regime_ref, base_cov_ref))
-
-# Crisis regime: convex combination of base covariance and vol_i * vol_j.
-model.where(
-    Stock.covar(PairedStockCrisis, crisis_cov_ref),
-    crisis_regime_ref.regime_name == "crisis",
-).define(
-    Stock.regime_covar(
-        PairedStockCrisis,
-        crisis_regime_ref,
-        CRISIS_ALPHA * crisis_cov_ref
-        + (1 - CRISIS_ALPHA) * Stock.volatility * PairedStockCrisis.volatility,
-    )
-)
-```
-
-Both regimes live on the same `Stock.regime_covar` property, keyed by the `Regime` concept, so Stage 3's objective can select the right covariance per scenario without branching:
+Crisis covariance is derived in PyRel via PSD-preserving correlation shrinkage, keyed by the `Regime` concept. The shrinkage formula `rho_crisis = alpha · rho + (1 - alpha) · J`, re-expressed in covariance units, becomes `cov_crisis(i, j) = alpha · cov(i, j) + (1 - alpha) · vol_i · vol_j` — a convex combination of PSD matrices, so positive semi-definiteness is preserved by construction. The base regime leaves covariance unchanged. Both regimes live on the same `regime_covar` property keyed by `Regime`, so Stage 3's objective selects the right covariance per scenario without branching.
 
 After the Stage 3 frontier is traced, Stage 4 emits a side-by-side comparison of base and crisis volatility (`sqrt(risk)`) at each frontier point, grouped by budget. Crisis volatility is consistently ~22-30% higher than base. The gap peaks in the middle of the frontier (p1 at +29.6%) and narrows toward the concentrated end (p5 at +21.7%). That shape is the payoff of the representative-only universe: at the concentrated end the optimizer is picking the highest-Sharpe distinct bet per cluster (Energy and Consumer Staples in this dataset), which happen to have lower crisis correlations than the middle of the frontier. Without the representative collapse, the concentrated end would stack near-duplicates and the crisis gap would grow instead of shrink.
 
+For the exact PyRel formulation of all four stages, see `portfolio_balancing.py`; `runbook.md` reproduces them step by step with the RAI skills.
+
 ## Customize this template
 
+### Use your own data
+
+- Replace the six CSV files with your own universe and book; the four-stage structure does not change.
+- **Add more stocks**: extend `returns.csv` and `covar.csv` with additional assets and their covariance entries. Keep the covariance matrix symmetric (`covar(i, j) == covar(j, i)`) and complete over every pair.
+
+### Tune parameters
+
 - **Adjust compliance thresholds**: `POSITION_LIMIT` (default 0.15) applies in Stage 1 compliance rules (per-stock holdings). `REP_POSITION_LIMIT` (default 0.30) applies in Stage 3 optimization (per-representative allocation, which carries its cluster's combined exposure). `SECTOR_LIMIT` (default 0.30) applies to both. Note that `REP_POSITION_LIMIT` must satisfy `REP_POSITION_LIMIT * num_representatives >= 1.0` or the fully-invested constraint becomes infeasible.
-- **Tune the correlation graph**: Raise or lower `CORR_THRESHOLD` (default 0.3) to control graph sparsity. Higher thresholds produce fewer edges and more singleton clusters; lower thresholds produce a denser graph and fewer, larger clusters.
+- **Tune the correlation graph**: raise or lower `CORR_THRESHOLD` (default 0.3) to control graph sparsity. Higher thresholds produce fewer edges and more singleton clusters; lower thresholds produce a denser graph and fewer, larger clusters.
+- **Adjust crisis severity**: lower `CRISIS_ALPHA` (default 0.7) shrinks correlations harder toward all-ones (more severe crisis). `alpha = 1.0` is no crisis (base); `alpha = 0.0` is maximum crisis (all correlations = 1). Values between 0.5 and 0.9 give interesting comparisons while keeping the QP well-conditioned.
+- **Adjust frontier resolution**: increase `N_SOLVES` for a finer-grained frontier. Because the three drivers share a solve cache, the total number of unique solves stays close to `N_SOLVES` rather than 3x.
+
+### Extend the model
+
 - **Change the representative picking rule**: Stage 2 picks the highest-Sharpe stock per cluster. To pick differently, change the `Stock.cluster_max_sharpe` derivation -- e.g., replace `Stock.sharpe` with `Stock.returns` (highest return), `-Stock.volatility` (lowest vol), or a weighted blend. Singletons are always their own representative regardless of rule.
-- **Adjust crisis severity**: Lower `CRISIS_ALPHA` (default 0.7) shrinks correlations harder toward all-ones (more severe crisis). `alpha = 1.0` is no crisis (base); `alpha = 0.0` is maximum crisis (all correlations = 1). Values between 0.5 and 0.9 give interesting comparisons while keeping the QP well-conditioned.
-- **Add more stocks**: Extend `returns.csv` and `covar.csv` with additional assets and their covariance entries.
-- **Add compliance rules**: Define additional Relationships in the rules stage (e.g., minimum holding period, transaction velocity limits).
-- **Allow short selling**: Remove the non-negativity constraint to allow negative holdings.
-- **Adjust frontier resolution**: Increase `N_SOLVES` for a finer-grained frontier. Because the three drivers share a solve cache, the total number of unique solves stays close to `N_SOLVES` rather than 3x.
-- **Maximize return for given risk**: Flip the formulation to maximize expected return subject to a risk budget.
-- **Transaction costs**: Add a linear or quadratic penalty term for rebalancing from an existing portfolio.
+- **Add compliance rules**: define additional Relationships in the rules stage (e.g., minimum holding period, transaction velocity limits).
+- **Allow short selling**: remove the non-negativity constraint to allow negative holdings.
+- **Maximize return for given risk**: flip the formulation to maximize expected return subject to a risk budget.
+- **Transaction costs**: add a linear or quadratic penalty term for rebalancing from an existing portfolio.
+
+### Scale up / productionize
+
+- Swap the `data/` CSV bundle for `model.data(snowflake_table)` calls to run against a live Snowflake-hosted universe and book.
+- Add a fourth regime or a fifth budget as a data edit in `scenario_data` -- the `solve_epsilon` call is unchanged, since scenarios are data, not code.
 
 ## Troubleshooting
 
@@ -617,3 +279,20 @@ Make sure you activated the virtual environment and ran `python -m pip install .
 
 Ensure the covariance matrix is symmetric and positive semi-definite. Check that `covar.csv` contains entries for all (i, j) pairs and that covar(i,j) == covar(j,i). HiGHS solves convex QPs to a global optimum and returns shadow prices (duals) when `sensitivity=True`.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Multi-reasoner workflows](https://docs.relational.ai/) — chained reasoner patterns and ontology enrichment across stages.
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)` / `aggs` / derived properties.
+
+### Reasoner reference
+
+- [Rules-based reasoner](https://docs.relational.ai/) — derived properties and Relationships for compliance flags.
+- [Graph reasoner](https://docs.relational.ai/) — building graphs from ontology, Louvain community detection.
+- [Prescriptive reasoner](https://docs.relational.ai/) — `Problem` API, quadratic objectives, sensitivity (duals / shadow prices), the epsilon-constraint frontier method.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/product_configurator/README.md b/v1/product_configurator/README.md
index 27219700..7b25f7dc 100644
--- a/v1/product_configurator/README.md
+++ b/v1/product_configurator/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Product Configurator"
-description: "Enumerate every feasible build of a configurable product in multi-solution mode: one option per slot subject to feature-model rules, regional regulations, and a price ceiling."
+description: "Enumerate every feasible build of a configurable product with a constraint solver in multi-solution mode. Each build picks one option per slot subject to feature-model rules, regional regulations, and a price ceiling."
 featured: false
 experience_level: intermediate
 industry: "Manufacturing"
@@ -14,8 +14,6 @@ tags:
   - manufacturing
 ---
 
-# Product Configurator
-
 ## What this template is for
 
 Configurable products -- cars, industrial equipment, enterprise software, network gear -- come with hundreds or thousands of options grouped into slots (engine, transmission, trim, sound, wheels, and so on). Picking a buildable combination by hand is hard: options require or exclude other options, regional regulations remove some choices entirely, and the total price has to stay under a target.
@@ -44,6 +42,7 @@ The configurator scenario here is automotive trim, drawn from the public Renault
 ## What's included
 
 - `product_configurator.py` -- main script with ontology, decisions, constraints, and solver call
+- **Runbook**: `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/slots.csv` -- 6 slots (Engine, Transmission, Trim, Sound, Wheels, Roof)
 - `data/options.csv` -- 16 options across the 6 slots, each with a price in integer cents
 - `data/implies.csv` -- option-to-option implies rules (e.g. Premium Audio implies Premium Trim)
@@ -94,167 +93,107 @@ The configurator scenario here is automotive trim, drawn from the public Renault
    python product_configurator.py
    ```
 
-6. Expected output. With `MAX_CONFIGURATIONS = 100` and `TARGET_REGION = "EU"`, the solver exhausts the search and returns every distinct feasible build (status `OPTIMAL`, 63 builds). The script prints all 63 rows, pivoted to one row per configuration, sorted ascending by total dollars; the block below is **abridged** to the 8 cheapest and 8 most-expensive. The `solution` column is the solver's internal index, not a sequential ranking, and `objective: 0` is reported by convention because this is pure constraint satisfaction with no minimize/maximize call. Exact wall times and the solver build string vary across RAI Native App versions:
+6. Expected output. With `MAX_CONFIGURATIONS = 100` and `TARGET_REGION = "EU"`, the solver exhausts the search and returns every distinct feasible build (status `OPTIMAL`, 63 builds), pivoted to one row per configuration and sorted ascending by total dollars. A few representative lines (the script prints all 63):
+
    ```text
    Solve result:
    • status: OPTIMAL
-   • objective: 0
-   • solve time: 0.95s
    • num_points: 63
-   • solver: MiniZinc_unknown
 
    Feasible builds for region 'EU' (ceiling $20,000, up to 100 per run):
     solution        Engine            Roof          Sound Transmission         Trim              Wheels  total_$
           60 1.6L Inline-4      Steel Roof Standard Sound       Manual    Base Trim       16-inch Alloy     1500
           59 1.6L Inline-4      Steel Roof Standard Sound       Manual    Base Trim       18-inch Sport     2700
-          39 1.6L Inline-4      Steel Roof Standard Sound    Automatic    Base Trim       16-inch Alloy     3500
-          50    2.0L Turbo      Steel Roof Standard Sound       Manual    Base Trim       16-inch Alloy     3500
-          56 1.6L Inline-4      Steel Roof Standard Sound       Manual   Sport Trim       16-inch Alloy     4000
-          51    2.0L Turbo      Steel Roof Standard Sound       Manual    Base Trim       18-inch Sport     4700
-          38 1.6L Inline-4      Steel Roof Standard Sound    Automatic    Base Trim       18-inch Sport     4700
-          57 1.6L Inline-4      Steel Roof Standard Sound       Manual   Sport Trim       18-inch Sport     5200
-           ... 47 more builds omitted (script prints all 63) ...
-           5    2.0L Turbo Panoramic Glass Standard Sound    Automatic Premium Trim       18-inch Sport    14700
-           7    2.0L Turbo Panoramic Glass  Premium Audio    Automatic Premium Trim       16-inch Alloy    15000
-          27    2.0L Turbo      Steel Roof  Premium Audio          DCT Premium Trim       18-inch Sport    15200
-          10    2.0L Turbo Panoramic Glass Standard Sound          DCT Premium Trim       16-inch Alloy    15500
-           1    2.0L Turbo Panoramic Glass  Premium Audio    Automatic Premium Trim       18-inch Sport    16200
-           4    2.0L Turbo Panoramic Glass Standard Sound          DCT Premium Trim       18-inch Sport    16700
-          11    2.0L Turbo Panoramic Glass  Premium Audio          DCT Premium Trim       16-inch Alloy    17000
+           ... 60 more builds omitted (script prints all 63) ...
            2    2.0L Turbo Panoramic Glass  Premium Audio          DCT Premium Trim       18-inch Sport    18200
    ```
 
-   With `TARGET_REGION = "EU"` the V6 engine is unavailable, and the 63 returned builds span $1,500-$18,200 -- every legal combination across the six slots, satisfying every implies/excludes rule. Lower `MAX_CONFIGURATIONS` to cap how many the solver returns (status flips to `SOLUTION_LIMIT` once hit).
+   With `TARGET_REGION = "EU"` the V6 engine is unavailable, and the 63 returned builds span $1,500-$18,200 -- every legal combination across the six slots, satisfying every implies/excludes rule. Lower `MAX_CONFIGURATIONS` to cap how many the solver returns (status flips to `SOLUTION_LIMIT` once hit). The full 63-row printout and a step-by-step walkthrough are in `runbook.md`.
 
 ## Template structure
+
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── product_configurator.py
-└── data/
-    ├── slots.csv
-    ├── options.csv
-    ├── implies.csv
-    ├── excludes.csv
-    └── regional_rules.csv
+product_configurator/
+  product_configurator.py    # Main script (ontology, decisions, constraints, solve, inspection)
+  data/
+    slots.csv                # 6 slots (Engine, Transmission, Trim, Sound, Wheels, Roof)
+    options.csv              # 16 options across the 6 slots, each priced in integer cents
+    implies.csv              # option-to-option implies rules (head -> tail)
+    excludes.csv             # option-to-option excludes rules (symmetric)
+    regional_rules.csv       # which options are allowed in which region (US, EU)
+  README.md                  # this file
+  runbook.md                 # analyst-facing paste-testable walkthrough
+  pyproject.toml             # dependencies
 ```
 
-## How it works
+**Start here**: run `python product_configurator.py` to enumerate every feasible build end to end, or follow `runbook.md` to rebuild it step by step.
 
-**1. Define slots, options, and load CSVs.** Slots and options are concepts; each option points to its slot, has a price in integer cents, and lists the regions it is allowed in:
+## Sample data
 
-```python
-Slot = model.Concept("Slot", identify_by={"id": Integer})
-Slot.name = model.Property(f"{Slot} has {String:name}")
+The bundled CSVs are illustrative demo data for an automotive trim configurator, drawn from the public Renault feature-model literature. Swap in your own slots, options, and rules to configure a different product.
 
-Option = model.Concept("Option", identify_by={"id": Integer})
-Option.name = model.Property(f"{Option} has {String:name}")
-Option.price_cents = model.Property(f"{Option} has {Integer:price_cents}")
-Option.slot = model.Property(f"{Option} is in {Slot:slot}")
-Option.allowed_in = model.Relationship(f"{Option} is allowed in {String:region}")
-```
+- **`slots.csv`** (6 rows) — the configurable slots (Engine, Transmission, Trim, Sound, Wheels, Roof).
+- **`options.csv`** (16 rows) — the options across the six slots, each with a `slot_id`, `name`, and `price_cents`.
+- **`implies.csv`** — directional option-to-option rules (`head_id` -> `tail_id`); selecting the head requires the tail.
+- **`excludes.csv`** — symmetric option-to-option rules (`left_id`, `right_id`); at most one of the pair may be selected.
+- **`regional_rules.csv`** — one row per `(option_id, region)` allowed pairing; an option missing for a region is banned there.
 
-**2. Define the implies and excludes rule tables.** Each rule is a concept identified by the pair of option IDs it links. `Implies` is directional (`head_id` -> `tail_id`) -- holding the rule *data*; the constraint *method* `model.require(...)` enforces them. `Excludes` is symmetric (`left_id`, `right_id`). The keys are deliberately dissimilar: PyRel emits a "potential relationship typo" warning when two compound-key names differ in a single character (e.g. `option_a_id` / `option_b_id`):
-
-```python
-Implies = model.Concept(
-    "Implies",
-    identify_by={"head_id": Integer, "tail_id": Integer},
-)
-Excludes = model.Concept(
-    "Excludes",
-    identify_by={"left_id": Integer, "right_id": Integer},
-)
-```
+## Model overview
 
-**3. Define the binary decision variable.** `Option.selected` is 0/1 and only exists for options allowed in the target region. Options banned in the region simply do not get a decision variable. Capture the returned `selected_var` handle -- step 6 indexes per-solution outputs through it via `.values(solution_index, value)`:
+The script builds a small ontology from the CSVs, then layers the binary decision and the four constraint families on top.
 
-```python
-Option.selected = model.Property(f"{Option} is selected if {Integer:selected}")
-selected_var = problem.solve_for(
-    Option.selected,
-    type="bin",
-    name=["selected", Option.name],
-    where=[Option.allowed_in(TARGET_REGION)],
-)
-```
+- **Key entities**: `Slot` — a configurable position on the product (e.g. engine), filled by exactly one option per build; `Option` — a choice that can fill a slot, with a price and region availability; plus the `Implies` and `Excludes` rule tables that constrain which options can combine.
+- **Primary identifiers**: integer `id` on `Slot` and `Option`; composite key on each rule table (`head_id` + `tail_id` on `Implies`, `left_id` + `right_id` on `Excludes`).
+- **Important invariants**: every option belongs to exactly one slot; prices are non-negative integer cents; a build picks exactly one option per slot; only options allowed in the target region get a decision variable.
 
-**4. Add the four constraint families and register each with the problem.** Each constraint is stored in a named variable so it can be re-checked by `problem.verify(...)` after solving; `problem.satisfy(ic)` is what actually pushes each constraint into the solver:
-
-```python
-exactly_one_ic = model.where(
-    Option.allowed_in(TARGET_REGION),
-    Option.slot(Slot),
-).require(sum(Option.selected).per(Slot) == 1)
-problem.satisfy(exactly_one_ic)
-
-A = Option.ref()
-B = Option.ref()
-implies_ic = model.where(
-    R := Implies,
-    A.id(R.head_id),
-    B.id(R.tail_id),
-    A.allowed_in(TARGET_REGION),
-    B.allowed_in(TARGET_REGION),
-).require(A.selected <= B.selected)
-problem.satisfy(implies_ic)
-
-excludes_ic = model.where(
-    E := Excludes,
-    A.id(E.left_id),
-    B.id(E.right_id),
-    A.allowed_in(TARGET_REGION),
-    B.allowed_in(TARGET_REGION),
-).require(A.selected + B.selected <= 1)
-problem.satisfy(excludes_ic)
-
-price_ic = model.where(
-    Option.allowed_in(TARGET_REGION),
-).require(sum(Option.price_cents * Option.selected) <= PRICE_CEILING_CENTS)
-problem.satisfy(price_ic)
-```
+The two rule tables — `Implies(head_id, tail_id)` (selecting the head requires the tail) and `Excludes(left_id, right_id)` (at most one of the pair) — are concepts identified by the pair of option ids they link, and the constraint families read them directly.
 
-The implies constraint reads as "if A (head) is selected (selected[A] = 1), then B (tail) must be selected too (selected[B] = 1), so selected[A] <= selected[B]". The excludes constraint reads as "at most one of A and B may be selected".
+For the full concept and property definitions, see `product_configurator.py`; `runbook.md` builds them step by step with the RAI skills.
 
-**5. Solve in multi-solution mode and verify.** Pass `solution_limit=MAX_CONFIGURATIONS` to enumerate up to that many distinct feasible builds. After solving, `problem.verify()` fires the named constraints to confirm the configuration satisfies every rule (it inspects only the first solution -- the populated property -- but the constraint structure is shared across every solution the solver returns):
+## How it works
 
-```python
-problem.solve("minizinc", time_limit_sec=60, solution_limit=MAX_CONFIGURATIONS)
-problem.solve_info().display()
-problem.verify(exactly_one_ic, implies_ic, excludes_ic, price_ic)
-```
+The model declares a binary "selected" decision per region-allowed option, applies four constraint families, then enumerates every feasible build in one multi-solution solve.
 
-**6. Inspect every feasible build with `Variable.values`.** Capturing the variable subconcept from `solve_for(...)` exposes a `.values(solution_index, value)` relationship that indexes the per-solution outputs; binding the value slot directly to the literal `1` surfaces just the options the solver picked into each build. The variable subconcept exposes a back-pointer field named after the entity in its property: `selected_var.option` walks back to the `Option` instance for each row, so `selected_var.option.slot.name` and `selected_var.option.price_cents` resolve naturally. A post-solve `pandas.pivot` collapses the per-option rows into one row per build for buyer-facing display:
-
-```python
-sol_idx = Integer.ref()
-selections_df = (
-    model.select(
-        sol_idx.alias("solution"),
-        selected_var.option.slot.name.alias("slot"),
-        selected_var.option.name.alias("option"),
-        selected_var.option.price_cents.alias("price_cents"),
-    )
-    .where(selected_var.values(sol_idx, 1))
-    .to_df()
-    .astype({"solution": "int64", "price_cents": "int64"})
-)
-build_view = selections_df.pivot(index="solution", columns="slot", values="option")
-build_view["total_$"] = selections_df.groupby("solution")["price_cents"].sum() // 100
-build_view = build_view.sort_values("total_$").reset_index()
-print(build_view.to_string(index=False))
+```text
+slots + options + implies + excludes + regional rules → region-filtered selected decisions → exactly-one + implies + excludes + price constraints → multi-solution solve → pivot to one row per build
 ```
 
+**1. Slots, options, and rule tables.** Slots and options are concepts; each option points to its slot, has a price in integer cents, and lists the regions it is allowed in. Each rule is a concept identified by the pair of option ids it links — `Implies` is directional (head -> tail), `Excludes` is symmetric. The compound-key field names are deliberately dissimilar (`head_id`/`tail_id`, `left_id`/`right_id`) because PyRel emits a "potential relationship typo" warning when two compound-key names differ by a single character.
+
+**2. The binary decision.** `Option.selected` is 0/1 and is scoped, via a `where` on region availability, to options allowed in the target region — options banned in the region simply never get a decision variable. The `solve_for` call returns a variable handle that step 4 uses to read per-solution outputs.
+
+**3. The four constraint families.** Each is stored in a named variable so it can be re-checked by `problem.verify(...)`, and pushed to the solver with `problem.satisfy(...)`:
+
+- **Exactly-one** — the selected options per slot sum to 1, so every build fills each slot exactly once.
+- **Implies** — for each region-allowed rule, `selected[head] <= selected[tail]`: picking the head forces the tail.
+- **Excludes** — for each region-allowed pair, `selected[left] + selected[right] <= 1`: at most one of the pair.
+- **Price ceiling** — the price-weighted sum of selected options stays within `PRICE_CEILING_CENTS`.
+
+**4. Solve in multi-solution mode, verify, and pivot.** Passing `solution_limit=MAX_CONFIGURATIONS` runs the search in enumeration mode, returning up to that many distinct feasible builds. `problem.verify()` re-checks the named constraints against the first returned solution (the constraint structure is shared across every solution the solver returns). The variable handle exposes a `.values(solution_index, value)` relationship over the per-solution outputs; binding the value slot to `1` surfaces just the picked options, and a `pandas.pivot` collapses the per-option rows into one row per build (one column per slot, plus a dollar total, sorted ascending by price) for buyer-facing display.
+
+For the exact PyRel formulation, see `product_configurator.py`; `runbook.md` reproduces the model step by step with the RAI skills.
+
 ## Customize this template
 
-- **Use your own product** by replacing the five CSV files with your slots, options, implies, excludes, and regional_rules tables. The constraint structure does not change.
-- **Cap the solution limit on a large catalog.** The bundled `MAX_CONFIGURATIONS = 100` is above the demo's feasible-set size so every build is enumerated (status `OPTIMAL`). On a production catalog the feasible set can be enormous; lower `MAX_CONFIGURATIONS` to the K builds your buyer-facing UI wants to surface -- the solver returns once the cap is hit (status `SOLUTION_LIMIT`) and `time_limit_sec` is your safety net for runaway enumeration.
+### Use your own data
+
+- Replace the five CSV files with your slots, options, implies, excludes, and regional_rules tables. The constraint structure does not change.
 - **Add a new region** by adding rows to `regional_rules.csv` for the new region and changing `TARGET_REGION` in the runner.
+
+### Tune parameters
+
+- **Cap the solution limit on a large catalog.** The bundled `MAX_CONFIGURATIONS = 100` is above the demo's feasible-set size so every build is enumerated (status `OPTIMAL`). On a production catalog the feasible set can be enormous; lower `MAX_CONFIGURATIONS` to the K builds your buyer-facing UI wants to surface -- the solver returns once the cap is hit (status `SOLUTION_LIMIT`) and `time_limit_sec` is your safety net for runaway enumeration.
 - **Tighten the price ceiling** by lowering `PRICE_CEILING_CENTS` to force the solver toward cheaper builds. If the ceiling drops below the cheapest feasible build, the solver returns INFEASIBLE.
+
+### Extend the model
+
 - **Switch from "all feasible" to "the cheapest build"** by adding `problem.minimize(sum(Option.price_cents * Option.selected))` and setting `MAX_CONFIGURATIONS = 1`. The solver returns one optimum. Top-K *optimal* enumeration (the K cheapest distinct builds, ranked) is not a single solver call; for that, run an iterative exclusion-cut loop -- after each optimal solve, add a constraint forbidding the just-returned build's exact option set, then re-solve -- or sort the enumerated multi-solution set in post-processing if the feasible set is small enough to fit in memory (the bundled demo already does this: 63 builds sorted ascending by total dollars).
 - **Add cardinality rules** like "at least one of {A, B, C} must be selected" with `count` over a filter on `Option.id`.
+
+### Scale up / productionize
+
 - **Apply this to enterprise software bundling** by mapping slots to product modules, options to feature tiers, implies/excludes to module dependencies, and price_cents to seat-license cost. The constraint families and multi-solution shape carry over unchanged.
+- Swap the `data/` CSV bundle for `model.data(snowflake_table)` calls to configure against a live Snowflake-hosted catalog; `time_limit_sec` and `MAX_CONFIGURATIONS` bound enumeration on large catalogs.
 
 ## Troubleshooting
 
@@ -316,3 +255,19 @@ print(build_view.to_string(index=False))
 - To pin a single answer (e.g. surface the cheapest build first), set `MAX_CONFIGURATIONS = 1` and add `problem.minimize(sum(Option.price_cents * Option.selected))`.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — concepts, properties, relationships, and `model.where(...)`.
+- [Prescriptive reasoner](https://docs.relational.ai/) — `Problem` API, binary decision variables, integrity constraints.
+
+### Reasoner reference
+
+- [Multi-solution enumeration](https://docs.relational.ai/) — `solution_limit`, `Variable.values(...)`, and reading every returned solution.
+- [Constraint satisfaction patterns](https://docs.relational.ai/) — exactly-one, implies, excludes, and budget constraints over binary decisions.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/production_planning/README.md b/v1/production_planning/README.md
index 3e6e58dd..90fe8fa4 100644
--- a/v1/production_planning/README.md
+++ b/v1/production_planning/README.md
@@ -12,34 +12,32 @@ tags:
   - Scenario Analysis
 ---
 
-# Production Planning
-
 ## What this template is for
 
 Manufacturers must decide how many units of each product to produce on each machine to maximize profit while meeting customer demand and respecting machine capacity. When market conditions are uncertain, planners need to evaluate how production plans change under different demand scenarios.
 
-This template uses prescriptive reasoning to find the profit-maximizing production plan across a set of machines and products. Each machine has limited available hours, and each machine-product combination has a specific production rate. The model runs multiple demand scenarios (80%, 100%, and 110% of base demand) to show how the optimal plan shifts as demand changes.
+This template finds the profit-maximizing production plan across a set of machines and products. Each machine has limited available hours, and each machine-product combination has a specific production rate. Three demand scenarios (80%, 100%, and 110% of base demand) are modeled together so decision-makers can see how the optimal plan shifts as demand changes and understand how sensitive their production strategy is to demand fluctuations.
 
-The scenario analysis loop demonstrates a powerful pattern for what-if planning. By solving the same model structure under different parameter values, decision-makers can understand the sensitivity of their production strategy to demand fluctuations.
+**The reasoning approach uses prescriptive optimization: a single mixed-integer program that solves all demand scenarios simultaneously, with scenario-scoped capacity and demand constraints.**
 
 ## Who this is for
 
 - Production planners optimizing machine utilization and product mix
 - Operations managers evaluating plans under demand uncertainty
 - Developers learning integer programming and scenario analysis with RelationalAI
-- Anyone building production scheduling or capacity planning tools
+- **Assumed knowledge**: comfortable reading Python; the optimization and manufacturing terms are explained as they come up
 
 ## What you'll build
 
-- A multi-machine, multi-product production planning model with integer variables
-- Machine capacity constraints based on production rates
-- Demand satisfaction constraints with configurable demand multipliers
-- A profit maximization objective
-- A scenario analysis loop comparing results across demand levels
+- A profit-maximizing production plan across machines and products, produced by **prescriptive reasoning** (mixed-integer program)
+- Machine-capacity limits enforced as per-machine, per-scenario constraints
+- Demand-satisfaction requirements scaled by a per-scenario demand multiplier
+- A three-scenario comparison (80% / 100% / 110% of base demand) solved in a single call over a first-class `Scenario` concept
 
 ## What's included
 
-- `production_planning.py` -- Main script with scenario loop, model definition, and result summaries
+- `production_planning.py` -- Main script with the scenario model, constraints, objective, and result summary
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/products.csv` -- Products with base demand and per-unit profit margins
 - `data/machines.csv` -- Machines with available hours per planning period
 - `data/production_rates.csv` -- Hours required per unit for each machine-product combination
@@ -87,140 +85,113 @@ The scenario analysis loop demonstrates a powerful pattern for what-if planning.
    python production_planning.py
    ```
 
-6. Expected output:
+6. Expected output (all scenarios solved together in a single call):
    ```text
-   Running scenario: demand_multiplier = 0.8
-     Status: OPTIMAL, Objective: 14650.0
-
-     Production plan:
-              name  value
-    qty_Machine_1_Widget_A   80.0
-    qty_Machine_1_Widget_C   48.0
-    qty_Machine_2_Widget_B   64.0
-    qty_Machine_3_Widget_A    2.0
-    qty_Machine_3_Widget_B    2.0
-
-   Running scenario: demand_multiplier = 1.0
-     Status: OPTIMAL, Objective: 15950.0
-
-     Production plan:
-              name  value
-    qty_Machine_1_Widget_A   80.0
-    qty_Machine_1_Widget_C   60.0
-    qty_Machine_2_Widget_B   70.0
-    qty_Machine_3_Widget_A   20.0
-    qty_Machine_3_Widget_B   10.0
-
-   Running scenario: demand_multiplier = 1.1
-     Status: OPTIMAL, Objective: 16800.0
-
-     Production plan:
-              name  value
-    qty_Machine_1_Widget_A   80.0
-    qty_Machine_1_Widget_B   10.0
-    qty_Machine_1_Widget_C   66.0
-    qty_Machine_2_Widget_B   70.0
-    qty_Machine_3_Widget_A   30.0
-    qty_Machine_3_Widget_B   10.0
-
-   ==================================================
-   Scenario Analysis Summary
-   ==================================================
-     0.8: OPTIMAL, obj=14650.0
-     1.0: OPTIMAL, obj=15950.0
-     1.1: OPTIMAL, obj=16800.0
+   Solve result:
+   • status: OPTIMAL
+   • objective: 44735.0
+   • solver: HiGHS
+   • relative gap: 0.0
+
+   Production plan per scenario:
+          scenario    machine   product  quantity
+   0      baseline  Machine_1  Widget_A       4.0
+   1      baseline  Machine_1  Widget_C      95.0
+   2      baseline  Machine_2  Widget_B      70.0
+   3      baseline  Machine_3  Widget_A      96.0
+   4      baseline  Machine_3  Widget_B      11.0
+   5   high_demand  Machine_1  Widget_A      24.0
+   6   high_demand  Machine_1  Widget_B       1.0
+   7   high_demand  Machine_1  Widget_C      68.0
+   8   high_demand  Machine_2  Widget_B      70.0
+   9   high_demand  Machine_3  Widget_A      87.0
+   10  high_demand  Machine_3  Widget_B      17.0
+   11   low_demand  Machine_1  Widget_C     100.0
+   12   low_demand  Machine_2  Widget_B      70.0
+   13   low_demand  Machine_3  Widget_A     111.0
+   14   low_demand  Machine_3  Widget_B       1.0
    ```
 
+   The single objective (`44735.0`) is the combined profit across all three scenarios. Per-scenario profit is $15,020 (0.8x), $14,945 (1.0x), and $14,770 (1.1x) — profit *falls* as the demand floor rises, because a looser floor leaves more capacity for the highest-margin mix.
+
 ## Template structure
+
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── production_planning.py
+production_planning/
+├── README.md               # this file
+├── pyproject.toml          # dependencies
+├── production_planning.py   # main script (single solve over all scenarios)
+├── runbook.md              # analyst-facing walkthrough
 └── data/
-    ├── products.csv
-    ├── machines.csv
-    └── production_rates.csv
+    ├── products.csv        # products with base demand and per-unit profit
+    ├── machines.csv        # machines with available hours per period
+    └── production_rates.csv # hours per unit for each machine-product pair
 ```
 
-## How it works
+**Start here**: run `python production_planning.py` for the full run end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-### 1. Define the ontology and load data
+## Sample data
 
-The model defines products with demand and profit, machines with available hours, and production rates linking each machine-product pair.
+The bundled data is small and illustrative — three CSVs describing a plant with a handful of products and machines, sized so the model solves instantly while showing the full workflow.
 
-```python
-Product = Concept("Product", identify_by={"id": Integer})
-Product.name = Property(f"{Product} has {String:name}")
-Product.demand = Property(f"{Product} has {Integer:demand}")
-Product.profit = Property(f"{Product} has {Float:profit}")
+- **`products.csv`** — one row per product, with `demand` (base units required) and `profit` (per-unit margin).
+- **`machines.csv`** — one row per machine, with `hours_available` per planning period.
+- **`production_rates.csv`** — one row per machine-product pair, with `hours_per_unit` (machine time to make one unit). A missing pair means that machine cannot make that product.
 
-Machine = Concept("Machine", identify_by={"id": Integer})
-Machine.name = Property(f"{Machine} has {String:name}")
-Machine.hours_available = Property(f"{Machine} has {Float:hours_available}")
+The three demand scenarios (`low_demand` 0.8, `baseline` 1.0, `high_demand` 1.1) are defined inline in the script, not loaded from a CSV.
 
-Rate = Concept("ProductionRate")
-Rate.machine = Property(f"{Rate} on {Machine}", short_name="machine")
-Rate.product = Property(f"{Rate} for {Product}", short_name="product")
-Rate.hours_per_unit = Property(f"{Rate} has {Float:hours_per_unit}")
-```
+## Model overview
 
-### 2. Define decision variables and scenarios
+- **Key entities**: `Product` — a product to manufacture, with its base demand and profit margin; `Machine` — a machine with a fixed number of available hours per planning period; `ProductionRate` — how long a given machine takes to make one unit of a given product; `Scenario` — a demand scenario applied uniformly to all products; and the decision concept `Production` — one per production rate, carrying the solved quantity per scenario.
+- **Primary identifiers**: integer `id` on `Product` and `Machine`; string `name` on `Scenario`. `ProductionRate` and `Production` are identified structurally by the entities they link.
+- **Important invariants**: `demand`, `profit`, `hours_available`, and `hours_per_unit` are non-negative; the decision variable `x_quantity` is a non-negative integer; total machine hours used cannot exceed `hours_available`; total units produced must meet demand scaled by the scenario multiplier.
 
-Scenarios are modeled as a `Scenario` concept with a `demand_multiplier` property — all scenarios are solved in a single call, not a loop.
+For the full concept and property definitions, see `production_planning.py`; `runbook.md` builds them step by step with the RAI skills.
 
-```python
-Scenario = Concept("Scenario", identify_by={"name": String})
-Scenario.demand_multiplier = Property(f"{Scenario} has {Float:demand_multiplier}")
+## How it works
 
-problem = Problem(model, Float)
+The pipeline loads the three CSVs into the ontology, layers a `Scenario` concept over them, and hands a single mixed-integer program to the solver that decides production quantities for every scenario at once.
 
-# Variable indexed by Scenario — one quantity per production rate per scenario
-Production.x_quantity = Property(f"{Production} in {Scenario} has {Float:quantity}")
-problem.solve_for(
-    Production.x_quantity(Scenario, x_qty),
-    name=["qty", Scenario.name, Production.rate.machine.name, Production.rate.product.name],
-    lower=0, type="int",
-)
+```text
+CSV inputs → load Product / Machine / ProductionRate → add Scenario multipliers
+  → build the integer production variable (per rate, per scenario)
+  → capacity + demand constraints → maximize profit → solve → per-scenario plan
 ```
 
-### 3. Add constraints
+1. **Load the data.** Products carry base demand and per-unit profit, machines carry available hours, and each `ProductionRate` links a machine-product pair to the hours it takes to make one unit. A missing pair means that machine cannot make that product.
+2. **Add scenarios and the decision variable.** The three demand scenarios become a first-class `Scenario` concept, each with a `demand_multiplier`. The solver decides one non-negative integer quantity per production rate *per scenario*, so all scenarios are solved together in a single call rather than in a loop.
+3. **Constrain the plan.** For each machine and scenario, total hours used cannot exceed the machine's available hours. For each product and scenario, total units produced must meet that product's demand scaled by the scenario's multiplier.
+4. **Maximize profit.** The objective sums per-unit profit across every production assignment, and the solver returns the profit-maximizing plan for all scenarios at once.
 
-Machine capacity and demand satisfaction constraints are defined per scenario.
+See `production_planning.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
-```python
-# Machine capacity: total production hours <= available hours (per machine, per scenario)
-problem.satisfy(model.where(...).require(
-    sum(x_qty * Production.rate.hours_per_unit)
-    .where(Production.rate.machine == Machine)
-    .per(Machine, Scenario)
-    <= Machine.hours_available
-))
+## Customize this template
 
-# Meet scaled demand (per product, per scenario)
-problem.satisfy(model.where(...).require(
-    sum(x_qty).where(Production.rate.product == Product).per(Product, Scenario)
-    >= Product.demand * Scenario.demand_multiplier
-))
-```
+Focus on the first changes most users will make.
 
-### 4. Maximize profit
+### Use your own data
 
-The objective maximizes total profit across all production assignments.
+- Replace the CSVs in `data/` with your own, keeping the column names listed in *Sample data* above.
+- Add a `production_rates.csv` row for every machine-product pair a machine can actually make; omit pairs it cannot make.
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)`.
 
-```python
-total_profit = sum(Production.x_quantity * Production.rate.product.profit)
-problem.maximize(total_profit)
-```
+### Tune parameters
 
-## Customize this template
+- **Demand scenarios** — edit the `scenario_data` list at the top of the script to change the multipliers or add scenarios.
+- **Solver time limit** — `time_limit_sec` (default `60`) on the `problem.solve(...)` call.
+- **Extend scenario analysis** to vary other parameters, such as machine availability or profit margins.
+
+### Extend the model
 
-- **Add more products or machines** by extending the CSV files.
 - **Add raw material constraints** by introducing material requirements per product and inventory limits.
 - **Model setup times** between product changeovers on the same machine.
-- **Extend scenario analysis** to vary other parameters like machine availability or profit margins.
 - **Add minimum lot sizes** by setting lower bounds on production quantities when a product is produced.
 
+### Scale up / productionize
+
+- Replace the CSV bundle with ingestion from your ERP or MES tables.
+- Integer programs grow harder with more products, machines, and scenarios; give the solver more time via `time_limit_sec`, or relax integrality during exploratory runs (see Troubleshooting).
+
 ## Troubleshooting
 
 <details>
@@ -246,3 +217,21 @@ Run `rai init` to configure your Snowflake connection. Verify that the RAI Nativ
 
 Ensure you activated the virtual environment and ran `python -m pip install .` to install all dependencies listed in `pyproject.toml`.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)`, `.per(...)`, aggregations, and `model.select(...)`.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives.
+
+### Deeper dives
+
+- [Scenario modeling with a `Scenario` concept](https://docs.relational.ai/) — how a single solve covers multiple parameter settings via a scenario-indexed decision variable.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/retail_markdown/README.md b/v1/retail_markdown/README.md
index b385df1a..c2afc23a 100644
--- a/v1/retail_markdown/README.md
+++ b/v1/retail_markdown/README.md
@@ -13,34 +13,33 @@ tags:
   - Pricing Optimization
 ---
 
-# Retail Markdown
-
 ## What this template is for
 
 Retailers often face the challenge of clearing seasonal inventory before it loses value. Markdown optimization determines the best discount schedule across a planning horizon to maximize total revenue -- including both sales revenue and the salvage value of any remaining stock. Discounts stimulate demand but reduce per-unit revenue, so the trade-off must be carefully balanced.
 
-This template uses **Prescriptive** reasoning to model the markdown problem as a mixed-integer program. Binary decision variables select which discount level to apply to each product in each week. Continuous variables track units sold and cumulative sales. Constraints enforce that exactly one discount is chosen per product-week, that discounts can only increase over time (a price ladder), and that cumulative sales never exceed initial inventory. Demand depends on a base rate, a discount-specific demand lift, and a weekly seasonal multiplier.
+This template finds the discount schedule that maximizes revenue across a multi-week horizon, respecting a price ladder (discounts only deepen over time) and finite inventory, and crediting the salvage value of whatever is left at the end. It captures the full trade-off between aggressive discounting to drive volume and preserving margin on high-value items.
 
-The objective maximizes total revenue from sales plus the salvage value of unsold inventory at the end of the planning horizon. This captures the full trade-off between aggressive discounting to drive volume and preserving margin on high-value items.
+**The reasoning approach uses prescriptive optimization: a mixed-integer program that picks one discount level per product-week and tracks the resulting sales and cumulative inventory.**
 
 ## Who this is for
 
 - Retail pricing and merchandising analysts optimizing markdown schedules
 - Operations researchers working with mixed-integer programming
 - Data scientists exploring multi-period optimization with binary decisions
-- Anyone interested in inventory clearance and revenue management
+- **Assumed knowledge**: comfortable reading Python; the pricing and optimization terms are explained as they come up
 
 ## What you'll build
 
-- A mixed-integer programming model that selects discount levels per product per week
-- Price ladder constraints preventing discount reversals
-- Demand modeling with base demand, discount lifts, and seasonal multipliers
-- Inventory tracking via cumulative sales constraints
-- Revenue maximization including end-of-horizon salvage value
+- A revenue-maximizing markdown schedule (one discount level per product per week), produced by **prescriptive reasoning** (mixed-integer program)
+- A price ladder that prevents discounts from reversing week to week
+- A demand model combining base demand, discount lift, and weekly seasonal multipliers
+- Per-week sales and cumulative-inventory tracking, bounded so cumulative sales never exceed initial stock
+- A total-revenue figure that credits end-of-horizon salvage value on unsold units
 
 ## What's included
 
 - `retail_markdown.py` -- Main script defining the MIP model with discount selection, sales tracking, and revenue optimization
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/products.csv` -- Products with initial price, cost, inventory, base demand, and salvage rate
 - `data/discounts.csv` -- Discount levels with percentage and demand lift factor
 - `data/weeks.csv` -- Planning weeks with seasonal demand multipliers
@@ -91,150 +90,87 @@ The objective maximizes total revenue from sales plus the salvage value of unsol
 6. Expected output:
    ```text
    Status: OPTIMAL
-   Total revenue (sales + salvage): $18432.50
-
-   === Selected Discounts by Product-Week ===
-    product  week  discount_pct
-    Sweater     1           0.0
-    Sweater     2          10.0
-    Sweater     3          20.0
-    Sweater     4          30.0
-     Jacket     1           0.0
-     Jacket     2           0.0
-     Jacket     3          10.0
-     Jacket     4          20.0
-      Pants     1           0.0
-      Pants     2          10.0
-      Pants     3          20.0
-      Pants     4          30.0
-      Shirt     1           0.0
-      Shirt     2           0.0
-      Shirt     3          10.0
-      Shirt     4          20.0
-
-   === Sales by Product-Week ===
-    product  week  discount_pct  units_sold
-    Sweater     1           0.0       20.00
-    Sweater     2          10.0       20.70
-    Sweater     3          20.0       21.60
-    Sweater     4          30.0       22.40
-     Jacket     1           0.0       12.00
-     Jacket     2           0.0       10.80
-     Jacket     3          10.0       11.04
-     Jacket     4          20.0       11.34
-      Pants     1           0.0       25.00
-      Pants     2          10.0       25.88
-      Pants     3          20.0       27.00
-      Pants     4          30.0       28.00
-      Shirt     1           0.0       30.00
-      Shirt     2           0.0       27.00
-      Shirt     3          10.0       27.60
-      Shirt     4          20.0       28.35
-
-   === Cumulative Sales by Product-Week ===
-    product  week  cumulative_sold
-    Sweater     1            20.00
-    Sweater     2            40.70
-    Sweater     3            62.30
-    Sweater     4            84.70
-     Jacket     1            12.00
-     Jacket     2            22.80
-     Jacket     3            33.84
-     Jacket     4            45.18
-      Pants     1            25.00
-      Pants     2            50.88
-      Pants     3            77.88
-      Pants     4           105.88
-      Shirt     1            30.00
-      Shirt     2            57.00
-      Shirt     3            84.60
-      Shirt     4           112.95
+   Total revenue (sales + salvage): $23374.65
    ```
 
+   Discounts start shallow (20%) and deepen to 30% later in the season; no
+   product needs the 50% tier. See `runbook.md` for the full discount, sales,
+   and cumulative-sales schedule.
+
 ## Template structure
 
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── retail_markdown.py
+retail_markdown/
+├── README.md            # this file
+├── pyproject.toml       # dependencies
+├── retail_markdown.py   # main script (MIP model, solve, result tables)
+├── runbook.md           # analyst-facing walkthrough
 └── data/
-    ├── products.csv
-    ├── discounts.csv
-    └── weeks.csv
+    ├── products.csv     # products with price, cost, inventory, base demand, salvage rate
+    ├── discounts.csv    # discount levels with percentage and demand lift
+    └── weeks.csv        # planning weeks with seasonal demand multipliers
 ```
 
-## How it works
+**Start here**: run `python retail_markdown.py` for the full run end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-### 1. Define concepts and load data
+## Sample data
 
-Three concepts are defined: `Product` (with pricing, inventory, and demand info), `Discount` (with percentage and demand lift), and `Week` (with seasonal demand multiplier):
+The bundled data is small and illustrative — a short seasonal clearance across a handful of products, sized so the model solves instantly while showing the full workflow.
 
-```python
-Product = model.Concept("Product", identify_by={"name": String})
-Product.initial_price = model.Property(f"{Product} has {Float:initial_price}")
-Product.initial_inventory = model.Property(f"{Product} has {Integer:initial_inventory}")
-Product.base_demand = model.Property(f"{Product} has {Float:base_demand}")
-Product.salvage_rate = model.Property(f"{Product} has {Float:salvage_rate}")
+- **`products.csv`** — one row per product, with `initial_price`, `cost`, `initial_inventory`, `base_demand` (units per week at full price), and `salvage_rate` (fraction of price recovered on leftovers).
+- **`discounts.csv`** — one row per discount tier, with `discount_pct` (percent off) and `demand_lift` (demand multiplier at that discount). Includes a `level` 0 / 0% tier so "no markdown" is always an option.
+- **`weeks.csv`** — one row per planning week, with `demand_multiplier` (seasonal factor applied to base demand).
 
-Discount = model.Concept("Discount", identify_by={"level": Integer})
-Discount.discount_pct = model.Property(f"{Discount} has {Float:discount_pct}")
-Discount.demand_lift = model.Property(f"{Discount} has {Float:demand_lift}")
+## Model overview
 
-Week = model.Concept("Week", identify_by={"num": Integer})
-Week.demand_multiplier = model.Property(f"{Week} has {Float:demand_multiplier}")
-```
+- **Key entities**: `Product` — an item to mark down, with its price, cost, stock, demand, and salvage economics; `Discount` — a discount tier defining how much price is cut and how much demand rises; `Week` — a period in the planning horizon, with its seasonal demand factor.
+- **Primary identifiers**: string `name` on `Product`; integer `level` on `Discount`; integer `num` on `Week`.
+- **Important invariants**: exactly one discount level is active per product-week; discounts can only deepen over successive weeks (price ladder); cumulative sales never exceed `initial_inventory`; `discount_pct`, `demand_lift`, and `demand_multiplier` are non-negative; the selection variable is binary and sales variables are non-negative.
+
+For the full concept and property definitions, see `retail_markdown.py`; `runbook.md` builds them step by step with the RAI skills.
 
-### 2. Decision variables
+## How it works
 
-Three sets of variables model the decisions and state: binary selection of discount level per product-week, continuous sales per product-week-discount, and cumulative sales per product-week:
+The pipeline loads products, discount tiers, and planning weeks, then builds a single mixed-integer program that chooses a discount for each product-week, tracks the resulting sales and inventory, and credits salvage value on whatever is left over.
 
-```python
-problem.solve_for(Product.x_select(Week_ref, Discount_ref, selection_ref), type="bin", ...)
-problem.solve_for(Product.x_sales(Week_ref, Discount_ref, sales_ref), type="cont", lower=0, ...)
-problem.solve_for(Product.x_cuml_sales(Week_ref, cumulative_ref), type="cont", lower=0, ...)
+```text
+CSV inputs → load Product / Discount / Week → decision variables (discount choice, sales, cumulative sales)
+  → one-discount + price-ladder + inventory constraints → maximize sales revenue + salvage → solve → schedule
 ```
 
-### 3. Key constraints
+1. **Load the data.** Products carry price, cost, starting inventory, base demand, and a salvage rate; discounts carry a percent-off and a demand-lift multiplier (including a 0% tier so "no markdown" is always available); weeks carry a seasonal demand multiplier.
+2. **Set up the decisions.** Three variable families capture the plan: a binary choice of which discount is active for each product-week, continuous units sold per product-week-discount, and cumulative units sold through each week. A `num_weeks` count marks the final week for the salvage term.
+3. **Constrain the schedule.** Exactly one discount level is active per product-week; discounts can only deepen from one week to the next (the price ladder); and cumulative sales can never exceed starting inventory.
+4. **Maximize revenue.** The objective adds sales revenue — discounted price times units sold — to the salvage value of unsold units at the end of the horizon, and the solver returns the revenue-maximizing discount schedule.
 
-The one-hot constraint ensures exactly one discount level is active per product-week. The price ladder constraint prevents discount reversals:
+See `retail_markdown.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
-```python
-# One discount per product-week
-problem.satisfy(model.where(Product.x_select(Week_ref, Discount_ref, selection_ref)).require(
-    sum(Discount_ref, selection_ref).per(Product, Week_ref) == 1
-))
+## Customize this template
 
-# Discounts can only increase over time
-problem.satisfy(model.where(
-    Product.x_select(Week_ref, Discount_ref, selection_ref),
-    Product.x_select(Week_inner, Discount_inner, selection_inner),
-    Week_inner.num == Week_ref.num + 1,
-    Discount_inner.level < Discount_ref.level,
-).require(selection_ref + selection_inner <= 1))
-```
+Focus on the first changes most users will make.
 
-### 4. Objective
+### Use your own data
 
-Revenue combines sales revenue (price after discount times units sold) and salvage value of remaining inventory:
+- Replace the CSVs in `data/` with your own, keeping the column names listed in *Sample data* above.
+- Keep a `level` 0 / 0% row in `discounts.csv` so "no markdown" remains a feasible choice.
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)`.
 
-```python
-revenue = sum(
-    Product.initial_price * (1 - Discount_ref.discount_pct / 100) * sales_ref
-).where(Product.x_sales(Week_ref, Discount_ref, sales_ref))
-salvage = sum(
-    Product.initial_price * Product.salvage_rate * (Product.initial_inventory - cumulative_ref)
-).where(Product.x_cuml_sales(Week_ref, cumulative_ref), Week_ref.num == num_weeks)
-problem.maximize(revenue + salvage)
-```
+### Tune parameters
 
-## Customize this template
+- **Discount levels** — modify `discounts.csv` to add finer or coarser tiers with different demand lifts.
+- **Planning horizon** — add or remove rows in `weeks.csv`; the model scales with longer horizons.
+- **Solver time limit** — `time_limit_sec` (default `60`) on the `problem.solve(...)` call.
+
+### Extend the model
 
-- **Add more products or weeks**: Extend the CSV files. The model scales with additional products and longer planning horizons.
-- **Change discount levels**: Modify `discounts.csv` to add finer or coarser discount tiers with different demand lifts.
-- **Minimum margin constraint**: Add a constraint ensuring the discounted price always exceeds the product cost.
-- **Category-level constraints**: Group products by category and limit the total discount budget per category.
-- **Demand elasticity**: Replace the fixed demand lift with a price-elasticity function for more realistic demand modeling.
+- **Minimum margin constraint** — add a constraint ensuring the discounted price always exceeds the product cost.
+- **Category-level constraints** — group products by category and limit the total discount budget per category.
+- **Demand elasticity** — replace the fixed demand lift with a price-elasticity function for more realistic demand modeling.
+
+### Scale up / productionize
+
+- Replace the CSV bundle with ingestion from your merchandising or point-of-sale tables.
+- Mixed-integer programs grow harder with more products, weeks, and discount tiers; give the solver more time via `time_limit_sec`, or accept a near-optimal solution by checking the MIP gap.
 
 ## Troubleshooting
 
@@ -261,3 +197,21 @@ Ensure your Snowflake credentials are configured correctly and that the RAI Nati
 
 Make sure you activated the virtual environment and ran `python -m pip install .` from the template directory. The `pyproject.toml` declares the required dependencies.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)`, `.per(...)`, aggregations, and `model.select(...)`.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives.
+
+### Deeper dives
+
+- [Multi-period optimization patterns](https://docs.relational.ai/) — modeling week-over-week state (cumulative sales, price ladders) with indexed decision variables.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/retail_planning/README.md b/v1/retail_planning/README.md
index 81936118..4ac707c8 100644
--- a/v1/retail_planning/README.md
+++ b/v1/retail_planning/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Retail Planning"
-description: "Predict article sales and customer churn with GNNs, then optimize markdown pricing and inventory planning to maximize revenue and minimize costs."
+description: "Predict article sales and customer churn with graph neural networks (GNNs), then optimize markdown pricing and inventory planning to maximize revenue and minimize costs."
 featured: true
 experience_level: advanced
 industry: "Retail & Consumer"
@@ -8,7 +8,7 @@ reasoning_types:
   - Predictive
   - Prescriptive
 tags:
-  - GNN
+  - Graph Neural Network (GNN)
   - Predict-then-Optimize
   - Markdown Optimization
   - Demand Planning
@@ -18,11 +18,11 @@ tags:
 
 ## What this template is for
 
-Retailers face interconnected decisions: which items will sell, which customers are at risk of leaving, what discounts to offer, and how much inventory to stock. Traditionally these are solved in isolation -- demand forecasting in one silo, pricing optimization in another, supply planning is a third. This template shows how to unify them in a single **predict-then-optimize** pipeline using RelationalAI.
+Retailers face interconnected decisions: which items will sell, which customers are at risk of leaving, what discounts to offer, and how much inventory to stock. Traditionally these are solved in isolation -- demand forecasting in one silo, pricing optimization in another, supply planning a third. Solved separately, they pull against each other: a markdown plan that ignores the demand forecast, or an inventory plan that ignores the markdowns, leaves revenue on the table. This template unifies them so predicted demand flows straight into the pricing and inventory decisions that depend on it.
 
-**Start with `retail_planning_local.py`** -- it trains a real sales-regression GNN on a bundled H&M subset (CPU, no external data), aggregates predictions per article, and runs both optimizers. A few minutes end-to-end. It's the quickest way to see the whole pattern working.
+**Graph neural networks predict article demand and customer churn, and those predictions become the parameters of a markdown-pricing and inventory optimization** -- a single predict-then-optimize pipeline on one shared ontology, so the optimizer prices and plans against learned demand rather than static estimates.
 
-**Then adapt the pattern to your own Snowflake data** using `retail_planning.py` as a reference. It trains three GNNs (sales regression, customer-churn classification, user-article link prediction) against the full Kaggle H&M dataset in Snowflake, aggregates all three signals into an adjusted demand estimate, and feeds that into the same two optimizers. The H&M pipeline is the worked example -- the structure (graph concepts → GNN tasks → aggregation bridge → prescriptive constraints) is what carries over to your own retail, pricing, or demand-planning data.
+The bundled H&M dataset is the worked example; the structure -- graph concepts, then GNN tasks, then an aggregation bridge, then prescriptive constraints -- is what carries over to your own retail, pricing, or demand-planning data (see the *Pipeline stages* diagram under *Model overview*).
 
 ## Who this is for
 
@@ -35,7 +35,7 @@ Assumes familiarity with Python, basic ML concepts (classification, regression,
 
 ## What you'll build
 
-- Three GNN predictive models on the H&M knowledge graph (item-sales, user-churn, user-item-purchase)
+- Three graph neural network (GNN) predictive models on the H&M knowledge graph (item-sales, user-churn, user-item-purchase)
 - A bridge layer that aggregates all three GNN outputs into adjusted demand per article
 - A markdown optimization (MILP) that selects discount schedules to maximize revenue + salvage
 - A demand/inventory planning (LP) that minimizes production, holding, and unmet demand costs
@@ -47,6 +47,7 @@ Assumes familiarity with Python, basic ML concepts (classification, regression,
   - `retail_planning_local.py` -- **primary, runnable out of the box.** Trains a sales-regression GNN on the bundled HM_MINI subset and solves both optimizers.
   - `retail_planning.py` -- **reference pattern** for adapting the same pipeline to your own Snowflake data. Trains three GNNs (sales, churn, purchase) against a full H&M dataset in Snowflake.
 - **Model**: Three GNN tasks on the H&M knowledge graph (Customer, Article, Transaction), two prescriptive problems consuming their output.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Sample data**:
   - `data/hm_mini/` -- bundled H&M subset (~10K customers / 5K articles / 9.6K transactions) with sales task splits. This is what the local runner trains on.
   - `data/*.csv` -- optimizer parameters: discounts, weeks, article inventory, production capacity.
@@ -168,10 +169,10 @@ task splits (see Prerequisites).
        ...
 
 Markdown Status: OPTIMAL
-Total revenue (sales + salvage): $62,096.89
+Total revenue (sales + salvage): $62,038.94
 
 Demand Planning Status: OPTIMAL
-Total cost (production + holding + unmet penalty): $8,985.53
+Total cost (production + holding + unmet penalty): $8,761.30
 ```
 
 ## Template structure
@@ -198,9 +199,7 @@ Total cost (production + holding + unmet penalty): $8,985.53
         └── production_capacity.csv    # matching production params
 ```
 
-**Start here**: `retail_planning_local.py` (CPU, no external setup). Use
-`retail_planning.py` (requires GPU) as the adaptation reference when you wire
-this pattern into your own Snowflake data.
+**Start here**: run `python retail_planning_local.py` for the full run end to end (CPU, no external setup), or follow `runbook.md` to reproduce it step by step with the RAI skills. Use `retail_planning.py` (requires GPU) as the adaptation reference when you wire this pattern into your own Snowflake data.
 
 ## Sample data
 
@@ -219,6 +218,10 @@ The H&M core data (customers, articles, transactions) comes from Snowflake, sour
 - **Article** (`article_id`): Products with rich metadata (category hierarchy, color, department, description)
 - **Transaction**: Purchase events linking customers to articles with price and date
 
+**Primary identifiers**: `Customer.customer_id`, `Article.article_id`, and `Week.num` / `Discount.level` identify their rows; the optimizer concepts key on the matching article id (`OptArticle.opt_article_id` and `ProdCapacity.pc_article_id` both equal an `article_id`). A `Transaction` is identified by its `(customer_id, article_id, date)` combination.
+
+**Important invariants**: `opt_article_id` and `pc_article_id` must match real `article_id` values that carry GNN predictions; the discount tiers include a 0% level (feasible starting point) and only increase across weeks (price ladder); prices, costs, inventory, and demand are non-negative.
+
 ### Pipeline stages
 
 ```text
@@ -236,110 +239,18 @@ task) on the bundled HM_MINI CSVs — HM_MINI does not ship churn or purchase
 splits. Churn and purchase are omitted from the local aggregation step.
 `retail_planning.py` runs all three GNNs against the full HM_PYREL data.
 
-### Concepts
-
-**OptArticle** -- Articles in the optimizer's scope, linking GNN predictions to pricing/inventory data.
-
-| Property | Type | Notes |
-|---|---|---|
-| `opt_article_id` | integer | Identifying; matches `article_id` |
-| `name` | string | Human-readable product name |
-| `initial_price` | float | Starting price before discounts |
-| `cost` | float | Unit cost |
-| `initial_inventory` | integer | Available stock |
-| `salvage_rate` | float | Fraction of price recovered for unsold units |
-| `predicted_sales` | float | From item-sales GNN |
-| `avg_buyer_churn` | float | Average churn probability of recent buyers |
-| `avg_purchase_score` | float | Average purchase prediction score across predicted buyers |
-| `adjusted_demand` | float | `predicted_sales * (1 - churn_weight * churn) * (1 + purchase_weight * score)` |
-
-**Discount** -- Markdown tiers with demand response.
-
-| Property | Type | Notes |
-|---|---|---|
-| `level` | integer | Identifying; ordered tier (0 = no discount) |
-| `discount_pct` | float | Percentage off initial price |
-| `demand_lift` | float | Multiplier on base demand |
-
-**Week** -- Planning periods with seasonality.
-
-| Property | Type | Notes |
-|---|---|---|
-| `num` | integer | Identifying; week number |
-| `demand_multiplier` | float | Seasonal adjustment factor |
-
-**ProdCapacity** -- Per-article production parameters for demand planning.
-
-| Property | Type | Notes |
-|---|---|---|
-| `pc_article_id` | integer | Identifying; matches `article_id` |
-| `max_production_per_week` | integer | Production cap |
-| `production_cost` | float | Cost per unit produced |
-| `holding_cost_per_week` | float | Cost per unit in inventory per week |
-| `pc_initial_inventory` | float | Starting stock for demand planner |
+For the full concept and property definitions, see `retail_planning_local.py` (and `retail_planning.py` for the full Snowflake pipeline); `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
-### 1. Train GNN models on the H&M knowledge graph
-
-Three separate GNN models are trained using the Graph / Relationship / PropertyTransformer API. All three share the same graph and feature configuration; only the task relationships and task-type differ:
-
-```python
-# Item-sales regression
-SalesTrain = Relationship(f"{Article} at {Any:timestamp} has {Any:sales}")
-sales_gnn = GNN(
-    exp_database=GNN_EXP_DATABASE, exp_schema=GNN_EXP_SCHEMA,
-    graph=graph, property_transformer=pt,
-    train=SalesTrain, validation=SalesVal,
-    task_type="regression", eval_metric="rmse",
-    has_time_column=True, stream_logs=STREAM_LOGS, seed=SEED,
-    device="cuda", n_epochs=20, train_batch_size=256, lr=0.005, head_layers=2,
-    temporal_strategy="last", max_iters=500,
-)
-sales_gnn.fit()
-Article.sales_predictions = sales_gnn.predictions(domain=SalesTest)
-```
-
-Each GNN learns from the same knowledge graph (Customer-Transaction-Article) but targets different labels: article sales (regression), customer churn (binary classification), and customer-article purchase links (link prediction).
-
-### 2. Bridge: aggregate predictions into optimizer inputs
-
-Predicted sales per article come directly from the item-sales GNN. Churn risk is aggregated per article by averaging the churn probability of each article's recent buyers. Purchase propensity is derived from the link prediction GNN by averaging prediction scores per article. All three signals combine into a single demand estimate:
-
-```python
-model.define(OptArticle.adjusted_demand(
-    OptArticle.predicted_sales
-    * (1 - CHURN_DISCOUNT_WEIGHT * OptArticle.avg_buyer_churn)
-    * (1 + PURCHASE_PROPENSITY_WEIGHT * OptArticle.avg_purchase_score)
-))
-```
-
-Articles bought primarily by high-churn-risk customers get reduced demand, while articles with high purchase propensity get an uplift.
+The pipeline trains GNNs on the H&M knowledge graph, aggregates their predictions into an adjusted-demand estimate per article through a bridge concept, and feeds that estimate into two optimizers — one for markdown pricing, one for production/inventory planning. The same demand number flows into both, so pricing and planning stay consistent with the learned forecast rather than static estimates (see the *Pipeline stages* diagram above).
 
-### 3. Markdown optimization (maximize revenue)
+1. **Train the GNNs.** All models share one graph (Customer-Transaction-Article) and one feature configuration, differing only in task relationship and task type: article sales (regression), customer churn (binary classification), and customer-article purchase links (link prediction). The local runner trains only the sales GNN on the bundled HM_MINI subset; the full runner trains all three against Snowflake.
+2. **Bridge to optimizer inputs.** Predicted sales come straight from the item-sales GNN. Churn risk is averaged per article over each article's recent buyers, and purchase propensity is averaged per article from the link-prediction scores. The three combine into a single `adjusted_demand`: high-churn-buyer articles are marked down in demand, high-purchase-propensity articles are lifted up.
+3. **Markdown optimization (maximize revenue).** A mixed-integer program selects one discount per article per week under a price ladder and inventory limits, bounding sales by the *GNN-predicted* adjusted demand rather than a static estimate, and maximizes sales revenue plus salvage.
+4. **Demand/inventory planning (minimize cost).** A linear program decides production quantities per article per week, tracks inventory with flow conservation against adjusted demand, and minimizes production cost plus holding cost plus an unmet-demand penalty.
 
-A mixed-integer program selects one discount level per article per week. Constraints enforce a price ladder (discounts only increase) and inventory limits. The demand bound uses GNN-predicted demand instead of static estimates:
-
-```python
-problem.satisfy(model.where(...).require(
-    sales_ref <= OptArticle.adjusted_demand
-    * Discount_ref.demand_lift * Week_ref.demand_multiplier * selection_ref
-))
-problem.maximize(revenue + salvage)
-```
-
-### 4. Demand/inventory planning (minimize cost)
-
-A linear program decides production quantities per article per week. Inventory flow conservation tracks stock levels. The objective balances production cost, holding cost, and a penalty for unmet demand:
-
-```python
-dp.satisfy(model.where(...).require(
-    inv_curr == inv_prev + flow_prod_ref
-    - OptArticle.adjusted_demand * flow_week_ref.demand_multiplier
-    + flow_unmet_ref
-))
-dp.minimize(prod_cost_total + hold_cost_total + unmet_cost_total)
-```
+See `retail_planning_local.py` / `retail_planning.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
 ## Customize this template
 
@@ -363,6 +274,13 @@ dp.minimize(prod_cost_total + hold_cost_total + unmet_cost_total)
 - **Multi-site planning**: extend `ProdCapacity` with a site dimension and add cross-site transfer variables.
 - **Scenario analysis**: wrap the demand planner in a loop over different planning horizons (see `demand_planning_temporal` template for the pattern).
 
+### Scale up / productionize
+
+- Move from the bundled `data/hm_mini/` CSVs to your full Snowflake dataset by wiring `retail_planning.py` at your customer / article / transaction tables and task splits (see *Adapting to your own Snowflake data* under Quickstart).
+- Train the three GNNs on a GPU-enabled RAI engine; the local sales-only run is CPU-sized for the mini subset and grows well beyond it on GPU.
+- Pin `relationalai` (see Prerequisites) and keep `SEED` fixed so training and solves stay reproducible across environments.
+- Schedule the pipeline as a recurring job once table references and grants are in place; the GNN experiment schema and change tracking configured in Quickstart carry over unchanged.
+
 ## Troubleshooting
 
 <details>
@@ -419,3 +337,23 @@ continues training server-side; only the client-side log stream is suppressed.
 
 Ensure your Snowflake credentials are configured correctly and that the RAI Native App is installed on your account. Run `rai init` again and verify the connection settings.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Multi-reasoner workflows](https://docs.relational.ai/) — chaining predictive output into prescriptive optimization on a shared ontology.
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)`, aggregations, and `model.select(...)`.
+
+### Reasoner reference
+
+- [Predictive reasoner (GNN)](https://docs.relational.ai/) — the Graph / Relationship / PropertyTransformer API, task types, and training configuration.
+- [Prescriptive reasoner](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives.
+
+### Deeper dives
+
+- [Predict-then-optimize patterns](https://docs.relational.ai/) — using model predictions as parameters inside an optimizer, via an aggregation bridge concept.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/shift_assignment/README.md b/v1/shift_assignment/README.md
index 6ce7ee9e..1497d4bf 100644
--- a/v1/shift_assignment/README.md
+++ b/v1/shift_assignment/README.md
@@ -13,8 +13,6 @@ tags:
   - what-if-analysis
 ---
 
-# Shift Assignment
-
 ## What this template is for
 
 Workforce scheduling is a common operational challenge: given a set of workers, each with their own availability windows, you need to assign them to shifts so that every shift meets its minimum staffing requirements. Doing this manually becomes impractical as the number of workers, shifts, and constraints grows.
@@ -39,6 +37,7 @@ The template also demonstrates scenario analysis by sweeping over different mini
 ## What's included
 
 - `shift_assignment.py` -- main script with ontology, constraints, and scenario analysis
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/workers.csv` -- 10 workers with IDs and names
 - `data/shifts.csv` -- 3 shifts (Morning, Afternoon, Night) with capacity limits
 - `data/availability.csv` -- worker-to-shift availability mappings
@@ -52,6 +51,7 @@ The template also demonstrates scenario analysis by sweeping over different mini
 
 ### Tools
 - Python >= 3.10
+- RelationalAI Python SDK (`relationalai == 1.0.14`)
 
 ## Quickstart
 
@@ -86,119 +86,102 @@ The template also demonstrates scenario analysis by sweeping over different mini
    python shift_assignment.py
    ```
 
-6. Expected output:
+6. Expected output (a few representative rows confirm a successful run):
    ```text
    Assignments per scenario:
        scenario  worker      shift
      coverage_1   Alice    Morning
      coverage_1     Bob      Night
      coverage_1  Carlos  Afternoon
-     coverage_1   Diana    Morning
-     coverage_1   Ethan  Afternoon
-     coverage_1   Frank  Afternoon
-     coverage_1   Grace  Afternoon
-     coverage_1   Henry      Night
-     coverage_1   Irene      Night
+     ...
      coverage_2   Alice  Afternoon
      coverage_2     Bob    Morning
-     coverage_2   Diana  Afternoon
-     coverage_2   Ethan      Night
-     coverage_2   Frank  Afternoon
-     coverage_2   Grace      Night
-     coverage_2   Henry    Morning
-     coverage_2   Irene      Night
-     coverage_2    Jack  Afternoon
+     ...
      coverage_3   Alice    Morning
      coverage_3     Bob    Morning
-     coverage_3  Carlos  Afternoon
-     coverage_3   Diana      Night
-     coverage_3   Ethan      Night
-     coverage_3   Frank    Morning
-     coverage_3   Grace  Afternoon
-     coverage_3   Irene      Night
-     coverage_3    Jack  Afternoon
+     ...
    ```
 
-   Coverage_1 (min_coverage=1) uses 9 workers with one per shift minimum.
-   Coverage_2 (min_coverage=2) uses 9 workers with two per shift, dropping
-   Carlos and adding Jack. Coverage_3 (min_coverage=3) requires 9 workers
-   with three per shift, adding more Morning assignments.
+   The three scenarios sweep `min_coverage` from 1 to 3 workers per shift. This
+   is a feasibility problem with no objective, so the solver returns *any*
+   assignment that satisfies the constraints — the specific worker-to-shift
+   roster varies run to run. What is stable is feasibility: each scenario returns
+   an `OPTIMAL` status with every shift meeting its minimum coverage and no worker
+   over their shift limit.
 
 ## Template structure
+
 ```text
 .
-├── README.md
-├── pyproject.toml
-├── shift_assignment.py
+├── README.md            # this file
+├── pyproject.toml       # dependencies
+├── shift_assignment.py  # main script: ontology, constraints, scenario sweep
 └── data/
-    ├── workers.csv
-    ├── shifts.csv
-    └── availability.csv
+    ├── workers.csv       # 10 workers (id, name)
+    ├── shifts.csv        # 3 shifts (id, name, capacity)
+    └── availability.csv  # worker-to-shift availability pairs
 ```
 
-## How it works
+**Start here**: run `python shift_assignment.py` for the full scenario sweep end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-**1. Define the ontology and load data.** Workers, shifts, and availability are modeled as concepts and relationships:
+## Sample data
 
-```python
-Worker = model.Concept("Worker", identify_by={"id": Integer})
-Worker.name = model.Property(f"{Worker} has {String:name}")
+The bundled data is a small, illustrative workforce — 10 workers, 3 shifts, and their availability pairs — sized to make the constraint interactions easy to read.
 
-Shift = model.Concept("Shift", identify_by={"id": Integer})
-Shift.name = model.Property(f"{Shift} has {String:name}")
-Shift.capacity = model.Property(f"{Shift} has {Integer:capacity}")
+- **`workers.csv`** (10 rows) — one row per worker (`id`, `name`).
+- **`shifts.csv`** (3 rows) — the Morning, Afternoon, and Night shifts, each with a `capacity` (the maximum number of workers it can hold).
+- **`availability.csv`** — `(worker_id, shift_id)` pairs listing which shifts each worker can take. A worker can only be assigned to a shift that appears here.
 
-Worker.available_for = model.Relationship(f"{Worker} is available for {Shift}")
-```
+## Model overview
 
-**2. Define decision variables.** A binary variable `x_assign` indicates whether a worker is assigned to a given shift:
+The model has three concepts plus a `Scenario` concept that parameterizes the coverage sweep. Availability is a standalone relationship, and the assignment decision is a per-scenario decision variable.
 
-```python
-Worker.x_assign = model.Property(f"{Worker} has {Shift} in {Scenario} if {Integer:assigned}")
-problem.solve_for(
-    Worker.x_assign(Shift, Scenario, assigned_ref),
-    type="bin",
-    name=["x", Scenario.name, Worker.name, Shift.name],
-    where=[Worker.available_for(Shift)],
-)
-```
+- **Key entities**: `Worker` — a person who can be assigned to shifts; `Shift` — a shift that needs to be staffed; `Scenario` — one coverage level in the sweep, solved simultaneously with the others.
+- **Primary identifiers**: `Worker.id` and `Shift.id` are integers; `Scenario.name` is a string.
+- **Important invariants**: `Shift.capacity` is a positive integer; each scenario's `min_coverage` must be no larger than the smallest shift capacity or that scenario is infeasible; each worker takes at most `max_shifts` shifts (default 1); a worker can only be assigned to a shift they are available for.
 
-**3. Add constraints.** Three constraints govern the assignment: minimum coverage, maximum shifts per worker, and shift capacity limits. Constraints are stored in named variables so they can be verified after solving:
+For the full concept and property definitions, see `shift_assignment.py`; `runbook.md` builds them step by step with the RAI skills.
 
-```python
-coverage_ic = model.where(
-    Worker.x_assign(Shift, Scenario, assigned_ref),
-).require(sum(Worker, assigned_ref).per(Shift, Scenario) >= Scenario.min_coverage)
-problem.satisfy(coverage_ic)
+## How it works
 
-workload_ic = model.where(
-    Worker.x_assign(Shift, Scenario, assigned_ref),
-).require(sum(Shift, assigned_ref).per(Worker, Scenario) <= max_shifts)
-problem.satisfy(workload_ic)
+The pipeline loads workers, shifts, and availability pairs, adds a `Scenario` concept for the coverage sweep, then hands a single constraint-satisfaction problem to the MiniZinc solver that finds a feasible roster for every scenario at once.
 
-capacity_ic = model.where(
-    Worker.x_assign(Shift, Scenario, assigned_ref),
-).require(sum(Worker, assigned_ref).per(Shift, Scenario) <= Shift.capacity)
-problem.satisfy(capacity_ic)
+```text
+CSV inputs → load Worker / Shift / availability → add Scenario coverage levels
+  → binary assignment variable (per worker-shift-scenario, scoped to availability)
+  → coverage + workload + capacity constraints → solve → verify → per-scenario roster
 ```
 
-**4. Solve and verify.** A single solve handles all scenarios simultaneously. After solving, `problem.verify()` fires the named constraints as integrity constraints to confirm the solution satisfies them:
+1. **Load the data.** Workers and shifts come from their CSVs; availability pairs become a `Worker.available_for(Shift)` relationship that scopes which assignments are even possible.
+2. **Set up the decision.** A binary `x_assign` variable indicates whether a worker takes a given shift in a given scenario. Each coverage level (`coverage_1` / `_2` / `_3`) is a `Scenario` with a `min_coverage`, and the variable is scoped to the availability relationship so unavailable pairs are never considered.
+3. **Constrain the roster.** Three constraints govern every scenario: each shift meets its `min_coverage`, each worker takes no more than `max_shifts` shifts (default 1), and no shift exceeds its `capacity`. The constraints are named so they can be re-checked after solving.
+4. **Solve and verify.** A single solve handles all scenarios simultaneously; this is a feasibility problem with no objective, so the solver returns any assignment satisfying every constraint. `problem.verify()` then re-fires the named constraints as integrity checks to confirm the solution holds.
 
-```python
-problem.solve("minizinc", time_limit_sec=60)
-problem.solve_info().display()
-problem.verify(coverage_ic, workload_ic, capacity_ic)
-model.require(problem.termination_status() == "OPTIMAL")
-```
+See `shift_assignment.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
 ## Customize this template
 
-- **Add more shifts or workers** by editing the CSV files. The model scales automatically.
-- **Change the max shifts per worker** by adjusting the `max_shifts` parameter.
+### Use your own data
+
+- Replace the CSVs in `data/` with your own; keep the column names (`workers.csv`: `id`, `name`; `shifts.csv`: `id`, `name`, `capacity`; `availability.csv`: `worker_id`, `shift_id`). The model scales automatically to more workers, shifts, and availability pairs.
+- Every `worker_id` and `shift_id` in `availability.csv` must match an `id` in the other two files, or those pairs silently drop out of the available-for relationship.
+
+### Tune parameters
+
+- **Max shifts per worker** — adjust the `max_shifts` parameter (default `1`) near the top of the decision-problem section.
+- **Coverage levels** — edit the `scenario_data` list to sweep different `min_coverage` values, or add more scenarios.
+
+### Extend the model
+
 - **Add shift preferences** by introducing a preference score and converting from feasibility to optimization (minimize total dissatisfaction).
 - **Add skills or qualifications** by introducing a skill-matching relationship between workers and shifts.
 - **Switch to optimization** by adding an objective (e.g., maximize total coverage or minimize cost) with `problem.minimize()` or `problem.maximize()`.
 
+### Scale up / productionize
+
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)` and adjust the loaders accordingly.
+- The feasibility CSP scales to whatever fits the solver's time budget (`time_limit_sec`, default 60). For a scheduled pipeline, pin the `relationalai` version and add an objective so results are reproducible rather than any-feasible.
+
 ## Troubleshooting
 
 <details>
@@ -234,3 +217,19 @@ model.require(problem.termination_status() == "OPTIMAL")
 - As an alternative, you can try switching to `"highs"` in the `problem.solve()` call, though HiGHS is designed for linear/MIP problems.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Prescriptive reasoning](https://docs.relational.ai/) — constraint satisfaction and optimization: decision variables, constraints, objectives.
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.select(...)` / `model.where(...)` / aggregations, used to extract the assignments after solving.
+
+### Reasoner reference
+
+- [Solver management](https://docs.relational.ai/) — problem types, solver selection (MiniZinc, HiGHS), and solve execution.
+- [Scenario modeling](https://docs.relational.ai/) — parameterizing a single solve across multiple scenarios.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/shipment_compliance/README.md b/v1/shipment_compliance/README.md
index 6f52889a..6698fe66 100644
--- a/v1/shipment_compliance/README.md
+++ b/v1/shipment_compliance/README.md
@@ -13,8 +13,6 @@ tags:
   - Aggregation
 ---
 
-# Shipment Compliance
-
 ## What this template is for
 
 This template uses **rules-based reasoning** to define derived business rules for shipment compliance, sourcing risk, and demand escalation.
@@ -45,6 +43,7 @@ The four rules demonstrate different rule patterns:
 ## What's included
 
 - `shipment_compliance.py` -- Main script defining the data model and four rules
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/suppliers.csv` -- Supplier names and reliability scores
 - `data/skus.csv` -- Product and component catalog
 - `data/shipments.csv` -- Shipment records with status and delay
@@ -61,7 +60,7 @@ The four rules demonstrate different rule patterns:
 
 ### Tools
 - Python >= 3.10
-- RelationalAI Python SDK (`relationalai == 1.12.0`)
+- RelationalAI Python SDK (`relationalai == 1.13.0`)
 
 ## Quickstart
 
@@ -96,84 +95,108 @@ The four rules demonstrate different rule patterns:
    python shipment_compliance.py
    ```
 
+6. Expected output (a few lines confirm a successful run):
+
+   The script prints the entities each rule flags. On the bundled data the four
+   rules catch **2 late shipments**, **6 at-risk shipments**, **2 single-sourced
+   BOM inputs**, and **4 escalated demands**:
+
+   ```text
+   === Rule 1: Late Shipments (delay_days > 0) ===
+   (2 rows)
+
+   === Rule 2: At-Risk Shipments (undelivered + unreliable supplier) ===
+   (6 rows)
+
+   === Rule 3: Single-Sourced BOM Inputs (only 1 operation route) ===
+   (2 rows)
+
+   === Rule 4: Escalated Demands (HIGH or URGENT priority) ===
+   (4 rows)
+   ```
+
+   See `runbook.md` for the full record-by-record walkthrough of each flag.
+
 ## Template structure
 
 ```text
 .
-├── README.md
-├── pyproject.toml
-├── shipment_compliance.py
+├── README.md               # this file
+├── pyproject.toml          # dependencies
+├── shipment_compliance.py  # main script: data model + four derived rules
+├── runbook.md              # analyst-facing paste-testable walkthrough
 └── data/
-    ├── suppliers.csv
-    ├── skus.csv
-    ├── shipments.csv
-    ├── operations.csv
-    ├── bill_of_materials.csv
-    └── demands.csv
+    ├── suppliers.csv          # 5 suppliers (id, name, reliability_score)
+    ├── skus.csv               # 6 SKUs (id, name, product_type)
+    ├── shipments.csv          # 12 shipments (id, sku_id, supplier_id, status, delay_days)
+    ├── operations.csv         # 7 operations (input/output SKU, cost, capacity)
+    ├── bill_of_materials.csv  # 6 BOM lines (input SKU, site, quantity)
+    └── demands.csv            # 8 demand orders (SKU, quantity, priority)
 ```
 
-## How it works
+**Start here**: run `python shipment_compliance.py` for the full run end to end — authoring all four rules and printing the flagged records — or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-### 1. Define concepts and load data
+## Sample data
 
-The model defines six concepts (Supplier, SKU, Shipment, Operation, BillOfMaterials, Demand) and loads each from CSV. Relationships link shipments to suppliers and SKUs, operations to input/output SKUs, etc.
+The bundled data is a small, illustrative sourcing-and-fulfillment model — 6 concepts sized so each rule pattern is easy to trace by hand.
 
-Closed vocabularies are declared as `model.Enum` types and populated by name from the raw CSV strings (so `"DELIVERED"` in `shipments.csv` becomes the `ShipmentStatus.DELIVERED` member):
+- **`suppliers.csv`** (5 rows) — supplier `name` and `reliability_score` (a fraction in `[0, 1]`); two suppliers score below the `0.8` at-risk threshold.
+- **`skus.csv`** (6 rows) — the product and component catalog (`name`, `product_type`).
+- **`shipments.csv`** (12 rows) — each shipment links to a SKU and a supplier, and carries a `status` and `delay_days`.
+- **`operations.csv`** (7 rows) — production/shipping routes, each consuming an input SKU and producing an output SKU.
+- **`bill_of_materials.csv`** (6 rows) — input-SKU requirements per site.
+- **`demands.csv`** (8 rows) — demand orders for SKUs, each with a `quantity` and a `priority`.
 
-```python
-class ShipmentStatus(model.Enum):
-    PENDING = 1
-    IN_TRANSIT = 2
-    DELIVERED = 3
+`status` and `priority` are closed vocabularies (`ShipmentStatus`, `Priority`) loaded from the raw CSV strings by member name.
 
-Shipment.status = Property(f"{Shipment} has {ShipmentStatus:status}")
+## Model overview
 
-model.define(
-    s := Shipment.new(id=shipment_data.id, ...),
-    s.status(ShipmentStatus.lookup(shipment_data.status)),
-)
-```
+Six concepts model a small supply chain, linked by SKU and supplier references. The four business rules are derived boolean flags added back onto the concepts.
 
-Rules then compare against members rather than raw strings -- typo-proof and discoverable -- and queries read the label back with `.name` (e.g. `Shipment.status.name.alias("status")`).
+- **Key entities**: `Supplier` — a company that supplies parts; `SKU` — a stock-keeping unit tracked in the supply chain; `Shipment` — a delivery of a SKU from a supplier; `Operation` — a production or shipping route that transforms SKUs; `BillOfMaterials` — an input-SKU requirement for production; `Demand` — a quantity requirement for a specific SKU.
+- **Primary identifiers**: an integer `id` on every concept.
+- **Important invariants**: `Supplier.reliability_score` is a fraction in `[0, 1]`; `Shipment.status` is a `ShipmentStatus` member (`PENDING` / `IN_TRANSIT` / `DELIVERED`); `Demand.priority` is a `Priority` member (`LOW` / `STANDARD` / `HIGH` / `URGENT`); `delay_days`, `quantity`, and `input_quantity` are non-negative. Each rule adds a derived boolean flag back onto its concept: `Shipment.is_late` (Rule 1), `Shipment.is_at_risk` (Rule 2), `BillOfMaterials.is_single_sourced` (Rule 3), and `Demand.is_escalated` (Rule 4).
 
-One caveat when bringing your own data: `lookup()` cannot validate values that arrive from data columns. A CSV value that matches no member name silently maps to a nonexistent entity, and those rows simply drop out of every member-comparison rule. Keep the enum declarations in sync with your data's vocabulary. (Literal strings in code are checked at construction and raise a `ValueError` naming the valid members.)
+For the full concept and property definitions, see `shipment_compliance.py`; `runbook.md` builds them step by step with the RAI skills.
 
-### 2. Define rules as derived Relationships
+## How it works
 
-Each rule uses the `model.where(...).define(...)` pattern to create a boolean flag:
+The pipeline loads six concepts from CSV, maps the closed-vocabulary columns to enums, then declares four derived rules as boolean flags and queries the entities each one catches. No solver is involved — the rules are pure declarative logic that re-evaluates as the data changes.
 
-```python
-# Simple threshold rule
-Shipment.is_late = Relationship(f"{Shipment} is late")
-model.where(Shipment.delay_days > 0).define(Shipment.is_late())
+```text
+CSV inputs → load Supplier / SKU / Shipment / Operation / BOM / Demand
+  → map status & priority strings to enum members → define four rule flags → query flagged entities
+```
 
-# Cross-entity rule (joins Shipment -> Supplier)
-Shipment.is_at_risk = Relationship(f"{Shipment} is at risk")
-model.where(
-    Shipment.status != ShipmentStatus.DELIVERED,
-    Shipment.supplier(SupplierRef),
-    SupplierRef.reliability_score < 0.8,
-).define(Shipment.is_at_risk())
+1. **Load the data and map enums.** Six concepts load from CSV, with relationships linking shipments to their SKU and supplier, operations to their input/output SKUs, and so on. The `status` and `priority` columns are closed vocabularies declared as `model.Enum` types (`ShipmentStatus`, `Priority`) and populated by name — so `"DELIVERED"` in the CSV becomes the `ShipmentStatus.DELIVERED` member. Rules then compare against members rather than raw strings, which is typo-proof and discoverable, and queries read the label back with `.name`. One caveat when bringing your own data: `lookup()` cannot validate values arriving from data columns — a CSV value matching no member name silently maps to a nonexistent entity and drops out of every member-comparison rule, so keep the enum declarations in sync with your data's vocabulary.
+2. **Define four rule patterns.** Each rule uses the `model.where(...).define(...)` pattern to set a boolean flag, and together they show four shapes: a simple threshold (Rule 1: `delay_days > 0`), a cross-entity join (Rule 2: undelivered shipments from suppliers scoring below `0.8`), an aggregation (Rule 3: BOM inputs produced by exactly one operation route), and OR semantics via multiple `define()` calls on the same relationship (Rule 4: `HIGH` or `URGENT` priority).
+3. **Query the flags.** Each rule is queried with `model.select(...).where(Concept.rule_flag())` to display the matching entities.
 
-# Aggregation rule (count operations per BOM)
-route_count = aggregates.count(Operation).per(BOM).where(...)
-model.where(route_count == 1).define(BOM.is_single_sourced())
+See `shipment_compliance.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
-# OR semantics (multiple define calls on same Relationship)
-model.where(Demand.priority == Priority.HIGH).define(Demand.is_escalated())
-model.where(Demand.priority == Priority.URGENT).define(Demand.is_escalated())
-```
+## Customize this template
 
-### 3. Query flagged entities
+### Use your own data
 
-Each rule is queried with `model.select(...).where(Concept.rule_flag())` to display matching entities.
+- Replace the CSVs in `data/` with your own; keep the column names listed in *Sample data* above. Every foreign-key column (`sku_id`, `supplier_id`, `input_sku_id`, `output_sku_id`) must match an `id` in the referenced file, or those rows drop out of the join.
+- The `status` and `priority` columns are enum-mapped: values must exactly match the `ShipmentStatus` / `Priority` member names. `lookup()` cannot validate values that arrive from data columns — unrecognized values silently map to a nonexistent member and drop out of every member-comparison rule. Extend the enum if your feed has more values.
 
-## Customize this template
+### Tune parameters
+
+- **At-risk threshold** — Rule 2 flags suppliers scoring below `0.8`; adjust the `reliability_score < 0.8` comparison to match your risk tolerance.
+- **Escalation tiers** — Rule 4 fires on `HIGH` or `URGENT`; add or remove `define()` calls to change which priorities escalate.
+
+### Extend the model
 
 - **Add more rules**: Define additional Relationships for new business conditions (e.g., `Supplier.is_high_risk` based on reliability thresholds).
 - **Chain rules**: Reference one rule's output in another rule's definition (e.g., flag demands as critical if they are escalated AND depend on a single-sourced BOM input).
 - **Connect to optimization**: Use rule flags as constraint filters in a prescriptive formulation (e.g., exclude at-risk shipments from allocation).
 
+### Scale up / productionize
+
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)` and load the concepts from your tables.
+- Rules are pure declarative logic and re-evaluate as the underlying data changes, so they slot naturally into a change-data-capture pipeline. Pin the `relationalai` version for reproducibility.
+
 ## Troubleshooting
 
 <details>
@@ -187,3 +210,27 @@ Make sure you activated the virtual environment and ran `python -m pip install .
 
 Run `rai init` to configure your Snowflake connection. Verify that the RAI Native App is installed and your user has the required permissions.
 </details>
+
+<details>
+<summary>A rule catches no records (or too few)</summary>
+
+- Confirm the enum values in `status` / `priority` exactly match the `ShipmentStatus` / `Priority` member names — mismatched strings silently drop rows.
+- Sanity-check the input data: Rule 2 needs undelivered shipments from suppliers scoring below `0.8`; Rule 3 needs an input SKU produced by exactly one operation.
+- Verify foreign keys line up across CSVs (`sku_id`, `supplier_id`, `input_sku_id` match an `id` in the referenced file).
+</details>
+
+## Learn more
+
+### Core concepts
+
+- [Rules-based reasoning](https://docs.relational.ai/) — authoring business logic as derived properties: validation, classification, and alerting.
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...).define(...)` and `model.select(...)`, the patterns this template is built on.
+
+### Language / modeling reference
+
+- [Derived relationships and aggregation](https://docs.relational.ai/) — the `define()` pattern and `aggregates.count(...).per(...)` used in Rule 3.
+- [Enum vocabularies](https://docs.relational.ai/) — `model.Enum` types and `lookup()` for closed-value fields.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/smoker_status_prediction/README.md b/v1/smoker_status_prediction/README.md
index ad6db0e4..b136474c 100644
--- a/v1/smoker_status_prediction/README.md
+++ b/v1/smoker_status_prediction/README.md
@@ -7,7 +7,7 @@ industry: "Healthcare & Life Sciences"
 reasoning_types:
   - Predictive
 tags:
-  - GNN
+  - Graph Neural Network (GNN)
   - Binary Classification
   - Node Classification
   - Healthcare
@@ -37,6 +37,7 @@ Assumes familiarity with Python and basic ML concepts (binary classification, tr
 - **Scripts**:
   - `smoker_status_prediction_local.py` -- **primary, runnable out of the box.** Loads CSVs from `data/` via `model.data()`.
   - `smoker_status_prediction.py` -- **reference pattern** for adapting the same pipeline to Snowflake-hosted tables.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Sample data** (`data/`) -- bundled demo dataset for end-to-end runs; predictions are illustrative of the GNN methodology, not clinically meaningful (see [Sample data](#sample-data) for what's real vs. constructed):
   - `people.csv` -- 38,984 individuals with demographic and medical features.
   - `related.csv` -- 58,355 connection pairs between people.
@@ -258,7 +259,7 @@ Local run complete.
     └── test.csv            # 3,899 rows
 ```
 
-**Start here**: `smoker_status_prediction_local.py` (no external setup beyond Snowflake grants). Use `smoker_status_prediction.py` as the adaptation reference when you wire this pattern into your own Snowflake data.
+**Start here**: run `python smoker_status_prediction_local.py` for the full run end to end (no external setup beyond Snowflake grants), or follow `runbook.md` to reproduce it step by step with the RAI skills. Use `smoker_status_prediction.py` as the adaptation reference when you wire this pattern into your own Snowflake data.
 
 ## Sample data
 
@@ -273,10 +274,9 @@ The dataset contains medical and demographic attributes for a population of indi
 
 ## Model overview
 
-### Key entities
-
-- **People** (`Id`): individuals with demographic and medical attributes.
-- **Related**: pairs of people, used as the edge list of the GNN graph.
+- **Key entities**: `People` (individuals with demographic and medical attributes), `Related` (pairs of people, used as the edge list of the graph neural network (GNN) graph), and the split tables `TrainTable` / `ValidationTable` / `TestTable`.
+- **Primary identifiers**: `People.Id` (integer, unique per person). `Related`, `TrainTable`, `ValidationTable`, and `TestTable` have no key of their own — they join back to `People` by `Id`.
+- **Important invariants**: `Id` values in `Related` and the split tables must reference an existing `People.Id`; the `smoking` label is binary (`0` / `1`); `TestTable.smoking` is held out and never fed to the model; the three splits partition the labeled population (31,187 train / 3,898 validation / 3,899 test).
 
 ### Pipeline stages
 
@@ -289,113 +289,19 @@ People + Related (CSVs or Snowflake tables)
   → (Optional) Register and load the trained model
 ```
 
-### Concepts
-
-**People** -- individuals with demographic and medical attributes.
-
-| Property | Type | Notes |
-|---|---|---|
-| `Id` | integer | Identifying; unique per person |
-| `age` | integer | Age in years |
-| `height(cm)` | integer | Height in centimeters |
-| `weight(kg)` | integer | Weight in kilograms |
-| `systolic` | integer | Systolic blood pressure |
-| `relaxation` | integer | Diastolic blood pressure |
-| `fasting blood sugar` | integer | Fasting blood glucose level |
-| `Cholesterol` | integer | Total cholesterol |
-| `triglyceride` | integer | Triglyceride level |
-| `HDL` | integer | High-density lipoprotein |
-| `LDL` | integer | Low-density lipoprotein |
-| `hemoglobin` | float | Hemoglobin level |
-| `Urine protein` | integer | Urine protein indicator |
-| `serum creatinine` | float | Serum creatinine level |
-| `AST` | integer | Aspartate aminotransferase (liver enzyme) |
-| `ALT` | integer | Alanine aminotransferase (liver enzyme) |
-| `Gtp` | integer | Gamma-glutamyl transferase (liver enzyme) |
-| `dental caries` | integer | Binary indicator (0 / 1) |
-
-**Related** -- pairs of connected people; used to construct edges in the GNN graph. No primary key.
-
-| Property | Type | Notes |
-|---|---|---|
-| `person1` | integer | Foreign key into `People.Id` |
-| `person2` | integer | Foreign key into `People.Id` |
-
-**TrainTable / ValidationTable / TestTable** -- split tables joined to `People` by `Id` to build the train, validation, and test relationships. `TestTable.smoking` is held out from the model.
-
-| Property | Type | Notes |
-|---|---|---|
-| `Id` | integer | Foreign key into `People.Id` |
-| `smoking` | integer | Binary label (0 / 1); held out for `TestTable` |
+For the full concept and property definitions, see `smoker_status_prediction_local.py` (and `smoker_status_prediction.py` for the Snowflake pipeline); `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
-### 1. Build the graph
-
-Each row of `Related` defines a directed edge from one `People` instance to another. Because both endpoints are the same concept, the destination uses `.ref()`:
-
-```python
-PeopleRef = People.ref()
-model.define(Edge.new(src=People, dst=PeopleRef)).where(
-    People.Id == Related.person1,
-    PeopleRef.Id == Related.person2,
-)
-```
-
-### 2. Configure features
-
-`PropertyTransformer` lists the medical and demographic features as continuous, treats the binary `dental caries` indicator as a category, and drops the `Id` so it isn't fed into the model:
-
-```python
-pt = PropertyTransformer(
-    continuous=[
-        People.age,
-        getattr(People, "height(cm)"),
-        getattr(People, "weight(kg)"),
-        ...
-    ],
-    category=[getattr(People, "dental caries")],
-    drop=[People.Id],
-)
-```
-
-The `getattr()` calls handle column names with special characters (spaces, parentheses) that aren't valid Python identifiers. The schema is preserved as-is so the same names work in Snowflake queries against the underlying tables.
+The pipeline turns the `PEOPLE` table into graph nodes and the `RELATED` pairs into edges, configures the medical/demographic features, defines the train/validation/test task, then trains a binary-classification GNN and predicts smoking status on the held-out test cohort (see the *Pipeline stages* diagram above).
 
-### 3. Define the task
+1. **Build the graph.** Each `RELATED` row becomes a directed edge from one `People` node to another. Because both endpoints are the same concept, the destination endpoint uses a `.ref()` of `People`.
+2. **Configure features.** A `PropertyTransformer` lists the medical and demographic columns as continuous features, treats the binary `dental caries` indicator as a category, and drops `Id` so the identifier isn't fed into the model. Column names with spaces or parentheses (`height(cm)`, `fasting blood sugar`) are accessed via `getattr`, and the schema is preserved as-is so the same names work against the underlying Snowflake tables.
+3. **Define the task.** A node-classification task pairs each labeled `People` row with its smoking status via train and validation relationships; the test relationship omits the label because it is held out.
+4. **Train and predict.** The GNN is instantiated with the graph, the transformer, and the train/validation relationships, fit, then used to attach predictions over the held-out test cohort back onto each `People` node.
+5. **(Optional) Register and load.** The bottom of each script has a commented-out block that registers the trained model in the Snowflake Model Registry and loads it back into a fresh `GNN` instance to predict without retraining.
 
-A simple node-classification task: each labeled row pairs a `People` instance with its smoking status. The `Test` relationship omits the label since it's held out.
-
-```python
-Train = Relationship(f"{People} has {Any:smoking}")
-model.define(Train(People, TrainTable.smoking)).where(
-    People.Id == TrainTable.Id
-)
-
-Test = Relationship(f"{People}")
-model.define(Test(People)).where(
-    People.Id == TestTable.Id
-)
-```
-
-### 4. Train and predict
-
-Instantiate the GNN with the graph, the `PropertyTransformer`, and the Train / Validation relationships, fit it, then attach predictions over the held-out Test cohort to each `People` instance:
-
-```python
-gnn = GNN(
-    exp_database=GNN_EXP_DATABASE, exp_schema=GNN_EXP_SCHEMA,
-    graph=gnn_graph, property_transformer=pt,
-    train=Train, validation=Validation,
-    task_type="binary_classification", eval_metric="roc_auc",
-    device="cuda", n_epochs=5, lr=0.005, train_batch_size=256,
-)
-gnn.fit()
-People.predictions = gnn.predictions(domain=Test)
-```
-
-### 5. (Optional) Register and load
-
-The bottom of each script has a commented-out block that registers the trained model in the Snowflake Model Registry, then loads it into a fresh `GNN` instance and predicts without retraining. Uncomment it if you want to register a model, load it back, and run predictions without retraining.
+See `smoker_status_prediction_local.py` / `smoker_status_prediction.py` for the implementation and `runbook.md` for the skill-driven reproduction.
 
 ## Customize this template
 
@@ -404,7 +310,7 @@ The bottom of each script has a commented-out block that registers the trained m
 - Replace the CSVs in `data/` with your own equivalent files (people, edges, splits). Column names need to match the `PropertyTransformer`, or you'll need to edit the transformer.
 - For Snowflake adaptation, edit the `DATABASE`, `SCHEMA`, `TASK_SCHEMA`, and `GNN_EXP_*` constants at the top of `smoker_status_prediction.py`.
 
-### Tune the model
+### Tune parameters
 
 - `n_epochs` -- increase for better convergence on a larger dataset.
 - `lr` -- lower if training loss bounces.
@@ -419,6 +325,13 @@ For the full hyperparameter list, see the [Configure a GNN](https://docs.relatio
 - **Try a multiclass task**: if your label has more than two values (e.g. never / light / heavy smoker), change `task_type="multiclass_classification"` and use `eval_metric="macro_f1"` or `"accuracy"`.
 - **Register the model** for reuse: uncomment the bonus section at the bottom of either script.
 
+### Scale up / productionize
+
+- Move from the bundled CSVs to Snowflake-hosted tables with `smoker_status_prediction.py` (see *Adapting to your own Snowflake data* under Quickstart); the graph, features, and task setup are unchanged.
+- Train on a GPU-enabled engine (`device="cuda"`) for larger populations; CPU is fine for the bundled ~39K-person demo.
+- Pin `relationalai` (see Prerequisites) so runs stay reproducible across environments.
+- Register the trained model in the Snowflake Model Registry (the optional block at the bottom of each script) so downstream jobs load and predict without retraining.
+
 ## Troubleshooting
 
 <details>
@@ -458,3 +371,20 @@ GRANT CREATE MODEL      ON SCHEMA   identifier($schema_experiments) TO APPLICATI
 
 Ensure your Snowflake credentials are configured correctly and that the RAI Native App is installed on your account. Run `rai init` again and verify the connection settings.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Predictive reasoning (GNN)](https://docs.relational.ai/) — graph neural network modeling on an ontology: nodes, edges, and features.
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.define(...)` / `model.where(...)`, used to build the edge list and split relationships.
+
+### Reasoner reference
+
+- [Configure a GNN](https://docs.relational.ai/build/guides/reasoning/predictive/configure-a-GNN) — the full hyperparameter list for `GNN(...)`.
+- [PropertyTransformer](https://docs.relational.ai/) — declaring continuous vs. category features and dropping identifier columns.
+- [Model Registry](https://docs.relational.ai/) — registering, loading, and reusing a trained model without retraining (the optional bonus block).
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/sprint_scheduling/README.md b/v1/sprint_scheduling/README.md
index cf6a25d1..8198a001 100644
--- a/v1/sprint_scheduling/README.md
+++ b/v1/sprint_scheduling/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Sprint Scheduling"
-description: "Assign backlog issues to developers across sprints, minimizing weighted completion time while respecting capacity and skill constraints."
+description: "Assign backlog issues to developers across sprints, minimizing weighted completion time while respecting capacity and skill constraints. Uses mixed-integer programming (MIP)."
 featured: false
 experience_level: intermediate
 industry: "Technology & Telecom"
@@ -9,12 +9,10 @@ reasoning_types:
 tags:
   - Assignment
   - Scheduling
-  - MIP
-  - Temporal-Filtering
+  - Mixed-Integer Programming (MIP)
+  - Temporal Filtering
 ---
 
-# Sprint Scheduling
-
 ## What this template is for
 
 Software development teams need to decide which developer works on which issue in which sprint. Manually balancing priorities, story points, skill requirements, and capacity across multiple sprints is error-prone and time-consuming, especially as the backlog grows. An optimization model can produce an assignment plan that minimizes delay on high-priority work while keeping every developer within their capacity.
@@ -32,21 +30,20 @@ This template assigns 30 backlog issues to 8 developers across 4 two-week sprint
 
 ## What you'll build
 
-- Load developers, sprints, issues, and skill mappings from CSV files
-- Filter issues by epoch timestamp to scope the backlog to a planning horizon
-- Map each issue's `created_at` epoch to a target sprint (earliest eligible sprint)
-- Build a cross-product `Assignment` concept linking developers, issues, and sprints where skill constraints hold
-- Define binary decision variables for each valid (developer, issue, sprint) assignment
-- Enforce that each issue is assigned exactly once and developer capacity is not exceeded per sprint
-- Minimize weighted completion time so high-priority issues land in earlier sprints
-- Run scenario analysis across capacity multiplier levels (0.35, 0.5, 1.0) to see the impact of reduced team capacity
-- Solve with HiGHS and display the assignment plan per scenario
+- A sprint assignment plan that places each in-scope issue with exactly one developer in one sprint, minimizing weighted completion time within capacity and skill limits, produced by **prescriptive reasoning** (a mixed-integer program).
+- An `Assignment` decision concept whose binary variables span only the valid (developer, issue, sprint) combinations, pruned by an epoch-based temporal filter and skill-matching `.where()` clauses.
+- A scenario comparison across capacity-multiplier levels (0.35, 0.5, 1.0), showing how reduced team capacity moves the objective and tips the problem into infeasibility.
+- Per-scenario stdout: solver status, objective value, planning-horizon summary, and the assignment table.
+
+Built using **prescriptive reasoning** (mixed-integer programming solved with HiGHS), with epoch-based temporal filtering to scope the backlog.
 
 ## What's included
 
-- **Script**: `sprint_scheduling.py` -- end-to-end model, solve, and results
-- **Data**: `data/developers.csv`, `data/sprints.csv`, `data/issues.csv`, `data/skills.csv`
-- **Config**: `pyproject.toml`
+- **Model**: developers, sprints, issues, and skill mappings as concepts, plus a cross-product `Assignment` decision concept with binary assignment variables, capacity and once-per-issue constraints, and a weighted-completion-time objective.
+- **Runner**: `sprint_scheduling.py` -- a single Python script that loads data, builds the model, and sweeps the capacity scenarios end to end.
+- **Runbook**: `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: four CSVs under `data/` describing 8 developers, 4 sprints, 30 backlog issues, and developer-team skills. See *Sample data* below.
+- **Outputs**: per-scenario solver status, objective, planning-horizon summary, and assignment table printed to stdout, plus a scenario-analysis summary.
 
 ## Prerequisites
 
@@ -144,122 +141,80 @@ This template assigns 30 backlog issues to 8 developers across 4 two-week sprint
 
 ```text
 .
-├── README.md
-├── pyproject.toml
-├── sprint_scheduling.py
+├── README.md              # this file
+├── pyproject.toml         # dependencies
+├── sprint_scheduling.py   # main script (load, model, scenario sweep, results)
 └── data/
-    ├── developers.csv
-    ├── sprints.csv
-    ├── issues.csv
-    └── skills.csv
+    ├── developers.csv     # 8 developers with team and per-sprint capacity
+    ├── sprints.csv        # 4 two-week sprints with epoch start/end dates
+    ├── issues.csv         # 30 backlog issues with epoch created_at, priority, team
+    └── skills.csv         # developer-team skill mappings
 ```
 
-## How it works
-
-### 1. Epoch filtering -- scope the backlog to the planning horizon
+**Start here**: run `python sprint_scheduling.py` for the full load, model, and capacity-scenario sweep end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-Issues have a `created_at` column storing Unix epoch seconds. The script converts the planning horizon boundaries to epochs and filters:
+## Sample data
 
-```python
-planning_start = "2024-10-01"
-planning_end = "2024-11-26"
+The bundled data is synthetic and illustrative -- a small backlog sized to teach the assignment and temporal-filtering patterns, not to mirror a specific team's tracker.
 
-start_epoch = int(datetime.strptime(planning_start, "%Y-%m-%d").timestamp())
-end_epoch = int(datetime.strptime(planning_end, "%Y-%m-%d").timestamp())
+- **`developers.csv`** (8 rows) -- developers with a `team` and `capacity_points_per_sprint` (14-20 points each).
+- **`sprints.csv`** (4 rows) -- two-week sprints, each with a `number` and Unix-epoch `startdate` / `enddate`.
+- **`issues.csv`** (30 rows) -- backlog issues with `story_points`, `priority` (1 = most urgent), `team`, and a Unix-epoch `created_at`. Raw data spans September-November 2024; the planning-horizon filter keeps the 25 issues created within the window.
+- **`skills.csv`** -- which teams each developer can work on. Most developers cover one team; Grace and Hank carry cross-team skills.
 
-filtered_issues = issues_df[
-    (issues_df["created_at"] >= start_epoch) & (issues_df["created_at"] <= end_epoch)
-].copy()
-```
+## Model overview
 
-This keeps only issues created within the planning horizon. Issues created before or after are excluded from scheduling.
+The model has four source concepts loaded from CSV, plus a derived `Assignment` decision concept that forms the optimizer's search space. All identifiers are integer keys except the composite `Assignment`, which is identified by its three linked entities.
 
-### 2. Epoch-to-categorical-period mapping -- assign target sprints
+- **Key entities**: `Developer` — an engineer with a team affiliation and a per-sprint story-point capacity; `Sprint` — a two-week planning period with epoch boundaries; `Issue` — a backlog item to schedule; `Skill` — a developer-team capability row; and the decision concept `Assignment` — a valid (developer, issue, sprint) placement.
+- **Primary identifiers**: integer `id` on `Developer`, `Sprint`, `Issue`, and `Skill`; `Assignment` is identified by its `(developer, issue, sprint)` triple.
+- **Important invariants**: `story_points`, `priority`, and `capacity_points_per_sprint` are positive integers; each issue is assigned exactly once; a developer's assigned story points per sprint stay within capacity (scaled by the scenario's `capacity_multiplier`); a sprint can only host issues whose target sprint is at or before it.
 
-Unlike the date-to-integer mapping in the demand planning template, this template maps epochs to categorical sprint periods. Each issue is assigned to its earliest eligible sprint based on when it was created:
+For the full concept and property definitions, see `sprint_scheduling.py`; `runbook.md` builds them step by step with the RAI skills.
 
-```python
-def map_to_sprint(created_at_epoch):
-    for _, sprint in sprints_df.iterrows():
-        if created_at_epoch < sprint["startdate"]:
-            return int(sprint["number"])
-        if sprint["startdate"] <= created_at_epoch < sprint["enddate"]:
-            return int(sprint["number"])
-    return int(sprints_df["number"].max())
+## How it works
 
-filtered_issues["target_sprint_number"] = filtered_issues["created_at"].apply(map_to_sprint)
+```text
+CSV inputs → epoch filter → target-sprint mapping → assignment domain → constraints + objective → solve → results
 ```
 
-Issues created during Sprint 2 cannot be assigned to Sprint 1 (only Sprint 2 or later). Issues created before `planning_start` are excluded by the epoch filter in step 1.
-
-### 3. Assignment domain with skill constraints
+**1. Epoch filtering -- scope the backlog to the planning horizon.** Issues carry a `created_at` column in Unix epoch seconds. The script converts the planning-horizon boundaries to epochs and keeps only issues created within the window; issues created before or after are excluded from scheduling.
 
-The `Assignment` concept is a cross-product of developers, issues, and sprints, filtered by two conditions: the developer must have the matching team skill, and the sprint must be at or after the issue's target sprint:
+**2. Epoch-to-categorical-period mapping -- assign target sprints.** Each in-scope issue is mapped to its earliest eligible sprint based on when it was created. An issue created during Sprint 2 cannot be scheduled into Sprint 1 -- only Sprint 2 or later.
 
-```python
-Assignment = Concept("Assignment")
-Assignment.developer = Property(f"{Assignment} has {Developer}", short_name="developer")
-Assignment.issue = Property(f"{Assignment} has {Issue}", short_name="issue")
-Assignment.sprint = Property(f"{Assignment} has {Sprint}", short_name="sprint")
+**3. Assignment domain with skill constraints.** The `Assignment` decision concept is a cross-product of developers, issues, and sprints, pruned to valid placements only: the developer must have the matching team skill, and the sprint must be at or after the issue's target sprint. Pruning up front keeps the search space tractable by creating variables only where a valid assignment could exist.
 
-model.define(
-    Assignment.new(developer=Developer, issue=Issue, sprint=Sprint)
-).where(
-    Skill.developer_id == Developer.id,
-    Skill.team == Issue.team,
-    Sprint.number >= Issue.target_sprint_number,
-)
-```
+**4. Binary assignment variables and constraints.** Each valid placement gets a binary variable (1 = assigned). Two constraints govern the solve: each issue is assigned exactly once, and each developer's assigned story points per sprint stay within capacity scaled by the scenario's `capacity_multiplier`.
 
-This dramatically reduces the search space by only creating assignment variables where a valid assignment could exist.
+**5. Weighted completion time objective.** The objective minimizes a weighted sum where higher-priority issues (lower priority number) cost more when placed in later sprints -- a priority-1 issue in Sprint 4 costs `(4-1+1) * 4 = 12`, a priority-3 issue in Sprint 4 costs `(4-3+1) * 4 = 8`. This pushes the most urgent work into the earliest sprints.
 
-### 4. Binary assignment variables and constraints
+For the implementation, see `sprint_scheduling.py`; to reproduce it step by step with the RAI skills, follow `runbook.md`.
 
-Each valid assignment gets a binary variable (1 = assigned, 0 = not assigned). The "each issue assigned exactly once" constraint is defined once as a named expression, while the capacity constraint references a `capacity_multiplier` that varies per scenario:
+## Customize this template
 
-```python
-problem.solve_for(
-    Assignment.x_assigned,
-    type="bin",
-    name=["assign", Assignment.issue.key, Assignment.developer.name, Assignment.sprint.name],
-)
+Focus on the first changes most users will make.
 
-# Static constraint: each issue assigned exactly once
-issue_once = model.require(
-    sum(Assignment.x_assigned).per(Issue) == 1
-).where(Assignment.issue == Issue)
-problem.satisfy(issue_once)
+### Use your own data
 
-# Parameterized constraint: developer capacity per sprint (references capacity_multiplier)
-problem.satisfy(model.require(
-    sum(Assignment.x_assigned * Assignment.issue.story_points).per(Developer, Sprint)
-    <= Developer.capacity_points_per_sprint * capacity_multiplier
-).where(Assignment.developer == Developer, Assignment.sprint == Sprint))
-```
+- Replace the four CSVs in `data/` with your own, keeping the column names listed in *Sample data* above. `developers.csv`, `sprints.csv`, `issues.csv`, and `skills.csv` each map directly to a concept.
+- `sprints.csv` and `issues.csv` use Unix epoch seconds for dates; convert your date strings to epochs before loading, or adapt the epoch-mapping helper.
+- Make sure every team present in `issues.csv` has at least one skilled developer in `skills.csv`, or those issues cannot be assigned.
 
-### 5. Weighted completion time objective
+### Tune parameters
 
-The objective minimizes a weighted sum where high-priority issues (lower priority number) incur a higher cost when placed in later sprints. It is defined once and reused across scenario iterations:
+- **Planning horizon** -- edit `planning_start` and `planning_end` to include more or fewer sprints, and add matching rows to `sprints.csv`.
+- **Capacity** -- modify `capacity_points_per_sprint` in `developers.csv`, or edit `SCENARIO_VALUES` to sweep different `capacity_multiplier` levels (default `[0.35, 0.5, 1.0]`).
+- **Priority scheme** -- adjust `max_priority` and the weight formula in the objective to match your team's priority scale.
 
-```python
-max_priority = 3
-weighted_completion = sum(
-    Assignment.x_assigned
-    * (max_priority + 1 - Assignment.issue.priority)
-    * Assignment.sprint.number
-)
-problem.minimize(weighted_completion)
-```
+### Extend the model
 
-A priority-1 issue in Sprint 4 costs `(4-1+1) * 4 = 12`, while a priority-3 issue in Sprint 4 costs `(4-3+1) * 4 = 8`. This pushes the most urgent work into the earliest sprints.
+- **Add cross-team skills** -- append rows to `skills.csv` to let developers work on issues outside their primary team (Grace and Hank already carry cross-team skills).
+- **Add sprint-specific constraints** -- for example, require that certain issues finish by a given sprint using additional `.where()` clauses on the `Assignment` domain.
 
-## Customize this template
+### Scale up / productionize
 
-- **Change the planning horizon**: Edit `planning_start` and `planning_end` to include more or fewer sprints. Add corresponding rows to `sprints.csv`.
-- **Adjust developer capacity**: Modify `capacity_points_per_sprint` in `developers.csv` or edit `SCENARIO_VALUES` to sweep different `capacity_multiplier` levels (e.g., `[0.35, 0.5, 1.0]`).
-- **Add cross-team skills**: Append rows to `skills.csv` to let developers work on issues outside their primary team. Grace and Hank already have cross-team skills in the sample data.
-- **Change the priority scheme**: Adjust `max_priority` and the weight formula in the objective to match your team's priority scale.
-- **Add sprint-specific constraints**: For example, require that certain issues are completed by a specific sprint using additional `.where()` clauses.
+- The assignment domain grows with developers x issues x sprints; the skill and target-sprint `.where()` filters keep it tractable by only creating variables where a valid placement exists.
+- Pin the `relationalai` SDK version (see *Prerequisites*) for reproducible solves, and swap the CSV loads for `model.data(snowflake_table)` calls to run against live backlog data.
 
 ## Troubleshooting
 
@@ -291,3 +246,21 @@ Every issue must have at least one developer with a matching team skill. Verify
 
 Ensure your Snowflake account has the RAI Native App installed and your user has the required permissions. Run `rai init` to configure your connection profile. See the [RelationalAI documentation](https://docs.relational.ai) for setup details.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) -- concepts, properties, `.where()` filters, and aggregates used to build the assignment domain.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) -- the `Problem` API, `solve_for` decision variables, `satisfy` constraints, and `minimize` objectives used here.
+
+### CLI / SDK guides
+
+- [RelationalAI setup and `rai init`](https://docs.relational.ai/) -- connecting the SDK to your Snowflake account.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/subscriber_retention/README.md b/v1/subscriber_retention/README.md
index 433a1b77..87f26857 100644
--- a/v1/subscriber_retention/README.md
+++ b/v1/subscriber_retention/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Subscriber Retention"
-description: "Telco churn-risk scoring: PageRank over a Subscriber→Subscriber call graph plus aggregate-derived call-volume features feed a regression GNN that scores per-subscriber churn risk, then surfaces the highest-risk subscribers per segment."
+description: "Score every telco subscriber for churn risk using a graph neural network (GNN) that learns from both plan attributes and each subscriber's position in the call network, then surface the highest-risk subscribers per segment for retention campaigns."
 featured: false
 experience_level: advanced
 industry: "Technology & Telecom"
@@ -8,7 +8,7 @@ reasoning_types:
   - Graph
   - Predictive
 tags:
-  - GNN
+  - Graph Neural Network (GNN)
   - Regression
   - Churn Prediction
   - Graph Features
@@ -16,31 +16,36 @@ tags:
   - Multi-Reasoner
 ---
 
-# Subscriber Retention
-
 ## What this template is for
 
-Telco retention teams need to score every active subscriber for churn risk so they can target proactive offers at the right people before contracts roll over. Traditional churn models lean on plan attributes (rate, term, auto-renew) and demographics; they ignore the network around each subscriber. This template wires a call-graph signal into the model: who you call, who calls you, and how central you sit in the call network all become features, and the **Predictive** reasoner trains a GNN regression head over them. The graph features come from the **Graph** reasoner (PageRank on the Subscriber→Subscriber call graph); aggregate-derived `outgoing_calls` / `incoming_calls` properties round out the per-subscriber feature row.
+Telco retention teams need to know which subscribers are most likely to churn, so they can spend a limited campaign budget on the people most worth keeping. Traditional churn models lean on plan attributes and demographics alone, and miss a signal the operator already owns: the call network. A subscriber who talks to many others, or sits at the center of a tight calling community, behaves differently from an isolated one -- and that structure predicts retention.
+
+This template scores every subscriber for churn risk using both their plan attributes and their standing in the call network, then ranks the highest-risk subscribers within each segment so a retention team can act on them first.
+
+**A graph neural network learns per-subscriber churn risk from plan and demographic attributes enriched with call-network features**, so who a subscriber talks to shapes the score, not just what plan they hold.
 
 ## Who this is for
 
 - Telco data scientists building churn-risk scoring pipelines that combine static plan attributes with relational/network signal
 - Retention marketers who need a per-subscriber risk score by segment to drive targeted offer campaigns
-- ML engineers exploring GNN regression over heterogeneous customer graphs
+- ML engineers exploring graph neural network (GNN) regression over customer graphs
 - Teams already querying RelationalAI on a Subscriber/Plan/Call ontology who want to layer a predictive head onto it
 
-Assumes familiarity with Python, basic ML concepts (regression, RMSE), and graph data structures.
+**Assumed knowledge**: comfortable with Python, basic ML concepts (regression, root-mean-square error / RMSE), and graph data structures. The telco, graph, and GNN terms are explained as they come up.
 
 ## What you'll build
 
-- **Graph**: PageRank on a directed Subscriber→Subscriber call graph, exposing each subscriber's "social influence" as a continuous GNN feature
-- **Predictive**: a regression GNN on the call graph predicting `churn_risk_score` per subscriber from demographics + plan attributes + the PageRank feature + aggregate-derived `outgoing_calls` / `incoming_calls` properties
-- **Reporting**: top-N highest-predicted-risk subscribers per segment, ready to drop into a retention campaign queue
-- The whole pipeline runs end-to-end on a small bundled telco dataset (~1,200 subscribers, ~6,000 calls); no Snowflake source data setup, no GPU
+- A per-subscriber churn-risk score, predicted by a **graph neural network (GNN) regression head** (the predictive reasoner) from plan attributes, demographics, and call-network features.
+- Call-network features enriched onto each subscriber by the **graph reasoner** -- a PageRank "social influence" score plus aggregate-derived `outgoing_calls` / `incoming_calls` counts -- so the GNN sees who each subscriber talks to.
+- A retention-ready report of the top-N highest-predicted-risk subscribers per segment, queryable straight from the ontology.
+- A pipeline that runs end-to-end on the small bundled telco dataset (~1,200 subscribers, ~6,000 calls) with no Snowflake source-data setup and no GPU.
+
+Built using the **graph reasoner** (PageRank on the call graph) and the **predictive reasoner** (GNN regression scored per subscriber).
 
 ## What's included
 
 - **Runner**: `subscriber_retention.py` — runs the full Graph-feature + GNN-regression pipeline plus reporting on the bundled CSVs
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Model**: `Subscriber` (with denormalized plan attributes), `Call` (edge-intermediary for the call graph), and three task-table concepts (`TrainTable`, `ValTable`, `TestTable`) carrying the churn-risk labels
 - **Sample data**: small telco subset (subscribers + plans + call detail records); see [Sample data](#sample-data) below
 - **Outputs**: subscriber/call counts, churn-risk distribution, GNN training/prediction metrics, top-5 highest-risk subscribers per segment, test-set RMSE
@@ -165,17 +170,19 @@ Test-set RMSE: 0.1386
         └── billing_events.csv      # billing-cycle records (not used by the default pipeline; available for customization)
 ```
 
+**Start here**: run `python subscriber_retention.py` for the full graph-feature, GNN-regression, and reporting pipeline end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
+
 ## Sample data
 
 Two ways to feed this template:
 
 1. **Bundled (light)** — `data/telco_mini/` ships with the template ZIP. ~1,200 subscribers + ~6,000 calls + 1,200 plans. Demo data. The four identifier columns (`FIRST_NAME`, `LAST_NAME`, `EMAIL`, `PHONE`) are dropped at load time as unused features. No external setup. **Quickstart uses this.**
-2. **Bring-your-own** — replace the four CSVs under `data/telco_mini/` with your own subscriber / plan / CDR exports (same column names) and re-run. There is no widely-known public telco churn dataset that includes a caller→callee call graph (the popular [IBM Telco Customer Churn](https://www.kaggle.com/datasets/blastchar/telco-customer-churn) benchmark is tabular only — no calls, no graph), so the GNN graph path requires real CDR data or a synthetic call-graph generator. See [Run on your own Snowflake data](#run-on-your-own-snowflake-data) for the loading pattern.
+2. **Bring-your-own** — replace the four CSVs under `data/telco_mini/` with your own subscriber / plan / CDR exports (same column names) and re-run. There is no widely-known public telco churn dataset that includes a caller-to-callee call graph (the popular [IBM Telco Customer Churn](https://www.kaggle.com/datasets/blastchar/telco-customer-churn) benchmark is tabular only — no calls, no graph), so the GNN graph path requires real CDR data or a synthetic call-graph generator. See [Run on your own Snowflake data](#run-on-your-own-snowflake-data) for the loading pattern.
 
 About the bundled mini set:
 
 - **~1,200 subscribers** across five segments: `BUDGET`, `ENTERPRISE_PREMIUM`, `HIGH_VALUE_INFLUENCER`, `PREMIUM`, `STANDARD`
-- **~6,000 call records** wired as Subscriber→Subscriber edges for the PageRank graph
+- **~6,000 call records** wired as Subscriber-to-Subscriber edges for the PageRank graph
 - **`CHURN_RISK_SCORE` target** is a continuous 0-1 risk score sourced from the analyst-facing risk model in the source schema. Customers adapting this template would replace it with their own labelled churn ground-truth (binary outcome) — the regression scaffold transfers directly to a binary-classification task by switching `task_type` and the target type.
 
 ## Model overview
@@ -185,6 +192,12 @@ About the bundled mini set:
 - **Subscriber** (`sub_id`): one customer with denormalized plan attributes (`plan_type`, `monthly_rate_usd`, `data_limit_gb`, `term_months`, `auto_renew`, etc.) plus demographic fields (`segment`, `subscriber_type`, `lifetime_value_usd`, `nps_score`, `signup_date`). Enriched at pipeline time with `pagerank` and `outgoing_calls` / `incoming_calls`.
 - **Call**: one call record between two subscribers; serves only as the edge intermediary for the PageRank graph and the call-volume aggregates. Has no identity property — only the edges matter downstream.
 
+**Primary identifiers**: `Subscriber.sub_id` (string, unique per customer). `Call` has no key of its own — its `caller_sub_id` / `callee_sub_id` reference `Subscriber.sub_id` to form call-graph edges.
+
+**Important invariants**: `churn_risk_score` is a fraction in `[0, 1]` (the regression target); every `Call`'s `caller_sub_id` and `callee_sub_id` must resolve to an existing `Subscriber.sub_id`; each subscriber row carries exactly one denormalized plan (1:1 join); `sub_id`, `postal_code`, and the target are dropped from the feature set before training.
+
+For the full concept and property definitions, see `subscriber_retention.py`; `runbook.md` builds them step by step with the RAI skills.
+
 ### Pipeline stages
 
 ```text
@@ -197,120 +210,29 @@ Subscribers + Plans + Call records (bundled CSVs, denormalized to Subscriber)
 
 ## How it works
 
-### 1. Build the call graph
-
-A directed `Subscriber → Subscriber` graph with one edge per call record drives the PageRank score:
-
-```python
-call_graph = Graph(
-    model,
-    directed=True,
-    weighted=False,
-    node_concept=Subscriber,
-    aggregator="sum",
-)
-caller = Subscriber.ref()
-callee = Subscriber.ref()
-call_ref = Call.ref()
-model.define(call_graph.Edge.new(src=caller, dst=callee)).where(
-    call_ref.caller_sub_id == caller.sub_id,
-    call_ref.callee_sub_id == callee.sub_id,
-)
-```
-
-PageRank is bound to a `Subscriber.pagerank` property so it shows up as a continuous feature for the GNN:
+**1. Build the call graph.** A directed `Subscriber → Subscriber` graph is built with one edge per call record. PageRank runs over it and is bound back to a `Subscriber.pagerank` property, so each subscriber's "social influence" in the call network becomes a continuous feature the GNN can learn from.
 
-```python
-pagerank_rel = call_graph.pagerank()
-Subscriber.pagerank = model.Property(f"{Subscriber} has {Float:pagerank}")
-sub_pr = Subscriber.ref()
-score_pr = Float.ref()
-model.define(sub_pr.pagerank(score_pr)).where(pagerank_rel(sub_pr, score_pr))
-```
+**2. Derive call-volume features.** Two count-based rules derive `outgoing_calls` and `incoming_calls` per subscriber via `count(Call).per(Subscriber)` aggregates. These attach to the same `Subscriber` row PageRank is on, so the GNN sees one feature row per subscriber with graph structure and call volume blended in.
 
-### 2. Derive call-volume features
+**3. Declare features and target.** A `PropertyTransformer` declares each feature's type explicitly — categorical, continuous, integer, datetime — and drops the primary key, high-cardinality `postal_code`, and the `churn_risk_score` target from the feature set.
 
-Two count-based rules derive `outgoing_calls` and `incoming_calls` per subscriber. Each is a Property bound via a `count(Call).per(Subscriber)` aggregate:
+**4. Train and predict.** The split is stratified by `SEGMENT` so each segment's risk distribution carries through train/val/test. The GNN trains as a regression head evaluated with RMSE, then scores the held-out test subscribers; predictions bind back as `Subscriber.predictions` for downstream queries.
 
-```python
-Subscriber.outgoing_calls = model.Property(f"{Subscriber} has {Integer:outgoing_calls}")
-model.define(
-    Subscriber.outgoing_calls(count(Call).per(Subscriber))
-).where(Call.caller_sub_id == Subscriber.sub_id)
-
-Subscriber.incoming_calls = model.Property(f"{Subscriber} has {Integer:incoming_calls}")
-model.define(
-    Subscriber.incoming_calls(count(Call).per(Subscriber))
-).where(Call.callee_sub_id == Subscriber.sub_id)
-```
+**5. Top-N per segment.** A single declarative query joins predicted risk back to subscriber metadata and groups by segment, surfacing the highest-predicted-risk subscribers a retention team should act on first.
 
-These declarative rules feed the same `Subscriber` row that PageRank is attached to, so the GNN sees one feature row per subscriber with everything blended in.
-
-### 3. Declare features and target (PropertyTransformer)
-
-Categorical, continuous, and integer feature types are declared explicitly. PKs and target columns are dropped:
-
-```python
-pt = PropertyTransformer(
-    drop=[Subscriber.sub_id, Subscriber.postal_code, Subscriber.churn_risk_score],
-    category=[Subscriber.subscriber_type, Subscriber.segment, Subscriber.status,
-              Subscriber.plan_type, Subscriber.auto_renew],
-    continuous=[Subscriber.lifetime_value_usd, Subscriber.monthly_rate_usd,
-                Subscriber.early_termination_fee_usd, Subscriber.pagerank],
-    integer=[Subscriber.nps_score, Subscriber.data_limit_gb, Subscriber.term_months,
-             Subscriber.outgoing_calls, Subscriber.incoming_calls],
-    datetime=[Subscriber.signup_date],
-)
-```
+For the implementation, see `subscriber_retention.py`; to reproduce it step by step with the RAI skills, follow `runbook.md`.
 
-### 4. Train and predict (GNN regression)
-
-The split is stratified by `SEGMENT` so each segment's distribution carries through train/val/test. The GNN trains as a regression head with `eval_metric="rmse"`:
-
-```python
-gnn = GNN(
-    exp_database=EXP_DATABASE,
-    exp_schema=EXP_SCHEMA,
-    graph=call_graph,
-    property_transformer=pt,
-    train=Train,
-    validation=Val,
-    task_type="regression",
-    eval_metric="rmse",
-    has_time_column=False,
-    seed=SEED,
-    device="cpu",
-    n_epochs=20,
-    lr=0.005,
-)
-gnn.fit()
-Subscriber.predictions = gnn.predictions(domain=Test)
-```
+## Customize this template
 
-The prediction is bound back as `Subscriber.predictions` so downstream queries can pull `predicted_value` per subscriber.
+### Use your own data
 
-### 5. Top-N per segment (Reporting)
+- **Repoint to your own subscriber data** — replace the CSVs under `data/telco_mini/` with your real subscriber/plan/CDR exports (same column names) and re-run.
 
-A single declarative query joins predicted risk back to subscriber metadata and groups by segment:
+### Tune parameters
 
-```python
-sub_ref = Subscriber.ref()
-risk_ref = Float.ref()
-results_df = (
-    select(
-        sub_ref.sub_id.alias("sub_id"),
-        sub_ref.segment.alias("segment"),
-        sub_ref.subscriber_type.alias("type"),
-        sub_ref.lifetime_value_usd.alias("lifetime_value"),
-        sub_ref.churn_risk_score.alias("actual_risk"),
-        risk_ref.alias("predicted_risk"),
-    )
-    .where(sub_ref.predictions.predicted_value(risk_ref))
-    .to_df()
-)
-```
+- **Adjust the segment stratification** — the default split stratifies by `SEGMENT`. For very imbalanced churn outcomes, stratify by the target instead (or in addition).
 
-## Customize this template
+### Extend the model
 
 - **Switch to binary churn classification** — change `task_type="regression"` → `"binary_classification"` and set the train/val target to a Boolean churn outcome instead of a continuous risk score. The graph + rules stages stay identical.
 - **Add weights to the call graph** — set `weighted=True` on the `Graph(...)` call and add an aggregated edge-weight property (e.g. total call-duration or call-count per pair). The PageRank scores will reflect call intensity, not just topology.
@@ -333,10 +255,8 @@ results_df = (
 
   # then add Subscriber.late_payment_count to PropertyTransformer(integer=[...])
   ```
-- **Adjust the segment stratification** — the default split stratifies by `SEGMENT`. For very imbalanced churn outcomes, stratify by the target instead (or in addition).
-- **Repoint to your own subscriber data** — replace the CSVs under `data/telco_mini/` with your real subscriber/plan/CDR exports (same column names) and re-run.
 
-### Run on your own Snowflake data
+### Scale up / productionize
 
 The bundled CSVs are loaded via `model.data(df)` for a no-setup local demo. To run against full data living in Snowflake instead:
 
@@ -354,7 +274,7 @@ The bundled CSVs are loaded via `model.data(df)` for a no-setup local demo. To r
 3. Bump the GNN's compute (`device="cuda"` and a GPU-backed RAI engine) if the call graph has more than ~50K subscribers; CPU works for ~1-10K subscribers.
 
 > [!NOTE]
-> There is no widely-known public telco churn dataset that includes a caller→callee call graph. The IBM Telco Customer Churn dataset (popular benchmark) is tabular only — no calls, no graph — so this template's GNN regression head doesn't add value over a tabular model on that benchmark. To exercise the graph path you need real CDR data or a synthetic call-graph generator.
+> There is no widely-known public telco churn dataset that includes a caller-to-callee call graph. The IBM Telco Customer Churn dataset (popular benchmark) is tabular only — no calls, no graph — so this template's GNN regression head doesn't add value over a tabular model on that benchmark. To exercise the graph path you need real CDR data or a synthetic call-graph generator.
 
 ## Troubleshooting
 
@@ -384,6 +304,25 @@ model = Model("subscriber_retention_local_v2")  # bump on each re-run if needed
 ```
 </details>
 
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — concepts, properties, `count(...).per(...)` aggregates, and `select(...)` used to derive features and build the top-N report.
+
+### Reasoner reference
+
+- [Graph reasoner](https://docs.relational.ai/) — building a `Graph`, edge patterns, and PageRank on the call graph.
+- [Predictive reasoner (GNN)](https://docs.relational.ai/) — `GNN` regression, `PropertyTransformer` feature declaration, train/validation/test tables, and predictions.
+
+### CLI / SDK guides
+
+- [RelationalAI setup and `rai init`](https://docs.relational.ai/) — connecting the SDK and configuring the experiments schema.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
+
 ## Related templates
 
 - **`fraud-detection`** — the canonical multi-reasoner GNN template (Graph + Rules + Predictive + Prescriptive). Use as the reference for adding a Prescriptive optimization stage on top of the GNN scores.
diff --git a/v1/supplier_reliability/README.md b/v1/supplier_reliability/README.md
index bf90708a..796e4ad4 100644
--- a/v1/supplier_reliability/README.md
+++ b/v1/supplier_reliability/README.md
@@ -13,21 +13,13 @@ tags:
   - Cost Optimization
 ---
 
-# Supplier Reliability
-
 ## What this template is for
 
-Procurement teams must choose which suppliers to source from when multiple options exist for each product. Each supplier has different pricing and capacity limits (plus a reliability score, carried as extension data -- not priced into the objective, and not what drives the disruption scenarios below). The challenge is to meet all product demand at minimum cost without exceeding any supplier's capacity.
-
-This template uses **Prescriptive** reasoning to formulate the supplier selection problem as a linear program. It determines the optimal order quantities across supply options, ensuring that every product's demand is met and no supplier is overloaded. The solver finds the cost-minimizing allocation automatically.
+Procurement teams must choose which suppliers to source from when multiple options exist for each product. Each supplier has different pricing and capacity limits, and the challenge is to meet all product demand at minimum cost without overloading any supplier. Beyond the cheapest plan, a planner wants to know which supplier is the real bottleneck, what one more unit of demand would cost, and how badly the plan breaks if a key supplier goes offline.
 
-A plain solve answers *"what is the cheapest sourcing plan?"*. This template requests **sensitivity analysis** (`solve(sensitivity=True)`) on the baseline, which ALSO answers the *marginal* questions a planner asks next -- in the same solve:
+This template answers all of those in one place: it finds the cost-minimizing sourcing plan, reads off the marginal values that rank where to invest next, and re-solves under supplier-disruption scenarios to test resilience.
 
-- **Which supplier capacity is the bottleneck?** The *shadow price* of each capacity constraint (`cap.shadow_price`) is how much total cost moves per unit of that supplier's capacity. A capacity with room to spare prices at zero; a nonzero price marks a binding bottleneck.
-- **What does one more unit of demand cost?** The shadow price of each demand constraint (`meet.shadow_price`) is the marginal cost to serve one more unit of that product.
-- **Which supply lanes are priced out?** A lane's *reduced cost* (`qty_var.reduced_cost`) and *basis status* (`qty_var.basis_status`) show which options are unused and how far their cost must fall before they enter the plan.
-
-Finally, the template demonstrates **scenario analysis** by re-solving the problem with specific suppliers fully excluded. This is a *finite, structural* change -- what happens to cost and feasibility if a key supplier becomes unavailable? -- that the local marginals contextualize but do not by themselves predict.
+**Prescriptive reasoning formulates supplier selection as a linear program**, solved once with sensitivity analysis for the marginals and re-solved per scenario for the disruption tests.
 
 ## Who this is for
 
@@ -45,11 +37,11 @@ Finally, the template demonstrates **scenario analysis** by re-solving the probl
 
 ## What's included
 
-- `supplier_reliability.py` -- Main script defining the model, constraints, and scenario analysis
-- `data/suppliers.csv` -- Supplier capacity and reliability scores
-- `data/products.csv` -- Product demand requirements
-- `data/supply_options.csv` -- Cost per unit for each supplier-product pair
-- `pyproject.toml` -- Python package configuration
+- **Model**: `Supplier`, `Product`, and `SupplyOption` concepts, a `SupplyOrder` decision concept holding the order-quantity variable, capacity and demand constraints, and a cost-minimizing objective.
+- **Runner**: `supplier_reliability.py` -- a single Python script that loads data, runs the baseline solve with sensitivity analysis, reads the marginals, and runs the disruption scenarios end to end.
+- **Runbook**: `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: three CSVs under `data/` describing suppliers, products, and per-supplier-product supply options. See *Sample data* below.
+- **Outputs**: the baseline plan with capacity and demand shadow prices, lane reduced costs and basis status, a per-scenario order plan, and a scenario-analysis summary printed to stdout.
 
 ## Prerequisites
 
@@ -182,123 +174,92 @@ Finally, the template demonstrates **scenario analysis** by re-solving the probl
    less impact (+6%) since SupplierC absorbs most of the displaced volume.
 
 ## Template structure
+
 ```text
 .
-├── README.md
-├── pyproject.toml
-├── supplier_reliability.py
+├── README.md                # this file
+├── pyproject.toml           # dependencies
+├── supplier_reliability.py  # main script (load, baseline solve, marginals, scenarios)
 └── data/
-    ├── products.csv
-    ├── suppliers.csv
-    └── supply_options.csv
+    ├── products.csv         # products with demand requirements
+    ├── suppliers.csv        # suppliers with capacity and reliability scores
+    └── supply_options.csv   # per-unit cost for each supplier-product pair
 ```
 
-## How it works
+**Start here**: run `python supplier_reliability.py` for the full baseline solve, marginal reads, and disruption scenarios end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-### 1. Define the ontology and load data
+## Sample data
 
-The model defines three concepts -- Supplier, Product, and SupplyOption -- and loads them from CSV files:
+The bundled data is synthetic and illustrative -- a small four-supplier, three-product catalog sized to teach the sourcing and sensitivity patterns, not to mirror a specific procurement portfolio.
 
-```python
-Supplier = Concept("Supplier", identify_by={"id": Integer})
-Supplier.name = Property(f"{Supplier} has {String:name}")
-Supplier.reliability = Property(f"{Supplier} has {Float:reliability}")
-Supplier.capacity = Property(f"{Supplier} has {Integer:capacity}")
-supplier_csv = read_csv(DATA_DIR / "suppliers.csv")
-model.define(Supplier.new(model.data(supplier_csv).to_schema()))
-```
+- **`suppliers.csv`** (4 rows) -- suppliers `SupplierA` through `SupplierD`, each with a `capacity` (350-600 units) and a `reliability` score. The reliability score is carried as data only: it is not priced into the objective and does not drive the disruption scenarios (it is an extension point; see *Customize this template*).
+- **`products.csv`** (3 rows) -- `Widget`, `Gadget`, and `Component`, each with a `demand` requirement.
+- **`supply_options.csv`** -- one row per supplier-product pair with a `cost_per_unit`. `SupplierC` is the cheapest source for every product, so it fills its capacity first; the pricing is tuned so `SupplierC`'s capacity is the single binding bottleneck at the optimum.
 
-SupplyOption links suppliers to products with a cost per unit, establishing the many-to-many relationship:
+## Model overview
 
-```python
-SupplyOption = Concept("SupplyOption", identify_by={"id": Integer})
-SupplyOption.supplier = Property(f"{SupplyOption} from {Supplier}", short_name="supplier")
-SupplyOption.product = Property(f"{SupplyOption} for {Product}", short_name="product")
-SupplyOption.cost_per_unit = Property(f"{SupplyOption} has {Float:cost_per_unit}")
-```
+The model has three source concepts loaded from CSV, plus a derived `SupplyOrder` decision concept that carries the order-quantity variable and back-pointers to its supplier and product.
 
-### 2. Create decision variables
+- **Key entities**: `Supplier` — a source with a capacity limit and a reliability score; `Product` — an item with a demand requirement to satisfy; `SupplyOption` — a supplier-product sourcing lane with a per-unit cost; and the decision concept `SupplyOrder` — an order placed through one supply option.
+- **Primary identifiers**: integer `id` on `Supplier`, `Product`, and `SupplyOption`; `SupplyOrder` is identified by the `SupplyOption` it uses.
+- **Important invariants**: `capacity` and `demand` are non-negative integers; `cost_per_unit` is non-negative; order quantities are continuous and non-negative; total ordered per supplier stays within capacity; total ordered per product meets demand.
 
-A SupplyOrder concept holds the decision variable -- the quantity to order through each supply option:
+For the full concept and property definitions, see `supplier_reliability.py`; `runbook.md` builds them step by step with the RAI skills.
 
-```python
-SupplyOrder = Concept("SupplyOrder")
-SupplyOrder.option = Property(f"{SupplyOrder} uses {SupplyOption}", short_name="option")
-SupplyOrder.x_quantity = Property(f"{SupplyOrder} has {Float:quantity}")
-model.define(SupplyOrder.new(option=SupplyOption))
-```
+## How it works
 
-### 3. Add constraints and objective
-
-Capacity and demand constraints ensure feasibility, while the objective minimizes total procurement cost. Each constraint is **captured as a handle**, **named per entity** (a readable label), and declared with **`keyed_by`** -- the entity key its marginal reads back through after the solve:
-
-```python
-cap = baseline.satisfy(
-    model.require(
-        sum(SupplyOrder.x_quantity).where(SupplyOrder.supplier == Supplier).per(Supplier) <= Supplier.capacity
-    ),
-    name=["cap", Supplier.name],
-    keyed_by={"supplier": Supplier},
-)
-meet = baseline.satisfy(
-    model.require(
-        sum(SupplyOrder.x_quantity).where(SupplyOrder.product == Product).per(Product) >= Product.demand
-    ),
-    name=["demand", Product.name],
-    keyed_by={"product": Product},
-)
-baseline.minimize(sum(SupplyOrder.x_quantity * SupplyOrder.cost_per_unit))
+```text
+CSV inputs → load Supplier/Product/SupplyOption → SupplyOrder decision variables → capacity + demand constraints + cost objective → baseline solve with sensitivity → read marginals → scenario re-solves
 ```
 
-### 4. Request sensitivity and read the marginals
+**1. Define the ontology and load data.** Three source concepts -- `Supplier`, `Product`, and `SupplyOption` -- load from CSV. `SupplyOption` links each supplier to each product it can supply with a per-unit cost, forming the many-to-many sourcing lanes.
 
-Solve the baseline with `sensitivity=True`, then read each marginal straight off the variable or constraint object -- the same attribute style as `.name`. A constraint declared with `keyed_by` carries an **entity back-pointer** (`cap.supplier`, `meet.product`), mirroring the variable's automatic back-pointer (`qty_var.supplyorder`), so a marginal joins to that entity's own data by KEY -- no name parsing, no pandas:
+**2. Create decision variables.** A `SupplyOrder` decision concept holds the order-quantity variable -- how many units to order through each supply option -- with back-pointers to its supplier and product for direct access.
 
-```python
-baseline.solve("highs", time_limit_sec=60, sensitivity=True)
+**3. Add constraints and objective.** A capacity constraint caps total units ordered per supplier; a demand constraint requires total units per product to meet demand; the objective minimizes total procurement cost. Each constraint is captured as a handle, named per entity for a readable label, and declared with `keyed_by` so its marginal reads back through the entity's key after the solve.
 
-# Capacity shadow prices, joined to each supplier's capacity by key:
-model.select(cap.supplier.name, cap.supplier.capacity, cap.shadow_price).inspect()
-# Demand shadow prices, joined to each product's demand by key:
-model.select(meet.product.name, meet.product.demand, meet.shadow_price).inspect()
-# Lane reduced costs and basis status, joined to supplier / product by key:
-model.select(
-    qty_var.supplyorder.supplier.name, qty_var.supplyorder.product.name,
-    qty_var.reduced_cost, qty_var.basis_status,
-).inspect()
-```
+**4. Request sensitivity and read the marginals.** A plain solve answers *"what is the cheapest sourcing plan?"*. Requesting sensitivity analysis on the same solve also answers the marginal questions a planner asks next:
 
-(`.inspect()` prints the rows for a quick look; the script materializes the same selects as DataFrames with `.to_df()` for its printed report and assertions.)
+- **Which supplier capacity is the bottleneck?** The *shadow price* of each capacity constraint is how much total cost moves per unit of that supplier's capacity. A capacity with room to spare prices at zero; a nonzero price marks a binding bottleneck.
+- **What does one more unit of demand cost?** The shadow price of each demand constraint is the marginal cost to serve one more unit of that product.
+- **Which supply lanes are priced out?** A lane's *reduced cost* and *basis status* show which options are unused and how far their cost must fall before they enter the plan.
 
-The economics are also stated as integrity constraints joined by the same keys -- but only the always-true directions of complementary slackness (a lane in use prices at ~0; SupplierA's lanes are priced out). The converse "every unused lane has a positive reduced cost" is **not** asserted, because SupplierB's lanes tie SupplierC at the margin (alternate optima).
+Because each constraint carries an entity back-pointer, a marginal joins to that entity's own data by key -- no name parsing, no pandas. The economics are also stated as integrity constraints, but only the always-true directions of complementary slackness (a lane in use prices at ~0; SupplierA's lanes are priced out). The converse "every unused lane has a positive reduced cost" is **not** asserted, because SupplierB's lanes tie SupplierC at the margin (alternate optima).
 
 > [!NOTE]
 > Sensitivity analysis returns marginals only for LP/QP models (linear constraints with a linear or quadratic objective). For mixed-integer models the duals are empty -- use scenario analysis instead. The marginal reads must happen on the **baseline** Problem, before the scenario loop rebuilds a fresh Problem.
 
-### 5. Scenario analysis
-
-Each disruption scenario is a separate Problem that excludes one supplier with a `where=` filter on the decision variable -- a finite, structural change the marginals contextualize but do not by themselves predict:
-
-```python
-for excluded in ["SupplierC", "SupplierB"]:
-    problem = Problem(model, Float)
-    qty_scn = problem.solve_for(
-        SupplyOrder.x_quantity,
-        name=["qty", SupplyOrder.supplier.name, SupplyOrder.product.name],
-        lower=0,
-        where=[SupplyOrder.supplier.name != excluded],
-        populate=False,
-    )
-    # ... re-add capacity / demand constraints and the objective ...
-    problem.solve("highs", time_limit_sec=60)
-```
+**5. Scenario analysis.** Each disruption scenario is a separate Problem that excludes one supplier via a filter on the decision variable, then re-solves. This is a finite, structural change the marginals contextualize but do not by themselves predict -- removing all of a supplier's capacity can move cost further than the local shadow price suggests.
+
+For the implementation, see `supplier_reliability.py`; to reproduce it step by step with the RAI skills, follow `runbook.md`.
 
 ## Customize this template
 
-- **Add a reliability penalty** to the objective function, weighting cost against supplier reliability scores. One weighting yields a single trade-off point; sweep the weight to trace the cost-vs-reliability frontier.
-- **Expand the scenario analysis** to exclude combinations of suppliers or simulate capacity reductions.
+Focus on the first changes most users will make.
+
+### Use your own data
+
+- Replace the three CSVs in `data/` with your own, keeping the column names listed in *Sample data* above. `suppliers.csv`, `products.csv`, and `supply_options.csv` each map directly to a concept.
+- Every product in `products.csv` needs at least one supply option in `supply_options.csv`, and total capacity across suppliers must cover total demand, or the baseline solve is infeasible.
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)` calls.
+
+### Tune parameters
+
+- **Capacity and demand** -- edit `capacity` in `suppliers.csv` and `demand` in `products.csv` to change where the bottleneck lands; the shadow prices track which constraint binds.
+- **Costs** -- adjust `cost_per_unit` in `supply_options.csv` to shift the optimal sourcing mix and the reduced costs of unused lanes.
+- **Scenarios** -- edit the excluded-supplier list in the scenario loop to test different disruptions.
+
+### Extend the model
+
+- **Add a reliability penalty** to the objective, weighting cost against supplier reliability scores. One weighting yields a single trade-off point; sweep the weight to trace the cost-vs-reliability frontier.
 - **Add minimum order quantities** by setting lower bounds on the decision variables for active supply options.
-- **Introduce transportation costs** by adding a distance or shipping cost dimension to supply options.
+- **Introduce transportation costs** by adding a distance or shipping-cost dimension to supply options.
+- **Expand the scenario analysis** to exclude combinations of suppliers or simulate capacity reductions rather than full exclusions.
+
+### Scale up / productionize
+
+- The model is a linear program that solves quickly; it scales to larger supplier-product catalogs within the solver's time budget.
+- Pin the `relationalai` SDK version (see *Prerequisites*) for reproducible solves. Note that the optimum has cost-equal alternates, so exact order quantities can vary across HiGHS builds while the objective and shadow prices stay fixed.
 
 ## Troubleshooting
 
@@ -325,3 +286,22 @@ Run `rai init` to configure your Snowflake connection. Verify that your account
 
 The solver minimizes cost, so it will avoid expensive supply options when cheaper alternatives exist. Check `supply_options.csv` to see if the cost differences explain the allocation. If you want to enforce minimum diversification, add constraints requiring orders from multiple suppliers.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) -- concepts, properties, `sum(...).per(...)` aggregates, and `select(...)` used to build constraints and read marginals.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) -- the `Problem` API, `solve_for` decision variables, `satisfy` constraints, and `minimize` objectives.
+- [Sensitivity analysis](https://docs.relational.ai/) -- shadow prices, reduced costs, and basis status returned by `solve(sensitivity=True)`, and reading them back by entity key.
+
+### CLI / SDK guides
+
+- [RelationalAI setup and `rai init`](https://docs.relational.ai/) -- connecting the SDK to your Snowflake account.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/supply_chain_resilience/README.md b/v1/supply_chain_resilience/README.md
index f2015044..a0cd7e22 100644
--- a/v1/supply_chain_resilience/README.md
+++ b/v1/supply_chain_resilience/README.md
@@ -17,67 +17,31 @@ tags:
   - Scenario Analysis
 ---
 
-# Supply Chain Resilience
-
 ## What this template is for
 
-Supply chain networks must route goods from suppliers through factories and distribution centers to customers -- but not all routes carry equal risk. Unreliable suppliers, ML-predicted delays, and over-reliance on bottleneck sites can all disrupt fulfillment. This template shows how to combine multiple analytical signals into a single routing decision.
-
-This template uses RelationalAI's **Graph** analysis, **Rules-based** classification, and **Prescriptive** optimization capabilities in a chained multi-reasoner workflow:
-
-0. **Blast-radius pre-analysis** builds a directed Business graph from shipment data and traces every supplier each high-priority demand customer transitively depends on -- making the exposure footprint explicit before any optimization runs.
-1. **Graph analysis** builds a site dependency graph from shipping operations and computes eigenvector centrality to identify critical warehouses and bridges between supply chain regions.
-2. **Rules** classify suppliers by risk level (avoid / watch / reliable) using reliability scores and ML delay predictions, and flag escalated demand orders.
-3. **Prescriptive optimization** solves a minimum-cost network flow that routes supply to meet demand. Graph centrality feeds a bottleneck penalty in the objective, and supplier risk flags feed hard constraints (no flow from "avoid" suppliers) and surcharges (extra cost for "watch" suppliers).
-4. **Scenario analysis** re-solves with disruptions -- taking a critical site offline (+88.5% cost) and downgrading watch suppliers to avoid (+0.0% cost, because the optimizer had already routed around them) -- to quantify resilience costs.
-
-Each stage enriches the shared ontology, and downstream stages consume those enrichments -- this is the **accretive ontology enrichment** pattern:
-
-- **Stage 1 writes** `Site.centrality` (normalized eigenvector centrality) -- consumed by Stage 3's bottleneck penalty in the objective. High-centrality sites incur a `CENTRALITY_WEIGHT` surcharge per unit of flow.
-- **Stage 2 writes** `Business.is_unreliable`, `Business.has_high_delay_risk`, `Business.is_watch_level` -- consumed by Stage 3 as hard constraints (avoid suppliers get zero flow) and cost surcharges (watch suppliers get `RISK_SURCHARGE` per unit of flow).
-- **Stage 3 writes** `Operation.x_flow` and `Demand.x_unmet` decision variables, re-solved per scenario with modified constraints.
-
-### Reasoner overview
-
-| Stage | Reasoner | Reads from ontology | Writes to ontology | Role |
-|-------|----------|---------------------|--------------------|------|
-| 1 | Graph | Site, Operation (SHIP edges) | Site.centrality (normalized eigenvector) | 2 connected components. Top hubs: S004 TechAssembly (0.50), S006 West Coast DC (0.39), S003 PowerCell (0.37). Centrality feeds the bottleneck penalty in Stage 3. |
-| 2 | Rules | Business.reliability_score, DelayPrediction | Business.is_unreliable, Business.has_high_delay_risk, Business.is_watch_level, Demand.is_escalated | 37 of 262 shipments late (14%). B003 classified as watch (reliability=0.81). 9 escalated demands. Watch/avoid flags feed constraints and surcharges in Stage 3. |
-| 3 | Prescriptive | Site.centrality (Stage 1), Business.is_watch_level (Stage 2), Operation capacity/cost | Operation.x_flow, Demand.x_unmet | Baseline: $1,865 optimal cost, 8 active flows, all demand satisfied. |
-| 3+ | Scenario Analysis | Same + exclude_site_id / block_business_ids | Re-solved x_flow, x_unmet per scenario | S004 offline: +88.5% cost ($3,515). Watch→Avoid: +0.0% ($1,865 -- watch suppliers were not on optimal routes). |
+Supply chain networks route goods from suppliers through factories and distribution centers to customers -- but not all routes carry equal risk. Cost-optimal routes tend to concentrate flow through a few critical hubs, creating fragility that cost-minimization alone never surfaces. Unreliable suppliers, predicted delays, and over-reliance on bottleneck sites all threaten fulfillment, yet each is a different kind of signal: structural risk, supplier reliability, and routing cost are interdependent, and no single analysis reveals how they compound. When a critical warehouse goes offline, the network must absorb the shock through costlier alternatives or unmet demand -- and planners need to know that cost before it happens.
 
-## Why this problem matters
-
-Supply chain routing decisions are typically made with cost and capacity data alone. But cost-optimal routes can concentrate flow through a small number of critical hubs, creating fragility invisible to cost-minimization alone. When a critical warehouse goes offline -- due to weather, labor disruption, or infrastructure failure -- the network must absorb the disruption through costlier alternatives or unmet demand.
-
-The multi-reasoner approach is necessary because structural risk (graph), supplier reliability (rules), and routing cost (optimization) are interdependent signals. A cost-optimal route through a high-centrality hub served by a watch-level supplier compounds risk in a way no single analysis reveals. Scenario analysis then quantifies the cost of disruption: taking the highest-centrality site offline increases total cost by 88.5%, while downgrading watch suppliers to avoid has no impact -- because the optimizer already routed around them. This asymmetry is the key insight.
-
-### Key design patterns demonstrated
-
-- **Accretive ontology enrichment** -- Stage 1's `Site.centrality` feeds Stage 3's objective; Stage 2's risk flags feed Stage 3's constraints and surcharges
-- **Single model composition** -- all three reasoners (Graph, Rules, Prescriptive) attach to one `Model` instance, unlike templates that require a separate graph model
-- **Reusable solve function** -- `solve_flow(label, exclude_site_id, block_business_ids)` encapsulates the full formulation, enabling scenario analysis by re-solving with modified constraints
-- **Derived relationship for business-to-operation linkage** -- `Operation.source_business` is derived by matching `source_site` to `Business.site`, avoiding an explicit join table
-- **Scenario analysis via re-solve** -- disruptions are modeled as constraint modifications (site offline = zero flow, supplier downgrade = block), not separate models
+**This template chains RelationalAI's Graph, Rules-based, and Prescriptive reasoners on one shared ontology, so structural criticality and supplier risk flow directly into a risk-adjusted minimum-cost network flow, then re-solves under disruption scenarios to price resilience.**
 
 ## Who this is for
 
-- Supply chain and logistics managers evaluating network resilience
-- Operations researchers exploring multi-reasoner pipelines in RelationalAI
-- Developers learning how to chain graph, rules, and optimization in a single model
+- Supply chain and logistics managers evaluating network resilience.
+- Operations researchers exploring multi-reasoner pipelines in RelationalAI.
+- Developers learning how to chain graph, rules, and optimization in a single model.
+- **Assumed knowledge**: comfortable reading Python; the graph, rules, and optimization terms are explained as they come up. No prior RelationalAI experience is required to run it, though following a single-reasoner template first makes the chained flow easier to follow.
 
 ## What you'll build
 
-- A site dependency graph with connected component detection and eigenvector centrality scoring
-- Supplier risk classification rules combining reliability scores and ML delay predictions
-- Continuous decision variables for flow on each operation and unmet demand slack
-- Demand satisfaction, supplier blocking, and site-offline constraints
-- A cost minimization objective that incorporates transport cost, risk surcharges, centrality-based bottleneck penalties, and unmet demand penalties
-- Scenario analysis comparing baseline, site-offline, and supplier-downgrade disruptions
+- A risk-adjusted routing plan that meets demand at minimum cost while penalizing flow through bottleneck sites and risky suppliers, produced by the **prescriptive** reasoner (continuous flow and unmet-demand decision variables).
+- Per-site criticality scores (`Site.centrality`) from **graph analysis** -- weakly connected components plus normalized eigenvector centrality -- that feed the routing objective as a bottleneck penalty.
+- Supplier risk classifications (`Business.is_unreliable`, `is_watch_level`, `is_avoid`) and escalated-demand flags from **rules-based** reasoning, wired into the optimizer as hard constraints and surcharges.
+- An upstream blast-radius view: for each high-priority customer, the set of suppliers it transitively depends on, computed by **graph reachability** before any optimization runs.
+- A scenario comparison that re-solves the same formulation with a critical site offline and with watch suppliers downgraded to avoid, quantifying the cost of each disruption.
 
 ## What's included
 
-- `supply_chain_resilience.py` -- Main script with three chained reasoning stages and scenario analysis
+- `supply_chain_resilience.py` -- Main script: a blast-radius pre-analysis, three chained reasoning stages (graph, rules, prescriptive), and scenario analysis
+- `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself
 - `data/site.csv` -- 31 sites (factories, distribution centers, offices, stores) across multiple regions
 - `data/business.csv` -- 31 businesses (suppliers, manufacturers, warehouses, buyers) with reliability scores
 - `data/operation.csv` -- 70 shipping and transfer operations with cost, capacity, and transit time
@@ -138,55 +102,11 @@ The multi-reasoner approach is necessary because structural risk (graph), suppli
 
 6. Expected output:
    ```text
-   ======================================================================
-   STAGE 1: Graph -- Network Criticality
-   ======================================================================
-
-   Connected components: 2
-
-   Top critical sites (eigenvector centrality):
-     S004 TechAssembly Factory (FACTORY, APAC): centrality=0.5016
-     S006 West Coast DC (DISTRIBUTION_CENTER, AMERICAS): centrality=0.3895
-     S003 PowerCell Facility (FACTORY, APAC): centrality=0.3688
-     ...
-
-   ======================================================================
-   STAGE 2: Rules -- Supplier Risk Classification
-   ======================================================================
-
-   Late shipments: 37 of 262 (14%)
-     B006: 7 late shipments
-     B007: 5 late shipments
-     ...
-
-   Supplier risk classification:
-     [!] B003 PowerCell Ltd: reliability=0.81, class=watch
-     [ ] B005 GlobalBuild Inc: reliability=0.85, class=reliable
-     [ ] B001 ChipTech Industries: reliability=0.95, class=reliable
-     ...
-
-   Escalated demands (HIGH priority): 9
-
-   ======================================================================
+   STAGE 1: Graph -- Network Criticality        (top critical sites ranked)
+   STAGE 2: Rules -- Supplier Risk Classification (late shipments, risk classes)
    STAGE 3: Prescriptive -- Risk-Adjusted Network Flow
-   ======================================================================
-
-     [Baseline]
-     Status: OPTIMAL
-     Total cost: 1,865.00
-     Active flows: 8
-     All demand satisfied
-
-   ======================================================================
-   SCENARIO ANALYSIS
-   ======================================================================
-
-   SCENARIO COMPARISON
-     Scenario                  Status                Cost        Unmet
-     -----------------------------------------------------------------
-     Baseline                  OPTIMAL            1,865.00          0
-     Site S004 offline         OPTIMAL            3,515.00 (+88.5%)          0
-     Watch->Avoid              OPTIMAL            1,865.00 (0.0%)          0
+     Status: OPTIMAL   Total cost: 1,865.00   All demand satisfied
+   SCENARIO COMPARISON: Baseline vs. Site S004 offline vs. Watch->Avoid
    ```
 
 ## Template structure
@@ -206,218 +126,82 @@ The multi-reasoner approach is necessary because structural risk (graph), suppli
     └── delay_prediction.csv
 ```
 
-## How it works
-
-This section walks through the highlights in `supply_chain_resilience.py`.
-
-### Import libraries and configure inputs
-
-First, the script imports the RAI SDK and configures key parameters that control risk thresholds, penalties, and the prediction quarter:
-
-```python
-from relationalai.semantics import Float, Integer, Model, String, select, sum, where
-from relationalai.semantics.reasoners.graph import Graph
-from relationalai.semantics.reasoners.prescriptive import Problem
-from relationalai.semantics.std import aggregates as aggs
-
-model = Model("supply_chain_resilience")
-
-UNMET_PENALTY = 100.0  # penalty for unmet demand (kept moderate so routing costs are visible)
-RISK_SURCHARGE = 5.0  # cost multiplier for "watch" supplier operations
-CENTRALITY_WEIGHT = 2.0  # multiplier for bottleneck site penalty
-DELAY_PROB_THRESHOLD = 0.15  # above this = high delay risk
-RELIABILITY_THRESHOLD = 0.80  # below this = unreliable supplier
-PREDICTION_QUARTER = "Q1-2025"  # which quarter's predictions to use
-```
-
-### Define concepts and load CSV data
-
-Next, the model defines concepts for the supply chain ontology. `Site` represents physical locations (factories, distribution centers, stores). `Business` represents entities (suppliers, manufacturers, buyers) with reliability scores. `Operation` defines shipping routes between sites with cost and capacity:
-
-```python
-Site = model.Concept("Site", identify_by={"id": String})
-Site.name = model.Property(f"{Site} has {String:name}")
-Site.site_type = model.Property(f"{Site} has type {String:site_type}")
-Site.region = model.Property(f"{Site} in {String:region}")
-
-Business = model.Concept("Business", identify_by={"id": String})
-Business.reliability_score = model.Property(
-    f"{Business} has reliability {Float:reliability_score}"
-)
-Business.site = model.Relationship(f"{Business} operates at {Site}")
-
-Operation = model.Concept("Operation", identify_by={"id": String})
-Operation.cost_per_unit = model.Property(
-    f"{Operation} costs {Float:cost_per_unit} per unit"
-)
-Operation.capacity_per_day = model.Property(
-    f"{Operation} has capacity {Integer:capacity_per_day} per day"
-)
-Operation.source_site = model.Relationship(f"{Operation} from {Site}")
-Operation.output_site = model.Relationship(f"{Operation} to {Site}")
-Operation.output_sku = model.Relationship(f"{Operation} produces {SKU}")
-```
+**Start here**: run `python supply_chain_resilience.py` for the full chain end to end -- blast-radius pre-analysis, the three reasoning stages, and the scenario comparison -- or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-A derived relationship links each operation to its source business by matching the operation's source site to the business's site:
+## Sample data
 
-```python
-Operation.source_business = model.Relationship(
-    f"{Operation} sourced from {Business}"
-)
-model.define(Operation.source_business(Operation, Business)).where(
-    Operation.source_site == Business.site
-)
-```
+The bundled data is synthetic and illustrative -- designed to teach the reasoning flow on a Snowflake-connected RAI account, not to match a specific operator's network.
 
-`DelayPrediction` captures ML-predicted delay probabilities per supplier per fiscal quarter:
+- **`site.csv`** (31 rows) -- physical locations (factories, distribution centers, offices, stores) with region and country.
+- **`business.csv`** (31 rows) -- suppliers, manufacturers, warehouses, and buyers, each operating at a site, with a `RELIABILITY_SCORE` and value tier.
+- **`operation.csv`** (70 rows) -- shipping and transfer routes between sites, each with `COST_PER_UNIT`, `CAPACITY_PER_DAY`, transit time, and output SKU.
+- **`sku.csv`** (9 rows) -- raw materials, components, and finished goods with unit cost and price.
+- **`demand.csv`** (20 rows) -- customer orders with quantity, priority, and due date.
+- **`shipment.csv`** (262 rows) -- historical shipments with status and delay days; the source for the late-shipment rate and the blast-radius supplier graph.
+- **`delay_prediction.csv`** (36 rows) -- predicted delay probabilities per supplier per fiscal quarter, with a risk tier.
 
-```python
-DelayPrediction = model.Concept("DelayPrediction", identify_by={"id": String})
-DelayPrediction.predicted_delay_prob = model.Property(
-    f"{DelayPrediction} has {Float:predicted_delay_prob}"
-)
-DelayPrediction.supplier_business = model.Relationship(
-    f"{DelayPrediction} predicts for {Business}"
-)
-```
+## Model overview
 
-### Stage 1: Graph -- network criticality
+One shared ontology threads the pre-analysis and all three stages. Each stage reads concepts and properties earlier stages wrote, and writes new ones for downstream stages.
 
-An undirected graph is built with sites as nodes and shipping operations as edges. This captures how sites are connected through the physical shipping network:
+- **Key entities**: `Site` — a physical location (Stage 1 enriches it with a centrality score); `Business` — a supplier, manufacturer, warehouse, or buyer operating at a site (Stage 2 enriches it with risk flags); `Operation` — a shipping or transfer route between sites, the flow decision space; `SKU` — a stock-keeping unit (raw material, component, or finished good); `Demand` — a customer order (Stage 2 flags escalations, Stage 3 tracks unmet slack); `Shipment` — a historical shipment, the source for late-shipment rates and the blast-radius supplier graph; `DelayPrediction` — a predicted delay probability per supplier per fiscal quarter.
+- **Primary identifiers**: string `id` on every concept.
+- **Important invariants**: `reliability_score` and `predicted_delay_prob` are fractions in `[0, 1]`; `capacity_per_day`, `cost_per_unit`, and `quantity` are non-negative; the flow decision variable `x_flow` is bounded by each operation's capacity; unmet-demand slack `x_unmet` is non-negative.
 
-```python
-graph = Graph(model, directed=False, weighted=False, node_concept=Site, aggregator="sum")
+For the full concept and property definitions, see `supply_chain_resilience.py`; `runbook.md` builds them step by step with the RAI skills.
 
-s1, s2, op_ref = Site.ref(), Site.ref(), Operation.ref()
-model.define(
-    graph.Edge.new(src=s1, dst=s2)
-).where(
-    op_ref.source_site(s1),
-    op_ref.output_site(s2),
-    op_ref.op_type == "SHIP",
-)
-```
-
-Weakly connected components identify whether the network is fragmented or unified. Eigenvector centrality scores each site by its influence in the network -- high-centrality sites are critical hubs whose disruption would cascade through many routes. These scores are normalized and stored as a `Site.centrality` property for use in the optimization objective:
-
-```python
-eigenvector = graph.eigenvector_centrality()
+## How it works
 
-Site.centrality = model.Property(f"{Site} has centrality {Float:centrality}")
-eig_df["normalized"] = eig_df["centrality_score"] / max_centrality
-cent_data = model.data(eig_df[["site_id", "normalized"]])
-model.where(Site.id == cent_data["site_id"]).define(
-    Site.centrality(cent_data["normalized"])
-)
-```
+One shared ontology threads a pre-analysis and three chained reasoning stages -- each stage reads what earlier stages wrote and enriches the model for the next.
 
-### Stage 2: Rules -- supplier risk classification
-
-Two derived Relationships flag risky suppliers. The first marks businesses with reliability scores below the threshold. The second uses ML delay predictions to flag suppliers with high predicted delay probability:
-
-```python
-Business.is_unreliable = model.Relationship(f"{Business} is unreliable")
-model.where(
-    Business.reliability_score < RELIABILITY_THRESHOLD
-).define(Business.is_unreliable())
-
-Business.has_high_delay_risk = model.Relationship(
-    f"{Business} has high delay risk"
-)
-dp_ref = DelayPrediction.ref()
-model.where(
-    dp_ref.supplier_business(Business),
-    dp_ref.fiscal_quarter == PREDICTION_QUARTER,
-    dp_ref.predicted_delay_prob > DELAY_PROB_THRESHOLD,
-).define(Business.has_high_delay_risk())
+```text
+CSV inputs → blast-radius reachability → Graph criticality → Rules risk classification → Prescriptive risk-adjusted flow → scenario re-solves
 ```
 
-Suppliers that are both unreliable and have high delay risk are classified as "avoid" (blocked from the network flow). Suppliers with either flag are "watch" (allowed but penalized). These classifications feed directly into the optimizer as hard constraints and cost surcharges.
+**Configure inputs.** A handful of parameters at the top control the run: risk thresholds (`RELIABILITY_THRESHOLD`, `DELAY_PROB_THRESHOLD`), objective penalties (`UNMET_PENALTY`, `RISK_SURCHARGE`, `CENTRALITY_WEIGHT`), and which quarter's delay predictions to use (`PREDICTION_QUARTER`).
 
-A third rule flags escalated demand orders to surface high-priority fulfillment requirements:
-
-```python
-Demand.is_escalated = model.Relationship(f"{Demand} is escalated")
-model.where(Demand.priority == "HIGH").define(Demand.is_escalated())
-```
+**Define concepts and load data.** The seven source concepts load from CSV. A derived `Operation.source_business` relationship links each operation to its source business by matching the operation's source site to the business's site, avoiding an explicit join table.
 
-### Stage 3: Define decision variables, constraints, and objective
+**Stage 0 -- blast-radius pre-analysis.** A directed `Business` graph is built from the derived supplier-to-customer `ships_to` edges. Upstream reachability from each high-priority customer traces every supplier it transitively depends on, making the exposure footprint explicit so the later scenario results can be read in context.
 
-Two continuous decision variables control the network flow: `x_flow` is the flow on each operation (bounded by capacity), and `x_unmet` is unmet demand slack per order:
+**Stage 1 -- Graph, network criticality.** An undirected graph with sites as nodes and SHIP operations as edges captures the physical shipping network. Weakly connected components reveal whether the network is fragmented or unified; eigenvector centrality scores each site by its structural influence. Scores are normalized and stored as `Site.centrality` for the optimizer to penalize.
 
-```python
-problem = Problem(model, Float)
+**Stage 2 -- Rules, supplier risk classification.** Derived relationships flag suppliers below the reliability threshold and suppliers with high predicted delay probability. Suppliers with both flags are classified "avoid" (blocked from flow); suppliers with either flag are "watch" (allowed but surcharged). A further rule flags `HIGH`-priority demand as escalated. These classifications feed the optimizer as hard constraints and cost surcharges.
 
-problem.solve_for(
-    Operation.x_flow,
-    name=["x_flow", Operation.id],
-    lower=0,
-    upper=Operation.capacity_per_day,
-)
+**Stage 3 -- Prescriptive, risk-adjusted network flow.** Two continuous decision variables drive the solve: `x_flow` per operation (bounded by capacity) and `x_unmet` slack per order. A demand-satisfaction constraint requires inbound flow at each customer's site for the demanded SKU, plus slack, to cover the order. Operations from "avoid" suppliers are pinned to zero flow. The objective minimizes four components: base transport cost, a surcharge on flow through "watch" suppliers, a centrality penalty that discourages over-reliance on bottleneck sites, and a high penalty on unmet demand.
 
-problem.solve_for(Demand.x_unmet, name=["x_unmet", Demand.id], lower=0, populate=False)
-```
-
-The demand satisfaction constraint requires that inbound flow at each customer's site for the demanded SKU, plus unmet slack, covers the order quantity:
-
-```python
-problem.satisfy(
-    model.require(
-        sum(Op.x_flow).per(D) + D.x_unmet >= D.quantity
-    ).where(
-        D.business(B),
-        B.site == Op.output_site,
-        D.sku == Op.output_sku,
-    ),
-    name=["demand_sat", D.id],
-)
-```
+**Solve and run scenarios.** The baseline solves with HiGHS. Two disruption scenarios then re-solve with modified constraints -- taking the highest-centrality site offline, and downgrading all "watch" suppliers to "avoid" -- and the cost increase across scenarios quantifies the network's resilience to each type of disruption.
 
-Operations sourced from "avoid" suppliers are blocked with zero-flow constraints. In scenario mode, operations from a specific site can also be disabled.
+For the implementation, see `supply_chain_resilience.py`; to reproduce it step by step with the RAI skills, follow `runbook.md`.
 
-The objective minimizes four cost components. Transport cost is the base shipping cost. Risk surcharge penalizes flow through "watch"-level suppliers. The centrality penalty discourages over-reliance on bottleneck sites identified in Stage 1. Unmet demand incurs a high penalty:
+## Customize this template
 
-```python
-transport_cost = sum(Operation.cost_per_unit * Operation.x_flow)
+Focus on the first changes most users will make.
 
-risk_cost = RISK_SURCHARGE * sum(op_watch.x_flow).where(
-    op_watch.source_business(biz_watch),
-    biz_watch.is_watch_level(),
-)
+### Use your own data
 
-centrality_cost = CENTRALITY_WEIGHT * sum(
-    op_cent.x_flow * cent_val
-).where(
-    op_cent.output_site(site_cent),
-    site_cent.centrality(cent_val),
-)
+- Replace the CSVs in `data/` with your own; keep the column names listed in *Sample data* above.
+- For Snowflake-backed runs, swap the `pd.read_csv(...)` calls for `model.data(snowflake_table)` calls.
+- The `source_business` link is derived by matching `Operation.source_site` to `Business.site` -- ensure those IDs align across `operation.csv` and `business.csv` (the script prints a populated count on startup).
 
-unmet_cost = UNMET_PENALTY * sum(Demand.x_unmet)
+### Tune parameters
 
-problem.minimize(
-    sum(model.union(transport_cost, risk_cost, centrality_cost, unmet_cost))
-)
-```
+- **Risk thresholds** -- `RELIABILITY_THRESHOLD` and `DELAY_PROB_THRESHOLD` control which suppliers are flagged as unreliable or high-delay-risk.
+- **Prediction quarter** -- `PREDICTION_QUARTER` selects which quarter's delay predictions to use.
+- **Centrality weight** -- `CENTRALITY_WEIGHT` controls how strongly bottleneck penalties influence routing.
+- **Risk surcharge** -- `RISK_SURCHARGE` sets the cost penalty for "watch" suppliers.
+- **Unmet-demand penalty** -- `UNMET_PENALTY` controls the trade-off between routing cost and demand fulfillment.
 
-### Solve and run scenario analysis
+### Extend the model
 
-The model is solved using the HiGHS solver with a two-minute time limit. The `solve_flow` function encapsulates the full formulation and accepts optional parameters to disable a site or block additional suppliers:
+- Add new scenarios by calling `solve_flow()` with different `exclude_site_id` or `block_business_ids` parameters.
+- Add rows to the CSV files -- more sites, operations, or demand orders scale the network flow problem.
+- Swap eigenvector centrality for another graph algorithm (e.g. betweenness) to surface a different notion of structural criticality without changing the optimizer.
 
-```python
-problem.solve("highs", time_limit_sec=120)
-```
+### Scale up / productionize
 
-After the baseline solve, two disruption scenarios are evaluated by re-solving with modified constraints: taking the highest-centrality site offline, and downgrading all "watch" suppliers to "avoid". The cost increase across scenarios quantifies the network's resilience to each type of disruption.
-
-## Customize this template
-
-- **Adjust risk thresholds** via `RELIABILITY_THRESHOLD` and `DELAY_PROB_THRESHOLD` to control which suppliers are flagged as unreliable or high-delay-risk.
-- **Change the prediction quarter** via `PREDICTION_QUARTER` to use different ML delay predictions.
-- **Tune the centrality weight** via `CENTRALITY_WEIGHT` to control how strongly bottleneck penalties influence routing.
-- **Adjust the risk surcharge** via `RISK_SURCHARGE` to increase or decrease the cost penalty for "watch" suppliers.
-- **Change the unmet demand penalty** via `UNMET_PENALTY` to control the trade-off between routing cost and demand fulfillment.
-- **Add new scenarios** by calling `solve_flow()` with different `exclude_site_id` or `block_business_ids` parameters.
-- **Extend the data** by adding rows to the CSV files -- more sites, operations, or demand orders will scale the network flow problem.
+- Replace the `data/` CSV bundle with change-data-capture ingestion from the operator's upstream systems.
+- The formulation scales to whatever fits the prescriptive engine's solve budget; the reusable `solve_flow()` function makes scheduled re-solves and new disruption scenarios cheap to add.
 
 ## Troubleshooting
 
@@ -463,3 +247,20 @@ After the baseline solve, two disruption scenarios are evaluated by re-solving w
 - Run `rai init` to configure your Snowflake connection.
 - Verify that the RAI Native App is installed and your user has the required permissions.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Multi-reasoner workflows](https://docs.relational.ai/) -- chained reasoner patterns and accretive ontology enrichment.
+- [PyRel v1 query language](https://docs.relational.ai/) -- `model.where(...)` / `aggs` / `.define()`.
+
+### Reasoner reference
+
+- [Graph reasoner](https://docs.relational.ai/) -- connected components, eigenvector centrality, and reachability.
+- [Rules-based reasoning](https://docs.relational.ai/) -- deriving classifications and flags as relationships.
+- [Prescriptive reasoner](https://docs.relational.ai/) -- `Problem` API, decision variables, constraints, and objective.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/supply_chain_resilience/runbook.md b/v1/supply_chain_resilience/runbook.md
index 0ad2dd2c..2f15daaf 100644
--- a/v1/supply_chain_resilience/runbook.md
+++ b/v1/supply_chain_resilience/runbook.md
@@ -17,9 +17,9 @@ watch->avoid downgrade = +0.0% (optimizer already routed around it).
                               Upstream supplier dependency map for
                               each HIGH-priority customer (B008, B009).
   ─────────────────────────────────────────────────────────────────
-  STAGE 1  Graph        ──►  Site.centrality  (normalized)
-                              Top hubs: S004 TechAssembly 1.000,
-                              S006 West Coast DC 0.776, S003 PowerCell 0.735.
+  STAGE 1  Graph        ──►  Site.centrality  (eigenvector)
+                              Top hubs: S004 TechAssembly 0.5016,
+                              S006 West Coast DC 0.3895, S003 PowerCell 0.3688.
                               2 weakly-connected components.
   ─────────────────────────────────────────────────────────────────
   STAGE 2  Rules        ──►  Business.is_unreliable           (1)
@@ -97,7 +97,7 @@ Reasoner-routing plan: (1) Graph reachability for upstream supplier exposure, (2
 
 **Response**
 
-`Site.centrality` normalized [0,1]: S004=1.000, S006=0.776, S003=0.735; 2 weakly-connected components.
+`Site.centrality` (eigenvector): S004=0.5016, S006=0.3895, S003=0.3688; 2 weakly-connected components.
 
 ### 6. Classify supplier reliability
 
diff --git a/v1/supply_chain_transport/README.md b/v1/supply_chain_transport/README.md
index 373ab009..d18b1be7 100644
--- a/v1/supply_chain_transport/README.md
+++ b/v1/supply_chain_transport/README.md
@@ -13,8 +13,6 @@ tags:
   - logistics
 ---
 
-# Supply Chain Transport
-
 ## What this template is for
 
 In freight logistics, choosing between truckload (TL) and less-than-truckload (LTL) shipping modes involves a cost trade-off. TL shipments have a fixed cost per truck but offer lower per-unit rates for large volumes. LTL shipments have a piecewise cost structure that is cheaper for small volumes but expensive at scale. On top of mode selection, freight sitting in a vendor warehouse incurs inventory holding costs. The optimal strategy balances when to ship, how much to ship, and which mode to use.
@@ -25,21 +23,23 @@ The model demonstrates several advanced techniques: multi-period inventory flow
 
 ## Who this is for
 
-- Supply chain planners optimizing freight consolidation and mode selection
-- Logistics analysts comparing TL vs LTL cost trade-offs
-- Operations researchers building multi-period transport models
-- Developers learning mixed-integer programming with RelationalAI
+- Supply chain planners optimizing freight consolidation and mode selection.
+- Logistics analysts comparing TL vs LTL cost trade-offs.
+- Operations researchers building multi-period transport models.
+- Developers learning mixed-integer programming with RelationalAI.
+- **Assumed knowledge**: comfortable reading Python; the transport and optimization terms are explained as they come up. No prior RelationalAI experience is required to run it.
 
 ## What you'll build
 
-- A mixed-integer optimization model for multi-period freight transport
-- Joint inventory and transport decisions across TL and LTL modes
-- Piecewise linear LTL cost modeling with segment breakpoints
-- Arrival day computation linked to departure day and transit time
+- A cost-minimizing transport plan -- per-freight-group inventory levels, shipment quantities, mode choice, and arrival days -- produced by the **prescriptive** reasoner as a mixed-integer program.
+- A binary mode-selection decision (truckload vs less-than-truckload) coupled to shipment volume through big-M constraints, expressed as **prescriptive** decision variables and constraints.
+- A piecewise-linear cost model for less-than-truckload freight, with per-segment breakpoint variables the solver activates as volume grows.
+- Arrival days derived from departure day and transit time, linked into the solve so on-time-arrival deadlines are enforced as constraints.
 
 ## What's included
 
 - `supply_chain_transport.py` -- main script with ontology, formulation, and solver call
+- `runbook.md` -- a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself
 - `data/freight_groups.csv` -- 2 freight groups with inventory/transport/arrival windows
 - `pyproject.toml` -- Python package configuration
 
@@ -51,6 +51,7 @@ The model demonstrates several advanced techniques: multi-period inventory flow
 
 ### Tools
 - Python >= 3.10
+- RelationalAI Python SDK (`relationalai` == 1.0.14)
 
 ## Quickstart
 
@@ -88,30 +89,16 @@ The model demonstrates several advanced techniques: multi-period inventory flow
 6. Expected output:
    ```text
    Status: OPTIMAL
-   Total cost: $5080.00
-
-   === Inventory Levels ===
-   freight_group  day  inventory
-             fg1    1     4000.0
-             fg1    2     4000.0
-             fg1    3        0.0
-             fg1    4        0.0
-             fg2    2     5000.0
-             fg2    3     5000.0
-             fg2    4        0.0
-             fg2    5        0.0
+   Total cost: $1444.00
 
    === Transport Quantities ===
    type freight_group  day  quantity
-     tl           fg1    2    4000.0
-     tl           fg2    3    5000.0
-
-   === Arrival Days ===
-   freight_group  arrival_day
-             fg1          4.0
-             fg2          5.0
+    ltl           fg1    2    4000.0
+    ltl           fg2    2    5000.0
    ```
 
+   Both freight groups ship less-than-truckload on day 2 (zero truckload trucks); see `runbook.md` for the full inventory and arrival-day tables.
+
 ## Template structure
 ```text
 .
@@ -122,56 +109,67 @@ The model demonstrates several advanced techniques: multi-period inventory flow
     └── freight_groups.csv
 ```
 
-## How it works
+**Start here**: run `python supply_chain_transport.py` for the full formulation and solve end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-**1. Define freight groups with time windows.** Each freight group has inventory, transport, and arrival windows loaded from CSV:
+## Sample data
 
-```python
-FreightGroup = Concept("FreightGroup", identify_by={"name": String})
-FreightGroup.inv_start_t = Property(f"{FreightGroup} has {Integer:inv_start_t}")
-FreightGroup.tra_start_t = Property(f"{FreightGroup} has {Integer:tra_start_t}")
-FreightGroup.inv_start = Property(f"{FreightGroup} has {Float:inv_start}")
-```
+The bundled data is synthetic and illustrative -- a minimal two-group example designed to teach the formulation on a Snowflake-connected RAI account, not to match a specific shipper's freight book. The transport modes and cost segments are defined inline in the script, not loaded from CSV.
 
-**2. Define transport types and LTL cost segments.** TL and LTL modes are defined inline with transit times. LTL uses a piecewise linear cost structure:
+- **`freight_groups.csv`** (2 rows) -- one row per freight group, giving its inventory window (`inv_start_t` to `inv_end_t`), transport window (`tra_start_t` to `tra_end_t`), arrival window (`arr_start_t` to `arr_end_t`), and starting inventory weight (`inv_start`).
 
-```python
-tl = TransportType.new(name="tl")
-ltl = TransportType.new(name="ltl")
-model.define(tl, tl.transit_time(2))
-model.define(ltl, ltl.transit_time(3))
+## Model overview
 
-seg1 = LTLSegment.new(seg=1)
-model.define(seg1, seg1.limit(6000.0), seg1.cost(0.18))
-```
+The formulation is built on three concepts: the freight groups loaded from CSV, and the transport types and LTL cost segments defined inline in the script.
 
-**3. Formulate decision variables.** The model solves for inventory levels, transport quantities, binary mode indicators, arrival days, and piecewise LTL segment variables:
+- **Key entities**: `FreightGroup` — a batch of freight with its own inventory, transport, and arrival time windows (the optimization solves for its per-day inventory, shipment quantities, and arrival day); `TransportType` — a shipping mode (truckload or less-than-truckload), with its transit time; `LTLSegment` — a breakpoint in the piecewise-linear less-than-truckload cost curve.
+- **Primary identifiers**: `name` on `FreightGroup` and `TransportType`; integer `seg` on `LTLSegment`.
+- **Important invariants**: window start days are less than or equal to window end days; `inv_start` weights are non-negative; transport-mode indicators and segment activation variables are binary; each freight group ships all inventory out by the end of its inventory window.
 
-```python
-problem.solve_for(FreightGroup.x_inv(time_period_ref, x_inv), lower=0,
-    name=["x_inv", FreightGroup.name, time_period_ref],
-    where=[time_period_ref == std.common.range(FreightGroup.inv_start_t, FreightGroup.inv_end_t + 1)])
-```
+For the full concept and property definitions, see `supply_chain_transport.py`; `runbook.md` builds them step by step with the RAI skills.
 
-**4. Add inventory flow conservation.** Inventory on day t equals inventory on day t+1 plus what is shipped out:
+## How it works
 
-```python
-problem.satisfy(model.where(
-    FreightGroup.x_inv(time_period_ref, x_inv_current),
-    FreightGroup.x_inv(time_period_ref + 1, x_inv_next),
-    TransportType.x_qty_tra(FreightGroup, time_period_ref, x_qty_tra),
-).require(x_inv_current == x_inv_next + sum(x_qty_tra).per(FreightGroup, time_period_ref)))
+```text
+CSV freight groups + inline modes/segments → decision variables → inventory + mode + arrival constraints → cost objective → solve
 ```
 
-**5. Minimize total cost.** The objective combines inventory holding costs, TL fixed costs, and piecewise LTL variable costs.
+**1. Define freight groups with time windows.** Each freight group loads from CSV with its inventory, transport (departure), and arrival deadline windows plus a starting inventory weight.
+
+**2. Define transport types and LTL cost segments.** The two shipping modes -- truckload (TL, 2-day transit) and less-than-truckload (LTL, 3-day transit) -- are defined inline, along with the LTL cost-curve breakpoints. TL carries a flat per-truck fixed cost; LTL is priced as a piecewise-linear curve the solver walks up as volume grows.
+
+**3. Formulate decision variables.** The solve determines per-day inventory levels, per-mode shipment quantities, binary mode indicators, computed arrival days, and the piecewise LTL segment variables -- indexed over each group's own time windows.
+
+**4. Add constraints.** Multi-period inventory flow conservation ties each day's inventory to the next day's plus what ships out; big-M coupling links the binary mode indicator to shipment volume; segment-activation logic enforces the LTL piecewise cost; and arrival days derived from departure day plus transit time must land within each group's arrival window.
+
+**5. Minimize total cost.** The objective combines inventory holding cost, TL fixed cost, and piecewise LTL variable cost, and the MIP is solved end to end.
+
+For the implementation, see `supply_chain_transport.py`; to reproduce it step by step with the RAI skills, follow `runbook.md`.
 
 ## Customize this template
 
-- **Add more freight groups** by extending `freight_groups.csv` with additional rows and time windows.
-- **Adjust cost parameters** by changing `inv_cost`, `tl_tra_cost`, or the LTL segment costs and limits.
-- **Add more LTL segments** by defining additional `LTLSegment` instances for finer cost granularity.
-- **Extend to multiple origins/destinations** by adding location concepts and routing constraints.
-- **Add capacity constraints** on warehouses or transport links.
+Focus on the first changes most users will make.
+
+### Use your own data
+
+- Replace `data/freight_groups.csv` with your own; keep the column names listed in *Sample data* above.
+- Ensure each group's windows are internally consistent (start day less than or equal to end day) and that the arrival window is reachable given transit times.
+
+### Tune parameters
+
+- **Cost parameters** -- change `inv_cost`, `tl_tra_cost`, or the LTL segment costs and limits in the script.
+- **Transit times** -- adjust the inline `transit_time` values on the `tl` and `ltl` transport types.
+
+### Extend the model
+
+- Add more freight groups by extending `freight_groups.csv` with additional rows and time windows.
+- Add more LTL segments by defining additional `LTLSegment` instances for finer cost granularity.
+- Extend to multiple origins/destinations by adding location concepts and routing constraints.
+- Add capacity constraints on warehouses or transport links.
+
+### Scale up / productionize
+
+- Replace the CSV load with `model.data(snowflake_table)` for a Snowflake-backed freight book.
+- The formulation scales to many freight groups within the prescriptive engine's solve budget; pin the SDK version for reproducible runs.
 
 ## Troubleshooting
 
@@ -208,3 +206,19 @@ problem.satisfy(model.where(
 - Inventory holding is 0.1% of weight per day. Double-check that your freight weights match expectations.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) -- `model.where(...)` / `aggs` / `.define()`.
+- [Ontology modeling](https://docs.relational.ai/) -- concepts, properties, and inline instances.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) -- `Problem` API, decision variables, constraints, and objective.
+- [Mixed-integer programming patterns](https://docs.relational.ai/) -- binary coupling, big-M constraints, and piecewise-linear costs.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/synthetic_order_lifecycle/README.md b/v1/synthetic_order_lifecycle/README.md
index e53dcd9f..fe001993 100644
--- a/v1/synthetic_order_lifecycle/README.md
+++ b/v1/synthetic_order_lifecycle/README.md
@@ -60,7 +60,7 @@ The same pattern applies to any test-data-generation problem where rows have to
 
 ### Tools
 - Python >= 3.10
-- RelationalAI Python SDK (`relationalai == 1.12.0`)
+- RelationalAI Python SDK (`relationalai == 1.13.0`)
 
 ## Quickstart
 
@@ -254,8 +254,8 @@ model.require(problem.termination_status() == "OPTIMAL")
   <summary>Import error or AttributeError on <code>relationalai</code></summary>
 
 - Confirm your virtual environment is active: `which python` should point to `.venv`.
-- Reinstall dependencies: `python -m pip install .`. The pinned version (`relationalai==1.12.0`) ships enum members as constants across the DSL and prescriptive reasoning (alongside the `solve_info()`, `verify()`, and chained-`where().require()` APIs); older versions reject the enum-indexed decision variable and produce type or attribute errors.
-- If you share a venv across templates, run `python -m pip install --upgrade --force-reinstall relationalai==1.12.0`.
+- Reinstall dependencies: `python -m pip install .`. The pinned version (`relationalai==1.13.0`) ships enum members as constants across the DSL and prescriptive reasoning (alongside the `solve_info()`, `verify()`, and chained-`where().require()` APIs); older versions reject the enum-indexed decision variable and produce type or attribute errors.
+- If you share a venv across templates, run `python -m pip install --upgrade --force-reinstall relationalai==1.13.0`.
 
 </details>
 
diff --git a/v1/telco_network_recovery/README.md b/v1/telco_network_recovery/README.md
index 7eb17813..544af357 100644
--- a/v1/telco_network_recovery/README.md
+++ b/v1/telco_network_recovery/README.md
@@ -1,6 +1,6 @@
 ---
 title: "Telco Network Recovery"
-description: "Tower-upgrade planning on a shared telco ontology: an equipment-failure graph neural network (GNN) over a heterogeneous graph (with manufacturer advisories), declarative critical-tower rules, and customer-impact analysis (revenue x churn, with PageRank)."
+description: "Tower-upgrade planning on a shared telco ontology: an equipment-failure graph neural network (GNN) over a heterogeneous graph (with manufacturer advisories), declarative critical-tower rules, and customer-impact analysis (revenue times churn, with PageRank)."
 featured: false
 experience_level: advanced
 industry: "Technology & Telecom"
@@ -45,7 +45,8 @@ Built using **predictive reasoning** (GNN on a heterogeneous graph), **rules-bas
 ## What's included
 
 - **Model**: a 5-stage pipeline (predictive, then rules, then graph, then paths, then prescriptive) on a single shared ontology — 8 source-data concepts wired to the bundled CSVs, plus the enrichments each stage writes back.
-- **Runner**: `telco_network_recovery.py` — a single Python script with four module-scope stages, runs end-to-end against a Snowflake-connected RAI account.
+- **Runner**: `telco_network_recovery.py` — a single Python script with five module-scope stages, runs end-to-end against a Snowflake-connected RAI account.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Sample data**: 250 cell towers, 1,500 equipment items, 8 manufacturer advisories on 7 MODELs, 1,200 subscribers, 6,000 call records, 750 upgrade options. See *Sample data* below.
 - **Outputs**: per-stage stdout diagnostics plus an ontology-resident `RestorePlan` singleton holding cost, capacity, install-weeks, tier mix, towers covered, and binding constraint.
 
@@ -168,7 +169,7 @@ telco_network_recovery/
   pyproject.toml                  # dependencies
 ```
 
-**Start here**: run `python telco_network_recovery.py` for the full five-stage chain end to end, or follow `runbook.md` to rebuild it step by step.
+**Start here**: run `python telco_network_recovery.py` for the full five-stage chain end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Sample data
 
@@ -206,83 +207,7 @@ One shared ontology threads all five stages. Each stage reads concepts and prope
 - **Primary identifiers**: string ids on the base entities (e.g. `TOWER_ID`, `EQUIPMENT_ID`, `SUB_ID`); composite key on `TowerUpgradeOption` (`tower_id` + `tier`); MODEL string on `ModelAdvisory`.
 - **Important invariants**: `severity`, `churn_risk_score`, and `health_score` are fractions in `[0, 1]`; `capacity_gbps` and `cost` are non-negative; the GNN's `at_risk` label is `1` if `STATUS` is `FAILING` or `WARNING`; Stage 5 decision variables are binary.
 
-### Concepts
-
-**`CellTower`** — a cell tower with location, status, and region. Stages 1-3 enrich it with predicted-failure, operational, and customer-impact properties.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | String | Yes | `TOWER_ID` from `data/cell_towers.csv` |
-| `name`, `tower_type`, `status`, `region` | String | No | Loaded from CSV |
-| `capacity_gbps` | Integer | No | Baseline backhaul capacity |
-| `install_date` | DateTime | No | When the tower came online |
-| `failure_intensity` | Float | No | **Stage 1** GNN sum (per-tower) |
-| `avg_packet_loss`, `avg_latency_ms`, `avg_error_rate`, `avg_health_score` | Float | No | **Stage 2** rule-stage averages |
-| `is_critical_restore` | Relationship | — | **Stage 2** three-branch flag |
-| `impact_count`, `weighted_impact`, `weighted_pagerank` | Float | No | **Stage 3** customer-impact aggregates |
-
-**`NetworkEquipment`** — an equipment install on a tower. The GNN's prediction target.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | String | Yes | `EQUIPMENT_ID` |
-| `tower_id_fk` | String | No | Explicit FK column for GNN edge construction |
-| `equipment_type`, `manufacturer`, `eqp_model`, `firmware_version`, `status` | String | No | Categorical features |
-| `at_risk` | Integer | No | Binary label (1 if `STATUS in {FAILING, WARNING}`) |
-| `install_date` | DateTime | No | When installed |
-
-**`Subscriber`** — a customer account that places calls. Stage 3 reads `customer_value` and `status` to weight the per-tower aggregation.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | String | Yes | `SUB_ID` |
-| `subscriber_type`, `segment` | String | No | `CONSUMER`/`ENTERPRISE`; segment tier |
-| `status` | `SubscriberStatus` enum | No | `ACTIVE`/`SUSPENDED` — a `model.Enum`, mapped from the CSV strings by member name |
-| `lifetime_value` | Float | No | `LIFETIME_VALUE_USD` |
-| `churn_risk_score` | Float | No | `[0, 1]` — probability of churn |
-| `customer_value` | Float | No | Precomputed: `lifetime_value x (1 + churn_risk_score)` — the per-subscriber weight Stage 3 sums into `weighted_impact` |
-| `influence_score` | Float | No | **Stage 3** PageRank on the call graph |
-| `top_call_path_influence` | Float | No | **Stage 4** (PREVIEW) most-influential call path's summed PageRank, for the seed hub |
-
-**`TowerUpgradeOption`** — a (tower, tier) candidate upgrade. The MIP's decision space.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `tower_id`, `tier` | String | Yes | Composite key |
-| `capacity_increase_gbps` | Integer | No | Capacity restored if selected |
-| `cost` | Float | No | USD |
-| `install_weeks` | Integer | No | Crew weeks required |
-| `for_tower` | Relationship | — | Link back to `CellTower` |
-| `selected` | Float | No | **Stage 5** binary decision (0/1) |
-| `is_selected_upgrade` | Relationship | — | **Stage 5** narrowed view of `selected == 1` |
-
-**`ModelAdvisory`** — a manufacturer advisory on an equipment MODEL.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `model` | String | Yes | Identifies the affected MODEL |
-| `advisory_type` | String | No | `RECALL` / `DEFECT_BATCH` / `EOL` / `FIRMWARE_BUG` / `SECURITY_PATCH` |
-| `severity` | Float | No | `[0, 1]` — manufacturer-stated severity |
-| `issued_date` | DateTime | No | When issued |
-
-`EquipmentHealth`, `NetworkPerformance`, and `CallDetailRecord` are also Concepts (snapshots / metric rows / call edges); they serve as join sources for the aggregations and edges Stages 1-3 build. Their properties mirror their CSV columns.
-
-**`RestorePlan`** — singleton holding the plan headline.
-
-| Property | Type | Notes |
-|---|---|---|
-| `total_cost`, `capacity_restored_gbps`, `total_install_weeks` | Float / Integer | Headline metrics |
-| `gold_count`, `silver_count`, `bronze_count`, `towers_covered` | Integer | Tier mix and reach |
-| `binding_constraint` | String | `"budget"`, `"install_weeks"`, or `"none"` |
-
-### Relationships
-
-- `NetworkEquipment.tower_id_fk == CellTower.id` — equipment install on a tower (also a Stage 1 GNN edge).
-- `EquipmentHealth.equipment_id_fk == NetworkEquipment.id` — per-equipment health snapshot (GNN edge).
-- `ModelAdvisory.model == NetworkEquipment.eqp_model` — advisory links to every equipment item on the affected MODEL (GNN edge — propagates advisory severity across fleet siblings).
-- `CallDetailRecord.caller` and `.callee` -> `Subscriber` — directed edges of the Stage 3 PageRank call graph.
-- `CallDetailRecord.routed_through` -> `CellTower` — links each call to the tower it routed through; the per-tower customer-impact aggregation reads this.
-- `TowerUpgradeOption.for_tower` -> `CellTower` — Stage 5 scopes the decision space to options on critical-restore towers.
+For the full concept and property definitions, see `telco_network_recovery.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
@@ -294,24 +219,12 @@ One shared ontology threads all five stages. Each stage reads concepts and prope
 
 **Stage 4 — Paths (PREVIEW).** Where Stage 3 scores a *subscriber*, the paths capability scores the *route*: from the top-PageRank hub it enumerates the simple call paths (up to three hops) over an arity-3 caller-via-tower-callee edge and ranks them by summed PageRank influence. On the bundled data this is 198 simple call paths recovering 54 distinct routing towers; the hub's top route is persisted as `Subscriber.top_call_path_influence`.
 
-**Stage 5 — Prescriptive (MIP).** Binary `TowerUpgradeOption.selected`, scoped to critical-restore towers, with three constraints (at most one tier per tower, total cost at most $5M, total install-weeks at most 200) and a three-factor objective:
-
-```python
-problem.maximize(
-    aggs.sum(
-        TowerUpgradeOption.selected
-        * TowerUpgradeOption.capacity_increase_gbps
-        * CellTower.weighted_impact      # Stage 3: revenue × churn
-        * CellTower.failure_intensity    # Stage 1: GNN-predicted
-    ).where(
-        TowerUpgradeOption.for_tower(CellTower),
-        CellTower.is_critical_restore(),
-    )
-)
-```
+**Stage 5 — Prescriptive (MIP).** Binary `TowerUpgradeOption.selected`, scoped to critical-restore towers, with three constraints (at most one tier per tower, total cost at most $5M, total install-weeks at most 200). The objective maximizes restored capacity weighted by two upstream signals per tower — Stage 3's `weighted_impact` (revenue × churn) and Stage 1's `failure_intensity` (GNN-predicted risk) — so capacity spent on high-value, high-risk towers counts most.
 
 After the solve, a `RestorePlan` singleton is populated and each selected option is tagged `is_selected_upgrade`. Every selected tower carries a `rationale` tag in the printed plan noting which upstream signal(s) drove its inclusion (`operational` / `advisory/predicted` / `high-value`).
 
+For the implementation, see `telco_network_recovery.py`; to reproduce it step by step with the RAI skills, follow `runbook.md`.
+
 ## Customize this template
 
 Focus on the first changes most users will make.
diff --git a/v1/transaction_screening_local/README.md b/v1/transaction_screening_local/README.md
index 24e36817..b140a0c0 100644
--- a/v1/transaction_screening_local/README.md
+++ b/v1/transaction_screening_local/README.md
@@ -39,6 +39,7 @@ The value of the template is that you can try this entire workflow with nothing
 
 - **Model**: the `Account` concept, the `transfers_to` relationship, and the classification and expansion rules.
 - **Runner**: a single Python script, together with `runbook.md`, an analyst paste-test walkthrough.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - **Sample data**: a ledger of 75 transfers across 54 accounts. A structuring ring and a large sender are embedded in a legitimate-traffic majority, and 6 of the 54 accounts flag.
 - **Outputs**: printed tables for the network overview, per-account volume, suspects, counterparties, and the investigation set.
 
@@ -88,6 +89,34 @@ Local DuckDB execution relies on deploy mode, which the package currently flags
    python transaction_screening_local.py
    ```
 
+5. Expected output (abbreviated). The suspects and the investigation set confirm a successful run — 6 of 54 accounts flag, and the review set expands to 8:
+
+   ```text
+   == Network overview ==
+    transactions  total_moved
+              75       870000
+
+   == Suspect accounts (rules) ==
+    suspect
+      C1001
+      C2001
+      C2002
+      C2003
+      C2004
+      C2005
+
+   == Investigation set (suspect or one hop from a suspect) ==
+    flagged_for_review
+      C1001
+      C1002
+      C1003
+      C2001
+      C2002
+      C2003
+      C2004
+      C2005
+   ```
+
 ## Template structure
 
 ```text
@@ -100,7 +129,7 @@ transaction_screening_local/
     └── transactions.csv             # sample transfer ledger
 ```
 
-**Start here:** `transaction_screening_local.py` runs the whole template end to end.
+**Start here:** run `python transaction_screening_local.py` for the full run end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Sample data
 
@@ -112,61 +141,21 @@ transaction_screening_local/
 - **Primary identifier**: an account is identified by its `id`, drawn from both ends of every transfer.
 - **Important invariants**: every transfer has a sender and a receiver, and transfer amounts are positive.
 
-### Account
-
-The `Account` concept represents a party in the ledger. Accounts are derived from both the `src` and the `dst` of every transfer, so an account appears whether it ever sent money, received money, or both.
-
-| Property | Type | Identifying? | Notes |
-|---|---|---|---|
-| `id` | string | Yes | The account identifier, loaded from the `src` and `dst` columns of `data/transactions.csv` |
-
-### Relationships
-
-The model defines one stored relationship and a set of derived relationships that hold the classification rules.
-
-| Relationship | Reads as | Notes |
-|---|---|---|
-| `transfers_to(Account, Account)` | one account transferred money to another | One row per transfer, linking the sender to the receiver |
-| `is_structuring(Account)` | the account sent a transfer in the 9,000 to 10,000 band | Just under the 10,000 reporting threshold |
-| `is_large_sender(Account)` | the account sent a transfer over 50,000 | |
-| `is_suspect(Account)` | the account is structuring or is a large sender | Defined as two rules, which together form a logical OR |
-| `near_suspect(Account)` | the account transacted directly with a suspect | In either direction |
-| `under_review(Account)` | the account is a suspect or is near a suspect | This is the investigation set |
+For the full concept and property definitions, see `transaction_screening_local.py`; `runbook.md` builds them step by step with the RAI skills.
 
 ## How it works
 
-The local path is configured with a DuckDB connection plus a `deployment` section that sets the schema and turns on automatic deployment:
-
-```python
-config = create_config(
-    connections={"local": DuckDBConnection(path=":memory:")},  # or a file path, e.g. "./dev.duckdb"
-    default_connection="local",
-    deployment={"schema": "main", "auto_deploy": True},
-)
-```
-
-The `transfers_to` relationship is built with explicit two-ref binding so that each row links the correct source and destination accounts:
+The script starts by configuring a local DuckDB connection with automatic deployment, so the model materializes and runs on your machine with no Snowflake connection. It then loads the transfer ledger from CSV and derives an `Account` for every party seen at either end of a transfer.
 
-```python
-Account.transfers_to = model.Relationship(f"{Account} transfers to {Account:other}")
-_src, _dst = Account.ref(), Account.ref()
-model.where(_src.id == txn.src, _dst.id == txn.dst).define(_src.transfers_to(_dst))
-```
+Next it builds the `transfers_to` relationship, linking each sender to its receiver, one row per transfer. The classification rules follow as declarative derived relationships: an account is flagged as structuring when it sends a transfer just under the reporting threshold, and as a large sender when it sends a transfer over the large-transfer limit. An account is a suspect if either flag holds — expressed as two rules that together read as a logical OR.
 
-Rules are declarative derived relationships, and `is_suspect` chains on the flags below it:
+Finally, connectivity comes from a self-join over `transfers_to` rather than a graph reasoner: an account sits near a suspect if it transacted directly with one in either direction. The investigation set — accounts under review — is the union of suspects and their direct counterparties. The queries at the bottom of the script summarize the network and print the review set.
 
-```python
-Account.is_suspect = model.Relationship(f"{Account} is suspect")
-model.where(Account.is_structuring()).define(Account.is_suspect())
-model.where(Account.is_large_sender()).define(Account.is_suspect())
+```text
+transactions.csv → load → Account + transfers_to → classification rules → suspects → one-hop expansion → review set
 ```
 
-Connectivity, meaning who transacts with whom, comes from a self-join over `transfers_to` rather than from a graph reasoner:
-
-```python
-_other = Account.ref()
-model.where(Account.transfers_to(_other), _other.is_suspect()).define(Account.near_suspect())
-```
+See `transaction_screening_local.py` for the implementation, and `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Customize this template
 
@@ -182,7 +171,7 @@ Adjust `STRUCTURING_FLOOR`, `STRUCTURING_CEILING`, and `LARGE_TRANSFER` at the t
 
 Add new derived relationships in the same `define()` and `where()` style to capture additional rules, then surface them in the queries at the bottom of the script.
 
-### Scale up
+### Scale up / productionize
 
 To move from local development to production scale, point `model.Table(...)` at a Snowflake table instead of the DuckDB connection. The ontology, rules, and queries stay the same. Because deploy mode on local DuckDB is flagged as experimental, confirm the support stance before relying on it for customer-facing work.
 
@@ -206,6 +195,26 @@ Make sure the configuration includes a `deployment` section with `auto_deploy` s
 DuckDB is case-insensitive, so a source table named like a concept collides with the installed view. Keep source tables in a schema named `raw`, separate from the model install schema named `main`.
 </details>
 
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 modeling](https://docs.relational.ai/) — concepts, relationships, and the `define()` / `where()` workflow this template is built on.
+- [Local DuckDB development](https://docs.relational.ai/) — running RelationalAI on a local DuckDB database with no Snowflake account.
+
+### Language / modeling reference
+
+- [Rules and derived relationships](https://docs.relational.ai/) — authoring classification rules like `is_structuring`, `is_suspect`, and the investigation expansion.
+- [Querying](https://docs.relational.ai/) — `select()`, filtering, and aggregation for the summary and review tables.
+
+### CLI / SDK guides
+
+- [RelationalAI Python SDK](https://docs.relational.ai/) — installing and configuring the `relationalai` package.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
+
 ## Related templates
 
 - [commercial_underwriting](../commercial_underwriting/) is a rules-based eligibility and risk-tier classification on a hierarchical ontology.
diff --git a/v1/traveling_salesman/README.md b/v1/traveling_salesman/README.md
index b9fda9ff..416915a5 100644
--- a/v1/traveling_salesman/README.md
+++ b/v1/traveling_salesman/README.md
@@ -1,27 +1,25 @@
 ---
 title: "Traveling Salesman"
-description: "Find the shortest route visiting all cities exactly once using the MTZ formulation."
+description: "Find the shortest route that visits every city exactly once and returns home. A self-contained starting point for building route optimization on RelationalAI."
 featured: false
 experience_level: intermediate
 industry: "Supply Chain & Logistics"
 reasoning_types:
   - Prescriptive
 tags:
-  - routing
-  - mixed-integer-programming
-  - combinatorial-optimization
-  - graph
+  - Routing
+  - Mixed-Integer Programming (MIP)
+  - Combinatorial Optimization
+  - Miller-Tucker-Zemlin (MTZ)
 ---
 
-# Traveling Salesman
-
 ## What this template is for
 
-The traveling salesman problem (TSP) is one of the most studied problems in combinatorial optimization: given a set of cities and the distances between them, find the shortest tour that visits every city exactly once and returns to the starting city. TSP has practical applications in route planning, circuit board drilling, delivery logistics, and many other domains.
+A delivery driver, a service technician, or a drilling head has a list of stops and needs the cheapest way to visit them all and come back. The traveling salesman problem (TSP) captures exactly this: given a set of locations and the distances between them, find the shortest tour that visits every location once and returns to the start. It is one of the most studied problems in optimization and shows up across route planning, delivery logistics, circuit-board drilling, and scheduling.
 
-This template solves a small TSP instance using the Miller-Tucker-Zemlin (MTZ) formulation, which eliminates subtours through auxiliary ordering variables rather than exponentially many subtour-elimination constraints. The model uses binary decision variables for edge selection and integer auxiliary variables for node ordering, solved as a mixed-integer program with HiGHS.
+This template solves a small TSP instance end to end and gives you a clear, self-contained starting point for building route optimization on RelationalAI.
 
-The MTZ formulation is compact and well-suited for small to medium instances. For larger problems, more sophisticated formulations (cutting planes, branch-and-cut) would be needed, but this template provides a clear, self-contained starting point for understanding TSP modeling with RelationalAI.
+**Reasoning approach:** the tour is found with prescriptive reasoning — a mixed-integer program (MIP) whose binary variables choose which edges are on the route and whose Miller-Tucker-Zemlin (MTZ) auxiliary variables rule out disconnected subtours.
 
 ## Who this is for
 
@@ -32,14 +30,17 @@ The MTZ formulation is compact and well-suited for small to medium instances. Fo
 
 ## What you'll build
 
-- An MTZ-based TSP formulation with binary edge variables and integer ordering variables
-- Degree constraints ensuring exactly one in-edge and one out-edge per node
-- Subtour elimination via MTZ auxiliary variables
-- Optimal tour extraction from solver results
+- An optimal tour visiting every node exactly once, returned as the set of selected edges with a total distance.
+- A prescriptive MIP formulation with binary edge decisions and integer ordering variables, expressed directly on the ontology.
+- Degree constraints guaranteeing exactly one in-edge and one out-edge per node.
+- Miller-Tucker-Zemlin subtour elimination that keeps the solution a single connected cycle.
+
+Built using **prescriptive reasoning** (mixed-integer programming with the HiGHS solver).
 
 ## What's included
 
 - `traveling_salesman.py` -- main script with ontology, MTZ formulation, and solver call
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/edges.csv` -- 12 directed edges between 4 nodes with distances
 - `pyproject.toml` -- Python package configuration
 
@@ -51,6 +52,7 @@ The MTZ formulation is compact and well-suited for small to medium instances. Fo
 
 ### Tools
 - Python >= 3.10
+- RelationalAI Python SDK (`relationalai == 1.0.14`)
 
 ## Quickstart
 
@@ -99,73 +101,64 @@ The MTZ formulation is compact and well-suited for small to medium instances. Fo
    ```
 
 ## Template structure
+
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── traveling_salesman.py
+traveling_salesman/
+├── README.md            # this file
+├── pyproject.toml       # dependencies
+├── traveling_salesman.py # main script (ontology, MTZ formulation, solve)
 └── data/
-    └── edges.csv
+    └── edges.csv        # 12 directed edges between 4 nodes, with distances
 ```
 
-## How it works
+**Start here:** run `python traveling_salesman.py` for the full run end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-**1. Load the edge data and derive nodes.** Edges with distances are loaded from CSV. Nodes are derived from edge endpoints:
+## Sample data
 
-```python
-Edge = model.Concept("Edge", identify_by={"i": Integer, "j": Integer})
-Edge.dist = model.Property(f"{Edge} has {Float:dist}")
+`data/edges.csv` is a directed distance matrix with the columns `i`, `j`, and `dist`: a distance `dist` for traveling from node `i` to node `j`. The bundled instance has 12 directed edges connecting 4 nodes, with an edge in both directions between every pair, so the graph is strongly connected and a tour always exists. Nodes are not listed in their own file; the model derives them from the edge endpoints.
 
-Node = model.Concept("Node", identify_by={"v": Integer})
-model.define(Node.new(v=Edge.i))
-```
+## Model overview
 
-**2. Define decision variables.** Binary variables `x[i,j]` select edges in the tour. Integer auxiliary variables `u[v]` enforce node ordering for subtour elimination:
+The model has two concepts: the `Edge` rows loaded from CSV, and the `Node` set derived from edge endpoints. The optimizer adds one decision per edge and one ordering value per node.
 
-```python
-Edge.x = model.Property(f"{Edge} is selected if {Float:x}")
-problem.solve_for(Edge.x, type="bin", name=["x", Edge.i, Edge.j])
+- **Key entities**: `Edge` (a directed leg with a distance), `Node` (a location to visit).
+- **Primary identifiers**: an `Edge` is identified by its endpoint pair `(i, j)`; a `Node` is identified by its index `v`.
+- **Important invariants**: distances are non-negative; every node needs exactly one in-edge and one out-edge; the selected edges must form a single cycle (no subtours).
 
-Node.u = model.Property(f"{Node} has auxiliary value {Float:u}")
-problem.solve_for(Node.u, name=["u", Node.v], type="int", lower=1, upper=node_count)
-```
+For the full concept and property definitions, see `traveling_salesman.py`; `runbook.md` builds them step by step with the RAI skills.
+
+## How it works
+
+The script loads the directed edges with their distances from CSV, then derives the `Node` set from the edge endpoints so nodes never need their own file. On the ontology it lays down the decision variables the solver will fill in: a binary variable per edge (1 if the edge is on the tour) and an integer ordering value per node used for subtour elimination.
 
-**3. Add degree constraints.** Every node must have exactly one incoming and one outgoing edge:
+Two families of constraints shape the tour. Degree constraints require exactly one incoming and one outgoing selected edge at every node, so the route enters and leaves each stop once. Miller-Tucker-Zemlin (MTZ) constraints tie the ordering values together: whenever an edge is selected, the destination's order must exceed the source's, which is what rules out disconnected subtours and forces a single connected cycle. The objective minimizes the total distance of the selected edges, and the HiGHS solver returns the optimal tour.
 
-```python
-node_flow = sum(Edge.x).per(Node)
-problem.satisfy(model.require(
-    node_flow.where(Edge.j == Node.v) == 1,
-    node_flow.where(Edge.i == Node.v) == 1
-))
+```text
+edges.csv → load edges → derive nodes → edge + ordering variables → degree + MTZ constraints → minimize distance → optimal tour
 ```
 
-**4. Add MTZ subtour elimination.** If edge (i,j) is in the tour, then the ordering of j must be at least one more than i. This prevents disconnected subtours:
+See `traveling_salesman.py` for the implementation, and `runbook.md` to reproduce it step by step with the RAI skills.
 
-```python
-problem.satisfy(model.where(
-    Ni := Node, Nj := Node.ref(),
-    Edge.i > 1, Edge.j > 1,
-    Ni.v(Edge.i), Nj.v(Edge.j),
-).require(
-    Ni.u - Nj.u + node_count * Edge.x <= node_count - 1
-))
-```
+## Customize this template
 
-**5. Minimize total tour distance:**
+### Use your own data
 
-```python
-total_dist = sum(Edge.dist * Edge.x)
-problem.minimize(total_dist)
-```
+- Replace `data/edges.csv` with your own city-to-city distance matrix, as a list of directed edges with the columns `i`, `j`, and `dist`, or change the `read_csv(...)` path in the script.
+- Provide an edge in both directions for every pair of nodes so the graph stays strongly connected. Asymmetric costs are supported: give the forward and reverse edges different `dist` values.
 
-## Customize this template
+### Tune parameters
 
-- **Use your own distance data** by replacing `edges.csv` with your city-to-city distance matrix (as a list of directed edges).
-- **Scale to more cities** by adding nodes and edges. The MTZ formulation works well for up to ~50 nodes.
-- **Add asymmetric costs** -- the formulation already supports directed edges with different forward/reverse distances.
-- **Add time windows** by introducing arrival time variables and constraints per node.
-- **Visualize the tour** by plotting nodes and selected edges with matplotlib.
+- The solve time cap is `time_limit_sec` (default 60) in the `problem.solve("highs", ...)` call. Lower it to accept a near-optimal tour sooner on larger instances.
+
+### Extend the model
+
+- Add time windows by introducing per-node arrival-time variables and constraints.
+- Visualize the result by plotting the nodes and the selected edges with a plotting library such as matplotlib.
+
+### Scale up / productionize
+
+- The MTZ formulation is compact and works well for small to medium instances (up to roughly 50 nodes). Its subtour-elimination constraints grow with the square of the node count, so solves slow down as instances grow.
+- For production-scale routing (100+ stops), move to specialized TSP solvers or cutting-plane / branch-and-cut formulations.
 
 ## Troubleshooting
 
@@ -201,3 +194,22 @@ problem.minimize(total_dist)
 - For production-scale TSP (100+ cities), consider specialized TSP solvers or cutting-plane approaches.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Prescriptive reasoning](https://docs.relational.ai/) — the `Problem` API, decision variables, constraints, and objectives used here.
+- [PyRel v1 modeling](https://docs.relational.ai/) — concepts, properties, and deriving one concept from another (nodes from edges).
+
+### Language / modeling reference
+
+- [Constraints and objectives](https://docs.relational.ai/) — `satisfy()`, `require()`, `minimize()`, and per-group aggregation with `.per(...)`.
+
+### CLI / SDK guides
+
+- [RelationalAI Python SDK](https://docs.relational.ai/) — installing and configuring the `relationalai` package and connecting to Snowflake.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/underwriting_audit/README.md b/v1/underwriting_audit/README.md
index 0b43e20f..804568af 100644
--- a/v1/underwriting_audit/README.md
+++ b/v1/underwriting_audit/README.md
@@ -1,55 +1,48 @@
 ---
 title: "Underwriting Audit"
-description: "Audit an underwriting ruleset against a catalog of properties. For each, either prove it holds (PASS) or return K distinct counterexample applicants that falsify it (FAIL). Multi-property batch audit in multi-solution mode."
+description: "Audit an underwriting ruleset against a catalog of required properties. For each property, the solver either proves it always holds or returns concrete counterexample applicants that break it."
 featured: false
 experience_level: advanced
 industry: "Financial Services"
 reasoning_types:
   - Prescriptive
 tags:
-  - constraint-programming
-  - multi-solution
-  - rule-verification
-  - audit
-  - insurance
-  - regtech
+  - Constraint Programming
+  - Rule Verification
+  - Multi-Solution Search
+  - Audit
+  - Insurance
+  - RegTech
 ---
 
-# Underwriting Audit
-
 ## What this template is for
 
-Insurance actuaries, RegTech audit teams, and Model Risk Management (MRM) reviewers periodically audit underwriting rulesets to verify that the rules enforce stated properties: "no high-risk applicant is auto-approved", "every frail applicant goes through manual review", "no policy exceeds the regulatory ceiling without two-signoff". Hand-checking a ruleset of even a few dozen rules against a property is intractable; sampled fixtures only catch the failures that happen to be in the sample. The right answer is verification: declare the ruleset and the property as a constraint model, ask the solver if any feasible applicant falsifies the property, and if so, return the *witness*.
-
-Real audits are a *batch* operation. The rule team owns the rule pack; the compliance / MRM team owns a catalog of properties the rule pack must satisfy. This template demonstrates that shape: a `PROPERTIES` catalog is separately authored from the rule pack, and a single audit run produces one verdict (PASS / FAIL / INCONCLUSIVE) per property plus witness tables for each FAIL. The mixed-verdict output is the point -- the audit is not rigged to always fail; it distinguishes properties the rule pack satisfies from those it violates. Bundling them in one script makes the per-run audit report the natural deliverable.
+Insurance actuaries, regulatory-technology (RegTech) audit teams, and Model Risk Management (MRM) reviewers periodically check underwriting rulesets against the properties those rules are supposed to guarantee: no high-risk applicant is auto-approved, every frail applicant goes through manual review, no policy exceeds the regulatory ceiling without a second sign-off. Hand-checking even a few dozen rules against a property is impractical, and testing on a sample of applicants only catches the failures that happen to be in the sample. The dependable answer is verification: state the ruleset and the property as a constraint model and ask the solver whether any applicant at all can slip through. If one can, the solver hands back the concrete applicant that breaks the rule.
 
-Audit / counterexample surfacing is plural per property as well. One witness tells the actuary that a property fails; K distinct witnesses surface concrete failure cases across age buckets, condition profiles, and coverage bands the buggy rule misses. A single counterexample is unhelpful for triage because the actuary then has to manually probe variations to understand the failure shape. K distinct witnesses surface the failure shape automatically. The solver guarantees pairwise distinctness, not maximal diversity -- to exhaust the failure space, raise `MAX_WITNESSES` past the size of the feasible set. Each property's audit runs in multi-solution mode (`solution_limit=K`) and reads back witnesses via `Variable.values(solution_index, value)`.
+A real audit is a batch job across many properties at once, and the two sides are owned by different teams: the rule team owns the rule pack, and the compliance or MRM team owns the catalog of properties it must satisfy. This template mirrors that shape. It authors a property catalog separately from the ruleset, then runs one audit per property and produces a single report with a verdict for each — the rule holds (PASS), the rule is broken with example applicants shown (FAIL), or the audit could not decide (INCONCLUSIVE). The bundled ruleset carries a deliberate bug so the report comes back mixed rather than all-clear: the manual-review rule flags only seniors, while the frailty rule counts anyone senior or with a chronic condition, so chronic non-seniors slip past review. The mixed report is the point — a single run separates the properties the ruleset satisfies from the ones it violates. And rather than a single example per failure, the audit returns several distinct counterexamples so the reviewer can see the shape of the failure across ages, conditions, and coverage levels without probing by hand.
 
-The bundled ruleset has a deliberate bug: `is_manual_review` is defined as "senior", but `is_frail` is defined as "senior OR has chronic condition". The bundled property catalog mixes verdicts and witness shapes: `frail_implies_review` FAILs broadly (12 chronic-non-senior witnesses across all four coverage bands and three non-senior age buckets); `chronic_under_50_implies_review` FAILs on a scoped sub-population (8 witnesses -- a strict subset of #1 restricted to age < 50, illustrating property scoping); `senior_implies_review` PASSes (INFEASIBLE) because the buggy rule literally encodes it. The same template structure -- scalar applicant decisions, derived rule indicators via OR-arithmetic equivalences, a property catalog with counterexample-IC builders, fresh-Model-per-audit factory -- adapts to any rule-based regulated domain (bank AML rules, healthcare prior-auth, manufacturing segregation-of-duties, SaaS retention). Real rule packs in those domains often contain hundreds of rules; the per-audit fresh-Model factory only isolates the rule count across iterations, so a single audit's rule pack still needs to stay under PyRel's per-Model `"Rules created in a loop"` threshold -- decompose into smaller property-scoped rule packs if it doesn't.
+**Reasoning approach:** each property is audited with prescriptive reasoning — a constraint-satisfaction model whose counterexample is the logical negation of the property, solved in multi-solution mode so the solver returns several distinct applicants that break the rule (or proves none exist).
 
 ## Who this is for
 
 - Insurance actuaries and underwriting governance teams auditing rule libraries
 - RegTech / compliance audit harnesses verifying property entailment over rule packs
 - Model Risk Management (MRM) reviewers performing rule-level verification before promotion
-- Operations researchers learning property-entailment audit as a CSP problem
+- Operations researchers learning property-entailment audit as a constraint satisfaction problem (CSP)
 
 ## What you'll build
 
-- A constraint model with three scalar free decisions (`age_bucket_id`, `has_chronic`, `coverage_band_id`) plus three derived binary indicators (`is_senior`, `is_frail`, `is_manual_review`) tied to the free decisions via solver-side ICs. `age_bucket_id` and `has_chronic` drive the indicator rules; `coverage_band_id` enters no rule IC and is a spread-only decision dimension whose role is to diversify witness output across coverage bands. Each decision is declared as `model.Relationship(f"{Integer:name}")` -- the unparented scalar shape -- rather than a property on a singleton `Applicant` concept, because there is exactly one applicant slot and the concept adds identity overhead with no payoff at N=1
-- A senior-indicator definition iterating over `AgeBucket` reference rows at relational time and binding `is_senior` via two `implies`-bodied ICs (one for senior buckets, one for non-senior)
-- A frail-indicator definition encoding `is_frail = is_senior OR has_chronic` via the standard OR-arithmetic equivalence on binaries (three linear ICs: two lower bounds, one upper bound)
-- A buggy `is_manual_review = is_senior` definition encoded as a binary equality (the audit will surface its missing chronic-condition arm)
-- A `_build_session()` factory that constructs a fresh `Model` per audit, bundling the concepts, scalar decisions, and rule pack into a `SimpleNamespace`. Returning a fresh model per audit (not per property *Problem*) is necessary because PyRel emits a `"Rules created in a loop"` warning when the per-Model internal-rule count crosses a fixed threshold; cumulative `problem.satisfy(...)` calls across iterations of a shared model trip it
-- A `PROPERTIES` catalog: a Python list of `(name, description, counterexample_builder)` tuples. The builder takes the audit session and returns the property's counterexample ICs against its freshly-built model. Scoped properties (e.g. "chronic applicants under age 50") use a `model.where(...)` data filter plus a decision-variable constraint in `require` to restrict the search sub-population
-- **A `run_audit(...)` helper that owns the per-property lifecycle**: build session, create `Problem`, re-bind every scalar decision via `solve_for(...)`, attach the rule pack and the property's counterexample ICs via `problem.satisfy(...)`, solve, classify, print witnesses (FAIL only), return the result. Each call is a fully isolated audit -- the model, decisions, rule pack, and Problem are all per-audit. The main loop is then a list comprehension over `PROPERTIES`
-- **Multi-solution enumeration as the per-property code path**: each `problem.solve(..., solution_limit=MAX_WITNESSES)` runs the search in enumeration mode; `Variable.values(solution_index, value)` joins the decision variables on a shared solution index to reconstruct each witness
-- A pre-solve check that reference IDs are dense and contiguous, so `lower=min(id), upper=max(id)` decision bounds line up with the reference rows the relational-time `implies` rules iterate over (sparse IDs would let the solver pick a value with no matching row, leaving the rule indicators unconstrained for that solution)
-- A per-property verdict driven by `solve_info().termination_status`: any status with one or more witnesses is **FAIL** (one witness falsifies the property regardless of whether the search exhausted), `INFEASIBLE` (or `OPTIMAL` with zero witnesses) is **PASS**, and anything else (`TIME_LIMIT`, `MEMORY_LIMIT`, ... with zero witnesses) is **INCONCLUSIVE**. Local-only statuses from continuous solvers (e.g. `LOCALLY_SOLVED`) are not exhaustion proofs and route to `INCONCLUSIVE`. Verdicts are stashed in a `results` list and printed as a verdict-matrix table at the end of the run
+- A batch audit report — one verdict (PASS, FAIL, or INCONCLUSIVE) per property, printed as a verdict matrix, distinguishing the rules the ruleset satisfies from the ones it breaks.
+- Witness tables for every failing property: several distinct counterexample applicants that break the rule, spread across ages, conditions, and coverage bands.
+- A constraint model of the ruleset itself — the applicant's attributes as free decisions and each rule as a derived indicator — built with prescriptive reasoning so a property is checked by asking the solver for any applicant that falsifies it.
+- A separately-authored property catalog and a per-property audit routine, so adding a new property to check is a one-line change with no other code touched.
+
+Built using **prescriptive reasoning** (constraint satisfaction with multi-solution enumeration on the MiniZinc solver).
 
 ## What's included
 
 - `underwriting_audit.py` -- main script with ontology, decisions, constraints, and solver call
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
 - `data/age_buckets.csv` -- 4 representative ages (28, 45, 55, 72) -- three under the 70 senior threshold, one above
 - `data/coverage_bands.csv` -- 4 coverage levels ($100k, $250k, $500k, $1M)
 - `pyproject.toml` -- Python package configuration
@@ -62,6 +55,7 @@ The bundled ruleset has a deliberate bug: `is_manual_review` is defined as "seni
 
 ### Tools
 - Python >= 3.10
+- RelationalAI Python SDK (`relationalai == 1.1.0`)
 
 ## Quickstart
 
@@ -96,229 +90,93 @@ The bundled ruleset has a deliberate bug: `is_manual_review` is defined as "seni
    python underwriting_audit.py
    ```
 
-6. Expected output. The audit loop processes the three bundled properties in turn. For each FAIL the witness table prints inline (under the property's verdict line); the verdict matrix follows at the end. With `MAX_WITNESSES = 16` each FAIL solve exhausts its feasible set and reports `status: OPTIMAL`: 12 witnesses for the broad `frail_implies_review`, 8 for the scoped `chronic_under_50_implies_review` (restricted to age < 50). Per-solution row ordering and wall times will vary across runs; the *set* of witnesses per property is stable because the search exhausts. Abridged output:
+6. Expected output. The audit processes the three bundled properties in turn, printing each verdict with its witness table (for FAILs), then a verdict matrix at the end. A few representative lines confirm a successful run:
 
    ```text
    ===== Auditing property: frail_implies_review =====
-   Description: every frail applicant goes through manual review
-   ... [problem.display() and solve progress] ...
    Verdict: FAIL  (12 witness(es), status=OPTIMAL)
-
-   Witnesses (up to 16 per run):
-      solution age_years has_chronic coverage_dollars is_senior is_frail is_manual_review
-   0         0        55           1          1000000         0        1                0
-   1         1        55           1           500000         0        1                0
-   ...      (12 rows total: has_chronic is forced to 1 by the counterexample, so the spread is over 3 non-senior age buckets × 4 coverage bands)
-
-   ===== Auditing property: chronic_under_50_implies_review =====
-   Description: every chronic applicant under age 50 goes through manual review
-   Verdict: FAIL  (8 witness(es), status=OPTIMAL)
-
-   Witnesses (up to 16 per run):
-     solution age_years has_chronic coverage_dollars is_senior is_frail is_manual_review
-   0        0        45           1          1000000         0        1                0
-   1        1        28           1          1000000         0        1                0
-   ...     (8 rows total, covering 2 under-50 age buckets × 4 coverage bands -- a strict subset of property 1's witnesses)
-
-   ===== Auditing property: senior_implies_review =====
-   Description: every senior applicant goes through manual review
-   Verdict: PASS  (0 witness(es), status=INFEASIBLE)
-
-   ================================================================================
+   ...
    Audit report (3 properties: 1 PASS, 2 FAIL, 0 INCONCLUSIVE)
-   ================================================================================
-     Property                         Verdict         Witnesses  Description
-     ------------------------------------------------------------------------------------------
-     frail_implies_review             FAIL                   12  every frail applicant goes through manual review
-     chronic_under_50_implies_review  FAIL                    8  every chronic applicant under age 50 goes through manual review
-     senior_implies_review            PASS                    0  every senior applicant goes through manual review
    ```
 
-   Each FAIL witness row is one applicant who falsifies that property: chronic (`has_chronic == 1`), frail under the rule book (`is_frail == 1`, via the OR rule), but missed by manual review (`is_manual_review == 0`) because the buggy rule only flags seniors and these applicants are below the 70 threshold. **FAIL** means *the ruleset under audit fails the property* -- the audit tool itself ran cleanly; FAIL is the audit's *finding*, not a template error. **PASS** on `senior_implies_review` means the solver proved no counterexample exists -- the buggy rule literally encodes "manual review = senior", so "every senior gets manual review" is trivially satisfied. The witness-count gap (12 vs 8) demonstrates *property scoping*: `chronic_under_50_implies_review` restricts its counterexample to a sub-population, and the audit reports a correspondingly narrower failure shape. The mixed-verdict matrix at the bottom is the audit's headline deliverable: a single run distinguishes properties the ruleset satisfies from those it violates. Lower `MAX_WITNESSES` below the feasible-set size (e.g. 4) to demonstrate the `SOLUTION_LIMIT` outcome where the solver returns a sample and signals that more witnesses may exist.
+   FAIL is the audit's finding about the ruleset, not a template error; a PASS means the solver proved no counterexample exists. The full printout and a step-by-step walkthrough are in `runbook.md`.
 
 ## Template structure
+
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── underwriting_audit.py
+underwriting_audit/
+├── README.md            # this file
+├── runbook.md           # analyst paste-test walkthrough
+├── pyproject.toml       # dependencies
+├── underwriting_audit.py # main script (ontology, decisions, rule pack, property catalog, audit loop)
 └── data/
-    ├── age_buckets.csv
-    └── coverage_bands.csv
+    ├── age_buckets.csv    # representative applicant ages
+    └── coverage_bands.csv # representative coverage levels
 ```
 
-## How it works
+**Start here:** run `python underwriting_audit.py` for the full batch audit end to end, or follow `runbook.md` to reproduce it step by step with the RAI skills.
 
-The template factors the audit into three artifacts: a `_build_session()` factory that constructs a fresh `Model` per audit (with the concepts, scalar decisions, and rule pack bundled into a `SimpleNamespace`); a `PROPERTIES` catalog that pairs each property's name and description with a counterexample-IC builder; and a `run_audit(...)` helper that owns one property's full lifecycle (build session, create `Problem`, satisfy ICs, solve, verdict, witnesses). The main script is a list comprehension over `PROPERTIES`, then a verdict-matrix recap. The script consists of these patterns:
+## Sample data
 
-**Free decisions describe what an applicant looks like.** Three integer/binary scalar decisions: which age bucket the applicant falls into, whether they have a chronic condition, which coverage band they sit in. Each is `model.Relationship(f"{Integer:name}")` (the unparented scalar shape), not a property on a singleton `Applicant` concept. The solver picks values for these on every solution. `age_bucket_id` and `has_chronic` drive the rules below; `coverage_band_id` enters no rule IC and is left in as a spread-only dimension that diversifies witness output (and gives customisation room when coverage thresholds need to enter the rule pack).
+The two small reference files describe the applicant space the audit searches over. They are the dimensions of an applicant, not a population of applicants — the solver picks values from them on every solution.
 
-```python
-age_bucket_id = model.Relationship(f"{Integer:age_bucket_id}")
-has_chronic = model.Relationship(f"{Integer:has_chronic}")
-coverage_band_id = model.Relationship(f"{Integer:coverage_band_id}")
-```
+- `data/age_buckets.csv` — 4 representative ages (28, 45, 55, 72), three below the 70-year senior threshold and one above, with the columns `id` and `age_years`.
+- `data/coverage_bands.csv` — 4 coverage levels ($100k, $250k, $500k, $1M), with the columns `id` and `coverage_dollars`.
 
-**Derived indicators encode the rule body.** Three more scalar binaries -- `is_senior`, `is_frail`, `is_manual_review` -- defined via solver-side ICs that pin them to functions of the free decisions. Treating the indicators as decisions (rather than as relational-time predicates) lets the property-entailment IC compare them directly:
+Both files need dense, contiguous `id` values (the audit checks this before solving), because the decision-variable bounds run from the minimum to the maximum id and the rules iterate over the reference rows in between.
 
-```python
-is_senior = model.Relationship(f"{Integer:is_senior}")
-is_frail = model.Relationship(f"{Integer:is_frail}")
-is_manual_review = model.Relationship(f"{Integer:is_manual_review}")
-```
+## Model overview
 
-**Senior indicator via per-bucket iteration.** `is_senior` is 1 iff the applicant's age bucket has age >= 70. Iterate over `AgeBucket` reference rows at relational time and gate on the decision-valued `age_bucket_id == AgeBucket.id` inside `implies`. Two ICs cover both directions of the equivalence:
+Rather than a table of applicants, the model has one applicant slot described by free decisions the solver fills in, plus derived indicators that encode each rule. Two reference concepts, `AgeBucket` and `CoverageBand`, supply the values the decisions can take.
 
-```python
-senior_def_pos_ic = model.where(AgeBucket.age_years >= SENIOR_THRESHOLD_YEARS).require(
-    implies(age_bucket_id == AgeBucket.id, is_senior == 1)
-)
-senior_def_neg_ic = model.where(AgeBucket.age_years < SENIOR_THRESHOLD_YEARS).require(
-    implies(age_bucket_id == AgeBucket.id, is_senior == 0)
-)
-```
+- **Key entities**: `AgeBucket` and `CoverageBand` (reference rows loaded from CSV); the applicant is represented by scalar decisions rather than a concept.
+- **Primary identifiers**: `AgeBucket` and `CoverageBand` are each identified by an integer `id`.
+- **Important invariants**: reference ids are dense and contiguous; the free decisions `age_bucket_id`, `has_chronic`, and `coverage_band_id` select one reference row (or a binary flag); the rule indicators `is_senior`, `is_frail`, and `is_manual_review` are binaries pinned to those decisions by the rule pack.
 
-**Frail indicator via OR-arithmetic equivalence.** `is_frail = is_senior OR has_chronic`. The standard CSP encoding for OR over binaries is three linear ICs -- `y >= a`, `y >= b`, `y <= a + b` -- which together force `y` to equal `max(a, b)`. All three are pure relational arithmetic:
+For the full concept and property definitions, see `underwriting_audit.py`; `runbook.md` builds them step by step with the RAI skills.
 
-```python
-frail_lb_senior_ic = model.require(is_frail >= is_senior)
-frail_lb_chronic_ic = model.require(is_frail >= has_chronic)
-frail_ub_ic = model.require(is_frail <= is_senior + has_chronic)
-```
+## How it works
 
-**Buggy manual-review rule via equality.** The bundled ruleset has `is_manual_review = is_senior`, encoded as a single equality. The intended rule was `is_manual_review = is_frail`; the missing chronic arm is exactly what the audit exposes:
+The template factors the audit into three artifacts. A session factory constructs a fresh model for each audit — the concepts, the scalar decisions that describe an applicant, and the rule pack bundled together. A property catalog pairs each property's name and description with a builder for its counterexample constraints. And a per-property audit routine owns one property's full lifecycle: build the session, create the problem, attach the constraints, solve, classify the verdict, and read back the witnesses. The main script simply runs the routine over every property in the catalog and prints a verdict matrix at the end.
 
-```python
-manual_review_eq_ic = model.require(is_manual_review == is_senior)
-```
+An applicant is described entirely by free decisions the solver fills in — which age bucket they fall into, whether they have a chronic condition, which coverage band they sit in — rather than by a row in an applicant table. On top of those, three rule indicators (`is_senior`, `is_frail`, `is_manual_review`) are also modeled as decisions, so the property check can compare them directly. The rule pack pins each indicator to a function of the free decisions: the senior indicator turns on when the chosen age bucket is at or above the senior threshold; the frailty indicator is the logical OR of senior-or-chronic, encoded as the standard three-constraint arithmetic for OR over binaries; and the manual-review indicator is pinned by the bundled — deliberately buggy — rule to the senior indicator alone, omitting the chronic arm that the audit is designed to expose.
 
-The rule pack is then bundled into a list inside the session-builder for one-pass attachment in `run_audit(...)`:
+Each property in the catalog is checked by asserting its logical negation and asking the solver for any applicant that satisfies it. If the solver finds one, the property is violated (FAIL) and the assignment is a concrete counterexample; if it proves none exists, the property holds (PASS); if it cannot decide within the time budget, the verdict is INCONCLUSIVE. Scoped properties add a data-filtered constraint to restrict the sub-population searched. Solving in multi-solution mode returns several distinct counterexamples per failure, each read back through the solver's per-solution values so the reviewer sees the shape of the failure across ages, conditions, and coverage bands. A fresh model per audit keeps the per-model rule count bounded, which matters as the rule pack grows.
 
-```python
-rule_pack = [
-    senior_def_pos_ic, senior_def_neg_ic,
-    frail_lb_senior_ic, frail_lb_chronic_ic, frail_ub_ic,
-    manual_review_eq_ic,
-]
+```text
+reference CSVs → free decisions + rule indicators → rule pack → per-property: assert negation → solve → PASS/FAIL/INCONCLUSIVE + witnesses → verdict matrix
 ```
 
-**Audit session factory: fresh Model per audit.** `_build_session()` is the single entry point that constructs a fresh `Model`, defines the concepts, scalar decisions, and rule pack on it, and returns a `SimpleNamespace` exposing every artifact the per-property audit needs. Fresh model per audit -- not per Problem -- is necessary because PyRel emits a `"Rules created in a loop"` warning when the per-Model internal-rule count crosses a fixed threshold; cumulative `problem.satisfy(...)` calls across iterations of a shared model would trip it after a few audits. The build is cheap (concepts + relationships + IC handles, no solver work); the costly path is the solve below.
-
-```python
-def _build_session():
-    model = Model("underwriting_audit")
-    AgeBucket = model.Concept("AgeBucket", identify_by={"id": Integer})
-    # ... CoverageBand, scalar decisions, rule pack ICs ...
-    return SimpleNamespace(
-        model=model,
-        AgeBucket=AgeBucket, CoverageBand=CoverageBand,
-        age_bucket_id=age_bucket_id, has_chronic=has_chronic,
-        coverage_band_id=coverage_band_id,
-        is_senior=is_senior, is_frail=is_frail, is_manual_review=is_manual_review,
-        rule_pack=rule_pack,
-    )
-```
+See `underwriting_audit.py` for the implementation, and `runbook.md` to reproduce it step by step with the RAI skills.
 
-**Property catalog as separately-authored spec.** Each property is a `(name, description, counterexample_builder)` tuple. The builder takes the session `s` (the fresh-model namespace) and returns the property's counterexample ICs. The counterexample for a property `P` is the *negation* of `P`: if the solver finds a feasible assignment satisfying the counterexample, `P` does not hold. Scoped properties (`chronic_under_50_implies_review` below) add a `s.model.where(...)`-bound IC to restrict the search sub-population -- the data filter goes in `where`, the decision-variable constraint in `require` (PyRel rejects decision-variable expressions inside `where`):
-
-```python
-PROPERTIES = [
-    (
-        "frail_implies_review",
-        "every frail applicant goes through manual review",
-        lambda s: [
-            s.model.require(s.is_frail == 1),
-            s.model.require(s.is_manual_review == 0),
-        ],
-    ),
-    (
-        "chronic_under_50_implies_review",
-        f"every chronic applicant under age {UNDER_50_THRESHOLD_YEARS} goes through manual review",
-        lambda s: [
-            s.model.require(s.has_chronic == 1),
-            s.model.require(s.is_manual_review == 0),
-            s.model.where(s.AgeBucket.age_years >= UNDER_50_THRESHOLD_YEARS).require(
-                s.age_bucket_id != s.AgeBucket.id
-            ),
-        ],
-    ),
-    (
-        "senior_implies_review",
-        "every senior applicant goes through manual review",
-        lambda s: [
-            s.model.require(s.is_senior == 1),
-            s.model.require(s.is_manual_review == 0),
-        ],
-    ),
-]
-```
+## Customize this template
 
-**`run_audit(...)` runs one isolated audit and returns its verdict.** Each call builds a fresh session, creates a `Problem` over that session's model, re-binds every scalar decision via `solve_for(...)`, attaches the rule pack and the property's counterexample ICs via `problem.satisfy(...)`, solves, classifies the verdict, prints the witness table (FAIL only), and returns a result dict. `populate=False` skips the first-solution write-back to the scalar relationships; every witness is read through `Variable.values(...)`, so the populated state is unused, and `populate=False` also sidesteps the latent FDError under `solution_limit`. The main code is then a list comprehension over `PROPERTIES`:
-
-```python
-def run_audit(name, description, counterexample_fn, show_formulation):
-    s = _build_session()
-    problem = Problem(s.model, Integer)
-    age_bucket_var = problem.solve_for(
-        s.age_bucket_id, type="int", name="age_bucket",
-        lower=int(age_buckets_csv["id"].min()),
-        upper=int(age_buckets_csv["id"].max()),
-        populate=False,
-    )
-    # ... five more solve_for(...) calls for the other scalar decisions ...
-
-    for rule_ic in s.rule_pack:
-        problem.satisfy(rule_ic)
-    for counterexample_ic in counterexample_fn(s):
-        problem.satisfy(counterexample_ic)
-
-    problem.solve("minizinc", time_limit_sec=60, solution_limit=MAX_WITNESSES)
-    si = problem.solve_info()
-    verdict = _classify_verdict(si)
-    # ... witness query (FAIL only) and return result dict ...
-
-results = [
-    run_audit(name, description, fn, show_formulation=(idx == 0))
-    for idx, (name, description, fn) in enumerate(PROPERTIES)
-]
-```
+### Use your own data
 
-**Multi-solution enumeration via `Variable.values(solution_index, value)`.** Inside `run_audit`, the `Variable` subconcepts returned by `solve_for(...)` expose `.values(sol_idx, val)` relationships that index per-solution outputs. Binding the value slot directly to a reference Concept's `.id` walks the chosen ID back to that row's columns in one step; binary indicator decisions read out into Integer placeholders:
-
-```python
-sol_idx = Integer.ref()
-chr_v = Integer.ref()
-sen_v = Integer.ref()
-frl_v = Integer.ref()
-mr_v = Integer.ref()
-s.model.select(
-    sol_idx.alias("solution"),
-    s.AgeBucket.age_years.alias("age_years"),
-    chr_v.alias("has_chronic"),
-    s.CoverageBand.coverage_dollars.alias("coverage_dollars"),
-    sen_v.alias("is_senior"),
-    frl_v.alias("is_frail"),
-    mr_v.alias("is_manual_review"),
-).where(
-    age_bucket_var.values(sol_idx, s.AgeBucket.id),
-    chronic_var.values(sol_idx, chr_v),
-    coverage_band_var.values(sol_idx, s.CoverageBand.id),
-    senior_var.values(sol_idx, sen_v),
-    frail_var.values(sol_idx, frl_v),
-    manual_review_var.values(sol_idx, mr_v),
-).inspect()
-```
+- Replace `data/age_buckets.csv` and `data/coverage_bands.csv` with the reference dimensions of your own applicant space, keeping the `id` plus attribute columns and dense, contiguous ids.
+- Adapt to a different regulated domain by editing the rule pack and the property catalog. The same shape carries to bank anti-money-laundering rules, healthcare prior-authorization, manufacturing segregation-of-duties, and SaaS retention — each is a set of binary indicators and a catalog of properties they must satisfy. Real rule packs in these domains often run to hundreds of rules; if a single audit's rule count exceeds PyRel's per-model `"Rules created in a loop"` threshold, decompose it into smaller property-scoped packs.
 
-## Customize this template
+### Tune parameters
+
+- Raise `MAX_WITNESSES` to surface more counterexamples per failing property. Production audits typically want 50 to 500 witnesses per failure to cover the rule pack's failure modes. Raising it past the size of the feasible set makes the solver exhaust every distinct case.
+- The solve time cap is `time_limit_sec` (default 60) in the `problem.solve("minizinc", ...)` call inside `run_audit(...)`.
+
+### Extend the model
+
+- Add a property to the catalog by appending a `(name, description, counterexample_builder)` tuple to `PROPERTIES`. The builder takes the audit session and returns the property's counterexample ICs — the logical negation of the property. For example, to audit "no senior is in the cheapest coverage band", add `("no_senior_cheap_band", "no senior is in the cheapest coverage band", lambda s: [s.model.require(s.is_senior == 1), s.model.require(s.coverage_band_id == 1)])`. `run_audit` picks it up automatically; no other code changes.
+- Add a scoped property by adding a `s.model.where(<data filter>).require(<decision constraint>)` IC alongside the unconditional counterexample ICs. `chronic_under_50_implies_review` shows the pattern: the `where` iterates `AgeBucket` rows outside the scope (a pure data filter), and the `require` body forbids the applicant decision from picking those rows. PyRel rejects decision-variable expressions inside `where`, so the decision-variable constraint must live in `require`.
+- Audit a corrected ruleset by changing the buggy rule inside `_build_session()`: the manual-review rule pins `is_manual_review == is_senior`; change the right-hand side to `is_frail`. With the fix in place, the failing verdicts in the bundled run turn to PASS and the verdict matrix reports 3 PASS, 0 FAIL.
+- Add more rule indicators by introducing additional decisions and their defining ICs inside `_build_session()`, then appending them to `rule_pack`. A logical AND over binaries is encoded with the dual of the OR pattern used for `is_frail`.
+- Switch from "any counterexample" to "worst counterexample" by adding a `problem.minimize(...)` over a violation-severity score with `solution_limit=1`, when triage capacity is limited and you want the single most severe failure first.
+
+### Extend to many applicants
+
+- Extend to a fleet of applicants by reintroducing an `Applicant` concept inside `_build_session()` and lifting each scalar decision to a property on it, then scoping every IC — including each property's counterexample ICs — to that concept. The scalar shape used here is the right default for the single-applicant search; the per-applicant shape becomes necessary once the audit binds to a real applicant table.
+
+### Scale up / productionize
 
-- **Add a property to the catalog.** Append a new `(name, description, counterexample_builder)` tuple to `PROPERTIES`. The builder takes the session `s` (a fresh-model namespace) and returns the property's counterexample ICs (the *negation* of the property). Example: to audit "no senior is in the cheapest coverage band", add `("no_senior_cheap_band", "no senior is in the cheapest coverage band", lambda s: [s.model.require(s.is_senior == 1), s.model.require(s.coverage_band_id == 1)])`. `run_audit` picks it up automatically -- no other code needs to change.
-- **Add a scoped property.** Add a `s.model.where(<data filter>).require(<decision constraint>)` IC alongside the unconditional counterexample ICs. `chronic_under_50_implies_review` shows the pattern: the where iterates AgeBucket rows with `age_years >= UNDER_50_THRESHOLD_YEARS` (pure data filter), and the require body adds `s.age_bucket_id != s.AgeBucket.id` per matching row to forbid the scalar decision from picking those rows. PyRel rejects decision-variable expressions inside `where`, so the decision-variable constraint must live in `require`.
-- **Audit a corrected ruleset** by changing the buggy rule inside `_build_session()`. `is_manual_review` is encoded as a single equality IC (`manual_review_eq_ic`) pinning `is_manual_review == is_senior`; replace the right-hand side with `is_frail` (i.e. `model.require(is_manual_review == is_frail)`). Both sides are already pinned binaries, so a single equality suffices -- no three-IC OR re-derivation is needed because the `is_frail` rule pack already encodes the OR shape. With the fix in place, the FAIL verdicts in the bundled run become PASS and the verdict matrix reports 3 PASS / 0 FAIL.
-- **Extend to a fleet of N applicants** by reintroducing an `Applicant` concept inside `_build_session()` and lifting each scalar decision to a property on it (e.g. `Applicant.age_bucket_id = model.Property(f"{Applicant} in age bucket {Integer:age_bucket_id}")`). Then scope every IC -- including each property's counterexample ICs in the catalog -- with `s.model.where(s.Applicant)` (or a tighter applicant filter). The scalar shape used here is the right default at N=1; the per-applicant shape becomes mandatory the moment you bind the audit to a real applicant table.
-- **Add more rule indicators** by introducing additional decisions and OR/AND-arithmetic ICs inside `_build_session()`, then appending the new ICs to `rule_pack`. Conjunction `y = a AND b` is encoded as `y <= a, y <= b, y >= a + b - 1` -- the dual of the OR pattern.
-- **Raise the witness count on a real ruleset** by increasing `MAX_WITNESSES`. Production audits typically want 50--500 witnesses per FAILed property to cover the rule pack's failure modes.
-- **Switch from "any witness" to "minimum-violation witness"** by adding `problem.minimize(...)` inside `run_audit(...)` over a violation severity score and `solution_limit=1`. Useful for ranking failures when triage capacity is limited.
-- **Adapt to a different regulated domain** by editing the rule pack and the property catalog. The shape carries directly to bank AML rules (`is_pep AND is_high_velocity AND is_auto_approved`), healthcare prior-auth (`requires_pa AND was_auto_paid`), manufacturing segregation-of-duties (`is_requester AND is_approver AND is_executor`), SaaS retention (`is_paying AND is_churn_risk AND is_in_low_touch_segment`). Real rule packs in these domains often contain hundreds of rules; decompose into smaller property-scoped rule packs if a single audit's count exceeds PyRel's per-Model `"Rules created in a loop"` threshold.
+- Real rule packs are large. The template rebuilds a fresh model per audit precisely so the per-model rule count stays bounded across many properties; keep that factory pattern as the pack grows, and split oversized packs into property-scoped subsets.
+- Cross-check the encoding against the source rule pack before trusting a PASS: a pass is sound only for the rules and properties as encoded, so a missing rule arm can pass silently. See the Troubleshooting notes on audit soundness.
 
 ## Troubleshooting
 
@@ -381,3 +239,23 @@ s.model.select(
 - HiGHS is not appropriate here -- the model is discrete satisfaction with categorical decisions and binary indicator equivalences, not LP/MILP.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Prescriptive reasoning](https://docs.relational.ai/) — the `Problem` API, decision variables, and constraints that model the ruleset.
+- [Constraint satisfaction and multi-solution search](https://docs.relational.ai/) — solving in enumeration mode and reading back several solutions.
+
+### Language / modeling reference
+
+- [Integrity constraints and `require`](https://docs.relational.ai/) — encoding rule bodies and property negations as ICs.
+- [PyRel v1 modeling](https://docs.relational.ai/) — concepts, relationships, and the standalone scalar-relationship shape used for the applicant decisions.
+
+### CLI / SDK guides
+
+- [RelationalAI Python SDK](https://docs.relational.ai/) — installing and configuring the `relationalai` package and connecting to Snowflake.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/warehouse_allocation/README.md b/v1/warehouse_allocation/README.md
index 0cede1de..719050a1 100644
--- a/v1/warehouse_allocation/README.md
+++ b/v1/warehouse_allocation/README.md
@@ -16,23 +16,13 @@ tags:
   - Inventory Optimization
 ---
 
-# Warehouse Allocation
-
 ## What this template is for
 
-This template chains **Graph** analysis and **Prescriptive** optimization to allocate inventory across a distribution network using centrality to prioritize critical hubs.
-
-Distribution networks have critical hub warehouses that connect many downstream sites. Identifying these hubs and ensuring they carry adequate inventory is essential for supply chain resilience.
+Distribution networks have critical hub warehouses that connect many downstream sites. When a hub runs short of inventory, the disruption cascades across every site it feeds — so identifying which warehouses are structurally critical, and making sure they carry adequate stock, is essential for supply chain resilience. Judging importance by throughput alone misses hubs that are critical because of where they sit in the network, not how much moves through them.
 
-This template chains two reasoning stages:
+This template chains graph analysis and prescriptive optimization so that the allocation plan respects network structure: the graph reasoner scores each site's importance, and the optimizer holds more inventory where it matters most.
 
-1. **Graph analysis** characterizes the route topology three ways:
-   - **Stage 1a — Eigenvector centrality** ranks sites by network influence.
-   - **Stage 1b — Weakly connected components** flags fragmentation.
-   - **Stage 1c — Bridge detection** surfaces cross-region routes whose loss would split the network.
-2. **Prescriptive optimization** allocates a limited inventory budget across sites, using the centrality scores from Stage 1a to enforce minimum stock levels at critical hubs.
-
-The key pattern: the graph reasoner writes centrality scores as properties on the Site concept, and the prescriptive reasoner references those properties directly in its constraints. No manual data transfer between stages -- the ontology carries enrichment forward.
+**The graph reasoner writes centrality scores as properties on the `Site` concept, and the prescriptive reasoner reads those same properties directly in its constraints — the shared ontology carries the enrichment forward with no manual data transfer between stages.**
 
 ## Who this is for
 
@@ -42,17 +32,19 @@ The key pattern: the graph reasoner writes centrality scores as properties on th
 
 ## What you'll build
 
-- A distribution network graph with eigenvector centrality, weakly-connected-components, and bridge-detection analyses
-- An inventory allocation model that uses centrality as a constraint input
-- A two-stage pipeline where graph results feed optimization
+- A distribution-network graph enriched with eigenvector-centrality scores, weakly-connected-component labels, and cross-region bridge routes — all written back onto the ontology as queryable `Site` and `Route` properties.
+- An inventory-allocation plan that satisfies demand and budget while holding buffer stock at critical hubs proportional to their centrality.
+- A two-stage chain where the graph reasoner's centrality output becomes a direct input to the prescriptive reasoner's constraints — no DataFrame hand-off between stages.
+
+Built using **graph analysis** (eigenvector centrality, weakly connected components, bridge detection) and **prescriptive reasoning** (linear program over continuous allocation variables).
 
 ## What's included
 
-- `warehouse_allocation.py` -- Main script with Stage 1 (graph) and Stage 2 (prescriptive)
-- `data/sites.csv` -- Warehouse and store locations with holding costs
-- `data/routes.csv` -- Distribution routes with capacity and transport cost
-- `data/demands.csv` -- Demand requirements per site
-- `pyproject.toml` -- Python package configuration with dependencies
+- **Model**: a two-stage pipeline (graph, then prescriptive) on a single shared ontology — `Site`, `Route`, and `Demand` concepts wired to the bundled CSVs, plus the centrality enrichment Stage 1 writes back.
+- **Runner**: `warehouse_allocation.py` — a single Python script that runs both stages end-to-end against a Snowflake-connected RAI account.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: a small distribution network of warehouses and stores with routes and per-site demand. See *Sample data* below.
+- **Outputs**: stdout diagnostics (centrality ranking, connected-component summary, bridge routes, solver status) plus the inventory allocation plan as queryable `Site.x_inventory`.
 
 ## Prerequisites
 
@@ -61,7 +53,8 @@ The key pattern: the graph reasoner writes centrality scores as properties on th
 - A Snowflake user with permissions to access the RAI Native App.
 
 ### Tools
-- Python >= 3.10
+- Python >= 3.10.
+- RelationalAI Python SDK (`relationalai == 1.11.0`).
 
 ## Quickstart
 
@@ -96,99 +89,93 @@ The key pattern: the graph reasoner writes centrality scores as properties on th
    python warehouse_allocation.py
    ```
 
-6. Expected output:
+6. Expected output (a few lines confirm a successful run):
    ```text
-   ==================================================
-   Stage 1: Network Centrality Ranking
-   ==================================================
-
-               site       type   region  centrality
-      Atlanta_DC  WAREHOUSE    SOUTH    0.321427
-     Chicago_Hub  WAREHOUSE  MIDWEST    0.631380
-      Dallas_Hub  WAREHOUSE    SOUTH    0.350735
-       Denver_DC  WAREHOUSE     WEST    0.212727
-      Detroit_DC  WAREHOUSE  MIDWEST    0.511638
-        LA_Store      STORE     WEST    0.057216
-     Miami_Store      STORE    SOUTH    0.139914
-       NYC_Store      STORE     EAST    0.184369
-   Phoenix_Store      STORE     WEST    0.093792
-   Seattle_Store      STORE     WEST    0.048634
-
-   ==================================================
+   Stage 1a: Eigenvector Centrality  (Chicago_Hub and Detroit_DC rank highest)
    Stage 2: Inventory Allocation
-   ==================================================
-
-   Status: OPTIMAL
-   Total holding cost: $13713.29
-
-   Allocation plan:
-               site       type  centrality   allocated  unit_cost
-      Atlanta_DC  WAREHOUSE    0.321427   70.000000        9.0
-     Chicago_Hub  WAREHOUSE    0.631380  126.275907       12.0
-      Dallas_Hub  WAREHOUSE    0.350735   70.146993       11.0
-       Denver_DC  WAREHOUSE    0.212727   42.545325       13.0
-      Detroit_DC  WAREHOUSE    0.511638  102.327586       10.0
-        LA_Store      STORE    0.057216  120.000000       18.0
-     Miami_Store      STORE    0.139914  100.000000       16.0
-       NYC_Store      STORE    0.184369  150.000000       20.0
-   Phoenix_Store      STORE    0.093792   90.000000       14.0
-   Seattle_Store      STORE    0.048634   80.000000       15.0
+     Status: OPTIMAL
+     Total holding cost: $13713.29
    ```
 
-   The graph analysis identifies Chicago_Hub (0.63) and Detroit_DC (0.51) as
-   the most central network nodes. The optimizer allocates more inventory to
-   these high-centrality warehouses -- Chicago gets 126 units and Detroit 102 --
-   while stores receive exactly their minimum demand. The centrality floor
-   constraint ensures critical hubs carry buffer stock proportional to their
-   network importance.
+   The full printout and a step-by-step walkthrough are in `runbook.md`.
 
 ## Template structure
 
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── warehouse_allocation.py
-└── data/
-    ├── sites.csv
-    ├── routes.csv
-    └── demands.csv
+warehouse_allocation/
+  warehouse_allocation.py   # Main script (Stage 1 graph + Stage 2 prescriptive)
+  data/
+    sites.csv               # Warehouse and store locations with holding costs
+    routes.csv              # Distribution routes with capacity and transport cost
+    demands.csv             # Demand requirements per site
+  README.md                 # this file
+  runbook.md                # analyst-facing paste-testable walkthrough
+  pyproject.toml            # dependencies
 ```
 
-## How it works
+**Start here**: run `python warehouse_allocation.py` for both stages end to end, or follow `runbook.md` to rebuild it step by step.
 
-This section walks through the highlights in `warehouse_allocation.py`.
+## Sample data
 
-### Stage 1: Graph centrality
+The bundled data is a small, illustrative distribution network — designed to teach the graph-then-optimize flow on a Snowflake-connected RAI account, not to match a specific operator's network.
 
-An undirected weighted graph is built from the route network, with route capacity as edge weight. Eigenvector centrality identifies sites whose connections make them structurally important:
+- **`sites.csv`** — distribution sites, each with a `region`, a `type` (`WAREHOUSE` or `STORE`), and a per-unit `holding_cost`.
+- **`routes.csv`** — directed transport links between sites, each with a `capacity` (used as the undirected graph edge weight) and a `transport_cost`.
+- **`demands.csv`** — the inventory `quantity` required at each site.
 
-```python
-graph = Graph(model, directed=False, weighted=True, node_concept=Site, aggregator="sum")
-Site.centrality = graph.eigenvector_centrality()
-```
+## Model overview
 
-### Stage 2: Inventory allocation
+One shared ontology threads both stages. Stage 1 (graph) writes centrality onto `Site`; Stage 2 (prescriptive) reads it back as a constraint input.
 
-The optimization allocates inventory across sites to minimize holding cost, subject to:
-- Total budget constraint
-- Demand satisfaction at each site
-- **Centrality-based minimum**: warehouses must hold stock proportional to their centrality score
+- **Key entities**: `Site` (warehouses and stores), `Route` (transport links), `Demand` (per-site requirements).
+- **Primary identifiers**: integer `id` on each of `Site`, `Route`, and `Demand`.
+- **Important invariants**: `holding_cost`, `capacity`, and `quantity` are non-negative; the centrality floor applies only to `Site.type == "WAREHOUSE"`; allocation variables are continuous and non-negative.
 
-```python
-problem.satisfy(model.require(
-    Site.x_inventory >= Site.centrality * MIN_CENTRALITY_FACTOR
-).where(Site.type("WAREHOUSE")))
+For the full concept and property definitions, see `warehouse_allocation.py`; `runbook.md` builds them step by step with the RAI skills.
+
+## How it works
+
+Stage 1 characterizes the route topology three ways, then Stage 2 allocates inventory using the results — all on the one shared ontology, so the graph reasoner's output is read directly by the optimizer with no data hand-off in between.
+
+**Stage 1a — Eigenvector centrality.** The script builds an undirected weighted graph from the route network, using route capacity as the edge weight, and scores each site with eigenvector centrality. This surfaces sites that are structurally important because of where they sit in the network, not merely how much throughput passes through them. The scores are written back onto `Site.centrality`.
+
+**Stage 1b — Weakly connected components.** The same graph is checked for fragmentation. Weakly connected components reveal whether every site is reachable from every other, or whether the network has split into isolated clusters that no route bridges. The script reports whether the network is unified or fragmented and lists the size and regions of each component.
+
+**Stage 1c — Bridge routes.** Cross-region routes are flagged as bridges: links whose two endpoints lie in different regions, so losing one fragments the corresponding inter-region flow.
+
+**Stage 2 — Inventory allocation.** The optimizer allocates inventory across sites to minimize total holding cost, subject to a total budget, demand satisfaction at each site, and a centrality-based floor that requires each warehouse to hold buffer stock proportional to its centrality score. That floor reads the `Site.centrality` property Stage 1 wrote, so the more structurally critical a warehouse, the more stock the plan holds there.
+
+```text
+sites/routes/demands CSVs → graph (centrality, components, bridges) → Site.centrality → optimizer (budget, demand, centrality floor) → allocation plan
 ```
 
-The `Site.centrality` property was populated by Stage 1 and is referenced directly here.
+See `warehouse_allocation.py` for the implementation, and `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Customize this template
 
-- **Add more sites and routes**: Extend the CSVs. The graph and optimization automatically adapt to new topology.
-- **Change the centrality algorithm**: Replace `eigenvector_centrality()` with `pagerank()` or `betweenness_centrality()` for different notions of importance.
-- **Add a third stage**: Use rule-based reasoning to flag sites that are both high-centrality and under-stocked, feeding into an alerting workflow.
-- **Scenario analysis**: Loop over different budget levels or centrality thresholds to see how allocation shifts.
+Focus on the first changes most users will make.
+
+### Use your own data
+
+- Replace the CSVs in `data/` with your own; keep the column names shown in *Sample data* above (`sites.csv`, `routes.csv`, `demands.csv`). The graph and optimization adapt automatically to new topology.
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)` calls.
+- Confirm `site_id` values in `routes.csv` and `demands.csv` match the `id` column in `sites.csv` — a mismatched key drops the route or demand silently.
+
+### Tune parameters
+
+- **Budget** — `TOTAL_BUDGET` (default `2000`) caps total units allocated across all sites.
+- **Centrality floor** — `MIN_CENTRALITY_FACTOR` (default `200`) sets how much buffer stock a warehouse must hold per unit of centrality.
+
+### Extend the model
+
+- **Change the centrality algorithm** — replace `eigenvector_centrality()` with `pagerank()` or `betweenness_centrality()` for a different notion of importance; Stage 2 reads whatever `Site.centrality` holds.
+- **Add a third stage** — use rule-based reasoning to flag sites that are both high-centrality and under-stocked, feeding into an alerting workflow.
+- **Add a constraint or metric** — e.g., a per-region minimum-coverage floor, or fold `transport_cost` into the objective.
+
+### Scale up / productionize
+
+- Replace the `data/` CSV bundle with CDC ingestion from your upstream inventory and routing systems.
+- The bundled network is small; the chain scales to whatever fits the prescriptive engine's solve budget. Pin dependencies via `pyproject.toml` for reproducible runs.
 
 ## Troubleshooting
 
@@ -203,3 +190,19 @@ Make sure you activated the virtual environment and ran `python -m pip install .
 
 Run `rai init` to configure your Snowflake connection. Verify that the RAI Native App is installed and your user has the required permissions.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Multi-reasoner workflows](https://docs.relational.ai/) — chaining reasoners through a shared ontology, as this template does with graph then prescriptive.
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)` / `model.select(...)` / `aggs`.
+
+### Reasoner reference
+
+- [Graph reasoner](https://docs.relational.ai/) — building graphs from ontology patterns, eigenvector centrality, weakly connected components.
+- [Prescriptive reasoner](https://docs.relational.ai/) — `Problem` API, decision variables, constraints, objective.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/water_allocation/README.md b/v1/water_allocation/README.md
index 2c3c68f2..422be002 100644
--- a/v1/water_allocation/README.md
+++ b/v1/water_allocation/README.md
@@ -13,17 +13,13 @@ tags:
   - Ipopt
 ---
 
-# Water Allocation
-
 ## What this template is for
 
-This template uses **Prescriptive** reasoning (nonlinear optimization) to minimize the cost of distributing water from sources to users with nonlinear transmission losses.
-
-Water utilities must distribute water from multiple sources (reservoirs, groundwater) to multiple user groups (municipal, industrial, agricultural). Each source has a limited capacity and a different extraction cost. Each connection in the distribution network has a maximum flow rate and a transmission loss rate that reduces the effective amount delivered.
+Water utilities must distribute water from multiple sources — reservoirs, groundwater — to multiple user groups such as municipal, industrial, and agricultural demand. Each source has a limited capacity and a different extraction cost, and every connection in the distribution network has a maximum flow rate and a transmission loss that reduces the amount actually delivered. Losses grow as a pipe runs closer to capacity, so a plan that ignores that effect over-promises delivery on its busiest routes.
 
-This template uses prescriptive reasoning to find the minimum-cost allocation that satisfies every user's demand. It models the distribution network as a flow problem with source capacity constraints, demand satisfaction constraints with nonlinear transmission losses, and connection flow limits.
+The goal is the minimum-cost allocation that still meets every user's demand once realistic, utilization-dependent losses are accounted for.
 
-The key feature is nonlinear loss modeling: transmission losses increase with utilization (effective delivery = flow * (1 - loss_rate * flow / max_flow)), creating a quadratic constraint that requires the Ipopt nonlinear solver. This is more realistic than constant-rate losses -- at low flow the loss is small, but at capacity the full loss rate applies.
+**A prescriptive reasoner finds the least-cost allocation that meets every demand while honoring source capacities and utilization-dependent transmission losses.**
 
 ## Who this is for
 
@@ -33,18 +29,19 @@ The key feature is nonlinear loss modeling: transmission losses increase with ut
 
 ## What you'll build
 
-- A nonlinear optimization model for minimum-cost water distribution solved with Ipopt
-- Source capacity constraints limiting total outflow per source
-- Demand constraints with nonlinear (utilization-dependent) transmission losses
-- Flow upper bounds on individual connections
+- A minimum-cost water-distribution plan — a flow allocation across every source-to-user connection — solved with the Ipopt nonlinear solver.
+- Source-capacity constraints limiting total outflow per source, and per-connection flow upper bounds.
+- Demand constraints that model utilization-dependent transmission losses, so delivered volume reflects how hard each route is being pushed.
+
+Built using **prescriptive reasoning** (nonlinear program over continuous flow variables, with a quadratic loss term).
 
 ## What's included
 
-- `water_allocation.py` -- Main script defining the network model, constraints, and solver call
-- `data/sources.csv` -- Water sources with capacity and cost per unit
-- `data/users.csv` -- User groups with demand and priority
-- `data/connections.csv` -- Network connections with max flow and loss rate
-- `pyproject.toml` -- Python package configuration
+- **Model**: a single-stage nonlinear optimization on a shared ontology — `Source`, `User`, and `Connection` concepts wired to the bundled CSVs.
+- **Runner**: `water_allocation.py` — a single Python script that builds the model, constraints, and objective and calls the solver against a Snowflake-connected RAI account.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: a small water-distribution network of sources, user groups, and the connections between them. See *Sample data* below.
+- **Outputs**: solver status, total cost, and the per-connection flow allocations.
 
 ## Prerequisites
 
@@ -53,7 +50,8 @@ The key feature is nonlinear loss modeling: transmission losses increase with ut
 - A Snowflake user with permissions to access the RAI Native App.
 
 ### Tools
-- Python >= 3.10
+- Python >= 3.10.
+- RelationalAI Python SDK (`relationalai == 1.0.14`).
 
 ## Quickstart
 
@@ -88,103 +86,94 @@ The key feature is nonlinear loss modeling: transmission losses increase with ut
    python water_allocation.py
    ```
 
-6. Expected output:
+6. Expected output (a few lines confirm a successful run):
    ```text
    Status: LOCALLY_SOLVED
    Total cost: $853.39
 
    Flow allocations:
-     Reservoir_A  Agricultural  352.77
-     Reservoir_A    Industrial  247.23
      Reservoir_A     Municipal  400.00
      Reservoir_B  Agricultural  182.06
-     Reservoir_B    Industrial  177.93
-     Reservoir_B     Municipal  228.99
+     ...
    ```
 
-   Groundwater is not used — the solver routes all flow through the cheaper
-   reservoirs. Reservoir A supplies its full municipal capacity (400 units) while
-   splitting the remainder between agricultural and industrial users. Reservoir B
-   covers the remaining demand.
+   The full printout and a step-by-step walkthrough are in `runbook.md`.
 
 ## Template structure
+
 ```text
-.
-├── README.md
-├── pyproject.toml
-├── water_allocation.py
-└── data/
-    ├── connections.csv
-    ├── sources.csv
-    └── users.csv
+water_allocation/
+  water_allocation.py   # Main script (network model, constraints, solver call)
+  data/
+    sources.csv         # Water sources with capacity and cost per unit
+    users.csv           # User groups with demand and priority
+    connections.csv     # Network connections with max flow and loss rate
+  README.md             # this file
+  runbook.md            # analyst-facing paste-testable walkthrough
+  pyproject.toml        # dependencies
 ```
 
-## How it works
+**Start here**: run `python water_allocation.py` for the full solve end to end, or follow `runbook.md` to rebuild it step by step.
 
-### 1. Define sources, users, and connections
+## Sample data
 
-The model loads three concepts from CSV. Sources have capacity and cost. Users have demand and priority. Connections link sources to users with max flow and loss rate:
+The bundled data is a small, illustrative water-distribution network — designed to teach the nonlinear flow formulation on a Snowflake-connected RAI account, not to match a specific utility's system.
 
-```python
-Source = Concept("Source", identify_by={"id": Integer})
-Source.capacity = Property(f"{Source} has {Float:capacity}")
-Source.cost_per_unit = Property(f"{Source} has {Float:cost_per_unit}")
+- **`sources.csv`** — water sources, each with a `capacity` and a `cost_per_unit`.
+- **`users.csv`** — user groups, each with a `demand` and a `priority`.
+- **`connections.csv`** — source-to-user links, each with a `max_flow` and a `loss_rate` (the fraction lost at full utilization).
 
-User = Concept("User", identify_by={"id": Integer})
-User.demand = Property(f"{User} has {Float:demand}")
+## Model overview
 
-Connection = Concept("Connection")
-Connection.source = Property(f"{Connection} from {Source}", short_name="source")
-Connection.user = Property(f"{Connection} to {User}", short_name="user")
-Connection.max_flow = Property(f"{Connection} has {Float:max_flow}")
-Connection.loss_rate = Property(f"{Connection} has {Float:loss_rate}")
-```
+A single shared ontology holds the network. The `Connection` concept carries the flow decision variable the solver assigns.
 
-### 2. Define the flow variable
+- **Key entities**: `Source` (reservoirs, groundwater), `User` (demand groups), `Connection` (source-to-user links).
+- **Primary identifiers**: integer `id` on `Source` and `User`; `Connection` is identified by its `source` and `user` endpoints.
+- **Important invariants**: `capacity`, `demand`, `max_flow`, and `cost_per_unit` are non-negative; `loss_rate` is a fraction in `[0, 1]`; each connection's flow is continuous and bounded between 0 and its `max_flow`.
 
-Each connection gets a continuous flow variable bounded between zero and its maximum flow:
+For the full concept and property definitions, see `water_allocation.py`; `runbook.md` builds them step by step with the RAI skills.
 
-```python
-problem.solve_for(
-    Connection.x_flow,
-    name=["flow", Connection.source.name, Connection.user.name],
-    lower=0,
-    upper=Connection.max_flow
-)
-```
+## How it works
 
-### 3. Add capacity and demand constraints
+This is a network-flow problem: source-capacity limits, per-connection flow bounds, and demand constraints whose nonlinear loss term makes it quadratic, solved with the Ipopt nonlinear solver.
 
-Source capacity limits total outflow. Demand constraints use nonlinear losses -- loss increases with utilization, so effective delivery per connection is `flow * (1 - loss_rate * flow / max_flow)`:
+The script loads three concepts from CSV — sources with a capacity and an extraction cost, users with a demand, and connections that link a source to a user with a maximum flow and a loss rate. Each connection then gets a continuous flow decision variable, bounded between zero and its maximum flow, that the solver assigns.
 
-```python
-outflow = sum(ConnectionRef.x_flow).where(ConnectionRef.source == Source).per(Source)
-problem.satisfy(model.require(outflow <= Source.capacity))
+Two families of constraints shape the plan. A source-capacity constraint holds the total outflow from each source within its capacity. A demand constraint requires each user's effective inflow — the flow delivered after losses — to meet its demand. The loss term is where the nonlinearity enters: the fraction lost on a connection grows with how hard the route is being pushed, so effective delivery falls as a connection approaches its maximum flow. That utilization-dependent loss makes the demand constraint quadratic, which is why the model needs the Ipopt nonlinear solver rather than a linear one. The objective minimizes total extraction cost across all flows, so the solver leans on cheaper sources and lightly loaded routes.
 
-effective_inflow = sum(
-    ConnectionRef.x_flow * (1 - ConnectionRef.loss_rate * ConnectionRef.x_flow / ConnectionRef.max_flow)
-).where(ConnectionRef.user == User).per(User)
-problem.satisfy(model.require(effective_inflow >= User.demand))
+```text
+sources/users/connections CSVs → per-connection flow variables → capacity + loss-adjusted demand constraints → minimize cost → allocation plan
 ```
 
-This quadratic constraint makes the problem nonlinear, requiring the Ipopt solver.
+See `water_allocation.py` for the implementation, and `runbook.md` to reproduce it step by step with the RAI skills.
 
-### 4. Minimize cost
+## Customize this template
 
-The objective minimizes total extraction cost across all active flows:
+Focus on the first changes most users will make.
 
-```python
-total_cost = sum(Connection.x_flow * Connection.source.cost_per_unit)
-problem.minimize(total_cost)
-```
+### Use your own data
 
-## Customize this template
+- Replace the CSVs in `data/` with your own; keep the column names shown in *Sample data* above (`sources.csv`, `users.csv`, `connections.csv`).
+- For Snowflake-backed runs, swap the `read_csv(...)` calls for `model.data(snowflake_table)` calls.
+- Confirm `source_id` and `user_id` in `connections.csv` match the `id` columns in `sources.csv` and `users.csv` — a mismatched key silently drops the connection.
+
+### Tune parameters
+
+- **Source capacity and cost** — edit `capacity` and `cost_per_unit` in `sources.csv` to change which sources the solver prefers.
+- **Loss rate** — `loss_rate` in `connections.csv` controls how steeply delivery falls as a route approaches capacity.
+
+### Extend the model
 
 - **Add seasonal variation** by introducing time periods with different source capacities and user demands.
-- **Include priority-based allocation** using the priority field to penalize unmet demand differently for each user group.
+- **Include priority-based allocation** using the `priority` field to penalize unmet demand differently for each user group.
 - **Add minimum flow requirements** on certain connections to model contractual obligations.
 - **Extend the network** with intermediate nodes (pumping stations, treatment plants) that add processing costs or additional capacity constraints.
 
+### Scale up / productionize
+
+- Replace the `data/` CSV bundle with CDC ingestion from your upstream source and demand systems.
+- The bundled network is small; the formulation scales to whatever the Ipopt solver can handle in your solve budget. Pin dependencies via `pyproject.toml` for reproducible runs.
+
 ## Troubleshooting
 
 <details>
@@ -210,3 +199,19 @@ Make sure you activated the virtual environment and ran `python -m pip install .
 
 Run `rai init` to configure your Snowflake connection. Verify that your account has the RAI Native App installed and that your user has the required permissions.
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [PyRel v1 query language](https://docs.relational.ai/) — `model.where(...)` / `model.select(...)` / `sum`.
+- [Ontology modeling](https://docs.relational.ai/) — concepts, properties, and relationships that back this network model.
+
+### Reasoner reference
+
+- [Prescriptive reasoner](https://docs.relational.ai/) — `Problem` API, decision variables, constraints, objective.
+- [Nonlinear solving with Ipopt](https://docs.relational.ai/) — when a quadratic or nonlinear constraint requires the nonlinear solver.
+
+## Support
+
+- File issues at the RelationalAI templates repository.
diff --git a/v1/wildlife-conservation-network/README.md b/v1/wildlife-conservation-network/README.md
index 1822a9f7..d8ae7167 100644
--- a/v1/wildlife-conservation-network/README.md
+++ b/v1/wildlife-conservation-network/README.md
@@ -13,12 +13,11 @@ tags:
 
 ## What this template is for
 
-Wildlife conservation requires coordination across many organizations—NGOs, research stations, wildlife reserves, veterinary services, and community programs. This template demonstrates how to use graph analytics to understand conservation networks:
+Wildlife conservation requires coordination across many organizations — non-governmental organizations (NGOs), research stations, wildlife reserves, veterinary services, and community programs. Coordination that already works well is hard to see from an org chart, and the organizations best placed to broker resources across groups are rarely the obvious ones. Analyzing the network of partnerships between these organizations makes both visible.
 
-- **Louvain algorithm** — a community detection method that finds clusters of densely connected nodes in a network — to identify groups of conservation organizations that work closely together
-- **Degree centrality** — a connectivity measure that identifies the most influential organizations within each community
+This template discovers natural collaboration clusters — based on geography, species focus, or organizational mission — and identifies the hub organizations within each cluster that are well-positioned to lead coordination and resource-sharing efforts.
 
-By analyzing a network of conservation partnerships, this template helps you discover natural collaboration clusters based on geography, species focus, or organizational mission. These communities reveal which organizations form tight-knit working groups, where coordination is already strong, and where opportunities exist for better cross-community collaboration. Degree centrality then identifies the hub organizations within each cluster that are well-positioned to lead coordination efforts and resource sharing initiatives.
+**A graph reasoner turns a raw partnership network into a coordination map — the collaboration clusters that already exist and the hub organizations best placed to broker resources across them.**
 
 ## Who this is for
 - **Beginners** who want to learn community detection with a real-world use case
@@ -28,28 +27,34 @@ By analyzing a network of conservation partnerships, this template helps you dis
 
 ## What you'll build
 
-- Load a wildlife conservation network with 12 organizations and 19 undirected partnerships from CSV files
-- Use RelationalAI's Graph API to model the conservation partnership network
-- Apply the Louvain algorithm to detect communities (collaboration clusters)
-- Calculate degree centrality to identify which organizations serve as hubs within each community
-- Analyze community characteristics (region, species focus, organization types, hub organizations)
-- Generate insights on intra-community collaboration, hub organization leadership potential, and cross-community coordination opportunities
+- A conservation partnership network modeled with RelationalAI's Graph API, built from the bundled organization and partnership CSVs.
+- Community assignments from the Louvain algorithm — the collaboration clusters within the network — written onto each `Organization`.
+- A degree-centrality ranking that surfaces the hub organization inside each cluster, the one best placed to lead coordination.
+- Community-level insight: region and species-focus makeup, hub identity, and cross-community connectors, available both as a CLI report and an interactive Streamlit visualization.
 
-This template uses **RelationalAI's graph modeling** capabilities with the Graph class to represent the network, the built-in Louvain algorithm for community detection, and degree centrality analysis to identify influential organizations within each cluster.
+Built using **graph analysis** (Louvain community detection and degree centrality on an undirected, unweighted partnership graph).
 
 ## What's included
 
-- **Shared model setup**: `model_setup.py` - Common model configuration and graph creation (used by both scripts)
-- **Command-line script**: `wildlife_conservation_network.py` - CLI analysis script with detailed output
-- **Interactive app**: `app.py` - Streamlit web application with visualizations and interactive analysis
-- **Data**: `data/organizations.csv` and `data/partnerships.csv`
+- **Model**: a single shared ontology — `Organization` nodes and `Partnership` edges — plus the Louvain community and degree-centrality enrichment the graph reasoner writes back. Defined once in `model_setup.py` and reused by both runners.
+- **Runner**: `wildlife_conservation_network.py` (CLI report) and `app.py` (interactive Streamlit visualization), both against a Snowflake-connected RAI account.
+- **Runbook**: `runbook.md` — a paste-testable walkthrough that reproduces the template step by step with the RAI skills; as important a reference as the script itself.
+- **Sample data**: a small network of conservation organizations and the partnerships between them. See *Sample data* below.
+- **Outputs**: a per-organization table of community assignments and metrics, a per-community breakdown, and (in the app) an interactive network graph.
 
 ## Prerequisites
 
-- Python >= 3.10
+### Access
+
 - A Snowflake account that has the RAI Native App installed.
 - A Snowflake user with permissions to access the RAI Native App.
 
+### Tools
+
+- Python >= 3.10.
+- RelationalAI Python SDK (`relationalai == 1.11.0`).
+- Streamlit (installed via the optional `.[visualization]` extra) for the interactive app.
+
 ## Quickstart
 
 Follow these steps to run the template with the included sample data.
@@ -113,145 +118,97 @@ You can customize the data and model as needed after you have it running end-to-
    - Cross-community connector identification
    - Summary statistics and key metrics
 
-## How it works
-
-The template follows this flow:
-
-```text
-CSV files → model_setup.create_model() → Apply Louvain → Analyze communities → Display results
-```
+6. Expected output (a few lines confirm a successful run):
 
-### 1. Shared Model Setup
+   ```text
+   Louvain community detection -> 3 collaboration clusters (5 / 4 / 3 organizations)
+   Global hub: Serengeti Wildlife Trust -- 5 partnerships, degree centrality 0.4545
+   ```
 
-Both the CLI script and Streamlit app use the same model setup from `model_setup.py`:
+   The community ID numbers are arbitrary labels; what matters is which
+   organizations group together. The full report and a step-by-step walkthrough
+   are in `runbook.md`.
 
-```python
-from model_setup import create_model
+## Template structure
 
-# Create the model, concepts, relationships, and graph (all in one call)
-model, graph, Organization = create_model()
+```text
+wildlife-conservation-network/
+  model_setup.py                     # Shared model, concepts, and graph (used by both runners)
+  wildlife_conservation_network.py   # CLI analysis script with detailed output
+  app.py                             # Optional Streamlit visualization app
+  data/
+    organizations.csv                # Conservation organizations (type, region, focus species)
+    partnerships.csv                 # Undirected collaboration partnerships between organizations
+  README.md                          # this file
+  runbook.md                         # analyst-facing paste-testable walkthrough
+  pyproject.toml                     # dependencies
 ```
 
-The `create_model()` function handles:
-- Creating the RelationalAI model container
-- Defining the `Organization` concept with all properties
-- Loading organizations from CSV
-- Defining the `Partnership` concept for edges
-- Loading partnerships from CSV
-- Creating the undirected, unweighted graph
-- Returning all components for use in analysis
+**Start here**: run `python wildlife_conservation_network.py` for the full CLI analysis end to end, or follow `runbook.md` to rebuild it step by step. The Streamlit app is an optional visualization layer over the same model.
 
-### 2. Apply Community Detection and Centrality Analysis
+## Sample data
 
-Use the built-in Louvain algorithm to detect communities and calculate centrality metrics:
+The bundled data is a small, illustrative conservation network — designed to teach community detection on a Snowflake-connected RAI account, not to match a specific program's partnerships.
 
-```python
-# Apply Louvain algorithm for community detection
-louvain_communities = graph.louvain()
+- **`organizations.csv`** — 12 conservation organizations, each with a `type` (NGO, research station, reserve, and so on), a `region`, and a `focus_species`.
+- **`partnerships.csv`** — 19 collaboration partnerships, one row each, given as a pair of organization ids. Partnerships are undirected, so ordering does not matter.
 
-# Calculate degree centrality to identify hub organizations within communities
-degree_centrality = graph.degree_centrality()
+## Model overview
 
-# Also calculate degree (raw partnership count) for additional analysis
-degree = graph.degree()
-```
+A single shared ontology (defined in `model_setup.py`) backs both runners. The graph reasoner writes community and centrality results back onto the network.
 
-The Louvain algorithm works by:
-1. Optimizing modularity (a measure of how well the network divides into communities)
-2. Iteratively grouping nodes to maximize within-community connections
-3. Minimizing between-community connections
-4. Returning a community ID for each node
-
-Degree centrality then normalizes the partnership counts to a 0-1 scale, making it easier to compare organizations across different community sizes. Organizations with higher centrality are well-positioned hubs that could lead coordination efforts within their community.
-
-### 3. Query and Analyze Communities
-
-Query the graph to retrieve community assignments and metrics:
-
-```python
-from relationalai.semantics import where, Integer, Float
-
-# Create variable references
-org = graph.Node.ref("org")
-community_id = Integer.ref("community_id")
-centr_score = Float.ref("centr_score")
-partner_count = Integer.ref("partner_count")
-
-# Query the graph
-results = where(
-    louvain_communities(org, community_id),
-    degree_centrality(org, centr_score),
-    degree(org, partner_count)
-).select(
-    org.id,
-    org.name,
-    org.type,
-    org.region,
-    org.focus_species,
-    community_id.alias("community"),
-    centr_score.alias("degree_centrality"),
-    partner_count.alias("partnerships")
-).to_df()
-
-# Sort by community, then by centrality within each community
-results = results.sort_values(["community", "degree_centrality"], ascending=[True, False])
-```
+- **Key entities**: `Organization` (the network's nodes), `Partnership` (the collaboration edges).
+- **Primary identifiers**: integer `id` on `Organization`; `Partnership` is identified by its two endpoint organizations.
+- **Important invariants**: every `Partnership` endpoint must reference a valid `Organization` id; the graph is undirected and unweighted, so a partnership counts once regardless of row order.
 
-### 4. CLI Script Analysis
+For the full concept and property definitions, see `model_setup.py`; `runbook.md` builds them step by step with the RAI skills.
 
-The `wildlife_conservation_network.py` script displays:
-- A table of all organizations with their community assignments and metrics
-- Detailed breakdown of each detected community (size, region, species focus, hub organization)
-- Network-wide summary statistics
-- Actionable recommendations for conservation coordination
+## How it works
 
-### 5. Interactive Streamlit App
+```text
+CSV files → model_setup.create_model() → apply Louvain + degree centrality → analyze communities → display results
+```
 
-The included `app.py` provides an interactive web interface using the same shared model:
+Both runners share one model. `model_setup.py` builds the RelationalAI model container, defines the `Organization` concept and loads it from CSV, defines the `Partnership` edges and loads them, and constructs the undirected, unweighted graph — returning everything the analysis needs in a single call. This keeps the CLI script and the Streamlit app perfectly in sync, since neither redefines the model.
 
-```python
-import streamlit as st
-from model_setup import create_model
+The graph reasoner then runs two algorithms over that graph. Louvain community detection partitions the network into collaboration clusters by optimizing modularity — iteratively grouping organizations to maximize connections within a cluster and minimize connections between clusters — and writes a community label onto each organization. Degree centrality normalizes each organization's partnership count to a 0-to-1 scale, which makes hubs comparable across clusters of different sizes; the highest-centrality organization inside a community is the one best placed to broker coordination there.
 
-# Load the same model and query results
-model, graph, Organization = create_model()
-results = get_results(model, graph, Organization)
-```
+Reading those results back is a query joining the community label, centrality score, and raw partnership count per organization. The CLI script renders a per-organization table, a per-community breakdown (size, region, species focus, hub), and network-wide summary statistics. The optional Streamlit app is a visualization layer over the same query: an interactive network graph colored by community, expandable per-cluster detail, and cross-community connector analysis.
 
-The Streamlit app features:
-- **Interactive network graph**: Nodes colored by community, sized by partnerships
-- **Community breakdown**: Expandable sections with detailed metrics for each cluster
-- **Strategic analysis**: Cross-community connectors, geographic distribution, species focus
-- **Summary statistics**: Sidebar with key network metrics and hub organizations
+See `model_setup.py` and `wildlife_conservation_network.py` for the implementation, and `runbook.md` to reproduce it step by step with the RAI skills.
 
 ## Customize this template
 
-**Use your own data:**
+Focus on the first changes most users will make.
+
+### Use your own data
 
-- Replace the CSV files in the `data/` directory with your own conservation network, keeping the same column names (or update the logic in wildlife_conservation_network.py).
-- Make sure that organizations in **partnerships.csv** only reference valid organization IDs.
-- You can add additional properties to organizations (budget, staff size, years active) by adding columns to the CSV and corresponding properties to the model.
+- Replace the CSV files in `data/` with your own conservation network, keeping the same column names (or update the logic in `model_setup.py`).
+- Make sure organizations in `partnerships.csv` only reference valid organization ids from `organizations.csv`.
+- For Snowflake-backed runs, swap the `pd.read_csv(...)` calls for `data(snowflake_table)` calls in `model_setup.py`.
 
-**Extend the model:**
+### Tune parameters
 
-- **Add weighted partnerships**: Weight edges by collaboration intensity (number of joint projects, funding shared, frequency of interaction). Update `weighted=True` in the Graph definition and add weight values to edges.
+- The graph is built undirected and unweighted in `model_setup.py`. Adding edge weights (see *Extend the model*) is the main lever on how the community detection partitions the network.
 
-- **Try different community detection algorithms**: RelationalAI supports multiple algorithms:
+### Extend the model
 
-  - `graph.label_propagation()` - Faster but less accurate for small networks
-  - `graph.weakly_connected_component()` - Finds completely disconnected groups
-  - Experiment to see which algorithm best reveals your network's structure
+- **Add organization properties** — budget, staff size, years active — by adding columns to `organizations.csv` and corresponding properties in `model_setup.py`.
+- **Add weighted partnerships** — weight edges by collaboration intensity (joint projects, shared funding, interaction frequency). Set `weighted=True` in the Graph definition and add weight values to edges.
+- **Try different community-detection algorithms** — `graph.label_propagation()` (faster, less accurate on small networks) or `graph.weakly_connected_component()` (completely disconnected groups); experiment to see which best reveals your network's structure.
+- **Add temporal analysis** — include partnership start dates to study how communities evolve over time.
 
-- **Add temporal analysis**: Include partnership start dates to analyze how communities evolve over time.
+### Scale up / productionize
 
-- **Calculate modularity**: Measure how well the detected communities separate from each other (higher modularity = better community structure).
+- Replace the `data/` CSV bundle with ingestion from your partnership system of record.
+- The bundled network is small; Louvain and degree centrality scale to much larger graphs. Pin dependencies via `pyproject.toml` for reproducible runs.
 
 ## Troubleshooting
 
 <details>
   <summary>Why does authentication/configuration fail?</summary>
 
-- Run `rai init` to create/update `raiconfig.toml`.
+- Run `rai init` to create/update `raiconfig.yaml`.
 - If you have multiple profiles, set `RAI_PROFILE` or switch profiles in your config.
 
 </details>
@@ -259,7 +216,7 @@ The Streamlit app features:
 <details>
   <summary>Why does the script fail to connect to the RAI Native App?</summary>
 
-- Verify the Snowflake account/role/warehouse and `rai_app_name` are correct in `raiconfig.toml`.
+- Verify the Snowflake account/role/warehouse and `rai_app_name` are correct in `raiconfig.yaml`.
 - Ensure the RAI Native App is installed and you have access.
 
 </details>
@@ -281,3 +238,18 @@ The Streamlit app features:
 - The Louvain algorithm can have some randomness, so community assignments might vary slightly between runs, but the overall structure should be consistent.
 
 </details>
+
+## Learn more
+
+### Core concepts
+
+- [Graph modeling](https://docs.relational.ai/) — building a graph from ontology concepts and relationships, as this template does with `Organization` and `Partnership`.
+- [PyRel v1 query language](https://docs.relational.ai/) — `where(...)` / `select(...)` to read algorithm results back out.
+
+### Reasoner reference
+
+- [Graph reasoner](https://docs.relational.ai/) — Louvain community detection, degree centrality, and other built-in graph algorithms.
+
+## Support
+
+- File issues at the RelationalAI templates repository.