Runtime Config Schema

BIGGI config has two related but separate paths:

• The embedded BIGGI runtime loads and merges config locally.
• Cloud-served JSON Schema gives editors validation and completion for biggi.json and biggi.jsonc.

JSON Schema does not load, apply, or override runtime config.

{
  "$schema": "https://app.biggi.dev/config.json"
}

Two separate paths

flowchart LR
  subgraph runtime ["Runtime config loading"]
    files["Global, project, organization,<br/>managed, and runtime config sources"] --> loader["BIGGI runtime config loader"] --> effective["Effective runtime config"]
  end

  subgraph schema ["Editor validation and completion"]
    info["Config.Info<br/>Effect Schema"] --> generated["Locally generated schema<br/>for verification"]
    upstream["https://opencode.ai/config.json"] --> overlay["BIGGI Cloud merge route"]
    extras["BIGGI extras.ts overlay buckets"] --> overlay --> endpoint["https://app.biggi.dev/config.json"] --> editor["Editor validation and completion"]
    generated -. "Keep aligned" .-> extras
  end

Changing runtime config precedence affects the first path. Adding or changing a config key affects both paths because the editor schema must describe keys the runtime accepts. See Embedded Runtime for runtime ownership.

Source of truth

The canonical runtime config source is Effect Schema Config.Info in packages/opencode/src/config/config.ts in stemcat/biggi. The runtime derives a .zod compatibility surface from Effect Schema for plugin and SDK consumers. Do not maintain a separate handwritten Zod definition for BIGGI config fields.

Cloud schema endpoint

Static source review of BIGGI-Org/cloud shows this route behavior:

1. Editor fetches https://app.biggi.dev/config.json because config file references $schema.
2. Cloud route apps/web/src/app/config.json/route.ts fetches https://opencode.ai/config.json.
3. Route runs merge() and returns upstream schema with BIGGI additions and overrides.
4. merge() overlays buckets from apps/web/src/app/config.json/extras.ts.

Cloud source defines 1-hour upstream revalidation and edge-cache headers. This describes checked-in route behavior, not live deployment or cache state.

Overlay buckets

Reviewed cloud source overlays:

Nested runtime fields outside these buckets need a dedicated overlay bucket and matching merge() logic.

Failure mode

If the cloud overlay misses a valid runtime field, the runtime can accept config while the editor reports unknown property. Opposite drift is also possible: the cloud schema can advertise a field that the runtime no longer accepts.

Treat schema synchronization as cross-repository contract. Tests should detect both missing valid fields and stale overlay entries. Keep branch-specific drift findings in tracked issues or test output, not this architecture page.

Adding or changing BIGGI-only config key

1. Add or update Effect Schema field with biggi_change marker in packages/opencode/src/config/config.ts.
2. Generate JSON Schema shape:

bun --bun packages/opencode/script/schema.ts /tmp/biggi.json
jq '.properties.<new_key>' /tmp/biggi.json

3. Update matching bucket in apps/web/src/app/config.json/extras.ts in cloud repo.
4. Extend merge() in apps/web/src/app/config.json/route.ts when new nested bucket is required.
5. Add assertion in apps/web/src/tests/cli-config-schema.test.ts.
6. Audit stale overlay entries as well as missing additions.

Source map

Repository column identifies source root for each relative path.

Related pages

• Embedded Runtime - runtime config ownership
• Development Patterns - shared-file markers, BIGGI-owned boundaries, and cross-repository contributor workflow