@wpmoo/toolkit 0.9.27 → 0.9.29

package/README.md

@@ -64,6 +64,9 @@ Short alias:
 npx wpmoo
 ```
 
+Optional short alias: `npx wpmoo`. Use `npx @wpmoo/toolkit` for documentation,
+scripts, and automation.
+
 Deprecated compatibility aliases:
 
 ```bash
@@ -71,7 +74,10 @@ npx @wpmoo/odoo
 npx @wpmoo/odoo-dev
 ```
 
-Deprecated package paths `npx @wpmoo/odoo` and `npx @wpmoo/odoo-dev` remain available as compatibility aliases that redirect to `@wpmoo/toolkit`.
+Deprecated package paths `npx @wpmoo/odoo` and `npx @wpmoo/odoo-dev` remain
+available through the 1.x line as compatibility aliases that redirect to
+`@wpmoo/toolkit`. Removing either compatibility alias requires a future major
+release and prior notice.
 
 When the current directory is not already a WPMoo environment, the CLI opens the create flow. It asks for a product slug, Odoo version, and environment folder. The default environment folder is `./<product>_dev`.
 
@@ -196,6 +202,13 @@ JSON variant exposes a versioned PostgreSQL diagnostics contract.
 `postgres` payload; individual fields are optional so automation can safely handle
 environments where PostgreSQL does not expose a metric.
 
+JSON compatibility policy:
+
+- Automation should ignore unknown JSON fields.
+- Minor and patch releases may add optional fields without a breaking release.
+- Removing, renaming, or changing the meaning of a documented field requires a
+  major release or a `schemaVersion` bump.
+
 ## Release Artifacts
 
 WPMoo Toolkit releases are valid when the required npm artifacts publish
@@ -219,11 +232,17 @@ warning while keeping the scoped package release valid.
   packages are valid.
 - **Smoke expectation**: run `npm run smoke:published -- "$VERSION"` after the
   release tag workflow completes.
+- **1.0 release smoke**: For `1.0.0`, generated-environment acceptance smoke is
+  required before the release is considered final.
 
 ## Documentation
 
+- [Command Reference](docs/command-reference.md)
 - [External Resources](docs/external-resources.md)
 - [Generated Environment Verification](docs/generated-environment-verification.md)
+- [Lifecycle Recipes](docs/lifecycle-recipes.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [1.0 Readiness](docs/1-0-readiness.md)
 - Public documentation site: <https://wpmoo.org>
 
 ## License

package/dist/help.js

@@ -76,8 +76,9 @@ Options:
 
 Package aliases:
   npx @wpmoo/toolkit is the official package path.
-  npx wpmoo is the short alias.
-  npx @wpmoo/odoo and npx @wpmoo/odoo-dev remain deprecated compatibility aliases.
+  npx wpmoo is an optional best-effort short alias; use @wpmoo/toolkit for automation.
+  npx @wpmoo/odoo and npx @wpmoo/odoo-dev remain deprecated compatibility aliases through 1.x.
+  Removing a compatibility alias requires a future major release and prior notice.
 
 Daily actions:
   Daily actions must be run from a generated environment root containing .wpmoo/odoo.json.
@@ -160,6 +161,11 @@ Machine-readable JSON output:
     doctor --json --postgres includes a structured postgres object for automation.
     Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
 
+JSON compatibility policy:
+  Automation should ignore unknown fields.
+  Minor and patch releases may add optional fields.
+  Removing, renaming, or changing the meaning of a documented field requires a major release or schemaVersion bump.
+
 Example:
   npx @wpmoo/toolkit create \\
     --product odoo_sample_module \\

package/docs/1-0-readiness.md

@@ -0,0 +1,123 @@
+# 1.0 Readiness
+
+This checklist tracks what must stay stable before WPMoo Toolkit can be
+released as `1.0.0`.
+
+## Stable Command Names
+
+Ready:
+
+- `npx @wpmoo/toolkit` is the official package entrypoint.
+- Generated environments use local `./moo` for daily commands.
+- Direct commands cover create, status, doctor, source, repository, module,
+  service, database, snapshot, restore, lint, and POT workflows.
+- Compatibility aliases remain available through the 1.x line:
+  `npx @wpmoo/odoo` and `npx @wpmoo/odoo-dev`.
+- The optional unscoped `npx wpmoo` short alias remains best-effort and
+  warning-only. User-facing examples may mention it as optional, but
+  documentation, scripts, and automation should use `npx @wpmoo/toolkit`.
+
+## Stable JSON Contracts
+
+Ready:
+
+- `status --json` uses `schemaVersion: 1`.
+- `source list --json` and `source sync --json` use `schemaVersion: 1`.
+- `doctor --json` uses `schemaVersion: 1`.
+- `doctor --json --postgres` exposes a versioned `postgres` payload with
+  `contractVersion` and diagnostics `schemaVersion`.
+- PostgreSQL diagnostics treat unavailable optional metrics as optional fields.
+- Post-1.0 JSON contracts allow additive optional fields in minor and patch
+  releases.
+- Automation should ignore unknown JSON fields.
+- Breaking JSON changes require a major release or a schemaVersion bump.
+
+## Deprecated Alias Policy
+
+Ready:
+
+- `@wpmoo/toolkit` is the supported package.
+- `@wpmoo/odoo` and `@wpmoo/odoo-dev` are required compatibility artifacts in
+  releases.
+- The optional `wpmoo` short alias is warning-only and does not determine
+  release validity.
+- Compatibility aliases remain available through the 1.x line.
+- Removing a compatibility alias requires a future major release and prior
+  notice.
+
+## Generated File Compatibility
+
+Ready:
+
+- Generated environments keep product source repositories under
+  `odoo/custom/src/private`, `odoo/custom/src/oca`, and
+  `odoo/custom/src/external`.
+- `safe reset` refreshes generated files while preserving source repositories.
+- PostgreSQL 18 mount compatibility is documented and doctor can apply safe
+  mount-target fixes.
+- Generated `./moo` delegates daily commands and keeps local guard behavior.
+- Generated environments created by pre-1.0 releases are supported through safe
+  reset and doctor-guided generated-file migration checks.
+- Generated-file migration support must preserve product source repositories,
+  `.env` files, database dumps, and Docker volumes.
+
+## Stage And Production Policy
+
+Ready:
+
+- Stage `install` and `update` require `WPMOO_ALLOW_STAGE_LIFECYCLE=1`.
+- Production `install`, `update`, and `test` require
+  `WPMOO_ALLOW_PROD_LIFECYCLE=1`.
+- Destructive database commands require `WPMOO_ALLOW_DESTRUCTIVE=1` in stage
+  and production.
+- `restore-snapshot --dry-run`, `doctor`, and `doctor --postgres` remain safe
+  preview/read-only paths.
+- Migration-risk lifecycle commands can require `WPMOO_ALLOW_MIGRATIONS=1`.
+- Environment-variable approvals remain supported through 1.x.
+- Timestamped approval files may be added as an additive safety layer, not as a
+  replacement for env flags in 1.x.
+
+## Release Artifact Policy
+
+Ready:
+
+- Required release artifacts are `@wpmoo/toolkit`, `@wpmoo/odoo`, and
+  `@wpmoo/odoo-dev`.
+- Publishing is handled by GitHub Actions Trusted Publishing after a `v<version>`
+  tag is pushed.
+- `npm run release:check` verifies package state and bumps patch versions when
+  the current version already exists.
+- `npm run smoke:published -- "$VERSION"` is the preferred published package
+  smoke check.
+- Generated-environment acceptance smoke is mandatory for a 1.0.0 release
+  candidate.
+
+## Current Audit
+
+Last updated: 2026-05-21.
+
+Completed checks:
+
+- Full local gate for Train 8 passed on 2026-05-21:
+  `npm run typecheck`, `npm test`, `npm run build`, and `git diff --check`.
+- Coverage passed on 2026-05-21: 72 test files, 682 tests, 92.32%
+  statements, 87.56% branches, 96.74% functions, and 92.32% lines.
+- Published CLI smoke passed against `@wpmoo/toolkit@0.9.27` with `npm exec`
+  for `wpmoo --version`, `wpmoo --help`, and `wpmoo doctor --help`.
+- Placeholder review found no `TODO`, `FIXME`, `TBD`, or `coming soon`
+  markers in `README.md`, `docs`, or `src`.
+- Local markdown link review passed across `README.md` and `docs/*.md`.
+
+Final policy decisions:
+
+- JSON compatibility permits additive optional fields in minor and patch
+  releases; breaking changes require a major release or schemaVersion bump.
+- Compatibility aliases remain available through the 1.x line; removal requires
+  a future major release and prior notice.
+- Pre-1.0 generated environments are supported through safe reset and
+  doctor-guided generated-file migration checks that preserve source code and
+  local runtime data.
+- Environment-variable approvals remain supported through 1.x; timestamped
+  approval files may be added only as an additive safety layer.
+- Generated-environment acceptance smoke is mandatory for a `1.0.0` release
+  candidate.

package/docs/command-reference.md

@@ -0,0 +1,117 @@
+# Command Reference
+
+Use `npx @wpmoo/toolkit ...` for package/operator commands. Use `./moo ...`
+inside a generated environment for daily local commands. The deprecated
+compatibility aliases `npx @wpmoo/odoo` and `npx @wpmoo/odoo-dev` redirect to
+the toolkit package; new automation should use `@wpmoo/toolkit`. Deprecated
+compatibility aliases remain available through the 1.x line. Removing a
+compatibility alias requires a future major release and prior notice. The
+unscoped `npx wpmoo` short alias is optional and best-effort; scripts should use
+`npx @wpmoo/toolkit`.
+
+## Package Commands
+
+| Command | Cockpit Equivalent | JSON | Notes |
+| --- | --- | --- | --- |
+| `npx @wpmoo/toolkit` | Open cockpit or create wizard | No | Opens the create wizard outside an environment and the cockpit inside one. |
+| `npx @wpmoo/toolkit create ...` | Create wizard | No | Creates a generated environment. Use `--target <path>` for a custom folder. |
+| `npx @wpmoo/toolkit status` | Diagnostics -> Environment status | Yes, `--json` | Fast local metadata and file check. |
+| `npx @wpmoo/toolkit doctor [--fix] [--postgres]` | Diagnostics -> Run doctor | Yes, `--json` | Deeper health checks. `--postgres` is read-only and advisory. |
+| `npx @wpmoo/toolkit source list` | Repositories | Yes, `--json` | Lists known source repositories. |
+| `npx @wpmoo/toolkit source sync` | Repositories | Yes, `--json` | Refreshes source manifest data. |
+| `npx @wpmoo/toolkit add-repo --repo-url <url>` | Repositories -> Add source repo | No | Adds a source repository category entry. |
+| `npx @wpmoo/toolkit remove-repo --repo <name>` | Repositories -> Remove source repo | No | Removes a source repository from the environment. |
+| `npx @wpmoo/toolkit add-module --repo <repo> --module <name>` | Modules -> Add module | No | Creates an Odoo module skeleton in a source repository. |
+| `npx @wpmoo/toolkit remove-module --repo <repo> --module <name>` | Modules -> Remove module | No | Removes module metadata; pass `--delete-files` to delete module files after dirty checks. |
+| `npx @wpmoo/toolkit reset [--dry-run]` | Maintenance -> Safe reset environment | No | Refreshes generated files while preserving source repositories. |
+
+## Generated Environment Commands
+
+Run these from the generated environment root:
+
+| Command | Cockpit Equivalent | Guarded In Stage/Prod | Notes |
+| --- | --- | --- | --- |
+| `./moo start` | Services -> Start services | No | Starts local Odoo services. Disabled in cockpit when already running. |
+| `./moo stop` | Services -> Stop services | No | Stops local services. Disabled in cockpit when services are stopped. |
+| `./moo restart` | Services -> Restart services | No | Restarts services. |
+| `./moo logs [service] [tail-lines]` | Services -> View logs | No | Streams or tails service logs. |
+| `./moo shell` | Services -> Open shell | No | Opens a shell in the Odoo service container. |
+| `./moo psql [db]` | Database -> Open psql | No | Opens a PostgreSQL prompt. |
+| `./moo install <module[,module]> [db]` | Modules -> Install module | Yes | Installs one or more modules. |
+| `./moo update <module[,module]> [db]` | Modules -> Update module | Yes | Updates one or more modules. |
+| `./moo test <module[,module]> --db <db>` | Modules -> Run tests | Yes in prod | Runs Odoo tests for modules. |
+| `./moo lint` | Modules -> Run environment lint | No | Runs configured environment lint checks. |
+| `./moo pot <module[,module]> [db] [output]` | Modules -> Generate POT | No | Generates translation template files. |
+| `./moo snapshot [db] [name]` | Database -> Create snapshot | No | Creates a database and filestore snapshot. |
+| `./moo restore-snapshot --dry-run <name> [db]` | Database -> Restore snapshot | Preview only | Prints a restore preview without changing data. |
+| `./moo restore-snapshot <name> [db]` | Database -> Restore snapshot | Yes | Restores database and filestore from a snapshot. |
+| `./moo resetdb [db] [module[,module]]` | Database -> Reset database | Yes | Destructive database reset. |
+| `./moo doctor [--fix] [--postgres]` | Diagnostics -> Run doctor | No | Local health checks. |
+| `./moo status` | Diagnostics -> Environment status | No | Local environment status. |
+
+## JSON Output
+
+Machine-readable output is available for automation:
+
+```bash
+npx @wpmoo/toolkit status --json
+npx @wpmoo/toolkit source list --json
+npx @wpmoo/toolkit source sync --json
+npx @wpmoo/toolkit doctor --json
+npx @wpmoo/toolkit doctor --json --postgres
+```
+
+Current JSON contract notes:
+
+- `status --json` uses `schemaVersion: 1`.
+- `source list --json` and `source sync --json` use `schemaVersion: 1`.
+- `doctor --json` uses `schemaVersion: 1`.
+- `doctor --json --postgres` adds `postgres.contractVersion` and a PostgreSQL
+  diagnostics object with its own `schemaVersion`.
+- PostgreSQL fields are optional when a metric is unavailable.
+- Automation should ignore unknown JSON fields.
+- Minor and patch releases may add optional fields without a breaking release.
+- Removing, renaming, or changing the meaning of a documented field requires a
+  major release or a `schemaVersion` bump.
+
+## Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `WPMOO_ENV=dev|stage|prod` | Selects environment safety policy. Missing value behaves like development for local workflows. |
+| `WPMOO_ALLOW_STAGE_LIFECYCLE=1` | Allows `install` and `update` in stage. |
+| `WPMOO_ALLOW_PROD_LIFECYCLE=1` | Allows `install`, `update`, and `test` in production. |
+| `WPMOO_ALLOW_DESTRUCTIVE=1` | Allows destructive database commands in stage/prod. |
+| `WPMOO_ALLOW_NO_RECENT_SNAPSHOT=1` | Allows destructive commands without a recent snapshot when that extra guard applies. |
+| `WPMOO_ALLOW_MIGRATIONS=1` | Allows lifecycle commands when migration scripts are detected. |
+| `WPMOO_NODE_BIN`, `WPMOO_NPX_BIN`, `WPMOO_GIT_BIN` | Override binaries used by release smoke scripts. |
+
+Process environment values take precedence over `.env` values for safety flags.
+
+## Exit Behavior
+
+- Successful commands exit `0`.
+- Invalid arguments, missing environment metadata, refused guard checks, dirty
+  deletion, and failed subprocesses exit non-zero.
+- `--json` commands still use process exit codes; automation should check both
+  the exit status and the `ok` field when present.
+- Guard failures are intentional failures. Do not silence them unless the named
+  `WPMOO_ALLOW_*` flag has been reviewed.
+
+## Stage And Production Restrictions
+
+| Command Family | Stage | Production |
+| --- | --- | --- |
+| `install`, `update` | Requires `WPMOO_ALLOW_STAGE_LIFECYCLE=1` | Requires `WPMOO_ALLOW_PROD_LIFECYCLE=1` |
+| `test` | Allowed | Requires `WPMOO_ALLOW_PROD_LIFECYCLE=1` |
+| `resetdb`, real `restore-snapshot` | Requires `WPMOO_ALLOW_DESTRUCTIVE=1` | Requires `WPMOO_ALLOW_DESTRUCTIVE=1` |
+| `restore-snapshot --dry-run` | Allowed | Allowed |
+| Commands with detected migration scripts | May require `WPMOO_ALLOW_MIGRATIONS=1` | May require `WPMOO_ALLOW_MIGRATIONS=1` |
+
+Prefer read-only and dry-run commands first:
+
+```bash
+./moo doctor
+./moo doctor --postgres
+./moo restore-snapshot --dry-run before-change devel
+```

package/docs/handoff.md

@@ -60,7 +60,26 @@ Suggested smoke check:
 npm run smoke:published -- "$VERSION"
 ```
 
+For a 1.0.0 tag, run generated-environment acceptance smoke with
+WPMOO_SMOKE_ENVIRONMENT=1. Treat the release as final only after that smoke
+passes:
+
+```bash
+WPMOO_SMOKE_ENVIRONMENT=1 npm run smoke:published -- "$VERSION"
+```
+
 Current command standard:
 
 - Use `npx @wpmoo/toolkit ...` for package/operator commands.
 - Use generated environment `./moo ...` for local compose daily commands.
+
+1.0 readiness references:
+
+- [Command Reference](command-reference.md)
+- [Lifecycle Recipes](lifecycle-recipes.md)
+- [Troubleshooting](troubleshooting.md)
+- [1.0 Readiness](1-0-readiness.md)
+
+Before a `1.0.0` tag, review the readiness gap list and decide whether the next
+milestone is "ship 1.0" or "finish named gaps." Do not treat the gap list as an
+open-ended cleanup queue.

package/docs/lifecycle-recipes.md

@@ -0,0 +1,190 @@
+# Lifecycle Recipes
+
+These recipes show WPMoo Toolkit as a sequence of Dev, Stage, and Production
+workflows. Replace repository names, module names, and database names with your
+project values.
+
+## Local Development Setup
+
+Create a generated environment from a workspace directory:
+
+```bash
+npx @wpmoo/toolkit create \
+  --product odoo_sample_module \
+  --odoo-version 19.0 \
+  --target ./odoo_sample_module_dev \
+  --dev-repo-url https://github.com/example-org/odoo_sample_module_dev.git \
+  --source-repo-url https://github.com/example-org/odoo_sample_module.git
+```
+
+Enter the environment and start daily work:
+
+```bash
+cd odoo_sample_module_dev
+./moo start
+./moo status
+./moo doctor
+```
+
+Use the cockpit for interactive workflows:
+
+```bash
+./moo
+```
+
+## Add A Source Repository
+
+Add a private source repository:
+
+```bash
+npx @wpmoo/toolkit add-repo \
+  --repo-url https://github.com/example-org/odoo-addons.git \
+  --source-type private
+```
+
+Refresh the source manifest:
+
+```bash
+npx @wpmoo/toolkit source sync
+npx @wpmoo/toolkit source list
+```
+
+Use `--source-type oca` for OCA repositories and `--source-type external` for
+third-party repositories.
+
+## Add A Module
+
+Create a module skeleton:
+
+```bash
+npx @wpmoo/toolkit add-module \
+  --repo odoo-addons \
+  --module moo_test \
+  --source-type private
+```
+
+Verify the generated module:
+
+```bash
+./moo status
+./moo lint
+```
+
+Expected module files include `__manifest__.py`, model imports, security access
+CSV, views, menus, and a post-install TransactionCase smoke test.
+
+## Install And Update A Module
+
+Start services and install the module into the development database:
+
+```bash
+./moo start
+./moo install moo_test devel
+```
+
+After code changes, update the module:
+
+```bash
+./moo update moo_test devel
+```
+
+If the cockpit shows module actions as disabled, run:
+
+```bash
+./moo status
+npx @wpmoo/toolkit source list
+```
+
+Then add or sync source repositories until installable modules are detected.
+
+## Run Tests
+
+Run module tests in development:
+
+```bash
+./moo test moo_test --db devel
+```
+
+Use explicit test mode when needed:
+
+```bash
+./moo test moo_test --db devel --mode update --tags /moo_test
+```
+
+For production, test execution is guarded:
+
+```bash
+WPMOO_ENV=prod WPMOO_ALLOW_PROD_LIFECYCLE=1 ./moo test moo_test --db devel
+```
+
+## Snapshot And Restore
+
+Take a snapshot before risky changes:
+
+```bash
+./moo snapshot devel before-moo-test-update
+```
+
+Preview a restore:
+
+```bash
+./moo restore-snapshot --dry-run before-moo-test-update devel
+```
+
+Restore intentionally:
+
+```bash
+WPMOO_ENV=stage WPMOO_ALLOW_DESTRUCTIVE=1 ./moo restore-snapshot before-moo-test-update devel
+```
+
+When the no-recent-snapshot guard applies to a destructive command, either make
+a fresh snapshot or set `WPMOO_ALLOW_NO_RECENT_SNAPSHOT=1` after review.
+
+## Stage Dry-Run Validation
+
+Use stage for preview-first validation:
+
+```bash
+WPMOO_ENV=stage ./moo doctor
+WPMOO_ENV=stage ./moo doctor --postgres
+WPMOO_ENV=stage ./moo restore-snapshot --dry-run before-moo-test-update devel
+```
+
+Run lifecycle commands only after review:
+
+```bash
+WPMOO_ENV=stage WPMOO_ALLOW_STAGE_LIFECYCLE=1 ./moo update moo_test devel
+```
+
+If migration scripts are detected, WPMoo may also require:
+
+```bash
+WPMOO_ENV=stage WPMOO_ALLOW_STAGE_LIFECYCLE=1 WPMOO_ALLOW_MIGRATIONS=1 ./moo update moo_test devel
+```
+
+## Production-Safe Preview
+
+Production workflows should start with read-only checks:
+
+```bash
+WPMOO_ENV=prod ./moo status
+WPMOO_ENV=prod ./moo doctor
+WPMOO_ENV=prod ./moo doctor --postgres
+WPMOO_ENV=prod ./moo restore-snapshot --dry-run before-change devel
+```
+
+Production lifecycle commands require explicit approval flags:
+
+```bash
+WPMOO_ENV=prod WPMOO_ALLOW_PROD_LIFECYCLE=1 ./moo update moo_test devel
+```
+
+Destructive production commands require a separate flag and a rollback plan:
+
+```bash
+WPMOO_ENV=prod WPMOO_ALLOW_DESTRUCTIVE=1 ./moo restore-snapshot before-change devel
+```
+
+Do not set production flags globally in a shell profile. Prefer one-command
+environment variable prefixes so intent is visible in shell history.
+

package/docs/troubleshooting.md

@@ -0,0 +1,225 @@
+# Troubleshooting
+
+This cookbook lists common WPMoo Toolkit failure states and the safest next
+step for each one. Run commands from the generated environment root unless the
+example explicitly starts with `npx @wpmoo/toolkit`.
+
+## Docker Is Missing Or Stopped
+
+Symptoms:
+
+- The create wizard stops before writing files.
+- `./moo start`, `./moo status`, or `./moo doctor` reports Docker or Docker
+  Compose as unavailable.
+
+Check:
+
+```bash
+docker version
+docker compose version
+```
+
+Next steps:
+
+1. Install Docker Desktop or another Docker Engine distribution.
+2. Start Docker Desktop and wait until the engine is ready.
+3. Open a new terminal if Docker was added to `PATH`.
+4. Run the WPMoo command again.
+
+The create wizard intentionally stops before setup questions when required
+runtime tools are missing. That protects the workspace from half-created
+environments.
+
+## No Modules Found
+
+Symptoms:
+
+- The cockpit disables module actions.
+- `List modules`, `Install module`, `Update module`, `Run tests`, `Run
+  environment lint`, `Generate POT`, or `Remove module` says no modules are
+  available.
+
+Check the source inventory:
+
+```bash
+./moo status
+npx @wpmoo/toolkit source list
+```
+
+Next steps:
+
+1. Add or sync a source repository.
+
+   ```bash
+   npx @wpmoo/toolkit add-repo --repo-url https://github.com/example-org/odoo-addons.git --source-type private
+   npx @wpmoo/toolkit source sync
+   ```
+
+2. Add a new module skeleton if the repository exists but has no installable
+   module yet.
+
+   ```bash
+   npx @wpmoo/toolkit add-module --repo odoo-addons --module moo_test --source-type private
+   ```
+
+3. Reopen the cockpit or run `./moo status` again.
+
+Expected result:
+
+- Module actions become selectable once at least one installable module is
+  detected.
+- If a module has no actionable Odoo menu, `status` reports it so you can fix
+  the generated menu/action metadata.
+
+## No Source Repositories
+
+Symptoms:
+
+- `source list` is empty.
+- Module actions cannot find a target repository.
+- The generated environment exists but `odoo/custom/src/private`,
+  `odoo/custom/src/oca`, and `odoo/custom/src/external` contain no usable
+  source checkout.
+
+Check:
+
+```bash
+npx @wpmoo/toolkit source list --json
+```
+
+Next steps:
+
+```bash
+npx @wpmoo/toolkit add-repo --repo-url https://github.com/example-org/odoo-addons.git --source-type private
+npx @wpmoo/toolkit source sync
+```
+
+Use `--source-type oca` or `--source-type external` when the repository belongs
+outside the private source category.
+
+## Dirty Module Deletion Is Refused
+
+Symptoms:
+
+- `remove-module` refuses to delete module files.
+- The command reports local changes or an unsafe module worktree.
+
+Check the source repository directly:
+
+```bash
+git -C odoo/custom/src/private/<repo> status --short
+```
+
+Next steps:
+
+1. Commit, stash, or intentionally discard the local module changes from inside
+   the source repository.
+2. Re-run the removal.
+
+   ```bash
+   npx @wpmoo/toolkit remove-module --repo <repo> --module <module> --source-type private --delete-files
+   ```
+
+WPMoo refuses dirty deletion because module repositories are product source
+code, not disposable generated files.
+
+## Optional `wpmoo` Alias Reports E404
+
+Symptoms:
+
+- Release checks or manual npm checks report `wpmoo@<version>` as missing.
+- Scoped packages are available.
+
+Required packages:
+
+```bash
+npm view @wpmoo/toolkit@<version> version
+npm view @wpmoo/odoo@<version> version
+npm view @wpmoo/odoo-dev@<version> version
+```
+
+Interpretation:
+
+- `@wpmoo/toolkit`, `@wpmoo/odoo`, and `@wpmoo/odoo-dev` are the supported
+  release artifacts.
+- The unscoped `wpmoo` short alias is best-effort. An E404 for `wpmoo` does not
+  invalidate a release when the three scoped packages verify.
+
+Use the supported package path in automation:
+
+```bash
+npx @wpmoo/toolkit --version
+```
+
+## PostgreSQL Diagnostics Are Unavailable
+
+Symptoms:
+
+- `./moo doctor --postgres` prints an advisory warning.
+- `./moo doctor --json --postgres` includes `postgres.available: false`.
+
+Check that services are running:
+
+```bash
+./moo status
+./moo start
+./moo doctor --postgres
+```
+
+Next steps:
+
+1. Confirm the database service is running and reachable.
+2. Run the JSON form to inspect the structured reason.
+
+   ```bash
+   ./moo doctor --json --postgres
+   ```
+
+3. Treat PostgreSQL diagnostics as advisory. WPMoo only runs read-only checks
+   and does not tune PostgreSQL automatically.
+
+Expected result when available:
+
+- The JSON payload includes `postgres.contractVersion`.
+- The diagnostics object includes `schemaVersion`.
+- Missing or malformed metric rows are reported as unavailable diagnostics
+  instead of being treated as success.
+
+## Stage Or Production Guard Failure
+
+Symptoms:
+
+- `install`, `update`, `test`, `resetdb`, or `restore-snapshot` is refused in
+  `WPMOO_ENV=stage` or `WPMOO_ENV=prod`.
+- The message names a required `WPMOO_ALLOW_*` flag.
+
+Safe preview commands:
+
+```bash
+./moo restore-snapshot --dry-run <snapshot-name> devel
+./moo doctor
+./moo doctor --postgres
+```
+
+Intentional stage lifecycle command:
+
+```bash
+WPMOO_ENV=stage WPMOO_ALLOW_STAGE_LIFECYCLE=1 ./moo update <module> devel
+```
+
+Intentional production lifecycle command:
+
+```bash
+WPMOO_ENV=prod WPMOO_ALLOW_PROD_LIFECYCLE=1 ./moo test <module> --db devel
+```
+
+Intentional destructive command:
+
+```bash
+WPMOO_ENV=stage WPMOO_ALLOW_DESTRUCTIVE=1 WPMOO_ALLOW_NO_RECENT_SNAPSHOT=1 ./moo resetdb devel
+```
+
+Use the guard flag only when the command is intentional, reviewed, and has an
+appropriate rollback path. Migration-risk lifecycle commands may also require
+`WPMOO_ALLOW_MIGRATIONS=1`.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpmoo/toolkit",
-  "version": "0.9.27",
+  "version": "0.9.29",
   "description": "WPMoo Toolkit for development, staging, and production lifecycle workflows.",
   "type": "module",
   "repository": {