LUX Light Archive

Chance Brothers sync interface

Interface Guide

Human and agent documentation for importing, reconciling, and reviewing LUX Light Archive Chance Brothers data. LUX stores lighthouses and sites, but also lenses, optics, lanterns, towers, museum objects, and other heritage assets that may move or survive separately.

Agent handoff

Use these machine-readable and plain-text contracts when Claude or another import agent needs to understand the exchange format before importing data into another CMS.

Open agent JSON Download Markdown spec Back to sync

Snapshot protocol

The exchange files describe a dated generated snapshot. Use this section when comparing imports across time or reporting a parser/import bug.

MetadataValue
generated_at2026-07-09T20:24:00+00:00
archive_version.versionv0.24.110-review
archive_version.display_versionv0.24.110
extractor.scriptscripts/build_static_site.py
  1. Before importing, read generated_at and archive_version from the JSON file being used; treat those values as the snapshot identity.
  2. 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.
  3. Use comparison.csv/json to review gaps and possible adoptions after a Chance Heritage Trust import, then record confirmed decisions in the partner overlay.
  4. 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.
  5. Refresh from a newer LUX snapshot by replacing the previous export/comparison files rather than merging rows across different generated_at values.

Model

Chance Brothers sync data model LUX heritage assets, the CHT snapshot, and the manual partner overlay feed exports and comparison reports; curator review records confirmed partner decisions back into the overlay. LUX heritage asset lens / optic / lantern / tower CSV / JSON export public-safe import rows GeoJSON mapped points only Comparison report matches / gaps / adoption signals CHT snapshot prepared source rows Curator review confirm / reject / adoption signal Partner overlay manual counterpart decisions
Mermaid source for agents 
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

Endpoints

PathFormatUse
/chance-brothers/export.csvcsvFlat CMS/import handoff for public-safe Chance Brothers records.
/chance-brothers/export.jsonjsonStructured row export with the same fields as CSV.
/chance-brothers/lighthouses.geojsongeojsonMapped point overlay for records with coordinates.
/chance-brothers/comparison.csvcsvReconciliation report between LUX rows and the latest prepared CHT snapshot.
/chance-brothers/comparison.jsonjsonStructured reconciliation report; review-only, not an import source.

Core concepts

ConceptMeaning
heritage_assetA 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_siteA host place or navigation site that may contain, display, replace, or historically relate to a Chance Brothers asset.
current_host_idReviewed LUX lighthouse/lightship host when known. It may be blank when an asset is known but not yet matched to a host record.
current_locationSource-import or reviewed location used for matching and mapping. Coordinates are not automatically accepted canonical lighthouse coordinates.
source_evidenceThe source rows supporting or discovering the asset. Object-level links are useful provenance but not automatically field-level evidence.
partner_linkManual counterpart/adoption review row for Chance Heritage Trust exchange. It is separate from independent source evidence.

Fields

Use the JSON and Markdown contracts for machine import. These field lists are collapsed here so the human guide stays readable.

CSV / JSON export 21 fields
CSV / JSON export
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 10 fields
Comparison
comparison_status
lux_asset_id
lux_title
lux_url
cht_source_id
cht_title
cht_url
match_method
review_action
review_note
GeoJSON properties 14 fields
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 7 fields
Partner overlay
lux_asset_id
cht_source_id
cht_url
match_status
adoption_status
reviewed_at
reviewer_note

Import guidance for agents

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