feat: improve 5 lowest-scoring skill definitions

GEO-INFER-EXAMPLES/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geo-infer-examples
-description: Working examples and module orchestration patterns. Use when looking for usage examples, cross-module orchestration patterns, end-to-end workflows, or reference implementations of GEO-INFER capabilities.
+description: "Provides runnable code examples and module orchestration patterns for the GEO-INFER framework. Use when wiring GEO-INFER modules together for the first time, finding a working agriculture/climate/health/IoT integration pattern, running a cross-module SPACE-MATH-BAYES pipeline, or adapting a reference implementation to a new geospatial domain."
 prerequisites:
   required: []
   recommended: []
@@ -13,42 +13,50 @@ examples_dir: ../GEO-INFER-EXAMPLES/examples/
 
 ## Instructions
 
-### Core Capabilities
-
-- **Module orchestrators**: Cross-module workflow examples
-- **Domain examples**: Per-domain analysis workflows
-- **Active Inference**: End-to-end inference pipeline examples
-- **Integration patterns**: How modules connect and compose
+### Step 1: Identify the Example Category
 
-### Key Directories
+Browse the examples directory to find the pattern that matches your use case:
 
 ```text
 GEO-INFER-EXAMPLES/examples/
-├── module_orchestrator.py    # Cross-module coordination
-├── spatial_analysis/         # SPACE + MATH examples
-├── active_inference/         # ACT + BAYES examples
-└── domain/                   # Domain-specific examples
+├── module_orchestrators/         # Cross-module coordination pipelines
+├── getting_started/              # Beginner walkthroughs
+├── agriculture_integration/      # AG + SPACE + RISK workflows
+├── climate_integration/          # CLIMATE + TIME + MATH workflows
+├── health_integration/           # HEALTH + BAYES + SPACE workflows
+├── iot_radiation_monitoring/     # IOT + DATA + SPACE real-time pipelines
+└── area_study/                   # Region-specific analysis patterns
 ```
 
-### Orchestrator Example
+### Step 2: Run an Example
 
-```python
-from geo_infer_examples.module_orchestrator import ModuleOrchestrator
+1. Install required modules for the example (check imports at the top of each script):
+   ```bash
+   uv pip install -e ./GEO-INFER-SPACE ./GEO-INFER-MATH ./GEO-INFER-BAYES
+   ```
+2. Verify imports resolve — run `python -c "from geo_infer_space.backends.h3 import H3Backend"` to confirm each module is installed correctly.
+3. Execute the example script:
+   ```bash
+   uv run python GEO-INFER-EXAMPLES/examples/module_orchestrators/orchestrator_demo.py
+   ```
+4. Check output for convergence status and iteration count to confirm the pipeline ran end-to-end.
 
-orchestrator = ModuleOrchestrator(modules=["SPACE", "MATH", "BAYES"])
-result = orchestrator.run(data, max_iterations=100)
-# Convergence uses numeric relative-change (not placeholder)
-```
+### Core Capabilities
+
+- **Module orchestrators**: Chain SPACE, MATH, BAYES, ACT, and other modules into convergent pipelines
+- **Domain examples**: Agriculture risk, climate analysis, health mapping, IoT monitoring
+- **Active Inference**: End-to-end inference pipelines using ACT + BAYES with free energy minimization
+- **Integration patterns**: How modules connect, compose, and exchange data across the framework
 
 ## Examples
 
 ```python
+# Cross-module pipeline: SPACE → MATH → BAYES
 from geo_infer_examples.module_orchestrator import ModuleOrchestrator
 
-# Cross-module pipeline: SPACE → MATH → BAYES
 orchestrator = ModuleOrchestrator(modules=["SPACE", "MATH", "BAYES"])
 result = orchestrator.run(data, max_iterations=100)
-# Convergence uses numeric relative-change (not placeholder)
+# Convergence uses numeric relative-change threshold
 print(f"Converged in {result.iterations} iterations")
 ```
 
