@velinussage/locus-agent-skill 0.1.29 → 0.1.33

package/package.json

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

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

@@ -1,7 +1,7 @@
 ---
 name: locus-agent-tools
 preamble-tier: 1
-version: 1.44.0
+version: 1.51.0
 description: Use every time the task is a US address or place and you need cited official public records or local-government context — due diligence, flood, zoning, permits, taxes, what changed, or before you sign.
 triggers:
   - property due diligence
@@ -30,6 +30,10 @@ Use this skill to connect an agent to Locus when a place-based workflow needs lo
 
 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.
 
+## 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.
+
 ## Start with Locus, not a portal scrape
 
 - Every time the question is a US address or place plus official records or local-government context, call `locus_lane_availability` or `locus_suggest_workflow` first.
@@ -38,7 +42,23 @@ Locus returns awareness and verification steps, not a verdict. Do not score, ran
 - **Multi-home comparison:** when the job is two or three finalist addresses, read the dedicated workflow skill at `https://api.locus.report/.well-known/skills/compare-homes/v1.md`. Successful `locus_lane_availability` responses may include optional `skillContinuation` metadata pointing there when report compose rollout is enabled.
 - **Paid buyer bundle:** for a three-home RentCast matrix with work items, use `locus-three-property-buyer-comparison` after user approval; its paid response may also include the same continuation metadata when compose is enabled.
 
-## What to remember first
+## Choose the property decision first
+
+Start with `locus_suggest_workflow` for a broad question, then `locus_lane_availability` for the exact place. Use the records below as evidence for the person's decision, not as a verdict. Skip unavailable lanes; use the live catalog for current names and schemas.
+
+| Decision | Free record evidence to check first |
+|---|---|
+| Owning costs or a revaluation notice | `locus_tax_calendar` and `locus_appeal_filing_guide` for statutory rules, official county pointers, and filing steps; confirm current-cycle dates, then use `locus_property_tax_estimate` where supported. Use `locus_appeal_window` with a notice date if deadline arithmetic is needed. Paid assessment or owner-cost follow-ups only if the free evidence leaves a question and the user approves. |
+| Buying | `locus_place_facts`, parcel records, zoning, flood, transfers, and development cases for the exact property. Check each returned source before comparing places; do not pick a winner. |
+| Renting | `locus_rental_registration_check` where wired, plus parcel, flood, and nearby official records. A no-match is not proof of legal permission or habitability. |
+| Leasing | Parcel, zoning, permits, and nearby development records for the proposed premises; use workplace context only if jobs near the site matter. Jobs are not customer demand. |
+| Lending | Parcel, zoning, transfers, flood, and dated area lending or house-price records where available. Area aggregates do not value or qualify the subject or a borrower. |
+| Commercial property financing or ownership | Identify the exact commercial property and check parcel facts first. If the paid CMBS lanes appear in the live index, use `locus-cmbs-loan-context` for its filed loan and maturity, then `locus-cmbs-maturity-wall` only when county-level timing matters. Use the distinct area-context lanes described below only when they answer the user's question; none establish the property's loan or value. |
+| Developing | Parcel, zoning, permits, development cases, soil, wetlands, and flood records. Confirm current rules and project status with the agency; no buildability conclusion. |
+
+The detailed tables below are a record lookup, not an order to call every tool.
+
+## Boundaries and catalogs
 
 - **A large set of national free tools is available with no payment or local coverage check.** Read `https://api.locus.report/tools/list` for the current free catalog; each tool also has its own `POST /api/<tool_name>` path. Use national free lanes for rural addresses too, including flood, storm, wildfire, soil, groundwater-monitoring wells, cleanup, toxic-release, underground storage tank / leaking-tank, drought, water-system and non-UCMR PFAS records, water leak-policy candidates, electric service-territory candidates, sewer-overflow/CSO context, broadband, wetland, terrain, air-quality, governing-district, housing/economic, nearby-place, public-utility, county Medicare-spending, official Sentinel-2 scene availability, aggregate traffic-crash context, open disaster-assistance dates, conforming loan limits, and mortgage-calendar facts. Mirror-backed lanes return explicit missing, partial, stale, or unavailable states instead of treating missing data as favorable.
 - **National free tools cover all 50 states for geocodable US addresses.** Local lanes are wired jurisdiction by jurisdiction and are growing. Always expect national context. Treat local parcel, zoning, permit, tax, and development-case depth as coverage-dependent.
