---
name: ogp-config-and-flags
description: >
  Catalog of every configuration axis in Open Garden Planner: QSettings keys
  (AppSettings), UI-state persistence (UiStateStore), environment variables
  (.env / OGP_GOOGLE_MAPS_KEY / QT_QPA_PLATFORM / PYTHONUTF8), project-file
  version + per-plan settings, hidden-feature toggles in code, tooling config
  (pyproject/ruff/mypy/pytest/pins/ogp.spec), and CI knobs. Load this when:
  adding or changing a setting or flag; wondering what a settings key does or
  what its default is; configuring environment variables or .env; touching the
  Preferences dialog; deciding whether a change needs a FILE_VERSION bump; or
  a feature seems mysteriously disabled (hidden panel, missing API key,
  default-off snap mode). Includes the "how to add a setting" checklist.
---

# OGP Configuration & Flags Catalog

**Verified 2026-07-03 against v1.23.0** by reading `settings.py`, `ui_state.py`,
`project.py`, `main.py`, `application.py`, `preferences_dialog.py`,
`pyproject.toml`, `installer/ogp.spec`, `ci.yml`, `release.yml`. Flags drift —
if the repo has moved on, re-verify with the commands at the bottom before
trusting a row.

**When NOT to use this skill:** build/run/test commands (`ogp-build-and-run`),
what a subsystem does (`ogp-architecture-contract`, `ogp-qt-cad-reference`,
`ogp-garden-domain-reference`), release/branch/PR process (`ogp-change-control`),
debugging technique (`ogp-debugging-playbook`, `debug-verbose`).

Jargon, defined once:
- **QSettings** — Qt's per-user persistent key/value store. This app constructs
  it as `QSettings("cofade", "Open Garden Planner")`, so it lives at:
  Windows registry `HKEY_CURRENT_USER/Software/cofade/Open Garden Planner`,
  macOS `~/Library/Preferences/com.cofade.Open Garden Planner.plist`,
  Linux `~/.config/cofade/Open Garden Planner.conf`.
- **App setting vs per-plan setting** — app settings (QSettings) follow the
  *user* across all plans; per-plan settings live inside the `.ogp` JSON file
  (`ProjectData`) and follow the *document*.
- **Additive `.ogp` key** — a new top-level key in the project JSON that old
  builds silently ignore on load. Additive keys do NOT bump `FILE_VERSION`.

---

## 1. AppSettings — QSettings catalog

Source: `src/open_garden_planner/app/settings.py` (all keys enumerated below —
the file has no others as of v1.23.0). Access via the singleton
`get_settings()`; each key has a typed property with the default baked in.
All rows **production** unless noted.

### General / startup

| Key | Property | Type | Default | Read by |
|---|---|---|---|---|
| `autosave/enabled` | `autosave_enabled` | bool | `True` | `services/autosave_service.py` |
| `autosave/interval_minutes` | `autosave_interval_minutes` | int | `5` (clamped 1–30 on both read and write) | `services/autosave_service.py` |
| `recent_files` | `recent_files` (+ `add_recent_file`, max 10) | list[str] | `[]` | File menu in `application.py` |
| `startup/show_welcome` | `show_welcome_on_startup` | bool | `True` | `welcome_dialog.py`, startup sequence |
| `updates/skipped_version` | `skipped_version` | str | `""` | update checker in `application.py` ("Skip this version") |

> `window/geometry` and `window/state` (`AppSettings.window_geometry` /
> `window_state`) were **removed in #285**: a never-called duplicate of what
> `UiStateStore` owns under `UiState/` (§2). Old real stores may still hold the
> orphaned keys; nothing reads them.

### Appearance & language

| Key | Property | Type | Default | Read by |
|---|---|---|---|---|
| `appearance/theme_mode` | `theme_mode` | `ThemeMode` (`light`/`dark`/`system`; invalid → SYSTEM) | `"system"` | `ui/theme.py` + every color consumer — **see trap below** |
| `appearance/language` | `language` | str | `"en"` | `core/i18n.py` |
| `appearance/show_shadows` | `show_shadows` | bool | `True` | canvas / View menu |
| `appearance/show_scale_bar` | `show_scale_bar` | bool | `True` | canvas / View menu |
| `appearance/show_labels` | `show_labels` | bool | `True` | canvas / View menu |
| `appearance/show_constraints` | `show_constraints` | bool | `True` | canvas / View menu |
| `appearance/show_spacing_circles` | `show_spacing_circles` | bool | `True` | `canvas_view.py`, spacing-ring paint gate |

