@velinussage/locus-agent-skill 0.1.34 → 0.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velinussage/locus-agent-skill",
-  "version": "0.1.34",
+  "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.",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "url": "git+https://github.com/velinussage/locus.git",
     "directory": "packages/locus-agent-skill"
   },
-  "homepage": "https://docs.locus.report/skill.md",
+  "homepage": "https://api.locus.report/.well-known/skill.md",
   "bugs": {
     "url": "https://github.com/velinussage/locus/issues"
   },

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

@@ -1,8 +1,8 @@
 ---
 name: locus-agent-tools
 preamble-tier: 1
-version: 1.52.0
-description: Use every time the task is a US address or place and you need cited official public records or local-government context — due diligence, flood, zoning, permits, taxes, what changed, or before you sign.
+version: 1.62.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
   - flood zone
@@ -13,15 +13,27 @@ triggers:
   - one address solar screen
   - renovation site context
   - large site satellite change
+  - check a listing or notice against the county record
+  - kill list of candidate sites
   - property tax
   - before you sign
   - what changed at this address
   - local government records
+  - planning meetings and agendas
+  - budgets and audits
+  - county data series
+  - compare dated county observations across places
+  - discover local data sources
   - locus agent tools
   - mcp or rest for locus
   - a2a locus
+  - mcp events
+  - subscribe to property changes
+  - watch address for permits or deadlines
+  - real estate webhook notifications
 allowed-tools: Bash Read AskUserQuestion
 license: MIT
+contentHash: d6a93e779f5b
 ---
 
 # Locus Agent Capabilities
@@ -32,7 +44,7 @@ Locus returns awareness and verification steps, not a verdict. Do not score, ran
 
 ## Check for updates
 
-On first use in each session, fetch `https://docs.locus.report/skill.md` and read its `version:` line. Compare it with the installed copy's version. If the served version is newer, tell the user and suggest `npx @velinussage/locus-agent-skill@latest add` (or `npx skills add velinussage/locus-agent-skill --skill locus-agent-tools`). Do not install without approval.
+On first use in each session, fetch `https://api.locus.report/.well-known/skill.md` and read its `version:` line. Compare it with the installed copy's version. If the served version is newer, tell the user and suggest `npx @velinussage/locus-agent-skill@latest add` (or `npx skills add velinussage/locus-agent-skill --skill locus-agent-tools`). Do not install without approval.
 
 ## Start with Locus, not a portal scrape
 
@@ -69,7 +81,7 @@ A **Preview** returns a bounded public-record lookup. Use it when that lookup an
 - **Start with `locus_place_facts` when lane availability says it is available.** It is the one-call address bundle for supported parcel areas: parcel facts, FEMA flood zone, governing districts, transportation context, and tax context where wired.
 - **Use `locus_lane_availability` before paid calls.** Summary mode gives a short native-product shortlist. Use `detailLevel: "full"` or the paid index for exact paid-only atomic buy signals.
 - **Treat partial trend coverage as a check-first signal.** `supported_partial` trend places appear in `lanes.varies` with low paid substance; buy `locus-local-trend-brief` only when `buyRecommendations[].substanceHere` is `medium` or better. Thin exact-radius results can return a `charged:false` data-sufficiency diagnostic instead of a paid brief.
-- **The paid catalog mixes native paid tools, promoted dual-rail routes, and paid-only atomic routes.** Read `GET /.well-known/locus-tools.json` for the current set and count. Rollout-gated tools appear in the live catalog only when configured. Six paid-only atomics cost $0.01: `locus-workplace-employment-context`, `locus-wikimedia-commons-area-context`, `locus-wikipedia-place-context`, `locus-pfas-occurrence`, `locus-nei-emissions-nearby`, and `locus-electricity-context`. The paid-only `locus-evaluation-packet` costs $0.35. They use x402 over REST and have no free underscore, MCP, or A2A counterpart. Read the live challenge for exact price, chain, asset, recipient, and schema before payment.
+- **The paid catalog mixes native paid tools, promoted dual-rail routes, and paid-only atomic routes.** Read `GET /.well-known/locus-tools.json` for the current set and count. Rollout-gated tools appear in the live catalog only when configured. Six paid-only atomics cost $0.01: `locus-workplace-employment-context`, `locus-wikimedia-commons-area-context`, `locus-wikipedia-place-context`, `locus-pfas-occurrence`, `locus-nei-emissions-nearby`, and `locus-electricity-context`. The paid-only `locus-legistar-property-meetings` costs $0.05. The paid-only `locus-evaluation-packet` costs $0.35. They use x402 over REST and have no free underscore, MCP, or A2A counterpart. Read the live challenge for exact price, chain, asset, recipient, and schema before payment.
 - **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.
@@ -83,6 +95,8 @@ Install this skill in Codex-style agents:
 npx @velinussage/locus-agent-skill add
 ```
 
+For MCP event discovery, call free `locus_mcp_events_catalog` with `{}`. It returns public event names, authentication guidance, method pointers and `skill://locus/subscribing-to-locus-events`; use live `events/list` for authoritative event input and payload schemas. Polling and subscriptions are separate operations, not side effects of reading this catalog.
+
 Remote MCP server:
 
 ```json
@@ -148,7 +162,7 @@ Install the Locus skill separately with `npx @velinussage/locus-agent-skill@late
 
 Read the live challenge and ask before every payment. Keep the settlement receipt.
 
