@velinussage/locus-agent-skill 0.1.43 → 0.1.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velinussage/locus-agent-skill",
-  "version": "0.1.43",
+  "version": "0.1.44",
   "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,7 +1,7 @@
 ---
 name: locus-agent-tools
 preamble-tier: 1
-version: 1.67.0
+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.
 triggers:
   - property due diligence
@@ -33,7 +33,7 @@ triggers:
   - real estate webhook notifications
 allowed-tools: Bash Read AskUserQuestion
 license: MIT
-contentHash: 90024d84edff
+contentHash: 5982e0aebc33
 ---
 
 # Locus Agent Capabilities
@@ -63,9 +63,9 @@ Each recipe below matches a user decision to its minimum inputs, smallest useful
 | 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. |
 | 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. |
+| 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. |
 | 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 +135,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 +182,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.

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)