> **TRAP (§11.4, verified in `docs/11-risks-and-technical-debt/README.md`):
> `ThemeColors.get_colors(ThemeMode.SYSTEM)` ignores the user's theme choice.**
> `apply_theme()` only writes a stylesheet and never mutates
> `QApplication.palette()`, so SYSTEM-mode detection probes the *OS* palette. A
> user who explicitly picked LIGHT on a dark-default OS gets the dark palette
> dict. Rule: only `theme.py` may call `get_colors(ThemeMode.SYSTEM)`; every
> other consumer must call `ThemeColors.get_colors(get_settings().theme_mode)`.

### Canvas snap & input (Phase 13 CAD packages)

| Key | Property | Default | Status / note |
|---|---|---|---|
| `canvas/object_snap_enabled` | `object_snap_enabled` | `True` | production |
| `canvas/midpoint_snap_enabled` | `midpoint_snap_enabled` | `True` | production (US-A3) |
| `canvas/intersection_snap_enabled` | `intersection_snap_enabled` | `True` | production (US-A3) |
| `canvas/nearest_snap_enabled` | `nearest_snap_enabled` | **`False`** | production, **deliberately default-OFF** (US-B4: fallback snap would surprise users relying on free placement near edges) |
| `canvas/perpendicular_snap_enabled` | `perpendicular_snap_enabled` | **`False`** | production, default-OFF opt-in precision aid (US-B5) |
| `canvas/tangent_snap_enabled` | `tangent_snap_enabled` | **`False`** | production, default-OFF opt-in precision aid (US-B6) |
| `canvas/dynamic_input_enabled` | `dynamic_input_enabled` | `True` | production (US-A4 cursor overlay + typed coordinates) |

All read by `ui/canvas/canvas_view.py` / the snap pipeline; toggled from the
View menu. If a snap "doesn't work", check nearest/perpendicular/tangent first —
they default OFF.

### Tool memory ("last used" values)

| Key | Property | Default | Read by |
|---|---|---|---|
| `tools/fillet_last_radius_cm` | `fillet_last_radius_cm` | `25.0` | `core/tools/fillet_tool.py` (prefills the dialog, US-B3) |
| `tools/chamfer_last_distance_cm` | `chamfer_last_distance_cm` | `25.0` | same |

### Weather & tasks

| Key | Property | Default | Read by |
|---|---|---|---|
| `weather/frost_warning_orange_c` | `frost_warning_orange_c` | `5.0` °C | frost alerting (US-12.2) |
| `weather/frost_warning_red_c` | `frost_warning_red_c` | `2.0` °C | frost alerting |
| `tasks/notify_overdue_on_startup` | `notify_overdue_tasks_on_startup` | `True` | startup `TaskReminderBar` (US-C2) |

### Agent API (embedded MCP server, US-D1.x)

| Key | Property | Default | Note |
|---|---|---|---|
| `agent_api/enabled` | `agent_api_enabled` | **`True`** | Default ON is a locked product decision (`tests/unit/test_agent_api_settings.py` asserts the class constants). Read-only tools, loopback-only. Comment in `settings.py`: token auth must land before D2 write tools default-expose mutate access. |
| `agent_api/port` | `agent_api_port` | `8765` | Clamped 1024–65535 on read and write. Server URL is `http://127.0.0.1:<port>/mcp`. |

Startup path (verified in `application.py`): `_setup_agent_api()` →
`QTimer.singleShot(1500, self._maybe_start_agent_api)` → starts only
`if get_settings().agent_api_enabled`. Preferences dialog restarts/stops the
server when either value changes (compares before/after tuple around the
dialog, ~line 3758).

### Plant-DB API keys (stored in QSettings, NOT .env)

| Key | Property | Default |
|---|---|---|
| `api_keys/trefle_token` | `trefle_api_token` | `""` |
| `api_keys/perenual_key` | `perenual_api_key` | `""` |
| `api_keys/permapeople_key_id` | `permapeople_key_id` | `""` |
| `api_keys/permapeople_key_secret` | `permapeople_key_secret` | `""` |

Entered in Preferences (with per-API "Test" buttons); consumed by the online
plant-search services. Contrast: the Google Maps key is env-only (§3) because
it must never ship in a binary.

---

## 2. UiStateStore — what UI state persists (and what deliberately does not)

Source: `src/open_garden_planner/app/ui_state.py`. Same QSettings backend as §1
— both take it from `app/settings.create_qsettings()`, the only store factory in
`src/` (#285, ADR-041; gated by `tests/unit/test_settings_chokepoint.py`, so do
not hand-roll a second one) — with keys under the `UiState/` group to avoid
colliding with §1. All production.

