Massive simplification and reground docs/skills/notebooks/py against latest crc-sdk

.agents/skills/compare-crc-velo-assessments/SKILL.md

@@ -7,6 +7,21 @@ description: Reconcile an open CRC climate-risk assessment with its VELO/CDT ent
 
 Make the open/proprietary relationship credible by preserving both provenance and non-equivalence.
 
+## Before each assessment: refresh from the canonical source
+
+This installed copy is a bootstrap for `RiskThinking/crc-docs`. Before executing
+an assessment, resolve `main` at
+`https://api.github.com/repos/RiskThinking/crc-docs/commits/main` using an available
+GitHub, web-fetch or Git tool. Record the returned full commit SHA, then load
+`https://raw.githubusercontent.com/RiskThinking/crc-docs/<sha>/.agents/skills/compare-crc-velo-assessments/SKILL.md`
+and its required linked files from that same commit. Follow that version for this
+run; see its `ai-playbooks/docs/skill-refresh.md` for resolution and provenance.
+Do this once per new assessment, not recursively when reading the fetched skill.
+An explicit user-pinned revision or requested local development copy takes
+precedence and must be labelled. If the commit or required files cannot be
+verified, report the limitation and stop assessment execution; never silently
+use an older installed copy. This refreshes the run, not the host's installation.
+
 ## Guided intake
 
 Treat naming this skill in plain language, or any platform selector
@@ -31,6 +46,14 @@ do not imply that the targets align or that the exercise demonstrates live VELO
 capability. A decision-grade paired comparison requires CRC and VELO outputs for
 the same real target, with aligned dimensions documented below.
 
+## Execution reference
+
+Use the repository's [setup](../../../ai-playbooks/docs/setup.md) and
+[capability matrix](../../../ai-playbooks/docs/capability-matrix.md) for the
+tested package baseline and output contract. Run repository-relative commands
+from the `crc-docs` root. Helpers produce intermediate data; complete the
+reporting and interpretation steps below in the assistant workflow.
+
 ## Workflow
 
 1. Inventory both artifacts and run `scripts/inventory_assessments.py` when CRC Parquet and VELO JSON are available.

.agents/skills/crc-assess-agricultural-climate-risk/SKILL.md

@@ -8,6 +8,21 @@ description: Assess bounded USDA crop-cover or global FTW field evidence against
 Produce an auditable agricultural evidence layer and a separate per-hazard
 evaluation. Never infer ownership, yield, production, or a combined risk score.
 
+## Before each assessment: refresh from the canonical source
+
+This installed copy is a bootstrap for `RiskThinking/crc-docs`. Before executing
+an assessment, resolve `main` at
+`https://api.github.com/repos/RiskThinking/crc-docs/commits/main` using an available
+GitHub, web-fetch or Git tool. Record the returned full commit SHA, then load
+`https://raw.githubusercontent.com/RiskThinking/crc-docs/<sha>/.agents/skills/crc-assess-agricultural-climate-risk/SKILL.md`
+and its required linked files from that same commit. Follow that version for this
+run; see its `ai-playbooks/docs/skill-refresh.md` for resolution and provenance.
+Do this once per new assessment, not recursively when reading the fetched skill.
+An explicit user-pinned revision or requested local development copy takes
+precedence and must be labelled. If the commit or required files cannot be
+verified, report the limitation and stop assessment execution; never silently
+use an older installed copy. This refreshes the run, not the host's installation.
+
 ## Intake and source choice
 
 Reuse a supplied geography, year, crops, hazard, and decision context. If the
@@ -22,6 +37,14 @@ a narrow WGS84 AOI.
 - Default flood to EFAS in Europe and GloFAS elsewhere. Add EDO SMI only when
   drought is relevant and covered.
 
+## Execution reference
+
+Use the repository's [setup](../../../ai-playbooks/docs/setup.md) and
+[capability matrix](../../../ai-playbooks/docs/capability-matrix.md) for the
+tested package baseline and output contract. Run repository-relative commands
+from the `crc-docs` root. Helpers produce intermediate data; complete the
+reporting and interpretation steps below in the assistant workflow.
+
 ## Workflow
 
 1. Read [the agricultural playbook](../../../ai-playbooks/agricultural-climate-risk.md).

