@velinussage/locus-agent-skill 0.1.39 → 0.1.43

package/README.md

@@ -2,7 +2,7 @@
 
 [![skills.sh](https://skills.sh/b/velinussage/locus-agent-skill)](https://skills.sh/velinussage/locus-agent-skill)
 
-Install three Locus agent skills: the general MCP/REST/A2A capability guide, the opt-in surrounding-area purchase workflow, and the property-tax protest workflow.
+Install eight Locus agent skills: the general MCP/REST/A2A capability guide, the opt-in surrounding-area purchase workflow, the property-tax protest workflow, home-watch, water-incident, seller-readiness, escrow-shock, and payment-hardship workflows.
 
 Locus returns awareness and verification steps, not a verdict. Do not use it to score, rank, screen, value, predict, or label a person, property, block, or neighborhood as safe or unsafe.
 
@@ -12,7 +12,7 @@ Locus returns awareness and verification steps, not a verdict. Do not use it to
 npx @velinussage/locus-agent-skill add
 ```
 
-By default this writes `locus-agent-tools/`, `locus-surrounding-area-analysis/`, and `locus-property-tax-protest/` to `$CODEX_HOME/skills` or `~/.codex/skills`. The general public skill routes relevant requests to the specialist workflows; it does not turn ordinary Locus discovery into a paid flow.
+By default this writes `locus-agent-tools/`, `locus-surrounding-area-analysis/`, `locus-property-tax-protest/`, `locus-home-watch/`, `locus-water-incident/`, `locus-seller-readiness/`, `locus-escrow-shock/`, `locus-payment-hardship/`, `locus-insurance-nonrenewal/`, `locus-inherited-home/` and `locus-aging-owner/` to `$CODEX_HOME/skills` or `~/.codex/skills`. The general public skill routes relevant requests to the specialist workflows; it does not turn ordinary Locus discovery into a paid flow.
 
 Options:
 
@@ -65,13 +65,16 @@ npx skills use velinussage/locus-agent-skill --skill locus-agent-tools
 
 ## What the skills teach agents
 
-- The full free catalog exposes 104 tools, including 58 national free lanes. Read the live catalog because rollout configuration can change the visible total.
+- Read the live free catalog for current tools and national lanes; rollout configuration can change the visible total.
 - `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.
+- The payment-hardship workflow routes mortgage trouble to HUD counseling agencies first, then official state foreclosure pointers and servicer fact cards; the tax branch checks payment status, calendars and relief-program pointers without an eligibility decision.
 - `locus_rental_registration_check` declares its scope per jurisdiction. Long-term registration is wired in Minneapolis, Montgomery County, New York City, and Seattle; Denver is short-term-license only; Kansas City is building-enforcement only. It returns no legal-rental or compliance verdict.
 - The property-tax protest workflow keeps deadline, filing-guide, evidence, browser handoff, and published-outcome facts separate from the owner's own filing and value position.
-- Paid endpoints use live x402 discovery, may offer USDC on Base and Solana, and require explicit user authorization. Agents choose one complete `accepts[]` entry.
+- The home-watch workflow sets up deadline and change events for an address or a signed-in pool, reads an empty poll as "nothing new seen", and offers each paid next step only with the owner's approval.
+- The water-incident workflow keeps what failed, who maintains each pipe segment, and the resulting damage or bill separate, and gives insurer questions without a coverage verdict.
+- Paid endpoints use live x402 and MPP discovery: x402 may offer USDC on Base and Solana (`accepts[]`), and MPP offers `USDC.e` (`0x20C000000000000000000000b9537d11c60E8b50`) on Tempo mainnet (`eip155:4217`, `chainId: 4217`) via `WWW-Authenticate: Payment`, all requiring explicit user authorization. Agents choose one complete offer (for example `-p x402 --payment-network base` or `-p mpp --payment-network tempo`).
 - The surrounding-area workflow requires two separate approvals: $0.10 for the reusable JSON packet, then $0.15 for an eligible HTML/PDF report within 24 hours. Packet and report retrieval are proof-gated for 90 days.
 
 Docs: <https://docs.locus.report/skill.md>

package/bin/locus-agent-skill.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const bundledSkillsRoot = path.join(packageRoot, "skill");
-const skillNames = ["locus-agent-tools", "locus-surrounding-area-analysis", "locus-property-tax-protest"];
+const skillNames = ["locus-agent-tools", "locus-surrounding-area-analysis", "locus-property-tax-protest", "locus-home-watch", "locus-water-incident", "locus-seller-readiness", "locus-escrow-shock", "locus-payment-hardship", "locus-insurance-nonrenewal", "locus-inherited-home", "locus-aging-owner"];
 
 function usage() {
   return `Usage:
@@ -71,7 +71,7 @@ async function installSkills({ target, force }) {
     await cp(source, destination, { recursive: true });
     console.log(`Installed ${skillName} to ${destination}`);
   }
-  console.log("Next: restart or refresh your agent skill catalog. Use locus-agent-tools for general discovery, locus-surrounding-area-analysis for the paid two-stage area workflow, and locus-property-tax-protest for assessment-contest work.");
+  console.log("Next: restart or refresh your agent skill catalog. Use locus-agent-tools for general discovery, locus-surrounding-area-analysis for the paid two-stage area workflow, locus-property-tax-protest for assessment-contest work, locus-home-watch for a standing deadline and change watch, locus-water-incident for a main break, leak or service-line failure, locus-seller-readiness for pre-listing checks, locus-escrow-shock when an escrow payment goes up, locus-payment-hardship for mortgage or tax payment trouble, locus-insurance-nonrenewal when a homeowners insurer will not renew, locus-inherited-home for a house left by someone who died, and locus-aging-owner for an older owner's home or rental.");
 }
 
 async function main() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velinussage/locus-agent-skill",
-  "version": "0.1.39",
-  "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.",
+  "version": "0.1.43",
+  "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": {
     "locus-agent-skill": "bin/locus-agent-skill.js"
@@ -27,6 +27,8 @@
     "locus",
     "mcp",
     "x402",
+    "mpp",
+    "tempo",
     "skills",
     "skills.sh",
     "real-estate",

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

@@ -1,7 +1,7 @@
 ---
 name: locus-agent-tools
 preamble-tier: 1
-version: 1.62.0
+version: 1.67.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,12 +33,12 @@ triggers:
   - real estate webhook notifications
 allowed-tools: Bash Read AskUserQuestion
 license: MIT
-contentHash: d6a93e779f5b
+contentHash: 90024d84edff
 ---
 
 # Locus Agent Capabilities
 
-Use this skill to connect an agent to Locus when a place-based workflow needs local-government context: taxes, parcels, zoning, flood, environmental records, development activity, transportation projects, local policy, source coverage, or recurring monitoring. The fuller client guide is [`docs/AGENT_CAPABILITIES.md`](https://github.com/velinussage/locus/blob/main/docs/AGENT_CAPABILITIES.md).
+This skill is a guide to answering the user's question with Locus, not instructions for running their assistant. It is prescriptive about what Locus records mean and how the API works, and conditional about when to call each tool. The fuller client guide is [`docs/AGENT_CAPABILITIES.md`](https://github.com/velinussage/locus/blob/main/docs/AGENT_CAPABILITIES.md).
 
 Locus returns awareness and verification steps, not a verdict. Do not score, rank, predict, screen, value, or label a person, property, block, or neighborhood as safe/unsafe.
 
@@ -48,27 +48,29 @@ On first use in each session, fetch `https://api.locus.report/.well-known/skill.
 
 ## Start with Locus, not a portal scrape
 
-- Every time the question is a US address or place plus official records or local-government context, call `locus_lane_availability` or `locus_suggest_workflow` first.
-- Looking is free. Paying happens only after an x402 challenge the user authorized.
+- When the question is broad or the right local lane is unclear for a US address or place, call `locus_lane_availability` or `locus_suggest_workflow` first. When the user asks a specific question that maps to one known free tool (such as a water service-line check, a contractor license number, or a state statutory pointer), call that smallest free tool directly; a water-line question should not trigger the same workflow as a tax notice.
+- Looking is free. Paying happens only after a live x402 or MPP (Tempo) challenge the user authorized.
 - Do not buy a generic scrape of FEMA, EPA ECHO/SDWIS/TRI, USGS, HUD, FCC, county GIS, or assessor sites Locus already wraps with provenance. Still follow the official source link Locus returned when you need to verify.
 - **Multi-home comparison:** when the job is two or three finalist addresses, read the dedicated workflow skill at `https://api.locus.report/.well-known/skills/compare-homes/v1.md`. Successful `locus_lane_availability` responses may include optional `skillContinuation` metadata pointing there when report compose rollout is enabled.
 - **Paid buyer bundle:** for a three-home RentCast matrix with work items, use `locus-three-property-buyer-comparison` after user approval; its paid response may also include the same continuation metadata when compose is enabled.
 
 ## Choose the property decision first
 
-Start with `locus_suggest_workflow` for a broad question, then `locus_lane_availability` for the exact place. Use the records below as evidence for the person's decision, not as a verdict. Skip unavailable lanes; use the live catalog for current names and schemas.
+Each recipe below matches a user decision to its minimum inputs, smallest useful free call, coverage limits, what the result establishes, completeness and stop conditions, and the optional paid addition (always presented as an offer, never an instruction to spend). Skip unrelated lanes; use the live catalog for current names and schemas.
 
-| Decision | Free record evidence to check first |
-|---|---|
-| Owning costs or a revaluation notice | `locus_tax_calendar` and `locus_appeal_filing_guide` for statutory rules, official county pointers, and filing steps; confirm current-cycle dates, then use `locus_property_tax_estimate` where supported. Use `locus_appeal_window` with a notice date if deadline arithmetic is needed. Paid assessment or owner-cost follow-ups only if the free evidence leaves a question and the user approves. |
-| Buying | `locus_place_facts`, parcel records, zoning, flood, transfers, and development cases for the exact property. Check each returned source before comparing places; do not pick a winner. |
-| Renting | `locus_rental_registration_check` where wired, plus parcel, flood, and nearby official records. A no-match is not proof of legal permission or habitability. |
-| Leasing | Parcel, zoning, permits, and nearby development records for the proposed premises; use workplace context only if jobs near the site matter. Jobs are not customer demand. |
-| Lending | Parcel, zoning, transfers, flood, and dated area lending or house-price records where available. Area aggregates do not value or qualify the subject or a borrower. |
-| Commercial property financing or ownership | Identify the exact commercial property and check parcel facts first. If the paid CMBS lanes appear in the live index, use `locus-cmbs-loan-context` for its filed loan and maturity, then `locus-cmbs-maturity-wall` only when county-level timing matters. Use the distinct area-context lanes described below only when they answer the user's question; none establish the property's loan or value. |
-| Developing | Parcel, zoning, permits, development cases, soil, wetlands, and flood records. Confirm current rules and project status with the agency; no buildability conclusion. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
 
-The detailed tables below are a record lookup, not an order to call every tool.
+The detailed tables below are a reference lookup by question, not a checklist to run on every turn.
 
 ## Preview, Brief, and Same-data-paid
 
@@ -123,13 +125,19 @@ A2A and REST discovery:
 - [MCP catalog](https://mcp.locus.report/catalog) - searchable tool catalog.
 - [API base](https://api.locus.report) - health and discovery links.
 
-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.
+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` (x402) and `Authorization: Payment` (MPP) are signed payment credentials, not account API keys.
 
 ### Fastest paid setup with AgentCash
 
 The whole free catalog runs without any of this. Get a wallet when you choose to call a paid route.
 
-AgentCash is one compatible x402 client. It creates a local payer wallet and can install its MCP server into common agent clients. Locus issues no buyer API key.
+The live HTTP 402 payment challenge on native and dual-rail REST endpoints offers two payment protocols side by side:
+
+- **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.
+
+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.
 
 ```bash
 npx agentcash@latest onboard
@@ -148,15 +156,23 @@ npx agentcash@latest discover https://api.locus.report
 npx agentcash@latest check https://api.locus.report/api/locus-flood-zone
 ```
 
-`check` returns request and response schema plus pricing before any payment. Then call it, capping the amount:
+`check` returns request and response schema plus pricing before any payment. Then call it on either **Base (x402)** or **Tempo (MPP)**, capping the amount:
 
 ```bash
+# Base USDC over x402:
 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"}'
+
+# Tempo mainnet USDC.e over MPP (separate protocol; no Base wallet required):
+npx agentcash@latest fetch https://api.locus.report/api/locus-flood-zone \
+  -m POST -p mpp --payment-network tempo --max-amount 0.01 \
+  -b '{"address":"1 E Edenton St, Raleigh, NC 27601"}'
 ```
 
-`fetch` handles paid and SIWX routes alike and pays only when the route still demands payment. Hold the same `--payment-network` across every call in one workflow. Force x402 with `-p x402` when an endpoint advertises several rails. Full command reference: [agentcash docs](https://www.npmjs.com/package/agentcash).
+`fetch` handles paid and SIWX routes alike and pays only when the route still demands payment. Hold the same `-p` and `--payment-network` across every call in one workflow (`-p x402 --payment-network base`, `-p x402 --payment-network solana`, or `-p mpp --payment-network tempo`). Force x402 with `-p x402` or MPP with `-p mpp` when an endpoint advertises both protocols. Full command reference: [agentcash docs](https://www.npmjs.com/package/agentcash).
+
+**Wallet compatibility vs. verified settlement on Tempo:** Locus already offers the Tempo payment route over MPP (`method="tempo", intent="charge"`, requesting `USDC.e` on Tempo mainnet), so x402-on-Tempo is not required. The remaining question for any custom wallet is whether it holds Tempo mainnet `USDC.e` (`0x20C000000000000000000000b9537d11c60E8b50`) and can sign the MPP Tempo challenge; inspecting the 402 challenge is a compatibility finding, whereas a completed payment test requires a settled 200 response with `Payment-Receipt` and `charged: true`.
 
 Install the Locus skill separately with `npx @velinussage/locus-agent-skill@latest add`. Use the free Locus MCP or the `POST /api/<tool_name>` routes first.
 
@@ -172,6 +188,8 @@ This route is rollout-gated. Call it only when `locus-surrounding-area-analysis`
 
 When the buyer wants more than the free `locus_surrounding_parcels` primitive and needs one composed view of surrounding parcels, zoning, development cases, permits, legislation, transportation/capital projects, environmental mechanisms, and optional dated aerial evidence, load the separate `locus-surrounding-area-analysis` skill. It owns the paid two-stage workflow and its recovery states. Keep this general capability skill on free discovery and the broader public tool surface; do not copy the paid workflow into ordinary Locus calls. For 100 or 200 m compact windows, treat exact returned distances as the window result. Standard ring aggregates are `null` whenever the request did not cover that full 250, 500, or 1,000 m ring.
 
+For mortgage or property-tax payment trouble, load the bundled `locus-payment-hardship` workflow. Start mortgage help with the HUD agency directory; do not ask why the caller is behind, infer eligibility or predict foreclosure. If the person says they are thinking of harming themselves or are in crisis, stop the records task and give the US 988 Suicide and Crisis Lifeline (call or text 988; https://988lifeline.org/).
+
 ## 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.
@@ -263,7 +281,7 @@ Trimmed response example for a rural Montana ZIP:
         { "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" },
-        { "tool": "locus_homeowners_insurance_context", "what": "ACS median homeowners-insurance cost band and owner costs by ZIP, county, state (estimate)", "access": "free" },
+        { "tool": "locus_homeowners_insurance_context", "what": "ACS insurance-cost bands; opt-in Treasury FIO 2018-2022 ZIP premiums, nonrenewals and claims (historical area context, not a quote)", "access": "free" },
         { "tool": "locus_property_tax_context", "what": "ACS effective property-tax rate and median bill by ZIP, county, state (estimate)", "access": "free" },
         { "tool": "locus_market_context", "what": "County listing price, inventory, days on market (FRED) plus ACS value and rent (estimate)", "access": "free" },
         { "tool": "locus_rebuild_cost_context", "what": "County permit valuation per unit trended by construction PPI as a labeled rebuild-cost proxy", "access": "free" },
@@ -414,6 +432,10 @@ Dual-rail routes (a paid `/api/locus-<tool>` with a free `locus_<tool>` counterp
 | `POST /api/locus-landslide-diligence` | `$0.05` | Agent needs separate USGS documented inventory history and exact source-native n10 model-cell evidence. | Unless both components answer, returns `charged:false`. Never a probability, parcel stability finding, engineering assessment, or safety label. |
 | `POST /api/locus-permit-closeout-check` | `$0.05` | Agent needs exact-subject permit status plus source-published closeout or occupancy-document evidence. Registry coverage: Raleigh, unincorporated Wake County, Durham, Austin, Seattle, Chicago, Los Angeles, and New York City. It accepts an address or up to 25 jurisdiction-scoped `parcelIds`. The coverage label is generated from the source registry. | Uncovered, uncertain, unavailable, unpublished, and no-exact-match states are charge-suppressed. Not condition, compliance, suite/use permission, or closing approval. |
 | `POST /api/locus-transaction-follow-up` | `$0.10` | Agent needs one explicit homebuyer, land-investor, developer-predevelopment, commercial-tenant, or renovation-planning packet with cited handoffs. Prefer the dedicated `locus-renovation-site-context` route for renovation work because it fixes the profile server-side. | Profile-specific component/group thresholds control chargeability. Assessor totals never establish above-grade or finished-basement area. The result is not a feasibility, condition, drainage-design, permit-requirement, cost, or valuation conclusion. Thin evidence is charge-free. |
+| `POST /api/locus-property-tax-protest-packet` | `$0.89` | Homeowner or representative contesting a property-tax assessment needs one shareable evidence packet (cited JSON + self-contained printable HTML/PDF) bundling same-roll assessment uniformity (`locus-assessment-position`), recorded comparable sales (`locus-comps-brief`), optional proposed-figure protest comparison (`locus-valuation-challenge`), statutory appeal deadline rules, and filing portal pointers. Eligible for Stripe MPP (`method="stripe"`), Tempo MPP (`method="tempo"`), and Base/Solana x402. | Fewer than two resolved constituent lanes return `charged:false`. Descriptive percentile and recorded sales only; never an over-assessment verdict or legal/tax advice. |
+| `POST /api/locus-before-you-sign-dossier` | `$1.19` | Homebuyer or buyer's agent under contract needs one complete pre-signing dossier (cited JSON + self-contained printable HTML/PDF) bundling subject parcel identity and roll value, the immediate surrounding parcel ring, FEMA flood zone and mandatory-purchase rule, EPA TRI/RCRA/SDWIS environmental proximity, recorded comparable sales, and local legislative context. Eligible for Stripe MPP (`method="stripe"`), Tempo MPP (`method="tempo"`), and Base/Solana x402. | Fewer than two resolved constituent lanes return `charged:false`. Never an inspection, appraisal, title opinion, or purchase recommendation. |
+| `POST /api/locus-escrow-insurance-dossier` | `$0.89` | Homeowner facing an escrow payment jump or homeowners insurance nonrenewal needs one two-track action dossier (cited JSON + self-contained printable HTML/PDF) bundling `locus-owner-action-brief` (exemptions, tax calendar, appeal window, LOMA screen), `locus-assessment-position`, `locus-insurance-context` (FEMA flood rule, NFIP/ACS figures, rebuild proxy), state nonrenewal notice and FAIR Plan pointers, and federal RESPA 12-month shortage rules. Eligible for Stripe MPP (`method="stripe"`), Tempo MPP (`method="tempo"`), and Base/Solana x402. | Fewer than two resolved constituent lanes return `charged:false`. Never an insurance quote, servicer error finding, or legal/financial advice. |
+| `POST /api/locus-seller-readiness-packet` | `$0.85` | Seller or listing agent preparing to list needs one pre-listing verification and permit closeout packet (cited JSON + self-contained printable HTML/PDF) bundling `locus-permit-closeout-check`, municipal permit portal rules, county assessor roll baseline, state seller property disclosure statute pointers, municipal code cases, FEMA flood-map revision notices, and special district levies. Eligible for Stripe MPP (`method="stripe"`), Tempo MPP (`method="tempo"`), and Base/Solana x402. | Fewer than two resolved constituent lanes return `charged:false`. Never a compliance certificate, legal disclosure opinion, or inspection substitute. |
 
 ### Report compose: turn results you already have into one cited comparison
 
@@ -493,13 +515,14 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | FEMA flood zone at a point | `locus_flood_zone` | `{ "address": "600 E 4th St, Charlotte, NC" }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Flood zone code, SFHA flag, panel or DFIRM identifiers when returned, plain-language zone context, provenance, verify-next steps. |
 | Flood determination form inputs for a loan file | `locus_flood_determination_inputs` | `{ "address": "100 Beach Rd, Surf City, NC" }` | SFHDF fields in section order: NFIP community name and number, FIRM panel and effective date, zone and SFHA, LOMA/LOMR polygons, USFWS CBRS unit and buffer status, per-source status. Not a determination; no 12 CFR 22.6 guarantee. |
 | Flood insurance cost context (estimate) | `locus_flood_premium_context` | `{ "address": "142 Hedgerow, Pittsboro, NC 27312" }` | Median and quartiles of annual NFIP policy cost and full-risk premium for policies in force in the ZIP, split SFHA vs minimal hazard, with policy count and vintage. Not a quote. |
-| Homeowners insurance cost context (estimate) | `locus_homeowners_insurance_context` | `{ "address": "142 Hedgerow, Pittsboro, NC 27312" }` | ACS 2023 median annual insurance-cost band by mortgage status and monthly owner costs at ZIP, county, state; state regulator sample-rate link where published. |
+| Homeowners insurance cost context (estimate) | `locus_homeowners_insurance_context` | `{ "address": "142 Hedgerow, Pittsboro, NC 27312" }` | ACS 2023 median annual insurance-cost band by mortgage status and monthly owner costs at ZIP, county, state; state regulator sample-rate link where published. When enabled, `fioZip` adds Treasury FIO 2018-2022 annual premiums per policy, insurer nonrenewal rates and claim metrics. Rates are fractions, not percentages; missing or withheld cells are null, never zero. Historical area-level data is not a quote or a finding about this home. Ask the insurer or licensed agent about current renewal terms and the notice's dates; do not infer current premium growth from this older series. |
 | Property tax burden context (estimate) | `locus_property_tax_context` | `{ "address": "142 Hedgerow, Pittsboro, NC 27312" }` | ACS median real-estate tax, median home value, and implied effective rate at ZIP, county, state; Lincoln Institute study linked. |
 | Housing market context (estimate) | `locus_market_context` | `{ "address": "142 Hedgerow, Pittsboro, NC 27312" }` | County median listing price, active listings, days on market with year change (FRED), plus ACS value and rent medians. Not a valuation. |
 | Rebuild-cost proxy (estimate, labeled proxy) | `locus_rebuild_cost_context` | `{ "address": "142 Hedgerow, Pittsboro, NC 27312" }` | County permit valuation per unit, PPI trend, implied $/sq ft range under a stated size assumption, floored at FEMA $100. Never a coverage amount. |
 | Environmental records screen for a Phase I file | `locus_environmental_records_screen` | `{ "address": "1500 Market St, Philadelphia, PA" }` | NPL, cleanup, RCRA, UST/LUST, and TRI lists at ASTM E1527-21 search distances with records returned, records within distance, nearest distance, and per-list status. Government-records step only; never a Phase I. |
 | Treasurer tax payment status (Philadelphia) | `locus_tax_payment_status` | `{ "address": "2401 Pennsylvania Ave, Philadelphia, PA 19130", "unit": "5C42" }` | Outstanding principal, interest, penalty, lien numbers by tax year per OPA parcel; `no_outstanding_balance_recorded` when the dataset has no rows. Out of coverage elsewhere. |
 | Nearby flood gauges | `locus_flood_gauges` | `{ "address": "...", "radiusMeters": 20000 }` | Nearby USGS/NWS gauges, latest stage/flow observations when available, threshold metadata, source links. |
+| Pending FEMA flood map changes (county) | `locus_flood_map_change_notices` | `{ "place": "Harris County, TX" }` or `{ "address": "..." }` | Federal Register notices of proposed or final flood map revisions and Letters of Map Revision that name the county: communities, project or case number, comment deadline or effective date, NFIP community number, notice link. A notice is not a parcel zone change; compare the preliminary map. |
 | 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. |
@@ -510,7 +533,9 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | 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. |
 | EPA radon zone | `locus_radon_zone` | `{ "address": "..." }` or `{ "state": "MT", "county": "Park County" }` | EPA county radon zone 1/2/3, county basis, testing/disclosure caveat, provenance. |
-| Public water systems | `locus_water_systems` | `{ "state": "MT", "county": "Park County" }` | Active public water systems serving the county, PWSIDs, SDWIS/ECHO links. County membership does not prove which system serves an address. |
+| California service-line material | `locus_service_line_material` | `{ "address": "<complete CA street address, unit if applicable, city, state and ZIP>" }` | Utility-reported system-owned and customer-owned materials separately (~34% of published statewide rows carry complete indexable street addresses; systems with unindexable or excluded location rows return `source_unavailable` on a miss rather than a negative finding). Opt-in snapshot; exact or normalized address only. Unknown stays unknown; no match is not non-lead. Verify current materials and ownership boundaries with the utility. |
+| Public water systems | `locus_water_systems` | `{ "state": "MT", "county": "Park County" }` | Active public water systems, PWSIDs, SDWIS/ECHO links, and dated system-wide lead, galvanized-requiring-replacement, unknown, and non-lead service-line counts when reported; missing counts are not zero and non-lead counts may be underreported until November 1, 2027. County membership does not prove which system serves an address; system counts do not identify the caller's own line. |
+| State boil-water notices | `locus_boil_water_notices` | `{ "pwsid": "MO1010001" }` or `{ "address": "..." }` | State-published active orders where wired; check live coverage. Address input uses candidate service-area boundaries, not county association. Precautionary utility advisories may be excluded. Use `poll_events` or `subscribe_event` with `name: "locus.real_estate.changes_detected"`, `arguments.addresses`, and `arguments.lanes: ["locus_boil_water_notices"]` to watch for new published notices after a quiet complete baseline. Unavailable reads keep the prior notice watermark. A disappearing row never means lifted; confirm address impact and current instructions with the utility. Not an emergency notification service. |
 | Groundwater monitoring-well context | `locus_groundwater_context` | `{ "address": "...", "radiusMeters": 5000 }` | Nearby USGS monitoring locations, aquifer codes/names, well-construction depth distributions, and static water-level observations, returned in distance bands without location names or exact coordinates. Not a domestic-well depth, yield, potability, contamination, or cost prediction. |
 | EPA Sole Source Aquifer designation | `locus_sole_source_aquifer` | `{ "address": "..." }` | EPA mapped designation containment, designation names, and Federal Register citations. A designation means EPA reviews federally funded projects in the area under SDWA 1424(e); it is not a contamination or water-quality finding and does not itself restrict a private owner. |
 | Non-UCMR PFAS multimedia records | `locus_pfas_multimedia_nearby` | `{ "address": "...", "radiusMeters": 10000 }` | EPA PFAS Analytic Tools environmental-media, wastewater, TRI, Superfund/federal-site, and industry records from reviewed mirror exports. Measured/reported records stay separate from potential-handling flags; proximity does not establish source, migration, exposure, or parcel contamination. |
@@ -520,6 +545,8 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | 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. |
 | Open FEMA assistance windows | `locus_open_disaster_assistance` | `{ "address": "...", "monthsBack": 36 }`, `{ "latitude": 35.22, "longitude": -80.84 }`, or `{ "state": "IN", "county": "Marion" }` | Recent county declarations and published Individuals and Households Program filing dates that have not passed, with FEMA, DisasterAssistance.gov, IRS, and registry pointers. FEMA decides eligibility. |
 | 2026 conforming loan limits | `locus_loan_limits` | `{ "address": "...", "units": 1, "proposedLoanAmountUsd": 900000 }` or `{ "state": "AZ", "county": "Cochise" }` | FHFA county limits for one to four units and optional arithmetic against a caller-supplied amount. Eligibility ceiling context only, not qualification, approval, value, or a recommendation. |
+| HUD housing counseling agencies | `locus_housing_counselors` | `{ "address": "...", "service": "DFC" }` or `{ "lat": 35.78, "lon": -78.64 }` | Nearest directory organizations, published business contacts, raw `sourceStatusCode` (HUD `agc_STATUS`), service/language codes and straight-line distance. A listing or code is not verified HUD approval; confirm approval with HUD or the agency, and ask about free or low-cost counseling, fees and availability. Bounded live source, never an outage-as-empty. |
+| 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. |
 | HUD fair-market rents | `locus_fair_market_rents` | `{ "stateFips": "30", "countyFips3": "067", "year": 2026 }` | HUD FMR values by bedroom count and county/FIPS basis. |
@@ -541,7 +568,7 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | Prepare satellite area from an address | `locus_satellite_area_prepare` | `{ "address": "1 E Edenton St, Raleigh, NC 27601", "beforeDate": "2024-06-01", "afterDate": "2026-06-01", "halfExtentMeters": 1000 }` | Free request preparation: dated parcel/rooftop centroid, explicit surrounding area box, dimensions and ready `retryInput`. No rendering/payment. Depends on parcel resolution; diagnostics never invent a location. |
 | 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. |
+| 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. Top-level `status` (`complete` \| `partial` \| `unavailable`), `partial`, `degradedComponents`, `historyState`, and `susceptibilityState` keep inventory no-match, model out-of-footprint, stale/unavailable snapshot, and source failure 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. |
 | Historical wildfire perimeters | `locus_wildfire_history` | `{ "address": "..." }` or `{ "latitude": 38.6, "longitude": -122.5 }` | WFIGS interagency historical wildfire perimeters within about 5 miles: incident name, category, acres, discovery year. Realized-event records (complements the modeled `locus_wildfire_risk`); most non-Western points return none, an honest `out_of_coverage`. |
 | Soil context and site constraints | `locus_soil_context` | `{ "address": "..." }` or `{ "latitude": 35.9, "longitude": -78.9 }` | USDA NRCS SSURGO soil suitability at a point: NRCS engineering ratings (Very/Somewhat/Not limited, with limiting features) for dwellings, septic absorption fields, and shallow excavations, plus drainage, hydric, slope, shrink-swell (linear extensibility), taxonomic order, and farmland class. Soil-map-unit-level screening context for septic/foundation/drainage/buildability, never a geotechnical, perc-test, permit, or safe/unsafe/buildable verdict. Developed/urban points often return `out_of_coverage` (no soil component). |
@@ -560,7 +587,7 @@ Temporarily degraded national tools may appear in `lanes.degraded` when an upstr
 | Surrounding parcel context | `locus_surrounding_parcels` | `{ "address": "1 E Edenton St, Raleigh, NC 27601", "radiusMeters": 500, "maxParcels": 50 }` | Free source-native parcel topology where the release gate is active, plus bounded centroid-distance rings in supported parcel areas. Use it to identify nearby parcels, not to infer violations or ownership. Use `locus_parcel_code_cases` separately for a supported subject's code-case records; those cases do not describe every surrounding parcel. A 100 m or 200 m request does not cover the full 250 m ring. |
 | Development or rezoning nearby | `locus_development_cases` | `{ "address": "...", "radiusMeters": 1500 }` | Nearby development/rezoning case records, statuses, dates, identifiers, citations where wired. |
 | Public capital projects nearby | `locus_capital_projects` | `{ "address": "...", "radiusMeters": 1609 }` | Government capital projects, public works, assessments where wired, with project ids and source links. |
-| Building permits for a place, parcel set, or supported metro | `locus_metro_permits` | Exact address: `{ "place": "1 E Edenton St, Raleigh, NC 27601" }`; parcel set: `{ "parcelIds": ["0736544606", "0736845188"], "state": "NC", "county": "Wake" }`; point mode: `{ "city": "chicago", "latitude": 41.878, "longitude": -87.629, "radiusMeters": 1000, "sinceDate": "2025-01-01" }` | Free permit activity lookup. Exact subjects resolve through the parcel before source selection. Unincorporated Wake County returns Tyler EnerGov permit, plan, and inspection workflow fields. Verified point-radius metros come from the executable metro registry. Exact parcel requests never fall back to the Census residential county trend. |
+| Building permits for a place, parcel set, or supported metro | `locus_metro_permits` | Exact address: `{ "place": "1 E Edenton St, Raleigh, NC 27601" }`; parcel set: `{ "parcelIds": ["0736544606", "0736845188"], "state": "NC", "county": "Wake" }`; point mode: `{ "city": "chicago", "latitude": 41.878, "longitude": -87.629, "radiusMeters": 1000, "sinceDate": "2025-01-01" }` | Free permit activity lookup with explicit completeness fields (`returnedCount`, `matchedPermits`, `matchedPermitsIsLowerBound`, `responseLimited`, `upstreamTruncated`, `truncated`) and `excludePermitIds` pagination. Exact subjects resolve through the parcel before source selection. Unincorporated Wake County returns Tyler EnerGov permit, plan, and inspection workflow fields. Verified point-radius metros come from the executable metro registry. Exact parcel requests never fall back to the Census residential county trend. |
 | Transportation projects and traffic counts | `locus_transportation_context` | `{ "address": "...", "radiusMeters": 2000 }` | State DOT funded projects, traffic-count stations, routes, statuses where wired. |
 | Public water/sewer service-area screen | `locus_utility_service_check` | `{ "address": "..." }` | Whether the point falls inside mapped public water and sewer service-area polygons where county sources are wired, with provider names when safely published. Polygon membership does not prove service availability, capacity, connection rights, timing, or cost for a parcel. |
 | Transit stops and routes | `locus_transit_context` | `{ "address": "...", "radiusMeters": 400 }` | Transit stops, routes, shelter/ADA fields, headways where supported. Wired transit agencies span about 15 metros: New York (MTA), Los Angeles (LA Metro), Houston (METRO), Charlotte (CATS), Miami-Dade, Nashville (WeGo), Washington DC (WMATA), Dallas (DART), Philadelphia (SEPTA), Atlanta (MARTA), San Antonio (VIA), Seattle (King County Metro), Phoenix (Valley Metro), Denver (RTD), and Raleigh (GoRaleigh). Other areas return no wired transit lane. |
@@ -575,6 +602,9 @@ Temporarily degraded national tools may appear in `lanes.degraded` when an upstr
 | Appeal filing forms and workflow | `locus_appeal_filing_guide` | `{ "address": "..." }` or `{ "state": "Texas", "county": "Harris County" }` | Accepts an address, two-letter state code, or full state name. Covered states: TX, GA, AZ, FL, NC, CO, OH, NJ, WA, CA, NY, IL, MI, TN, and PA (Philadelphia only). Returns the cited filing body, forms, portal mode, fee rule, hearing modes, next appeal body, and a separate browser-workflow handoff. Locus does not file or advise whether to appeal. |
 | Published appeal outcomes | `locus_appeal_outcomes` | `{ "address": "...", "taxYear": 2025 }` or `{ "state": "Illinois", "county": "Cook", "township": "Evanston", "taxYear": 2025 }` | Accepts an address, two-letter state code, or full state name. Coverage includes Cook County Board of Review and Assessor aggregates, NYC Tax Commission published granted reductions, the Texas Comptroller statewide 2024 district survey, and registered official pointers. Historical records only, never a parcel forecast. |
 | State landlord-tenant and owner tax-relief statutes | `locus_tenant_statute_pointers` | `{ "state": "NC" }` or `{ "place": "Raleigh, NC" }` | State/DC chapter and title locators for deposit return/limits, entry notice, repair duties, lease termination, and owner tax relief; local owner-program references and state-locked source queries. Not live-verified section text, legal advice, or a program determination. Verify current official sections and local applicability. The same records are available through the $0.01 `locus-tenant-statute-pointers` route. |
+| State seller-disclosure law and federal lead paint | `locus_seller_disclosure_pointers` | `{ "state": "IA" }` or `{ "place": "Des Moines, IA" }` | Per state: `verified` rows give the official statute or form citation, its URL, the regime (`statutory_form` or `statute_without_form`) and items the official text names (Iowa: lead service lines from January 1, 2026); `not_verified` rows give only an official portal. Always adds the federal lead-based-paint rules for pre-1978 housing (42 U.S.C. 4852d, 40 CFR 745 subpart F, 24 CFR 35 subpart A). Pointers to official text, not legal advice; it never applies a rule to the property. `out_of_coverage` outside the 50 states and DC |
+| Homeowners-insurance nonrenewal rights | `locus_insurance_nonrenewal_pointers` | `{ "state": "FL" }` or `{ "address": "..." }` | Per state: a `verified` notice rule gives the advance-notice days, citation, scope and quoted official text; `not_verified` gives only the insurance department portal. Also the insurer of last resort (FAIR Plan, Citizens or another named plan, or `not_checked`), the department complaint page, and dated emergency rules only while in force. No verdict on a notice and no coverage recommendation. |
+| Estate, heirs-property and court pointers for a home | `locus_estate_property_pointers` | `{ "state": "OH" }` or `{ "place": "Columbus, OH" }` | Per state, each pointer `verified` or `not_verified`: transfer-on-death deed statute, small-estate procedure (citation, whether its text reaches real property, and a threshold quoted only from the checked text), Uniform Partition of Heirs Property Act and Uniform Power of Attorney Act status from the Uniform Law Commission (`not_listed` is not proof of no law), and the court self-help page. Pointers, not legal advice; never says who owns or inherits a home. Workflows: `locus-inherited-home`, `locus-aging-owner`. |
 | Owner programs and windows | `locus_owner_programs` | `{ "place": "Fort Lauderdale, FL" }` or `{ "address": "...", "classes": ["early_payment_discount"], "includeDerived": true }` | Matching curated money-action and program rows, cited statewide tax and appeal rows, nationwide rows, coverage counts, and a jurisdiction-locked official-source query pack. No individual determination, recommendation, or computed savings estimate. |
 | Mitigation incentives | `locus_mitigation_incentives` | `{ "place": "Florida", "hazard": "wind" }` | Cited mitigation grants, insurance discount rules and programs, disaster-assistance windows, flood-map correction, and flood-protection rebate rows, plus next checks in the existing hazard tools. |
 | Utility credits and cost shares | `locus_utility_credits` | `{ "place": "Chicago, IL" }` | Cited stormwater and utility credits, energy rebates, lead service-line programs, sidewalk cost shares, and flood-protection rebate rows, with official-source search prompts for gaps. |
@@ -586,6 +616,7 @@ Temporarily degraded national tools may appear in `lanes.degraded` when an upstr
 | Special valuation screen | `locus_special_valuation_screen` | `{ "address": "..." }` | The parcel's public acreage and land-use code plus cited state special-valuation, historic-incentive, and solar-exemption rows. It does not determine program status for the parcel. |
 | 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. |
 | Recent 311 service requests | `locus_service_requests` | `{ "address": "...", "radiusMeters": 1000, "lookbackDays": 365 }` | Recent San Diego Get It Done request type, status, dates, and public location from the synced city feed. A service request is a report, not a verified condition, code violation, responsible-party finding, or complete account of local activity. |
+| Contractor licence roster | `locus_contractor_license_check` | `{ "state": "WA", "licenseNumber": "<number from bid or permit>" }` | Exact-number lookup only; no name search or licensee names/addresses. Official status, type, effective/expiry dates and source update time where wired. No-match is not proof of being unlicensed; confirm the current record and trade with the board before hiring or relying on recent work. No hiring or workmanship verdict. |
 | Rental registration, short-term licensing, or building enforcement | `locus_rental_registration_check` | `{ "address": "1531 Belmont Ave, Seattle, WA 98122" }` | Exact-building rows with `recordScope` set to long-term registration, short-term license, or enforcement-only. Excludes owner/contact/unit/narrative fields. A no-match is limited to the named dataset, not a compliance finding. |
 | NYC deed and mortgage index | `locus_nyc_recording_history` | `{ "address": "..." }` or `{ "bbl": "3079740028", "limit": 25 }` | Bounded ACRIS Legals and Master document index, dates, source-published amounts, citations, query horizon, and verify-next questions. No party or unit data and no title conclusion. |
 | Government planning meeting pointers | `locus_government_meetings` | `{ "jurisdiction": "us-ca-modesto" }` or `{ "jurisdiction": "us-nc-wake" }` | Free bounded Modesto Planning Commission and Wake County Planning Board dates and official links. No item extraction, parcel match, or final decision. |
@@ -866,13 +897,18 @@ Both MCP harnesses (via protocol JSON-RPC `events/list`, `events/poll`, `events/
 
 | Event name | Dynamic target & filter arguments | What it emits |
 |---|---|---|
-| `locus.real_estate.changes_detected` | `{ "addresses": ["123 Main St, Raleigh, NC"], "lanes": ["locus_metro_permits", "locus_zoning"], "includeUpcomingDays": 60 }` (or `{ "poolId": "<uuid>" }`) | Cited `newRecords` and `newUpcoming` dated milestones since the baseline cursor, plus `followUpTools`. |
-| `locus.real_estate.deadline_approaching` | `{ "addresses": ["123 Main St, Raleigh, NC"], "horizonDays": 30, "basis": ["as filed", "statutory", "published schedule"] }` (or `{ "poolId": "<uuid>" }`) | Dated tax, appeal, hearing, or filing milestones entering the window, with `daysRemaining` and `recommendedTools`. |
+| `locus.real_estate.changes_detected` | `{ "addresses": ["123 Main St, Raleigh, NC"], "lanes": ["locus_metro_permits", "locus_zoning"], "includeUpcomingDays": 60 }` (or `{ "poolId": "<uuid>" }`) | Cited `newRecords` and `newUpcoming` dated milestones since the baseline cursor, plus `followUpTools` and pre-filled `nextActions` (`locus-property-update`). |
+| `locus.real_estate.deadline_approaching` | `{ "addresses": ["123 Main St, Raleigh, NC"], "horizonDays": 30, "basis": ["as filed", "statutory", "published schedule"] }` (or `{ "poolId": "<uuid>" }`) | Dated tax, appeal, hearing, or filing milestones entering the window, with `daysRemaining`, `recommendedTools`, and a priced, pre-filled `nextActions` offer (`locus-assessment-position`, `locus-owner-action-brief`, `locus-property-tax`, or `locus-permit-closeout-check`, each `charge_free_unless_substantive`). |
 | `locus.jurisdiction.legislation_activity` | `{ "address": "123 Main St, Raleigh, NC", "topic": "zoning" }` (or `{ "state": "NC", "topic": "housing" }`) | Newly cited bills or ordinances (`zoning`, `housing`, `tax`, `short_term_rental`, `development`, `all`) with `"Data via LegiScan, CC BY 4.0"` attribution. |
-| `locus.pool.changes_detected` | `{ "poolId": "<uuid>", "lanes": [...], "includeUpcomingDays": 60 }` | Authenticated saved-pool record and milestone changes. |
+| `locus.pool.changes_detected` | `{ "poolId": "<uuid>", "lanes": [...], "includeUpcomingDays": 60 }` | Authenticated saved-pool record and milestone changes, with `followUpTools` and pre-filled `nextActions`. |
 | `locus.watch.digest_sent` | `{ "poolId": "<optional-uuid>" }` | Privacy-preserving digest count (`{ "changeCount": N }` only; no addresses or raw records). |
+| `locus.real_estate.seasonal_hazard_window` | `{ "address": "123 Main St, Wilmington, NC 28401" }` | Opt-in May 1 reminder before the official June 1 Atlantic season start, in coastal-registry counties. Free flood-map and premium-context `nextActions`. No verified state wildfire season is wired. |
+| `locus.real_estate.insurance_renewal_approaching` | `{ "address": "...", "renewalMonth": 7 }` | Opt-in window opens 45 days before the supplied month's first day. Free insurance-context and mitigation `nextActions`. The month boundary is not an actual policy renewal date. |
+| `locus.real_estate.escrow_analysis_approaching` | `{ "address": "...", "escrowAnalysisMonth": 7 }` | Opt-in window opens 30 days before the supplied month's first day. Free mortgage-calendar fact cards, tax-calendar and insurance-context `nextActions`. The month boundary is not a verified servicer date. |
 
-1. **Discover event schemas first:** Call JSON-RPC `events/list` (or model tool `list_event_types` on `/muse/mcp`, or free `locus_mcp_events_catalog` with `{}` on `/mcp` or REST `/tools/call`) and read each event's `inputSchema`, `payloadSchema`, `delivery`, and `requiresAuthForPoll`.
+Calendar reminders require the provider's `LOCUS_MCP_CALENDAR_EVENTS_ENABLED` flag. Unknown months create no date and return `calendarStatus: "missing_date"`. Caller months are explicitly `caller_supplied`, with no invented source URL. Their `nextActions` are free (`priceUsdc: "0.00"`, `charge: "free"`), with no payment field. Cursors expire after 24 hours; when the user has asked for recurring checks, a 12-hour interval supports continuity without losing the baseline. A stale cursor establishes a silent truncated baseline; to recover, omit that cursor and deduplicate by stable `eventId`. Fresh polls list only windows from `triggerDate` through `date`, inclusive in UTC, with no closed-window backfill. If the user opts into a webhook subscription, creating it before the trigger window opens and renewing before `refreshBefore` avoids a gap. Existing `deadline_approaching` events already resurface explicit exemption and appeal dates; never roll recurring prose or a prior-cycle date into a new year. To test event polling, deduplication, or webhook delivery without waiting for a real public-record filing, pass `cursor: "cur_synthetic_test_fixture"` to `events/poll`, `poll_events`, `events/subscribe`, or `subscribe_event`; it emits one clearly labeled synthetic event (`eventId` prefixed `evt_synthetic_`, `synthetic: true` on the poll result) and returns a real cursor. Keep synthetic fixture results separate from proof that a real source change was detected.
+
+1. **Discover event schemas first:** Call JSON-RPC `events/list` (or model tool `list_event_types` on `/muse/mcp`, or free `locus_mcp_events_catalog` with `{}` on `/mcp` or REST `/tools/call`) and read each event's strict `inputSchema`, `payloadSchema` (defined `properties` and `required` fields for every listed event; five kinds by default, eight where calendar reminders are enabled), `delivery`, and `requiresAuthForPoll`.
 2. **Poll an address set or pool (`events/poll` or `poll_events`):**
    - Public inline-address polls (`addresses`: 1-10 US addresses) work on `https://mcp.locus.report/mcp` without authentication. Pool-scoped events (`poolId`) require `/muse/mcp` OAuth or `Authorization: Bearer lmc_...`.
    - Omit `cursor` on the first call to establish a baseline cursor (`cur_...`), then pass the returned `cursor` on subsequent polls:
@@ -973,7 +1009,7 @@ changes what a call is allowed to do.
 
 The paid catalog includes native products, promoted free duals, and paid-only atomics. Native tools use the transports listed in their catalogs. Paid-only atomics are REST-only.
 
-1. **REST:** call `POST /api/<tool-slug>`. Read the x402 v2 `PaymentRequired` body from HTTP 402. Retry the identical request with `PAYMENT-SIGNATURE`. Read settlement from `PAYMENT-RESPONSE`. Legacy `X-PAYMENT` and `X-PAYMENT-RESPONSE` remain compatibility aliases.
+1. **REST (x402 or MPP / Tempo):** call `POST /api/<tool-slug>`. An unpaid call returns HTTP 402 with the x402 v2 `PaymentRequired` JSON body (`accepts[]` offers Base USDC and Solana USDC) and, on MPP-enabled native and dual-rail routes, a `WWW-Authenticate: Payment ..., method="tempo", intent="charge"` header requesting `USDC.e` (`0x20C000000000000000000000b9537d11c60E8b50`) on Tempo mainnet (`eip155:4217`, `chainId: 4217`). For x402, retry the identical request with `PAYMENT-SIGNATURE` and read settlement from `PAYMENT-RESPONSE` (legacy `X-PAYMENT` and `X-PAYMENT-RESPONSE` remain compatibility aliases). For MPP / Tempo, retry the identical request with `Authorization: Payment <credential>` and read the receipt from `Payment-Receipt`. Never send both payment headers on the same request.
 2. **MCP:** use only paid entries present in the MCP catalog. Call `locus_execute`, then retry with `_meta["x402/payment"]` when challenged.
 3. **A2A:** activate `https://github.com/google-a2a/a2a-x402/v0.1` in `X-A2A-Extensions`. A covered paid call returns a task in `input-required` state with `x402.payment.required`. Retry with the same `taskId` and `contextId` and put only `x402.payment.payload` in message metadata; Locus reuses the server-bound tool and arguments. If the completion response is lost, repeat the same payment-only message during the task's short recovery window. The settled replay returns the stored canonical artifact and may refresh the ephemeral owner-of-record field for the same exact verified parcel without another settlement. If you repeat the tool call, it must match that binding. Read settlement from `x402.payment.receipts` in the completed task.
 4. On every rail, read `amount`, `network`, `asset`, and `payTo` from the live challenge. Ask before signing. Payment is idempotent on the tool plus a canonical argument hash, so replay does not double-charge.
@@ -1011,6 +1047,53 @@ Serialize authorization integers as decimal strings. Do not add top-level `resou
 
 An `insufficient_funds` 402 includes `payer`, `network`, and `amountRequired` (atomic USDC units). Before topping up, confirm the funding human holds a recovery copy, especially for an ephemeral agent environment. Then fund that wallet on that network and retry using the fresh challenge. `invalid_signature` and `expired_authorization` require a new signature. A malformed envelope remains `invalid_payload`. None of these responses is a settlement receipt.
 
+### Minimal Tempo MPP (USDC.e) setup
+
+Native and promoted dual-rail REST endpoints also advertise Tempo on HTTP 402 via MPP (`WWW-Authenticate: Payment ..., method="tempo", intent="charge"`), a separate payment protocol from x402. You do not need Base USDC or x402-on-Tempo to use this route; you need a wallet that holds **USDC.e** (`0x20C000000000000000000000b9537d11c60E8b50`) on **Tempo mainnet** (`eip155:4217`, `chainId: 4217`) and can answer the MPP Tempo challenge.
+
+A live `WWW-Authenticate` header on HTTP 402 starts with:
+
+```text
+WWW-Authenticate: Payment id="...", realm="api.locus.report", method="tempo", intent="charge", request="<base64url>", description="...", expires="...", opaque="<base64url>"
+```
+
+Decoding the `request` base64url payload shows the exact Tempo offer (illustrative; always read the live challenge):
+
+```json
+{
+  "amount": "10000",
+  "currency": "0x20C000000000000000000000b9537d11c60E8b50",
+  "externalId": "locus-flood-zone",
+  "methodDetails": { "chainId": 4217 },
+  "recipient": "0xF121fbeceC43e1B616D47285851c20d5fC64431b"
+}
+```
+
+After explicit user spending approval, answer the challenge with an MPP-compatible Tempo client (such as `mppx/client` or `npx agentcash@latest fetch ... -p mpp --payment-network tempo`), which retries the identical `POST` with `Authorization: Payment <credential>` and receives a `Payment-Receipt` header on HTTP 200:
+
+```js
+import { Mppx, tempo } from "mppx/client";
+import { privateKeyToAccount } from "viem/accounts";
+
+// Requires a wallet holding USDC.e (0x20C000000000000000000000b9537d11c60E8b50) on Tempo mainnet (chainId 4217)
+// that can sign the MPP tempo/charge challenge.
+const mppx = Mppx.create({
+  polyfill: false,
+  methods: [tempo.charge({ account: privateKeyToAccount(process.env.TEMPO_PRIVATE_KEY) })],
+});
+
+const response = await mppx.fetch("https://api.locus.report/api/locus-flood-zone", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ address: "1 E Edenton St, Raleigh, NC 27601" }),
+});
+const receipt = response.headers.get("Payment-Receipt");
+const result = await response.json();
+// Confirm response.status === 200, Boolean(receipt), and result.charged === true.
+```
+
+Do not send both `Authorization: Payment` and `PAYMENT-SIGNATURE` on the same request. Lifecycle-bound async jobs (`locus-place-report-batch`, `locus-property-update`, `locus-property-flyer`), paid-only atomics, and `locus-permit-closeout-check` when recheck snapshots are enabled omit the Tempo `WWW-Authenticate` challenge and accept x402 only. Observing the MPP Tempo challenge on a 402 probe is a protocol and asset compatibility finding, not a completed payment test; verify your wallet can sign and settle a `$0.01` call before relying on it in automation.
+
 ### Probe the challenge without paying
 
 `GET` on any paid endpoint returns a side-effect-free discovery challenge. Do not sign that challenge for a Turnkey-backed workflow because it has no exact request body and reserves no provider capacity. Send the exact `POST` body without payment first. That charge-free preflight either returns a current 402 or an uncharged availability error.
@@ -1027,7 +1110,7 @@ For RentCast workflows, inspect `X-Locus-Provider-Budget-State` and `X-Locus-Pro
 
 A 402 challenge alone is not proof that end-to-end paid settlement works for your client. Before relying on paid Locus calls in automation, validate the full pay-and-retry loop once with a $0.01 promoted lookup such as `locus-parcel-lookup` or `locus-flood-zone`:
 
-1. `POST https://api.locus.report/api/locus-flood-zone` with a real address, satisfy the $0.01 challenge, and confirm a 200 with a `PAYMENT-RESPONSE` header (or the legacy `X-PAYMENT-RESPONSE` compatibility header).
+1. `POST https://api.locus.report/api/locus-flood-zone` with a real address, satisfy the $0.01 challenge on your chosen rail (x402 `PAYMENT-SIGNATURE` on Base/Solana or MPP `Authorization: Payment` on Tempo mainnet `USDC.e`), and confirm a 200 with `charged: true` and a `PAYMENT-RESPONSE` header (x402) or `Payment-Receipt` header (MPP / Tempo).
 2. Keep the payment challenge and settlement receipt. Keep signed `offer-receipt` evidence when present. The current EIP-712 receipt extension is EVM-only, so a Solana settlement may omit that additive extension while still returning the standard `PAYMENT-RESPONSE` transaction receipt.
 3. Only then move to higher-priced tools. Read the live challenge instead of relying on a copied price range.
 
@@ -1082,6 +1165,18 @@ Redirect these asks back to records plus verification questions:
 - Named-person dossiers, mugshots, exact victim/suspect addresses, or scraped personal profiles.
 - Legal advice or claims that a user must or should take a legal action.
 
+## How to speak with owners, sellers and buyers
+
+Money, home and deadline questions are stressful. Keep presentation grounded in available evidence across every owner, seller and buyer answer and every Locus workflow skill:
+
+- **Fact, source, uncertainty, useful next step.** State what the record shows, cite the source and its date or vintage when returned, name what the record leaves open, and give a concrete next step when one helps.
+- **Do not require a date for every risk or promise when an unknown will clear.** Include a deadline or window when a statute, notice, or published schedule actually supports one. Sometimes no supported date exists; when a date is unknown or unverified, say so rather than inventing a timeline.
+- **Let completeness and stop conditions guide the next step.** `"This address isn't indexed"` (`source_unavailable` with `incomplete_source_rows` on `locus_service_line_material`) leads to asking the utility for its inventory entry rather than reporting a clean result, whereas `"the indexed record says non-lead"` reports the utility's classification as of the snapshot date. An unverified state rule (`not_verified`) stops at the official portal rather than implying no rule exists.
+- **Treat `nextActions` and paid tools as offers, never instructions to spend or contact someone.** Present the exact tool, arguments, free-versus-paid tier, price (`priceUsdc`), and what question the call answers so the user decides whether to run it.
+- **No alarm words, fear imagery, or verdicts.** Offer choices supported by the records ("You can appeal, apply for the exemption, or ask the servicer how a shortage can be repaid") rather than telling the user what they must do.
+- **Route to human help without shame when relevant.** When payment trouble comes up, note that payment trouble is common and that agencies listed in HUD's housing counseling directory can be asked about free or low-cost counseling.
+- **Crisis guard:** if a person says they are thinking of harming themselves or are in crisis, stop the records task and give the 988 Suicide and Crisis Lifeline (call or text 988). Locus is not a mental-health service.
+
 ## Failure handling
 
 - **Unsupported place:** return the coverage/source diagnostic and suggest the official source to check next.