-For broad requests, start with the current bundles in the top-agent manifest. For exact lanes, use the full catalog. A paid entry has a free underscore route only when it publishes `dualFreeTool` or a free `counterparts[]` entry. The seven paid-only atomics do not. Free executor names use underscores (`locus_zoning`); paid REST slugs use hyphens (`locus-zoning`). Execute the entry's exact `callName`.
+For broad requests, start with the current bundles in the top-agent manifest. For exact lanes, use the full catalog. A paid entry has a free underscore route only when it publishes `dualFreeTool` or a free `counterparts[]` entry. Paid-only atomics do not. Free executor names use underscores (`locus_zoning`); paid REST slugs use hyphens (`locus-zoning`). Execute the entry's exact `callName`.
 
 The live catalogs are authoritative for tool names, schemas, prices, and endpoints. Do not copy stale tool definitions into prompts.
 
@@ -160,7 +174,7 @@ When the buyer wants more than the free `locus_surrounding_parcels` primitive an
 
 ## 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`, and `tax_delinquency_redemption`. 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 `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_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.
@@ -174,7 +188,17 @@ When the buyer wants more than the free `locus_surrounding_parcels` primitive an
 - `area_operating_context` is supplemental. It cannot make a thin exact-premises packet chargeable.
 - Choose `locus_nearby_places` for free current mapped amenities. Paid `locus-wikipedia-place-context` runs topic-agnostic geosearch, so it may return places, institutions, events, or people. Use it only as community reference research; never turn person-topic articles into property, resident, customer, screening, or neighborhood claims. Use paid `locus-wikimedia-commons-area-context` for nearby media license metadata and attribution leads.
 - Commons items remain `nearby_context`. Proximity does not prove that media depicts the premises or represents the area. Metadata is not reuse permission. Verify storage, transformation, redistribution, attribution, and share-alike rights before reuse.
+- **Official fiscal source research:** Call free `locus_fiscal_source_guide { "place": "Raleigh, NC" }` (or `{ "place": "Wake County, NC" }`) for national and resolved local government document leads plus a parsing guide. An empty `observations[]` is normal, not a failed lookup: the guide does not fetch documents or report numeric figures. Confirm the reporting government before extracting figures from the originals; retain the document edition, page or cell, period, units, accounting basis, and retrieval time in a caller-owned ledger. For a cross-county city, provide an exact address or confirmed county before assigning local links.
 - Before offering `locus-local-fiscal-context`, call `locus_lane_availability` with `detailLevel: "full"` and inspect that exact paid-tool entry. It states whether an active verified fiscal snapshot exists and explains when a paid call would return `charged:false` because the snapshot is missing, stale, or thin. `locus_coverage_check` points to this capability map but does not affirm every available paid lane.
+- **Local fiscal revenue series:** When a commercial borrower, owner, or civic researcher asks how local government receipts changed, check the live paid catalog and exact fiscal snapshot availability. After separate payment approval, read `revenueSeries` by jurisdiction, reporting period, measure, kind, publication date, and official source. `property_tax_levy` is billed/levied, `property_tax_collected` and `property_tax_revenue` are reported actuals on their stated basis, `taxable_assessed_value` is a tax base, and `sales_tax_distribution` is a government distribution—not Raleigh retail sales. Use `revenueChanges` only when the tool has verified comparable periods; revaluations, rate changes, allocation changes, and accounting changes can make an apparent change noncomparable. An unreviewed collection or a source pointer is not active numeric coverage.
+- **Official documents when the fiscal snapshot is missing:** Use free `locus_fiscal_source_guide` to find scoped official leads without attempting payment; if a paid preflight has already returned `charged:false` with `no_active_snapshot`, its `verifyNext` links may also point to Raleigh annual reports, NC distribution workbooks and memos, or Wake tax-base and levy indexes. Agents may parse those originals for the user's question without calling the paid tool again. Label extracted figures as your own unreviewed observations, and cite the exact document, page or cell, period, units, and jurisdiction. Raleigh citywide figures are not Wake County figures; NC distributions to governments are not retail sales. Do not label source links or your parsing as an active Locus fiscal series, infer a comparable year-over-year change without checked definitions, or charge for absent numeric coverage.
+- **Second-order context:** If the question also concerns refinancing and construction, obtain the county `locus-cmbs-maturity-wall` only after its own payment approval, and use `locus_development_cases` separately where covered. Align each tool's geography and report date; show their dated observations side by side. Neither series establishes why another moved or predicts this property's finances.
+
+## Comparing dated evidence across places
+
+When a user asks how several centers are changing, let their question select the measures. Check the live catalog for independent source primitives, such as `locus_acs_living_arrangements_series`, `locus_cbp_county_industry_series` (caller selects the industry), or `locus_office_source_guide` (office-report leads, not vacancy measurements). Run only relevant tools; resolve each center's geography before joining records. Ask which county the user means when a city spans counties.
+
+Keep a caller-owned evidence ledger with each observation's geography, measure, source edition and year, value and units, record ID, source URL, retrieval time, and source caveats. Record missing, suppressed, and unavailable cells as gaps, not zeros. Compare only like geographies and definitions; distinguish revised source data from change on the ground. Give the user's agent the dated records and unresolved questions to interpret, without encoding their thesis, private destinations, a place score, or a recommended investment in Locus.
 
 ## Commercial property and public CMBS filings
 
@@ -200,7 +224,7 @@ When the buyer wants more than the free `locus_surrounding_parcels` primitive an
 3. **Resolve the exact place first.** Call `locus_coverage_check` and `locus_lane_availability` with the exact user string. Compare the resolved jurisdiction to any user-supplied city/county/state.
 4. **For a broad address question, call `locus_place_facts` first if available.** It often replaces several separate calls. If lane availability marks it not covered, fall back to national free tools or parcel-only mode.
 5. **For local depth, check availability for the exact place.** Follow the lane's `access` value. A paid-only `varies` lane still needs approval, but returns `charged:false` when it cannot provide substantive data.