.agents/skills/crc-assess-asset-portfolio-risk/SKILL.md

@@ -7,6 +7,21 @@ description: Assess a user-supplied portfolio or Overture candidate locations ag
 
 Keep per-hazard results auditable and refuse to fabricate a combined portfolio score.
 
+## Before each assessment: refresh from the canonical source
+
+This installed copy is a bootstrap for `RiskThinking/crc-docs`. Before executing
+an assessment, resolve `main` at
+`https://api.github.com/repos/RiskThinking/crc-docs/commits/main` using an available
+GitHub, web-fetch or Git tool. Record the returned full commit SHA, then load
+`https://raw.githubusercontent.com/RiskThinking/crc-docs/<sha>/.agents/skills/crc-assess-asset-portfolio-risk/SKILL.md`
+and its required linked files from that same commit. Follow that version for this
+run; see its `ai-playbooks/docs/skill-refresh.md` for resolution and provenance.
+Do this once per new assessment, not recursively when reading the fetched skill.
+An explicit user-pinned revision or requested local development copy takes
+precedence and must be labelled. If the commit or required files cannot be
+verified, report the limitation and stop assessment execution; never silently
+use an older installed copy. This refreshes the run, not the host's installation.
+
 ## Guided intake
 
 Treat naming this skill in plain language, or any platform selector
@@ -34,6 +49,14 @@ beneath `pipeline_output/`. Overture candidates demonstrate geographic exposure
 only and do not establish ownership, materiality, asset value, or portfolio
 membership.
 
+## Execution reference
+
+Use the repository's [setup](../../../ai-playbooks/docs/setup.md) and
+[capability matrix](../../../ai-playbooks/docs/capability-matrix.md) for the
+tested package baseline and output contract. Run repository-relative commands
+from the `crc-docs` root. Helpers produce intermediate data; complete the
+reporting and interpretation steps below in the assistant workflow.
+
 ## Workflow
 
 1. Validate a unique asset ID and coordinates/H3 cell for every asset. AI may discover open Overture candidate locations, but the open stack does not verify ownership, materiality, or portfolio membership.

.agents/skills/crc-assess-asset-portfolio-risk/references/playbook.md

@@ -1,6 +1,6 @@
 # Asset portfolio playbook
 
-Install `crc-sdk[geometry]==0.3.0` for point assets, adding `raster` or `zarr` when the source onboarding path needs it.
+Use the repository environment: `uv sync --locked`. See [setup](../../../../ai-playbooks/docs/setup.md) for optional dependencies and the tested package baseline.
 
 ## Native crc-docs learning path
 

.agents/skills/crc-model-flood-insurance-loss/SKILL.md

@@ -7,6 +7,21 @@ description: Apply an explicit depth-damage function to a CRC canonical flood da
 
 Model hazard-to-damage transparently. Do not call the result a premium, technical price, reserve, or regulatory capital requirement.
 
+## Before each assessment: refresh from the canonical source
+
+This installed copy is a bootstrap for `RiskThinking/crc-docs`. Before executing
+an assessment, resolve `main` at
+`https://api.github.com/repos/RiskThinking/crc-docs/commits/main` using an available
+GitHub, web-fetch or Git tool. Record the returned full commit SHA, then load
+`https://raw.githubusercontent.com/RiskThinking/crc-docs/<sha>/.agents/skills/crc-model-flood-insurance-loss/SKILL.md`
+and its required linked files from that same commit. Follow that version for this
+run; see its `ai-playbooks/docs/skill-refresh.md` for resolution and provenance.
+Do this once per new assessment, not recursively when reading the fetched skill.
+An explicit user-pinned revision or requested local development copy takes
+precedence and must be labelled. If the commit or required files cannot be
+verified, report the limitation and stop assessment execution; never silently
+use an older installed copy. This refreshes the run, not the host's installation.
+
 ## Guided intake
 
 Treat naming this skill in plain language, or any platform selector
@@ -32,6 +47,14 @@ depth knots `0,0.2,1,2` metres and damage-ratio knots
 `pipeline_output/`. Overture records are not an insured portfolio, and real
 analysis requires authorized exposures and an applicable, approved curve.
 