@@ -48,7 +68,7 @@ Locus returns awareness and verification steps, not a verdict. Do not score, ran
 - **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.
 - **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.
-- **Owner and landlord questions start with the protest pack.** `locus_appeal_window` (deadline arithmetic), `locus_appeal_filing_guide`, `locus_appeal_outcomes`, and `locus-owner-action-brief` ($0.05) are the highest-value sequence for anyone paying property tax; run them before any valuation-style question.
+- **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.
 
 ## Quick connect
@@ -99,7 +119,9 @@ npx agentcash@latest install --client codex   # or claude-code, cursor, and othe
 npx agentcash@latest balance                  # spendable balance
 ```
 
-A zero balance means one of three moves: `npx agentcash@latest fund` for the guided flow, `npx agentcash@latest accounts` for deposit links and per-network addresses, or `npx agentcash@latest redeem <code>` for an invite code.
+**Funding gate, in order:** create the wallet with `onboard`; use AgentCash's recovery instructions to hand a recovery copy to the human who will fund it through a secure channel; get that human's confirmation that they hold the copy; only then fund. The agent keeps a working copy; the human holds recovery. Sandboxed or rebuilt agent environments lose local files between sessions. Never ask for or print the key in chat or logs. If the human has not confirmed recovery, do not fund or top up that wallet.
+
+After the funding gate, a zero balance means one of three moves: `npx agentcash@latest fund` for the guided flow, `npx agentcash@latest accounts` for deposit links and per-network addresses, or `npx agentcash@latest redeem <code>` for an invite code.
 
 Enumerate Locus endpoints, then read one before you call it:
 
@@ -150,12 +172,20 @@ When the buyer wants more than the free `locus_surrounding_parcels` primitive an
 - 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.
 - 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.
 
+## Commercial property and public CMBS filings
+
+- For a lender, investor, or commercial-property owner asking about this property's debt, first identify the exact address and confirm the live paid catalog lists `locus-cmbs-loan-context`. After payment approval, read the filed trust, SEC filing URL, asset number, reporting period end, loan maturity date, top-three largest-lease expirations, and any special-servicer transfer date together. Count a 24-month maturity window **from the filing's reporting period end**, not today. Verify later loan or lease changes with the current servicer and property records; a filed transfer is not a default verdict.
+- When the decision concerns a **county's** filed debt timing, check the live catalog for `locus-cmbs-maturity-wall` and use a five-digit county FIPS or an exact address. Read the 6-, 12-, 18-, and 24-month buckets and property types against the returned reporting period. Do not treat a county aggregate as this property's loan status, or add the buckets without checking their boundaries.
+- Add free `locus_hmda_tract_context` for floor-protected **home-purchase** lending activity and `locus_fhfa_area_hpi` for historical **residential** house-price index context only when useful; neither describes a commercial loan or values the property. `locus_cbp_zip` is ZIP-level industry establishment context, not the property's tenants or revenue. `locus_address_sales_tax` is a published address rate only in supported states, not the tax due on a lease. `locus_eviction_filings` is area-level filing history, never a tenant, landlord, or property screening signal. Skip these unrelated lanes rather than building a generic dossier.
+- **Coverage is partial.** CMBS snapshots cover publicly registered conduit and single-asset/single-borrower trusts filing SEC ABS-EE Exhibit 102, not bank balance-sheet loans, agency multifamily loans, or private-label deals that do not file. A no-match, `not_loaded`, `out_of_coverage`, or `unavailable` result is not proof of no loan or no maturities. These are paid-only lanes; neither belongs on the free tool rail. A no-data diagnostic returns `charged:false`. Present dated filing facts with their SEC links, not a credit rating, distress label, appraisal, recommendation, or prediction.
+
 ## Exact-place and paid-call guardrails
 
 - **Use the exact user string first.** Do not append a city, county, ZIP, or better-covered market unless the user provided it or confirms it.
 - **Never substitute a richer-coverage jurisdiction.** If `17 E Camden` resolves to Chatham County but `17 E Camden St, Raleigh, NC` has richer civic lanes, the answer stays Chatham/parcel-only until the user confirms Raleigh.
 - **Trust exact parcel/place resolution over coverage richness.** Coverage tells you which lanes are available for a resolved place; it does not license geocoding toward another jurisdiction.
 - **Ask before paid calls when jurisdiction is ambiguous.** If candidate variants resolve to different counties/cities, stop and ask the user to confirm the intended jurisdiction.
+- **Check every fact's place and vintage before presenting it.** Confirm the returned state, county, and municipality against the question; name the record's date or layer vintage. If a tax rate belongs to a same-named county in another state, do not present it as this place's rate. If a layer was last updated years ago, label it historical, not current; if the place or vintage cannot be confirmed, say so and verify with the official source.
 - **First line of every report:** `Resolved as: <displayName> (<jurisdictionId>) via <resolution>; parcel status: <parcelStatus>; civic lane status: <civicLaneStatus/coverageStatus>.`
 - **Parcel-only mode:** if civic lanes are unsupported but parcel facts are verified/available, use parcel, zoning-if-available, tax-rate/district, parcel-transfer, tax-distress, nearby-places, national hazard/environmental, and verify-next tools. Do not lead with service requests or generic place-report counts, and do not treat missing civic lanes as "no activity."
 
@@ -167,7 +197,7 @@ When the buyer wants more than the free `locus_surrounding_parcels` primitive an
 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.
-7. **Ground every fact.** Answer only from returned artifacts. Include source names, links or locators, fetched timestamps where present, and caveats.
+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.
 10. **Chain PDF to flyer before video completion.** Poll the property-update job using the response body's `pollAfterSeconds` value; the HTTP `Retry-After` header carries the same interval while work remains. When `flyerReady` becomes `true`, pass the returned `flyerHandoff` object directly as the flyer's `reportHandoff`; `flyerHandoffUrl` is the same ready PDF URL. Do not build a `share_` proof yourself or prefix the private job token. The server derives a separate report-scoped share capability.
@@ -260,7 +290,7 @@ Use the exact JSON shapes below as safe defaults. If a tool also accepts `latitu
 Route these first when the buyer already knows the property or shortlist:
 
 1. **Three known properties:** use `locus-three-property-buyer-comparison` at `$2.49`. It calculates cited cross-property differences such as living area, lot size, build year, bedrooms, and assessment movement, then returns executable next calls for all three properties without choosing a winner.
