@velinussage/locus-agent-skill 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velinussage/locus-agent-skill",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Install the Locus agent skill with npx or skills.sh for MCP, free tools, and x402-paid property-context workflows.",
   "type": "module",
   "bin": {

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

@@ -19,11 +19,12 @@ Locus returns awareness and verification steps, not a verdict. Do not score, ran
 
 ## What to remember first
 
-- **23+ national free tools work for geocodable US addresses, with no payment or local coverage check needed.** The live free catalog currently exposes 50 tools total. Use national lanes for rural addresses too, including flood zone, flood gauges, FEMA events, NOAA storms, radon, wildfire risk, cleanup sites, toxic releases, water systems, representatives, governing districts, fair-market rents, opportunity zones, seismic design, unemployment, house-price index context, nearby places, ordinance leads, and data-center/source-discovery prompts.
+- **23+ national free tools work for geocodable US addresses, with no payment or local coverage check needed.** The live free catalog currently exposes 51 tools total. Use national lanes for rural addresses too, including flood zone, flood gauges, FEMA events, NOAA storms, radon, wildfire risk, cleanup sites, toxic releases, water systems, representatives, governing districts, fair-market rents, opportunity zones, seismic design, unemployment, house-price index context, nearby places, ordinance leads, and data-center/source-discovery prompts.
 - **National free tools cover all 50 states for geocodable US addresses.** Local lanes are wired jurisdiction by jurisdiction and are growing. Always expect national context. Treat local parcel, zoning, permit, tax, and development-case depth as coverage-dependent.
 - **Start with `locus_place_facts` when lane availability says it is available.** It is the one-call address bundle for supported parcel areas: parcel facts, FEMA flood zone, governing districts, transportation context, and tax context where wired.
 - **Use `locus_lane_availability` before paid calls.** It maps national, local, varies, not-covered, and degraded lanes, then gives per-paid-tool buy recommendations.
-- **Paid tools currently list at $0.05 to $0.07 USDC per call.** Call the live paid catalog or `locus_lane_availability` for current `priceUsdc`, then read the x402 challenge for exact price, chain, recipient, and schema before payment.
+- **Treat partial trend coverage as a check-first signal.** `supported_partial` trend places appear in `lanes.varies` with low paid substance; buy `locus-local-trend-brief` only when `buyRecommendations[].substanceHere` is `medium` or better. Thin exact-radius results can return a `charged:false` data-sufficiency diagnostic instead of a paid brief.
+- **Paid single-call tools currently list at $0.05 to $0.07 USDC; `locus-place-report-batch` is $0.25 USDC per 10-50 address async job.** Call the live paid catalog or `locus_lane_availability` for current `priceUsdc`, then read the x402 challenge for exact price, chain, recipient, and schema before payment.
 
 ## Quick connect
 
@@ -112,7 +113,12 @@ Trimmed response example for a rural Montana ZIP:
         { "tool": "locus_place_facts", "access": "free", "why": "needs a wired parcel backbone", "requestTool": "locus_request_coverage" }
       ],
       "degraded": [
-        { "tool": "locus_housing_stock", "access": "free", "why": "upstream Census geocoder is failing" }
+        {
+          "tool": "locus_housing_stock",
+          "access": "free",
+          "why": "Temporarily unavailable: the upstream Census geocoder is failing for all points.",
+          "fallbackTools": ["locus_fair_market_rents"]
+        }
       ]
     },
     "buyRecommendations": [
@@ -179,11 +185,11 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | County unemployment trend | `locus_unemployment` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Recent BLS LAUS county unemployment trend. Reported statistic only, not an area-quality label. |
 | State house-price index | `locus_house_price_index` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Latest state-level FHFA All-Transactions House Price Index and year-over-year change via FRED. Not an appraisal or value estimate. |
 | Nearby places and amenities | `locus_nearby_places` | `{ "address": "...", "radiusMeters": 800 }` | OpenStreetMap nearby amenities/places with categories, distance, and OSM provenance. |
-| Data-center or large-development watch prompts | `locus_data_center_watch` | `{ "address": "..." }` or `{ "state": "NC", "county": "Wake County", "municipality": "Raleigh" }` | Bounded official-source query pack and watch leads for large projects, data centers, utility/water/planning sources. |
+| Data-center or large-development watch prompts | `locus_data_center_watch` | `{ "address": "..." }` or `{ "state": "NC", "county": "Wake County", "municipality": "Raleigh" }` | Bounded official-source query pack and lead-discovery prompts for large projects, data centers, utility/water/planning sources. |
 | Local ordinance leads | `locus_ordinance_leads` | `{ "address": "...", "topics": ["short_term_rental", "adu"] }` or `{ "place": "Raleigh, NC" }` | Jurisdiction-locked official-source query pack for ordinance research. Leads only, not legal advice. |
 | Coastal county catalog | `locus_coastal_county_catalog` | `{}` or `{ "county": "new-hanover-nc" }` | Catalog of supported coastal source packs, overlays, source leads, and limitations. |
 
-Temporarily degraded national tools may appear in `lanes.degraded`, such as `locus_regulated_facility_compliance` or `locus_housing_stock`. If degraded, use the suggested fallback from lane availability.
+Temporarily degraded national tools may appear in `lanes.degraded`, such as `locus_housing_stock` when an upstream source is failing for every point. If `locus_regulated_facility_compliance` ever appears there during a future EPA ECHO outage, use `locus_environmental_history` and `locus_toxic_releases` as the functional fallback; otherwise ECHO compliance is a callable national lane.
 
 ### Local or coverage-dependent free tools
 
@@ -196,15 +202,15 @@ Temporarily degraded national tools may appear in `lanes.degraded`, such as `loc
 | Transportation projects and traffic counts | `locus_transportation_context` | `{ "address": "...", "radiusMeters": 2000 }` | State DOT funded projects, traffic-count stations, routes, statuses where wired. |
 | Transit stops and routes | `locus_transit_context` | `{ "address": "...", "radiusMeters": 400 }` | Transit stops, routes, shelter/ADA fields, headways where supported. |
 | Recent nearby parcel transfers | `locus_parcel_transfers` | `{ "address": "...", "radiusMeters": 1500, "monthsBack": 12 }` | Recorded sales/transfers near the point where parcel-sale sources are wired. |
-| Property-tax rates | `locus_property_tax_rates` | `{ "place": "Wake County, NC" }` | Adopted rate components and jurisdiction basis where wired. |
-| Property-tax estimate | `locus_property_tax_estimate` | `{ "address": "..." }` | Estimated annual property tax from assessed value and rates where wired. Not a valuation. |
-| Tax calendar | `locus_tax_calendar` | `{ "county": "Wake" }` | Appeal/payment/revaluation calendar for supported counties. |
+| Property-tax rates | `locus_property_tax_rates` | `{ "place": "Wake County, NC" }` | Adopted rate components and jurisdiction basis where wired. NC only today. |
+| Property-tax estimate | `locus_property_tax_estimate` | `{ "address": "..." }` | Estimated annual property tax from assessed value and NC rates where wired. NC only today; not a valuation. |
+| Tax calendar | `locus_tax_calendar` | `{ "county": "Harris County, TX" }` or `{ "address": "..." }` | State property-tax statutory framework (cited to the state tax code) for NC, TX, CA, FL, NY, plus the official county source pointer and a current-year live-lookup prompt for the volatile per-cycle dates; verified prior-cycle county dates where curated (NC). |
 | Area reported-crime context | `locus_area_incidents` | `{ "address": "...", "radiusMeters": 1000, "lookbackDays": 365 }` | Area-level or citywide reported-incident context where wired, plus caveats. No safety verdict. |
 | Local legislation preview | `locus_local_legislation` | `{ "address": "..." }` | Recent property-relevant legislation preview, status labels, source attribution. Not legal advice. |
 | Dated changes around one place | `locus_ownership_loop` | `{ "address": "...", "radiusMeters": 1500, "state": "NC", "countyFips3": "183", "zip": "27601" }` | Composite dated-change bundle across available ownership, tax, flood, transfer, and local lanes. |
 | Coastal overlays | `locus_coastal_county_overlays` | `{ "address": "..." }` or `{ "latitude": 34.22, "longitude": -77.88, "county": "auto" }` | Coastal hazard overlays, parcel/address facts, zoning/flood/wetland/resiliency context for supported coastal counties. |
 | ACS housing stock | `locus_housing_stock` | `{ "address": "..." }` | Census tract housing units, tenure, median rent/value, year built when upstream is healthy. |
-| EPA facility compliance | `locus_regulated_facility_compliance` | `{ "address": "...", "radiusMeters": 5000 }` | EPA ECHO facility compliance and inspection/enforcement summary when upstream is healthy. |
+| EPA facility compliance | `locus_regulated_facility_compliance` | `{ "address": "...", "radiusMeters": 5000 }` | EPA ECHO facility compliance and inspection/enforcement summary when upstream is healthy. If lane availability lists it as degraded, use the fallback tools instead. |
 
 ## Worked example: address to free tools to answer
 
@@ -270,7 +276,7 @@ Use the argument key from the tool schema. Do not send every place as `place`; m
 ## Paid report rules
 
 - Unsupported or discovery-only places return a free diagnostic, not a payment challenge.
-- Current paid tools list between $0.05 and $0.07 USDC per call. Read `priceUsdc` from `locus_lane_availability` or the paid tool index, then confirm exact cost, network, asset, and recipient from the 402 challenge before payment.
+- Current paid single-call tools list between $0.05 and $0.07 USDC; `locus-place-report-batch` is $0.25 USDC per 10-50 address async job. Read `priceUsdc` from `locus_lane_availability` or the paid tool index, then confirm exact cost, network, asset, and recipient from the 402 challenge before payment.
 - The price, network, asset, and recipient appear before payment.
 - Paid results return only after settlement succeeds.
 - Payment metadata binds to the tool and a canonical hash of arguments, not the raw address.
@@ -278,7 +284,7 @@ Use the argument key from the tool schema. Do not send every place as `place`; m
 
 ## x402 payment flow
 
-The compiled paid tools (`locus-place-report`, `locus-local-trend-brief`, `locus-local-policy-brief`, `locus-before-you-sign`, `locus-environmental-context`) are gated with x402 micropayments in USDC on Base. The flow is identical over REST, MCP, and A2A:
+The compiled paid tools (`locus-place-report`, `locus-place-report-batch`, `locus-local-trend-brief`, `locus-local-policy-brief`, `locus-before-you-sign`, `locus-environmental-context`) are gated with x402 micropayments in USDC on Base. The flow is identical over REST, MCP, and A2A:
 
 1. Call the paid tool without payment: `POST https://api.locus.report/api/<tool-slug>` over REST, `locus_execute` over MCP, or `/a2a/v1/message:send` over A2A. The free `/tools/call` facade is never paid.
 2. A covered place returns **HTTP 402** with `{ "x402Version": 2, "accepts": [{ "scheme": "exact", "network", "maxAmountRequired", "payTo", "asset", "extra": { "assetTransferMethod": "eip3009" } }] }`. Read live values from the challenge.