@wpmoo/odoo 0.8.56 → 0.8.58

package/README.md

@@ -28,7 +28,10 @@ It gives Odoo teams a repeatable environment layout, a guided cockpit for daily
 - Docker and Docker Compose for generated environment runtime commands
 - GitHub CLI (`gh`) is optional. Use it for repository discovery, repository creation, and deeper diagnostics.
 
-The wizard currently offers Odoo `19.0`, `18.0`, `17.0`, and `16.0`. The copied Compose resource must include the matching `docker-compose_<version>.yml` file for the selected branch.
+The wizard currently offers Odoo `19.0`, `18.0`, `17.0`, and `16.0`. Generated
+environments now use the compact compose layout (`compose.yaml` with
+`compose/<env>.yaml` overlays). Legacy root-level
+`docker-compose_<version>.yml` layouts are still supported for compatibility.
 
 Set up GitHub CLI only when you want WPMoo to discover your personal account and organizations or create missing repositories from the interactive wizard:
 
@@ -173,11 +176,20 @@ odoo_sample_module_dev/
 |-- .env.example
 |-- AGENTS.md
 |-- README.md
+|-- compose.yaml
+|-- compose/
+|   |-- dev.yaml
+|   |-- stage.yaml
+|   `-- prod.yaml
+|-- config/
+|   `-- odoo/
+|       `-- odoo.conf
 |-- docs/
 |   |-- appstore-release.md
 |   `-- compose.md
-|-- docker-compose_19.0.yml
-|-- etc/
+|-- resources/
+|   `-- odoo/
+|       `-- entrypoint.sh
 |-- moo
 |-- odoo/
 |   `-- custom/
@@ -187,6 +199,10 @@ odoo_sample_module_dev/
 `-- scripts/
 ```
 
+Development uses `compose.yaml` plus `compose/dev.yaml` by default. Set
+`WPMOO_ENV=stage` or `WPMOO_ENV=prod` only after providing production-grade
+secrets and volumes.
+
 The metadata file `.wpmoo/odoo.json` records the product slug, selected Odoo version, dev repo URL, source repos, engine, external resource refs, ports, and template configuration. Status, doctor, daily actions, and safe reset use that metadata instead of guessing from the filesystem.
 
 ## Daily `./moo` Commands
@@ -291,7 +307,12 @@ Safe reset refreshes generated environment files without deleting product source
 npx @wpmoo/odoo reset
 ```
 
-Safe reset updates generated files such as `.wpmoo/odoo.json`, `moo`, `.gitignore`, `.env.example`, generated docs, compose assets, and optional Agent Skills. It does not touch source repo folders under `odoo/custom/src/private`, module source code, Git history, remotes, or branches.
+Safe reset updates generated files such as `.wpmoo/odoo.json`, `moo`,
+`.gitignore`, `.env.example`, generated docs, compose assets, and optional
+Agent Skills. It does not touch source repo folders under
+`odoo/custom/src/private`, module source code, Git history, remotes, or
+branches. Legacy compose template paths from older scaffolds can remain
+(`docs/assets/`, `test/`, `.github/`) until you remove them manually.
 
 Recommended recovery pattern:
 

package/dist/compose-layout.js