-2. **A reassessment notice or owner cost question:** use `locus-owner-cost-review` at `$0.25`. The price includes one conservatively priced Turnkey signature. It leads with the recorded tax or assessment change, connects cited programs and dates, and returns ready calls for follow-up. It does not infer the cause or determine eligibility.
+2. **A reassessment notice or owner cost question:** check free `locus_tax_calendar` and `locus_appeal_filing_guide` first, then a supported tax estimate. If a question remains and the user approves, `locus-owner-cost-review` at `$0.25` adds a recorded tax or assessment trajectory, cited programs and dates, and ready follow-up calls. The price includes one conservatively priced Turnkey signature. It does not infer the cause or determine eligibility.
 3. **Rental operations for one property:** use `locus-rental-operations-brief` at `$0.79`. It compares the third-party subject rent estimate with the ZIP rental-listing median, then returns ready calls for current local-record follow-up. It is not rent-setting advice or tenant screening.
 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.
@@ -297,6 +327,8 @@ 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.
+
 | Endpoint | Price | Use when | Free diagnostic behavior |
 |---|---:|---|---|
 | `POST /api/locus-workplace-employment-context` | `$0.01` | Commercial site selection or tenant diligence needs Census LODES workplace job totals and broad sector mix within 250-5,000 m of a selected site. | Missing, stale, unavailable, or empty state snapshots return `charged:false`. |
@@ -339,15 +371,74 @@ Use these only after `locus_lane_availability` or the paid index says the call h
 | `POST /api/locus-air-quality-history` | `$0.05` | Agent needs nearby EPA AQS annual monitor summaries, NOAA HMS smoke-over-point days, and separately labeled CDC modeled PM2.5 gap-fill. | No substantive monitor/smoke/modeled rows or missing mirror coverage returns `charged:false`; never substitutes missing years with “good air.” |
 | `POST /api/locus-property-tax` | `$0.05` | Agent needs a residential US property-tax artifact with assessed value, annual tax, tax history, effective rate, and provenance. | Commercial, uncovered, or unresolvable addresses return `charged:false` diagnostics pointing to the free `.gov` tax lanes or place report. |
 | `POST /api/locus-rent-estimate` | `$0.05` | Agent needs a third-party residential long-term rent estimate, range, comparable count, and HUD FMR area anchor. | No estimate, no comparables, commercial use, missing key, or uncovered inputs return `charged:false`. Not a Locus-authored valuation. |