@@ -58,26 +66,56 @@ from geo_infer_ag.models.soil_health import SoilHealthModel
 from geo_infer_risk.core.risk_engine import RiskEngine
 from geo_infer_space.backends.h3 import H3Backend
 
-# 1. Tessellate farm boundary
+# 1. Tessellate farm boundary into H3 cells
 cells = H3Backend().tessellate(farm_polygon, resolution=9)
 
 # 2. Assess soil health per cell
 soil = SoilHealthModel()
 health_scores = {cell: soil.assess(cell) for cell in cells}
 
-# 3. Compute risk
+# 3. Compute spatially-aware risk map
 risk = RiskEngine()
 risk_map = risk.assess(hazard=drought_index, exposure=health_scores)
 ```
 
+```python
+# Climate integration: temporal trend analysis over spatial grid
+from geo_infer_climate.core.trend_analyzer import TrendAnalyzer
+from geo_infer_space.backends.h3 import H3Backend
+from geo_infer_time.core.temporal_index import TemporalIndex
+
+# 1. Define spatial extent and time range
+cells = H3Backend().tessellate(region_polygon, resolution=7)
+time_range = TemporalIndex(start="2020-01", end="2025-12", freq="monthly")
+
+# 2. Analyze climate trends per cell over time
+analyzer = TrendAnalyzer()
+trends = {
+    cell: analyzer.fit(climate_data[cell], time_range)
+    for cell in cells
+}
+
+# 3. Identify cells with statistically significant warming
+hotspots = [cell for cell, t in trends.items() if t.p_value < 0.05]
+```
+
 ## Guidelines
 
-- `module_orchestrator.py` convergence check uses numeric relative-change
-- Missing end-to-end Active Inference tutorial (planned for v0.4.0)
-- Test: `uv run python -m pytest GEO-INFER-EXAMPLES/tests/ -v`
+### Running and Testing Examples
+
+- Run all example tests: `uv run python -m pytest GEO-INFER-EXAMPLES/tests/ -v`
+- Run a specific example category: `uv run python -m pytest GEO-INFER-EXAMPLES/tests/ -k "agriculture" -v`
+- Install module dependencies before running — each example's imports indicate which modules are needed.
+
+### Common Pitfalls
+
+- **Missing module installs**: Examples import from multiple GEO-INFER modules. Install all referenced modules before running, or you will get `ModuleNotFoundError`.
+- **H3 version mismatch**: SPACE examples require `h3>=4.0.0` (use `latlng_to_cell`, not the legacy `geo_to_h3` API).
+- **Convergence tuning**: The `ModuleOrchestrator` uses numeric relative-change for convergence checks. Adjust `max_iterations` and tolerance based on data complexity.
+- End-to-end Active Inference tutorial is planned for v0.4.0.
 
 ### Integrations
 
-- **INTRA** → Documentation hub links to examples
-- **All modules** → Examples demonstrate cross-module workflows
-- **TEST** → Example code testable as integration tests
+- **INTRA** → Documentation hub links to these examples for onboarding
+- **All modules** → Examples demonstrate cross-module data flow and composition
+- **TEST** → Example scripts are testable as integration tests via the unified test runner

GEO-INFER-INTRA/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geo-infer-intra
-description: Central documentation hub and cross-module integration guides for GEO-INFER. Use when navigating documentation, finding cross-module integration patterns, understanding data flow architecture, or locating tutorials and API references.
+description: "Central documentation hub and cross-module integration layer for GEO-INFER. Use when onboarding new developers to the framework, wiring together multi-module pipelines (e.g. DATA to SPACE to BAYES), resolving import paths across the 44-module monorepo, looking up API signatures for any module, or debugging cross-module data flow issues."
 prerequisites:
   required: []
   recommended: []
@@ -13,72 +13,131 @@ examples_dir: ../GEO-INFER-EXAMPLES/examples/
 
 ## Instructions
 
-### Core Capabilities
+### When to Use This Skill
 
-- **Documentation hub**: Central `docs/` directory with comprehensive guides
-- **Integration guides**: Cross-module data flow patterns and examples
-- **Architecture docs**: System design diagrams, module dependency graph
-- **API reference**: Consolidated API documentation for all 44 modules
-- **Tutorials**: Step-by-step workflows spanning multiple modules
+Use `geo-infer-intra` when you need to:
 
-### Key Directories
+- Onboard to GEO-INFER and understand the module landscape
+- Wire data between two or more modules (e.g. DATA -> SPACE -> BAYES)
+- Find the correct import path or API signature for any of the 44 modules
+- Debug data format mismatches at module boundaries
+- Locate tutorials, architecture diagrams, or integration guides
 
-```text
-GEO-INFER-INTRA/docs/
-├── guides/          # How-to guides for common workflows
-├── tutorials/       # Step-by-step multi-module tutorials
-├── integration/     # Cross-module integration patterns
-├── architecture/    # System design and data flow diagrams
-└── api/             # Consolidated API reference
-```
+### Step-by-Step Workflow
 
-### Cross-Module Integration Pattern
+1. **Identify the modules involved**: Determine which GEO-INFER modules your task spans. Check `docs/architecture/` for the module dependency graph.
+2. **Check integration guides**: Look in `docs/integration/` for an existing pattern matching your module combination. Many common pipelines (SPACE->MATH->BAYES, DATA->AI->AGENT) are already documented.
+3. **Verify data contracts**: Each module expects specific input formats. Cross-reference the API docs in `docs/api/` to confirm the output of module A matches the input of module B.
+4. **Build the pipeline**: Import from each module's canonical path (`geo_infer_<module>.core.*` for algorithms, `geo_infer_<module>.api.*` for endpoints).
+5. **Test the integration**: Run `uv run python -m pytest GEO-INFER-INTRA/tests/ -v` to validate cross-module flows.
 
-```python
-# Example: SPACE → MATH → BAYES pipeline
-from geo_infer_space.backends.h3 import H3Backend
-from geo_infer_math.core.spatial_statistics import MoranI
-from geo_infer_bayes.core.bayesian_inference import BayesianModel
+### Key Directories
 