-6. **Run the smallest tool by intent.** Use each transport's own catalog. The seven paid-only atomics use `POST /api/<hyphenated-slug>` over REST.
+6. **Run the smallest tool by intent.** Use each transport's own catalog. Paid-only atomics use `POST /api/<hyphenated-slug>` over REST.
 7. **Ground every fact.** Check the returned state, county, municipality, and data vintage against the question before using a record. Mark mismatches or old layers as such, not current facts. Include source names, links or locators, fetched timestamps where present, and caveats.
 8. **Pay only on explicit authorization.** A paid tool returns an x402 challenge. Show price, chain, recipient, and tool, then retry only after the user approves.
 9. **Follow property-update diagnostics exactly.** On `409 clarification_required`, inspect the response before retrying. If `retryInput` is present, ask the user to confirm the matched subject and then resend that object as the next request. If `retryInput` is absent, ask the user for a corrected exact address and construct a new request from it. Never resend the original ambiguous address. On `insufficient_current_context`, use the returned wider radius or choose one of `alternativeTools`; those alternatives are separate paid calls and still require their own preflight and authorization.
@@ -286,8 +310,9 @@ Use the exact JSON shapes below as safe defaults. If a tool also accepts `latitu
 | What helped or was confusing | `locus_agent_feedback` | `{ "kind": "ux_gap", "target": "locus_lane_availability", "summary": "The varies bucket is easy to treat as available" }` | Product note only. Summary up to 1,000 characters. Set `target` (aliases `tool`, `toolName`). Also `POST /feedback`. |
 | Inspect official source cards | `locus_source_card_check` | `{ "place": "Raleigh, NC" }` or `{ "jurisdiction": "us-nc-raleigh" }` or `{ "cardId": "us-nc-durham:permits" }` | Source-card status, provenance, endpoint, verification method, timestamp. |
 | Verify a citation URL | `locus_verify_citation` | `{ "sourceUrl": "https://...", "recordId": "optional", "jurisdiction": "optional" }` | Whether a citation matches a known source card, with provenance context. |
-| What policy sources govern here? | `locus_policy_sources` | `{ "place": "Raleigh, NC" }` | State, county, city policy-source list, legal geographies, source links. |
+| What policy sources govern here? | `locus_policy_sources` | `{ "place": "Raleigh, NC" }` or `{ "place": "Raleigh, NC", "liveSearch": true }` | State, county, city policy-source list, legal geographies, source links, and optional operator-enabled Gov-Index pointer discovery (`govIndex`). |
 | Read aggregate coverage demand | `locus_coverage_demand` | `{}` | Aggregate requested-coverage demand, not place records. |
+| Discover dynamic MCP real-estate events | `locus_mcp_events_catalog` | `{}` | Public MCP Events catalog: event names, parameter/payload summaries, delivery modes (`poll`, `webhook`), auth rules, and `skill://locus/subscribing-to-locus-events` pointer. |
 
 ### High-value property workflows
 
@@ -299,6 +324,8 @@ Route these first when the buyer already knows the property or shortlist:
 4. **Rental registration, short-term license, or building enforcement:** use free `locus_rental_registration_check` for an exact building. Read `recordScope` before interpreting the result. 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 and cannot answer whether a rental registration exists. Agent-commerce callers may use the identical `$0.01` REST dual. Never turn a row or no-match into legal permission, compliance, habitability, or a person judgment.
 5. **NYC deed and mortgage index:** use free `locus_nyc_recording_history` with one NYC address or exact 10-digit BBL. It joins ACRIS Legals to ACRIS Master and returns bounded document ids, types, dates, source-published amounts, and citations without party or unit data. The `$0.01` REST dual is identical. It is not a title, lien, payoff, ownership, priority, validity, or insurability conclusion.
 6. **Rental-registration portfolio:** use `locus-record-batch` at `$0.05` with 2-25 exact addresses and `lanes: ["locus_rental_registration_check"]`. One async job returns results keyed by address. Addresses outside the current source registry remain explicit out-of-coverage items; do not treat them as unregistered.
+7. **A listing, assessment notice, or inspection excerpt you want held against the county record:** use `locus-listing-claim-check` at `$0.25` (one address) or `locus-listing-claim-batch` at `$0.65` (2-3 addresses in one settlement). Paste the document text or pass structured claims; each address is one `subject` with a `mode` of `listing`, `assessment_notice`, or `inspection_excerpt`, and each mode takes only its own field (`claims` or `listingText`; `noticeText`; `inspectionText`, 10-20,000 characters). It compares building area, year built, permit references, and notice values with the parcel and exact-address permit record and shows each match, difference, or ambiguity with a dated citation. It is x402-only, and a result with no cited evidence is `charged:false`. Limits to say out loud: it cannot check rent rolls, leases, offering-memorandum (OM) figures, NOI, or any number no public record publishes; an area is compared only when the text names the same definition (heated, gross, and so on); an assessor year built can be an effective year; and a difference is a question to verify, not a finding that anyone misstated anything. If the address matches a lot recorded under a different house number, the tool returns `identity: unresolved` and does not charge.
+8. **Kill-list before spending time on a candidate list:** see "5. Which candidate sites can I drop early?" below.
 
 These products return `nextCalls[]` instead of a prose narrative. Each call includes the exact `tool`, ready `input`, one-sentence `why`, supporting `evidenceIds`, `cost`, `urgency`, endpoint, and `requiresPaymentApproval`. `cost` is `free` or the exact dollar price from Locus's central price registry when the workflow was generated. `costAtGeneration` remains an identical compatibility alias. `nextCallPlan.pricedAt` timestamps the price snapshot; the next tool's live challenge remains authoritative. A small model may select and order only server-built candidate IDs. Locus owns and validates every returned tool name, argument object, price snapshot, evidence link, and payment flag. Model failure uses the deterministic candidate order. A paid next call is never executed without separate approval.
 