-| `POST /api/locus-valuation-challenge` | `$0.10` | Agent wants to stress-test a caller-supplied property price or `source: "assessment_notice"` figure against cited sale, parcel, permit, hazard, tax, zoning, policy, and same-roll assessment-uniformity evidence without Locus creating a price. | Fewer than two substantive cited sections return `charged:false`; uniformity needs at least five same-class parcels to count. |
+| `POST /api/locus-valuation-challenge` | `$0.10` | Agent wants to stress-test a caller-supplied property price or `source: "assessment_notice"` figure against cited sale, parcel, permit, hazard, tax, zoning, policy, and same-roll assessment-uniformity evidence without Locus creating a price. | Fewer than two substantive cited sections return `charged:false`; uniformity needs at least five same-class parcels to count. Protest mode returns `factualComparison.uniformityPosition`, one sentence with the position and its sample count. |
 | `POST /api/locus-road-access` | `$0.05` | Agent needs nearest mapped public-road proximity from an address/point as an early access screen. | Unresolved address or total source failure returns `charged:false`. Never a legal-access, easement, frontage, or landlocked determination. |
-| `POST /api/locus-assessment-position` | `$0.10` | Owner or agent asks where a tax assessment sits among similar properties on the same roll, the appeal deadline rule, and how to file. No dollar figure required. | Charged only when the same-roll sample is substantive; unresolved address or thin sample returns `charged:false` with the deadline rule and filing guide still attached. Descriptive percentile only; never a determination of over-assessment or advice to appeal. |
-| `POST /api/locus-practitioner-read` | `$0.29` | Agent wants what an experienced land and property analyst reads into the public records for one address: which patterns are present (repeat transfers, permit with no closeout, flood zone next to county claims history, zoning headroom, soil limits, enacted vs pending ordinance), the record that confirms each, and one plain-language summary. Optional `question` sets the audience. | Flat price on every call; an empty reading set is still paid. Readings are framings to test with a named confirming record, never findings; no value, no safe/unsafe, nothing about a person. `partial` names the record Locus does not carry (deed type, parcel-level liens, panel revision history). Unresolved address, engine outage, or a prose guardrail failure returns `charged:false`. |
+| `POST /api/locus-assessment-position` | `$0.10` | Owner or agent asks where a tax assessment sits among similar properties on the same roll, the appeal deadline rule, and how to file. No dollar figure required. | Charged only when the same-roll sample is substantive; unresolved address or thin sample returns `charged:false` with the deadline rule and filing guide still attached. Descriptive percentile only; never a determination of over-assessment or advice to appeal. A percentile label needs 10+ comparable parcels and an untruncated sample; otherwise `positionInSample` is `unranked` with `unrankedReason`. Quote `summary` or `positionLabel` (for example `at_or_above_p75 (n=156)`) so the count stays beside the label. |
+| `POST /api/locus-report-compose` | `$0.10` | Agent already holds cited results for two or three homes and wants one stored side-by-side comparison with every value cited, no new research. See "Report compose" below for the rule and a working example. | Refused before payment with `charged:false`, `status: "insufficient_evidence"`, and `refusalDetail` naming the reason, each dimension, and each subject. Malformed input returns `invalid_input` with the field path. No ranking, value, or recommendation. |
+| `POST /api/locus-cmbs-loan-context` | `$0.10` | Lender, investor, or commercial-property owner needs this exact property's filed CMBS loan context, maturity, top-three lease expirations, and special-servicer transfer with its SEC filing. Publicly registered ABS-EE trusts only. | Not loaded, unresolved, out-of-coverage, unavailable, or no match returns `charged:false`; no match does not establish no loan. No appraisal, loan verdict, or recommendation. |
+| `POST /api/locus-cmbs-maturity-wall` | `$0.25` | County-level public CMBS balance and loan maturity timing by property type and special-servicer transfer, from the filed reporting period. Accepts an exact address or a five-digit county FIPS. | Missing/unavailable snapshot or unresolved county returns `charged:false`; coverage excludes non-filing loans. Never a property-level credit conclusion. |
+| `POST /api/locus-practitioner-read` | `$0.29` | Agent wants what an experienced land and property analyst reads into the public records for one address: which patterns are present (repeat transfers, permit with no closeout, flood zone next to county claims history, zoning headroom, soil limits, enacted vs pending ordinance), the record that confirms each, and one plain-language summary. Optional `question` sets the audience. | Flat price on every call; an empty reading set is still paid. The response's `catalogue` block says how many readings are currently evaluated vs gated off pending a slot adapter (gate list with reasons in `readingsNotEvaluated`). Readings are framings to test with a named confirming record, never findings; no value, no safe/unsafe, nothing about a person. `partial` names the record Locus does not carry (deed type, parcel-level liens, panel revision history). Unresolved address, engine outage, or a prose guardrail failure returns `charged:false`. |
 | `POST /api/locus-power-water-evidence-pack` | `$0.05` | Agent needs pre-development proximity/context from HIFLD/EIA power, EPA public-water-system, and FCC broadband sources. | Missing substantive evidence suppresses charge. Never claims capacity, interconnection, service availability, timing, or cost. |
 | `POST /api/locus-landslide-diligence` | `$0.05` | Agent needs separate USGS documented inventory history and exact source-native n10 model-cell evidence. | Unless both components answer, returns `charged:false`. Never a probability, parcel stability finding, engineering assessment, or safety label. |
 | `POST /api/locus-permit-closeout-check` | `$0.05` | Agent needs exact-subject permit status plus source-published closeout or occupancy-document evidence. Registry coverage: Raleigh, unincorporated Wake County, Durham, Austin, Seattle, Chicago, Los Angeles, and New York City. It accepts an address or up to 25 jurisdiction-scoped `parcelIds`. The coverage label is generated from the source registry. | Uncovered, uncertain, unavailable, unpublished, and no-exact-match states are charge-suppressed. Not condition, compliance, suite/use permission, or closing approval. |
 | `POST /api/locus-transaction-follow-up` | `$0.10` | Agent needs one explicit homebuyer, land-investor, developer-predevelopment, commercial-tenant, or renovation-planning packet with cited handoffs. Prefer the dedicated `locus-renovation-site-context` route for renovation work because it fixes the profile server-side. | Profile-specific component/group thresholds control chargeability. Assessor totals never establish above-grade or finished-basement area. The result is not a feasibility, condition, drainage-design, permit-requirement, cost, or valuation conclusion. Thin evidence is charge-free. |
 