| Key | Saved / restored |
|---|---|
| `UiState/geometry` | `QMainWindow.saveGeometry()` |
| `UiState/window_state` | `QMainWindow.saveState()` (docks/toolbars) |
| `UiState/splitter_<name>` | per-named `QSplitter.saveState()` |

**Deliberately NOT persisted (ADR-030 / issue #226):** per-panel
collapse/expand/pin state. The sidebar accordion starts fully collapsed every
session; the old `save_panel_state`/`restore_panel_state` helpers were
**removed** (the module docstring says so explicitly). Do not re-add panel
persistence without revisiting ADR-030.

---

## 3. Environment variables & .env

| Variable | Status | Purpose | What breaks without it |
|---|---|---|---|
| `OGP_GOOGLE_MAPS_KEY` | production, **user-supplied, never bundled** | Google Maps satellite background picker (ADR-019, docs/08 §8.15) | The "load satellite background" menu action is disabled with a tooltip telling you to set it (`application.py` ~line 379); `GoogleMapsKeyMissingError` if reached anyway. Deliberately env-only: bundling the key in the installer would let it be reverse-engineered and abused (`services/google_maps_service.py` docstring). |
| `QT_QPA_PLATFORM=offscreen` | production (test infra) | Headless Qt rendering | Set by `tests/conftest.py` via `os.environ.setdefault(...)` (line 11) AND by `ci.yml`'s test job env. Without it, tests need a display server. |
| `PYTHONUTF8=1` | production (script infra) | Forces UTF-8 I/O for `scripts/fill_translations.py` / `compile_translations.py` (German umlauts) | Mojibake / encode errors on Windows. Per CLAUDE.md, always run translation scripts with it. |

**.env loading (verified in `main.py` lines 14–27):** `python-dotenv`'s
`load_dotenv()` on the first existing candidate of, in order:
1. **frozen** (PyInstaller): `.env` next to the `.exe` (`sys.executable`'s dir —
   the source-relative lookup misses because `__file__` sits in `_internal/`);
2. **dev**: repo-root `.env` (three parents up from `main.py`).

First hit wins; loading happens at module import, before `QApplication`.

---

## 4. Project-file (.ogp) configuration axes

Source: `src/open_garden_planner/core/project.py`.

### FILE_VERSION

- Current: **`FILE_VERSION = "1.4"`** (line 34). 1.4 = Phase 13 Package B's
  `bezier` and `arc` item types; v1.3 files load transparently.
- **What bumps it:** only changes an older app could *misread* — new item
  types, changed geometry semantics. **What does NOT bump it:** additive
  top-level keys old builds ignore (`harvest_logs`, `task_states`,
  `manual_tasks`, `garden_journal_notes`, container/smart-symbol `metadata`,
  …). This additive-key convention is used by every Package C feature.
- **`paper_layouts` (deprecated):** written only by short-lived US-B7 draft
  builds; `from_dict` intentionally never consumes it (comment at line ~210),
  so those files still open.
- **Forward-compat rejection** (verified, `ProjectManager.load` ~line 962):
  `_is_newer_file_version(file_version, FILE_VERSION)` parses `X.Y`; strictly
  newer files raise `ValueError` ("created by a newer version… please update")
  instead of silently dropping unknown content on the next save. Unparseable
  or missing version strings are treated as *old* (returns `False`), so legacy
  files (e.g. "1.0" or no key) still load.

### Per-plan settings (live in the file, not QSettings)

`ProjectData` fields beyond geometry (`canvas_width/height`, `objects`,
`layers`, `constraints`, `guides`): `location` (geo metadata incl. the
satellite-picker scale/coords), `season_year` + `linked_seasons`,
`task_completions` (write-only compat mirror since #230 — read `task_states`),
`seed_inventory`, `propagation_overrides`, `crop_rotation`, `soil_tests`,
`pest_disease_logs`, `shopping_list_prices`, `excluded_shopping_items`,
`enabled_amendments` (`None` = "all bundled amendments enabled" default) +
`prefer_organic` (default `True`), `succession_plans`,
`garden_journal_notes`, `manual_tasks`, `task_states`, `harvest_logs`.

Rule of thumb: user preference about the *app* → §1 QSettings; data or
preference about *this garden* → `ProjectData`.

---

## 5. Feature-visibility toggles in code (the "experimental flag" pattern)

This repo has no feature-flag framework; experiments ship dark via one-line
visibility calls.

| Toggle | Where | Status |
|---|---|---|
| **Smart Symbols sidebar panel hidden** | `application.py` line ~1574: `self._sidebar_controller.set_panel_visible("smart_symbols", False)` | **experimental / deferred UI** (US-C4). Engine, persistence, DXF export, and properties editing all ship and are tested; symbols in existing `.ogp` files still regenerate. Re-enable by deleting that one line (the comment says exactly this). |
| Contextual panels hidden until relevant selection | `set_panel_visible(key, relevant)` for `plant_details` / `companion` / `crop_rotation` in the selection updaters (ADR-030) | production behavior — not a bug when they're absent with nothing selected |
| Satellite menu action disabled | `application.py` ~line 379 when `OGP_GOOGLE_MAPS_KEY` unset (§3) | production guard |
| Nearest / perpendicular / tangent snap default-OFF | §1 snap table | production, opt-in |

If "a feature seems disabled", check this table before debugging.

---

## 6. Tooling configuration

### pyproject.toml (verified in full)

| Section | Contents |
|---|---|
| `[tool.ruff]` | `target-version = "py311"`, `line-length = 100`, `src = ["src", "tests"]` |
| `[tool.ruff.lint]` | select `E, W, F, I, B, C4, UP, ARG, SIM`; ignore `E501`, `B008` |
| per-file ignores | `tests/**/*.py` → `ARG001, ARG002` (unused-but-required `qtbot` fixtures) |
| `[tool.mypy]` | `strict = true` (+ the usual disallow/warn set), `follow_imports = "silent"`, `ignore_missing_imports = true`; `tests.*` override relaxes `disallow_untyped_defs` |
| `[tool.pytest.ini_options]` | `testpaths = ["tests"]`, `addopts = "-v --tb=short"`, `qt_api = "pyqt6"` |
| `[tool.coverage]` | `source = src/open_garden_planner`, `branch = true`, standard exclude lines |

### Dependency pins worth knowing (pyproject `dependencies`)

| Pin | Rationale (from the in-file comment, verified) |
|---|---|
| `PyQt6-WebEngine>=6.10.0,<6.11` | upper-bound pin (needed by the map picker's `QWebEngineView`; must be imported before `QApplication` — `main.py`) |
| `mcp>=1.12,<2.0` | "Pinned to mcp v1 — v2 renames `FastMCP` -> `MCPServer`." uvicorn/starlette/pydantic/anyio/sse-starlette come transitively but are listed where used. |
| `uvicorn>=0.30`, `starlette>=0.37`, `pydantic>=2.11` | Agent API server stack |

**Deprecated:** the top-level `requirements.txt` lists only `PyQt6` + `Pillow`
— it is stale; `pyproject.toml` is the dependency source of truth.

### installer/ogp.spec knobs (verified; see docs/07 + §8.19 for narrative)

- `_safe_collect_submodules` over **concrete** MCP subpackages
  (`mcp.server`/`mcp.shared`/`mcp.types`, uvicorn, starlette, anyio,
  sse_starlette, pydantic, pydantic_settings, httpx_sse) — **never top-level
  `mcp`**: walking it imports `mcp.cli`, which `sys.exit(1)`s without the
  unbundled `typer` extra and aborts the build.
- `copy_metadata` for the same stack (they read distribution metadata at
  import time in the frozen exe).
- `excludes` = tkinter/unittest/pydoc/doctest — with an explicit NOTE: **do NOT
  exclude `multiprocessing`** (uvicorn imports it eagerly; excluding it breaks
  the embedded Agent API).
- `upx_exclude = ["pydantic_core*.pyd"]` — UPX can corrupt that compiled
  extension.
- `console=False`; data trees copied: icons, textures, plants, objects,
  translations, data, web (map-picker HTML).

---

## 7. CI axes

### ci.yml (verified)

Three jobs on every branch push + PRs to master, all Python 3.11,
ubuntu-latest: **lint** (`ruff check src/`), **test** (apt Qt libs, then
`pytest tests/ -v` with env `QT_QPA_PLATFORM: offscreen`), **security**
(`bandit -r src/ --severity-level high`). No other env vars or secrets.

### release.yml (verified) — details in `ogp-change-control`

- Triggers on push to master; **chore-skip predicate**:
  `!startsWith(message, 'chore:') && !startsWith(message, 'chore(')` — the
  scoped form was added after `chore(finalize-us):` slipped through and
  wrongly cut a release.
- Version bump from the **labels of the most recently merged master PR**:
  label `major` → X+1.0.0, `minor` → Y+1, else **patch** (default). Skips
  cleanly if the computed tag already exists.
- Builds on windows-latest via `installer/build_installer.py`, NSIS installer +
  SHA256SUMS, `gh release create --generate-notes`. Never tag manually.

---

## 8. How to add a setting — checklist

Derived from `agent_api_enabled` (US-D1.1), whose every step verifiably exists;
copy that pattern.

1. **`settings.py`**: add `KEY_<NAME> = "group/key_name"` constant + a
   `DEFAULT_<NAME>` class constant (+ `MIN_/MAX_` if clamped) + a typed
   `@property`/setter pair reading `self._settings.value(KEY, DEFAULT,
   type=...)`. Clamp in **both** getter and setter if bounded (see
   `agent_api_port`, `autosave_interval_minutes`).
2. **Preferences UI** (`ui/dialogs/preferences_dialog.py`): add the widget in
   the right group box; **load** current value in the populate block (~line
   270), **save** in `_save_and_accept()` (ending with `settings.sync()`).
   Reference class constants for ranges (`AppSettings.MIN_AGENT_API_PORT`).
3. **i18n**: wrap every label/tooltip in `self.tr(...)` — no exceptions
   (CLAUDE.md MUST).
4. **Register the strings** in `scripts/fill_translations.py` (the Agent API
   entries sit at ~lines 1875 and 2300), then run
   `PYTHONUTF8=1 venv/Scripts/python.exe scripts/fill_translations.py` and
   `compile_translations.py`;
   `pytest tests/unit/test_i18n.py::TestTranslationFiles::test_german_ts_has_no_unfinished`
   must pass.
5. **Wire the consumer**: react to the changed value where it takes effect. If
   it needs apply-on-OK, compare before/after around the dialog like
   `application.py` does for the Agent API (~line 3758) and restart/refresh
   the affected service.
6. **Tests**: lock the default with a unit test if it's a product decision
   (`tests/unit/test_agent_api_settings.py` asserts the class constants —
   note its rationale: autouse fixtures may override the runtime value, so
   assert the *constant*); add/extend an integration test for the behavior
   (`tests/integration/test_agent_api_default_on.py`).
7. **Docs**: FR entry if user-facing (`docs/functional-requirements.md`), ADR
   if it's a decision, §11.4 if you hit a pitfall — and **update this skill's
   §1 table**.
8. Follow `ogp-change-control` for branch/review/draft-PR gates.

Deciding where it lives: user-scoped app behavior → QSettings (this checklist);
plan-scoped → `ProjectData` field + `to_dict`/`from_dict` (additive key, no
FILE_VERSION bump — §4); pure UI geometry → `UiStateStore` (§2, but never panel
open-state, ADR-030).

---

## Provenance and maintenance

Re-verify each section before relying on it after significant time/version drift:

| Section | Command |
|---|---|
| §1 keys & defaults | `grep -n "KEY_\|DEFAULT_\|MIN_\|MAX_" src/open_garden_planner/app/settings.py` |
| §1 QSettings location | `grep -n "QSettings(" src/open_garden_planner/app/settings.py src/open_garden_planner/app/ui_state.py` |
| §1 theme trap | `grep -n "get_colors(ThemeMode.SYSTEM)" -r src/ docs/11-risks-and-technical-debt/` |
| §2 UiState keys | `grep -n "UiState\|setValue\|save_panel" src/open_garden_planner/app/ui_state.py` |
| §3 env loading | `sed -n '14,28p' src/open_garden_planner/main.py; grep -rn "OGP_GOOGLE_MAPS_KEY\|QT_QPA_PLATFORM" src/ tests/conftest.py .github/workflows/ci.yml` |
| §4 FILE_VERSION | `grep -n "FILE_VERSION\|_is_newer_file_version\|paper_layouts" src/open_garden_planner/core/project.py` |
| §5 hidden panel | `grep -n 'set_panel_visible("smart_symbols"' src/open_garden_planner/app/application.py` |
| §6 tooling | `grep -n "tool.ruff\|tool.mypy\|tool.pytest\|mcp>=\|WebEngine" pyproject.toml; grep -n "multiprocessing\|mcp.cli\|upx_exclude" installer/ogp.spec` |
| §7 CI | `grep -n "chore\|major\|minor\|QT_QPA_PLATFORM" .github/workflows/release.yml .github/workflows/ci.yml` |
| §8 exemplar | `grep -n "agent_api" src/open_garden_planner/ui/dialogs/preferences_dialog.py src/open_garden_planner/app/application.py` |