Configure launches

The engine builds forecasts for the launches listed in a site catalogue, sites.json. This page shows how to write one. A launch is the place you fly, and a site is that launch’s record in the data. If the engine is not installed yet, start with the install command.

Every builder reads the same catalogue. Pass its path with --sites. The CLI resolves the path for each run, so the file can live anywhere in your project.

Catalogue shape

The catalogue says where each launch is and what to call it. It holds no physical measurements. The engine measures elevation, terrain, and land cover at your coordinates and publishes them in site-context.json.

sites.json

{
  "schemaVersion": 2,
  "sites": [
    {
      "slug": "test-hill",
      "name": "Test Hill",
      "latitude": 49.0,
      "longitude": -117.0,
      "timeZone": "America/Vancouver"
    }
  ]
}

Field	Meaning
schemaVersion	Site-catalogue contract version; 2
slug	Stable lowercase, hyphenated identity used in output paths
name	Reader-facing launch name
latitude, longitude	Decimal degrees
timeZone	IANA timezone used to read local days and clock times

The file must satisfy sitesCatalogueSchema from @azohra/meteo.briefing/contract, or the generated briefing/schema/sites.schema.json. meteo forecast build is stricter than a reader. It refuses unknown fields and elevationM outright, where the reader contract strips them. The strictness exists to catch a field someone typed that the pipeline would otherwise ignore without saying so.

You publish the catalogue to the dataset root yourself, unchanged. A build never copies it there. Once it is published, builders can read it from the dataset with --sites dataset.

Do not put elevation in the catalogue

The engine rejects a file that includes a hand-typed elevationM, or any other unknown field, and points you to the measured replacement. The launch elevation is the elevation pick in site-context.json, measured from ground observations at the catalogued coordinates. Each profile records the sampled grid terrain separately as site.modelElevationM.

Add a site

1. Choose a stable slug. Renaming it changes every profile and history path.

2. Record coordinates from a source you trust for your launches. Do not record elevation anywhere; the engine measures it in step 4.

3. Declare the launch’s IANA timezone. Local time sets day windows and the meaning of timing findings, so builders copy this value into each profile as site.timeZone. Do not infer it from longitude in presentation code.

4. Run the terrain measurement once, then commit site-context.json in the same change as the catalogue, so the published elevation, terrain, and land cover stay matched to the sites they describe:

   Terminal

   pnpm exec meteo forecast terrain --sites ./sites.json --output ./site-context.json

   The command reads the --sites catalogue and rewrites the --output file. Its geospatial dependencies load only when it runs, so a scheduled forecast build never pays for them. The site context reference covers the file’s shape, how the elevation pick is chosen, and its sources.

Next

Choose models to find the slug for --model. Then run one model as a dry run, which validates the catalogue before anything is downloaded. An invalid catalogue fails there and names the offending field. A site outside the chosen model’s sampling guard fails the build with an out-of-grid error instead of publishing a clamped boundary value.

The catalogue only chooses where to sample and which local clock to use. Audience, launch suitability, display windows, and access policy are the operator’s decisions.