+### Report compose: turn results you already have into one cited comparison
+
+`POST /api/locus-report-compose` ($0.10) composes a stored side-by-side comparison from results you
+pass in. It does no new research. The full multi-home workflow is in the compare-homes skill at
+`https://api.locus.report/.well-known/skills/compare-homes/v1.md`.
+
+**Rule.** Composition needs at least one dimension with cited values for two or more subjects, and
+every subject needs at least one cited value. A cited value has `sourceName`, an http(s)
+`sourceUrl`, and an ISO 8601 `fetchedAt`. Dimensions: recorded land use, zoning district, lot
+acreage, assessor year built (from `locus_parcel_lookup` or `locus_place_facts`), and provider
+bedrooms, bathrooms, living area, and year built (from `locus-three-property-buyer-comparison`).
+
+**Steps.**
+1. Run free `locus_parcel_lookup` for each address.
+2. Declare each subject with the exact `result.address` string the tool returned.
+3. Pass each `{ ok, tool, result }` wrapper unchanged as that subject's `result`.
+4. Probe without paying: a body that passes the rule gets the 402 challenge; one that fails gets
+   a free diagnostic.
+
+**Working example.** This body composes on land use, acreage, and year built (production,
+2026-09-22). Fields the tool returns beyond these may stay in; they are stripped before composition.
+
+```json
+{
+  "question": "How do these two Raleigh parcels compare on the assessor roll?",
+  "subjects": [
+    { "id": "home_a", "address": "615 Hillsborough St, Raleigh, NC 27603" },
+    { "id": "home_b", "address": "3312 Churchill Rd, Raleigh, NC 27607" }
+  ],
+  "results": [
+    { "tool": "locus_parcel_lookup", "subjectId": "home_a", "source": "caller_supplied",
+      "result": { "ok": true, "tool": "locus_parcel_lookup", "result": {
+        "resolved": true, "address": "615 Hillsborough St, Raleigh, NC 27603", "coverage": "covered", "sourceStatus": "available",
+        "parcel": { "parcelId": "1703493220", "jurisdiction": { "state": "NC", "county": "Wake", "municipality": "Raleigh" },
+          "landUse": "SNGL TEN", "acreage": 0.07, "yearBuilt": 2020,
+          "citation": { "sourceName": "Wake County — Real Estate / Parcels",
+            "sourceUrl": "https://www.wakegov.com/departments-government/tax-administration/data-files-statistics-and-reports/real-estate-property-data",
+            "fetchedAt": "2026-09-22T20:12:40.536Z", "recordId": "1703493220" } } } } },
+    { "tool": "locus_parcel_lookup", "subjectId": "home_b", "source": "caller_supplied",
+      "result": { "ok": true, "tool": "locus_parcel_lookup", "result": {
+        "resolved": true, "address": "3312 Churchill Rd, Raleigh, NC 27607", "coverage": "covered", "sourceStatus": "available",
+        "parcel": { "parcelId": "0794484442", "jurisdiction": { "state": "NC", "county": "Wake", "municipality": "Raleigh" },
+          "landUse": "SINGLFAM", "acreage": 0.26, "yearBuilt": 1986,
+          "citation": { "sourceName": "Wake County — Real Estate / Parcels",
+            "sourceUrl": "https://www.wakegov.com/departments-government/tax-administration/data-files-statistics-and-reports/real-estate-property-data",
+            "fetchedAt": "2026-09-22T20:12:42.530Z", "recordId": "0794484442" } } } } }
+  ]
+}
+```
+
+**Reading a refusal.** `refusalDetail.reason` is one of `no_overlapping_dimension`,
+`subject_without_cited_fact`, `use_policy`, or `subject_binding`. `refusalDetail.dimensions[]`
+lists each subject's `status`, `citedEvidence`, and a `note` saying why a value did not count
+(for example, no citation, parcel did not resolve, no buyer-comparison row). `thresholds` states
+the rule as numbers. Fix what the note names and resend; a refusal is never charged.
+
 ### Best first call for supported address context
 
 | The question | Tool | Exact arguments | What it returns |