@@ -311,7 +338,6 @@ The three RentCast workflows already use Turnkey to buy from the RentCast x402 g
 | Free snapshot | `locus_place_facts` (free) | Paid dual of the same |
 | Pre-sign parcel + trend + policy | `locus-before-you-sign` ($0.07) | Three separate briefs |
 | Owner programs, dates, appeal/tax rules, and parcel screens | `locus-owner-action-brief` ($0.05) | Six separate owner-action lanes |
-| Neighbors, topology, multi-lane surrounding evidence | `locus-surrounding-area-analysis` ($0.10) ± report ($0.15) | `locus-ownership-loop` alone or many micro duals |
 | EPA proximity bundle | `locus-environmental-context` ($0.05) | Parallel toxic/RCRA/water duals |
 | Compiled place artifact | `locus-place-report` ($0.05) | Stitching free tools into a fake report |
 | Recent official change + media | `locus-property-update` ($0.10) | Flyer first |
@@ -324,6 +350,8 @@ The three RentCast workflows already use Turnkey to buy from the RentCast x402 g
 | Review owner costs and deadlines | `locus-owner-cost-review` ($0.25) | Inferring why taxes changed or treating a program as eligibility |
 | Review rental property operations | `locus-rental-operations-brief` ($0.79) | Raw rent estimates without HUD, permit, tax, market, work items, or ready next calls |
 | Check municipal rental registration | `locus_rental_registration_check` (free) or `locus-rental-registration-check` ($0.01) | Treating a source row or no-match as legal permission, compliance, habitability, or a landlord judgment |
+| Hold a listing, notice, or inspection excerpt against the county record | `locus-listing-claim-check` ($0.25) or `locus-listing-claim-batch` ($0.65, 2-3 addresses) | Asking a model to "verify" the numbers from memory, or treating a difference as a misstatement; rent rolls, leases, and OM figures are outside any public record |
+| Drop weak candidate sites early | `locus-record-batch` ($0.05) with free lanes (see the kill-list pattern) | Ranking or scoring sites, or reading a lane with no flag as a good site |
 
 Full inventory decisions: `docs/PAID_TOOL_INVENTORY.md`. Paid index entries also carry `seeAlso` for overlap routing.
 
@@ -344,8 +372,8 @@ Dual-rail routes (a paid `/api/locus-<tool>` with a free `locus_<tool>` counterp
 | `POST /api/locus-electricity-context` | `$0.01` | Data-center, industrial, energy-development, or power-sensitive site screens need HIFLD line proximity plus EIA state price context before utility diligence. | An unresolved point or failure of both source components returns `charged:false`. |
 | `POST /api/locus-insurance-context` | `$0.05` | An insurance question on one address: the parcel FEMA zone with the federal purchase-requirement rule, NFIP policy-cost distribution for the ZIP, ACS homeowners-insurance cost bands, and a county rebuild proxy, in one call. Estimates with vintages, never a quote. | `charged: false` when the point does not resolve or no section returns data. |
 | `POST /api/locus-record-batch` | `$0.05` | A portfolio or any-jurisdiction screen needs up to 6 free record lanes across 2-25 addresses as ONE async job keyed by address; poll `statusUrl`. | Unresolved addresses are listed and never charged; `charged: false` when no address resolves or no valid lane is named. |
-| `POST /api/locus-surrounding-area-analysis` | `$0.10` | Buyer needs one stored multi-lane surrounding packet: topology-aware parcels, zoning, development, permits, legislation, capital/transport, environmental baseline, optional aerial. | Unstable subject, missing surrounding-parcel foundation, or under two completed components returns `charged:false`. |
-| `POST /api/locus-surrounding-area-report` | `$0.15` | HTML+PDF upgrade of an active surrounding-area packet within the 24h upgrade window. | Invalid/expired proof, second report, or render failure does not charge. |
+| `POST /api/locus-listing-claim-check` | `$0.25` | Agent has one address and pasted listing, assessment-notice, or inspection text (or structured claims) to hold against the parcel and permit record. Body: `{"subjects":[{"id":"subject_a","address":"...","mode":"listing","listingText":"..."}]}`. | `charged: false` without cited evidence or when the address does not resolve to one parcel with the requested house number; the document text is never stored or shown. |
+| `POST /api/locus-listing-claim-batch` | `$0.65` | Same, for 2-3 subjects in one settlement. | Billing is binary: `charged: false` unless every subject produced cited evidence. |
 | `POST /api/locus-place-report` | `$0.05` | Agent needs one compiled cited property-context artifact for an address or ZIP. The artifact confirms the matched subject, lists every source, and carries an honest coverage ledger. After confirmed x402 settlement or seller-escrow, the paid parcel-financials lane may include the assessor owner-of-record name for the same exact parcel (cited, not a contact). Canonical storage stays owner-free; settled replay refreshes the official field. | Unsupported or discovery-only places return no-charge diagnostics. |
 | `POST /api/locus-property-update` | `$0.10` | Agent needs an async exact-address decision check of recent or scheduled official-record changes, nearby activity, and physical comparability, with a shareable report, PDF, and temporary video. | Ambiguous, thin, or unsupported inputs return `charged:false`; on `clarification_required`, confirm and resend `retryInput`. Poll the job and, once `flyerReady:true`, use `flyerHandoff` immediately without waiting for video. |
 | `POST /api/locus-solar-property-comparison` | `$1.09` | Agent has exactly three known addresses and wants parcel-bound, dated Google Solar roof metrics beside utility candidates, cited solar-program rows, and one shared GridPulse reference. Input: `{ "addresses": ["...", "...", "..."], "financialZip": "27312", "systemKw": 8 }`. Results stay in input order for side-by-side review; Locus does not select a winner or recommend a property. | Fewer than two attributable Google Solar results return `charged:false`. The price includes up to four Turnkey signatures at the conservative Pay as You Go rate. GridPulse figures remain historical context. Licensed provider data is private, `no-store`, and excluded from public pinning. x402 only. |
@@ -448,7 +476,7 @@ the rule as numbers. Fix what the note names and resend; a refusal is never char
 | The question | Tool | Exact arguments | What it returns |
 |---|---|---|---|
 | Give me one broad free snapshot for this address | `locus_place_facts` | `{ "address": "1 E Edenton St, Raleigh, NC 27601" }` | One-call bundle: parcel facts where wired, FEMA flood zone, governing districts, transportation context, property-tax context where wired, citations, and caveats. Start here when available. |
-| Parcel facts only | `locus_parcel_lookup` | `{ "address": "123 Oak Park Dr, Cary, NC 27519" }` | PII-safe parcel or place facts such as land use, acreage, year built where present, derived county/municipality, provenance. |
+| Parcel facts only | `locus_parcel_lookup` | `{ "address": "123 Oak Park Dr, Cary, NC 27519" }` | PII-safe parcel or place facts such as land use, acreage, year built where present, derived county/municipality, provenance. For neighboring parcels, use free `locus_surrounding_parcels` (see Surrounding parcel context below). |
 | Multiple caller-supplied parcels | `locus_parcel_set` | `{ "addresses": ["addr 1", "addr 2"] }` | Normalized facts for up to 25 supplied addresses in an assemblage. |
 | Which public-record checks should I run before site diligence? | `locus_predevelopment_feasibility` | `{ "address": "...", "projectType": "multifamily" }` | Ordered Locus-tool and official-source plan for parcel/zoning, entitlements, utilities, access, environmental constraints, policy, fees, and permits. Prompt-mode; does not decide feasibility. |
 | Find candidate-site research paths for an area/spec | `locus_development_site_discovery` | `{ "area": "Wake County, NC", "projectType": "industrial" }` | Open-ended candidate-parcel discovery source map. Does not execute searches, select a parcel, or rank sites. |
@@ -460,6 +488,8 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 
 | The question | Tool | Exact arguments | What it returns |
 |---|---|---|---|
+| Fixed-rate payment and carrying-cost worksheet | `locus_property_math_calculator` | `{ "purchasePrice": 500000, "interestRatePercent": 6.5, "annualPropertyTaxRatePercent": 1.2 }` | Monthly principal/interest, tax, insurance and HOA arithmetic, lifetime interest, and optional closing-cost break-even. Defaults to 20% down with a source label; missing tax assumptions stay unknown. Optional location adds tax context and transfer/recording schedule pointers. Not a loan quote or affordability verdict. Also available on the $0.01 `locus-piti-transfer-tax-calculator` route. |
+| Municipal bond and district disclosure sources | `locus_muni_bond_disclosures` | `{ "place": "Wake County, NC" }` or `{ "state": "TX", "county": "Harris" }` | Jurisdiction-verified EMMA, official debt/audit/FAC pointers, bounded TX county levy candidates and source-search queries. Verification describes the place match, not an issuer or fetched filing. State-only input is too coarse. No debt assignment or credit conclusion; use returned Locus next-tool pointers for further research. Also available on the $0.01 `locus-special-district-debt-brief` route. |
 | 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. |
@@ -516,7 +546,7 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | 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). |
 | Data-center or large-development watch prompts | `locus_data_center_watch` | `{ "address": "..." }` or `{ "state": "NC", "county": "Wake County", "municipality": "Raleigh" }` | Bounded official-source query pack and lead-discovery prompts for large projects, data centers, utility/water/planning sources. |