-# 1. Index → 2. Analyze → 3. Model
-cells = H3Backend().tessellate(region, resolution=7)
-autocorrelation = MoranI(values, weights).compute()
-posterior = BayesianModel().fit(data)
+```text
+GEO-INFER-INTRA/
+├── docs/
+│   ├── guides/          # How-to guides for common workflows
+│   ├── tutorials/       # Step-by-step multi-module tutorials
+│   ├── integration/     # Cross-module integration patterns
+│   ├── architecture/    # System design and data flow diagrams
+│   └── api/             # Consolidated API reference
+├── src/geo_infer_intra/
+│   ├── core/            # Integration logic and orchestration
+│   ├── api/             # Internal API interfaces
+│   ├── models/          # Shared data models
+│   └── utils/           # Cross-module helpers
+└── tests/               # Integration tests
 ```
 
 ## Examples
 
+### Example 1: Multi-Module Geospatial Pipeline
+
 ```python
-# Multi-module data flow: DATA → SPACE → MATH → BAYES
+# DATA → SPACE → MATH → BAYES: load, index, analyze, model
 from geo_infer_data.formats.geojson import GeoJSONLoader
 from geo_infer_space.backends.h3 import H3Backend
 from geo_infer_math.core.spatial_statistics import MoranI
 from geo_infer_bayes.core.bayesian_inference import BayesianModel
 
-# 1. Load → 2. Index → 3. Analyze → 4. Model
 features = GeoJSONLoader().load("observations.geojson")
 cells = H3Backend().tessellate(features.bounds, resolution=7)
 autocorrelation = MoranI(values, weights).compute()
 posterior = BayesianModel().fit(data)
 ```
 
