C0 Config

c0 Config

Use this skill whenever work changes c0 configuration or the boundary between deployment-managed and runtime-managed state.

Canonical Deployment Configuration

The selected config/<stage>.config.jsonc file is the only source of truth for non-secret operator configuration. Keep configuration readable, reviewable, and shareable there rather than encoding objects in environment variables.

• Keep complete, independent config/dev.config.jsonc, config/test.config.jsonc, config/pre.config.jsonc, and config/prod.config.jsonc files in the repository's config/ directory. Do not add cross-file inheritance, partial overrides, or profile merging.
• Keep the stage JSONC files, config/example.config.jsonc, and config/c0.config.schema.json tracked. Ignore secret-bearing config/.env and config/.*.vars files while tracking their example templates.
• Map preview stages such as pre-123 to config/pre.config.jsonc. Other supported stages map directly to config/<stage>.config.jsonc.
• Fail before creating Alchemy resources when the selected file does not exist or fails schema validation.
• Parse and schema-decode only the selected file once at the Alchemy deployment boundary.
• Use that same resolved object for infrastructure decisions and Worker bindings so build-time and runtime configuration cannot drift structurally.
• Keep schemaVersion explicit and regenerate config/c0.config.schema.json when the schema changes.
• Point every stage file at the generated config/c0.config.schema.json. Run nub run config:check after editing any stage file or its schema. Run nub run config:schema intentionally when the generated schema needs to change.
• Define the external JSON contract with Effect Schema and generate the editor schema from that same contract. Schema.Struct is appropriate for plain JSON DTOs; use Schema.Class only when configuration values need class identity, constructors, methods, or branding.

Do not parse stage JSONC in a Worker or web request. Do not add a serialized JSON environment variable or a duplicate defaults layer.

Cloudflare Binding Boundary

Alchemy compiles the resolved config into bounded bindings:

• Pass cohesive, small server domains as native Cloudflare JSON bindings, such as C0_CONFIG_AUTH or C0_CONFIG_MCPCF.
• Pass browser-safe values as explicit VITE_* scalars. Never expose a secret or the full server configuration to the browser.
• Do not pass the entire configuration as one large binding. Cloudflare applies binding-count and per-binding size limits.
• Keep deployment-time binding budget checks close to the infrastructure code.
• Derive Worker env types from the Alchemy resources. Do not hand-write or cast a parallel env contract when resource inference is available.

Native JSON bindings arrive as objects. Runtime code should schema-decode them as objects and must not accept legacy JSON strings as a hidden fallback.

Secrets

Secret values never belong in a stage config file. Reference them explicitly at the field that consumes them:

{
  "apiKey": {
    "env": "C0_LITELLM_API_KEY"
  }
}

• Secret reference names must be explicit, stable uppercase environment binding names.
• Do not derive secret names from JSON paths or KV keys.
• Only secrets explicitly marked with "generateIfMissing": true may be generated by Alchemy.
• Generated secrets must use stable Alchemy logical ids so they persist in Alchemy state across deployments.
• A referenced active secret must resolve or deployment must fail closed. Do not silently fall back to a KV secret when the JSONC field explicitly names a missing deployment secret.
• Disabled integrations and providers should not require their otherwise-unused secrets.
• config/.dev.vars, config/.test.vars, config/.pre.vars, and config/.prod.vars contain secrets and deployment credentials only, never non-secret configuration objects.
• Use nub run config:write-stage-vars -- <stage> <path> to reconcile a stage file with the active secret references before syncing or deploying it.
• Never print secret values during validation or handoff. Names-only inspection is safe.

Deployment and Runtime Precedence

For a domain that supports Admin editing, use this precedence:

1. An explicit domain in the selected stage config is deployment-managed and locked in Admin.
2. If the domain is omitted, read its editable value from C0_CONFIG KV.
3. If neither exists, use the domain's documented default or unconfigured state.

The lock message must identify the active stage config location, for example config/prod.config.jsonc:aiProviders.litellm, and explain that the field must be removed from deployment configuration and redeployed before Admin can edit it.

Do not add long-lived compatibility fallbacks for old env names. Migrate callers and delete the obsolete path.

Authentication is deployment-managed because it defines which providers may establish identity. Provider kind does not grant authority: provider capabilities independently control sign-in, user provisioning, and explicit account linking. Keep implicit account linking disabled and keep provider secrets as explicit secret references.