@velinussage/locus-agent-skill 0.1.5 → 0.1.7

package/README.md

@@ -65,10 +65,27 @@ npx skills use velinussage/locus-agent-skill --skill locus-agent-tools
 
 ## What the skill teaches agents
 
-- 23+ national free tools work for geocodable US addresses, with 50 free tools total in the live catalog.
+- 23+ national free tools work for geocodable US addresses, with 51 free tools total in the live catalog.
 - `locus_place_facts` is the best first call when supported.
 - `locus_lane_availability` shows national, local, varies, not-covered, and degraded lanes before payment.
 - Free tools stay read-only and cited.
-- Paid tools use x402 and require explicit user authorization.
+- Seven paid endpoints use x402 and require explicit user authorization: place report, 10-50 address batch, trend brief, policy brief, before-you-sign bundle, environmental context, and residential property tax.
 
 Docs: <https://docs.locus.report/skill.md>
+
+
+## Paid endpoint surface
+
+The live paid index is authoritative: <https://api.locus.report/.well-known/ai-tool/index.json>. Current endpoints are:
+
+| Endpoint | Current price | Notes |
+|---|---:|---|
+| `POST /api/locus-place-report` | `$0.05` | Compiled cited property-context artifact. |
+| `POST /api/locus-place-report-batch` | `$0.25` | Async 10-50 address portfolio job, one settlement. |
+| `POST /api/locus-local-trend-brief` | `$0.05` | Permit, 311, and code-case local-change brief where source coverage is strong enough. |
+| `POST /api/locus-local-policy-brief` | `$0.07` | Property-relevant bills, agendas, ordinances, tax, fee, bond, housing, and permit-change context. |
+| `POST /api/locus-before-you-sign` | `$0.07` | Pre-decision bundle over parcel, trend, and policy components. |
+| `POST /api/locus-environmental-context` | `$0.05` | Address-level EPA TRI/RCRA/SDWIS/radon context ranked by distance where possible. |
+| `POST /api/locus-property-tax` | `$0.49` | Residential property-tax artifact with assessed value, annual tax, history, effective rate, and provenance. |
+
+Unsupported, discovery-only, commercial, or insufficient-data cases return free diagnostics instead of charging where applicable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velinussage/locus-agent-skill",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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

@@ -1,7 +1,7 @@
 ---
 name: locus-agent-tools
 preamble-tier: 1
-version: 1.3.0
+version: 1.3.1
 description: Use when an agent needs to connect to Locus over MCP, A2A, or REST for property and local-government context.
 triggers:
   - locus agent tools
@@ -24,7 +24,7 @@ Locus returns awareness and verification steps, not a verdict. Do not score, ran
 - **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.
 - **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.
+- **Most paid single-call tools list at $0.05 to $0.07 USDC; `locus-property-tax` is $0.49 USDC because it uses a paid residential tax upstream, and `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,14 +112,7 @@ Trimmed response example for a rural Montana ZIP:
       "notCovered": [
         { "tool": "locus_place_facts", "access": "free", "why": "needs a wired parcel backbone", "requestTool": "locus_request_coverage" }
       ],
-      "degraded": [
-        {
-          "tool": "locus_housing_stock",
-          "access": "free",
-          "why": "Temporarily unavailable: the upstream Census geocoder is failing for all points.",
-          "fallbackTools": ["locus_fair_market_rents"]
-        }
-      ]
+      "degraded": []
     },
     "buyRecommendations": [
       { "slug": "locus-place-report", "priceUsdc": "0.05", "substanceHere": "low", "rationale": "Coverage varies. Confirm the free component lanes first." },
@@ -151,6 +144,20 @@ Use the exact JSON shapes below as safe defaults. If a tool also accepts `latitu
 | What policy sources govern here? | `locus_policy_sources` | `{ "place": "Raleigh, NC" }` | State, county, city policy-source list, legal geographies, source links. |
 | Read aggregate coverage demand | `locus_coverage_demand` | `{}` | Aggregate requested-coverage demand, not place records. |
 
+### Paid tools by endpoint
+
+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.
+
+| Endpoint | Price | Use when | Free diagnostic behavior |
+|---|---:|---|---|
+| `POST /api/locus-place-report` | `$0.05` | Agent needs one compiled cited property-context artifact for an address or ZIP. | Unsupported or discovery-only places return no-charge diagnostics. |
+| `POST /api/locus-place-report-batch` | `$0.25` | Agent has a 10-50 address portfolio and wants one async job plus one settlement. | If all items are unsupported or discovery-only, no charge. Unsupported items inside a paid job remain item-level diagnostics. |
+| `POST /api/locus-local-trend-brief` | `$0.05` | Agent needs permit, 311, or code-case local-change series where the registry has enough source coverage. | Unsupported, discovery-only, or insufficient-data places return `charged:false` diagnostics. |
+| `POST /api/locus-local-policy-brief` | `$0.07` | Agent needs property-relevant bills, agendas, ordinances, tax, fee, bond, housing, or permit-change policy context. | Unsupported places return no-charge diagnostics. |
+| `POST /api/locus-before-you-sign` | `$0.07` | Agent needs a pre-decision bundle over parcel, trend, and policy components for one street address. | Weak component readiness returns no-charge component diagnostics. |
+| `POST /api/locus-environmental-context` | `$0.05` | Agent needs address-level EPA TRI/RCRA/SDWIS/radon public-record context ranked by distance where possible. | Unsupported or unresolvable inputs return no-charge diagnostics. |
+| `POST /api/locus-property-tax` | `$0.49` | Agent needs a residential US property-tax artifact with assessed value, annual tax, tax history, effective rate, and provenance. | Commercial, uncovered, or unresolvable addresses return `charged:false` diagnostics pointing to the free `.gov` tax lanes or place report. |
+
 ### Best first call for supported address context
 
 | The question | Tool | Exact arguments | What it returns |
