Developer setup and contribution

Prerequisites and repository layout

Use the repository’s lockfile and Node engine constraint: >=24.14.0 <25 or >=26 <27. The product-test runner has a stricter explicit version list; Node 24.14.0 was used for this documentation delivery. Do not assume the newest Node minor is accepted by every gate.

Source code lives under src and server; tests are under tests/lookout and alongside selected modules. public is copied to the frontend build. deploy and scripts/operators contain release tools, not blanket authority to run them against a host.

The application repository does not include production account files, signing secrets or the private M1 runtime. Use approved local fixtures or an explicitly authorized private runtime for the lane being tested.

From a clean application checkout with its lockfile

node --version
npm ci
node scripts/build-lookout-docs.mjs --check
npm run docs:check

Build and preview documentation

The documentation portal has no build-time web dependency. Manual content, release fixtures and application registries generate both Markdown and static HTML. The lightweight preview serves only documentation assets; it does not run the API or use production data.

npm run docs:build
npm run docs:check
npm run docs:preview
# Open http://127.0.0.1:4176/documentation.html

Build the frontend

The verification config keeps the production transforms while pinning the checkout root and Cesium asset copy. The base config may require a trusted data descriptor in runtime/preview modes. A build succeeding does not mean a production-compatible API is configured.

Use synthetic browser harnesses for UI development when you do not have an authorized private data runtime. Their recorded values and account context must never be described as production measurements.

node node_modules/vite/bin/vite.js build \
  --config scripts/lookout-vite-verify.config.mjs \
  --outDir /tmp/lookout-local-build
P9_BUILT_DIR=/tmp/lookout-local-build node --test \
  tests/lookout/product/ux/P9-guided-flow.browser-runtime.test.mjs

Configured API prerequisites

The real API starts through server/app/start.mjs and fails closed unless its explicit identity, origin, trusted data and workspace configuration are valid. A blank .env template is not sufficient. Create local operator-owned configuration through the approved runtime workflow; do not copy production secrets to a developer machine.

The table identifies configuration responsibilities, not sample credentials or a complete deployment command. Inspect the referenced loaders for exact schemas and size/mode checks.

Choose the right test lane

Product test configuration requires explicit isolated local origins and non-delivering transports. Some real-runtime lanes require approved root-owned data trees. Do not turn a missing prerequisite into a skip and claim the release passed. Keep failed runs as evidence and distinguish fixture tests from real data acceptance.

Contribution and review workflow

1. Branch from the intended release baseline and inspect the worktree before editing. Keep unrelated user changes and accepted release artifacts intact.
2. Change the source of truth: manual docs content, the actual route/provider, or the reviewed data definition. Generated docs are outputs, not hand-edit targets.
3. Run focused tests for the behavior changed, regenerate documentation, and verify links and source references. For UI changes, check narrow screens, keyboard access and empty/error states.
4. Record source/rights/method changes explicitly. An overlap method change needs a new method version; a source change needs data acceptance, not only a frontend edit.
5. Prepare a reviewable change with scope, evidence and known limitations. Build a new image for deployment rather than altering the live immutable image.