Skip to content

Weather playbook

This playbook is about weather only. How we build anything (data, platform, open data, analytics, APIs) is decided in the other playbooks, and this one follows them.

Weather is infrastructure, so it belongs to Nyuchi (owner direction, 2026-10-29). Nyuchi Web Services builds and runs it; Mukoko Weather is the consumer product on top of it, alongside the other apps and partners that read it. Where this page says “the weather repo” it means mukoko-dev/mukoko-weather, which still sits under the Mukoko organisation. Whether it moves is an open decision (section 7).

The one goal behind everything we build: a person anywhere on Earth, and above all in Africa, opens Mukoko Weather and learns what the weather means for what they need to do today.

Every /loop we run is an overarching objective that moves that goal. This file is the source for those loops: what each objective is, what moves it, who it helps, what is safe to do unattended, and what needs the owner.

Sources: the repo docs (CLAUDE.md, README.md, workers/README.md, releases/), the mukoko-dev/mukoko-weather issues and pull requests, mukoko-api, mukoko-weather-mobile, nyuchi-api and nyuchi-servers-api. First written 2026-10-29; reviewed 2026-11-17, and sections 1, 2, 4a, 7, 7a and 9 were updated then. “Decided, not built” is said wherever that is the case. Nothing here was measured in production; metrics marked not yet measured have no baseline.

How the web build, device push, releases and the other cross-cutting work are decided now lives in the Web, Notifications, Releases and Agents playbooks. This one follows them.

Built means merged to staging. The weather repository’s staging and main carried the same tree on 2026-11-17, so built also means released, except where a row says dark: dark code is merged and does not serve a person.

Area Built Decided, not built
Web app weather.mukoko.com is still Next.js on Vercel: forecast, activity suitability, AI summary, map, aviation, community reports, history, /display, embed, /locations, /releases. Installable from a visible control, and restorable by the browser’s back button for anonymous requests (measured: 7 of 8 pages) Astro and a Rust web Worker serve the whole web build with JavaScript only in the browser (owner, 2026-11-04 and 2026-11-14; the Web playbook). Dark: the layout and six static pages are built, with a link preview per page and per place; no cutover, no DNS, never run in a Workers runtime
Forecast Africa-weighted blend of six global models via Open-Meteo, Tomorrow.io enrichment only, seasonal fallback so a page never renders empty Verification-fitted weights (groundwork only); self-hosted Open-Meteo (#280, code not live)
Backend Rust Workers for forecast, places, aviation, stations, jobs, AI, tiles, internal and public API, and a Mongo bridge. No Python route is left (api/py deleted, 2026-11-02, v0.15.0; /api/py/* answers a 404 problem document except stations ingest). The workers deploy on every push to main that touches them Gwaihir in the Nyuchi Servers API (owner, 2026-11-01). A /v1/weather namespace is built there; no deployed Gwaihir app was found. Whether the Workers carry production traffic is unverified: the last confirmed hand deploy was 2026-10-19, and the Workers were modified on 2026-11-15
Public API mukoko-api routes /v1/weather/* to the weather Worker; developer keys scoped weather Client cutover to api.mukoko.com (#174)
Device push Dark, and in a draft PR (#583): /send on the push Worker, an hourly alert tick (ALERTS_ENABLED ships false). Merged: the pure push crates and the push Worker’s health route. It has never been switched on (see the Notifications playbook) The three secrets, the public key, the deploys and the flag flips: owner steps
Mobile Expo app, thin client over the same API Store status not re-checked on 2026-11-17: the earlier note said not in either store and no iOS submit config
Stations Ingest for Wunderground, Ecowitt and manual readings, in a Worker that can write to the Nyuchi API (STATIONS_BACKEND, d1 by default, so merging changed nothing). The console in nyuchi/stationkit console/ is built (Astro 7 on Workers; mock is refused in production). Station routes are built on the Nyuchi API’s staging The old Next.js station-console/ here goes after cutover plus 30 days. The production D1 held 0 stations and 0 observations on 2026-11-13, so “one active station” is not a measured fact. StationKit hardware and firmware are specification only
Money Free and anonymous; AI gated on sign-in only No entitlement or payment layer; payment provider is an open owner decision (#238)
Platform fit Mongo platform DBs, placesGeo as the location source Owner order 2026-10-28 (#359): stop being a silo, use Places ids, CF names, WIGOS. The weather model is built in data-infra; the migration has not run

These are owner decisions already recorded in the repos. A loop that breaks one has failed.

  1. The weather backend is Gwaihir, a server of the Nyuchi Servers API (owner, 2026-11-01: “Instead of building out the old weather-api.mukoko.com we should be building the nyuchi servers API”; the name, same day). Gwaihir is decided; a /v1/weather namespace is built in the Servers API, and an ADR makes it its own Fly app, but it is not deployed as one. The Rust Workers behind weather-api.mukoko.com are not built out further: they keep serving until Gwaihir is deployed at parity, and every new weather feature goes to Gwaihir. The repository’s own text still points WeatherKit at Gwaihir (“moving to Gwaihir”) and has no Gwaihir code, so whether Gwaihir or the Workers is the target remains an open question (section 7). The decisions live in weather-core (pure, builds for wasm32), so the logic is not rewritten, only its adapters. Vercel is frontend only, and is being replaced by Rust serving an Astro build (the Web playbook). api/py no longer exists.
  2. A domain refers to another by id. Geography is Places. Weather keeps no countries, provinces or regions of its own (#359). Agriculture is its own domain (agriconnect); weather adds no agriculture data store.
  3. Standards, not inventions. CF standard names with units declared once, ISO 8601 with the place’s IANA zone, ISO 3166 codes, WIGOS on stations, WMO 4677 weather codes, schema.org with JSON-LD.
  4. The coordinate is the identity, the name is cosmetic (#317). No valid coordinate dead-ends.
  5. Tomorrow.io enriches, never carries the baseline (#246).
  6. Never invent data. A place with no crop calendar gets a derived window that names no crops. A provider outage serves the seasonal estimate, labelled.
  7. Errors are isolated per section. A broken chart never takes down the page.
  8. Nothing is published, merged, deployed or released by a loop without the owner’s approval. The merge gate is: complete, CI green, verified at runtime, /code-review clean.
  9. Secrets, keys and credential status never go in files or public issues.
  10. Stations are registered on the Nyuchi API (owner direction, 2026-10-29), not on a weather-only endpoint, so a station has one registration and one id wherever it is used.
  11. Playbooks live here, on docs.nyuchi.com, in nyuchi/nyuchi-docs. A copy in an app repo goes stale; link to this page instead.
Entity Judged by Weather’s job
Nyuchi (Mukoko Weather) Growth and community reach: users, retention, community activity. Aim for break-even; surplus flows to Bundu. The consumer product people open daily and tell others about.
Bundu Foundation Openness, rigour, community benefit. No revenue expectation. Open data, open standards, research-grade rainfall and station records. No monetisation push.

Objectives below say which scorecard they serve. Where one serves both, the Bundu side stays free and open.

Order is priority. Objectives 1 to 3 are the foundation and unblock the rest. Do not start a new objective’s loop while an earlier one has an unresolved owner blocker that it depends on.

Objective 1: Any place on Earth renders real weather

Section titled “Objective 1: Any place on Earth renders real weather”
  • Entity: Nyuchi. Refs: #317, #302, #273, #359.
  • Why: A farmer, a pilot or a traveller who searches for a place and gets a dead end never comes back. Search, GPS and plain-name URLs now resolve worldwide (v0.12.0), but the location pipeline is still described for Africa first (#273) and holds its own location list (#359).
  • Metric moved: share of searches and GPS fixes that end on a rendered weather page; 404 rate on real place names; search-to-page-view rate. Not yet measured: add the event first (see Objective 6 loop step).
  • Story to tell: someone in Koh Samui, Gweru or a farm paddock with nothing mapped typed their place and got weather for exactly there.
  • Loop does:
    1. Probe a fixed list of 50 places (Africa-heavy: rural Zimbabwe, Sahel, Indian Ocean islands; plus world cities, open water, polar) through search, GPS coordinates and bare-name URLs; record pass or fail.
    2. Fix failures in workers/places and weather-core::resolve with a native cargo test per fix.
    3. Replace the app’s own location list with Places ids as #359 requires (read country and region from Places, never store them here).
  • Done when: all 50 probes pass, and a test pins each past failure.
  • Safe now: probes, native tests, fixes inside the Workers. Needs sign-off: any change to the Places schema or to what the Nyuchi API stores (platform-owned).

Objective 2: One backend, Rust Workers, Python deleted

Section titled “Objective 2: One backend, Rust Workers, Python deleted”

Status, 2026-11-17: the Python half is done. All of api/py (its modules and tests) was deleted in #428 and #429 and shipped in v0.15.0 on 2026-11-02; #333 is still listed open but its work is finished. What remains of this objective is the Gwaihir direction below, the deploy proof (below) and the web build (the Web playbook).

  • Entity: Nyuchi. Refs: #333, #148, #174, #351, #297.
  • Why: Two backends doubles the failure surface and keeps weather tied to Vercel. The owner decided Rust-only. Remaining Python routes are listed in #333 in four batches.
  • Direction (owner, 2026-11-01): the destination is Gwaihir in the Nyuchi Servers API, not more Workers. This objective now means: finish moving the remaining routes off Python (into the existing Workers, no new features there), then build Gwaihir from weather-core and move the routes across; the Mukoko API (api.mukoko.com) is the public door and Gwaihir has no public address. Every new route, provider (for example Apple WeatherKit, with its attribution) and budget is built for Gwaihir.
  • Metric moved: share of app calls served by Workers (target 100%); p95 page-load; error rate on the page-load path; cold-start failures on the seed fallback.
  • Story to tell: weather loads the same speed on a slow phone in Bulawayo as in Singapore, because the answer comes from the nearest edge, not a serverless cold start.
  • Loop does: one batch per run, in the #333 order (page-load routes, then agriculture/model-grid/profile, then reference data, then writes). Per route: same JSON as the Python, shared fixtures between Python and Rust tests, same caching, breakers and budgets. Then repoint with no /api/py fallback.
  • Done when: api/py, its tests and the Vercel rewrites are deleted, and /api/py has zero call sites in src/. (Met for the code. The Vercel rewrites go with the front-end cutover.)
  • Not yet proven in production: that the Workers serve the app. The deploy workflow has no variable gate and runs on every push to main that touches workers/, and a missing secret fails it loudly, but the last deploy anyone confirmed by hand was 2026-10-19 (#351).
  • Safe now: porting and tests, one batch at a time (disk is about 1.5 GB: share one cargo target dir). Needs sign-off: every deploy (workers-deploy.yml, behind the workers-production Environment), and the release blockers in #351 (Mongo bridge Worker, Atlas read-write user, index repairs). Those are owner steps.
  • Entity: both. Refs: #359, #150, #277, #265, #291.
  • Why: The owner’s order of 2026-10-28. Stations store airTemperatureCelsius-style names, not CF names; locations are not Places ids; weather has an agriculture endpoint that now belongs to another domain.
  • Metric moved: none for users directly. It protects every later metric: fewer duplicate records, and other Nyuchi products can read weather without translation. Measure as count of weather-owned geography/agriculture collections (target 0).
  • Loop does: an audit-then-migrate cycle against #359’s change list: Places id on locations and stations; WIGOS id where a station has one; CF standard names with the unit declared once; ISO 8601 plus IANA zone; no stored countries or provinces; point /agriculture consumers at agriconnect when it serves them.
  • Done when: a drift check (the platform-architect agent pattern) finds no weather-owned copy of geography or agriculture data.
  • Safe now: read-only audit, renames behind adapters with tests. Needs sign-off: any data migration on the shared cluster, and anything that touches data-infra.
  • What data-infra already says (#90, read 2026-10-29; comments dated 2026-10-28; the owner’s mandatory-and-urgent note is tracked in data-infra#122): weather has no module in the platform model (schemas/model/), so nothing checks it. Findings: ObjectId _id instead of UUID strings; free-text country and province on stations; two metric names per quantity (temperatureCelsius and airTemperatureCelsius, and three more pairs); daily values keyed by an instant instead of an ISO date plus IANA zone; regions boxes not in GeoJSON bbox order. Planned sequence: a weather.yaml model PR (no data touched), then a station-to-place match report, then a backfill that needs your yes. Unmatched stations are listed, not guessed. The sibling issues are nyuchi-api#397 (the /v1/weather router, which filters stations by free-text country and province) and an unfiled audit of the mobile app. The agriculture domain was added in data-infra#117 (merged 2026-10-28) with no data model yet; nyuchi/agriconnect is an empty repo (a heading in its README).
  • Loop order for this objective: (1) review the weather.yaml model PR when it lands, (2) make new code in this repo write the model’s names only, behind adapters, (3) wait for the match report before any backfill.

The audit of the weather database (which collections are not weather and where each goes), the rule for converting external feeds at the edge, and the wasmtime direction are decisions about data, so they live in the Data playbook, not here. Weather’s part of the work: the weather.yaml model (data-infra#90), stations registered on the Nyuchi API, and feed parsers that output standard names and units.

Objective 4: Forecasts people can trust in Africa

Section titled “Objective 4: Forecasts people can trust in Africa”
  • Entity: both. Free for everyone; the research is Bundu’s. Refs: #246, #247, #245, #268, #280, and the station fleet.
  • Why: Global models are weakest where our users are. The blend and fallback chain exist, but weights are a starting guess, nothing is verified against observations, history only recently resumed after stopping in July 2026 (#245), and we have one station.
  • Metric moved: forecast error against observations per region (temperature and rain, 24 h and 48 h); number of validated stations; days of continuous history per place. Not yet measured: the verification docs are captured but no job joins them to observations.
  • Story to tell: a school put a rain gauge and thermometer in the ground, typed in a reading, and the forecast for their village got better.
  • Loop does:
    1. Build the verification join (captured forecasts against StationKit observations, else ERA5) and report error by region.
    2. Propose per-region weights into modelBlendConfig for the owner to approve.
    3. Prototype CHIRPS and TAMSAT point extraction for rainfall anomaly (“is this season drier than usual?”), as scoped in #247.
    4. Keep history healthy: assert one doc per place per day.
  • Done when: a weekly error report exists per region and weights change only from that report.
  • Safe now: analysis, reports, prototypes, tests. Needs sign-off: weight changes, ingest jobs that add Cloudflare cost, and the licensing question below.
  • StationKit is the load-bearing piece of this objective. See section 4a.
  • Licensing blocker: Open-Meteo’s free API is non-commercial. Fine while we run at break-even and free, but any paid tier, or the developer API sold to businesses, needs the commercial plan, the self-hosted instance (#280, code ready, not deployed), or direct ECMWF/GFS/ICON ingestion. Decide before Objective 7.

StationKit is the station network that makes the loop “my station improves your forecast, your station improves mine” true, and it is the only way weather gets ground truth in places the models model badly.

Status, 2026-11-17. The station routes the console needs are built on the Nyuchi API’s staging (#540 to #544): register, list, status, readings, rotate key, claim, a service route for the ingest Worker and an import path. They answer 503 stations_unavailable until the owner applies the indexes, and were not verified to be in a tagged release. The console in stationkit console/ is merged on main (the repo’s front page no longer lags staging), reads a real client behind STATIONS_BACKEND, and has not been attached to its production domain. The owner confirmed on 2026-11-13: device.devices is the station record, the Nyuchi API builds the station routes, anonymous registration ends, and the Astro Workers use plain Worker secrets. The import of existing stations to the Nyuchi API has not been run (#561, dryRun defaults to true), and #558 records that the queue maps serialise as {}, so the D1 path stores no observations until the owner chooses between fixing it now or waiting for the cutover.

Where the pieces live (read 2026-10-29):

  • Station console: nyuchi/stationkit staging already holds it (console/, Astro 7 on Cloudflare Workers, deploy workflow, merged 2026-10-11 to 2026-10-21). main does not have it yet, which is why main’s README still says no code has landed. The old Next.js copy is station-console/ in this repo. The new console talks only to api.nyuchi.com, where POST /v1/stations and the other station routes are not built (live probe 2026-10-11), so it answers “not live yet”. The live ingest is the weather repo’s stations Worker at weather-ingest.nyuchi.com. So the move is mostly done in code, and what remains is: release staging to main, build the station routes on the Nyuchi API (or point the console at the existing Worker), then delete station-console/ here.
  • Product page and pilot signup: bundu-labs/marketing, apps/nyuchi/src/pages/stationkit/{index,signup}.astro (Astro monorepo with the nyuchi.com, bundu.org and mukoko.com sites). The signup form posts to Formspree, not to any station-registration API, so a pilot signup does not create a station.

What exists (read 2026-10-29):

  • The repo is a README and a licence. There is no firmware and no hardware design. The device is specification only: ESP32-C3, ESP-IDF, solar plus 18650, 5-minute reads, hourly batches of 12, about 48 h of flash buffer. The README says the figures are targets, not measurements, and that no hardware has been built from the repo.
  • The design record is four draft issues: #3 hardware, #4 firmware, #5 API contract, #6 data schema and QC. All carry TODO markers.
  • What runs in production is elsewhere: the pilot signup on nyuchi.com, the console at weatherstations.nyuchi.com, and the ingest and QC pipeline in this repo (/api/py/stations/*, being ported to workers/stations). Any consumer station can already push through the Wunderground or Ecowitt “custom upload” protocols, and analog stations can submit by hand. One station is active: Nyuchi Africa HQ, Harare.

Contract drift to resolve before any firmware is written (nothing downstream can be built until it settles, as the README says). On 2026-11-13 the console sends windSpeedKph while the API also accepts windSpeedMs; the Worker converts to km/h names and legacy_metrics() keeps them “at the storage boundary only” until the weather model is applied, so the table below is still the open decision:

Topic StationKit draft (#5, #6) What this repo runs today Platform rule (#359)
Endpoint POST /v1/stations/{stationId}/readings, bearer token per station WU GET and Ecowitt POST with PASSKEY=<stationId>:<ingestKey>; manual POST Not decided
Field names temperatureC, windSpeedMs, rainfallMm, pressureHpa airTemperatureCelsius, windSpeedKph, precipitationMillimeters CF standard names, unit declared once
Wind unit m/s km/h CF wind_speed is m/s
QC Range, spike, cross-check against satellite data Inline range check only; no spike or cross-validation Not decided
Identity Station id and key Station id and key Places id plus WIGOS id where it exists
Publish onward To Open-Meteo Not found in this repo Not decided

Three name sets for the same quantities is the silo problem in miniature. The draft’s m/s is the one that matches CF; the live code’s km/h does not.

Decision (owner, 2026-10-29): stations are registered on the Nyuchi API. That settles the open question about the console’s backend. The console in nyuchi/stationkit already targets api.nyuchi.com; what is missing is the API side. In nyuchi/nyuchi-api, gateway/routers/weather.py has only read routes (GET /v1/weather/stations, /stations/{id}, /stations/{id}/observations, /observations, /alerts, /forecast, /key, /status). There is no route that registers a station. To build:

  1. POST /v1/stations (register: returns a station id and a key once), GET /v1/stations, GET /v1/stations/{id}, POST /v1/stations/{id}/rotate-key, and POST /v1/stations/{id}/readings, which the draft contract in nyuchi/stationkit issue 5 already specifies.
  2. A registered station carries a Places id (placeId), an owner entity and a WIGOS id where it has one, and stores no country or province. weather.stations already has placeId and ownerEntityId fields, so this follows the shape in use.
  3. Move ingest onto the same key model so Weather Underground and Ecowitt uploads (today weather-ingest.nyuchi.com, the mukoko-weather-stations Worker) authenticate against stations registered through the API.
  4. The weather Worker stops being a second registry. Its register route (/api/py/stations/register today) is retired once the API’s exists.

The pilot signup process needs updating. Today the pilot form on nyuchi.com (bundu-labs/marketing, apps/nyuchi/src/pages/stationkit/signup.astro) posts to Formspree and creates nothing. The new process: a person signs in, registers a station in the console (which calls the Nyuchi API), and receives credentials once; the pilot form becomes a request to host a station, handled by a person, and it does not pretend to register one. The marketing copy and the console’s wording change in step.

Loop (daily, with Objective 4):

  1. Hold the contract in one place. Propose a single field and unit table (CF names, SI units) and a migration path from the live names. Do not edit #5 or #6 without the owner.
  2. Add the missing QC (spike and outlier, cross-validation against the model blend) in weather-core::station, with native tests.
  3. Verify the loop: when a station is within 50 km, current must come from StationKit (X-Current-Source: stationkit). Add a test that proves the overlay.
  4. Report fleet health: stations active, last seen, QC pass rate.

Done when: one written contract, the Worker implements it, QC has spike and cross-check, and the fleet report exists.

Safe now: the contract proposal, QC code and tests, reports. Needs sign-off: the contract itself, anything on hardware spend or the BOM, the location-privacy policy for published data (#6 leaves it as a TODO), and the publish-onward path to Open-Meteo (a data-licence decision for the Bundu commons).

Bundu scorecard: station data goes into a commons the Bundu Foundation governs. Judge this work by openness and rigour (published QC rules, a documented schema, no relicensing path), not revenue.

Also open in the repo: #16 records that CodeQL scans only the workflow files, with no dependency audit or pre-commit scan. Fix it through the org-level layer (nyuchi/.github), per the owner’s 2026-10-07 direction, not per-repo copies.

Story to tell: a school or smallholder joined with a rain gauge and a thermometer. Do not claim a hardware network exists: today it is one station plus any consumer station that points at our endpoint.

Status, 2026-11-17. The PWA installs on request and restores from the back button (#584). The device push path is written and dark (#583, draft): a frost alert has never been delivered to a device. The owner’s report of 2026-11-14 is the reason this is the live objective: notifications show in the app and do not reach the phone. The remaining steps are owner steps; see the Notifications playbook.

  • Entity: Nyuchi. Refs: #289, #320, #164, #171, #269, #282, and the mobile app.
  • Why: A weather app is judged by whether it is on the home screen and warns you before the frost. Mobile is built but in neither store; web push is designed (frost alerts first) but nothing sends a push; /display for TVs and the embed widget are live but not promoted.
  • Metric moved: installs (PWA and store), push opt-in rate, D7 and D30 retention, weekly active locations. Not yet measured: GA4 and Vercel Analytics exist; define the dashboard first.
  • Story to tell: a smallholder got a frost warning the evening before and covered the seedlings. Collect these (with permission) and tell them plainly; do not use fear.
  • Loop does: finish the PWA push path for frost (#289) on the Rust side; close the iOS-weather-grade gaps in #171 and #282; prepare mobile for the Play internal track and an iOS submit config; keep offline and repeat-load fast (#269).
  • Done when: a frost alert is delivered end to end to a test device, and mobile has a store-ready build candidate.
  • Safe now: code, tests, builds, preview channels. Needs sign-off: store submissions, push sender credentials, any message that reaches real users.

Objective 6: Advice that changes what someone does

Section titled “Objective 6: Advice that changes what someone does”
  • Entity: Nyuchi (community side is also Bundu research). Refs: #265, #277, community reports, suitability engine, AI summaries.
  • Why: The product’s difference is the answer to “can I do the thing today”: 60-odd activities with feasibility and tips, agriculture windows, place knowledge, community ground-truth. This is what makes the app worth opening instead of any other.
  • Metric moved: share of sessions with a selected activity; activity-card interactions; community reports per week and their verified rate; AI summary helpfulness. Not yet measured: add events for activity adoption and report submission outcomes.
  • Loop does: pick the three most-used regions, review the activity set and tips with local voices (Zimbabwean farming and mining vocabulary is the reference), fix unclear or wrong advice, and grow place-knowledge coverage without inventing specifics.
  • Done when: each of the top activities has reviewed advice, and report volume per week is tracked.
  • Safe now: copy, rules and tests. Needs sign-off: AI prompt changes (they move model behaviour for every user) and any new claim about crops, health or safety.

Objective 7: Break-even without breaking the mission

Section titled “Objective 7: Break-even without breaking the mission”
  • Entity: Nyuchi (fundraising is for scale; surplus flows to Bundu). Refs: #238, #174, #351, developer keys.
  • Why: Aim is break-even, not profit. Costs that grow with users are the Workers, Open-Meteo, Tomorrow.io and AI. Revenue paths in the repo are designed, not built: paid AI summaries and a metered developer API.
  • Metric moved: cost per active user; paying developer keys; partner agreements (mines, farms, schools, airlines) that fund coverage.
  • Loop does: a monthly cost-per-user readout; a one-page paid-AI and developer-API option with the licensing consequence of each; no payment code until the provider is chosen.
  • Done when: the owner has decided the payment provider and the Open-Meteo path.
  • Safe now: costing and write-ups. Needs sign-off: the payment provider, any pricing, any commercial data licence. Do not build an entitlement layer ahead of that decision.

Objective 8: Ship safely and tell the story

Section titled “Objective 8: Ship safely and tell the story”
  • Entity: both. Refs: CONTRIBUTING.md, releases/, the release blockers in #351.
  • Why: The release train (staging to main) is how value reaches people; a red or held release is lost reach. Release notes at /releases are the community-facing record.
  • Metric moved: time from merge to production; releases held by blockers; CI red rate.
  • Loop does: keep the release PR mergeable and green; watch CI; draft each release’s plain-language note in the house format (no PR numbers, code or model names).
  • Safe now: CI repair, conflict resolution on branches this repo owns, draft notes. Needs sign-off: merge to main, deploys, publishing release notes.

Marketing here is service and community storytelling. Each objective has a story shape; use real people with their permission, never invented ones.

Objective Who to tell Channel The story
1 Any place Travellers, diaspora, small towns that were missing /releases, social (Postiz), WhatsApp groups “Your town now has its own page, searched by its own name.”
2 One backend Developers, partner apps Developer docs, /status “Faster, and one API for every Mukoko app.” Only after it is measured.
3 No silo Internal and platform partners Engineering notes Not a public story.
4 Trust Farmers, schools, met-service contacts Direct outreach, station-owner onboarding “Add a gauge, improve your village’s forecast.”
5 Reach Smallholders, mining shifts, commuters Extension officers, WhatsApp, in-person demos, /display in offices “A warning before the frost.”
6 Advice Farmers, miners, coaches, pilots Short how-to posts per activity “Today it is safe to spray between 06:00 and 09:00.”
7 Break-even Partners and funders Partner briefs Cost per person helped, honestly stated.
8 Release notes Everyone /releases, Atom feed What changed for a person, in plain words.

Run one objective per loop. Paste the block, filling the objective number. A loop reads this file first, does the smallest safe step, writes its result as an issue comment on the referenced issue (hand-off: done, left, branch), and ends with a single “Needs you:” line.

/loop 1h Weather playbook, Objective <N> (docs.nyuchi.com/playbooks/weather).
Read the objective and rules in section 2. Do the next smallest safe step
listed under "Loop does". Run the repo's checks for what you changed.
Never merge, deploy, publish or message users. Comment progress and the
hand-off on the referenced issue. End with "Needs you:".

Suggested cadence: Objectives 1, 2, 3 hourly while active; 4 and 6 daily; 5 daily once a store build exists; 7 monthly; 8 on every release PR.

Each of these blocks a named objective. A loop surfaces them; only the owner decides.

Settled since 2026-10-29 (owner messages as recorded in mukoko-weather#475, #293, #561 and #579): Astro is how the web is built, and the weather web build is “Rust serves it, JS only in the browser” (2026-11-04, 2026-11-14); the Astro port stays on the roadmap and is the way forward (this answers item 5 below); stations register on the Nyuchi API, anonymous registration ends and device.devices is the station record (2026-11-13); both Vercel projects retire 30 days after cutover (2026-11-13); link previews are dynamic per page and per place (2026-11-15); the owner approved the station import with dryRun on and without creating a community owner entity (2026-11-13); and an authorised agent merges feature PRs into staging while the release PR is the app’s (2026-11-15, the Releases playbook).

Still open or new:

  • The device-push cutover: the three secrets (the sender key must be issued on the Nyuchi API), the deploys, ALERTS_ENABLED, then the feature flag. Steps and owners are in the Notifications playbook.
  • Station queue #558: fix in the d1 mode now, or wait for the cutover.
  • Gwaihir or the Workers as the weather backend target, and when the Workers’ production traffic is confirmed.
  • Cutover of weather.mukoko.com to the Rust web Worker (DNS, host, first deploy).
  • The OG renderer (decision O-O1 in #475) and the cache rule for the image path.
  1. Payment provider for paid AI and the developer API (Objective 7, #238 P0-1).
  2. StationKit: confirm the single field and unit contract (stationkit issues 5 and 6) and whether the hardware build starts (Objective 4a). Where stations register is decided: the Nyuchi API.
    • Also decide: drop weather_backup_20261028, create an AgriConnect staging branch, and whether mukoko-weather and its Workers move to the nyuchi organisation now that weather is Nyuchi infrastructure.
  3. Open-Meteo commercial path: plan, self-host on Railway (#280), or direct ingestion (Objectives 4 and 7).
  4. Release blockers #351: Atlas read-write user for the Mongo bridge, index repairs, placeKnowledge details (Objective 2).
  5. Whether the Astro port stays on the roadmap. Settled on 2026-11-04 and 2026-11-14: Astro, served by Rust (see above). The earlier recommendation to defer it was not taken.
  6. Mobile store submission and an iOS account (Objective 5).
  7. Applying the data-infra weather model (#90) to the live cluster and, later, the station-to-place backfill (Objective 3). The model is built and released in the repository (#181); nothing was run against the cluster, and the fix scripts wait for the owner’s go.

6a. A new source of ground truth: Zimbabwe’s WIS2 feed

Section titled “6a. A new source of ground truth: Zimbabwe’s WIS2 feed”

Status, 2026-11-17. Both external feeds (this one and SAAOPA below) exist as pure parsing code only. Every feed is off by default, nothing calls either API on a schedule, and there is no Worker transport or cron for them. They still need the owner’s choice of target store, and for SAAOPA permission and attribution wording. The WIS2 query parameters were not verified against the live node.

The Meteorological Services Department (MSD) publishes hourly surface observations from its automatic stations through an open, keyless OGC API under WMO’s core data policy (free and unrestricted exchange). Read from the live node on 2026-10-29 (brief of the same date). This is the strongest ground truth available for Zimbabwe, and it plugs into what exists: weather.stations (registry), weather.stationObservations (raw hourly), then the existing fusion into weather.observations. It needs no new collection.

What the first look found:

  • 19 stations are registered; four reported in the last 15 days (Bulawayo Goetz, Victoria Falls, Buffalo Range, Mount Darwin). Registered does not mean publishing. Buffalo Range had been silent about 20 hours.
  • Rainfall was exactly 0.0 in all 833 reported hours at every reporting station. That may be a dry fortnight, but zero everywhere for 16 days is unusual enough to verify. Hold this feed’s rainfall out of farm advice until MSD or a cross-check (CHIRPS) confirms the gauges.
  • Quirks that break a naive import: one row per parameter per station per hour, so group by reportId (precipitation carries an interval, the rest an instant); wind speed is m/s, so km/h is x 3.6; pressure is station-level, not sea-level; and some stations have doubtful coordinates or elevations (Beitbridge’s published point is near Harare, Nyanga’s elevation and barometer height differ by about 360 m, and Kutsaga is registered twice).
  • Import rules: idempotent upserts keyed wis2:<reportId>; attribution “Meteorological Services Department of Zimbabwe, via WMO WIS2” on every record; flag questionable values, do not fix them; never invent a station that is not in the registry; keep lastObservedAt honest so the app can show a station as stale.

This feeds Objective 4 directly: it is the observation set the forecast verification join needs, and a model for registering stations on the Nyuchi API (a WIGOS id and a Places id on each station). Open decisions from the brief (D1 to D8): which metrics naming family the app reads, where the WIGOS id lives, station versus sea-level pressure, province assignment by polygon (provinces are centroids today), how official data ranks against community data in fusion, an MSD record in entity.entities, and rainfall trust. The reference code in the brief was run against the live API.

wx.saaopa.org is a community weather site (“WX-CoPilot”, run under SAAOPA, saaopa.org). Its page is a script-driven app; the API it calls is wx-api.saaopa.org. Read on 2026-10-29 from the public routes only (/stations, /stations/status, /stations/{code}, /metar/{code}; the admin routes need a login and were not touched):

  • 84 stations: 25 automatic weather stations (aws, all reporting, about 8 minutes old), 57 official aerodromes and 2 webcams. 34 are in Zimbabwe, then South Africa (16), Mozambique (12), Botswana (10), Namibia (7) and Zambia (5).
  • Live fields: temperature, dew point, wind direction, wind speed and gust (knots) and QNH, about every 10 minutes. No rainfall in the status route.
  • No stated terms. There is no OpenAPI document, no licence and no operator named on the page. Ask SAAOPA for permission and attribution wording before any scheduled call. The parsers exist; nothing calls the API.
  • Do not duplicate: the 57 official aerodromes republish METARs we can read from the Aviation Weather Center. Ingest the 25 aws stations only.
  • QNH is not station pressure. It is kept as its own value, never written to the station-pressure metric.

The parsers for this feed and for the MSD WIS2 feed are weather_core::external_feeds (mukoko-dev/mukoko-weather#362); the plan, the gates and what is not built are in mukoko-dev/mukoko-weather#361. A WIS2 page boundary can cut a station-hour in two (seen live), so a writer must merge per metric, never replace.

Read from GitHub on 2026-11-17. “Blocked” means the PR text says it is waiting on something. Dependabot PRs are counted, not listed. The sweep of 2026-10-29 is replaced, not kept: most of it described a state that has changed.

Repo Open PRs worth knowing
mukoko-dev/mukoko-weather #583 device push (draft; owner secrets, public key, flag), #578 season names by region (draft; waits on native speakers), #580 adopt org standards (bot). Two Dependabot PRs. staging and main carry the same tree; releases are opened and merged by bundu-release[bot]. #356 (the old release PR) was closed on 2026-10-31
nyuchi/nyuchi-api #585 the v0.61.0 release PR, #572 a staging-to-main PR that was conflicted, #573 org standards, #568 owner decisions log (draft), #539 Shamwari machine-token-only (draft), #551 and #561 (superseded, left open on purpose), #518. No Dependabot
nyuchi/nyuchi-servers-api #50, #47, #46 and #41 (drafts), #49 org standards. Issue #15 is Gwaihir
nyuchi/data-infra #189 org standards, #160 CAP alert facet (draft, held), #124 news bridge (draft, held), #108 UUIDv7 re-key (draft, held), #107 placeKnowledge (draft; superseded by the merged #176), #96 and #97 (superseded, still open). Two Dependabot PRs
nyuchi/stationkit #24 org standards, #25 a stale release PR, three Dependabot PRs. main contains staging. #20 is still open though its code merged in #21; #1 to #6 are the draft specification
nyuchi/nyuchi-docs #120 a release PR, #118 org standards, #113 audit floors (draft), and Dependabot PRs
nyuchi/maps #6 a release PR and #7 org standards; one commit and no code
mukoko-dev/mukoko-api #34 a stale release PR, #36 org standards, four Dependabot PRs. Issue #9 is the weather migration
nyuchi/nyuchi-platform #391 (retire console-rs) was closed unmerged on 2026-10-30

Stale or risky, in order:

  1. Device push is code-complete and dark. #583 has never run in a Workers runtime. Merging it deploys two Workers that fail until the secrets exist, and jobs also carries cache warming and retention, so the owner’s secrets come first.
  2. The release rules disagree (merge commit or squash; two release mechanisms in nyuchi-api). See the Releases playbook.
  3. #107 versus #176. The draft is superseded and still open; close it.
  4. The weather model is built and not applied. The fix scripts on the live cluster were never run and need the owner’s go.
  5. Dependabot PRs wait unreviewed in most repos. Batch them weekly.

The loop for this section is Objective 8: re-run the sweep, report changes, and never merge a release PR.

  • New map base-map service (#298, replaces MapTiler; the nyuchi/maps repo is an empty shell, so there is nothing to build on yet) and new overlay sources (#272): real value, but they add architecture while the backend cutover is unfinished. Revisit after Objective 2.
  • Shamwari full-page chat stays paused (flag off). AI stays ambient.
  • Premium-maps, vector search and multi-language flags stay off.
  • New weather data sources beyond rainfall (#247 lists more): one source at a time, after verification exists.

Review of 2026-11-17. Built from the repositories’ documents, pull requests and issues and from the live Fly and Cloudflare inventory, by research agents reading read-only. Not verified: whether any Worker carries production traffic, the store status of the mobile app, the contents of nyuchi/.github, the stations in MongoDB weather.stations, and where weatherstations.nyuchi.com is served from. The 2026-10-29 limits below still apply to what was not re-read.

  • Built from repo documents and issue titles and bodies (some truncated), not from production telemetry. No metric here has a measured baseline.
  • StationKit was read from its README and issues #1 to #6 and #16. Hardware (#3) and firmware (#4) are specification with TODO markers: the BOM, panel, cell, rain gauge, anemometer and GSM modem parts are all unconfirmed, and OTA is undefined. Indicative kit prices are from $25 (Basic) and $65 (Full).
  • nyuchi/maps was read from its repo: one commit, a one-line README, a licence, no code and no issues. The base-map plan lives in mukoko-weather#298, not here.
  • nyuchi-docs, nyuchi-platform and super-app-web were searched for weather content only; super-app-web links out to weather rather than showing live data.
  • data-infra is now attached; only #90 (with comments) and PR #117 were read. The Cloudflare account lists the Workers by name but I could not read their routes, so which Worker serves weatherstations.nyuchi.com is unconfirmed.
  • Earlier text that called the Rust Workers “not deployed” came from issue #164 (2026-10-08) and is out of date: they were last modified 2026-10-19. Whether they take production traffic is unverified.