@velinussage/locus-agent-skill 0.1.43 → 0.1.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velinussage/locus-agent-skill",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "Install the general Locus agent skill, the surrounding-area purchase workflow, and the property-tax protest workflow for free, x402-paid, and MPP/Tempo-paid property context.",
   "type": "module",
   "bin": {

package/skill/locus-agent-tools/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: locus-agent-tools
 preamble-tier: 1
-version: 1.67.0
-description: Use for cited US place records, including parcels, zoning, permits, meetings, budgets, audits, county data series, changes over time, and setting up dynamic MCP event polling or signed webhooks.
+version: 1.70.0
+description: Use for cited US place records, including parcels, zoning, permits, flood, drought and water supply, meetings, budgets, audits, county data series, changes over time, and setting up dynamic MCP event polling or signed webhooks.
 triggers:
   - property due diligence
   - flood zone
+  - drought
+  - groundwater
+  - water restrictions
   - zoning
   - building permits
   - rental registration check
@@ -33,7 +36,7 @@ triggers:
   - real estate webhook notifications
 allowed-tools: Bash Read AskUserQuestion
 license: MIT
-contentHash: 90024d84edff
+contentHash: 78df5529235b
 ---
 
 # Locus Agent Capabilities
@@ -61,12 +64,13 @@ Each recipe below matches a user decision to its minimum inputs, smallest useful
 | Decision / question | Minimum inputs | Smallest useful free call | Coverage limits & what the result establishes | Completeness & stop conditions | Optional paid addition (offer only) |
 |---|---|---|---|---|---|
 | Water service-line material or water incident | Complete CA street address (with unit, city, state, ZIP) or US address / PWSID | `locus_service_line_material` (CA address) or `locus_water_systems` + `locus_water_utility_leak_adjustment_rules` | CA address inventory is opt-in and covers `~34%` of published statewide rows with complete indexable street addresses; `locus_water_systems` gives system-wide EPA SDWIS counts (not this parcel). Establishes utility-reported pipe classification or published leak rules as of the snapshot date, not a physical inspection or liability ruling. | `found`: report system-owned and customer-owned materials separately (`unknown` stays unknown; stop if that answers the question). `source_unavailable` with `incomplete_source_rows` ("this address isn't indexed"): do **not** treat as non-lead; direct the user to ask the utility for its inventory entry. `no_matching_record`: indexed system had no match for this address (still not non-lead). | None for pipe material; for broader site environmental context, offer `locus-environmental-context` ($0.05) only if the user asks. |
+| Drought, well drawdown, streamflow, or water-use restrictions | Address or coordinates for station tools; county FIPS alone works only for `locus_drought_history`; confirmed `pwsid` or address/coordinates for `locus_water_supply_status` (optional `countyFips` attaches a reservoir) | Choose one for the question: multi-year or current county drought -> `locus_drought_history` (`locus_drought_status` only for a quick current read); stream discharge vs seasonal normal -> `locus_streamflow_vs_normal` (flood stage -> `locus_flood_gauges`); daily well-depth change -> `locus_groundwater_drawdown` (well construction/aquifer -> `locus_groundwater_context`); conservation restrictions or reservoir pool -> `locus_water_supply_status` (boil-water or violations -> `locus_boil_water_notices` / `locus_drinking_water_violations`). | USDM weekly history (since 2000) is national and NOAA county PDSI (since 1895) covers the 48 contiguous states (`not_covered` for DC, AK, HI, and territories); USGS streamflow and daily monitoring-well depth (parameter `72019`, positive `changeFeet` = deeper below land surface) are nearby station readings, not the owner's domestic well; state conservation status is wired in NC (`not_covered` elsewhere) and reservoir pool comparison is wired where a USGS lake gauge is registered. | Stop after returning the free preview if one monitoring well and county/streamflow context answer the question. Read `restrictions.status` and the `componentStatus` entry for `reservoir` (`reservoir: null` when `not_covered`) or `usdm` (`weeksAtOrAbove: null` when `unavailable`, never zero). In NC, `restrictions.status: "ok"` with `matched: []` means no matching published state row for that system, not "unrestricted"; quote matched rows with `reportedAt` and treat `serving.match` (`name` or `county_candidate`) as a candidate to confirm on the utility bill. `sameDate.depthClass` compares only within the retrieved window (`comparisonYears`: ~1-2 yrs free preview, ~5 yrs paid); never treat a USGS monitoring well as proof of domestic well yield or potability. | Offer `locus-groundwater-drawdown` ($0.05) only for additional monitoring-well context: up to 3 wells, bounded 1/3/5-year comparisons and wet-season drawdown where readings exist (`null` on shorter daily series; empty daily-well or source-error results return `charged:false`). |
 | Revaluation notice, tax bill, or owning costs | Address or county + state (plus `noticeDate` if appealing) | `locus_tax_calendar` and `locus_appeal_filing_guide`; add `locus_appeal_window` when `noticeDate` is known | Covers all 50 states + DC for statutory framing and official county pointers; `locus_property_tax_estimate` is wired in supported tax-rate jurisdictions. Establishes statutory deadlines, filing body, and adopted rate components, not whether to appeal. | Stop after returning the deadline, filing steps, and free `locus_owner_programs` exemptions if that answers the user's question. If `matched: false` on `locus_appeal_window`, stop deadline arithmetic and hand off to the county pointer in `locus_tax_calendar`. | Offer `locus-assessment-position` ($0.10, `charge_free_unless_substantive` on 5+ same-roll peers), `locus-owner-action-brief` ($0.05), or `locus-owner-cost-review` ($0.25) if the user wants roll uniformity or recorded tax history. |
 | Mortgage or property-tax payment hardship | Address, point, or 2-letter state | `locus_housing_counselors` (mortgage/general) and `locus_foreclosure_process_pointers` (state) | National HUD directory lookup; 50-state + DC foreclosure pointer registry (`verified` in checked states, `not_verified` portal-only elsewhere). Establishes nearby directory agencies (`sourceStatusCode` is raw HUD `agc_STATUS`, not verified current approval) and state process pointers, not a sale countdown or legal advice. | If `no_agencies_in_radius`, widen the bounded search or give HUD's directory URL. If `locus_foreclosure_process_pointers` is `not_verified`, stop at the official court/housing portal and state that no statute was verified. Never invent a deadline when none is supplied. | None. Keep hardship routing free. |
-| Homeowners insurance nonrenewal or escrow shock | 2-letter state or address (plus notice/end dates or escrow letter figures) | `locus_insurance_nonrenewal_pointers` (nonrenewal) or `locus_homeowners_insurance_context` + `locus_owner_mortgage_calendar` (escrow) | 50-state + DC department portals (`verified` notice rules in 10 states; `complaintStatus: "verified"` where a direct complaint URL is checked, `"unresolved"` where portal-only). `fioZip` is 2018-2022 historical area context, not a quote or current rate. | If `notice.status: "not_verified"`, stop rule comparison and point to the state regulator portal. If `complaintStatus: "unresolved"`, state that the direct complaint handoff is unresolved and give `portalUrl`. For escrow shock without the servicer's letter, stop arithmetic until the user has the letter's figures. | Offer `locus-assessment-position` ($0.10) or `locus-property-tax` ($0.05) only if the tax component of an escrow increase needs parcel-roll detail. |
+| Homeowners insurance nonrenewal or escrow shock | 2-letter state or address (plus notice/end dates or escrow letter figures) | `locus_insurance_nonrenewal_pointers` (nonrenewal) or `locus_homeowners_insurance_context` + `locus_owner_mortgage_calendar` (escrow) | 50-state + DC department portals (`verified` notice rules in 10 states; `complaintStatus: "verified"` where a direct complaint URL is checked, `"unresolved"` where portal-only). `fioZip` is 2018-2022 historical area context, not a quote or current rate. | If `notice.status: "not_verified"`, stop rule comparison and point to the state regulator portal. If `complaintStatus: "unresolved"`, state that the direct complaint handoff is unresolved and give `portalUrl`. For escrow shock without the servicer's letter, stop arithmetic until the user has the letter's figures. | Offer `locus-escrow-insurance-dossier` ($0.89), `locus-assessment-position` ($0.10), or `locus-property-tax` ($0.05). Responses also attach caller-paid x402 `handoffs[]`: `insurance_market.querylines` ($0.10 state NAIC carrier market share / SERFF rate activity) and, on `locus_mitigation_incentives`, `trade_contractors.locationlists` ($0.02 nearby certified roofers/installers). |
 | Inherited home or estate property pointers | 2-letter state or city + state / address | `locus_estate_property_pointers` (state rules) and `locus_tax_payment_status` / `locus_tax_calendar` (what is due) | 50-state + DC registry (`verified` in 34 jurisdictions, `not_verified` court portal elsewhere) plus ULC enactment tables (UPHPA, UPOAA, URPTODA). `smallEstate.thresholdScope: "non_exhaustive_excerpt"` marks statutory dollar excerpts that may have conditional branches (such as Ohio's `$35,000` general and `$100,000` surviving-spouse branches). | Treat `thresholdText` as a non-exhaustive excerpt and read the linked statute before ruling an estate in or out. If `transferOnDeathDeed` or `smallEstate` is `not_verified`, stop statutory claims and give the court self-help portal. If `locus_tax_payment_status` is `out_of_coverage` or `unavailable`, report that gap rather than "nothing due." | None required; if preparing to list the property later, see `locus-seller-readiness`. |
-| Contractor license check before hiring | 2-letter `state` and exact `licenseNumber` | `locus_contractor_license_check` | Currently wired in Washington (WA L&I roster). Returns published license status, type, effective/expiration dates, and citation without person names or addresses. | `found`: report the published status and dates. `no_matching_record`: stop and tell the user to verify spelling/number on the state board portal (a miss is not proof of being unlicensed). `out_of_coverage` or `source_unavailable`: report the coverage or snapshot gap and stop. | None. |
-| Buying a property | Exact street address | `locus_lane_availability`, then `locus_place_facts`, `locus_zoning`, `locus_flood_zone`, `locus_parcel_transfers`, `locus_development_cases` | National hazard/environmental lanes cover all 50 states; parcel, zoning, permit, and transfer depth depend on wired county sources. Establishes recorded parcel attributes, district rules, and nearby filings without picking a winner or valuing the home. | Stop on any lane marked `notCovered` in `locus_lane_availability` and name the gap. If parcel identity is unresolved, confirm the house number before interpreting parcel or permit rows. | Offer `locus-before-you-sign` ($0.07), `locus-property-update` ($0.10), or `locus-place-report` ($0.05) as priced options with what each adds. |
+| Contractor license check before hiring | 2-letter `state` and exact `licenseNumber` (or coordinates/ZIP for partner directory discovery first) | `locus_contractor_license_check` | Currently wired in Washington (WA L&I roster). Returns published license status, type, effective/expiration dates, and citation without person names or addresses. | `found`: report the published status and dates. `no_matching_record`: stop and tell the user to verify spelling/number on the state board portal (a miss is not proof of being unlicensed). `out_of_coverage` or `source_unavailable`: report the coverage or snapshot gap and stop. | None in Locus. When the user first needs nearby trade leads, `locus_mitigation_incentives` and `locus_permit_rules` attach the caller-paid `trade_contractors.locationlists` x402 handoff ($0.02 at `POST https://locationlists.com/api/x402/query`); always verify state licensure next via `locus_contractor_license_check` or the state board. |
+| Buying a property | Exact street address | `locus_lane_availability`, then `locus_place_facts`, `locus_zoning`, `locus_flood_zone`, `locus_parcel_transfers`, `locus_development_cases` | National hazard/environmental lanes cover all 50 states; parcel, zoning, permit, and transfer depth depend on wired county sources. Establishes recorded parcel attributes, district rules, and nearby filings without picking a winner or valuing the home. | Stop on any lane marked `notCovered` in `locus_lane_availability` and name the gap. If parcel identity is unresolved, confirm the house number before interpreting parcel or permit rows. On a private well, add `locus_groundwater_context` and `locus_groundwater_drawdown` (area context, not the owner's well). | Offer `locus-before-you-sign` ($0.07), `locus-property-update` ($0.10), or `locus-place-report` ($0.05) as priced options with what each adds. |
 | Renting or checking rental registration | Exact building address | `locus_rental_registration_check`, `locus_flood_zone`, `locus_area_incidents` | Registration is wired in Minneapolis, Montgomery County, NYC, Seattle (long-term), Denver (STR license), and Kansas City (building enforcement only). | Read `recordScope` first: in Kansas City, stop before claiming whether a rental registration exists. A `no_matching_record` is not proof of legal permission or non-compliance. | Offer `locus-local-trend-brief` ($0.05) or `locus-rental-operations-brief` ($0.79) only if the user asks for trend or rent-median comparison. |
 | Leasing, lending, or commercial CMBS diligence | Exact commercial address (or county FIPS for maturity wall) | `locus_parcel_lookup`, `locus_zoning`, `locus_metro_permits`, `locus_development_cases` | Public CMBS filings cover SEC ABS-EE conduit/SASB trusts, not bank balance-sheet or agency loans. | If a CMBS or workplace lookup returns `no_matching_record`, `not_loaded`, or `out_of_coverage`, stop and report that public SEC filings did not match (never "no debt exists"). | Offer `locus-cmbs-loan-context` ($0.10), `locus-cmbs-maturity-wall` ($0.10), or `locus-workplace-employment-context` ($0.01) with exact price and scope. |
 
@@ -135,7 +139,7 @@ The live HTTP 402 payment challenge on native and dual-rail REST endpoints offer
 
 - **x402 (`PAYMENT-REQUIRED` / JSON `accepts[]`):** **Base USDC** (`eip155:8453`, `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) and **Solana USDC** (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`).
 - **MPP (`WWW-Authenticate: Payment ..., method="tempo", intent="charge"`):** **Tempo mainnet USDC.e** (`eip155:4217`, `chainId: 4217`, currency `0x20C000000000000000000000b9537d11c60E8b50`), a separate payment protocol. Base is not required when your wallet holds Tempo mainnet `USDC.e` and can answer the MPP Tempo challenge.
-- **Stripe MPP (`WWW-Authenticate: Payment ..., method="stripe", intent="charge"`, `>= $0.50` deliverables):** advertised alongside Tempo on MPP-enabled deliverables priced at or above Stripe's `$0.50` card minimum (`locus-property-tax-protest-packet` at `$0.89`, `locus-before-you-sign-dossier` at `$1.19`, `locus-escrow-insurance-dossier` at `$0.89`, and `locus-seller-readiness-packet` at `$0.85`) when Stripe MPP is configured. Link CLI / Stripe Shared Payment Token (`spt_...`) callers can settle these bundled JSON + printable HTML/PDF packets in a single challenge while micropayments (`$0.01-$0.35`) stay on Tempo MPP and Base/Solana x402.
+- **Stripe MPP (`WWW-Authenticate: Payment ..., method="stripe", intent="charge"`, `>= $0.50` deliverables on REST):** advertised alongside Tempo on MPP-enabled REST deliverables priced at or above Stripe's `$0.50` card minimum (`locus-property-tax-protest-packet` at `$0.89`, `locus-before-you-sign-dossier` at `$1.19`, `locus-escrow-insurance-dossier` at `$0.89`, and `locus-seller-readiness-packet` at `$0.85`) when Stripe MPP is configured. Link CLI / Stripe Shared Payment Token (`spt_...`) callers can settle these bundled JSON + printable HTML/PDF packets in a single challenge while sub-`$0.50` MPP-enabled tools (`$0.01-$0.49`) offer Tempo MPP and Base/Solana x402. MPP challenges (`tempo` and `stripe`) are served on direct HTTP REST (`POST /api/<tool-slug>`); MCP paid execution uses x402 (`_meta["x402/payment"]`).
 
 AgentCash is one compatible x402 and MPP client. It creates a local payer wallet and can install its MCP server into common agent clients. Locus issues no buyer API key.
 
@@ -182,6 +186,20 @@ For broad requests, start with the current bundles in the top-agent manifest. Fo
 
 The live catalogs are authoritative for tool names, schemas, prices, and endpoints. Do not copy stale tool definitions into prompts.
 
+### Caller-paid x402 partner handoffs (`handoffs[]`)
+
+Selected Locus free and paid responses include an optional `handoffs[]` array of caller-paid third-party x402 endpoints that complement Locus's public-record context. Every entry carries `id`, `category`, `provider`, `endpoint`, `method`, `payment: { protocol: "x402", priceUsd, priceNote }`, `prefilledInput`, `whenToUse`, `verified`, and `disclaimer: "Locus does not call or pay this partner; prices and availability may change."`
+
+- **State homeowners-insurance market data (`insurance_market.querylines`, `$0.10` x402 on Base):** attached to `locus_insurance_nonrenewal_pointers`, `locus_homeowners_insurance_context`, `locus-insurance-context`, and `locus-escrow-insurance-dossier` whenever a 2-letter state resolves.
+  - **Default prefilled route:** `GET https://api.querylines.com/v1/carriers?state=<ST>&line=homeowners` (`$0.10` USDC on `eip155:8453`), returning NAIC state market share, Direct Premiums Written (DPW) YoY change, and direct loss ratio for the top 10 homeowners carriers in that state.
+  - **Companion QueryLines routes (same origin `https://api.querylines.com`, read `https://querylines.com/llms.txt`):** `GET /v1/rates/activity?states=<ST>&line=homeowners&granularity=year` (`$0.10` SERFF rate filing counts, average requested vs. approved rate change, and approval disposition), `GET /v1/solvency?state=<ST>` (`$0.15` carrier RBC and leverage ratios), and `GET /v1/citizens/pif` (`$0.10` Florida Citizens policies-in-force exposure trend).
+  - **Boundary:** State-level regulatory market context only. Never treat carrier market share, loss ratios, or SERFF filing activity as a policy quote, a carrier recommendation, or a reason this specific parcel was nonrenewed.
+- **Nearby trade-contractor directory lookup (`trade_contractors.locationlists`, `$0.02` x402 on Base):** attached to `locus_mitigation_incentives`, `locus_permit_rules`, `locus-permit-closeout-check`, `locus-renovation-site-context`, and `locus-seller-readiness-packet` when coordinates or a 5-digit ZIP resolve.
+  - **Prefilled route:** `POST https://locationlists.com/api/x402/query` (`$0.02` USDC on `eip155:8453` for `limit: 1..25`, `$0.001/record` above 25) with `prefilledInput` set to `{ "dataset": "roofing-contractor-list", "near": { "lat": <lat>, "lng": <lng>, "radius_miles": 10 }, "limit": 2 }` (or `"near": { "zip": "<ZIP5>", "radius_miles": 10 }`). Also accepts `"hvac-installer-list"` and `"solar-installer-list"`, or `"near": { "place": "City, ST", "radius_miles": 10 }`.
+  - **Client call notes:** Call `POST https://locationlists.com/api/x402/query` directly with `npx agentcash@latest fetch https://locationlists.com/api/x402/query -m POST -p x402 --payment-network base --max-amount 0.05 -b '...'`. Do **not** run `agentcash check` on LocationLists (its `/openapi.json` has an unresolved `#/components/schemas/ErrorResponse` `$ref`), and do **not** use its free `GET /api/x402/locations/find` preview (which returns unfiltered nationwide rows when `state` is omitted).
+  - **Two-step contractor verification rule:** LocationLists returns manufacturer-certified commercial directory listings (`id: "oc:..."`, business name, address, phone, website, rating, and distance), **not** state government licensing records. Always verify state contractor licensure, bond, and disciplinary status next using Locus's free `locus_contractor_license_check` (where wired, e.g., WA L&I) or the state contractor licensing board before hiring. Never pass contractor names, phone numbers, or person fields from a partner response back into Locus tools.
+- **Other domain handoffs:** `skip_trace.batchdata` and `skip_trace.Trestle` (on `locus_tax_distress` / `locus-tax-liens`), `title_chain.FirstAmerican` (on `locus_parcel_transfers`), `environmental_phase1.EDR` (on `locus_cleanup_sites` / `locus-environmental-context`), `appraisal.HouseCanary` (on `locus-comps-brief` / `locus-valuation-challenge`), and `legal_review.RocketLawyer` (on `locus-before-you-sign` / `locus-local-policy-brief`). Always present any handoff as an optional caller-paid next step and ask for explicit user approval before spending.
+
 ## Surrounding-area orchestration route
 
 This route is rollout-gated. Call it only when `locus-surrounding-area-analysis` appears in the live paid index at `/.well-known/ai-tool/index.json`; when absent, use the free `locus_surrounding_parcels` primitive plus the individual lanes instead of assuming the $0.10/$0.15 workflow exists.
@@ -192,7 +210,7 @@ For mortgage or property-tax payment trouble, load the bundled `locus-payment-ha
 
 ## Workflow and coverage tools, know the difference
 
-- **`locus_suggest_workflow { "place": "...", "intent": "homebuyer_due_diligence" }`** is the free deterministic planner. It returns a ranked endpoint plan with reasons, estimated costs, free/paid rail, national/local scope, and place availability. Use it first when the intent is broad or the right endpoint is unclear. It accepts the established buyer, renter, business, civic, commercial-tenant, land-investor, developer, environmental, short-term-rental, data-center, agricultural-land, HOA, and renovation-planning intents. It also accepts `property_owner_cost_relief`, `property_tax_appeal`, `utility_bill_relief`, `mortgage_servicing`, `disaster_recovery`, `permit_project_closeout`, `tax_delinquency_redemption`, `government_meeting_monitoring`, `local_fiscal_research`, and `county_data_research`. Natural-language requests such as `finish a basement`, `lower my property taxes`, `review my PMI dates`, or `check permit closeout` are normalized. These planner lanes route tools only; they do not widen the four safety-versioned paid brief claim intents or make eligibility, legal, savings, compliance, occupancy, or renovation-feasibility conclusions.
+- **`locus_suggest_workflow { "place": "...", "intent": "homebuyer_due_diligence" }`** is the free deterministic planner. It returns a ranked endpoint plan with reasons, estimated costs, free/paid rail, national/local scope, and place availability. Use it first when the intent is broad or the right endpoint is unclear. It accepts the established buyer, renter, business, civic, commercial-tenant, land-investor, developer, environmental, short-term-rental, data-center, agricultural-land, HOA, and renovation-planning intents. It also accepts `drought_water_supply`, `property_owner_cost_relief`, `property_tax_appeal`, `utility_bill_relief`, `mortgage_servicing`, `disaster_recovery`, `permit_project_closeout`, `tax_delinquency_redemption`, `government_meeting_monitoring`, `local_fiscal_research`, and `county_data_research`. Phrases such as drought, dry well, groundwater, drawdown, streamflow, reservoir or lake level, and water or watering restrictions normalize to `drought_water_supply` (while groundwater contamination, plume, PFAS, or cleanup phrases route to `environmental_research`). Natural-language requests such as `finish a basement`, `lower my property taxes`, `review my PMI dates`, or `check permit closeout` are normalized. These planner lanes route tools only; they do not widen the four safety-versioned paid brief claim intents or make eligibility, legal, savings, compliance, occupancy, or renovation-feasibility conclusions.
 - **`locus_coverage_check { "place": "..." }`** asks whether Locus has source coverage for a jurisdiction at all. Use it for a broad city, county, ZIP, or address scope check.
 - **`locus_lane_availability { "place": "..." }`** is the per-address capability map. It returns which exact tools are national, local, varies, not covered, or degraded, plus buy signals for paid tools. Call this before address-specific local lanes and before paying.
 - **`locus_coverage_map {}`** returns the whole registry view. Use it when an agent needs breadth, not one address.
@@ -377,7 +395,7 @@ Full inventory decisions: `docs/PAID_TOOL_INVENTORY.md`. Paid index entries also
 
 Use these only after `locus_lane_availability` or the paid index says the call has substance for the exact place. The live paid index is authoritative for current prices and schemas.
 
-Dual-rail routes (a paid `/api/locus-<tool>` with a free `locus_<tool>` counterpart) return the same records as the free route. Paying adds a settled x402 receipt, higher rate limits, and catalog discovery; catalog rows mark this with `paidAdds: ["receipt", "rate_limit", "discovery"]`. Use the free route when you do not need a receipt.
+Dual-rail routes (a paid `/api/locus-<tool>` with a free `locus_<tool>` counterpart) return the same records as the free route when `paidAdds: ["receipt", "rate_limit", "discovery"]` is present; use the free route when you do not need a receipt. Exception: promoted routes without `paidAdds` (such as `locus-groundwater-drawdown`) expand a narrower free preview; read each entry's description.
 
 | Endpoint | Price | Use when | Free diagnostic behavior |
 |---|---:|---|---|
@@ -549,6 +567,10 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | State foreclosure process pointers | `locus_foreclosure_process_pointers` | `{ "state": "WA" }` | Verified statute/process and official mediation pointers where checked; otherwise a not_verified court portal only. No time-remaining, legal advice or foreclosure prediction. |
 | Owner mortgage calendar | `locus_owner_mortgage_calendar` | `{ "originationDate": "2026-01-01", "originalValueUsd": 500000, "originalLoanAmountUsd": 450000, "annualRatePercent": 6, "loanType": "conventional", "forcePlacedNoticeDate": "2026-09-01" }` | Twelve cited statute and agency fact cards plus dates computed only from caller inputs. Not legal advice, qualification, approval odds, value opinion, or a recommendation. |
 | Current drought status and recent history | `locus_drought_status` | `{ "address": "...", "weeks": 8 }` | Weekly US Drought Monitor county percentages by D0-D4 category plus recent weeks. County-level drought mapping does not establish parcel water supply, well yield, current utility restrictions, or a forecast. |
+| County drought history | `locus_drought_history` | `{ "countyFips": "37037" }` or `{ "latitude": 35.72, "longitude": -79.18 }` | Weekly US Drought Monitor series since 2000: weeks at each D level, worst D2-or-worse episodes, this week's rank among the same calendar week, plus NOAA county PDSI since 1895 for the 48 contiguous states (CONUS; `not_covered` for DC, AK, HI, and territories while USDM stays independent). Credit NDMC/USDA/NOAA. Not a parcel water supply or forecast. |
+| Streamflow versus normal | `locus_streamflow_vs_normal` | `{ "latitude": 35.72, "longitude": -79.18, "radiusMeters": 25000 }` | Nearest 1-3 USGS gauges, latest discharge versus approved day-of-year percentiles, and a class down to `record_low_for_date`. Provisional instantaneous values are labeled and are not the daily mean. |
+| Groundwater drawdown preview | `locus_groundwater_drawdown` | `{ "latitude": 35.72, "longitude": -79.18, "radiusMeters": 40000 }` | Nearest daily USGS monitoring well (parameter 72019): depth below land surface versus the same calendar dates (`sameDate.comparisonYears` and `sampleCount`) and the one-year change. Positive `changeFeet` means deeper water below land surface; if `pageLimited` is true, the sample or nearest candidate is bounded. A monitoring well is not the owner's well. No qualifying well falls back to discrete `locus_groundwater_context` readings. The paid `locus-groundwater-drawdown` route ($0.05) adds up to three wells and bounded 3- and 5-year change (`null` on shorter series), and does not charge when no daily well qualifies. |
+| Water supply and restrictions | `locus_water_supply_status` | `{ "address": "Pittsboro, NC" }` or `{ "pwsid": "NC0319015", "countyFips": "37037" }` | Candidate EPA SDWIS system, state conservation status where wired (North Carolina from NC DWR; other states return `not_covered`, and an empty `restrictions.matched` in NC means no matching state row rather than unrestricted), and USGS reservoir elevation versus normal pool where a gauge is registered (`reservoir: null` when `componentStatus` is `not_covered`). County or name candidate matching is not proof of service. |
 | HUD fair-market rents | `locus_fair_market_rents` | `{ "stateFips": "30", "countyFips3": "067", "year": 2026 }` | HUD FMR values by bedroom count and county/FIPS basis. |
 | Qualified Opportunity Zone | `locus_opportunity_zone` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Whether the point is in a Treasury/IRS Qualified Opportunity Zone tract, cited to HUD. A `not_designated` zero-hit is a valid designation answer, not a coverage failure. Not tax or investment advice. |
 | Address sales-tax rate | `locus_address_sales_tax` | `{ "address": "123 Pike St, Seattle, WA 98101" }` | Washington and California state revenue agency address-level rates only. Other states return `out_of_coverage`; unresolved addresses return `unavailable`. Confirm the effective date and taxable sale with the state; not tax advice. |

package/skill/locus-escrow-shock/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: locus-escrow-shock
 preamble-tier: 1
-version: 1.1.0
+version: 1.2.0
 description: Use when an owner, or their agent, asks why their mortgage payment or escrow went up and what they can do, and has the servicer's escrow analysis letter. Splits the change into its tax and insurance parts and routes each part to cited Locus records, dated windows and choices.
 triggers:
   - my mortgage payment went up
@@ -124,6 +124,20 @@ they do. Do not collect the loan number, account numbers, names or phone numbers
     self-contained printable HTML/PDF + JSON dossier combining the tax-track and insurance-track
     records in one settlement, offer `locus-escrow-insurance-dossier` (`$0.89`, eligible for
     Stripe MPP `method="stripe"`, Tempo MPP `method="tempo"`, and Base/Solana x402).
+16. **Optional caller-paid partner x402 handoffs (`handoffs[]`, offer only after user approval):**
+    - `insurance_market.querylines` (`$0.10` x402 on Base, returned on `locus_homeowners_insurance_context`,
+      `locus-insurance-context`, and `locus-escrow-insurance-dossier`):
+      `GET https://api.querylines.com/v1/carriers?state=<ST>&line=homeowners` for NAIC state carrier
+      market share, Direct Premiums Written (DPW) YoY change, and direct loss ratio (or
+      `/v1/rates/activity?states=<ST>&line=homeowners&granularity=year` at `$0.10` for SERFF rate
+      filings). Present as state-level market context, never as a carrier recommendation or quote.
+    - `trade_contractors.locationlists` (`$0.02` x402 on Base, returned on `locus_mitigation_incentives`):
+      `POST https://locationlists.com/api/x402/query` (`dataset: "roofing-contractor-list"`,
+      `near: { lat, lng, radius_miles: 10 }`) for nearby manufacturer-certified roofing/HVAC/solar
+      directory leads when the owner wants quotes on mitigation work that qualifies for cited
+      insurance discounts. Always verify state contractor licensure next via
+      `locus_contractor_license_check` or the state licensing board, and never pass partner contact
+      fields into Locus tools.
 
 ## Never
 

package/skill/locus-insurance-nonrenewal/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: locus-insurance-nonrenewal
 preamble-tier: 1
-version: 1.1.0
+version: 1.2.0
 description: Use when a US homeowner says their homeowners insurer will not renew, or is dropping, their policy and wants to know the state notice rule, the insurer of last resort, the complaint route, mitigation credits, flood exposure and the dates that matter before the policy lapses, from cited Locus records.
 triggers:
   - my insurer won't renew my policy
@@ -116,5 +116,20 @@ End with a short dated list of the owner's choices, for example:
   credits, assessment position, and RESPA escrow rules in a single settlement, offer
   `locus-escrow-insurance-dossier` (`$0.89`, eligible for Stripe MPP `method="stripe"`, Tempo MPP
   `method="tempo"`, and Base/Solana x402).
+- **Optional caller-paid partner x402 handoffs (`handoffs[]`, offer only after user approval):**
+  - `insurance_market.querylines` (`$0.10` x402 on Base, returned on `locus_insurance_nonrenewal_pointers`,
+    `locus_homeowners_insurance_context`, `locus-insurance-context`, and `locus-escrow-insurance-dossier`):
+    `GET https://api.querylines.com/v1/carriers?state=<ST>&line=homeowners` for NAIC state market
+    share, Direct Premiums Written (DPW) YoY change, and direct loss ratio of top carriers in the
+    state (or `/v1/rates/activity?states=<ST>&line=homeowners&granularity=year` at `$0.10` for SERFF
+    rate filing momentum, and `/v1/citizens/pif` at `$0.10` for Florida Citizens policy counts).
+    Present as state-level market context, never as a carrier recommendation or policy quote.
+  - `trade_contractors.locationlists` (`$0.02` x402 on Base, returned on `locus_mitigation_incentives`):
+    `POST https://locationlists.com/api/x402/query` with `prefilledInput` (`dataset: "roofing-contractor-list"`,
+    `near: { lat, lng, radius_miles: 10 }`) when the owner wants nearby manufacturer-certified
+    roofing, HVAC, or solar contractors to bid on wind/mitigation upgrades. Always treat returned
+    businesses as commercial directory leads and verify state licensure next via
+    `locus_contractor_license_check` or the state licensing board. Never pass partner contact fields
+    into Locus tools.
 
 Every statement traces to a Locus citation or to a date the owner gave you.

package/skill/locus-seller-readiness/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: locus-seller-readiness
 preamble-tier: 1
-version: 1.2.0
+version: 1.3.0
 description: Use when an owner who plans to sell one US property, or their agent, wants a pre-listing check of disclosure law, open permits, code cases, flood status, district levies and closing-tax arithmetic from cited Locus records.
 triggers:
   - getting ready to sell my house
@@ -53,6 +53,15 @@ narratives about past tenants.
    parcel: permit status and the final or closeout fields the source publishes. Report open or
    expired permits as record facts with their dates and permit numbers. Whether old work was
    permitted is a question for the permit office, not a Locus finding.
+   - **Optional caller-paid partner handoff (`trade_contractors.locationlists`, `$0.02` x402 on Base):**
+     `locus_permit_rules`, `locus-permit-closeout-check`, and `locus-seller-readiness-packet`
+     attach a `handoffs[]` entry for `POST https://locationlists.com/api/x402/query` (`prefilledInput`
+     with `dataset: "roofing-contractor-list"` and `near: { lat, lng, radius_miles: 10 }` or `zip`).
+     Offer it only if the seller asks for nearby trade contractors to inspect, repair, or close out
+     an open roof, HVAC, or solar permit item. Always treat LocationLists rows as commercial
+     directory leads (`oc:...`), verify state licensure next via `locus_contractor_license_check`
+     (where covered) or the state licensing board, and never pass partner contact fields back into
+     Locus tools.
 
 ## 3. Code cases (free)
 

package/skill/locus-water-incident/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: locus-water-incident
 preamble-tier: 1
-version: 1.2.0
+version: 1.2.1
 description: Use when an owner or their agent is dealing with a water main break, a leak, a high water bill or a failed service line at one US address and needs to know who maintains which pipe, the utility's published leak rules, what to document and what to ask the insurer.
 triggers:
   - water main break
@@ -23,6 +23,16 @@ credited and what is covered. Never say "the utility is liable", "you are covere
 covered" or "you qualify for a credit". State what the published record says, with its source
 and date, and give the question to ask.
 
+> **Scope note (drought, well drawdown, or water-conservation restrictions):** This workflow is for
+> physical pipe failures, leaks, high bills, and acute boil-water notices. When the question is about
+> **drought severity, river streamflow, well-water drawdown, reservoir pool elevation, or
+> water-conservation / shortage restrictions**, choose the matching tool (`locus_drought_history`,
+> `locus_streamflow_vs_normal`, `locus_groundwater_drawdown` or paid `locus-groundwater-drawdown` at
+> $0.05, or `locus_water_supply_status`) under "Drought, well drawdown, streamflow, or water-use
+> restrictions" in `locus-agent-tools`. Live conservation restriction status is NC-only (other states
+> return `not_covered`, which is not "no restrictions"), and a private well that stopped producing is a
+> well-contractor question (USGS wells are area context, not the owner's well).
+
 **How to speak:** follow "How to speak with owners, sellers and buyers" in the `locus-agent-tools`
 skill (https://api.locus.report/.well-known/skill.md), including its 988 crisis guard.