@velinussage/locus-agent-skill 0.1.20 → 0.1.21

package/README.md

@@ -94,7 +94,7 @@ The live paid index is authoritative: <https://api.locus.report/.well-known/ai-t
 | `POST /api/locus-nyc-recording-history` | `$0.01` | Paid dual of the free bounded NYC ACRIS document index. No party or unit data and no title conclusion. |
 | `POST /api/locus-renovation-site-context` | `$0.10` | Fixed renovation evidence workflow over parcel, permit, soil, terrain, flood, wetland, and radon context. |
 | `POST /api/locus-solar-property-screen` | `$0.49` | Rollout-gated private one-address roof-solar and historical financial-reference screen. |
-| `POST /api/locus-large-site-satellite-change` | `$0.39` | Rollout-gated, REST-only pair of dated Sentinel-2 composites for a 1-100 square-kilometre site. No automated change or condition claim. |
+| `POST /api/locus-large-site-satellite-change` | `$0.15` | Direct Copernicus REST-only pair of dated Sentinel-2 Level-2A images for a 1-100 square-kilometre site. No automated change or condition claim. |
 | `POST /api/locus-surrounding-area-analysis` | `$0.10` | Stored, bounded JSON evidence packet. Charge-suppressed unless the subject, surrounding-parcel foundation, and another component complete. |
 | `POST /api/locus-surrounding-area-report` | `$0.15` | One HTML/PDF rendering of an eligible packet; no research rerun. |
 | Six paid-only atomic REST routes | `$0.01` each | Workplace jobs, Wikipedia, Commons metadata, PFAS, NEI, and electricity. No free, MCP, or A2A counterpart. |

package/package.json

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

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

@@ -1,7 +1,7 @@
 ---
 name: locus-agent-tools
 preamble-tier: 1
-version: 1.34.0
+version: 1.35.0
 description: Use every time the task is a US address or place and you need cited official public records or local-government context — due diligence, flood, zoning, permits, taxes, what changed, or before you sign.
 triggers:
   - property due diligence
@@ -38,7 +38,7 @@ Locus returns awareness and verification steps, not a verdict. Do not score, ran
 
 ## What to remember first
 
-- **58 national free tools are available with no payment or local coverage check.** The live free catalog exposes 104 tools total. Use national free lanes for rural addresses too, including flood, storm, wildfire, soil, groundwater-monitoring wells, cleanup, toxic-release, underground storage tank / leaking-tank, drought, water-system and non-UCMR PFAS records, water leak-policy candidates, electric service-territory candidates, sewer-overflow/CSO context, broadband, wetland, terrain, air-quality, governing-district, housing/economic, nearby-place, public-utility, county Medicare-spending, aggregate traffic-crash context, open disaster-assistance dates, conforming loan limits, and mortgage-calendar facts. Mirror-backed lanes return explicit missing, partial, stale, or unavailable states instead of treating missing data as favorable.
+- **60 national free tools are available with no payment or local coverage check.** The live free catalog exposes 106 tools total. Use national free lanes for rural addresses too, including flood, storm, wildfire, soil, groundwater-monitoring wells, cleanup, toxic-release, underground storage tank / leaking-tank, drought, water-system and non-UCMR PFAS records, water leak-policy candidates, electric service-territory candidates, sewer-overflow/CSO context, broadband, wetland, terrain, air-quality, governing-district, housing/economic, nearby-place, public-utility, county Medicare-spending, official Sentinel-2 scene availability, aggregate traffic-crash context, open disaster-assistance dates, conforming loan limits, and mortgage-calendar facts. Mirror-backed lanes return explicit missing, partial, stale, or unavailable states instead of treating missing data as favorable.
 - **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.** Summary mode gives a short native-product shortlist. Use `detailLevel: "full"` or the paid index for exact paid-only atomic buy signals.
@@ -81,6 +81,27 @@ A2A and REST discovery:
 
 Buyers do not need a Locus or Coinbase Developer Platform account API key. Free tools are open. Paid tools return a live x402 or advertised MPP challenge. `PAYMENT-SIGNATURE` is a signed payment credential, not an account API key.
 