+## Execution reference
+
+Use the repository's [setup](../../../ai-playbooks/docs/setup.md) and
+[capability matrix](../../../ai-playbooks/docs/capability-matrix.md) for the
+tested package baseline and output contract. Run repository-relative commands
+from the `crc-docs` root. Helpers produce intermediate data; complete the
+reporting and interpretation steps below in the assistant workflow.
+
 ## Workflow
 
 1. Require a CRC canonical flood Parquet file and an asset CSV with `asset_id`, `longitude`, and `latitude`.

.agents/skills/crc-model-flood-insurance-loss/references/playbook.md

@@ -1,6 +1,6 @@
 # Flood loss playbook
 
-Install `crc-sdk[geometry]==0.3.0` for point-asset evaluation.
+Use the repository environment: `uv sync --locked`. See [setup](../../../../ai-playbooks/docs/setup.md) for optional dependencies and the tested package baseline.
 
 ## Native crc-docs examples
 

.agents/skills/crc-screen-mortgage-flood/SKILL.md

@@ -7,6 +7,21 @@ description: Screen residential or commercial mortgage collateral or Overture ca
 
 Produce a screening result, not an automated lending decision.
 
+## Before each assessment: refresh from the canonical source
+
+This installed copy is a bootstrap for `RiskThinking/crc-docs`. Before executing
+an assessment, resolve `main` at
+`https://api.github.com/repos/RiskThinking/crc-docs/commits/main` using an available
+GitHub, web-fetch or Git tool. Record the returned full commit SHA, then load
+`https://raw.githubusercontent.com/RiskThinking/crc-docs/<sha>/.agents/skills/crc-screen-mortgage-flood/SKILL.md`
+and its required linked files from that same commit. Follow that version for this
+run; see its `ai-playbooks/docs/skill-refresh.md` for resolution and provenance.
+Do this once per new assessment, not recursively when reading the fetched skill.
+An explicit user-pinned revision or requested local development copy takes
+precedence and must be labelled. If the commit or required files cannot be
+verified, report the limitation and stop assessment execution; never silently
+use an older installed copy. This refreshes the run, not the host's installation.
+
 ## Guided intake
 
 Treat naming this skill in plain language, or any platform selector
@@ -34,6 +49,14 @@ selection rule. Evaluate the generated CSV through this skill's script with
 `--hazard <jrc.parquet>`. Overture candidates are demonstration locations, not
 verified collateral, ownership, occupancy, value, or insurance exposure.
 
+## Execution reference
+
+Use the repository's [setup](../../../ai-playbooks/docs/setup.md) and
+[capability matrix](../../../ai-playbooks/docs/capability-matrix.md) for the
+tested package baseline and output contract. Run repository-relative commands
+from the `crc-docs` root. Helpers produce intermediate data; complete the
+reporting and interpretation steps below in the assistant workflow.
+
 ## Workflow
 
 1. Confirm the asset input contains a unique `asset_id` and WGS84 `longitude`/`latitude`. If AI sources Overture candidates, report how the bounds and filters were chosen; never geocode silently.
@@ -69,7 +92,7 @@ state why the map could not be produced.
 
 ## Boundaries
 
-- Target `crc-sdk==0.3.0` and `crc-framework>=0.2,<0.3`.
+- Use the tested package versions in the repository lockfile; see the setup reference above.
 - Treat the future open CDT hazard dataset as unavailable until a released adapter passes its conformance fixture.
 - Do not call historical JRC flood depth a future climate scenario.
 - Do not describe “no match” as “no risk.”

.agents/skills/crc-screen-mortgage-flood/references/playbook.md

@@ -1,6 +1,6 @@
 # Mortgage flood playbook
 
-Install `crc-sdk[geometry,raster]==0.3.0`. Point-to-H3 conversion needs the geometry extra; JRC GeoTIFF acquisition needs the raster extra.
+Use the repository environment: `uv sync --locked`. See [setup](../../../../ai-playbooks/docs/setup.md) for optional dependencies and the tested package baseline.
 
 ## Native crc-docs examples
 