-| Local ordinance and storefront-process leads | `locus_ordinance_leads` | `{ "address": "...", "topics": ["occupancy", "fee_schedule", "signage", "sidewalk_cafe", "published_review_timeline"] }` or `{ "place": "Raleigh, NC" }` | Jurisdiction-locked first-party query pack and reviewed process pointers. Numeric fees/timelines require an exact dated official source; published timelines are guidance, not predictions. Leads only, no restricted code body, not legal advice. |
+| Local ordinance and storefront-process leads | `locus_ordinance_leads` | `{ "address": "...", "topics": ["occupancy", "fee_schedule", "signage", "sidewalk_cafe", "published_review_timeline"] }` or `{ "place": "Raleigh, NC", "liveSearch": true }` | Jurisdiction-locked first-party query pack, reviewed process pointers, and optional operator-enabled Gov-Index pointer discovery (`govIndex`). Numeric fees/timelines require an exact dated official source; published timelines are guidance, not predictions. Leads only, no restricted code body, not legal advice. |
 | Coastal county catalog | `locus_coastal_county_catalog` | `{}` or `{ "county": "new-hanover-nc" }` | Catalog of supported coastal source packs, overlays, source leads, and limitations. |
 
 Temporarily degraded national tools may appear in `lanes.degraded` when an upstream source is failing for every point. If `locus_regulated_facility_compliance` appears there during a future EPA ECHO outage, use `locus_environmental_history` and `locus_toxic_releases` as the functional fallback; if `locus_housing_stock` appears there during a future Census outage, use `locus_fair_market_rents` for housing-cost context meanwhile. Otherwise those tools are callable national lanes.
@@ -525,10 +555,12 @@ Temporarily degraded national tools may appear in `lanes.degraded` when an upstr
 
 | The question | Tool | Exact arguments | What it returns |
 |---|---|---|---|