+### Example 2: Module Discovery and Health Check
+
 ```python
-# Onboarding: discover module capabilities
+# Verify which modules are installed and importable
 import importlib
-for module_name in ["math", "space", "bayes", "act", "risk"]:
-    mod = importlib.import_module(f"geo_infer_{module_name}")
-    print(f"geo_infer_{module_name}: {mod.__doc__ or 'No docstring'}")
+
+MODULE_NAMES = ["math", "space", "bayes", "act", "risk", "data", "ai"]
+available, missing = [], []
+
+for name in MODULE_NAMES:
+    try:
+        mod = importlib.import_module(f"geo_infer_{name}")
+        available.append(name)
+    except ImportError:
+        missing.append(name)
+
+print(f"Available: {available}")
+if missing:
+    print(f"Missing (install with uv): {missing}")
+```
+
+### Example 3: Cross-Module Error Handling at Boundaries
+
+```python
+# Safely chain SPACE → MATH with boundary validation
+from geo_infer_space.backends.h3 import H3Backend
+from geo_infer_math.core.spatial_statistics import MoranI
+
+cells = H3Backend().tessellate(region, resolution=7)
+
+if not cells or len(cells) == 0:
+    raise ValueError("Tessellation produced no cells — check region bounds and resolution")
+
+values = extract_values(cells)  # your extraction logic
+weights = compute_spatial_weights(cells)
+
+if values.shape[0] != weights.shape[0]:
+    raise ValueError(
+        f"Shape mismatch: {values.shape[0]} values vs {weights.shape[0]} weights. "
+        "Ensure spatial weights match the cell count from tessellation."
+    )
+
+result = MoranI(values, weights).compute()
 ```
 
 ## Guidelines
 
-- Start here when onboarding to GEO-INFER
-- Each module's README.md and AGENTS.md provide module-level detail
-- Each module's SKILL.md provides quick-reference for Claude Code
-- Test: `uv run python -m pytest GEO-INFER-INTRA/tests/ -v`
+### Getting Started
+
+- Start here when onboarding to GEO-INFER; this module is the entry point for understanding the framework
+- Each module's `SKILL.md` gives a quick-reference; `AGENTS.md` and `README.md` provide deeper module-level detail
+- Use the data flow overview: `Data Sources → DATA → SPACE/TIME → MATH/BAYES/ACT → AI/AGENT → Domain Modules → API/APP`
+
+### Common Pitfalls
+
+- **Import path casing**: Most modules use lowercase (`geo_infer_math`), but environmental modules currently use mixed-case dirs (`geo_infer_FOREST`, `geo_infer_MARINE`). Check the actual package directory before importing.
+- **H3 version**: SPACE and PLACE modules require `h3>=4.0.0`. Use `latlng_to_cell` / `cell_to_latlng`, not the legacy v3 API.
+- **Data format mismatches**: When chaining modules, verify that the output format of one module matches the expected input of the next. GeoJSON features, H3 cell arrays, and numpy arrays are the most common interchange formats.
+- **Optional dependencies**: Modules use `try/except` imports for optional deps. If a feature silently returns `None`, check whether the underlying package (e.g. `torch`, `geopandas`) is installed.
+
+### Testing
+
+```bash
+# Run INTRA integration tests
+uv run python -m pytest GEO-INFER-INTRA/tests/ -v
+
+# Run full cross-module test suite
+uv run python GEO-INFER-TEST/run_unified_tests.py --category integration
+```
 
 ### Integrations
 
-- **EXAMPLES** → Working code examples referenced from docs
-- **All modules** → Central hub linking all module documentation
-- **TEST** → Documentation-driven testing patterns
+- **EXAMPLES** → Working code examples referenced from docs (`../GEO-INFER-EXAMPLES/examples/`)
+- **All 44 modules** → Central hub linking documentation, API references, and integration patterns
+- **TEST** → Documentation-driven testing patterns and the unified test runner