@velinussage/locus-agent-skill 0.1.44 → 0.1.48

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 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.
+Install thirteen Locus agent skills: the general MCP/REST/A2A capability guide, the media-to-market photo/video regional triangulation workflow, the opt-in surrounding-area purchase workflow, the property-tax protest workflow, the land-entitlement and LiDAR drainage workflow, home-watch, water-incident, seller-readiness, escrow-shock, payment-hardship, insurance-nonrenewal, inherited-home, and aging-owner 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/`, `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.
+By default this writes `locus-agent-tools/`, `locus-media-to-market/`, `locus-surrounding-area-analysis/`, `locus-property-tax-protest/`, `locus-land-entitlement/`, `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:
 
@@ -67,6 +67,7 @@ npx skills use velinussage/locus-agent-skill --skill locus-agent-tools
 
 - 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.
+- When you have only 1–5 photos or a short video clip and no street address yet, start with `locus_media_upload_init` and `locus_media_locate` (free EXIF/text check) or `locus-media-locate` ($0.05) / `locus-video-locate` ($0.10) / `locus-media-to-market` ($0.15) / `locus-video-to-market` ($0.25) to triangulate the region and follow its pre-populated `nextTools` (`livingThere`, `buyingThere`, `whatChangedNearby`).
 - `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.

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", "locus-home-watch", "locus-water-incident", "locus-seller-readiness", "locus-escrow-shock", "locus-payment-hardship", "locus-insurance-nonrenewal", "locus-inherited-home", "locus-aging-owner"];
+const skillNames = ["locus-agent-tools", "locus-media-to-market", "locus-surrounding-area-analysis", "locus-property-tax-protest", "locus-land-entitlement", "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, 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.");
+  console.log("Next: restart or refresh your agent skill catalog. Use locus-agent-tools for general discovery, locus-media-to-market to start a property search or regional analysis from 1-5 photos or a short video, locus-surrounding-area-analysis for the paid two-stage area workflow, locus-property-tax-protest for assessment-contest work, locus-land-entitlement for pre-engineering land entitlement and LiDAR drainage screening, 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.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.",
+  "version": "0.1.48",
+  "description": "Install the general Locus agent skill, the media-to-market photo/video location workflow, 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"

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

@@ -1,11 +1,24 @@
 ---
 name: locus-agent-tools
 preamble-tier: 1
-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.
+version: 1.75.0
+description: Use for cited US place records — starting from an address, county, or directly from 1-5 photos or a short video — including parcels, zoning, permits, flood, drought and water supply, regional market/living briefs, meetings, budgets, audits, county data series, changes over time, and dynamic MCP event polling or signed webhooks.
 triggers:
+  - start property search from image
+  - analyze place from photo or video
+  - where is this photo real estate
+  - media to market
+  - video to market analysis
+  - contractor site card
+  - pre-mobilization check
+  - inspection prep
+  - superintendent permit poll
+  - scientific access metrics
   - property due diligence
   - flood zone
+  - drought
+  - groundwater
+  - water restrictions
   - zoning
   - building permits
   - rental registration check
@@ -33,11 +46,25 @@ triggers:
   - real estate webhook notifications
 allowed-tools: Bash Read AskUserQuestion
 license: MIT
-contentHash: 5982e0aebc33
+contentHash: 4a04f3f0c225
 ---
 
 # Locus Agent Capabilities
 
+## Inspection Handoff Scope
+
+Wake exact-parcel records can populate jobsite handoffs. Unfiltered point-radius metro permits describe neighboring parcels: their handoff permit/toolbox lines stay empty and they do not enter jobsite change events. A caller-selected permit number can support a bounded internal handoff, not a parcel-match claim. Active handoff lines include published `permitStatus` / `inspectionStatus` (null when absent). Terminal statuses, expired permits and past inspection dates relative to source `fetchedAt` are excluded; these filters do not promise inspection readiness. Legislation events pass `permits`, `fees`, or mapped policy domains into the free tool's domain filter, including state-only targets.
+
+## Active Agent Mapbox Orchestration vs. Deterministic Locus Public Records
+
+Locus provides cited public records and deterministic projections: parcel boundaries when published, flood/BFE, wetlands, slope samples, permits, inspections, code cases, liens, comps, and straight-line nearby-place measures. Use scientific fields only when actually returned. Its owner-scrubbed RFC 7946 `geojson` `FeatureCollection` uses `[lon, lat]` and simplestyle-spec marker/stroke/fill properties; a `subject_parcel` Polygon is included when WGS84 parcel rings are present. The optional stored paid-report street locator (`LOCUS_MAPBOX_LOCATOR_ENABLED`) is a separate delivery feature, not an interactive travel-time analysis.
+
+The calling agent actively composes Mapbox views or calculates routes when the user's goal needs them. First confirm credentials, pricing, and spending authority; Locus's records and recipe helper do not authorize or execute these calls.
+
+1. **Network access:** use Mapbox MCP `isochrone_tool`, `matrix_tool`, or `directions_tool` (or Mapbox REST) with the subject `[lon, lat]` and actual nearby destination coordinates. For a 15-minute catchment use `/isochrone/v1/mapbox/{walking|cycling|driving}/{lon},{lat}?contours_minutes=15&polygons=true`. State profile and assumptions; count reachable destinations from results, never relabel straight-line meters or gravity as travel time. Hosford et al. 2022 and Luo & Wang 2003 are method references, not validation of a particular address.
+2. **Role views:** use `static_map_image_tool`, Static Images `geojson(...)`, or GL JS to compose `mapbox/streets-v12` parcel + mapped road for GM-to-owner pre-mobilization; use `mapbox/satellite-streets-v12` or `mapbox/outdoors-v12` with published flood, wetland, and slope callouts for the superintendent's first walk with the excavation foreman. Do not invent boundary geometries from point samples. Reprints show `fetchedAt`. **No Mapbox map on dig day:** the 811 locate ticket and physical paint govern the trench. **No map on the morning inspection toolbox line:** use permit number and published inspection type with citation/date.
+3. **Wholesaler and large-site triage:** overlay `locus_place_facts` GeoJSON, `locus-road-access` GeoJSON, and `locus-large-site-satellite-change` `candidateGrid` cell `bbox` windows; inspect sub-tiles alongside `locus-comps-brief`. Geometry-only `unmeasured` cells are not pixel-change findings. Apparent frontage in imagery does not prove legal access, frontage rights, excavation clearance, or buildability.
+
 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,6 +75,7 @@ On first use in each session, fetch `https://api.locus.report/.well-known/skill.
 
 ## Start with Locus, not a portal scrape
 
+- **Starting from 1–5 photos or a short video (no address yet):** you can begin a property search, living-there/buying-there analysis, or local change check directly from images or a short clip (`<= 60 s`). Upload via `locus_media_upload_init` and call `locus_media_locate` (free EXIF/container GPS and place-text check) or the paid two-model vision tools (`locus-media-locate` $0.05, `locus-video-locate` $0.10, `locus-media-to-market` $0.15, `locus-video-to-market` $0.25) to triangulate the US city, county, or metro and receive a pre-populated `nextTools: { livingThere, buyingThere, whatChangedNearby }` call list plus `locus_region_brief`.
 - 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.
@@ -60,18 +88,47 @@ Each recipe below matches a user decision to its minimum inputs, smallest useful
 
 | Decision / question | Minimum inputs | Smallest useful free call | Coverage limits & what the result establishes | Completeness & stop conditions | Optional paid addition (offer only) |
 |---|---|---|---|---|---|
+| Start a property search or area analysis from 1–5 photos or a short video (no address yet) | 1–5 photos (`mediaId`/`mediaIds` or `imageBase64`/`imagesBase64`) or 1 video clip `<= 60 s` (`mediaId`), plus optional `caption`/`hashtags` | `locus_media_upload_init` → `locus_media_locate`, then `locus_region_brief` and `nextTools` (`livingThere`, `buyingThere`, `whatChangedNearby`) | National US region-level triangulation (city, county, or metro — never a home, street address, or person). Free tier reads EXIF/MP4 GPS and explicit place text; paid tier uses two-model vision (`gemini-3.8-flash` + `gemini-4-argon`) and deterministic NANPA area-code, highway-shield, sign, and plate rules. Every candidate returns `nextTools` pre-populated with exact `countyFips5`/`stateFips`/`countyFips3`/`representativePoint` arguments. | If free `locus_media_locate` locates the county (`status: "located"`), call `locus_region_brief` and the relevant `nextTools` directly without paying for vision locate. On `low_confidence` (Tier C scenic look-alikes), `charged:false` and exploratory `candidates` + `nextTools` are still returned so the user can explore look-alike regions for free. | Offer `locus-media-locate` ($0.05, 1–5 photos), `locus-video-locate` ($0.10, clip `<= 60 s`), `locus-media-to-market` ($0.15, locate + cited `locus_region_brief` + runner-up), or `locus-video-to-market` ($0.25); all return `charged:false` on low confidence, refusal, or insufficient brief coverage. |
 | 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. |
+| Drought, well drawdown, streamflow, or water-use restrictions | Address or coordinates for station tools; county FIPS alone works only for `locus_drought_history`; confirmed `pwsid` or address/coordinates for `locus_water_supply_status` (optional `countyFips` attaches a reservoir) | Choose one for the question: multi-year or current county drought -> `locus_drought_history` (`locus_drought_status` only for a quick current read); stream discharge vs seasonal normal -> `locus_streamflow_vs_normal` (flood stage -> `locus_flood_gauges`); daily well-depth change -> `locus_groundwater_drawdown` (well construction/aquifer -> `locus_groundwater_context`); conservation restrictions or reservoir pool -> `locus_water_supply_status` (boil-water or violations -> `locus_boil_water_notices` / `locus_drinking_water_violations`). | USDM weekly history (since 2000) is national and NOAA county PDSI (since 1895) covers the 48 contiguous states (`not_covered` for DC, AK, HI, and territories); USGS streamflow and daily monitoring-well depth (parameter `72019`, positive `changeFeet` = deeper below land surface) are nearby station readings, not the owner's domestic well; state conservation status is wired in NC (`not_covered` elsewhere) and reservoir pool comparison is wired where a USGS lake gauge is registered. | Stop after returning the free preview if one monitoring well and county/streamflow context answer the question. Read `restrictions.status` and the `componentStatus` entry for `reservoir` (`reservoir: null` when `not_covered`) or `usdm` (`weeksAtOrAbove: null` when `unavailable`, never zero). In NC, `restrictions.status: "ok"` with `matched: []` means no matching published state row for that system, not "unrestricted"; quote matched rows with `reportedAt` and treat `serving.match` (`name` or `county_candidate`) as a candidate to confirm on the utility bill. `sameDate.depthClass` compares only within the retrieved window (`comparisonYears`: ~1-2 yrs free preview, ~5 yrs paid); never treat a USGS monitoring well as proof of domestic well yield or potability. | Offer `locus-groundwater-drawdown` ($0.05) only for additional monitoring-well context: up to 3 wells, bounded 1/3/5-year comparisons and wet-season drawdown where readings exist (`null` on shorter daily series; empty daily-well or source-error results return `charged:false`). |
 | 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-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 pre-mobilization, first site walk, or inspection-week prep | Exact jobsite street address (or parcelId + county + state) | Before mobilization / first site walk: `locus_parcel_lookup`, `locus_metro_permits`, `locus_flood_zone`, `locus_wetland_context`, `locus_terrain_profile` (`slopeConstraintCheck` when returned), `locus_soil_context`. Inspection evening: `locus_metro_permits` (`sinceDate: polling.nextSince` + `excludePermitIds`; read `inspectionHandoff`), `locus_permit_rules`, `locus_parcel_code_cases` (open complaint/case rows), `locus_local_legislation` (fresh permits/zoning/fees headline only). | GM → owner pre-mobilization card and superintendent → excavation foreman first-walk card show published constraints with `fetchedAt`. **The 811 locate ticket and physical paint govern the trench**: if they disagree, stop and call the locator back. No Locus basemap on dig day. Reprint for a new foreman only with `fetchedAt` visible beside current Fieldwire/Bluebeam contract drawings. PM → superintendent evening list: `permitNumber`, published inspection field/date, registry-verified expiration/extension rule, complaint/case rows, and fresh permits/zoning/fees headline. Superintendent → trade foreman morning line: `permitNumber` + `inspectionType` with citation/date; never inspection-pass, compliance, or permit-closed conclusions. | On `polling.nothingNew: true`, report “no new permit row” with citation and do not page the crew. Leave stale/off-domain legislation off the field note. Keep `locus_government_meetings` and paid REST-only `locus-legistar-property-meetings` separate: never state the lot is on an agenda. Missing rules stay `not_verified`; nearby point results are not exact-parcel records. | Offer `locus-renovation-site-context` ($0.10) or `locus-road-access` ($0.05) before mobilization; `locus-permit-closeout-check` ($0.05) for exact-parcel closeout/occupancy evidence; `locus-local-policy-brief` ($0.07) only as a PM read after a fresh permits/zoning/fees headline, never a toolbox card. |
 | 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. |
+| 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. On a private well, add `locus_groundwater_context` and `locus_groundwater_drawdown` (area context, not the owner's well). | 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 reference lookup by question, not a checklist to run on every turn.
 
+## Contractor role handoffs and repeat checks
+
+Use the jobsite address, not crew names or daily worker locations. The six moments are: GM to owner before mobilization; superintendent to excavation foreman on the first site walk; foreman to operator on dig day (811 ticket only, no Locus map); superintendent to a new foreman mid-job (dated card beside the current contract drawings); PM to superintendent the evening before inspection, then superintendent to trade foreman that morning; and daily coordination/billing, which stays outside Locus.
+
+For an evening-before repeat check, retain the returned `permitId` values and send them as `excludePermitIds`, with `sinceDate: polling.nextSince`. This applies to Wake County's exact-parcel permit, plan, and inspection rows as well as supported point-mode feeds. Address input is an alias for `place`; the resolved legal authority controls the source. Read `inspectionHandoff.eveningBeforeProjectManagerToSuperintendent` and `inspectionHandoff.morningOfSuperintendentToTradeForeman`. The permit-only call does not fetch rules, cases, or legislation for you: collect those separately and keep their citations. A permit's building type alone is not an inspection type. For capped point responses, drain the window as described below before advancing; source failure is never “nothing new.”
+
+## Wholesaler identity, comparisons, and map artifacts
+
+- Settled `locus-place-report`, `locus-before-you-sign`, and the paid locus_parcel_financials capability may return `ownerOfRecordStatus` (`attached`, `not_published_by_source`, or `subject_mismatch`) and paid-only `mailingDiffersFromSitus`. The boolean is a source-field comparison, not absentee ownership, vacancy, distress, or contact permission. Treat these delivery fields and assessor names as private: omit them from canonical replay/public/GeoJSON artifacts. Only an eligible settled replay may freshly re-read the official owner record; it must not persist the enrichment.
+- `locus-comps-brief` ($0.05): select `useFilter` (`all`, `residential_only`, or `land_only`) and read `byUseClassSummary` before mixing land with improved-property recorded sales. These are recorded comparisons, not an appraisal or ARV.
+- `locus-tax-liens` ($0.01): read `subjectParcelMatched` and `subjectMatchStatus`; separate `subjectParcelLiens` from `records` (the area results). A nearby delinquency row does not attach a lien to the subject or establish payoff/title.
+- `locus-road-access` ($0.05): the multi-endpoint Overpass empty-trust guard returns `road_source_unavailable` with `charged: false` on degraded evidence. An optional Mapbox Tilequery cross-check uses `mapbox.mapbox-streets-v8` vehicular roads; it is a cross-check, not legal access. RFC 7946 `geojson` `FeatureCollection` output on this tool and `locus_place_facts` is a locator, not frontage, easement, survey, or utility clearance.
+- `locus-large-site-satellite-change` ($0.15): inspect the 4×4 `candidateGrid` and its method. The current `geometry_only_unmeasured` grid partitions the scene into sub-tiles; it does **not** measure pixel shifts. Report a sub-tile pixel-shift breakdown only if a future response explicitly supplies measured values and provenance. Neither geometry nor image differences prove construction or current condition.
+
+## Scientific access and exposure fields
+
+These are capability pointers for the seven PaperBridge method families, not a promise that every deployment returns them. Check the live response/schema first. If a named field is absent, report it unavailable; do not calculate a substitute, infer zero, or present it as shipped evidence. Retain returned method citations, units, radius, fetched date, and source limits. Never convert these measures into a location score or recommendation.
+
+1. **Distance and gravity access:** `locus_nearby_places.categoryMetrics` may carry pre-cap `uncappedNamedCountWithinRadius`, `nearestDistanceMeters`, `thirdNearestDistanceMeters`, `withOpeningHoursRecordedCount`, and `gravityPotential` (Luo & Wang 2003; Hansen 1959; Hosford et al. 2022). Read `overpassElementCapReached`: pre-display-cap counts can still be source-capped, and a gravity measure is not demand or observed visits.
+2. **Recorded opening/access tags:** raw `openingHours` and `wheelchair` tags from `locus_nearby_places` are mapped tags, not verified current availability or accessibility (Willberg et al. 2022).
+3. **Green-space access:** `locus_nearby_places.greenAccessFacts` supplies bounded mapped access facts when present (Battiston & Schifanella 2024), not park quality, a walkable route, or permission to enter.
+4. **Food-store proximity:** `locus_nearby_places.foodStoreProximityFacts` supplies source-bounded distances when present (Xie 2025), not nutrition, affordability, household access, or a neighborhood label.
+5. **Environmental exposure boundaries:** `locus_noise_proximity.scientificContext` uses the Kephalopoulos et al. 2014 CNOSSOS-EU boundary: road proximity is not modeled decibels or personal exposure. `locus_flood_zone.scientificContext.groundMinusBfeFeet` (ESSOAr 2021) is a datum-sensitive ground/BFE difference, not a certified floor elevation or flood clearance. `locus_wildfire_risk.unitBearingMetrics` keeps `annualizedFrequency` separate from `expectedAnnualLossUsd`; preserve the source geography, never a parcel forecast.
+6. **Sampled slope constraints:** `locus_terrain_profile.slopeConstraintCheck` may include `exceedsAdaRampSlope8_33Pct` and `exceeds15PctGradingThreshold`. These compare sampled slopes with named thresholds, not an ADA finding, grading permit decision, or engineering survey.
+7. **Workplace access and concentration:** paid `locus-workplace-employment-context` may include `cumulativeJobContours` and the 20-sector `herfindahlHirschmanIndex`. They describe source-bound workplace counts and sector concentration, not customer demand, foot traffic, or a site ranking.
+
 ## Preview, Brief, and Same-data-paid
 
 A **Preview** returns a bounded public-record lookup. Use it when that lookup answers the question. A **Brief** returns the deeper work named in its description; use it when you need those added records or analysis. A **Same-data-paid** route returns the same records as its named free tool; choose it only when your client can only call paid x402 routes; it adds no facts. Clients that can call Locus free tools (REST tools/call or MCP) should call the free tool. Check each tool's `tier` or `valueTier` and its selection guidance. For legislation, `locus_local_legislation` returns one headline bill; `locus-local-legislation` returns the same headline; `locus-local-policy-brief` adds matched bill and ordinance detail. Get explicit payment approval for any paid route.
@@ -87,7 +144,7 @@ A **Preview** returns a bounded public-record lookup. Use it when that lookup an
 - **Never plan against a count written in this guide.** This file is installed on disk and cannot track tools as they land, so it states no catalog totals. `GET /tools/list` (free rail) and `GET /.well-known/locus-tools.json` (full catalog) are the only authorities for what exists, what it costs, and what is enabled for a given deployment.
 - **Paid reports are async-grade, not click-and-wait.** A full `locus-place-report` takes 60-120 seconds; set a 120-second client timeout. A failed call (502/503 or timeout) is never charged: settlement only runs after the artifact is ready, so retrying is safe. For unattended runs use `locus-place-report-batch` (one settlement, poll the job) instead of tight synchronous retries.
 - **For an owner revaluation, start free.** Check `locus_tax_calendar` and `locus_appeal_filing_guide` before a supported tax estimate. Use `locus_appeal_window` for deadline arithmetic when the notice date is known. Consider paid follow-ups only for a remaining question, after approval; do not advise whether to appeal.
-- **Locus describes the property, never the person.** Owner names, phone numbers, and mailing contacts are excluded by design. For outreach, pair Locus with a licensed skip-tracing source; use Locus for the parcel, tax-status, permit, and area facts that decide whether outreach is worth it.
+- **Locus describes the property, never the person.** Free and public artifacts exclude owner names, phone numbers, and mailing contacts. Settled paid property responses may include the cited assessor owner-of-record field under the private-delivery limits below; it is not a contact, occupant identity, or skip trace.
 
 ## Quick connect
 
@@ -206,7 +263,7 @@ For mortgage or property-tax payment trouble, load the bundled `locus-payment-ha
 
 ## 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.
+- **`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 `drought_water_supply`, `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`. Phrases such as drought, dry well, groundwater, drawdown, streamflow, reservoir or lake level, and water or watering restrictions normalize to `drought_water_supply` (while groundwater contamination, plume, PFAS, or cleanup phrases route to `environmental_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.
 - **`locus_coverage_check { "place": "..." }`** asks whether Locus has source coverage for a jurisdiction at all. Use it for a broad city, county, ZIP, or address scope check.
 - **`locus_lane_availability { "place": "..." }`** is the per-address capability map. It returns which exact tools are national, local, varies, not covered, or degraded, plus buy signals for paid tools. Call this before address-specific local lanes and before paying.
 - **`locus_coverage_map {}`** returns the whole registry view. Use it when an agent needs breadth, not one address.
@@ -391,7 +448,7 @@ Full inventory decisions: `docs/PAID_TOOL_INVENTORY.md`. Paid index entries also
 
 Use these only after `locus_lane_availability` or the paid index says the call has substance for the exact place. The live paid index is authoritative for current prices and schemas.
 
-Dual-rail routes (a paid `/api/locus-<tool>` with a free `locus_<tool>` counterpart) return the same records as the free route. Paying adds a settled x402 receipt, higher rate limits, and catalog discovery; catalog rows mark this with `paidAdds: ["receipt", "rate_limit", "discovery"]`. Use the free route when you do not need a receipt.
+Dual-rail routes (a paid `/api/locus-<tool>` with a free `locus_<tool>` counterpart) return the same records as the free route when `paidAdds: ["receipt", "rate_limit", "discovery"]` is present; use the free route when you do not need a receipt. Exception: promoted routes without `paidAdds` (such as `locus-groundwater-drawdown`) expand a narrower free preview; read each entry's description.
 
 | Endpoint | Price | Use when | Free diagnostic behavior |
 |---|---:|---|---|
@@ -450,6 +507,11 @@ Dual-rail routes (a paid `/api/locus-<tool>` with a free `locus_<tool>` counterp
 | `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. |
+| `POST /api/locus-entitlement-brief` | `$0.25` | Developer, land buyer, or agent needs one pre-engineering land entitlement and LiDAR drainage dossier (cited JSON + `drainageSvg` + self-contained printable `reportHtml`) bundling subject parcel and surrounding parcel ring, zoning and overlays, physical site constraints (`locus_site_constraints`), LiDAR DEM Priority-Flood D8 flow routing and cut/fill earthwork across candidate pads (`locus_lidar_drainage_profile`), water/sewer/road/DOT infrastructure, nearby rezoning and board milestones (`locus_entitlement_activity`), and open specialist verification questions. Supports Tempo MPP (`method="tempo"`) and Base/Solana x402. | Fewer than three resolved constituent lanes return `charged:false`. Never a go/no-go verdict, approval-odds prediction, or engineering certification. |
+| `POST /api/locus-media-locate` | `$0.05` | Agent has 1-5 photos (`mediaId`/`mediaIds` from `locus_media_upload_init` or `imageBase64`/`imagesBase64`) and needs to triangulate the US region (city, county or metro) via two-model vision (`gemini-3.8-flash` + `gemini-4-argon`), OCR signs, area codes, highway shields, and plate rules, plus ready-to-call `nextTools` (`livingThere`, `buyingThere`, `whatChangedNearby`). | `charged:false` on `low_confidence` (Tier C scenic look-alikes still return exploratory `candidates` and `nextTools` for free), `refused` (interior, person, private residence close-up), or `non_us`. Region only; never a street address, home, or person. |
+| `POST /api/locus-video-locate` | `$0.10` | Same two-model vision triangulation and `nextTools` for a short uploaded video clip (MP4/MOV up to 60 s via `mediaId`, `mediaType: "video"`). | `charged:false` on clips over 60 s (`duration_exceeded`), multi-location compilations, `low_confidence`, `refused`, or `non_us`. |
+| `POST /api/locus-media-to-market` | `$0.15` | One-call photo-to-market bundle: runs `locus-media-locate` (1-5 photos) and, when located with confidence, runs `locus_region_brief` (market, HUD rents, FHFA HPI, schools, drought/wildfire/flood/air hazards, unemployment) plus `nextTools`. | `charged:false` unless both the locate gate (`>=0.60` Tier A/B) and brief coverage gate (`>=3` sections including `market` or `hpi`) pass. |
+| `POST /api/locus-video-to-market` | `$0.25` | Same one-call locate + `locus_region_brief` + `nextTools` bundle for a short video clip up to 60 s. | `charged:false` unless both the video locate gate and brief coverage gate pass. |
 
 ### Report compose: turn results you already have into one cited comparison
 
@@ -563,6 +625,10 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | 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. |
+| County drought history | `locus_drought_history` | `{ "countyFips": "37037" }` or `{ "latitude": 35.72, "longitude": -79.18 }` | Weekly US Drought Monitor series since 2000: weeks at each D level, worst D2-or-worse episodes, this week's rank among the same calendar week, plus NOAA county PDSI since 1895 for the 48 contiguous states (CONUS; `not_covered` for DC, AK, HI, and territories while USDM stays independent). Credit NDMC/USDA/NOAA. Not a parcel water supply or forecast. |
+| Streamflow versus normal | `locus_streamflow_vs_normal` | `{ "latitude": 35.72, "longitude": -79.18, "radiusMeters": 25000 }` | Nearest 1-3 USGS gauges, latest discharge versus approved day-of-year percentiles, and a class down to `record_low_for_date`. Provisional instantaneous values are labeled and are not the daily mean. |
+| Groundwater drawdown preview | `locus_groundwater_drawdown` | `{ "latitude": 35.72, "longitude": -79.18, "radiusMeters": 40000 }` | Nearest daily USGS monitoring well (parameter 72019): depth below land surface versus the same calendar dates (`sameDate.comparisonYears` and `sampleCount`) and the one-year change. Positive `changeFeet` means deeper water below land surface; if `pageLimited` is true, the sample or nearest candidate is bounded. A monitoring well is not the owner's well. No qualifying well falls back to discrete `locus_groundwater_context` readings. The paid `locus-groundwater-drawdown` route ($0.05) adds up to three wells and bounded 3- and 5-year change (`null` on shorter series), and does not charge when no daily well qualifies. |
+| Water supply and restrictions | `locus_water_supply_status` | `{ "address": "Pittsboro, NC" }` or `{ "pwsid": "NC0319015", "countyFips": "37037" }` | Candidate EPA SDWIS system, state conservation status where wired (North Carolina from NC DWR; other states return `not_covered`, and an empty `restrictions.matched` in NC means no matching state row rather than unrestricted), and USGS reservoir elevation versus normal pool where a gauge is registered (`reservoir: null` when `componentStatus` is `not_covered`). County or name candidate matching is not proof of service. |
 | HUD fair-market rents | `locus_fair_market_rents` | `{ "stateFips": "30", "countyFips3": "067", "year": 2026 }` | HUD FMR values by bedroom count and county/FIPS basis. |
 | Qualified Opportunity Zone | `locus_opportunity_zone` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Whether the point is in a Treasury/IRS Qualified Opportunity Zone tract, cited to HUD. A `not_designated` zero-hit is a valid designation answer, not a coverage failure. Not tax or investment advice. |
 | Address sales-tax rate | `locus_address_sales_tax` | `{ "address": "123 Pike St, Seattle, WA 98101" }` | Washington and California state revenue agency address-level rates only. Other states return `out_of_coverage`; unresolved addresses return `unavailable`. Confirm the effective date and taxable sale with the state; not tax advice. |
@@ -571,10 +637,16 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | County jobs vs housing permitted | `locus_housing_supply_balance` | `{ "address": "..." }` or `{ "latitude": 35.78, "longitude": -78.64 }` | BLS QCEW county job change over Census BPS units permitted the prior year, plus the permits share of ACS housing stock. Cited published benchmarks and the published critiques of the metric ship together; Locus performs no comparison. |
 | State house-price index | `locus_house_price_index` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Latest state-level FHFA All-Transactions House Price Index and year-over-year change via FRED. Not an appraisal or value estimate. |
 | Tract and ZIP house-price index series | `locus_fhfa_area_hpi` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Latest published FHFA annual tract and ZIP5 index observations from separately loaded official snapshots, with each lane's coverage and release date. Area context, not a property valuation; unloaded data stays `not_loaded`. |
+| County-level region brief | `locus_region_brief` | `{ "place": "Asheville, NC" }` or `{ "latitude": 35.5951, "longitude": -82.5515, "stateFips": "37", "countyFips3": "021" }` | Opt-in per deployment. Cited county brief from existing free lanes: market, HUD rents, FHFA index (ZIP approximated from the ZCTA when none is given, and labeled), drought, wildfire, flood gauges, air quality, unemployment, and schools (`locus_school_context`). Supplied FIPS must match the county at the point. Region-level only; each section reports its own availability. |
+| School district and nearby public schools | `locus_school_context` | `{ "address": "..." }` or `{ "latitude": 35.5951, "longitude": -82.5515 }` | NCES / Census TIGERweb school-district boundary (`school_districts_unified`, `school_districts_elementary`, `school_districts_secondary`), NCES LEAID, grade span, and nearby mapped public schools from OpenStreetMap. Factual boundary and inventory context only, never a school quality score, rating, or ranking. |
+| Where is this? (1-5 photos or clip of a US place) | `locus_media_locate` | `{ "mediaId": "med_…", "caption": "golden hour in Asheville, NC" }` or `{ "imagesBase64": ["…", "…"] }` | Opt-in per deployment. Free tier reads EXIF/container GPS and explicit place text (caption, hashtags, filename) only, no model. Ranked county or city regions with FIPS, rule-based confidence (tier A GPS 0.90, tier B "City, ST" text 0.60, tier C hashtag plus your state hint 0.40), evidence, and `nextTools: { livingThere, buyingThere, whatChangedNearby }` pre-populated with ready-to-call Locus tool arguments. GPS is snapped to the county and never returned. Refuses non-US. Not for interior photos, people or a specific house. For vision triangulation (signs, shields, architecture, biome across 1-5 photos), use paid `locus-media-locate` ($0.05) or `locus-media-to-market` ($0.15). |
+| Upload media for locate | `locus_media_upload_init` | `{ "mediaType": "image", "contentType": "image/jpeg", "bytes": 812345 }` | Opt-in. Returns a mediaId and a signed single-use PUT URL (10 min). Images up to 4 MB; video only where enabled. Deleted when locate reads it; expires within 1 hour otherwise. |
 | Broadband availability map | `locus_broadband_check` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Official FCC National Broadband Map link and current data vintage. Provider-reported availability; no fast/slow/good/bad verdict. |
 | Mapped wetland overlap/proximity | `locus_wetland_context` | `{ "address": "...", "radiusMeters": 1500 }` | FWS NWI mapped-wetland overlap and nearby polygon evidence. Never a delineation, jurisdictional determination, parcel boundary, or permit decision. |
 | Dated LiDAR availability | `locus_3dep_availability` | `{ "address": "..." }` | National collection dates, USGS project metadata and NC state raster override. Catalog recency does not establish raster vintage. |
 | Elevation and sampled terrain | `locus_terrain_profile` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | USGS EPQS/3DEP elevation plus sampled cardinal terrain profile/slopes. Never a survey, drainage, grading, or engineering conclusion. |
+| Physical site constraints composite | `locus_site_constraints` | `{ "address": "...", "radiusMeters": 250 }` or `{ "latitude": 35.72, "longitude": -79.18 }` | Unifies USGS terrain slope/relief, FEMA NFHL floodway/SFHA, USFWS NWI mapped wetlands, USDA SSURGO hydric/septic/shrink-swell/water-table/bedrock limits, and Chatham County NC watershed/stream/river corridor buffers where applicable. National baseline; not a wetland delineation, survey, perc test, or buildability determination. |
+| LiDAR DEM drainage routing, cut/fill earthwork & multi-pad comparison | `locus_lidar_drainage_profile` | `{ "address": "...", "padHalfSizeFt": 75, "includeDeliverables": true }` | Fetches NC OneMap 3-ft LiDAR DEM03 GeoTIFF where covered or USGS 3DEP Float32 GeoTIFF/grid nationally, then runs Barnes (2014) Priority-Flood depression filling, D8 steepest-descent flow routing, upstream off-pad catchment walk, depression/low-spot extraction, least-squares guidance-plane earthwork (cut/fill cubic yards for tilted vs level pad), multi-pad candidate comparison (Center/East/North), and SSURGO + neighboring soil fallback, plus optional `drainageSvg` and interactive `reportHtml`. Planning-grade screen only, not a stamped civil design. |
 | Transportation-noise proximity facts | `locus_noise_proximity` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Straight-line proximity to public-use airports and mapped major-road/rail centerlines. No decibel estimate or quiet/loud/safe/unsafe label. |
 | Nearby places and amenities | `locus_nearby_places` | `{ "address": "...", "radiusMeters": 800 }` | OpenStreetMap nearby amenities/places with categories, distance, and OSM provenance. |
 | Nearest emergency services and utilities | `locus_public_utilities` | `{ "address": "...", "radiusMeters": 5000 }` | Nearest mapped OpenStreetMap fire station, hospital/clinic, police, fire hydrant, electric substation, and water tower with straight-line distances and counts. Hydrants/infrastructure are often unnamed and still reported. Mapped facility distances only, never a fire-protection rating, insurance determination, or safety verdict. |
@@ -600,6 +672,7 @@ Temporarily degraded national tools may appear in `lanes.degraded` when an upstr
 | Exact-parcel code complaints, cases, and violations | `locus_parcel_code_cases` | NYC: `{ "bbl": "5000080019" }` or `{ "address": "<NYC street address>" }`; San Francisco: `{ "jurisdiction": "us-ca-san-francisco", "parcelId": "6311024E" }`; Austin: `{ "jurisdiction": "us-tx-austin", "parcelId": "<Travis parcel id>" }`; unincorporated Wake County: `{ "address": "<street address>" }` | Opt-in per source, default off. Each source has its own scope: NYC HPD housing-maintenance violations; SF Building Inspection complaints plus issued notices of violation (a complaint is not a violation); Austin code complaint cases (not confirmed violations); Wake County cases opened in the last 90 days, matched by street address verified against the parcel site address (not an exact-parcel match; Raleigh and other towns excluded). Returns up to 50 rows per source dataset (SF up to 50 each), no names, units, or narratives. No match is limited to that dataset, not a compliance finding. Other places return `out_of_coverage`; use `locus_request_coverage`. |
 | 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. |
+| Nearby entitlement, rezoning, subdivision & board milestone activity | `locus_entitlement_activity` | `{ "address": "...", "radiusMeters": 1500 }` | Recorded nearby rezonings, subdivisions, conditional/special-use permits, development plans, board milestone recommendations (TRC, Planning Board, Governing Body where published), and observed submittal-to-decision cycle-time distributions. PII-safe; historical records only, never an approval-odds prediction. |
 | 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 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. |
@@ -920,7 +993,7 @@ Both MCP harnesses (via protocol JSON-RPC `events/list`, `events/poll`, `events/
 | `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. |
 
-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.
+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. Ordinary poll cursors expire after 24 hours (when the user has asked for recurring poll checks, a 12-hour interval supports continuity without losing the baseline), while webhook subscription cursors last up to 7 days matching maximum consent lifetime. A stale cursor establishes a truncated fresh baseline (`cursorStatus: "rebaselined"`, `evaluationStatus.state: "rebaselined"` on subscriptions) without inventing gap history; source exceptions on a subscription sweep set `evaluationStatus.state: "failed"` without consuming the cursor. 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`):**
@@ -1196,6 +1269,7 @@ Money, home and deadline questions are stressful. Keep presentation grounded in
 - **Unsupported place:** return the coverage/source diagnostic and suggest the official source to check next.
 - **Empty result:** say no matching records were returned by that source, not that no records exist.
 - **Payment challenge:** do not retry automatically. Ask for authorization.
+- **Settled response dropped or truncated:** recover any settled x402 call's receipt or canonical owner-stripped replay JSON with `GET /api/reports?settlementTx=<txHash>`.
 - **Source conflict:** show both records and name which agency/source to verify with.
 - **User asks for a verdict:** decline that part and offer property-context records plus verification questions.
 

package/skill/locus-land-entitlement/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: locus-land-entitlement
+description: Use when a developer, land buyer, builder, or agent needs a pre-engineering land entitlement, rezoning, subdivision, physical site-constraint, LiDAR drainage/earthwork, or utility-reach screen for a US parcel or address from cited Locus records without turning public records into a go/no-go verdict.
+preamble-tier: 2
+version: 1.0.0
+triggers:
+  - land entitlement
+  - rezoning feasibility
+  - subdivision feasibility
+  - site constraints
+  - lidar drainage
+  - cut and fill earthwork
+  - pad placement
+  - water and sewer reach
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+  - WebFetch
+---
+
+# Land Entitlement & LiDAR Site Feasibility (`locus-land-entitlement`)
+
+**How to speak:** follow "How to speak with owners, sellers and buyers" in the `locus-agent-tools` skill (https://api.locus.report/.well-known/skill.md), including its 988 crisis guard.
+
+Produce a cited, pre-engineering land entitlement and physical site-constraints screen for a US address or parcel—before the buyer or developer spends on a civil engineer, soil scientist, or land-use attorney—while keeping every conclusion strictly factual and non-verdict.
+
+**Never:**
+- Emit a `"go / no-go"` verdict, `"buildable / unbuildable"` label, `"likely to be approved"` score, or approval-odds prediction.
+- Treat a GIS water/sewer district polygon (`locus_utility_service_check`) as a utility will-serve letter, tap allocation, or moratorium clearance.
+- Treat planning-grade LiDAR DEM D8 drainage or least-squares cut/fill yardage (`locus_lidar_drainage_profile`) as a stamped civil grading plan, stormwater model, or ALTA survey.
+- Expose individual applicant, developer, or property-owner names on free paths.
+
+---
+
+## When to Invoke
+
+- A user asks whether a parcel or address can be rezoned, subdivided, entitled, or graded for a residential, multifamily, commercial, or industrial project.
+- A user asks what physical constraints (FEMA floodway/SFHA, USFWS NWI wetlands, USDA SSURGO hydric/septic/shrink-swell/bedrock limits, watershed/riparian stream buffers) or LiDAR drainage/earthwork factors affect a site.
+- A user starts from drone/site photos or a listing clip of land for sale and wants to locate the market and run entitlement checks.
+
+---
+
+## Step-by-Step Entitlement Workflow
+
+1. **Optional Media-to-Market Entry (when starting from drone/site photos or video):**
+   - If no street address or coordinates are known yet, start with `locus_media_locate` (free EXIF/caption tier) or paid `locus-media-to-market` (`$0.15`) / `locus-video-to-market` (`$0.25`) after user payment approval to triangulate the county/metro and regional market brief.
+2. **Preflight Coverage & Parcel Identity (free):**
+   - Call `locus_lane_availability` with the exact `place` or `address`.
+   - Call `locus_parcel_lookup` and `locus_surrounding_parcels` (`radiusMeters: 300`) to confirm parcel acreage, land use, and adjacent parcel context. For multi-parcel assemblages, call `locus_parcel_set`.
+3. **Zoning, Overlays & ETJ Jurisdiction (free):**
+   - Call `locus_zoning` for the subject point.
+   - Report both the **base zoning district** and any **overlay districts** (e.g., Extra-Territorial Jurisdiction `ETJ`, Joint Land Use Plan, Compact Communities Ordinance, Watershed Protection `WS-II`/`WS-III`/`WS-IV`, Jordan Lake Watershed).
+   - Call `locus_ordinance_leads` when the user needs jurisdiction-locked UDO dimensional, buffer, or review-timeline pointers.
+4. **Physical Site Constraints Screen (free):**
+   - Call `locus_site_constraints` (`radiusMeters: 250`).
+   - Synthesize the five physical layers side by side:
+     - **Terrain (`locus_terrain_profile`):** center elevation, relief feet, max directional slope %, and `terrainClass`.
+     - **Flood (`locus_flood_zone`):** FEMA NFHL zone, `isRegulatoryFloodway`, and `sfha` status.
+     - **Wetlands (`locus_wetland_context`):** USFWS NWI point overlap and nearby wetland polygon distances.
+     - **Soils (`locus_soil_context`):** USDA SSURGO map unit, `hydricRating`, `drainageClass`, shrink-swell class, `annualMinimumWaterTableDepth`, `shallowestBedrockDepth`, and septic absorption field rating.
+     - **Watershed & Stream Buffers:** in Chatham County, NC, report `Chatham_WPReferenceLayers` hits (Jordan Lake 50-ft buffers, perennial/intermittent stream buffers, 100-ft river corridor, USGS blue-line streams, and 2,500-ft public water hazard buffers).
+5. **LiDAR DEM Drainage Routing, Cut/Fill Earthwork & Multi-Pad Comparison (free):**
+   - Call `locus_lidar_drainage_profile` (`padHalfSizeFt: 75`, `includeDeliverables: true`).
+   - Present the deterministic terrain findings:
+     - **DEM Source & Resolution:** NC OneMap 3-ft LiDAR (`DEM03`) where covered, or USGS 3DEP Float32 GeoTIFF / grid nationally.
+     - **Drainage & Upslope Catchment:** `runoffScore` (`0-100`), `offPadWaterInAcres` (walked along the Priority-Flood D8 receiver graph so meandering boundary crossings are never double-counted), `waterCrossingPadPct`, and mapped `lowSpots` (depression area in sq ft and max ponding depth in ft).
+     - **Earthwork & Pad Comparison:** least-squares guidance-plane `naturalGradePct`, `fallDirectionDeg`, tilted-plane vs. level-pad `cutYd3` / `fillYd3` / `netYd3`, and the side-by-side `Center` / `East` / `North` candidate pad table (`bestCandidateId` by lowest combined runoff + earthwork).
+     - **Neighboring Soil Fallback:** when the pad center falls on unrated `"Urban land"`, report `neighboringSoilZones` (~150 m N/S/E/W) for perimeter swale and infiltration context.
+6. **Water, Sewer, Power & Road Infrastructure Screen (free):**
+   - Call `locus_utility_service_check`, `locus_water_supply_status`, and `locus_transportation_context`.
+   - In Chatham County, NC, `locus_utility_service_check` checks `WaterDistrictReporting`, `Water Supply Watersheds`, and parcel-level `SewerUtilityAvailable = 'Yes'`. Remind the user that GIS polygon membership does not confirm treatment-plant allocation or absence of a moratorium.
+7. **Entitlement Activity, Board Milestones & Cycle Times (free):**
+   - Call `locus_entitlement_activity` (`radiusMeters: 1500`).
+   - Report `caseCountsByCategory` (`rezoning`, `conditionalOrSpecialUse`, `subdivision`, `siteOrDevelopmentPlan`), `dispositionCounts`, `boardMilestones` (TRC, Planning Board, and Governing Body recommendations/actions where published, such as Chatham County's `Subdivisions_and_Rezonings` layer and Raleigh's `DevelopmentPlans`), and `observedCycleTimeDays` (`medianDays`, `minDays`, `maxDays`, `sampleSize`).
+8. **Paid One-Call Bundle (`locus-entitlement-brief`, `$0.25`):**
+   - When the user wants the complete compiled dossier (cited JSON + `drainageSvg` + print-ready `reportHtml` with interactive flow-step inspection and specialist questions by discipline), check `locus_lane_availability`, state the `$0.25` price (Tempo MPP or Base/Solana x402), and call `POST /api/locus-entitlement-brief` only after explicit user payment approval.
+   - Always close with `openQuestionsByDiscipline` (`civilAndStormwaterEngineer`, `landUseAttorneyAndPlanner`, `utilityAndEnvironmentalHealth`, `geotechnicalAndSoilScientist`).

package/skill/locus-media-to-market/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: locus-media-to-market
+preamble-tier: 1
+version: 1.1.0
+description: Start a US property search, living-there or buying-there market analysis, or nearby change check directly from 1-5 photos or a short video clip when no street address is known yet.
+triggers:
+  - start property search from image
+  - analyze place from photo or video
+  - where is this photo real estate
+  - media to market
+  - tiktok or video to real estate analysis
+  - triangulate photos to location
+allowed-tools: Bash Read AskUserQuestion
+license: MIT
+---
+
+# Locus media-to-market
+
+Start a US property search, living-there or buying-there market analysis, or local change check directly from 1-5 photos or a short video clip when you do not have a street address yet. Locus triangulates the region (city, county or metro — never a home, a street address or a person) and returns a cited regional brief plus ready-to-call Locus tool arguments in `nextTools`.
+
+## Steps
+1. Upload: call `locus_media_upload_init` with `mediaType`, `contentType`, `bytes`; PUT each file to `upload.url` with the returned headers. Each `mediaId` is single use (pass `mediaId` for one photo/clip, or `mediaIds` for up to 5 photos from the same area to triangulate the region).
+2. Free try: `locus_media_locate` with `mediaId`/`mediaIds` (or `imageBase64`/`imagesBase64`, `caption`, `hashtags`). Free reads EXIF/container GPS and explicit place text only.
+3. Paid locate: `locus-media-locate` ($0.05, 1-5 images) or `locus-video-locate` ($0.10, clip up to 60 s). Uses two-model vision (`gemini-3.8-flash` primary + `gemini-4-argon` secondary corroboration) plus deterministic sign, NANPA area-code, highway-shield and plate verification.
+4. Paid bundle: `locus-media-to-market` ($0.15) or `locus-video-to-market` ($0.25). Runs two-model vision locate plus a cited `locus_region_brief` (market, rents, FHFA HPI, schools, hazards, jobs) and a runner-up comparison.
+5. Follow-up tools (`nextTools`): every candidate and top-level response includes `nextTools: { livingThere, buyingThere, whatChangedNearby }` pre-populated with exact `countyFips5`, `stateFips`, `countyFips3`, and `representativePoint` arguments so you can immediately continue the property search or area diligence (`locus_region_brief`, `locus_school_context`, `locus_market_context`, `locus_lane_availability`, `locus_flood_map_change_notices`, `locus_local_legislation`, and other Locus tools).
+
+## Read the result
+- `charged:false` means nothing was billed. Common statuses: `low_confidence`, `refused`, `non_us`, `duration_exceeded`, `insufficient_brief_coverage`. Even on `low_confidence` (Tier C scenic look-alikes), `candidates` and `nextTools` are returned so the user can explore the top candidate regions for free.
+- `calibratedConfidence` comes from the evidence tier (A deterministic anchor 0.85-0.95, B corroborated triangulation 0.60-0.68, C visual similarity only <=0.45), not from the raw model score.
+- When `comparison` is present, present the runner-up region alongside the primary region.
+
+## Never
+- Do not present a region or `representativePoint` as the exact street address or home where a photo was taken.
+- Do not ask for or infer who is in the media.

package/skill/locus-water-incident/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: locus-water-incident
 preamble-tier: 1
-version: 1.2.0
+version: 1.2.1
 description: Use when an owner or their agent is dealing with a water main break, a leak, a high water bill or a failed service line at one US address and needs to know who maintains which pipe, the utility's published leak rules, what to document and what to ask the insurer.
 triggers:
   - water main break
@@ -23,6 +23,16 @@ credited and what is covered. Never say "the utility is liable", "you are covere
 covered" or "you qualify for a credit". State what the published record says, with its source
 and date, and give the question to ask.
 
+> **Scope note (drought, well drawdown, or water-conservation restrictions):** This workflow is for
+> physical pipe failures, leaks, high bills, and acute boil-water notices. When the question is about
+> **drought severity, river streamflow, well-water drawdown, reservoir pool elevation, or
+> water-conservation / shortage restrictions**, choose the matching tool (`locus_drought_history`,
+> `locus_streamflow_vs_normal`, `locus_groundwater_drawdown` or paid `locus-groundwater-drawdown` at
+> $0.05, or `locus_water_supply_status`) under "Drought, well drawdown, streamflow, or water-use
+> restrictions" in `locus-agent-tools`. Live conservation restriction status is NC-only (other states
+> return `not_covered`, which is not "no restrictions"), and a private well that stopped producing is a
+> well-contractor question (USGS wells are area context, not the owner's well).
+
 **How to speak:** follow "How to speak with owners, sellers and buyers" in the `locus-agent-tools`
 skill (https://api.locus.report/.well-known/skill.md), including its 988 crisis guard.