-| Zoning district and overlays | `locus_zoning` | `{ "address": "..." }` or `{ "latitude": 35.78, "longitude": -78.64 }` | Governing zoning district, overlays/planning context where wired, source links. Rich coverage only in wired jurisdictions. |
+| Zoning district and overlays | `locus_zoning` | `{ "address": "..." }` or `{ "latitude": 35.78, "longitude": -78.64 }`; optional `{ "address": "<NYC street address>", "requestedUse": "restaurant" }` | Mapped district and overlays. If the requested-use pilot is enabled, NYC only: reviewed base-district rule excerpt and a parcel-specific question for `restaurant`, `cafe`, or `detached single family home`. Other uses return `use_not_mapped`; this is never a permission or buildability verdict. |
+| 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. |
 | 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 project: `{ "parcelIds": ["0736544606", "0736845188"], "state": "NC", "county": "Wake" }`; point mode: `{ "city": "chicago", "latitude": 41.878, "longitude": -87.629, "radiusMeters": 1000, "sinceDate": "2025-01-01" }` | 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. 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. |
@@ -542,6 +574,7 @@ Temporarily degraded national tools may appear in `lanes.degraded` when an upstr
 | Appeal or protest deadline arithmetic | `locus_appeal_window` | `{ "address": "...", "noticeDate": "2026-04-01" }` or `{ "state": "Texas", "noticeDate": "2026-04-01" }` | Accepts an address, two-letter state code, or full state name. Returns the cited statutory rule and deterministic UTC date arithmetic for TX, GA, AZ, FL, NC, CO, OH, NJ, WA, CA, NY, IL, MI, TN, and Philadelphia, PA. Never advises whether to appeal. |
 | 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. |
 | 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. |
@@ -555,12 +588,18 @@ Temporarily degraded national tools may appear in `lanes.degraded` when an upstr
 | 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. |
 | 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. |
+| Property-topic government agenda leads (REST-only; not an MCP tool) | `locus-legistar-property-meetings` | Paid x402 `POST /api/locus-legistar-property-meetings` with `{ "jurisdiction": "us-nc-chatham" }` | Five verified Legistar jurisdictions: Chatham County, Chapel Hill, Mecklenburg County, Denver, Seattle. $0.05 on a substantive result; inspect the live challenge and get payment approval first. A 30-minute cached scan inspects up to 10 meetings and 25 items per meeting in the requested month and returns generic topic labels with official links, not raw titles. A lead is not a parcel match, complete agenda, current meeting status, or final decision. |
 | Local legislation preview | `locus_local_legislation` | `{ "address": "...", "ownerActions": ["registration_required"], "domains": ["property_tax"] }` | Recent property-relevant legislation preview, status labels, source attribution. Oklahoma City and Las Vegas use PII-safe PrimeGov source pointers: Locus omits unstructured provider titles and the calling agent opens the cited item before describing it. Optional filters select the one headline before the cap. Not legal advice. |
 | Dated changes around one place | `locus_ownership_loop` | `{ "address": "...", "radiusMeters": 1500, "state": "NC", "countyFips3": "183", "zip": "27601" }` | Composite dated-change bundle across available ownership, tax, flood, transfer, and local lanes. |
 | Coastal overlays | `locus_coastal_county_overlays` | `{ "address": "..." }` or `{ "latitude": 34.22, "longitude": -77.88, "county": "auto" }` | Coastal hazard overlays, parcel/address facts, zoning/flood/wetland/resiliency context for supported coastal counties. |
 | HMDA tract lending context | `locus_hmda_tract_context` | `{ "address": "..." }` | Published tract-level home-purchase counts and median reported property value where a floor-protected FFIEC snapshot is loaded. Area context, not a finding about a borrower, household, or property. Missing and unavailable data stay distinct. |
 | ACS housing stock | `locus_housing_stock` | `{ "address": "..." }` | Census tract housing units, tenure, median rent/value, year built when upstream is healthy. |
 | ZIP industry establishments | `locus_cbp_zip` | `{ "address": "123 Main St, Chapel Hill, NC 27514" }` | Census 2023 County Business Patterns counts by broad 2-digit NAICS industry for the address ZIP. A ZIP is area context, not the premises, customers, sales, or a location recommendation; unavailable data is not zero. |
+| County living arrangements by year | `locus_acs_living_arrangements_series` | `{ "stateFips": "37", "countyFips3": "183", "fromYear": 2022, "toYear": 2024 }` | ACS five-year 18–34 household-member and child-of-householder counts with margins and explicit gaps. Overlapping windows are not independent annual change; child-of-householder is not every adult living with parents. |
+| County industry establishments by year | `locus_cbp_county_industry_series` | `{ "stateFips": "37", "countyFips3": "183", "industryCode": "31-33", "fromYear": 2022, "toYear": 2024 }` | Caller-selected industry size and subsector counts, not jobs or orders. 2024 CBP is not yet published by this source: expect a `not_published` gap, not zero. Suppressed cells are not zero either. |
+| Office source discovery | `locus_office_source_guide` | `{ "stateFips": "37", "countyFips3": "183" }` | Leads for dated office reports and measurement cautions; no vacancy or occupancy observations. Confirm market boundary, class, definition, date, and reuse terms before comparing reports. |
+| Official fiscal document discovery | `locus_fiscal_source_guide` | `{ "place": "Raleigh, NC" }` | National and resolved local budget, audit, and tax-base leads. Empty `observations[]` is expected because documents are not fetched; use the parsing guide and cite your own extracted figures separately. |
 | Area eviction filing counts | `locus_eviction_filings` | `{ "address": "..." }` or `{ "latitude": 35.78, "longitude": -78.64 }` | Published Eviction Lab weekly tract and Legal Services Corporation monthly county filing aggregates, each with a date and source. Area context only; never use to screen a tenant, landlord, household, or property. |
 | EPA facility compliance | `locus_regulated_facility_compliance` | `{ "address": "...", "radiusMeters": 5000 }` | EPA ECHO facility compliance and inspection/enforcement summary when upstream is healthy. It links to paid `locus-nei-emissions-nearby` for NEI detail. |
 
