# Chance Brothers Sync Interface

Human and agent contract for reusing LUX Light Archive Chance Brothers data.

## Endpoints
- `/chance-brothers/export.csv` (csv): Flat CMS/import handoff for public-safe Chance Brothers records.
- `/chance-brothers/export.json` (json): Structured row export with the same fields as CSV.
- `/chance-brothers/lighthouses.geojson` (geojson): Mapped point overlay for records with coordinates.
- `/chance-brothers/comparison.csv` (csv): Reconciliation report between LUX rows and the latest prepared CHT snapshot.
- `/chance-brothers/comparison.json` (json): Structured reconciliation report; review-only, not an import source.

## Snapshot Metadata
- `generated_at`: `2026-07-09T20:24:00+00:00`
- `archive_version.version`: `v0.24.110-review`
- `archive_version.display_version`: `v0.24.110`
- `extractor.script`: `scripts/build_static_site.py`

## Sync Protocol
- Before importing, read generated_at and archive_version from the JSON file being used; treat those values as the snapshot identity.
- If reporting an import issue, include generated_at, archive_version.version, extractor.script, the endpoint path, and the affected lux_asset_id or cht_source_id.
- Use comparison.csv/json to review gaps and possible adoptions after a Chance Heritage Trust import, then record confirmed decisions in the partner overlay.
- When a CHT page appears to have reused LUX data, store the CHT URL as a partner link only; do not promote it to independent source evidence.
- Refresh from a newer LUX snapshot by replacing the previous export/comparison files rather than merging rows across different generated_at values.

## Core Concepts
- `heritage_asset`: A first-class LUX object such as a lens, optic, lantern, apparatus, tower, museum object, or related component. It is not always a lighthouse page.
- `lighthouse_or_site`: A host place or navigation site that may contain, display, replace, or historically relate to a Chance Brothers asset.
- `current_host_id`: Reviewed LUX lighthouse/lightship host when known. It may be blank when an asset is known but not yet matched to a host record.
- `current_location`: Source-import or reviewed location used for matching and mapping. Coordinates are not automatically accepted canonical lighthouse coordinates.
- `source_evidence`: The source rows supporting or discovering the asset. Object-level links are useful provenance but not automatically field-level evidence.
- `partner_link`: Manual counterpart/adoption review row for Chance Heritage Trust exchange. It is separate from independent source evidence.

## Export Fields
`lux_asset_id`, `title`, `aliases`, `country`, `region`, `latitude`, `longitude`, `asset_kind`, `manufacturer`, `status`, `chance_relation`, `evidence_grade`, `evidence_score`, `evidence_note`, `source_urls`, `lux_url`, `matched_cht_url`, `image_url`, `image_attribution`, `image_license`, `image_verification_status`

## Comparison Fields
`comparison_status`, `lux_asset_id`, `lux_title`, `lux_url`, `cht_source_id`, `cht_title`, `cht_url`, `match_method`, `review_action`, `review_note`

## GeoJSON Properties
`asset_id`, `title`, `asset_kind`, `manufacturer`, `status`, `source_collection`, `source_collection_label`, `source_label`, `source_url`, `research_quality_score`, `research_quality_grade`, `research_quality_note`, `research_quality_label`, `url`

## Partner Overlay Fields
`lux_asset_id`, `cht_source_id`, `cht_url`, `match_status`, `adoption_status`, `reviewed_at`, `reviewer_note`

## Agent Rules
- Use export.csv for CMS imports unless richer JSON structure is required.
- Use lighthouses.geojson only for mapped points; unmapped assets can still be valid records.
- Do not import comparison.csv/json as facts; it is a reconciliation worklist.
- Blank image fields mean no public-safe image is currently exported.
- Do not treat matched_cht_url as independent evidence when the CHT page may have reused LUX data.
- Keep heritage assets distinct from lighthouse/site pages: a lens or optic may move, survive separately, or lack a confirmed host.

## Model Diagram
```mermaid
flowchart LR
  LUX[LUX heritage_asset\nlens / optic / lantern / tower] --> Export[CSV / JSON export]
  LUX --> GeoJSON[GeoJSON mapped points]
  LUX --> Comparison[Comparison report]
  CHT[CHT snapshot] --> Comparison
  Overlay[partner link overlay\nmanual review] --> Export
  Overlay --> Comparison
  Comparison --> Review[Curator review\nconfirm / reject / adoption signal]
  Review --> Overlay
```