@@ -0,0 +1,118 @@
+import { access, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseEnvContent(content) {
+    const values = new Map();
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const separator = line.indexOf('=');
+        if (separator === -1)
+            continue;
+        const key = line.slice(0, separator).trim();
+        let value = line.slice(separator + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        values.set(key, value);
+    }
+    return values;
+}
+export async function readEnvFile(target) {
+    const path = join(target, '.env');
+    if (!(await exists(path)))
+        return undefined;
+    return parseEnvContent(await readFile(path, 'utf8'));
+}
+export function selectedComposeEnvironment(env) {
+    return env?.get('WPMOO_ENV')?.trim() || 'dev';
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter((value) => value.trim()).map((value) => value.trim()))];
+}
+function isValidComposeEnvironmentName(value) {
+    return /^[A-Za-z0-9_-]+$/.test(value);
+}
+function isValidOdooVersion(value) {
+    return /^\d+\.\d+$/.test(value);
+}
+function compactOverlayError(envName, overlayFile) {
+    if (envName === 'dev')
+        return `Missing compact compose overlay: ${overlayFile}`;
+    return `Missing compact compose overlay for WPMOO_ENV=${envName}: ${overlayFile}`;
+}
+export async function detectComposeLayout(target, options) {
+    const envName = options.envName?.trim() || 'dev';
+    if (!isValidComposeEnvironmentName(envName)) {
+        return {
+            kind: 'missing',
+            files: [],
+            missingFiles: [],
+            errors: [`Invalid WPMOO_ENV in .env: expected a simple compose overlay name, got ${envName}`],
+        };
+    }
+    const compactBase = 'compose.yaml';
+    const compactOverlay = `compose/${envName}.yaml`;
+    const hasCompactBase = await exists(join(target, compactBase));
+    const hasCompactOverlay = await exists(join(target, compactOverlay));
+    if (hasCompactBase && hasCompactOverlay) {
+        return {
+            kind: 'compact',
+            envName,
+            files: [compactBase, compactOverlay],
+            missingFiles: [],
+            errors: [],
+        };
+    }
+    if (hasCompactBase || hasCompactOverlay) {
+        const errors = [];
+        const missingFiles = [];
+        if (!hasCompactBase) {
+            missingFiles.push(compactBase);
+            errors.push(`Missing compact compose base: ${compactBase}`);
+        }
+        if (!hasCompactOverlay) {
+            missingFiles.push(compactOverlay);
+            errors.push(compactOverlayError(envName, compactOverlay));
+        }
+        return { kind: 'missing', files: [], missingFiles, errors };
+    }
+    const odooVersions = uniqueStrings(options.odooVersions);
+    const invalidOdooVersions = odooVersions.filter((version) => !isValidOdooVersion(version));
+    if (invalidOdooVersions.length > 0) {
+        return {
+            kind: 'missing',
+            files: [],
+            missingFiles: [],
+            errors: invalidOdooVersions.map((version) => `Invalid Odoo version for compose file: ${version}`),
+        };
+    }
+    const legacyFiles = odooVersions.map((version) => `docker-compose_${version}.yml`);
+    const missingLegacyFiles = [];
+    for (const file of legacyFiles) {
+        if (!(await exists(join(target, file)))) {
+            missingLegacyFiles.push(file);
+        }
+    }
+    if (legacyFiles.length > 0 && missingLegacyFiles.length === 0) {
+        return { kind: 'legacy', files: legacyFiles, missingFiles: [], errors: [] };
+    }
+    return {
+        kind: 'missing',
+        files: [],
+        missingFiles: missingLegacyFiles,
+        errors: legacyFiles.length > 0
+            ? missingLegacyFiles.map((file) => `Missing compose file: ${file}`)
+            : ['Missing compose layout: expected compose.yaml with compose/dev.yaml or a versioned docker-compose file'],
+    };
+}

package/dist/doctor.js