+### Fastest paid setup with AgentCash
+
+AgentCash is one compatible x402 client. It creates a local payer wallet and can install its MCP server into common agent clients. Locus does not require a buyer API key.
+
+```bash
+npx agentcash@latest onboard
+npx agentcash@latest install --client codex   # or claude-code, cursor, and other supported clients
+npx agentcash@latest balance
+npx agentcash@latest fund
+```
+
+Install the Locus skill separately with `npx @velinussage/locus-agent-skill@latest add`. Use the free Locus MCP or `/tools/call` routes first. For a paid REST call, run `agentcash check <endpoint>` before `agentcash fetch`, force x402 when an endpoint advertises multiple rails, and cap the payment:
+
+```bash
+npx agentcash@latest fetch https://api.locus.report/api/locus-flood-zone \
+  -m POST -p x402 --payment-network base --max-amount 0.01 \
+  -b '{"address":"1 E Edenton St, Raleigh, NC 27601"}'
+```
+
+Read the live challenge and ask before every payment. Keep the settlement receipt.
+
 For broad requests, start with the current bundles in the top-agent manifest. For exact lanes, use the full catalog. A paid entry has a free underscore route only when it publishes `dualFreeTool` or a free `counterparts[]` entry. The seven paid-only atomics do not. Free executor names use underscores (`locus_zoning`); paid REST slugs use hyphens (`locus-zoning`). Execute the entry's exact `callName`.
 
 The live catalogs are authoritative for tool names, schemas, prices, and endpoints. Do not copy stale tool definitions into prompts.