@@ -170,7 +177,7 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | Governing districts | `locus_governing_districts` | `{ "address": "..." }` | Congressional, state senate, state house, county, municipality, and other governing geographies when resolved. |
 | Representatives | `locus_representatives` | `{ "address": "..." }` | Cited federal and state officials for the address, districts, party/office/contact links where available. |
 | Wildfire risk | `locus_wildfire_risk` | `{ "address": "..." }` | FEMA NRI tract-level wildfire rating, score, expected annual loss fields where returned, provenance, caveats. |
-| Environmental history bundle | `locus_environmental_history` | `{ "address": "..." }` or `{ "state": "MT", "county": "Park County" }` | EPA TRI, RCRA, SDWIS water systems, radon zone, and event-history verify links. |
+| Environmental history bundle | `locus_environmental_history` | `{ "address": "..." }` or `{ "state": "MT", "county": "Park County" }` | EPA TRI, RCRA, SDWIS water systems, radon zone, and event-history verify links. Read `radonHeadline` and `addressProximity` first; `countyBackground` and legacy county fields are broad context only. |
 | Cleanup sites | `locus_cleanup_sites` | `{ "address": "...", "radiusMeters": 5000 }` | EPA Superfund, NPL, brownfield, or cleanup-site records nearby with program/status fields and official profile links. |
 | Toxic releases | `locus_toxic_releases` | `{ "state": "MT", "county": "Park County" }` | EPA TRI facilities for the county, chemical-release reporting fields where available, profile links. |
 | RCRA hazardous-waste handlers | `locus_rcra_handlers` | `{ "state": "MT", "countyFips3": "067" }` or `{ "state": "MT", "zip": "59047" }` | RCRAInfo handlers, generator status/activity fields, coordinates, ECHO verify links. |
@@ -180,7 +187,7 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | NOAA storm events | `locus_storm_events` | `{ "stateFips": "30", "countyName": "Park", "countyFips3": "067" }` | NOAA Storm Events history, event type, dates, damage estimates, narratives, and source links. Use `stateFips`, not `state`. |
 | FEMA disaster and NFIP history | `locus_fema_events` | `{ "address": "..." }` or `{ "state": "MT", "countyFips3": "067", "zip": "59047" }` | FEMA disaster declarations by county, NFIP claims by ZIP, preliminary FIRM panel context where available. |
 | 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. Not tax or investment advice. |
+| 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. |
 | Seismic design parameters | `locus_seismic_design` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | USGS NEHRP/ASCE 7 seismic design parameters for a point. Hazard data only, not a safety verdict. |
 | 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. |
@@ -189,7 +196,7 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | 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_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.
+Temporarily degraded national tools may appear in `lanes.degraded` when an upstream source is failing for every point. If `locus_regulated_facility_compliance` appears there during a future EPA ECHO outage, use `locus_environmental_history` and `locus_toxic_releases` as the functional fallback; if `locus_housing_stock` appears there during a future Census outage, use `locus_fair_market_rents` for housing-cost context meanwhile. Otherwise those tools are callable national lanes.
 
 ### Local or coverage-dependent free tools
 
@@ -202,8 +209,9 @@ 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. 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. |
+| Property-tax rates | `locus_property_tax_rates` | `{ "place": "Wake County, NC" }`, `{ "place": "Nashville, TN" }`, `{ "place": "Austin, TX" }`, or `{ "place": "Tampa, FL" }` | Adopted rate components and jurisdiction basis from official tables where wired: NC statewide plus selected Nashville/Davidson TN, Austin/Travis TX, and Tampa/Hillsborough FL adapters. Other jurisdictions return an official-source prompt pack, not a server-emitted rate number. |
+| Property-tax estimate | `locus_property_tax_estimate` | `{ "address": "..." }` | Estimated annual property tax from assessed value and NC rates where wired. Computed estimates are NC-only; out-of-NC addresses fail closed and may return official-source prompt guidance. Not a valuation. |
+| Paid residential property-tax report | `locus-property-tax` | `POST https://api.locus.report/api/locus-property-tax` with `{ "address": "600 E 4th St, Charlotte, NC" }` | x402-paid residential property-tax artifact: assessed value, annual tax, tax history, effective rate, and provenance from RentCast aggregator records. Commercial or uncovered addresses return `charged:false` diagnostics. Not an official tax bill or 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. |
@@ -276,7 +284,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 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.
+- Most paid single-call tools list between $0.05 and $0.07 USDC; `locus-property-tax` is $0.49 USDC because it uses a paid residential tax upstream, and `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.
@@ -284,7 +292,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-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:
+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`, `locus-property-tax`) 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.