.agents/skills/velo-assess-company-climate-risk/SKILL.md

@@ -7,6 +7,21 @@ description: Assess company or market-index physical climate risk with VELO/CDT
 
 Use VELO's asset and ownership intelligence to answer a business diligence question; preserve scenario and metric definitions.
 
+## Before each assessment: refresh from the canonical source
+
+This installed copy is a bootstrap for `RiskThinking/crc-docs`. Before executing
+an assessment, resolve `main` at
+`https://api.github.com/repos/RiskThinking/crc-docs/commits/main` using an available
+GitHub, web-fetch or Git tool. Record the returned full commit SHA, then load
+`https://raw.githubusercontent.com/RiskThinking/crc-docs/<sha>/.agents/skills/velo-assess-company-climate-risk/SKILL.md`
+and its required linked files from that same commit. Follow that version for this
+run; see its `ai-playbooks/docs/skill-refresh.md` for resolution and provenance.
+Do this once per new assessment, not recursively when reading the fetched skill.
+An explicit user-pinned revision or requested local development copy takes
+precedence and must be labelled. If the commit or required files cannot be
+verified, report the limitation and stop assessment execution; never silently
+use an older installed copy. This refreshes the run, not the host's installation.
+
 ## Guided intake
 
 Treat naming this skill in plain language, or any platform selector
@@ -44,6 +59,14 @@ authorized connection is available, explain the prerequisite and stop. The
 repository's synthetic VELO-shaped JSON is only for reconciliation smoke tests,
 not a substitute for this assessment.
 
+## Execution reference
+
+Use the repository's [setup](../../../ai-playbooks/docs/setup.md) and
+[capability matrix](../../../ai-playbooks/docs/capability-matrix.md) for the
+tested package baseline and output contract. Run repository-relative commands
+from the `crc-docs` root. Helpers produce intermediate data; complete the
+reporting and interpretation steps below in the assistant workflow.
+
 ## Workflow
 
 1. Resolve the company or market index. Show ambiguity and require selection rather than choosing silently.

.agents/skills/velo-triage-portfolio-insurability/SKILL.md

@@ -7,6 +7,21 @@ description: Triage a company's physical-asset portfolio through the remote CDT
 
 Use VELO classifications as platform signals, not as universal actuarial or underwriting policy.
 
+## Before each assessment: refresh from the canonical source
+
+This installed copy is a bootstrap for `RiskThinking/crc-docs`. Before executing
+an assessment, resolve `main` at
+`https://api.github.com/repos/RiskThinking/crc-docs/commits/main` using an available
+GitHub, web-fetch or Git tool. Record the returned full commit SHA, then load
+`https://raw.githubusercontent.com/RiskThinking/crc-docs/<sha>/.agents/skills/velo-triage-portfolio-insurability/SKILL.md`
+and its required linked files from that same commit. Follow that version for this
+run; see its `ai-playbooks/docs/skill-refresh.md` for resolution and provenance.
+Do this once per new assessment, not recursively when reading the fetched skill.
+An explicit user-pinned revision or requested local development copy takes
+precedence and must be labelled. If the commit or required files cannot be
+verified, report the limitation and stop assessment execution; never silently
+use an older installed copy. This refreshes the run, not the host's installation.
+
 ## Guided intake
 
 Treat naming this skill in plain language, or any platform selector
@@ -41,6 +56,14 @@ supported pathways and horizons. Ask the user to select among ambiguous matches.
 If no authorized connection is available, explain the prerequisite and stop;
 never present mocked classifications as live VELO results.
 
+## Execution reference
+
+Use the repository's [setup](../../../ai-playbooks/docs/setup.md) and
+[capability matrix](../../../ai-playbooks/docs/capability-matrix.md) for the
+tested package baseline and output contract. Run repository-relative commands
+from the `crc-docs` root. Helpers produce intermediate data; complete the
+reporting and interpretation steps below in the assistant workflow.
+
 ## Workflow
 
 1. Resolve an existing company and confirm pathway/horizon from the connected API or MCP capability list.

.agents/skills/velo-underwrite-property-climate/SKILL.md

