/gaia-config-brownfield

What it does

/gaia-config-brownfield edits the brownfield section of .gaia/config/project-config.yaml. This section carries the deterministic-tools knobs consumed by /gaia-brownfield and /gaia-doctor: whether deterministic tools are enabled, the runner (docker vs native), grype on/off, and the scanner tier (0 / 1 / 2 / auto). The editor preserves all YAML comments and formatting outside the edited section.

Before this command landed, the deterministic-tools suite was hand-edit-only, contradicting the framework's "no manual YAML" rule.

When to use it

• You want to turn the deterministic-tools suite on or off without hand-editing YAML.
• You need to switch the brownfield runner between docker and native.
• You want to enable or disable grype dependency scanning.
• You need to pin the scanner tier (0 = LLM-only, 1 = pure-pip, 2 = heavy/native, auto = host-detect).

Prerequisites

• .gaia/config/project-config.yaml must exist. Run /gaia-init to create one if missing.

How to invoke

/gaia-config-brownfield                                 # show + menu
/gaia-config-brownfield set deterministic_tools true
/gaia-config-brownfield set tools.runner docker
/gaia-config-brownfield set grype_enabled true
/gaia-config-brownfield set scanner_tier auto
/gaia-config-brownfield show
/gaia-config-brownfield clear grype_enabled

What it does step by step

1. Locate project-config.yaml Resolves the path via the canonical resolver.
2. Print current state Renders the brownfield: block (or unset per key when absent).
3. Validate enums Rejects out-of-enum values: deterministic_tools = bool, tools.runner = docker | native, grype_enabled = bool, scanner_tier = 0 | 1 | 2 | auto.
4. Diff preview and confirmation Shows a unified diff of what will change. You must confirm before anything is written.
5. Comment-preserving write Routes through config-yaml-editor.sh so only the brownfield section is touched.
6. Post-write reminder When you flip deterministic_tools to true, the command tells you to run /gaia-doctor next to verify the deterministic-tools chain is installed on the host.

Inputs

Outputs

Example session

> /gaia-config-brownfield set deterministic_tools true

current brownfield:
  deterministic_tools: false
  tools.runner:        docker
  grype_enabled:       unset
  scanner_tier:        auto

Diff preview:
    brownfield:
  -   deterministic_tools: false
  +   deterministic_tools: true
      tools:
        runner: docker

Apply this edit? [y/n]
> y

brownfield section updated. deterministic_tools=true requires the deterministic-tools
chain on $PATH. Run /gaia-doctor now to confirm Tier 2 readiness on this host.

What to run next

• /gaia-doctor -- verify the deterministic-tools chain is installed (immediately after enabling deterministic_tools).
• /gaia-config-validate -- validate the modified configuration file.
• /gaia-brownfield -- re-run the brownfield scanner with the new knobs.

Troubleshooting

brownfield section not found

The section does not exist in your config file. The command appends a fresh block via config-yaml-editor.sh insert on first set.

Unknown key

Supported keys are deterministic_tools, tools.runner, tools.image (the docker-runner image reference — see the docker workflow page), grype_enabled, scanner_tier. Anything else exits 1 with a clear error. (tools.image is supported by the SKILL and included in this list.)

Out-of-enum value

The command rejects values outside the documented enum and lists the accepted set. No partial write occurs.

/gaia-doctor reports missing tools

You enabled deterministic_tools on a host that doesn't have the chain installed. Either install the missing binaries (the doctor output is copy-pasteable) or pin the scanner_tier to a tier your host supports.

Related commands