# Crockett Businesses — data files

Two files, both written by `lib/businesses.php` on every save (commands and rules are in that file's header):

- `data/businesses.json`: the full database. `data/` is closed to the web. The leads sheet comes from here. If you edit by hand, edit this one, then run `php lib/businesses.php --publish` to rebuild the public copy.
- `businesses/data/businesses.json` (this folder): the public copy the page reads. Open businesses only, public fields only, privacy rules applied. Never edit it by hand; it is rebuilt on every save.

## Where the listings come from

1. **Comptroller permit list** (`src: cpa_permits`). Every outlet with an active Texas sales tax permit whose outlet city is Crockett, from data.texas.gov dataset `jrea-zgmq`. Only the business location is kept: the taxpayer's own name, mailing address and taxpayer number are never stored.
2. **Checked by hand** (`src: checked`). Website, Facebook page, phone, a friendlier name, closed, or a better category, entered through the leads sheet (`--leads` out, `--import-research` back in).

Businesses that don't collect sales tax (most churches, doctors, lawyers, many farms) are not on the permit list.

## Privacy rules for the public copy

Until a listing has been checked by hand (`src` includes `checked`):

- **Rural address** (`location: rural`), or **one-person business off the main roads** (`sole_owner: true` and `location: in_town`): listed without the street address. Main-road addresses are shown.
- **Person-named** (`person_named: true`: a sole owner with no trade name, so the business name is the person's own name): not listed.

The public copy never carries `pkey`, `owner_local`, `sole_owner`, `location`, `person_named`, `naics`, `web`, `status` or permit dates other than `first_sales`.

## One business

| Field | Meaning |
|---|---|
| `id` | Stable slug of name + address. Never reused. |
| `pkey` | Matching key for the permit list (normalized name + address). |
| `status` | `active`; `closed` (checked by hand); `gone` (no longer on the permit list; kept, never deleted). |
| `name` | Outlet name exactly as registered with the Comptroller. |
| `display_name` | Friendlier name, set by hand. The page shows this when present. |
| `address`, `zip` | Outlet street address and ZIP as registered. |
| `naics` | Industry code from the permit. |
| `category` | Plain-English group (see `categories`), from `naics` unless set by hand (`category_set: true`). |
| `city_limits` | `inside` / `outside` the Crockett city limits, from the Comptroller's indicator; `null` if not given. |
| `permit_issued`, `first_sales` | Dates from the permit (YYYY-MM-DD). |
| `owner_local` | `true` if the permit holder's own address is in Houston County, `false` if not, `null` if unknown. The address itself is not stored. |
| `sole_owner` | `true` if a permit holder here is an individual (organization type IS). |
| `location` | `main_road` (a main road or highway inside the city limits: Loop 304, Houston Ave, Goliad Ave/St, 4th St), `rural` (county, FM or private road, or a highway outside the limits), or `in_town` (any other street). From the outlet address only. |
| `person_named` | `true` if a sole owner's business name is the owner's own name (no trade name). |
| `phone`, `website`, `facebook` | Checked by hand. |
| `web` | `unknown` (not checked yet), `live`, `dead` (listed site doesn't load), `facebook_only`, `none` (checked: no website or Facebook page). |
| `web_checked` | Date the listing was last checked by hand or by `--check-sites`. |
| `src` | Where the listing's facts come from; each id is in `sources`. |
| `first_seen`, `seen` | First and latest dates the business was on the permit list. |

Top level: `updated` (last date a listing changed), `last_checked` (last date the permit list was read), `sources` (with retrieval dates), `categories`.

## Leads sheet columns

`--leads` writes one row per open, locally owned, non-chain business with no working website on file (`--all` keeps chains and out-of-town owners, flagged). The `visit` column says how to make first contact: `walk in` (main road), `check the map first` (other in-town street), `call or message` (rural). Only these columns are read back by `--import-research`: `display_name`, `category`, `phone`, `website`, `facebook`, `web`, `closed` (yes/no). Everything else, including `pitched_on` and `notes`, stays in your sheet and never reaches the site.