@@ -615,8 +654,11 @@ or legal verdict.
 2. `locus_satellite_scene_availability { "bbox": <from retryInput>, "fromDate": ..., "toDate": ... }`
    lists dated Sentinel-2 scenes with cloud cover (downtown Raleigh: 0 % cloud scenes on
    2026-01-04, 2026-04-21, 2026-05-19).
-3. `locus_metro_permits { "address": ... }` returns permits within 500 m for the last 12 months with
-   `workclass`, `proposeduse`, `estprojectcost`, `pin`, and street (23 permits in the test).
+3. For permits near the scene, call `locus_metro_permits` in point-radius mode with
+   `{ "city": "raleigh", "latitude": <scene center latitude>, "longitude": <scene center longitude>, "radiusMeters": 500 }`.
+   An exact address instead uses `{ "place": "<address>" }` and selects the parcel's legal permitting
+   authority; it is **not** a 500 m search. Point mode defaults to a one-year lookback, but returned
+   fields and record counts depend on the city's published source.
 4. Keep only permits that could show from above at 10 m: `New Building`, `Addition`, demolition,
    or a large cost. Interior alterations, repairs, and change-of-use never show. A bounded
    judgment model (one yes/no per permit) sorted the 23 cleanly: a new school building
@@ -692,9 +734,13 @@ text itself is never echoed in the response). Not every
 catalogue reading can fire today: the `catalogue` block says how many readings are currently
 evaluated and how many are gated off pending a slot adapter or confirming-record fetch
 (`readingsNotEvaluated` lists those, with reasons). Expect 20 to 40 s
-cold, under 10 s on a cached parcel (6 h record-bundle cache); set a 90 s client timeout, and read
-the `timing` block (`totalMs`, `recordsCached`, per-stage ms) and the
-`x-locus-recommended-timeout-ms` header. Each reading
+cold, under 10 s on a cached parcel (6 h record-bundle cache); allow at least 60 seconds,
+set a 90 s client timeout, and honor the `x-locus-recommended-timeout-ms` header.
+If disconnected, retry the same request for the same payer with fresh valid payment within
+15 minutes: the finished result is held for reuse, but is never returned without valid
+payment. The disconnected run is not charged; the retry settles once after delivery.
+A different request or payer cannot reuse that result. Read the `timing` block (`totalMs`,
+`recordsCached`, per-stage ms). Each reading
 carries `status` (`matched` when every confirming record is present, `partial` naming the
 missing record), the fixed reading text, `recordRefs`, and `checkNext`. `readingsNotEvaluated`
 lists catalogue readings Locus could not test here and why. Use it after the free lanes, not
@@ -717,6 +763,18 @@ draws no conclusion about capacity, quality, or the effect of any permitted use.
 covered metro, `permitMix.available` is false and the six readings are listed under
 `readingsNotEvaluated`.
 
+### 5. "Which candidate sites can I drop early?" (kill-list, not a ranking)
+
+Use this when the user holds a list of 2-25 candidate addresses (land, teardowns, small commercial) and wants to stop spending time on sites that a public record already rules out for their use.
+
+1. Ask for the one or two hard filters the user already has (for example "not in a mapped flood zone", "no mapped wetlands on the point", "zoning must allow my use class"). Do not invent filters and do not weight them.
+2. Submit the list once: `locus-record-batch { "addresses": [...], "lanes": ["locus_parcel_lookup", "locus_zoning", "locus_flood_zone", "locus_wetland_context"] }` (up to 6 free lanes; add `locus_tax_distress` or `locus_soil_context` only if the user asked). Poll `statusUrl`.
+3. For each address, read the lanes and list only records that touch a stated filter, each with its citation and date. Example line: "Mapped in a FEMA flood zone at the point (FEMA NFHL, fetched 2026-09-29): verify the parcel boundary and elevation before dropping or keeping."
+4. Split the answer into three lists: **has a record that touches your filter**, **no such record found in the lanes checked**, and **could not check** (lane error, unresolved address, out of coverage). Never merge the last two; a lane with no flag is not a good site.
+5. Confirm identity before trusting a parcel lane: the parcel address returned should carry the candidate's house number. A point match can land on a neighboring lot.
+6. If a candidate came with a listing or offering text, run `locus-listing-claim-check` on the few survivors to hold its area, year built, and permit claims against the record. Rents, leases, and OM numbers stay unchecked.
+7. Say what this is not: no score, no rank, no "best site", no buildability, value, or use approval. The user makes the keep-or-drop call.
+
 ## A2A call shape
 
 ```json
@@ -761,6 +819,30 @@ curl -X POST https://api.locus.report/tools/call \
 
 Browse the free catalog with `curl https://api.locus.report/tools/list`; every entry also appears as a `/api/<tool_name>` path in the generated OpenAPI. Keep the two body shapes straight: flat fields for `/api/locus_*`, `{name, arguments}` for `/tools/call`. A flat body sent to `/tools/call` returns `wrapped_body_required` with the correct shape.
 
+## Permit activity discovery
+
+The former `locus-permit-activity` capability is now the **free** `locus_metro_permits` tool.
+Search for “building permits”, “permit activity”, or “contractors working nearby” with
+`locus_search_tools`, then use `locus_execute` or `POST /tools/call` with that exact catalog name.
+Use the x402-paid `locus-metro-permits` dual only when a client specifically needs the paid rail;
+do not pay to discover or read records available through the free tool.
+
+```json
+{"name":"locus_metro_permits","arguments":{"place":"1 E Edenton St, Raleigh, NC 27601"}}
+```
+
+For a supported city's nearby search, pass `city`, `latitude`, `longitude`, and optionally
+`radiusMeters` (50–3000), `sinceDate` (`YYYY-MM-DD`), `order` (`newest` or `nearest`), and
+`maxRecords` (1–100, default 25). For recurring point checks, send the prior response's
+`polling.nextSince` as `sinceDate` and previously seen permit IDs as `excludePermitIds`;
+`polling.nothingNew` means no new matching records in that check, not no permit activity.
+Chicago, New York City, Austin, and Seattle additionally support `minReportedCostUsd`,
+`trade`, and `scope` filters and published contractor-company fields. Read the live schema
+for allowed trade and scope values. An exact parcel lookup uses `place` or `parcelId`/
+`parcelIds` with `state` and `county`, not `address`. Use `locus_lane_availability` to
+check coverage; an empty or unavailable source is not evidence that no permits exist.
+Permit statuses are published workflow fields, not construction or compliance findings.
+
 ## MCP call pattern
 
 1. Call `locus_search_tools` with the user intent, place, and known source category.