@@ -158,6 +179,7 @@ Trimmed response example for a rural Montana ZIP:
     },
     "lanes": {
       "national": [
+        { "tool": "locus_3dep_availability", "access": "free", "what": "Dated LiDAR collection and raster-source availability; terrain estimates with vintage" },
         { "tool": "locus_flood_zone", "what": "FEMA flood-zone designation at the point", "access": "free" },
         { "tool": "locus_flood_determination_inputs", "what": "SFHDF form inputs: NFIP community, FIRM panel and date, zone, LOMA/LOMR, CBRS status", "access": "free" },
         { "tool": "locus_flood_premium_context", "what": "NFIP policy-cost distribution for policies in force in the ZIP (estimate, not a quote)", "access": "free" },
@@ -239,7 +261,7 @@ These products return `nextCalls[]` instead of a prose narrative. Each call incl
 | Screen one known rooftop for solar | `locus-solar-property-screen` ($0.49) | Treating modeled roof output or a historical financial reference as an installation recommendation |
 | Research a renovation site | `locus-renovation-site-context` ($0.10) | Calling the broader follow-up route with mutable intent fields |
 | Review NYC recording history | `locus_nyc_recording_history` (free) or `locus-nyc-recording-history` ($0.01) | Treating an ACRIS document index as a title or lien conclusion |
-| Compare dated imagery for a large site | `locus-large-site-satellite-change` ($0.39, rollout-gated) | Claiming building condition or detected change from 10 m pixels |
+| Compare dated imagery for a large site | `locus-large-site-satellite-change` ($0.15, direct Copernicus) | Claiming building condition or detected change from 10 m pixels |
 | Compare three known properties for a buyer | `locus-three-property-buyer-comparison` ($2.49) | Raw property, listing, market, and public-record calls without identity, deterministic differences, or ready next calls |
 | Review owner costs and deadlines | `locus-owner-cost-review` ($0.25) | Inferring why taxes changed or treating a program as eligibility |
 | Review rental property operations | `locus-rental-operations-brief` ($0.79) | Raw rent estimates without HUD, permit, tax, market, work items, or ready next calls |
@@ -269,7 +291,7 @@ Use these only after `locus_lane_availability` or the paid index says the call h
 | `POST /api/locus-solar-property-comparison` | `$1.09` | Agent has exactly three known addresses and wants parcel-bound, dated Google Solar roof metrics beside utility candidates, cited solar-program rows, and one shared GridPulse reference. Input: `{ "addresses": ["...", "...", "..."], "financialZip": "27312", "systemKw": 8 }`. Results stay in input order for side-by-side review; Locus does not select a winner or recommend a property. | Fewer than two attributable Google Solar results return `charged:false`. The price includes up to four Turnkey signatures at the conservative Pay as You Go rate. GridPulse figures remain historical context. Licensed provider data is private, `no-store`, and excluded from public pinning. x402 only. |
 | `POST /api/locus-solar-property-screen` | `$0.49` | Agent has one exact address and wants parcel-bound, dated Google Solar roof metrics beside utility candidates, cited programs, and a separately labeled GridPulse reference. Input: `{ "address": "...", "financialZip": "27312", "systemKw": 8 }`. | Missing or mismatched Google Solar evidence returns `charged:false` before GridPulse runs. The price includes two conservative Turnkey signature costs. No score, installation recommendation, current incentive claim, or utility-service conclusion. Private, `no-store`, x402 only. |
 | `POST /api/locus-renovation-site-context` | `$0.10` | Agent needs the fixed renovation evidence profile for one exact address and optional `projectType`. It combines parcel facts, exact-subject permits, USDA soil interpretations, sampled terrain, FEMA flood, mapped wetlands, and EPA county radon context. | The route fixes `intent`, transaction stage, and project archetype server-side. It does not determine feasibility, condition, design, permit requirements, cost, value, or construction readiness. Thin evidence is charge-free. |
-| `POST /api/locus-large-site-satellite-change` | `$0.39` | Agent needs two dated, cloud-filtered Sentinel-2 composites for the same 1-100 km2 caller-supplied bounding box, with each side at least 500 m. | Rollout-gated behind one exact Turnkey policy. Returns imagery and requested composite-window metadata only. It does not detect, classify, quantify, or explain change and cannot support individual-building condition claims. Private, `no-store`, REST x402 only. |
+| `POST /api/locus-large-site-satellite-change` | `$0.15` | Agent needs two dated, cloud-filtered Sentinel-2 Level-2A images for the same 1-100 km2 caller-supplied bounding box, with each side at least 500 m. | Uses direct Copernicus catalogue discovery plus two quota-backed Sentinel Hub renders, with no paid upstream or Turnkey signature. Returns official catalogue candidates, published tile cloud cover, imagery, and requested window metadata. It does not detect, classify, quantify, or explain change and cannot support individual-building condition claims. Private, `no-store`, REST x402 only. |
 | `POST /api/locus-three-property-buyer-comparison` | `$2.49` | Agent has exactly three known addresses and wants non-PII RentCast property/listing lookups, ZIP market context, bounded Locus public records, reusable work items, deterministic cross-property differences, and validated `nextCalls[]` for all three properties. | Invalid, unresolved, or duplicate resolved subjects fail before downstream spend. The price includes up to nine Turnkey signatures at the conservative Pay as You Go rate. Input order is preserved. No winner, valuation, prediction, or purchase recommendation. Private, `no-store`, x402 only. |
 | `POST /api/locus-owner-cost-review` | `$0.25` | Owner or representative has a reassessment or cost question and needs one property/tax trajectory beside cited programs, published windows, work items, and validated `nextCalls[]` with exact arguments and urgency. | An unresolved subject fails before downstream spend. The price includes one conservatively priced Turnkey signature. The response does not infer why tax changed, determine eligibility, or advise an appeal. Private, `no-store`, x402 only. |
 | `POST /api/locus-rental-operations-brief` | `$0.79` | Property operator needs a non-PII property lookup, third-party rent estimate, ZIP rental market, HUD/public-record context, work items, a deterministic rent-to-market difference, and validated `nextCalls[]`. | An unresolved subject fails before downstream spend. The price includes up to three Turnkey signatures at the conservative Pay as You Go rate. Comparable addresses and listing contacts are removed. No tenant screening, rent-setting advice, return calculation, or investment recommendation. Private, `no-store`, x402 only. |
@@ -356,11 +378,13 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | 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. |
 | Broadband availability map | `locus_broadband_check` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Official FCC National Broadband Map link and current data vintage. Provider-reported availability; no fast/slow/good/bad verdict. |
 | Mapped wetland overlap/proximity | `locus_wetland_context` | `{ "address": "...", "radiusMeters": 1500 }` | FWS NWI mapped-wetland overlap and nearby polygon evidence. Never a delineation, jurisdictional determination, parcel boundary, or permit decision. |
+| Dated LiDAR availability | `locus_3dep_availability` | `{ "address": "..." }` | National collection dates, USGS project metadata and NC state raster override. Catalog recency does not establish raster vintage. |
 | Elevation and sampled terrain | `locus_terrain_profile` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | USGS EPQS/3DEP elevation plus sampled cardinal terrain profile/slopes. Never a survey, drainage, grading, or engineering conclusion. |
 | Transportation-noise proximity facts | `locus_noise_proximity` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Straight-line proximity to public-use airports and mapped major-road/rail centerlines. No decibel estimate or quiet/loud/safe/unsafe label. |
 | Nearby places and amenities | `locus_nearby_places` | `{ "address": "...", "radiusMeters": 800 }` | OpenStreetMap nearby amenities/places with categories, distance, and OSM provenance. |
 | Nearest emergency services and utilities | `locus_public_utilities` | `{ "address": "...", "radiusMeters": 5000 }` | Nearest mapped OpenStreetMap fire station, hospital/clinic, police, fire hydrant, electric substation, and water tower with straight-line distances and counts. Hydrants/infrastructure are often unnamed and still reported. Mapped facility distances only, never a fire-protection rating, insurance determination, or safety verdict. |
 | County Medicare fee-for-service spending | `locus_medicare_spending` | `{ "address": "..." }` | Latest/prior CMS county aggregate: Original Medicare fee-for-service beneficiary count, actual and standardized per-capita payment, and standardized year-over-year change. Not a provider price, individual bill, premium, care-quality/access measure, health inference, score, or property signal. |
+| Official Sentinel-2 scene availability | `locus_satellite_scene_availability` | `{ "bbox": [-79.11, 35.795, -79.098, 35.805], "fromDate": "2024-05-01", "toDate": "2024-06-01", "maxCloudCoverage": 30 }` | Official Copernicus product ids, acquisition times, platform, grid, processing level, and source-published tile cloud cover. Metadata only. A match does not establish visual clarity, site condition, or change. |
 | Aggregate traffic-crash context | `locus_traffic_crash_context` | `{ "address": "...", "radiiMeters": [200, 500, 1000], "lookbackYears": 3 }` | Small-cell-suppressed police-reported crash counts by official severity and mode. Registry coverage: Chicago all-reported, Virginia reportable-threshold, North Carolina nonmotorist and K+A subsets kept separate, Pikes Peak region PPACG reportable-threshold records for 2020-2024, plus nationwide FARS fatal-only fallback. No raw rows, examples, exact points, party details, score, forecast, or place verdict. |
 | Landslide history + susceptibility context | `locus_landslide_context` | `{ "address": "...", "searchRadiusMeters": 1000 }` or `{ "latitude": 35.78, "longitude": -78.64 }` | USGS v3 bounded inventory point/polygon records plus a separately labeled exact source-native n10 90-meter cell where the active snapshot publishes one. Inventory no-match, model out-of-footprint, stale/unavailable snapshot, and source failure remain distinct. The 0–81 model value is not probability or parcel engineering. |
 | FEMA NFIP flood-insurance claims (county) | `locus_nfip_claims` | `{ "address": "..." }` or `{ "latitude": 25.76, "longitude": -80.19 }` | FEMA OpenFEMA NFIP redacted flood-insurance claims aggregated to the county: total claim count, total paid, year range, and top rated flood zones. Redacted (no address/PII), county-level historical fact, never a prediction or risk score. |