# Quick Start Guide

This guide shows the current recommended setup and the main user-facing
workflows.

## Migrating from an existing odoo.conf

If you already have an Odoo project with an `odoo.conf`, start with the CLI
import path:

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

Useful overrides:

```bash
oduit init dev \
  --from-conf ./odoo.conf \
  --local \
  --python-bin ./.venv/bin/python \
  --odoo-bin ./odoo-bin
```

Inspect the generated config with `print-config` before using it. The
generated TOML may contain secrets imported from `odoo.conf`.

## Preferred Configuration

Use sectioned TOML for both local and named environments.

### Local `.oduit.toml`

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

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

Then you can run commands without `--env`:

```bash
oduit doctor
oduit version
oduit list-addons
```

### Named Environment Config

```toml
[binaries]
python_bin = "/usr/bin/python3"
odoo_bin = "/opt/odoo/odoo-bin"

[odoo_params]
addons_path = "/opt/odoo/addons,/opt/custom/addons"
db_name = "odoo_dev"
db_user = "odoo"
```

Save that as `~/.config/oduit/dev.toml` and use it with:

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

## CLI Workflows

### Diagnostics and Version Detection

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

### Addon Intelligence

```bash
oduit --env dev list-addons
oduit --env dev print-manifest sale
oduit --env dev list-manifest-values category
oduit --env dev list-depends sale
oduit --env dev install-order sale,purchase
oduit --env dev explain-install-order sale
oduit --env dev impact-of-update sale
oduit --env dev docs addon sale --source-only
oduit --env dev docs addons --select-dir myaddons --output-dir ./docs-out
oduit --env dev docs dependency-graph --modules sale,purchase
```

### Generate addon-local architecture docs

```bash
oduit --env dev agent technical-evidence @addons/my_addon --allow-mutation --source-only
oduit --env dev agent technical-report @addons/my_addon --allow-mutation --source-only
oduit --env dev agent technical-doc-check @addons/my_addon --include-files
```

Use `technical-diff` to compare the report snapshot against current evidence.

### Operations

```bash
oduit --env dev install sale
oduit --env dev update sale
oduit --env dev test --test-tags /sale
oduit --env dev shell
```

### Runtime Inspection and Trusted Execution

```bash
oduit --env dev exec "env['res.partner']._table"
oduit --env dev inspect ref base.action_partner_form
oduit --env dev inspect model res.partner
oduit --env dev inspect field res.partner email --with-db
oduit --env dev db table res_partner
oduit --env dev performance table-scans
oduit --env dev manifest check sale
```

Prefer the first-class `inspect` / `db` / `performance` commands before
falling back to `exec`. `exec` and `inspect recordset` are trusted
arbitrary execution surfaces and keep rollback-by-default semantics unless
`--commit` is passed explicitly.

### Reusable operation sets

Create `.oduit/sets/base.toml`:

```toml
schema_version = 2
kind = "install"

[install]
addons = ["has_base", "has_helpdesk"]
without_demo = true
```

Inspect and apply it:

```bash
oduit set inspect base
oduit set apply base --allow-mutation --retry-missing 1
oduit set apply base --allow-mutation --one-by-one
oduit set list
```

For large install plans, `--retry-missing` first applies the set as a batch,
then checks the database and retries only addons that are still not installed.
For fragile plans, `--one-by-one` applies and verifies one addon at a time.
Both options imply `--verify-state` by default.

Snapshot installed addons from a database and turn them into an ordered set:

```bash
oduit list-installed-addons --save-set snapshot --set-kind install
oduit install-order --from-set snapshot --save-set snapshot_ordered
```

Save dependency and codependency lists as sets:

```bash
oduit list-depends has_helpdesk --save-set helpdesk_deps --set-kind install
oduit list-codepends has_base --save-set base_impact --set-kind update
```

Use `--overwrite` to replace an existing set. Use `--set-name` and
`--set-description` to add display metadata.

Sets are stored under `.oduit/sets/` for local projects or
`~/.config/oduit/sets/` for named environments.

### Agent Workflow

`oduit agent ...` is the primary automation surface for external coding
agents. For the full workflow and JSON contract, see
{doc}`agent_contract`.

```bash
oduit --env dev agent context
oduit --env dev agent inspect-addon my_partner
oduit --env dev agent addon-doc my_partner
oduit --env dev agent inspect-ref base.action_partner_form
oduit --env dev agent inspect-model res.partner
oduit --env dev agent inspect-field res.partner email --with-db
oduit --env dev agent db-table res_partner
oduit --env dev agent manifest-check sale
oduit --env dev agent get-model-fields res.partner --attributes string,type,required
oduit --env dev agent locate-model res.partner --module my_partner
oduit --env dev agent locate-field res.partner email3 --module my_partner
oduit --env dev agent list-addon-tests my_partner --model res.partner --field email3
oduit --env dev agent validate-addon-change my_partner --allow-mutation --install-if-needed --update --discover-tests
oduit --env dev agent test-summary --module my_partner --test-tags /my_partner
```

Use the explicit runtime DB flags in your config when you want stronger guards:
`write_protect_db` and `agent_write_protect_db` block runtime DB mutation,
while `needs_mutation_flag` and `agent_needs_mutation_flag` require
`--allow-mutation` for the matching caller.

## Python API

### High-level Operations

```python
from oduit import ConfigLoader, OdooOperations

loader = ConfigLoader()
config = loader.load_config("dev")
ops = OdooOperations(config, verbose=True)

result = ops.install_module("sale")
version = ops.get_odoo_version(suppress_output=True)
model = ops.inspect_model("res.partner")
field = ops.inspect_field("res.partner", "email", with_db=True)
addon_docs = ops.build_addon_documentation("sale", source_only=True)
```

### Addon Analysis

```python
from oduit import ConfigLoader, ModuleManager

loader = ConfigLoader()
config = loader.load_config("dev")
manager = ModuleManager(config["addons_path"])

addons = manager.find_modules()
install_order = manager.get_install_order("sale", "purchase")
```

### Safe Read-Only Queries

```python
from oduit import OdooQuery

query = OdooQuery(config)
partners = query.query_model(
    "res.partner",
    domain=[("customer_rank", ">", 0)],
    fields=["name", "email"],
    limit=5,
)
```

### First-Class Runtime Inspection

```python
from oduit import OdooInspector

inspector = OdooInspector(config)
xmlid = inspector.inspect_ref("base.action_partner_form")
model = inspector.inspect_model("res.partner")
table = inspector.describe_table("res_partner")
```

### Raw Trusted Code Execution

```python
from oduit import OdooCodeExecutor
from oduit.config_provider import ConfigProvider

executor = OdooCodeExecutor(ConfigProvider(config))
result = executor.execute_code(
    "env['res.partner'].search_count([])",
    allow_unsafe=True,
)
```

## Next Steps

- Read {doc}`configuration` for config details
- Read {doc}`cli` for command reference
- Read {doc}`api` for Python API reference