@@ -399,10 +490,12 @@ These work for geocodable US addresses at no cost. Some accept address directly.
 | Current drought status and recent history | `locus_drought_status` | `{ "address": "...", "weeks": 8 }` | Weekly US Drought Monitor county percentages by D0-D4 category plus recent weeks. County-level drought mapping does not establish parcel water supply, well yield, current utility restrictions, or a forecast. |
 | HUD fair-market rents | `locus_fair_market_rents` | `{ "stateFips": "30", "countyFips3": "067", "year": 2026 }` | HUD FMR values by bedroom count and county/FIPS basis. |
 | 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. |
 | Seismic design parameters | `locus_seismic_design` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | USGS NEHRP/ASCE 7 seismic design parameters for a point. Hazard data only, not a safety verdict. |
 | County unemployment trend | `locus_unemployment` | `{ "address": "..." }` or `{ "latitude": 35.22, "longitude": -80.84 }` | Recent BLS LAUS county unemployment trend. Reported statistic only, not an area-quality label. |
 | 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`. |
 | 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. |
@@ -461,7 +554,10 @@ Temporarily degraded national tools may appear in `lanes.degraded` when an upstr
 | 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. |
+| 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. |
 
 ## Worked example: address to free tools to answer
@@ -567,14 +663,17 @@ or legal verdict.
 
 ### 3. "Is my tax assessment out of line, and what do I do next?"
 
-One paid call: `POST /api/locus-assessment-position { "address": ..., "noticeDate": optional }` ($0.10).
+First use free `locus_tax_calendar` and `locus_appeal_filing_guide` to check the rule and filing path, then a supported `locus_property_tax_estimate` if annual tax is the question. If the owner still asks how the assessment compares and approves payment, use `POST /api/locus-assessment-position { "address": ..., "noticeDate": optional }` ($0.10).
 No dollar figure is required. It returns the subject's assessed total from the roll, its percentile
 among similar properties within 400 m on the same roll, the appeal deadline rule for the state,
 the filing body and form, and the browser-workflow handoff. It is charged only when the same-roll
-sample is substantive; otherwise it returns a free diagnostic that still carries the deadline rule
-and filing guide. Sentence shape: "Your assessment is $X. Among N similar homes within 400 m on the
-<county> roll it sits at the Pth percentile by total and Qth per square foot. The deadline is
-<rule>. If you appeal, <body> hears it first on <form>. Locus does not say whether to appeal."
+sample is substantive (5+ parcels); otherwise it returns a free diagnostic that still carries the
+deadline rule and filing guide. A percentile label (`at_or_above_p75`, `at_or_below_p25`,
+`interior`) needs 10+ comparable parcels and an untruncated sample; 5-9 parcels, or a sample the
+source truncated, return `unranked` with `unrankedReason`, and a truncated sample has no percentile.
+Always keep the count beside the position: quote `summary` or `uniformity.positionLabel`.
+Sentence shape: "Your assessment is $X. <summary> The deadline is <rule>. If you appeal, <body>
+hears it first on <form>. Locus does not say whether to appeal."
 When the owner already has a figure to test, use `locus-valuation-challenge` with `purpose: "protest"` instead.
 
 ### 4. "What would an experienced analyst read into all of this?"
@@ -583,7 +682,15 @@ One paid call: `POST /api/locus-practitioner-read { "address": ..., "question":
 flat). Locus fetches its own records (parcel, transfers, zoning, rezonings, permits, flood,
 county flood claims, wetlands, soil, capital projects, legislation, area tax distress,
 assessment position), builds typed facts from them, selects the catalogue readings those facts
