`docs/prd-pilot-v0.1.md`

123 lines
# PRD — pastdoor pilot v0.1

Decision-grade brief responding to the 2026-04-28 status audit.

## Wedge (locked)

**Property-history pages — Beverly Hills only.** Not Olympic host microsites, not filming-location discovery (both are credible adjacent wedges; both are deferred until the property-history wedge proves out).

Why this wedge first:
- Strongest source stack — county assessor + BH nightly permit feed + BH Public Library + Sanborn + HABS all viable today.
- Lowest regulatory risk — no STR-license validation, no Airbnb / Olympics policy churn.
- Best fit for the current schema — `listing` + `place_event` + `entity_place_association` + `media_asset` + `parcel` already model exactly this.
- Generates the editorial spine that everything else (Olympics microsites, filming) can ride on later.

## Audience

1. **Curious resident / buyer** — wants the story behind a house they're researching. Free public page.
2. **Owner / claimer** — wants to take the page over and add their own copy + booking link. **$9.99/mo Basic.**
3. **Real-estate agent / STR host** — wants visibility for a current listing without false-archive claims. **$29/mo Promote.**
4. **Architectural historian / preservationist** — wants the source-tier ledger and CSV export. **$19.99/mo Pro.**

## Success metric for the pilot

Single primary metric: **% of pilot address pages that earn at least one organic click within 60 days of indexing.** Target: ≥30% of indexed pages with click ≥1.

Supporting metrics:
- Pages indexed by Google (must be ≤ pages eligible per `sitemap.ts` rules)
- Avg session duration on address page > 45 seconds
- Claim conversion rate for indexed pages > 0.5%
- Promote-a-listing inbound submissions per week ≥ 2 by week 8

## Pilot scope

**Geo:** Beverly Hills, CA — 90210 + 90212.
**Page count:** 100–500 indexable address pages over 8 weeks.
**Indexability rule (enforced in sitemap.ts):** an address page is allowed in the sitemap **only if** it has ≥1 publicly-visible event OR association OR media asset. Stub pages get `noindex` automatically.
**Claim flow:** live for all pages, but Stripe wiring is deferred until the RAK lands; claims sit in `claim_request` queue.
**Promote flow:** live but admin-approved manually until self-serve Stripe.

## Indexable surface (final)

| Path | Indexable | Why |
|---|---|---|
| `/` | yes | Editorial homepage |
| `/about` | yes | Editorial |
| `/people` | yes | Curated index |
| `/neighborhoods` | yes | Curated index |
| `/hosts` | yes | Pricing + product positioning |
| `/browse` (no params) | yes | Branded search landing |
| `/browse?q=…&city=…` | **no** | Faceted, infinite URL space; canonicalized to `/browse` |
| `/address/[slug]` | yes **only if** ≥1 public event/association/media | Quality gate |
| `/entity/[slug]` | yes **only if** ≥1 public association | Quality gate |
| `/neighborhood/[slug]` | yes **only if** ≥3 listings | Quality gate |
| `/claim/[slug]` | no | Form |
| `/promote`, `/promote/[slug]` | no | Form |
| `/submit` | no | Form |
| `/dashboard` | no | Owner-only |
| `/api/*` | no | API |

robots.txt and sitemap.ts enforce these rules.

## Schema.org coverage

- `/address/[slug]` emits `Place` with name, PostalAddress, GeoCoordinates, additionalProperty (year-built, APN), description.
- `/entity/[slug]` emits `Person` (or `Organization` for businesses) with name, birthDate, deathDate, sameAs (Wikipedia), jobTitle (architects).
- All other pages stay schema-less — no misleading markup.

## Editorial review workflow

1. Tier-A government / Tier-B archive sources auto-flow to `public_visible=true` when ingested.
2. Tier-C verified secondary requires a reviewer to flip `review_status` from `pending` → `approved` before going public.
3. Tier-D social/discovery never reaches public, period. Lives in editorial queue only.
4. The `epa_privacy_gate` DB trigger blocks any living-person association from being published within last 25 years.

## Definition of "good enough" for an address page

An address page may go public if it has at least 3 of the following:
- ≥2 government-sourced events (permit / sale / assessor field)
- ≥1 archival media asset (Sanborn / archival photo / postcard)
- ≥1 historical association (architect / former owner / former tenant)
- A structure record with year_built
- A parcel record with APN
- A neighbourhood / block characterization paragraph

Pages below the bar get `noindex` and a "minimal record" badge until enriched.

## What we are NOT doing in v0.1

- Citywide page generation
- Speculative architect attributions
- Living-person association publishing (DB trigger blocks)
- Self-serve Stripe (pending RAK)
- Custom-domain Pro tier hosting
- Olympic / filming / venue layers
- API for enterprise consumers
- Mobile-app shells

## Risk register (rolled up from the audit)

| Risk | Mitigation |
|---|---|
| SEO quality risk from thin pages | sitemap.ts evidence-gate + per-page `robots: noindex` for stubs + canonical tags + faceted-URL noindex |
| Data coverage / licensing | Tier-A-first, source-matrix.md as source of truth, append-only event ledger w/ provenance |
| Linkage accuracy | APN as primary key when present; alt addresses queue to review when normalize fails |
| Privacy / reputational | DB trigger + policy + tier system |
| Regulatory drift on STR claims | Promote-a-listing self-attests permit number; we don't verify |
| Misleading structured data | JSON-LD only emits fields the visible page shows |
| Scope drift | This PRD locks the wedge; expansion needs a new PRD |

## Timeline

| Week | Milestone |
|---|---|
| 0 (now) | Schema + Beverly Hills seed + SEO playbook + JSON-LD live (this commit) |
| 1 | BH nightly permit feed ingest live; first 50 pages cleared the evidence gate |
| 2 | LA County Assessor APN cross-walk for those 50 pages; tier-A sales seeded |
| 3 | Sanborn + HABS attach for 30+ pages; first ~100 indexable |
| 4 | First-claim end-to-end; Stripe wiring (when RAK arrives) |
| 5 | Newspaper-clip ingest workflow (LA Times archive) for 20+ pages |
| 6 | First Promote-a-Listing live; revenue check |
| 7 | Search-Console monitoring + page-quality review |
| 8 | Pilot retrospective; go/no-go for expansion to West Hollywood + Hancock Park |