gOdoo-cli 1.0.2__tar.gz → 1.0.4__tar.gz

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/.agents/skills/godoo-editor-validation/SKILL.md

@@ -8,10 +8,9 @@ description:
 
 Read `docs/workspace.md`, then open the generated `<project>.code-workspace`.
 
-gOdoo sets `python.languageServer` to `None` so the installed Odoo IDE extension provides Python and Odoo analysis
-without a competing Pylance server. Keep the Python extension for interpreter selection and debugging. The generated
-`python.analysis.extraPaths` covers the resolved project, Odoo, third-party, and archive addon roots. The supported
-source mapping is the generated multi-root workspace plus its generated extra paths.
+Keep the Python extension for interpreter selection and debugging. The generated `python.analysis.extraPaths` covers the
+resolved project, Odoo, third-party, and archive addon roots. The supported source mapping is the generated multi-root
+workspace plus its generated extra paths.
 
 Reload the window after generation, save representative project, Odoo, and addon files, then inspect VS Code Problems.
 Confirm each diagnostic refers to the intended selected host worktree. Problems validate editor analysis, not execution.

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/.agents/skills/godoo-runtime-validation/SKILL.md

@@ -28,9 +28,9 @@ environment options, source paths, lifecycle hooks, or generated proxy configura
 upstream; downstream owns images, Compose, mounts, runtime users, service ordering, and project hooks. Check whether the
 downstream pin includes the required fix before proposing another implementation.
 
-`runtime init` owns restore, bootstrap, and reconciliation as a one-shot job. `runtime launch` only starts prepared
-state. Keep `init` ahead of `app` with `service_completed_successfully`. gOdoo provides no downstream service
-orchestration.
+`runtime start` initializes and reconciles explicitly before launching the same target on every app process start. Keep
+maintenance `runtime init` out of ordinary startup; the app depends on a healthy database. `runtime launch` starts
+prepared state only. gOdoo provides no downstream service orchestration.
 
 Use the downstream Make/Compose path for authorized runtime validation. Reuse host-resolved workspace paths rather than
 assembling a substitute container with guessed addon mounts. A pin change needs a rebuilt artifact and, when live

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/.env.sample

@@ -32,3 +32,7 @@ ODOO_DB_PORT=5432
 # ODOO_RPC_USER=admin
 # ODOO_RPC_PASSWORD=admin
 # ODOO_RPC_DB_NAME=odoo
+
+# runtime start reconciles before every server process start, including Docker restart.
+# The first source-baseline run deliberately updates installed source-backed modules.
+GODOO_UPDATE_CHANGED=true

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/.vscode/settings.json

@@ -2,7 +2,7 @@
   "python.testing.unittestEnabled": false,
   "python.testing.pytestEnabled": false,
   "xml.symbols.enabled": false,
-  "python.languageServer": "Pylance",
+  "python.languageServer": "None",
   "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
   "ruff.path": ["${workspaceFolder}/.venv/bin/ruff"],
   "ruff.configurationPreference": "filesystemFirst",

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/AGENTS.md

@@ -14,6 +14,24 @@ coherent change.
   whole-changeset reviews.
 - Keep shared Docker validation sequential.
 
+## Branches and releases
+
+- Start each independent change on a short-lived `codex/<topic>` branch from freshly fetched `origin/main`. Do not reuse
+  a merged branch for new work. Keep implementation, tests, and documentation for one behavior together.
+- Before switching or creating a branch, inspect staged, unstaged, and untracked work. Preserve existing changes and
+  verify the resulting diff against `origin/main`; use a separate Git worktree for concurrent independent work.
+- Open topic PRs into `main` and check Quality results before merging. Topic-branch pushes alone do not trigger Quality.
+  Follow the existing merge strategy and commit conventions. Push and merge only within explicit authorization.
+- After merge, return to an updated `main` or start the next topic branch from current `origin/main`. Prune stale remote
+  references and remove merged branches only after checking ancestry and worktree ownership; preserve unfinished work.
+- Leave package version changes to `.github/workflows/version-bump.yml`, dispatched against `main` with the chosen bump
+  type. It creates `release/<version>` and the release PR; keep that PR limited to preparing the release.
+- Review the release PR description and available Quality results before merging: its description becomes the release
+  notes. The release-labeled PR must target `main` and match the title, branch, and version identities documented in
+  `.github/workflows/README.md`. Publication uses the release merge commit for PyPI, the tag, and the GitHub Release.
+- Keep release PRs short-lived and coordinate other merges to preserve the intended release scope. Do not use a
+  long-lived `release` or `develop` branch for this workflow, or move an existing release tag to repair publication.
+
 ## Code and CLI
 
 - Every shell script under `scripts/` has a purpose comment immediately below its shebang.

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gOdoo-cli
-Version: 1.0.2
+Version: 1.0.4
 Summary: Odoo lifecycle, Python dependency preflight, and shared Git workspaces.
 Project-URL: repository, https://github.com/OpenJKSoftware/gOdoo
 Author-email: Joshua Kreuder <Joshua_Kreuder@outlook.com>