-support, and writes one hedged summary for the audience the question implies. Each reading
+support, and writes one hedged summary for the audience the question implies (the response's
+`questionUse` shows the persona signal and focus group the question resolved to; the question
+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
 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
@@ -766,7 +873,7 @@ const paymentSignature = btoa(JSON.stringify(credential));
 
 Serialize authorization integers as decimal strings. Do not add top-level `resource` or `extensions` to this minimal credential: some facilitator/client combinations reject those optional fields. Copy any description verbatim; Locus keeps paid descriptions ASCII and at most 480 characters. The installed TypeScript x402 client copies `accepted` and `resource` into its v2 payload, so automatic clients may need this slim-envelope compatibility path.
 
-An `insufficient_funds` 402 includes `payer`, `network`, and `amountRequired` (atomic USDC units). Fund that wallet on that network and retry using the fresh challenge. `invalid_signature` and `expired_authorization` require a new signature. A malformed envelope remains `invalid_payload`. None of these responses is a settlement receipt.
+An `insufficient_funds` 402 includes `payer`, `network`, and `amountRequired` (atomic USDC units). Before topping up, confirm the funding human holds a recovery copy, especially for an ephemeral agent environment. Then fund that wallet on that network and retry using the fresh challenge. `invalid_signature` and `expired_authorization` require a new signature. A malformed envelope remains `invalid_payload`. None of these responses is a settlement receipt.
 
 ### Probe the challenge without paying
 

package/skill/locus-property-tax-protest/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: locus-property-tax-protest
 preamble-tier: 1
-version: 1.0.0
+version: 1.1.0
 description: Use when an owner or their agent wants to contest a property-tax assessment for one US address and needs the deadline, the cited evidence, the filing steps and an outcome baseline from Locus tools.
 triggers:
   - protest my property taxes
@@ -47,8 +47,11 @@ anything the filing portal does not require.
    sales in the window, the subject parcel's public facts, permits, hazards, tax and zoning
    records, and the assessment-uniformity section (same-class parcels on the same roll, assessed
    and per-square-foot distributions, the subject's percentile, the noticed-versus-median
-   difference). `charged:false` means fewer than two sections were substantive; do not retry to
-   force a charge.
+   difference). `factualComparison.uniformityPosition` states the position and its sample count
+   in one sentence; quote it rather than the bare label. A percentile label needs 10+ comparable
+   parcels and an untruncated sample, so a small or truncated sample reads `unranked` with a
+   reason. `charged:false` means fewer than two sections were substantive; do not retry to force
+   a charge.
 5. `locus-comps-brief` only when you need more recorded sales than the challenge carried
    (different radius or months). Same rules: arithmetic over public records, no valuation.
 6. Present the two grounds the boards recognize as two record tables, not conclusions: