Update common things

Last reviewed against the codebase: 2026-07-25.

The routine changes a maintainer makes - a new environment variable, a schema column, an API route, a feature flag - and how to make each one without leaving the docs or the schema behind. The theme running through this whole page is a single design decision: anything that can be derived from the code is generated from the code, and a CI gate fails the build if the committed output drifts from source. So “updating a thing” almost always has two halves - change the code, then regenerate the artifact that mirrors it - and this page tells you which artifact and which command for each case.

If you only remember one command, remember this one. From Fire-Path-AI/:

pnpm --filter @workspace/docs-site run gen && \
pnpm --filter @workspace/docs-site run check:drift

That regenerates all four drift-gated reference sections and then verifies they match what’s committed. Everything below is a more surgical version of the same loop.

Why the reference regenerates instead of being hand-written

Four reference sections are generated directly from the codebase, not authored:

Generated page	Source of truth	Generator
Data model	the Drizzle schema barrel lib/db/src/schema/index.ts	gen:datamodel
Configuration	env vars read by the api-server (config.ts + raw process.env)	gen:config
API reference	the Express route files in artifacts/api-server/src/routes/	gen:api
Repository guide	the workspace package.json files	gen:repotree

The why: a hand-written reference is stale the moment someone forgets to update it, and a life-safety system cannot ship documentation that quietly lies about which columns exist or which endpoints are live. Generating from source makes staleness a build failure instead of a silent defect. Each generated file carries a <!-- GENERATED FILE - do not edit by hand --> marker with the exact regenerate command; do not hand-edit these files - your edit will be overwritten on the next gen and, worse, will trip the drift gate on the way.

The rich, hand-maintained narrative that a generator can’t infer (the “why” behind a variable, cross-references between tables) lives in the Overview & architecture page and is maintained separately - see the last section.

Regenerate the drift-gated reference

After any change to the data model, API routes, environment variables, or workspace layout, regenerate and commit the output. From Fire-Path-AI/:

pnpm --filter @workspace/docs-site run gen

gen runs all four generators in sequence (gen:datamodel && gen:config && gen:api && gen:repotree). Expected output is one ✓ … generated - N … line per generator, for example ✓ repository.md generated - N packages. Then confirm the committed output matches:

pnpm --filter @workspace/docs-site run check:drift

On success: ✓ drift gate passed - generated reference matches the committed code.

The drift gate is a git diff, so you must commit the regenerated output

check:drift works by running git diff (and git ls-files --others) over src/content/docs/reference/. It fails if a generated file differs from what is committed or is untracked. That means:

• Regenerating without committing → the gate still fails (the working tree differs from HEAD). Fix: git add + commit the regenerated Markdown.
• A brand-new generator whose output was never committed → flagged as untracked. Fix: commit the new file.
• Uncommitted unrelated edits inside the reference/ directory → also flagged. Keep hand edits out of that directory entirely (that’s why the pages are marked generated).

Recovery is always the same: pnpm … run gen, then commit the result, and the gate goes green.

There is a second, related gate - check:reference - that catches a failure the drift gate cannot: a generator that silently no-ops (bad path, swallowed exception) and emits an empty page. Because an empty-but-committed page passes check:drift, check:reference independently asserts each of the four sections exists, still carries its GENERATED marker, and has at least one ## heading, and that every sidebar link: resolves to a real file. Both gates run in the ci and build scripts, so CI catches drift even if you forget to run it locally.

Change configuration or a feature flag

Environment configuration lives in two files that must stay in step:

• .env.example - the committed, documented template (safe placeholder values only; never real secrets).
• your local .env - real values, git-ignored.

To add or rename a variable, edit both, then regenerate the Configuration reference (adding/renaming a variable changes it):

pnpm --filter @workspace/docs-site run gen:config

Why regenerating catches you here: gen:config statically scans the api-server source for every requiredEnv / optionalEnv / boolEnv / numberEnv helper call and any raw process.env.X, then emits the table. So if you read a new variable in code but forget to document it, the generated list changes and the drift gate fails until you commit - the code and the documented variable set can’t diverge.

Dynamically-named flags can’t be captured statically

Per-jurisdiction incident flags are built at runtime, e.g. boolEnv("INCIDENTS_<code>_ENABLED"). A static scan can’t see those names, so they will not appear in the generated Configuration reference. They are documented in .env.example instead - for example the INCIDENTS_NSW_RFS_ENABLED, INCIDENTS_QLD_FIRE_ENABLED, INCIDENTS_ACT_ESA_ENABLED, INCIDENTS_TAS_TFS_ENABLED family and the FIRE_CLUSTERING_ENABLED / FIRE_INCIDENTS_ENABLED toggles. If you add another dynamic flag, document it in .env.example by hand.

Do not hardcode identity/contact/config literals across files. Every such value has a single config source and is injected via env/secrets, so a change is one edit in one place, not a find-and-replace across the tree.

Evolve the database schema

Edit the schema in lib/db/src/schema/ (one file per table - alerts.ts, assets.ts, fire_incidents.ts, and so on, all re-exported from index.ts). Then push the change to your database and regenerate the data-model reference:

pnpm --filter @workspace/db run push
pnpm --filter @workspace/docs-site run gen:datamodel

push runs drizzle-kit push against DATABASE_URL. gen:datamodel reads the schema barrel connection-free (it imports the TypeScript directly, so it never needs a live database) and re-emits Data model, which reports the total table count and every column. Commit the regenerated file or the drift gate fails.

Two real gotchas that bite new maintainers on push

1. Enable extensions before you push. The schema uses the PostGIS spatial type and citext (case-insensitive text). drizzle-kit push does not create Postgres extensions for you - if citext/PostGIS aren’t already enabled on the target database, the push fails or produces the wrong column types. Enable the required extensions on the database first, then push.
2. PostGIS bookkeeping tables are excluded on purpose. drizzle.config.ts sets tablesFilter: ["!spatial_ref_sys", "!geography_columns", "!geometry_columns"] so drizzle-kit’s introspection ignores PostGIS’s own tables. Without this, push prompts you asking whether each new table is a rename of spatial_ref_sys - an easy way to corrupt a migration. If you ever see that prompt, stop and check the filter is intact rather than answering it.

Use push-force (drizzle-kit push --force) only when you knowingly accept a data-loss-capable statement - it skips the confirmation drizzle would otherwise ask for, so treat it as a deliberate, reviewed action, never a reflex.

Add or change an API route

Add the route in artifacts/api-server/src/routes/ and mount it in routes/index.ts, then regenerate the API reference:

pnpm --filter @workspace/docs-site run gen:api

gen:api parses the Express route files - the mount prefixes in routes/index.ts plus each router’s METHOD("path") calls - and emits a complete endpoint list to API reference, grouped and drift-proof. It reports the endpoint and group counts.

The endpoint list is generated; request/response schemas are not - yet

The generated page lists every endpoint (method + path), which is enough to never miss a route. Full request/response schemas are only hand-documented for the stable public subset in lib/api-spec/openapi.yaml; expanding that spec to full coverage is tracked in the authoring backlog, not done. So: adding a route updates the generated list automatically, but if you want its schema documented, you also edit openapi.yaml by hand.

Verify before you commit

Before committing a change, run the same checks CI runs. The docs site has an all-in-one ci script that regenerates, gates drift + reference, builds, then runs the redaction and broken-link gates over the built output:

pnpm --filter @workspace/docs-site run ci

For the api-server or the app, the workspace convention is typecheck + test (Vitest). For example:

pnpm --filter @workspace/api-server run typecheck
pnpm --filter @workspace/api-server run test

The runtime health endpoints (/healthz, /readyz) are the operational equivalent - see the deployment and operations material for those.

Update the architecture overview (the hand-maintained page)

The Overview & architecture page is the one narrative that does not regenerate itself. The generated reference keeps the facts (tables, endpoints, variables) current automatically; the architecture page carries the story - tiers, external feeds, prediction method, and the Capability status table - which no generator can infer.

When a tier, external feed, prediction method, or capability status changes, update that page’s Capability status table and bump its freshness date. The page lists its own explicit “update triggers” so you know exactly when it’s owed a revision.

Finally, bump the _Last reviewed against the codebase_ line at the top of any get-started page you revise - including this one - so a reader can trust how current the guidance is.