Select an independent environment

Module preferences additionally have base → selected JSON overlay → generic binding → selected-prefix precedence. No KB module adoption occurred; general PHP configuration remains unchanged.

Steps

Set APP_ENV in the shell/service environment or a private uncommitted .env. Select DEV, TEST, STAGE, or PROD; the loader normalizes the supported names.

APP_ENV=TEST php bin/import-docs
APP_ENV=DEV php -S 127.0.0.1:8081 -t public public/dev-router.php

The import command is editorial, not environment-specific; the selected documentation revision is shared. Accounts, sessions, rate files, and AI ledgers are environment-specific.

Use DEV_KB_SECURE_COOKIE=false only for loopback HTTP development. Hosted STAGE/PROD require HTTPS and secure cookies. Do not trust a forwarded scheme unless the peer belongs to the explicit trusted-proxy list.

Verify

Inspect config/load.php, the schema, and the selected overlay. A missing STAGE secret must not fall back to DEV or PROD. See Configuration.

Candidate-only module preferences

The candidate's optional module policy reads private, bounded config/modules.json, not executable module preferences. General PHP configuration and native PHP templates remain PHP. Convert old literal preference values manually; never include or execute old PHP as a converter or fallback. The KB has not adopted this loader or activated a module.

Illustrative preference shape, not a complete trusted module catalog:

{
  "modules": {"example.local": {"enabled": false, "adapter": "local", "disable": "complete"}},
  "environments": {"dev": {"example.local": {"enabled": false}}, "test": {}, "stage": {}, "prod": {}}
}

Use JSON objects, including {} for an empty map, and real booleans, not [] or strings such as "false". Keep preferences outside the public directory. The loader bounds input to 256 KiB/depth 16 and validates every environment overlay. Precedence is base preferences, selected environment overlay, generic MODULE_EXAMPLE_LOCAL_ENABLED, then selected-prefix DEV_MODULE_EXAMPLE_LOCAL_ENABLED. Other environment prefixes do not participate. The trusted catalog separately defines valid module/adapter identities and readiness; credentials cannot make an OFF module available. Startup snapshots need controlled restart for long-lived workers. See module activation for the complete schema, loader example, safe failures and explicit HTTP/CLI/worker/scheduler adoption.

Editorial provenance

Source: resources/guides/environments.md. Source SHA-256: 7268b0cb4393d9a05a24f13458f3fbe14ef28e7abf47b6f40c23ffe7ba45e571.

Knowledge-base application source; editorial checkpoint 2026-10-20. See candidate status and adoption boundary.