vortexa-claude-skills 1.0.0 → 1.1.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [1.1.0-beta.1] - 2026-03-12
+
+### Beta Release
+
+**New: Workflow Analytics Engine**
+- 15 curated analytical workflows accessible via `/vortexa:workflows`
+- Covers net flows, top ports, top movers, floating storage, seasonal patterns, fleet distribution, ballast speeds, idle vessel analysis, post-ballast distribution, speed-based diversions, and cargo-on-water
+- Each workflow produces publication-ready charts and exportable data
+
+**New: Flagship Custom Analytics Builder**
+- `/vortexa:custom` rebuilt as a 3-stage analytics builder (discuss, plan, execute)
+- Adaptive questioning to identify exactly what you need
+- Parallel data fetching for complex multi-endpoint queries
+- Default output as Jupyter notebooks
+
+**New: Intelligent Skill Routing**
+- Ask any commodity/energy question in natural language -- Claude automatically routes to the right skill
+- No need to remember slash command names
+
+**Improved: Setup & Installation**
+- Setup validates Python 3.10+ and vortexasdk before installing
+- Clear guidance when prerequisites are missing
+- Package published as vortexa-claude-skills on npm
+
+**Improved: Interaction Speed**
+- Faster workflow menu navigation
+- Streamlined category browsing
+
 ## [1.0.0] - 2026-02-27
 
 ### Initial Release
@@ -22,7 +50,7 @@
 - Endpoint template pattern for adding new API endpoints
 
 **Distribution:**
-- One-command install: `npx @vortexa/claude-skills setup`
+- One-command install: `npx vortexa-claude-skills setup`
 - Per-directory init: `/vortexa:init` for environment setup
 - Cross-platform: Mac, Windows, Linux
-- Automatic update: `npx @vortexa/claude-skills update`
+- Automatic update: `npx vortexa-claude-skills update`

package/README.md