@@ -1,6 +1,7 @@
 import { access, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { execa } from 'execa';
+import { detectComposeLayout, readEnvFile, selectedComposeEnvironment } from './compose-layout.js';
 import { dailyActionScripts } from './daily-actions.js';
 import { defaultOdooVersion, markerPath } from './environment.js';
 const realCommandRunner = async (command, args, options) => {
@@ -72,31 +73,6 @@ function metadataString(metadata, key) {
     const value = metadata[key];
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
-function parseEnv(content) {
-    const values = new Map();
-    for (const rawLine of content.split(/\r?\n/)) {
-        const line = rawLine.trim();
-        if (!line || line.startsWith('#'))
-            continue;
-        const separator = line.indexOf('=');
-        if (separator === -1)
-            continue;
-        const key = line.slice(0, separator).trim();
-        let value = line.slice(separator + 1).trim();
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-        }
-        values.set(key, value);
-    }
-    return values;
-}
-async function readEnv(target) {
-    const path = join(target, '.env');
-    if (!(await exists(path)))
-        return undefined;
-    return parseEnv(await readFile(path, 'utf8'));
-}
 function validatePort(name, env, errors) {
     const value = env.get(name)?.trim() ?? '';
     if (!/^\d+$/.test(value)) {
@@ -151,20 +127,21 @@ export async function runDoctor(target = process.cwd(), runner = realCommandRunn
     }
     const odooVersion = metadataString(metadata, 'odooVersion') ?? defaultOdooVersion;
     lines.push(`OK Odoo version ${odooVersion}`);
-    const env = await readEnv(target);
+    const env = await readEnvFile(target);
     const composeVersions = new Set([odooVersion]);
     const envOdooVersion = env?.get('ODOO_VERSION')?.trim();
     if (envOdooVersion) {
         composeVersions.add(envOdooVersion);
     }
-    for (const version of composeVersions) {
-        const composeFile = `docker-compose_${version}.yml`;
-        if (await exists(join(target, composeFile))) {
-            lines.push(`OK compose ${composeFile}`);
-        }
-        else {
-            errors.push(`Missing compose file: ${composeFile}`);
-        }
+    const composeLayout = await detectComposeLayout(target, {
+        odooVersions: [...composeVersions],
+        envName: selectedComposeEnvironment(env),
+    });
+    if (composeLayout.kind === 'missing') {
+        errors.push(...composeLayout.errors);
+    }
+    else {
+        lines.push(`OK compose files ${composeLayout.files.join(', ')}`);
     }
     const scriptNames = Object.values(dailyActionScripts);
     const scriptErrorCount = errors.length;

package/dist/external-assets.js

@@ -62,7 +62,8 @@ function isExcluded(relativePath, excludes) {
     return excludes.some((pattern) => normalized === pattern || normalized.startsWith(`${pattern}/`));
 }
 async function copyDirectory(options, checkedOut) {
-    const sourcePath = options.sourceSubdir ? join(checkedOut.root, options.sourceSubdir) : checkedOut.root;
+    const selectedSourceSubdir = await selectSourceSubdir(options, checkedOut.root);
+    const sourcePath = selectedSourceSubdir ? join(checkedOut.root, selectedSourceSubdir) : checkedOut.root;
     const destinationPath = options.destinationSubdir
         ? join(options.destination, options.destinationSubdir)
         : options.destination;
@@ -80,7 +81,10 @@ async function copyDirectory(options, checkedOut) {
         },
     });
     if (options.readmeDestination) {
-        const readmePath = join(checkedOut.root, 'README.md');
+        const selectedReadmePath = selectedSourceSubdir ? join(checkedOut.root, selectedSourceSubdir, 'README.md') : undefined;
+        const readmePath = selectedReadmePath && (await pathExists(selectedReadmePath))
+            ? selectedReadmePath
+            : join(checkedOut.root, 'README.md');
         if (await pathExists(readmePath)) {
             const destination = join(options.destination, options.readmeDestination);
             await mkdir(dirname(destination), { recursive: true });
@@ -88,6 +92,14 @@ async function copyDirectory(options, checkedOut) {
         }
     }
 }
+async function selectSourceSubdir(options, root) {
+    for (const candidate of options.sourceSubdirCandidates ?? []) {
+        if (await pathExists(join(root, candidate))) {
+            return candidate;
+        }
+    }
+    return options.sourceSubdir;
+}
 export function renderExternalAssetCommand(options) {
     const sourcePath = options.sourceSubdir ? `${options.source}/${options.sourceSubdir}` : options.source;
     const destinationPath = options.destinationSubdir

package/dist/external-templates.js

@@ -46,7 +46,18 @@ export function composeTemplateOptions(options) {
         source: options.composeTemplateUrl ?? defaultComposeTemplateUrl,
         destination: options.target,
         ref: options.composeTemplateRef,
-        exclude: ['README.md', 'README-template.md', '.gitignore', 'LICENSE', 'package.json', 'package-lock.json'],
+        sourceSubdirCandidates: ['resources/generated-env'],
+        exclude: [
+            '.github',
+            'docs/assets',
+            'test',
+            'README.md',
+            'README-template.md',
+            '.gitignore',
+            'LICENSE',
+            'package.json',
+            'package-lock.json',
+        ],
         readmeDestination: 'docs/compose.md',
     };
 }

package/dist/safe-reset.js

@@ -29,6 +29,7 @@ export function renderSafeResetPreview(target, stage) {
         '- source repo folders under odoo/custom/src/private',
         '- module source code',
         '- Git history, remotes, or branches',
+        '- Legacy compose template files may remain until manually removed: docs/assets/, test/, .github/',
         '',
         stage ? 'Generated changes will be staged with git add .' : 'Generated changes will not be staged.',
     ].join('\n');

package/dist/scaffold.js

@@ -22,6 +22,33 @@ function validateScaffoldOptions(options) {
 }
 export function generatedFiles(options) {
     const safeOptions = validateScaffoldOptions(options);
+    const sourceDirReadmes = [
+        {
+            path: 'odoo/custom/src/private/README.md',
+            title: 'private',
+            body: 'Project-owned/private addon repositories go here.',
+        },
+        {
+            path: 'odoo/custom/src/oca/README.md',
+            title: 'oca',
+            body: 'OCA repositories go here, for example server-tools, web, queue.',
+        },
+        {
+            path: 'odoo/custom/src/external/README.md',
+            title: 'external',
+            body: 'Non-OCA third-party, vendor, and community addon repositories go here.',
+        },
+        {
+            path: 'odoo/custom/patches/README.md',
+            title: 'patches',
+            body: 'Local patches for upstream/vendor/OCA repositories go here.',
+        },
+        {
+            path: 'odoo/custom/manifests/README.md',
+            title: 'manifests',
+            body: 'Manifest/lock/list files for external sources and pinned revisions go here.',
+        },
+    ];
     const files = [
         { path: markerPath, content: renderEnvironmentMetadata(safeOptions) },
         { path: 'moo', content: renderMooDelegationScript(), mode: 0o755 },
@@ -32,10 +59,10 @@ export function generatedFiles(options) {
     ];
     return [
         ...files,
-        {
-            path: 'odoo/custom/src/private/README.md',
-            content: renderPlaceholder('private', 'WPMoo source repositories are added here as Git submodules.'),
-        },
+        ...sourceDirReadmes.map((readme) => ({
+            path: readme.path,
+            content: renderPlaceholder(readme.title, readme.body),
+        })),
     ];
 }
 async function writeGeneratedFiles(target, files) {

package/dist/status.js

@@ -1,5 +1,6 @@
 import { access, readdir, readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { detectComposeLayout, readEnvFile, selectedComposeEnvironment } from './compose-layout.js';
 import { defaultOdooVersion, markerPath } from './environment.js';
 import { isValidPathSegment, validateRepoPath } from './path-validation.js';
 async function pathExists(path) {
@@ -43,12 +44,10 @@ function sourceRepoPathsFromMetadata(metadata) {
 }
 async function missingCoreFiles(target, odooVersion) {
     const missing = [];
-    const composeFile = `docker-compose_${odooVersion}.yml`;
     const checks = [
         { label: 'moo', path: join(target, 'moo') },
         { label: 'README.md', path: join(target, 'README.md') },
         { label: 'AGENTS.md', path: join(target, 'AGENTS.md') },
-        { label: composeFile, path: join(target, composeFile) },
         { label: 'scripts/', path: join(target, 'scripts'), mustBeDirectory: true },
     ];
     for (const check of checks) {
@@ -62,7 +61,13 @@ async function missingCoreFiles(target, odooVersion) {
                 missing.push(check.label);
         }
     }
-    return missing;
+    const env = await readEnvFile(target);
+    const composeLayout = await detectComposeLayout(target, {
+        odooVersions: [odooVersion],
+        envName: selectedComposeEnvironment(env),
+    });
+    missing.push(...composeLayout.missingFiles);
+    return { missing, composeFiles: composeLayout.files, composeErrors: composeLayout.errors };
 }
 async function countModuleCandidatesInRepoPath(path) {
     if (!(await pathExists(path)))
@@ -96,7 +101,9 @@ function summaryText(status) {
         return 'No WPMoo environment detected.';
     if (status.kind === 'invalid_metadata')
         return 'Environment metadata is invalid.';
-    const prefix = status.missingCoreFiles.length > 0 || status.invalidSourceRepoPaths.length > 0
+    const prefix = status.missingCoreFiles.length > 0 ||
+        status.invalidSourceRepoPaths.length > 0 ||
+        status.composeErrors.length > 0
         ? 'Environment needs attention'
         : 'Environment ready';
     return `${prefix}: Odoo ${status.odooVersion}, source repos ${status.sourceRepoCount}, module candidates ${status.moduleCandidateCount}.`;
@@ -134,7 +141,7 @@ export async function getEnvironmentStatus(target) {
     for (const repoRoot of repoRoots) {
         moduleCandidateCount += await countModuleCandidatesInRepoPath(repoRoot);
     }
-    const missingFiles = await missingCoreFiles(target, odooVersion);
+    const { missing: missingFiles, composeFiles, composeErrors, } = await missingCoreFiles(target, odooVersion);
     let recommendedNextAction = 'Run npx @wpmoo/odoo doctor for deep checks or ./moo start.';
     if (invalidSourceRepoPaths.length > 0) {
         recommendedNextAction =
@@ -143,6 +150,9 @@ export async function getEnvironmentStatus(target) {
     else if (missingFiles.length > 0) {
         recommendedNextAction = 'Run npx @wpmoo/odoo reset, then npx @wpmoo/odoo doctor.';
     }
+    else if (composeErrors.length > 0) {
+        recommendedNextAction = 'Fix compose layout errors, then run npx @wpmoo/odoo doctor.';
+    }
     else if (sourceRepoPaths.length === 0) {
         recommendedNextAction = 'Run npx @wpmoo/odoo add-repo ...';
     }
@@ -155,6 +165,8 @@ export async function getEnvironmentStatus(target) {
         sourceRepoPaths,
         invalidSourceRepoPaths,
         moduleCandidateCount,
+        composeFiles,
+        composeErrors,
         missingCoreFiles: missingFiles,
         recommendedNextAction,
     };
@@ -177,6 +189,10 @@ export function renderEnvironmentStatus(status) {
     }
     lines.push(`Metadata: ${status.metadataPath}`);
     lines.push(`Odoo: ${status.odooVersion}`);
+    lines.push(`Compose files: ${status.composeFiles.length > 0 ? status.composeFiles.join(', ') : '(missing)'}`);
+    if (status.composeErrors.length > 0) {
+        lines.push(`Compose errors: ${status.composeErrors.join(', ')}`);
+    }
     lines.push(`Source repos: ${status.sourceRepoCount}`);
     lines.push(`Source repo paths: ${status.sourceRepoPaths.length > 0 ? status.sourceRepoPaths.join(', ') : '(none configured)'}`);
     if (status.invalidSourceRepoPaths.length > 0) {

package/dist/templates.js

@@ -22,29 +22,62 @@ function hasSourceRepos(options) {
 }
 function repositoryLayout(options) {
     const sourceRepoRows = hasSourceRepos(options)
-        ? options.sourceRepos.map((repo) => `│               ├── ${repo.path}/`).join('\n')
-        : '│               └── README.md';
-    return `${options.devRepo}/
-├── docker-compose_17.0.yml
-├── docker-compose_18.0.yml
-├── docker-compose_19.0.yml
-├── moo
-├── scripts/
-├── etc/
-├── odoo/
-│   └── custom/
-│       └── src/
-│           └── private/
+        ? options.sourceRepos
+            .map((repo, index) => {
+            const connector = index === options.sourceRepos.length - 1 ? '└──' : '├──';
+            return `│       │   │   ${connector} ${repo.path}/              # Project-owned addon source repository`;
+        })
+            .join('\n')
+        : '│       │   │   └── (add project-owned repos with ./moo add-repo)';
+    return `${options.devRepo}/                          # Development environment root
+├── compose.yaml                            # Base Docker Compose file
+├── compose/                                # Compose overlays for each workflow
+│   ├── dev.yaml                            # Local development services
+│   ├── debug.yaml                          # Debug tooling and debug-friendly settings
+│   ├── test.yaml                           # Test runner services and test database setup
+│   ├── stage.yaml                          # Staging-like deployment overlay
+│   ├── prod.yaml                           # Production deployment overlay
+│   ├── proxy.yaml                          # Reverse proxy / edge routing overlay
+│   └── tools.yaml                          # Optional maintenance and helper tools
+├── config/                                 # Runtime configuration mounted into containers
+│   ├── odoo/                               # Odoo server configuration
+│   │   ├── odoo.conf                       # Main Odoo configuration file
+│   │   └── requirements.txt                # Extra Python dependencies for the Odoo container
+│   └── logrotate/                          # Log rotation configuration
+│       └── odoo                            # Logrotate rules for Odoo logs
+├── resources/                              # Container-side helper resources
+│   └── odoo/                               # Resources specific to the Odoo service
+│       └── entrypoint.sh                   # Container startup script that discovers addons
+├── moo                                     # Local command hub shortcut
+├── scripts/                                # Shell scripts used by the local command hub
+├── odoo/                                   # Odoo workspace data and custom source tree
+│   └── custom/                             # Custom addon layer for this environment
+│       ├── src/                            # Source repository checkout root
+│       │   ├── private/                    # Project-owned/private addon repositories
 ${sourceRepoRows}
-├── docs/
-├── README.md
-└── AGENTS.md`;
+│       │   ├── oca/                        # OCA addon repositories
+│       │   └── external/                   # Non-OCA third-party addon repositories
+│       ├── patches/                        # Local patches for upstream repositories
+│       └── manifests/                      # Source manifests, locks, and pinned revisions
+├── docs/                                   # Project-specific documentation
+│   ├── appstore-release.md                 # Odoo App Store release checklist and notes
+│   └── compose.md                          # Compose layout and operations reference
+├── .env.example                            # Template for local environment variables
+├── README.md                               # This environment overview
+└── AGENTS.md                               # Agent instructions for this environment`;
 }
 function sourceRepoDocs(options) {
     if (!hasSourceRepos(options)) {
         return `This environment was scaffolded without source repository submodules.
 Add source repositories later from the cockpit or with \`npx @wpmoo/odoo add-repo\`.
-They will be added under \`odoo/custom/src/private\`.`;
+They can be organized under:
+
+\`odoo/custom/src/private\` for project-owned/private addon repositories,
+\`odoo/custom/src/oca\` for OCA repositories, and
+\`odoo/custom/src/external\` for non-OCA third-party repositories.
+
+Pinned external manifests and local patches should live under
+\`odoo/custom/manifests\` and \`odoo/custom/patches\` respectively.`;
     }
     return options.sourceRepos
         .map((repo) => `### ${repo.path}
@@ -61,6 +94,9 @@ Submodule path:
 odoo/custom/src/private/${repo.path}
 \`\`\`
 
+Note: If this repository is an OCA or third-party source, place it under
+\`odoo/custom/src/oca\` or \`odoo/custom/src/external\` according to your policy.
+
 Expected addon layout:
 
 \`\`\`text
@@ -137,7 +173,7 @@ function environmentKind() {
     return 'Docker Compose';
 }
 function repoDuplicationNote() {
-    return 'Keep these repositories under `odoo/custom/src/private`; the Compose entrypoint exposes discovered addons through `/mnt/wpmoo-addons`.';
+    return 'Keep source repositories under the relevant source directory (`private`, `oca`, or `external`); the Compose entrypoint exposes discovered addons through `/mnt/wpmoo-addons`.';
 }
 function verificationCommand(options) {
     const firstAddon = allAddons(options)[0] ?? options.product;
@@ -146,19 +182,25 @@ function verificationCommand(options) {
 function environmentUsageDocs(options) {
     return `## Docker Compose Notes
 
-This environment uses the standalone WPMoo Odoo Compose resource. Compose files
-are version-specific and static:
+This environment uses the compact WPMoo Compose layout:
 
 \`\`\`text
-docker-compose_17.0.yml
-docker-compose_18.0.yml
-docker-compose_19.0.yml
+compose.yaml
+compose/dev.yaml
+compose/stage.yaml
+compose/prod.yaml
+config/odoo/odoo.conf
+resources/odoo/entrypoint.sh
 \`\`\`
 
-If copied from the standalone resource, additional compose documentation is kept
-in \`docs/compose.md\`.
+Development uses compose.yaml plus compose/dev.yaml by default.
+Set WPMOO_ENV=stage or WPMOO_ENV=prod only after providing production-grade secrets and volumes.
+
+If copied from the standalone resource, additional compose notes are in
+\`docs/compose.md\`.
 
-Source repositories stay under \`odoo/custom/src/private\` when configured. At
+Source repositories stay under \`odoo/custom/src/{private,oca,external}\` when
+configured. At
 container startup, \`entrypoint.sh\` scans those repositories for addons and
 exposes them through \`/mnt/wpmoo-addons\`.
 
@@ -531,7 +573,8 @@ export function renderReadme(options) {
 Private ${environmentKind()} development environment for the ${title} product.
 
 This folder owns the development environment only. Product source code lives
-in source repository submodules under \`odoo/custom/src/private\` when source
+in source repository submodules under \`odoo/custom/src/private\`,
+\`odoo/custom/src/oca\`, or \`odoo/custom/src/external\` when source
 repositories are connected.
 
 ## Repository Layout
@@ -581,7 +624,8 @@ export function renderAgents(options) {
         ? options.sourceRepos.map((repo) => `- \`${repo.path}\`: \`${repo.url}\``).join('\n')
         : '- No source repositories are configured yet.';
     const sourceLayout = hasSourceRepos(options)
-        ? `Product repositories are Git submodules:
+        ? `Product repositories are Git submodules. They are listed under the private
+source directory below for this environment:
 
 \`\`\`text
 ${options.sourceRepos.map((repo) => `odoo/custom/src/private/${repo.path}`).join('\n')}

package/docs/external-resources.md

@@ -15,21 +15,33 @@ gh:wpmoo-org/odoo-skills
 
 ## Compose resource
 
-`wpmoo-org/odoo-docker-compose` uses static version-specific files:
+`wpmoo-org/odoo-docker-compose` now exposes a compact generated-environment payload
+under `resources/generated-env/`:
 
 ```text
-docker-compose_17.0.yml
-docker-compose_18.0.yml
-docker-compose_19.0.yml
+compose.yaml
+compose/dev.yaml
+compose/stage.yaml
+compose/prod.yaml
+config/odoo/odoo.conf
+resources/odoo/entrypoint.sh
 ```
 
-Standalone usage:
+`@wpmoo/odoo` prefers that compact payload first when copying compose assets.
+For pinned older refs that do not provide `resources/generated-env/`, the CLI
+falls back to the legacy repository-root layout (`docker-compose_<version>.yml`
+and related files) for compatibility.
+
+Standalone usage with the compact payload:
 
 ```bash
 git clone https://github.com/wpmoo-org/odoo-docker-compose
 cd odoo-docker-compose
-cp .env.example .env
-docker compose -f docker-compose_19.0.yml up -d
+mkdir -p ../my_product_dev
+cp -R resources/generated-env/. ../my_product_dev/
+cp .env.example ../my_product_dev/.env
+cd ../my_product_dev
+./scripts/up.sh
 ```
 
 WPMoo CLI usage with the default remote source:

package/docs/generated-environment-verification.md

@@ -18,14 +18,42 @@ not validate staging or production deployments.
 | Area | Contract | Primary command(s) |
 | --- | --- | --- |
 | Scaffold files and metadata | Generated environment includes expected files and `.wpmoo/odoo.json` metadata. | `npx @wpmoo/odoo create ...` |
-| Compose resource files | Required compose/version files, compose docs, and script set are present. | `npx @wpmoo/odoo create ...` |
+| Compose resource files | Compact compose layout is present (`compose.yaml` + environment overlays under `compose/`), plus config/resources/scripts. | `npx @wpmoo/odoo create ...` |
 | `./moo` delegation | `./moo` dispatches fixed daily actions to the matching script and preserves argument pass-through. | `./moo <action> ...` |
 | Doctor checks | Metadata, compose files, scripts, source repo paths, and local tooling checks behave as expected. | `npx @wpmoo/odoo doctor` or `./moo doctor` |
 | Source repo add/remove | Source repository registration and submodule lifecycle behave correctly. | `npx @wpmoo/odoo add-repo ...`, `npx @wpmoo/odoo remove-repo ...` |
 | Module add/remove | Module registration changes are applied to the selected source repo config. | `npx @wpmoo/odoo add-module ...`, `npx @wpmoo/odoo remove-module ...` |
-| Safe reset | Generated files are refreshed without deleting source module code. | `npx @wpmoo/odoo reset` |
+| Safe reset | Generated files are refreshed without deleting source module code. Legacy user-editable paths from older templates may remain and are reported for manual cleanup. | `npx @wpmoo/odoo reset` |
 | Snapshot/restore and lint/pot | These actions are delegated by `./moo` to compose scripts without extra package-side logic. | `./moo snapshot ...`, `./moo restore-snapshot ...`, `./moo lint`, `./moo pot ...` |
 
+## Compact compose checks
+
+Verify the generated environment includes at least:
+
+```text
+compose.yaml
+compose/dev.yaml
+compose/stage.yaml
+compose/prod.yaml
+config/odoo/odoo.conf
+resources/odoo/entrypoint.sh
+```
+
+Default local development uses `compose.yaml` plus `compose/dev.yaml`.
+`WPMOO_ENV=stage` or `WPMOO_ENV=prod` must only be used after production-grade
+secrets and volumes are configured.
+
+## Safe reset policy
+
+Safe reset intentionally avoids deleting user-editable legacy paths from old
+compose templates. Preview output must warn when these paths may remain:
+
+```text
+docs/assets/
+test/
+.github/
+```
+
 ## Local verification commands
 
 Run from the `wpmoo-odoo` repository root:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpmoo/odoo",
-  "version": "0.8.56",
+  "version": "0.8.58",
   "description": "WPMoo Odoo lifecycle tooling for development, staging, and production workflows.",
   "type": "module",
   "repository": {