@velinussage/locus-agent-skill 0.1.44 → 0.1.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velinussage/locus-agent-skill",
-  "version": "0.1.44",
+  "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.69.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: 5982e0aebc33
+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-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` (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. | 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. |
+| 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. |
 
@@ -206,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.
@@ -391,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 |
 |---|---:|---|---|
@@ -563,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-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.