@@ -7,6 +7,21 @@ description: Perform a higher-calibre property climate underwriting assessment t
 
 Use enterprise data to deepen a CRC baseline; do not turn a platform score into an automatic lending decision.
 
+## Before each assessment: refresh from the canonical source
+
+This installed copy is a bootstrap for `RiskThinking/crc-docs`. Before executing
+an assessment, resolve `main` at
+`https://api.github.com/repos/RiskThinking/crc-docs/commits/main` using an available
+GitHub, web-fetch or Git tool. Record the returned full commit SHA, then load
+`https://raw.githubusercontent.com/RiskThinking/crc-docs/<sha>/.agents/skills/velo-underwrite-property-climate/SKILL.md`
+and its required linked files from that same commit. Follow that version for this
+run; see its `ai-playbooks/docs/skill-refresh.md` for resolution and provenance.
+Do this once per new assessment, not recursively when reading the fetched skill.
+An explicit user-pinned revision or requested local development copy takes
+precedence and must be labelled. If the commit or required files cannot be
+verified, report the limitation and stop assessment execution; never silently
+use an older installed copy. This refreshes the run, not the host's installation.
+
 ## Guided intake
 
 Treat naming this skill in plain language, or any platform selector
@@ -44,6 +59,14 @@ their property query, show candidates, and require a selection when ambiguous.
 If no authorized connection is available, explain the prerequisite and stop;
 never replace enterprise evidence with synthetic data.
 
+## Execution reference
+
+Use the repository's [setup](../../../ai-playbooks/docs/setup.md) and
+[capability matrix](../../../ai-playbooks/docs/capability-matrix.md) for the
+tested package baseline and output contract. Run repository-relative commands
+from the `crc-docs` root. Helpers produce intermediate data; complete the
+reporting and interpretation steps below in the assistant workflow.
+
 ## Workflow
 
 1. Require an existing VELO `asset_id` or search query. If search returns ambiguity, show candidates and stop for selection. State whether the result is truncated; refine or paginate the search before selection when it is.

AGENTS.md

@@ -5,7 +5,7 @@ Canonical skill definitions live under [`.agents/skills/`](.agents/skills), one
 `AGENTS.md` (Codex, Cursor, Aider, Amp, and similar) discover the skills
 without any manual linking step. Claude Code loads this file through
 `@AGENTS.md` in the root [`CLAUDE.md`](CLAUDE.md). claude.ai has no automatic
-repository discovery; see README.md's "Platform discovery" section.
+repository discovery; see [platform discovery](ai-playbooks/docs/setup.md#platform-discovery).
 
 ## Skills
 
@@ -20,6 +20,14 @@ repository discovery; see README.md's "Platform discovery" section.
 | velo-assess-company-climate-risk | [.agents/skills/velo-assess-company-climate-risk/SKILL.md](.agents/skills/velo-assess-company-climate-risk/SKILL.md) |
 | compare-crc-velo-assessments | [.agents/skills/compare-crc-velo-assessments/SKILL.md](.agents/skills/compare-crc-velo-assessments/SKILL.md) |
 
+## Canonical source and freshness
+
+Follow the selected skill's refresh bootstrap before an assessment. Resolve
+`RiskThinking/crc-docs` once and use its skill, references and scripts from the
+same commit; see [the refresh contract](ai-playbooks/docs/skill-refresh.md).
+Explicit user pins and local development requests take precedence. Never replace
+local edits or claim an installed copy is current without verifying the source.
+
 ## Invoking a skill
 
 Say the skill by name in plain language — e.g. "Use the
@@ -42,5 +50,5 @@ https://raw.githubusercontent.com/RiskThinking/crc-docs/main/.agents/skills/<ski
 For enterprise (VELO/CDT) skills, also connect the CDT Express MCP server at
 `https://mcp.riskthinking.ai/mcp` — see [`.mcp.json`](.mcp.json) and README.md.
 
-See [README.md](README.md) for the full walkthrough, enterprise MCP setup,
-and per-platform discovery notes.
+See [README.md](README.md) for the problem-to-code map and
+[setup](ai-playbooks/docs/setup.md) for enterprise MCP and platform discovery.