@wpmoo/toolkit 0.9.28 → 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,6 +232,8 @@ 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
 

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

@@ -11,13 +11,11 @@ Ready:
 - 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.
-- Deprecated package aliases remain compatibility paths:
+- Compatibility aliases remain available through the 1.x line:
   `npx @wpmoo/odoo` and `npx @wpmoo/odoo-dev`.
-
-Remaining decision:
-
-- Whether the optional unscoped `npx wpmoo` short alias should be promoted,
-  kept best-effort, or removed from public examples before `1.0.0`.
+- 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
 
@@ -29,11 +27,10 @@ Ready:
 - `doctor --json --postgres` exposes a versioned `postgres` payload with
   `contractVersion` and diagnostics `schemaVersion`.
 - PostgreSQL diagnostics treat unavailable optional metrics as optional fields.
-
-Remaining decision:
-
-- Document a compatibility policy for future JSON schema changes, including
-  whether minor additive fields are allowed without a major release.
+- 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
 
@@ -44,11 +41,9 @@ Ready:
   releases.
 - The optional `wpmoo` short alias is warning-only and does not determine
   release validity.
-
-Remaining decision:
-
-- Set an explicit deprecation horizon for compatibility aliases after `1.0.0`,
-  or commit to maintaining them indefinitely.
+- Compatibility aliases remain available through the 1.x line.
+- Removing a compatibility alias requires a future major release and prior
+  notice.
 
 ## Generated File Compatibility
 
@@ -61,11 +56,10 @@ Ready:
 - PostgreSQL 18 mount compatibility is documented and doctor can apply safe
   mount-target fixes.
 - Generated `./moo` delegates daily commands and keeps local guard behavior.
-
-Remaining decision:
-
-- Define a generated-file migration policy for environments created by older
-  pre-1.0 releases.
+- 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
 
@@ -79,11 +73,9 @@ Ready:
 - `restore-snapshot --dry-run`, `doctor`, and `doctor --postgres` remain safe
   preview/read-only paths.
 - Migration-risk lifecycle commands can require `WPMOO_ALLOW_MIGRATIONS=1`.
-
-Remaining decision:
-
-- Decide whether stage/prod approvals should gain a timestamped confirmation
-  file or continue to rely on environment variables only.
+- 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
 
@@ -97,11 +89,8 @@ Ready:
   the current version already exists.
 - `npm run smoke:published -- "$VERSION"` is the preferred published package
   smoke check.
-
-Remaining decision:
-
-- Decide whether release smoke should include a generated-environment acceptance
-  run by default for `1.0.0` tags.
+- Generated-environment acceptance smoke is mandatory for a 1.0.0 release
+  candidate.
 
 ## Current Audit
 
@@ -119,11 +108,16 @@ Completed checks:
   markers in `README.md`, `docs`, or `src`.
 - Local markdown link review passed across `README.md` and `docs/*.md`.
 
-Final gap list:
-
-- Define JSON compatibility rules for post-1.0 additive fields.
-- Decide the long-term compatibility alias policy.
-- Decide generated-environment migration support for older pre-1.0 outputs.
-- Decide whether stage/prod approvals need timestamped confirmation files.
-- Decide whether generated-environment published smoke should be mandatory for
-  `1.0.0` tags.
+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

@@ -3,7 +3,11 @@
 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`.
+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
 
@@ -65,6 +69,10 @@ Current JSON contract notes:
 - `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
 
@@ -107,4 +115,3 @@ Prefer read-only and dry-run commands first:
 ./moo doctor --postgres
 ./moo restore-snapshot --dry-run before-change devel
 ```
-

package/docs/handoff.md

@@ -60,6 +60,14 @@ 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.

package/package.json

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