@@ -778,6 +860,55 @@ Browse the free catalog with `curl https://api.locus.report/tools/list`; every e
 
 Use the argument key from the tool schema. Do not send every place as `place`; many tools require `address`, `state` plus `county`, or FIPS fields.
 
+### Setting up dynamic real estate MCP Events (Poll & Signed Webhooks)
+
+Both MCP harnesses (via protocol JSON-RPC `events/list`, `events/poll`, `events/subscribe`, `events/unsubscribe` per SEP-3415) and models inside `tools/call`-only clients (via `locus_mcp_events_catalog` and `/muse/mcp` tools `list_event_types`, `poll_events`, `subscribe_event`, `unsubscribe_event`, `list_event_subscriptions`) can dynamically set up, poll, and subscribe to cited public-record 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.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.watch.digest_sent` | `{ "poolId": "<optional-uuid>" }` | Privacy-preserving digest count (`{ "changeCount": N }` only; no addresses or raw records). |
+
+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`.
+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:
+   ```json
+   {
+     "name": "locus.real_estate.changes_detected",
+     "arguments": {
+       "addresses": ["615 Hillsborough St, Raleigh, NC 27603"],
+       "lanes": ["locus_metro_permits", "locus_zoning", "locus_flood_zone"],
+       "includeUpcomingDays": 60
+     },
+     "cursor": "cur_..."
+   }
+   ```
+   - On `/muse/mcp`, calling `poll_events` with `"deliverWebhooks": true` also runs a bounded webhook delivery sweep for the authenticated principal's active subscriptions.
+3. **Subscribe to signed Standard Webhooks (`events/subscribe` or `subscribe_event`):**
+   - Connect to `https://mcp.locus.report/muse/mcp` (OAuth 2.1 with `pools events:subscribe` scopes) or pass `Authorization: Bearer lmc_...`.
+   - Provide a public HTTPS `delivery.url` (query parameters such as `?mcp_event_subscription=...` are preserved) and a Standard Webhooks signing secret (`whsec_<base64-of-24-to-64-bytes>`):
+   ```json
+   {
+     "name": "locus.real_estate.deadline_approaching",
+     "arguments": {
+       "addresses": ["615 Hillsborough St, Raleigh, NC 27603"],
+       "horizonDays": 30,
+       "basis": ["statutory", "as filed"]
+     },
+     "delivery": {
+       "mode": "webhook",
+       "url": "https://receiver.example.com/webhooks/locus",
+       "secret": "whsec_..."
+     }
+   }
+   ```
+   - **Synchronous challenge handshake:** Before storing the subscription, Locus POSTs `{ "type": "verification", "challenge": "<uuid>" }` signed with Standard Webhooks headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`, `X-MCP-Subscription-Id`). The receiver must verify the HMAC-SHA256 signature (`v1,<base64>` over `${webhookId}.${timestamp}.${rawBody}`) and return HTTP 2xx with `{ "challenge": "<uuid>" }` within 5 seconds.
+   - **Event deliveries:** Each occurrence POST sets `webhook-id` equal to `event.eventId` (`evt_<sha256>`). Verify `webhook-signature` and `webhook-timestamp` before trusting the payload, deduplicate by `eventId`, and use `list_event_subscriptions` or `events/unsubscribe` (`unsubscribe_event`) to inspect or remove subscriptions. Never treat an event notification as payment authorization or a safe/unsafe verdict.
+
 <!-- satellite-input-guide:start -->
 ### Prepare a satellite imagery purchase
 
@@ -817,10 +948,11 @@ weeks ago. Call `resources/list` and read any whose URI starts with
 | `skill://locus/choosing-a-locus-tool` | Picking a tool. Search first, free lanes before paid, and the no-verdict boundary. |
 | `skill://locus/reading-locus-coverage` | Reporting an empty result. Distinguishes `out_of_coverage`, `source_unavailable`, and a genuine empty. |
 | `skill://locus/locus-place-workflow` | Any multi-tool question about a place. The resolve to preflight to fan-out to compose order. |
+| `skill://locus/subscribing-to-locus-events` | Setting up, polling, or subscribing to dynamic real-estate MCP Events (`events/list`, `events/poll`, `events/subscribe`, `events/unsubscribe`, `poll_events`, `subscribe_event`), Standard Webhooks verification, and paid follow-up boundaries. |
 
 This follows the draft Skills Extension (SEP-2640), so the capability is
 advertised under `experimental` as `io.modelcontextprotocol/skills`. A client
-that does not know the extension still sees four ordinary markdown resources and
+that does not know the extension still sees five ordinary markdown resources and
 can read them normally.
 
 These resources are guidance, never authorization. Free, paid, and admin
@@ -839,7 +971,7 @@ changes what a call is allowed to do.
 
 ## x402 payment flow
 
-The paid catalog includes native products, promoted free duals, and the seven paid-only atomics listed above. Native tools use the transports listed in their catalogs. The seven paid-only atomics are REST-only.
+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.
 2. **MCP:** use only paid entries present in the MCP catalog. Call `locus_execute`, then retry with `_meta["x402/payment"]` when challenged.