@@ -10,6 +10,7 @@ Keywords: docker,godoo,odoo,worktree
 Requires-Python: >=3.11
 Requires-Dist: gitpython>=3.1.27
 Requires-Dist: godoo-rpc>=0.1.4
+Requires-Dist: json-with-comments>=1.3.0
 Requires-Dist: packaging>=21.0
 Requires-Dist: passlib>=1.7.3
 Requires-Dist: psycopg2-binary>=2.7.7; sys_platform != 'linux'
@@ -144,19 +145,20 @@ in the Python environment that contains Odoo; gOdoo uses `VIRTUAL_ENV`, otherwis
 Commands read the project `.env`. **Explicit CLI values → exported environment → project `.env`** is the configuration
 precedence. Use `godoo --help` or `godoo <command> --help` for the full reference.
 
-### Prepare once, then launch
+### Prepare on every server start
 
 Initialization prepares the database and matching filestore, checks dependencies, and runs selected module updates and
-hooks. Launch starts the prepared runtime. In Compose, the app should depend on the init service completing
-successfully.
+hooks. `runtime start` performs this work before launching Odoo on the same target. Use it as the app entrypoint so
+Docker restarts also prepare the runtime; the app depends on a healthy database.
 
 ```bash
 # Run in a configured runtime environment with other Odoo writers stopped.
-godoo runtime init && godoo runtime launch
+godoo runtime start --update-changed
 ```
 
-Use `godoo runtime init --if-needed` for startup that skips reconciliation when the runtime is already ready. For
-deployments applying module updates or hooks, use explicit initialization. Inspect state without changing it:
+`--update-changed` selects native upgrades from source hashes; unchanged starts skip upgrades. Explicit maintenance
+`runtime init` and prepared-only `runtime launch` remain available. `runtime init --if-needed` skips all hooks and
+reconciliation on a ready runtime; `runtime start` always initializes explicitly. Inspect state without changing it:
 
 ```bash
 godoo runtime status --json

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/README.md

@@ -109,19 +109,20 @@ in the Python environment that contains Odoo; gOdoo uses `VIRTUAL_ENV`, otherwis
 Commands read the project `.env`. **Explicit CLI values → exported environment → project `.env`** is the configuration
 precedence. Use `godoo --help` or `godoo <command> --help` for the full reference.
 
-### Prepare once, then launch
+### Prepare on every server start
 
 Initialization prepares the database and matching filestore, checks dependencies, and runs selected module updates and
-hooks. Launch starts the prepared runtime. In Compose, the app should depend on the init service completing
-successfully.
+hooks. `runtime start` performs this work before launching Odoo on the same target. Use it as the app entrypoint so
+Docker restarts also prepare the runtime; the app depends on a healthy database.
 
 ```bash
 # Run in a configured runtime environment with other Odoo writers stopped.
-godoo runtime init && godoo runtime launch
+godoo runtime start --update-changed
 ```
 
-Use `godoo runtime init --if-needed` for startup that skips reconciliation when the runtime is already ready. For
-deployments applying module updates or hooks, use explicit initialization. Inspect state without changing it:
+`--update-changed` selects native upgrades from source hashes; unchanged starts skip upgrades. Explicit maintenance
+`runtime init` and prepared-only `runtime launch` remain available. `runtime init --if-needed` skips all hooks and
+reconciliation on a ready runtime; `runtime start` always initializes explicitly. Inspect state without changing it:
 
 ```bash
 godoo runtime status --json

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/docker/Dockerfile

@@ -48,7 +48,7 @@ RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
     && chown -R odoo:odoo "$VIRTUAL_ENV"
 WORKDIR /odoo/godoo_workspace
 USER odoo
