> ## Documentation Index
> Fetch the complete documentation index at: https://docs.homelogs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Signals Catalog

> Current HomeLogs permit-backed signals, timing families, and usage guidance

## What this page covers

This page explains the current public signal set and how to use each signal in practice.

Use it to understand:

* what each signal means
* whether it is observed or inferred
* when the timing is early vs late
* which signals are available for geo-scoped and permit-scoped workflows

## Timing families

HomeLogs signals fall into three timing families.

### Observed nowcasts

Observed nowcasts are tied to a permit event we can point to directly.

Examples:

* `site_prep_issued_nowcast`
* `new_construction_issued_nowcast`
* `roofing_activity_hotspot`
* `hvac_activity_hotspot`

Use observed nowcasts when you want:

* simple, easy-to-explain triggers
* the most literal reading of the underlying permit data
* a signal grounded in a real observed event

### Early inferred timing windows

Early inferred timing windows are useful when you want more lead time and can accept more uncertainty.

Examples:

* `framing_nowcast_early`
* `rough_in_nowcast_early`

Use early windows when you want:

* earlier outreach
* more time to plan a call, route, or campaign
* a broader timing window

### Late inferred timing windows

Late inferred timing windows are more conservative. They favor better timing fit and lower false positives.

Examples:

* `framing_window_late`
* `rough_in_window_late`

Use late windows when you want:

* tighter sales timing
* fewer premature leads
* more confidence that the project is in the right phase

## Current permit-pack signals

These are the current permit-scoped signals in the public pack.

| Signal key                        | Plain-language meaning                                                       | Best use                                                            |
| --------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `site_prep_issued_nowcast`        | A permit was issued and the project looks like site prep or demolition work. | Immediate contractor outreach, site services, dumpsters, prep crews |
| `new_construction_issued_nowcast` | A permit was issued for a new build or new construction project.             | Early project awareness, developer and trade prospecting            |
| `framing_nowcast_early`           | The project appears to be entering framing soon.                             | Earlier lumber and framing outreach                                 |
| `framing_window_late`             | The project appears to be in a later framing window.                         | More conservative framing outreach                                  |
| `rough_in_nowcast_early`          | The project appears to be entering rough-in soon.                            | Earlier electrical and plumbing outreach                            |
| `rough_in_window_late`            | The project appears to be in a later rough-in window.                        | More conservative electrical and plumbing outreach                  |

## Current geo signals

These are the public geo-scoped signals currently documented for WA:

* `roofing_activity_hotspot`
* `hvac_activity_hotspot`

The active signal catalog may expand over time as additional geo signals are released.

## How to read a signal row

Most signal responses include a few trust fields.

* `signal_key`: the customer-facing signal name
* `signal_basis`: whether the row is `observed_event` or `inferred_timing`
* `event_date_used`: the permit date or timing anchor used for the signal
* `confidence`: a simple confidence score for the row
* `reason_codes`: deterministic reasons that explain why the row was returned
* `freshness_lag_days`: how old the supporting data is relative to the run date

### Observed vs inferred

* `observed_event` means the signal is anchored to an explicit permit event.
* `inferred_timing` means the signal is derived from permit age and timing rules.

That difference matters:

* observed signals are easier to explain
* inferred signals are better for timing a sales motion

## Early vs late use cases

Early windows are better when you want to get there first.

* field sales routing
* outbound prospecting
* broad pipeline generation

Late windows are better when you want to be more selective.

* tighter trade timing
* smaller call lists
* fewer false positives

If you are unsure which one to use, start with the observed nowcasts for immediate value and the late inferred windows for precision.

## Confidence and freshness

Confidence is not a guarantee. It is a short-hand for how much supporting evidence the system had when it made the call.

* more support usually means higher confidence
* sparse geographies usually have lower confidence
* freshness lag is a caveat, not a promise of real-time coverage

If your ingest cadence is monthly, a signal can be valid but still slightly stale.

## Where to discover active keys

Use the catalog endpoint and the geo-specific read endpoints together:

* `GET /v1/signals/catalog`
* `GET /v1/signals/geo/location/{geo_id}`
* `GET /v1/signals/geo/search`
* `GET /v1/signals/permit/leads`
* `GET /v1/signals/permit/stats`

The catalog endpoint is the fastest way to see what is currently active.