@@ -0,0 +1,65 @@
+# vortexa-claude-skills
+
+Natural language analytics for Vortexa's commodity and energy data -- powered by Claude Code.
+
+## What it does
+
+A set of Claude Code skills that let you query Vortexa's API using plain English. Ask about cargo flows, vessel voyages, seasonal patterns, fleet analytics, and more -- get structured data and publication-ready charts without writing code. Includes 9 interactive skills and 15 curated analytical workflows covering flows, freight, on-water, and LNG markets.
+
+## Prerequisites
+
+- [Claude Code](https://claude.ai/code)
+- Node.js 18+
+- Python 3.10+
+- `vortexasdk` Python package (`pip install vortexasdk`)
+- Vortexa API key
+
+## Install
+
+```
+npx vortexa-claude-skills setup
+```
+
+This installs skill files to `~/.claude/` and registers them with Claude Code.
+
+## Quick Start
+
+1. Open Claude Code in any project directory
+2. Run `/vortexa:init` to set up your environment (API key, etc.)
+3. Start asking questions: "How much crude oil was exported from Saudi Arabia last month?"
+
+## Available Skills
+
+| Skill | Description |
+|---|---|
+| `/vortexa:init` | Set up your Vortexa analytics environment |
+| `/vortexa:cargo-flows` | Query cargo flows, exports, and imports |
+| `/vortexa:breakdown` | Break down flows by origin, destination, product, or vessel class |
+| `/vortexa:voyages` | Query vessel voyages and fleet movements |
+| `/vortexa:custom` | Flagship analytics builder -- discuss, plan, and build any analysis |
+| `/vortexa:explain` | Get plain-English explanations of Vortexa data and methodology |
+| `/vortexa:seasonal` | Multi-year seasonal pattern analysis with min/max/avg bands |
+| `/vortexa:compare` | Period-over-period or region-over-region comparisons |
+| `/vortexa:workflows` | Access 15 curated analytical workflows |
+
+## Workflows
+
+Run `/vortexa:workflows` to browse 15 curated analytical workflows organized by category:
+
+- **Flows** -- Net flows, top ports, top movers
+- **On Water** -- Floating storage, cargo on water
+- **Voyages** -- Fleet distribution, ballast speeds, idle vessels, post-ballast distribution, diversions
+- **Freight Pricing** -- Regional freight rates, pricing voyages
+- **LNG** -- Vessel availability, importers and exporters
+
+Each workflow produces publication-ready charts and exportable data.
+
+## Update
+
+```
+npx vortexa-claude-skills update
+```
+
+## License
+
+UNLICENSED -- Internal use only.

package/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0-beta.2

package/bin/setup.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
+const { execSync } = require('child_process');
 
 const packageDir = path.resolve(__dirname, '..');
 const version = fs.readFileSync(path.join(packageDir, 'VERSION'), 'utf8').trim();
@@ -159,6 +160,62 @@ function countFilesByType(files) {
   return counts;
 }
 
+function checkPrerequisites() {
+  const issues = [];
+
+  // 1. Check Python 3.10+
+  let python_version;
+  try {
+    const raw = execSync('python3 --version', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const match = raw.match(/Python\s+(\d+)\.(\d+)\.(\d+)/);
+    if (!match) {
+      issues.push('Could not parse Python version. Install Python 3.10+ from https://python.org/downloads/');
+    } else {
+      const major = parseInt(match[1], 10);
+      const minor = parseInt(match[2], 10);
+      if (major < 3 || (major === 3 && minor < 10)) {
+        issues.push(`Python ${match[1]}.${match[2]}.${match[3]} found, but 3.10+ is required. Install from https://python.org/downloads/`);
+      } else {
+        python_version = `${match[1]}.${match[2]}.${match[3]}`;
+      }
+    }
+  } catch (err) {
+    issues.push('python3 not found. Install Python 3.10+ from https://python.org/downloads/');
+  }
+
+  // 2. Check vortexasdk
+  let sdk_version;
+  try {
+    sdk_version = execSync('python3 -c "import vortexasdk; print(vortexasdk.__version__)"', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch (err) {
+    issues.push('vortexasdk not installed. Run: pip install vortexasdk');
+  }
+
+  if (issues.length > 0) {
+    console.log('\nPrerequisite warnings:');
+    for (const issue of issues) {
+      console.log(`  - ${issue}`);
+    }
+    console.log('\nSkills have been installed, but queries will not work until these are resolved.\n');
+  } else {
+    console.log(`Prerequisites OK: Python ${python_version}, vortexasdk ${sdk_version}`);
+  }
+}
+
+function checkEnvGuidance() {
+  const env_path = path.join(os.homedir(), '.claude', 'vortexa', '.env');
+  if (!fs.existsSync(env_path)) {
+    console.log('Note: You\'ll need a .env file with your Vortexa API key.');
+    console.log('Run /vortexa:init in Claude Code to set this up, or create ~/.claude/vortexa/.env with:');
+    console.log('');
+    console.log('  VORTEXA_API_KEY=your_key_here');
+    console.log('');
+  }
+}
+
 function setup(targetDir) {
   const commandsSrc = path.join(packageDir, 'commands', 'vortexa');
   const contextSrc = path.join(packageDir, 'context');
@@ -217,7 +274,7 @@ function setup(targetDir) {
   const libCount = libFiles.length;
   const templateCount = templateFiles.length;
 
-  console.log(`\nVortexa Claude Skills v${version} installed successfully!\n`);
+  console.log(`\nvortexa-claude-skills v${version} installed successfully!\n`);
   console.log('Files installed:');
   console.log(`  ~/.claude/commands/vortexa/  (${commandCount} skill files)`);
   console.log(`  ~/.claude/vortexa/context/   (${contextCount} context docs)`);
@@ -232,6 +289,8 @@ function setup(targetDir) {
   console.log('  2. Run /vortexa:init to set up your environment');
   console.log('  3. Run /vortexa:cargo-flows to start querying!');
   console.log('');
+
+  checkEnvGuidance();
 }
 
 function update(targetDir) {
@@ -292,6 +351,8 @@ function main() {
       setup(targetDir);
       break;
   }
+
+  checkPrerequisites();
 }
 
 try {

package/commands/vortexa/_check-setup.md

@@ -2,7 +2,7 @@
 
 Before executing any Vortexa analytics command, verify both the global install and local environment:
 
-1. Check that `~/.claude/vortexa/VERSION` exists. If not: "Vortexa skills package is not installed. Run: npx @vortexa/claude-skills setup"
+1. Check that `~/.claude/vortexa/VERSION` exists. If not: "Vortexa skills package is not installed. Run: npx vortexa-claude-skills setup"
 2. Check that `.env` exists in the current project directory. If not: "Vortexa environment not configured in this project. Run /vortexa:init first."
 3. Check that `.env` contains `VORTEXA_API_KEY` and it is not `your_key_here`. If not: "API key not configured. Edit .env and add your Vortexa API key."
 

package/commands/vortexa/_wf-ballast-speeds.md

@@ -0,0 +1,135 @@
+---
+name: vortexa:_wf-ballast-speeds
+description: "Seasonal ballast speed patterns with min/max/avg bands"
+argument-hint: "VLCC ballast speeds to AG, 2019-2026, daily"
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Seasonal ballast speed analysis using VoyagesTimeseries with avg_speed metric. Produces the same seasonal overlay chart as /vortexa:seasonal (min/max band, average, last year, current year) but for ballast voyage speeds instead of cargo flows. Uses `complete_seasonal_voyages()` from lib/ballast_speeds.py and `seasonal_chart()` from lib/visualization.py.
+</objective>
+
+<execution_context>
+## Pre-loaded Context (via CLAUDE.md @imports)
+- context/guardrails.md, context/entity-resolution.md, context/date-units.md
+
+## Required Context (Read on demand)
+- context/voyages.md -- VoyagesTimeseries parameters
+</execution_context>
+
+## Setup Check
+@commands/vortexa/_check-setup.md
+
+<process>
+
+## CRITICAL PITFALLS
+- Minimum 3 years for meaningful seasonal bands.
+- breakdown_property='avg_speed' with breakdown_unit_operator='avg' is the standard for speed patterns.
+- voyage_status='ballast' is essential -- without it, you get mixed laden/ballast speeds.
+
+## Step 1: Read Endpoint Context
+Read `context/voyages.md` for VoyagesTimeseries parameters.
+
+## Step 2: Parse the Query
+Extract: product (last cargo), destination, origin (optional), vessel class (optional), frequency (day/month, default: day), moving average (optional), start year.
+
+## Step 3: Check for Missing Parameters
+Required (ask one at a time): product, destination, start year.
+Optional: origin, vessel class, frequency (day), MA period.
+
+## Step 4: Resolve Entity IDs
+Resolve origin, destination, product via lib/entities.py. Use EntityCache().
+
+## Step 5: Confirm Before Executing (MANDATORY)
+```
+Query: [restate]
+Analysis: Seasonal Ballast Speeds
+Endpoint: VoyagesTimeseries (avg_speed, avg operator)
+Voyage status: ballast
+Destination: [name (layer)]
+Origin: [name (layer)] or "not specified"
+Product: [name (layer)] (last cargo filter)
+Vessel class: [class] or "all"
+Year range: [start_year] to [current_year]
+Frequency: [day/month]
+Moving average: [period or "none"]
+
+Confirm or adjust?
+```
+Use AskUserQuestion:
+- Question: "Does this look correct?"
+- Header: "Confirm"
+- Options:
+  1. Label: "Confirm", Description: "Run the analysis as configured"
+  2. Label: "Adjust", Description: "Change one or more parameters before running"
+
+## Step 6: Generate & Execute Code Artifact
+```python
+"""Vortexa Seasonal Ballast Speeds: {description}
+Generated by /vortexa:workflows (Seasonal Ballast Speeds)
+"""
+import os, sys, multiprocessing
+from datetime import datetime
+from dotenv import load_dotenv
+
+if sys.platform == "darwin" and sys.version_info >= (3, 13):
+    multiprocessing.set_start_method("fork", force=True)
+load_dotenv(override=True)
+sys.path.insert(0, os.path.expanduser("~/.claude/vortexa"))
+
+from lib.entities import resolve_geography, resolve_product, EntityCache
+from lib.ballast_speeds import complete_seasonal_voyages
+from lib.visualization import seasonal_chart
+
+cache = EntityCache()
+{entity_resolution_code}
+
+seasonal_df = complete_seasonal_voyages(
+    start_y={start_year}, start_m=1, start_d=1,
+    destination_ids=[{destination_ids}],
+    origin_ids={origin_ids_or_None},
+    product_ids=[{product_id}],
+    vessel_classes={vessel_classes_or_None},
+    voyage_status="ballast",
+    frequency="{frequency}",
+    breakdown_property="avg_speed",
+    breakdown_unit_operator="avg",
+    ma_period={ma_period_or_None},
+)
+
+print(seasonal_df)
+
+fig = seasonal_chart(seasonal_df, title="{title}", y_label="Avg Speed (knots)")
+os.makedirs("output", exist_ok=True)
+filepath = f"output/{slug}_ballast_speeds_{datetime.now().strftime('%Y-%m-%d')}.html"
+fig.write_html(filepath, auto_open=True)
+print(f"Chart saved: {filepath}")
+```
+
+## Step 7: Present Results
+- Seasonal DataFrame summary
+- Chart path
+- Methodology: `VoyagesTimeseries (avg_speed, avg) | ballast | {destination} | {product} | {freq} | {start_year}-{current_year}`
+- Use AskUserQuestion:
+  - Question: "What would you like to do next?"
+  - Header: "Next"
+  - Options:
+    1. Label: "Laden speeds", Description: "Compare with laden voyage speeds"
+    2. Label: "Idle analysis", Description: "Run idle vessel analysis for this fleet"
+    3. Label: "Export CSV", Description: "Save speed data to CSV"
+    4. Label: "Save as notebook", Description: "Convert to Jupyter notebook (.ipynb)"
+    5. Label: "Done", Description: "Analysis complete"
+
+If "Save as notebook": call `output_choice()` from `lib/notebook.py` with the code string to generate the .ipynb.
+
+## Error Handling
+Report errors in plain English. < 3 years warning for seasonal bands.
+
+</process>

package/commands/vortexa/{oow.md → _wf-cow.md}

@@ -1,7 +1,6 @@
 ---
-name: vortexa:oow
-description: "Run oil-on-water breakdown by region using the CM-Authoritative methodology"
-argument-hint: "crude on water by shipping region, last 3 months"
+name: "Cargo-On-Water (COW)"
+description: "Track where cargo volumes are physically located on the water, broken down by shipping region"
 allowed-tools:
   - Read
   - Edit
@@ -9,10 +8,11 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
+  - AskUserQuestion
 ---
 
 <objective>
-Build an oil-on-water breakdown by region using the CM-Authoritative methodology: CargoMovements for authoritative OOW periods and quantities, VoyagesSearchEnriched for real-time vessel location enrichment. Uses `cargo_on_water_ts()` from lib/movements.py for data and `oow_area_chart()` from lib/visualization.py for stacked area visualization.
+Cargo-On-Water (COW) workflow using the CM-Authoritative methodology: CargoMovements for authoritative OOW periods and quantities, VoyagesSearchEnriched for real-time vessel location enrichment. Product-agnostic (crude, LNG, LPG, CPP, DPP). Uses `cargo_on_water_ts()` from lib/movements.py for data. Offers two visualization options: stacked area chart via `oow_area_chart()` or animated dual-basin heatmap via `cow_animated_heatmap()` from lib/visualization.py.
 </objective>
 
 <execution_context>
@@ -33,18 +33,18 @@ Read before processing the user's query:
 
 <process>
 
-## CM-Authoritative OOW -- MANDATORY
+## CM-Authoritative COW -- MANDATORY
 
-The ONLY correct method for location-based OOW analysis is `cargo_on_water_ts()` from lib/movements.py.
+The ONLY correct method for location-based cargo-on-water analysis is `cargo_on_water_ts()` from lib/movements.py.
 
-DO NOT use CTS `cargo_on_water_state` for this skill. CTS shows where cargo was LOADED FROM and GOING TO (origin/destination), NOT where it currently IS on the water.
+DO NOT use CTS `cargo_on_water_state` for this workflow. CTS shows where cargo was LOADED FROM and GOING TO (origin/destination), NOT where it currently IS on the water.
 
 The CM-Authoritative pattern:
 1. CargoMovements with `cargo_on_water_state` for authoritative OOW periods and quantities
 2. VoyagesSearchEnriched for real-time vessel location (shipping_region from events)
 3. Join on cargo_movement_id (16-char truncated) to enrich CM cargoes with voyage location
 
-If the generated code imports CargoTimeSeries for the OOW skill, it is WRONG.
+If the generated code imports CargoTimeSeries for the COW workflow, it is WRONG.
 
 ## Step 1: Read Endpoint Context
 
@@ -54,23 +54,23 @@ Read `context/cargo-movements.md` and `context/voyages.md` (both are needed -- C
 
 Analyze $ARGUMENTS and extract:
 
-- **Product**: typically crude, but any product group works
+- **Product**: any commodity -- crude, LNG, LPG, CPP, DPP, etc. This workflow is product-agnostic.
 - **Location layer**: `shipping_region_v2` (default), `region`, or `country`. Controls how granular the location breakdown is.
 - **Time range**: Apply date-units.md convention. Note: longer ranges = longer API queries (CM + VSE both queried).
-- **Unit**: commodity defaults (oil=b for OOW since it's absolute volume, not rate)
+- **Unit**: commodity defaults -- `b` for crude/CPP/DPP (absolute volume, not rate), `cbm` for LNG, `t` for LPG. See date-units.md.
 - **Top-N**: how many regions to show in chart (default 8)
 - **Frequency**: for chart display resampling -- daily (default), weekly, monthly
-- **Exclude intra-country**: optional, default false for OOW
+- **Exclude intra-country**: optional, default false for COW
 
 ## Step 3: Check for Missing Parameters
 
-Required (ask if missing):
+Required (ask one at a time if missing):
 - **Product** -- MUST be specified
 - **Time range** -- MUST be specified
 
 Optional with smart defaults (mention in confirmation):
 - **Location layer**: default `shipping_region_v2`
-- **Unit**: default `b` (absolute barrels for OOW volumes)
+- **Unit**: commodity default (`b` for crude/CPP/DPP, `cbm` for LNG, `t` for LPG)
 - **Top-N**: default 8
 - **Frequency**: default `daily`
 - **Exclude intra-country**: default false
@@ -85,7 +85,7 @@ Resolve product ID using `lib/entities.py`:
 3. If multiple matches: present top 3 candidates. Ask user to pick. NEVER auto-correct.
 4. If zero matches: tell user the term wasn't found.
 
-No geography resolution needed -- OOW covers global flows; the location layer is applied during the CM+VSE join.
+No geography resolution needed -- COW covers global flows; the location layer is applied during the CM+VSE join.
 
 Use `EntityCache()` from `lib/entities.py` for the session.
 
@@ -95,43 +95,62 @@ Present the complete parameter set:
 
 ```
 Query: [restate the user's question]
-Analysis: Oil-on-water by region (CM-Authoritative)
+Analysis: Cargo-On-Water by region (CM-Authoritative)
 Data: CargoMovements (OOW periods) + VoyagesSearchEnriched (location)
 Product: [name (layer)]
 Time: [start datetime] -> [end datetime]
 Location level: [shipping_region_v2 / region / country]
-Unit: [unit] (absolute volume)
-Chart: Stacked area, Top [N] regions + Other
+Unit: [unit] ([commodity default reason])
+Chart: To be selected after data generation
 Display frequency: [daily/weekly/monthly]
+Top-N: [N] regions
 
 Note: This query calls both CM and VSE endpoints -- may take 1-3 minutes for large date ranges.
 
 Confirm or adjust?
 ```
 
-NEVER execute without confirmation. Wait for user response.
+Use AskUserQuestion:
+- Question: "Does this look correct?"
+- Header: "Confirm"
+- Options:
+  1. Label: "Confirm", Description: "Run the cargo-on-water analysis"
+  2. Label: "Adjust filters", Description: "Change product, time range, or other parameters"
+
+NEVER execute without confirmation. NEVER require the user to type "confirm" -- always use AskUserQuestion with clickable options.
 
 ## Step 6: Generate & Execute Code Artifact
 
-Generate a self-contained .py file using the data -> viz -> save pipeline:
+Generate a self-contained .py file using the data -> viz -> save pipeline.
+
+**Python command:** Use `python3` to execute generated scripts (macOS/Linux). On Windows, `python` is standard. If `python3` fails, fall back to `python`.
+
+**Environment loading:** Always use `load_dotenv(override=True)` so the `.env` file takes precedence over any stale environment variables.
 
 ```python
-"""Vortexa OOW: {description}
-Generated by /vortexa:oow
+"""Vortexa COW: {description}
+Generated by /vortexa:workflows (Cargo-On-Water)
 Date: {date}
 """
-from datetime import datetime
 import os
-import sys; sys.path.insert(0, "lib")
-from entities import resolve_product, EntityCache
-from movements import cargo_on_water_ts
-from visualization import oow_area_chart
+import sys
+import multiprocessing
+from datetime import datetime
+from dotenv import load_dotenv
+
+if sys.platform == "darwin" and sys.version_info >= (3, 13):
+    multiprocessing.set_start_method("fork", force=True)
+
+load_dotenv(override=True)
+
+sys.path.insert(0, os.path.expanduser("~/.claude/vortexa"))
+from lib.entities import resolve_product, EntityCache
+from lib.movements import cargo_on_water_ts
+from lib.visualization import oow_area_chart, cow_animated_heatmap
 
-# Entity Resolution
 cache = EntityCache()
 {product_resolution_code}
 
-# OOW by Region (CM-Authoritative)
 ts_wide = cargo_on_water_ts(
     time_min=datetime({time_min}),
     time_max=datetime({time_max}),
@@ -143,21 +162,37 @@ ts_wide = cargo_on_water_ts(
 )
 
 print(ts_wide)
+```
+
+After the data is generated and printed, present the user with a visualization choice using AskUserQuestion:
 
-# Chart
+- Question: "Which visualization would you like?"
+- Header: "Chart type"
+- Options:
+  1. Label: "Stacked Area Chart", Description: "Cleaner timeseries view -- top N regions stacked over time"
+  2. Label: "Animated Heatmap", Description: "Dual-basin Atlantic/Pacific grid with day-over-day changes, play/pause, date slider"
+
+Then append the user's chosen visualization code to the script and run it:
+
+**If Stacked Area Chart:**
+```python
 fig = oow_area_chart(ts_wide, freq="{freq}", top_n={top_n}, title="{title}")
 
 os.makedirs("output", exist_ok=True)
-filepath = f"output/{slug}_oow_{datetime.now().strftime('%Y-%m-%d')}.html"
+filepath = f"output/{slug}_cow_area_{datetime.now().strftime('%Y-%m-%d')}.html"
 fig.write_html(filepath, auto_open=True)
 print(f"Chart saved: {filepath}")
-
-# Export (uncomment to save)
-# ts_wide.to_csv(f"output/{slug}_oow_{datetime.now().strftime('%Y-%m-%d')}.csv")
 ```
 
-After generating, ask: "Save as new file, or add to an existing notebook/script?" Default: new file.
-Run the code to get results.
+**If Animated Heatmap:**
+```python
+fig = cow_animated_heatmap(ts_wide, title="{title}", speed_ms=200, unit_label="{unit}")
+
+os.makedirs("output", exist_ok=True)
+filepath = f"output/{slug}_cow_heatmap_{datetime.now().strftime('%Y-%m-%d')}.html"
+fig.write_html(filepath, auto_open=True)
+print(f"Chart saved: {filepath}")
+```
 
 ## Step 7: Present Results
 
@@ -166,11 +201,21 @@ Run the code to get results.
 - If capped: "Showing first N of M rows"
 - One-line methodology footnote using CONFIRMED parameters:
   ```
-  Methodology: CM-Authoritative OOW | CargoMovements (cargo_on_water_state) + VoyagesSearchEnriched (location) | {product} | {unit} | {location_layer} | Top {N}
+  Methodology: CM-Authoritative COW | CargoMovements (cargo_on_water_state) + VoyagesSearchEnriched (location) | {product} | {unit} | {location_layer} | Top {N}
   ```
   Use human-readable names for entity filters (not hex IDs).
 - File path to chart HTML
-- Offer: "Export to CSV?" and "Want a summary?"
+- Use AskUserQuestion:
+  - Question: "What would you like to do with these results?"
+  - Header: "Next step"
+  - Options:
+    1. Label: "Export to CSV", Description: "Save COW data to CSV"
+    2. Label: "Switch visualization", Description: "Try the other chart type (area/heatmap)"
+    3. Label: "Show summary", Description: "Summarize key COW findings by region"
+    4. Label: "Save as notebook", Description: "Convert to Jupyter notebook (.ipynb)"
+    5. Label: "Done", Description: "Analysis complete"
+
+If "Save as notebook": call `output_choice()` from `lib/notebook.py` with the code string to generate the .ipynb.
 
 ## Error Handling