-CMD ["python", "-m", "godoo_cli", "runtime", "launch"]
+CMD ["python", "-m", "godoo_cli", "runtime", "start"]
 
 # Materialize selected sources from read-only mounts without Git commands or worktree scans.
 FROM dependencies AS materialized
@@ -86,4 +86,4 @@ RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
 COPY --from=materialized --chown=odoo:odoo /image/odoo/ /odoo/
 WORKDIR /odoo/godoo_workspace
 USER odoo
-CMD ["godoo", "runtime", "launch"]
+CMD ["godoo", "runtime", "start"]

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/docker/docker-compose.base.yml

@@ -23,6 +23,9 @@ x-runtime: &runtime
     ODOO_WORKSPACE_ADDON_LOCATION: ${ODOO_WORKSPACE_ADDON_LOCATION:-/odoo/godoo_workspace/addons}
     ODOO_CONF_PATH: ${ODOO_CONF_PATH:-/odoo/config/odoo.conf}
     GODOO_RUNTIME_SEED: "${GODOO_RUNTIME_SEED:-}"
+    GODOO_UPDATE_CHANGED: ${GODOO_UPDATE_CHANGED:-true}
+    GODOO_RECONCILE_UPDATE: "${GODOO_RECONCILE_UPDATE:-}"
+    GODOO_RECONCILE_INSTALL: "${GODOO_RECONCILE_INSTALL:-}"
     GODOO_X_SENDFILE: ${GODOO_X_SENDFILE:-true}
     GODOO_HOOK_DIRS: "${GODOO_HOOK_DIRS:-}"
     GODOO_ENVIRONMENT: "${GODOO_ENVIRONMENT:-}"
@@ -37,16 +40,17 @@ x-runtime: &runtime
 services:
   init:
     <<: *runtime
+    profiles: [maintenance]
     command: [godoo, runtime, init]
     depends_on:
       db:
         condition: service_healthy
   app:
     <<: *runtime
-    command: [godoo, runtime, launch, "--extra-args=${ODOO_BIN_ARGS:+${ODOO_BIN_ARGS} }--proxy-mode"]
+    command: [godoo, runtime, start, "--extra-args=${ODOO_BIN_ARGS:+${ODOO_BIN_ARGS} }--proxy-mode"]
     depends_on:
-      init:
-        condition: service_completed_successfully
+      db:
+        condition: service_healthy
   nginx:
     build:
       context: ..

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/docker/docker-compose.dev.yml

@@ -28,7 +28,7 @@ services:
         -m,
         godoo_cli,
         runtime,
-        launch,
+        start,
         "--extra-args=${ODOO_BIN_ARGS:+${ODOO_BIN_ARGS} }--workers=0 --proxy-mode",
       ]
     volumes:
@@ -39,6 +39,7 @@ services:
       GODOO_RUNTIME_ODOO_PATH: ${GODOO_RUNTIME_ODOO_PATH}
       GODOO_RUNTIME_ADDON_PATHS: ${GODOO_RUNTIME_ADDON_PATHS}
       GODOO_DEV_MODE: "1"
+      GODOO_KEEP_RESET_BASELINE: ${GODOO_KEEP_RESET_BASELINE:-true}
       ODOO_MANIFEST: /odoo/godoo_workspace/odoo_manifest.yml
       PYTHONPATH: /odoo/godoo_workspace/src
 

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/docs/downstream.md

@@ -8,16 +8,15 @@ database topology is a same-host PostgreSQL sidecar on an isolated Compose netwo
 
 ## Service and ownership boundaries
 
