# Configuration

oduit supports several config shapes for compatibility, but the preferred user
facing format is sectioned TOML.

## Recommended Format

Local or environment configs should look like this:

```toml
[binaries]
python_bin = "./venv/bin/python"
odoo_bin = "./odoo/odoo-bin"
coverage_bin = "./venv/bin/coverage"

 [odoo_params]
 addons_path = "./addons,./enterprise"
 db_name = "project_dev"
 db_user = "odoo"
 db_host = "localhost"
 http_port = 8069
 write_protect_db = false
 agent_write_protect_db = false
  needs_mutation_flag = false
  agent_needs_mutation_flag = false
```

## Recommended setup for existing Odoo projects

If you already have an `odoo.conf` file, prefer importing it instead of
rewriting the config by hand:

```bash
oduit init dev --from-conf ./odoo.conf
oduit --env dev print-config
oduit --env dev doctor
```

For a project-local config, write `.oduit.toml` directly:

```bash
oduit init dev --from-conf ./odoo.conf --local
oduit print-config
```

Use `--dry-run` to preview the generated TOML without writing a file. The
generated config may include secrets imported from `odoo.conf`.

Runtime DB mutation policy is controlled by explicit flags:

- `write_protect_db` blocks runtime DB mutation for every caller
- `needs_mutation_flag` requires `--allow-mutation` for human runtime DB mutation
- `agent_write_protect_db` blocks runtime DB mutation for agent commands
- `agent_needs_mutation_flag` requires `--allow-mutation` for agent runtime DB mutation

Plain test runs stay read-only. Only runtime flows that install, update,
uninstall, create a database, or explicitly trigger runtime actions consult these
flags.

The legacy risk-level key is no longer supported and now raises a config error.

## Supported Locations

- local project config: `.oduit.toml`
- named environment config: `~/.config/oduit/<env>.toml`
- compatibility support: `~/.config/oduit/<env>.yaml`

## Compatibility Notes

oduit still accepts:

- flat config files with keys at the root level
- YAML environment files

Those shapes are compatibility support, not the preferred format for new docs
or new projects.

## Canonical Normalized Shape

Internally, oduit now treats the sectioned shape as the canonical normalized
configuration:

```toml
[binaries]
python_bin = "./venv/bin/python"
odoo_bin = "./odoo/odoo-bin"
coverage_bin = "./venv/bin/coverage"

[odoo_params]
addons_path = "./addons,./enterprise"
db_name = "project_dev"
```

`oduit agent resolve-config` exposes both the compatibility
`effective_config` view and the canonical `normalized_config` view, plus
`config_shape` metadata with a `shape_version`.

Legacy flat config files remain supported, but `resolve-config` now reports a
deprecation warning when they are detected so agents can migrate toward the
sectioned TOML shape.

## Canonical Normalized Shape

Internally, oduit now treats the sectioned shape as the canonical normalized
configuration:

```toml
[binaries]
python_bin = "./venv/bin/python"
odoo_bin = "./odoo/odoo-bin"
coverage_bin = "./venv/bin/coverage"

[odoo_params]
addons_path = "./addons,./enterprise"
db_name = "project_dev"
```

`oduit agent resolve-config` exposes both the compatibility
`effective_config` view and the canonical `normalized_config` view, plus
`config_shape` metadata with a `shape_version`.

Legacy flat config files remain supported, but `resolve-config` now reports a
deprecation warning when they are detected so agents can migrate toward the
sectioned TOML shape.

## Operation sets are not environment configuration

Environment configuration stays in `.oduit.toml` or
`~/.config/oduit/<env>.toml`. Operation sets live beside the active config and
store reusable execution plans for install, update, or test operations.

For local project config:

```text
.oduit.toml
.oduit/
  sets/
    base.toml
```

For named environments:

```text
~/.config/oduit/dev.toml
~/.config/oduit/sets/base.toml
```

Use `oduit set inspect`, `oduit set apply`, and `oduit set list` to work
with sets. Save addon lists into sets with `--save-set` and `--set-kind`.
Reorder install/update sets with `install-order --from-set`.

Short names resolve from the active config set store, then `.oduit/sets/`,
then `~/.config/oduit/sets/`.

Paths in `[test].test_files` resolve relative to the set file, not necessarily cwd.

### Execution controls

Operation sets may define execution controls inside their matching section.
`verify_state` enables database state verification after install/update steps.
`retry_missing` retries addons that are still not installed after verification.
`one_by_one` executes addon operations individually.
`retry_failed_tests` applies to test tags and files in test sets.
`stop_on_error` controls whether execution stops on the first failure.
`skip_installed` (install only) skips already-installed addons.
`require_installed` (update only) fails precheck for uninstalled addons.

Equivalent CLI options: `--verify-state`, `--retry-missing`, `--one-by-one`.
CLI options override set-file keys for each invocation.

## Important Keys

Binary keys:

- `python_bin`
- `odoo_bin`
- `coverage_bin`

Common Odoo keys:

- `addons_path`
- `db_name`
- `db_host`
- `db_port`
- `db_user`
- `db_password`
- `write_protect_db`
- `agent_write_protect_db`
- `needs_mutation_flag`
- `agent_needs_mutation_flag`
- `config_file`
- `without_demo`
- `log_level`
- `http_port`
- `workers`
- `odoo_series` (optional explicit override when addon-based detection is unavailable)

## Translation-specific config caution

Legacy Odoo server keys such as `translate_out`, `translate_in`,
`load_language`, `overwrite_existing_translations`, and
`translate_modules` remain supported for compatibility, but they are risky as
persistent environment defaults. Prefer passing translation inputs explicitly to
`oduit i18n export`, `oduit i18n import`, and `oduit i18n loadlang`
instead of storing them in shared config.

## Documentation workflow settings

Use this section to constrain addon technical documentation writes and scans:

```toml
[documentation]
allowed_addon_dirs = ["./addons"]
```

`allowed_addon_dirs` values are resolved relative to the project base:
`.oduit.toml` directory when present, then git root, then current working
directory.

This keeps `technical-next` and `technical-status` focused on your project
addons and avoids selecting native/third-party addon roots by default.

Legacy flat-key compatibility remains supported through
`documentation_allowed_addon_dirs`.

## Python Usage

```python
from oduit import ConfigLoader

loader = ConfigLoader()
dev_config = loader.load_config("dev")

if loader.has_local_config():
    local_config = loader.load_local_config()

envs = loader.get_available_environments()
```

## Import Existing Odoo Configuration

For the full migration workflow, including validation steps and no-pytest smoke
checks, see {doc}`migrate-odoo-conf`.

## Diagnostics

Use `doctor` to validate that your config, binaries, addons paths, version,
and database settings all line up:

```bash
oduit doctor
oduit --env dev doctor
```