-This diagram shows **Compose startup dependencies**, not HTTP traffic. A failed database healthcheck or init job
-prevents the dependent app from starting. “App service started” is a Compose state, not proof of HTTP readiness. The
-[HTTP and file delivery](#http-and-file-delivery) section describes request routing.
+This diagram shows **Compose startup dependencies**, not HTTP traffic. A failed database healthcheck prevents app
+startup; failed preparation makes the app exit before it serves. “App service started” is a Compose state, not proof of
+HTTP readiness. The [HTTP and file delivery](#http-and-file-delivery) section describes request routing.
 
 ```mermaid
 flowchart TD
     Compose["Operator runs downstream Docker Compose"]
     Compose --> DB["Compose starts db<br/>and waits for PostgreSQL's healthcheck"]
-    DB -->|database healthy| Init["Compose runs init<br/>godoo runtime init prepares the database and filestore"]
-    Init -->|init exits with code 0| App["Compose starts app<br/>godoo runtime launch starts Odoo"]
+    DB -->|database healthy| App["Compose starts app<br/>godoo runtime start prepares, then serves"]
     App -->|app service started| Nginx["Compose starts nginx<br/>HTTP ingress becomes available"]
 ```
 
@@ -61,22 +60,32 @@ healthcheck from [the base Compose file](../docker/docker-compose.base.yml).
 
 ```yaml
 services:
-  init:
-    command: [godoo, runtime, init] # One-shot preparation, not a daemon.
+  app:
+    command: [godoo, runtime, start]
+    environment:
+      GODOO_UPDATE_CHANGED: "true"
     depends_on:
       db:
         condition: service_healthy
 
-  app:
-    command: [godoo, runtime, launch] # Launch only prepared state.
+  init:
+    profiles: [maintenance]
+    command: [godoo, runtime, init] # Explicit maintenance, excluded from ordinary startup.
     depends_on:
-      init:
-        condition: service_completed_successfully
+      db:
+        condition: service_healthy
 ```
 
-Use `GODOO_INIT_IF_EMPTY=true` for startup that skips a ready runtime. Keep it false, or pass `--no-if-needed`, for
-deployment jobs that reconcile modules and hooks. Demo mode ignores configured restore inputs and rejects an explicit
-seed. All processes managing the pair must share the same data directory.
+The app owns initialization on every process start, including Docker restarts. Give it all restore dataset mounts and
+settings previously provided to init; seed datasets should be read-only. Stop existing Odoo writers before deployment or
+maintenance initialization. The supported scope is one app service, not concurrent replicas writing the same runtime.
+Use routed HTTP readiness after app startup; a running or restarting container does not prove initialization succeeded.
+
+`runtime start` always reconciles and ignores `GODOO_INIT_IF_EMPTY`. That variable still controls standalone
+`runtime init`. Demo mode ignores configured datasets and rejects an explicit seed. All pair operations share the same
+data directory. For maintenance, `docker compose run --rm init` explicitly selects the profiled service. Do not also
+start it through an ordinary deployment service list. Use `runtime launch` only when preparation is deliberately owned
+by a separate caller.
 
 ## PostgreSQL
 

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/docs/hooks.md

@@ -18,7 +18,7 @@ Ordinary restores and major upgrades share the same initialization flow.
 
 Native migration versions must be above the installed version and at or below the manifest version. Fresh installs need
 their own install behavior. There is no transition directory, version-pair selector, implicit module list, or hook
-completion ledger.
+implicit migration scheduler. Ordinary database hooks can opt into transactional one-shot completion with `once=True`.
 
 ## Discover and select hooks
 
@@ -49,6 +49,7 @@ actual boolean. A missing predicate runs whenever eligible; an exception fails i
 | `phase`        | `prepare`, `after_bootstrap`, `after_restore`, or `after_reconcile`.                                                             |
 | `on`           | Tuple of `ready`, `bootstrapped`, and/or `restored`; defaults to all. Custom outcome filters are invalid for preparation.        |
 | `environments` | Optional tuple of exact `GODOO_ENVIRONMENT` values. Omitted means unrestricted; an allowlist never matches an unset environment. |
+| `once`         | Optional boolean, default false. Record successful database-hook completion; preparation hooks cannot use it.                    |
 
 Environment is a deployment input, never inferred from database contents.
 
@@ -101,8 +102,9 @@ Database contexts expose `ctx.env`, `ctx.environment`, and the original `ctx.out
 lifecycle markers as an API, rebuild the registry, or perform immediate module installs/updates. Module loading belongs
 in native reconciliation.
 
-An eligible `after_restore` database hook conflicts with native pre-upgrade scripts because it would open the registry
-first. The combination is rejected before mutation. Put post-upgrade environment setup in `after_reconcile`.
+An eligible `after_restore` database hook conflicts with selected native pre-upgrade scripts because it would open the
+registry first. `--update-changed` requires database hooks to use `after_reconcile`; it rejects eligible `after_restore`
+and `after_bootstrap` declarations rather than changing their order. Put post-upgrade setup in `after_reconcile`.
 
 ## Execution and transaction boundaries
 
@@ -147,8 +149,20 @@ already satisfied, running, completed, or failed. Do not log passwords or comple
 
 ## Idempotence and recovery
 
-Hooks run **at least once**. There is no `once=True`, file-hash cache, or generic success ledger. `on=("restored",)`
-means eligible during restore initialization and its retries, rather than exactly one execution.
+Ordinary hooks run whenever eligible, subject to `needs_run`. `on=("restored",)` selects restore initialization and its
+retries; it is not a completion record.
+
+Use `Hook(id="project.repair.2026_10", phase="after_reconcile", once=True)` for a transactional one-shot repair. IDs are
+immutable: use a new ID for a new repair. The runner stores completion in `ir_config_parameter` under
+`godoo.hooks.once.<identity-hash>`, in the same transaction as the action. Unrestricted hooks complete globally in that
+database; environment-restricted hooks complete separately for each selected environment. Restores and baseline resets
+carry or rewind the records with the database. Declaration filters still apply, and duplicate IDs remain invalid.
+
+Completed hooks skip `needs_run`. A false predicate means the desired state is already satisfied and records completion
+atomically without running the action. An exception rolls back the action and its completion record. A later hook's
+failure preserves earlier committed repairs. Hooks that commit internally or change external systems still need their
+own idempotency: the runner cannot promise exactly-once external effects. Keep recurring environment policy repeatable,
+with state predicates, so ordinary drift is repaired after every controlled start.
 
 | Attempt                                        | Outcome visible to hooks                                                            |
 | ---------------------------------------------- | ----------------------------------------------------------------------------------- |

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/docs/lifecycle.md

@@ -8,6 +8,39 @@ hooks, then launch Odoo. Runtime commands require Odoo 16 or newer.
 Stop ordinary Odoo writers before initialization, restore, clone, or replacement. gOdoo locks coordinate gOdoo
 operations; they do not stop ordinary Odoo writes.
 
+## Back up a live runtime
+
+```bash
+# Default: one combined ZIP, including attachments.
+godoo db backup /backups/runtime.zip --db-name odoo
+
+# PostgreSQL custom format plus a separate filestore, copied with rsync.
+godoo db backup /backups/current --db-name odoo --format dump
+```
+
+`--format` accepts `zip` (default) or `dump`; `GODOO_BACKUP_FORMAT` supplies the environment default. Both formats
+capture the database first, then the filestore. The `dump` destination contains `odoo.dump` and
+`odoo_filestore/filestore/<database>/`, directly usable by `godoo runtime init --dump-path` or
+`godoo db restore <directory> --force`. It requires `pg_dump` and `rsync` in the execution environment. The destination
+must be outside Odoo's data directory. Borg or another backup system owns history; each successful run replaces the
+selected destination.
+
+During capture, gOdoo holds a row lock on `base.autovacuum_job`. Odoo's scheduler skips that internal cleanup job;
+users, attachment writes, integrations, and other background jobs continue. No app restart or attachment-table write
+lock is needed. The lock is released on completion or connection closure. If cleanup is already running, backup fails
+immediately so it can be retried afterward. The backup fails if the guard connection is lost before publication.
+
+This protects standard Odoo filestore storage and scheduled cleanup on Odoo 16 and newer, including Odoo 19's manual
+scheduled-action trigger. Do not run private cleanup methods, custom file deletion, attachment storage migration, or
+Odoo 16–18 manual autovacuum during backup. External attachment backends need their own backup procedure. Files added
+after the database snapshot may also be copied; they are harmless extra files, not additional database records.
+
+Backups are staged before replacing the previous result. Directory destinations must be dedicated child directories
+inside a mounted backup volume, not the mount root itself. Replacing a directory briefly renames the previous pair to
+`.<destination-name>.previous`; failed promotion restores it. After an abrupt termination, inspect that directory and
+the destination before retrying. gOdoo refuses to overwrite a retained previous pair. Start Borg only after this command
+succeeds, and keep other backup readers out of the brief directory promotion window.
+
 ## Initialize and launch
 
 Run in the configured downstream runtime environment. CLI values override exported environment values, then the project
@@ -16,44 +49,79 @@ Run in the configured downstream runtime environment. CLI values override export
 ```bash
 # Prepare and reconcile explicitly, including on an already ready database.
 # Other Odoo writers must be stopped.
-godoo runtime init && godoo runtime launch
+godoo runtime start --update-changed
 
-# For ordinary startup, skip initialization when the runtime is already ready.
+# Optional maintenance policy: skip all hooks and reconciliation on a ready runtime.
 godoo runtime init --if-needed && godoo runtime launch
 
 # Inspect state without changing the runtime.
 godoo runtime status --json
 ```
 
-These are alternative startup policies. Set `GODOO_INIT_IF_EMPTY=true` for conditional startup; use `--no-if-needed` to
-override it for deployment jobs that must apply updates or hooks. Conditional init prints the same JSON payload as
+`runtime start` uses the existing init and launch options, resolves one target, and always initializes explicitly before
+serving. It ignores `GODOO_INIT_IF_EMPTY` and has no `--if-needed` option. Bootstrap arguments apply only to
+initialization; server/debugger arguments apply only to launch. Failed initialization returns nonzero without launching,
+and lifecycle locks are released before the server lifetime.
+
+For separate maintenance commands, set `GODOO_INIT_IF_EMPTY=true` for conditional init; use `--no-if-needed` to override
+it for deployment jobs that must apply updates or hooks. Conditional init prints the same JSON payload as
 `runtime status --json` and checks readiness before loading datasets, hooks, or Odoo.
 
 The diagram below starts when initialization is required or explicitly requested. A ready runtime skipped by
 `--if-needed` exits before this work. Each arrow means the preceding step succeeded; failures stop initialization.
-Launching the server is a separate caller action. The bootstrap/restore branches show first initialization; recovery
-retries rerun hooks for the original outcome, as described under
+`runtime start` launches after this work succeeds; `runtime init` exits without serving. The bootstrap/restore branches
+show first initialization; recovery retries rerun hooks for the original outcome, as described under
 [incomplete initialization](#incomplete-initialization).
 
 ```mermaid
 flowchart TD
-    Prepare["gOdoo: run prepare hooks<br/>and check known dependencies"] --> State{"State of the target<br/>database and filestore?"}
-    State -->|ready| Reconcile["Odoo: install or update selected modules<br/>and run eligible native migrations"]
-    State -->|missing or empty| Seed{"Backup or dataset<br/>selected for restore?"}
-    State -->|inconsistent| Stop["Stop initialization<br/>Operator must recover a matching database and filestore"]
-    Seed -->|yes| Restore["gOdoo: restore the selected backup<br/>and its matching attachments"]
-    Seed -->|no| Bootstrap["Odoo: create a new database"]
-    Restore --> Restored["gOdoo: run eligible after_restore hooks"]
-    Bootstrap --> Bootstrapped["gOdoo: run eligible after_bootstrap hooks"]
-    Restored --> Reconcile
-    Bootstrapped --> Reconcile
-    Reconcile --> Finalize["gOdoo: run eligible after_reconcile hooks"]
-    Finalize --> Ready["gOdoo: mark initialization complete<br/>and exit successfully"]
-    Ready -->|caller runs a separate command| Launch["godoo runtime launch<br/>Start the prepared Odoo server"]
+    Prepare["Prepare hooks and dependency preflight"] --> State{"Database and filestore state"}
+    State -->|ready| Plan["Registry-free source selection when enabled"]
+    State -->|missing or empty| Seed{"Seed selected?"}
+    State -->|inconsistent| Stop["Stop; recover a matching pair"]
+    Seed -->|yes| Restore["Restore backup and matching attachments"]
+    Seed -->|no| Bootstrap["Native Odoo bootstrap"]
+    Restore --> Plan
+    Bootstrap --> Plan
+    Plan --> OutcomeHooks["Eligible after_restore / after_bootstrap hooks<br/>Legacy ordering; excluded with update-changed"]
+    OutcomeHooks --> Reconcile["Native module reconciliation"]
+    Reconcile --> Baseline["Verify and save the planned source baseline when enabled"]
+    Baseline --> Finalize["Eligible after_reconcile hooks"]
+    Finalize --> Ready["Clear pending lifecycle state"]
+    Ready --> Launch["runtime start launches Odoo<br/>runtime init exits"]
 ```
 
-Init is a one-shot job. In Compose, launch depends on init's `service_completed_successfully`; gOdoo does not start
-downstream services itself.
+Use `runtime start` as the app entrypoint so Docker restarts also prepare the runtime. Keep `runtime init` as explicit
+maintenance tooling; do not also run a second init service during ordinary startup. gOdoo does not start downstream
+services itself.
+
+### Source-driven native reconciliation
+
+`--update-changed` or `GODOO_UPDATE_CHANGED=true` selects source changes without loading an Odoo registry. Under the
+runtime lock, after restore/bootstrap and before database hooks, gOdoo reads installed and pending module state and
+compares source snapshots. A missing baseline deliberately upgrades installed source-backed modules once. Later
+unchanged starts request no native updates. Explicit `--update` selections remain explicit; desired installs already
+installed or queued for upgrade are filtered out. Native Odoo expands upgrade dependents and installs new dependencies.
+Pending install/upgrade states are included; pending removals need a selected native action or initialization fails.
+
+The independent `godoo.runtime.source_checksums.v1` parameter stores JSON `{"format": 1, "modules": {name: sha256}}`.
+Hashes include deterministic relative filenames and content, all translations regardless of active languages, and core
+Python package sources as part of `base`. Tests, static assets, Git metadata, Python bytecode, and editor swap files are
+excluded. Installed, pending, and requested addons plus their source dependencies are snapshotted before native work. If
+that set can introduce installs, potential auto-install addons and their dependencies are captured too. Unrelated
+ordinary addons are not hashed unless the caller explicitly selects `all`. Imported addons and pathless Studio
+customization are not source modules. Corrupt baseline data fails visibly.
+
+Missing installed sources may be deferred only when a selected native update will run configured pre-upgrade cleanup.
+They must be removed or repaired before a strict post-native rescan. Other missing sources fail initialization. Valid
+native upgrade paths can remain configured without forcing an update; pre-upgrade scripts run only with native update
+selections. These settings are dormant on unchanged starts.
+
+Only a successful native process with no unfinished module states can advance the baseline. gOdoo verifies final
+installed sources against the snapshot taken before native work and saves that snapshot before post-hooks. Source drift
+or failed native work leaves the old baseline; failed post-hooks retain the successful baseline and earlier completed
+one-shot hooks. The pending lifecycle marker remains until all phases succeed. Native Odoo can commit partial work; this
+is not an atomic module-upgrade guarantee. See the native migration recovery limits in [Hooks](hooks.md).
 
 Backups use native Odoo commands on Odoo 19 or newer and PostgreSQL tools on Odoo 16–18.
 
@@ -267,7 +335,9 @@ make dev
 
 `godoo db reset` performs the pair operation; callers must stop writers first. `--db-template` selects another database
 with its matching filestore; `--empty` retains drop-only behavior. Reset copies the database and uses rsync to delete
-filestore files absent from the baseline. PostgreSQL's faster copy method is used when available.
+filestore files absent from the baseline. PostgreSQL's faster copy method is used when available. At default verbosity,
+reset logs lock waiting, baseline checks, database and filestore operations, lifecycle updates, and successful
+completion. `--empty` logs database removal and filestore cleanup too.
 
 An interrupted reset can leave an incomplete active filestore: its marker blocks init, so rerun reset. A missing or
 incomplete baseline needs a fresh restore. The next init reruns restore hooks, native reconciliation, and final hooks.

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/docs/workspace.md

@@ -90,18 +90,23 @@ make typecheck
 ```
 
 Open `godoo.code-workspace` for this repository, or the generated `<project>.code-workspace` downstream. Opening the
-same files in another project's window does not load their workspace settings.
+same files in another project's window does not load their workspace settings. The generated workspace copies settings
+from the project's `.vscode/settings.json`, including JSON comments and trailing commas. Set fixed editor preferences
+there, including the interpreter, language server, and test discovery. gOdoo generates `python.analysis.extraPaths` from
+the selected sources and takes precedence for that setting in the generated workspace. Run `workspace configure` after
+changing project settings; `workspace check` reports the workspace as stale until it is regenerated. Projects without
+those fixed settings inherit their VS Code defaults or other configured values.
 
 | Generated setting    | Contract                                                                                                   |
 | -------------------- | ---------------------------------------------------------------------------------------------------------- |
 | Workspace folder     | Fixed name `gOdoo`; project-relative paths use `${workspaceFolder:gOdoo}`.                                 |
 | Selected sources     | Odoo, addon, and archive paths remain absolute host paths.                                                 |
-| Python analysis      | The Python extension's language server is disabled so Odoo IDE can provide Python and Odoo analysis.       |
-| Python extension     | Keep it installed for interpreter selection and debugging.                                                 |
 | Extra paths          | `python.analysis.extraPaths` includes the selected sources.                                                |
 | `gOdoo: attach`      | Maps the project to `/odoo/godoo_workspace` and the selected sources to their development-container paths. |
 | `pyrightconfig.json` | Ignored project-root file covering `src/`, `addons/`, `scripts/`, project addons, and resolved sources.    |
 
+Keep the Python extension for interpreter selection and debugging.
+
 Python uses Ruff for formatting and safe fixes on save, with lint rules from `pyproject.toml`, including C901. Supported
 text formats use Prettier and `.prettierrc.yml`.
 

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
     "packaging>=21.0",
     "typer-common-functions>=0.1.0",
     "typer>=0.9.0",
+    "json-with-comments>=1.3.0",
 ]
 
 [project.optional-dependencies]
@@ -168,6 +169,7 @@ disable = [
     "wrong-import-order",  # Handled by isort
 ]
 enable = [
+    "too-many-arguments",  # R0913; annotate justified public signatures locally.
     "eval-used",
     "license-allowed",
     "manifest-required-author",

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/src/godoo_cli/__about__.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "1.0.2"
+__version__ = "1.0.4"

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/src/godoo_cli/commands/configuration.py

@@ -15,6 +15,8 @@ from ..workspace.types import ResolvedSource
 LOGGER = logging.getLogger(__name__)
 
 
+# Resolve distinct CLI, config, and argv inputs before constructing GodooConfig; override precedence stays explicit.
+# pylint: disable-next=too-many-arguments
 def resolve_command_config(
     *,
     odoo_main_path: Path,

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/src/godoo_cli/commands/db/archive.py

@@ -15,6 +15,7 @@ from ...runtime.archive import (
     load_runtime_archive,
     prepare_archive_with_original_filestore,
 )
+from ...runtime.backup import BackupFormat
 from ...runtime.odoo import SUPPORTED_ODOO_VERSION_SPECIFIER
 from ..common import CommonCLI
 from ..configuration import require_cli_odoo_version, resolve_development_odoo_main_path
@@ -29,27 +30,37 @@ def dump_database(
     odoo_main_path: Annotated[Path, CLI.odoo_paths.bin_path],
     odoo_conf_path: Annotated[Path | None, CLI.odoo_paths.conf_path] = None,
     data_dir: Annotated[Path, CLI.odoo_paths.data_dir] = Path("/var/lib/odoo"),
+    backup_format: Annotated[
+        BackupFormat,
+        typer.Option(
+            "--format",
+            envvar="GODOO_BACKUP_FORMAT",
+            help="zip: combined archive; dump: custom PostgreSQL dump and rsync filestore directory.",
+        ),
+    ] = BackupFormat.ZIP,
 ) -> int:
-    """Create an Odoo runtime archive."""
+    """Back up a live Odoo database and its filestore in the selected format."""
     try:
         odoo_main_path = resolve_development_odoo_main_path(odoo_main_path)
         version = require_cli_odoo_version(odoo_main_path, SUPPORTED_ODOO_VERSION_SPECIFIER)
-        return CLI.returner(
-            dump_runtime_archive(
-                db_name=db_name,
-                archive_path=archive_path,
-                odoo_bin_path=odoo_main_path / "odoo-bin",
-                odoo_conf_path=odoo_conf_path,
-                data_dir=data_dir,
-                odoo_version=version.major,
-                connection=DBConnection.from_odoo_config(db_name, odoo_conf_path),
-            )
+        result = dump_runtime_archive(
+            db_name=db_name,
+            backup_format=backup_format,
+            archive_path=archive_path,
+            odoo_bin_path=odoo_main_path / "odoo-bin",
+            odoo_conf_path=odoo_conf_path,
+            data_dir=data_dir,
+            odoo_version=version.major,
+            connection=DBConnection.from_odoo_config(db_name, odoo_conf_path),
         )
-    except OSError:
+    except (OSError, RuntimeError, ValueError, psycopg2.Error):
         LOGGER.exception("Archive creation failed")
         return CLI.returner(1)
+    return CLI.returner(result)
 
 
+# Typer declares each archive-restore option in this public callback signature.
+# pylint: disable-next=too-many-arguments
 def load_database(
     db_name: Annotated[str, CLI.database.db_name],
     archive_path: Annotated[Path, typer.Argument()],

{godoo_cli-1.0.2 → godoo_cli-1.0.4}/src/godoo_cli/commands/rpc/importer.py

@@ -14,6 +14,8 @@ CLI = CommonCLI()
 LOGGER = logging.getLogger(__name__)
 
 
+# Typer declares each RPC import option in this public callback signature.
+# pylint: disable-next=too-many-arguments
 def import_to_odoo(
     read_paths: Annotated[
         list[Path],