container-superposition 0.1.6 → 0.1.8

package/dist/tool/questionnaire/composer.js

@@ -12,20 +12,311 @@ import { deepMerge, mergePackages, filterDependsOn, applyPortOffsetToEnv, } from
 import { generatePortsDocumentation } from '../utils/port-utils.js';
 import { generateServicesMarkdown, generateEnvLocalExample } from '../utils/services-export.js';
 import { appendGitignoreSection } from '../utils/gitignore.js';
+import { getTargetRule, resolveTargetFilePath, removeStaleTargetArtifacts, } from '../schema/target-rules.js';
+import { collectOverlayParameters, resolveParameters, substituteParameters, substituteParametersInObject, findUnresolvedTokens, redactSensitiveValues, } from '../utils/parameters.js';
 import { detectWarnings, generateTips, generateNextSteps, overlaysToServices, portsToPortInfo, } from '../utils/summary.js';
+import { resolveRepoPath } from '../utils/paths.js';
 // Get __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-// Resolve REPO_ROOT that works in both source and compiled output
-// When running from TypeScript sources (e.g. ts-node), __dirname is "<root>/tool/questionnaire"
-// When running from compiled JS in "dist/tool/questionnaire", __dirname is "<root>/dist/tool/questionnaire"
-const REPO_ROOT_CANDIDATES = [
-    path.join(__dirname, '..', '..'), // From source: tool/questionnaire -> root
-    path.join(__dirname, '..', '..', '..'), // From dist: dist/tool/questionnaire -> root
-];
-const REPO_ROOT = REPO_ROOT_CANDIDATES.find((candidate) => fs.existsSync(path.join(candidate, 'templates')) &&
-    fs.existsSync(path.join(candidate, 'overlays'))) ?? REPO_ROOT_CANDIDATES[0];
-const TEMPLATES_DIR = path.join(REPO_ROOT, 'templates');
+// Anchor for resolving the top-level templates directory.
+// In source layout: <repo>/tool/questionnaire -> anchor becomes <repo>/tool.
+//   path.basename('tool') === 'tool', so we go one level up to reach <repo>.
+// In compiled layout: <repo>/dist/tool/questionnaire -> anchor becomes <repo>/dist/tool.
+//   path.basename('tool') === 'tool', so we go one level up to <repo>/dist,
+//   then resolveRepoPath walks further up to find templates/ at the repo root.
+// NOTE: This check relies on the source directory being named 'tool'. If that changes,
+// update this constant accordingly.
+const TEMPLATES_ANCHOR_BASE = path.join(__dirname, '..', '..');
+const TEMPLATES_ANCHOR = path.basename(TEMPLATES_ANCHOR_BASE) === 'tool'
+    ? path.dirname(TEMPLATES_ANCHOR_BASE)
+    : TEMPLATES_ANCHOR_BASE;
+const TEMPLATES_DIR = resolveRepoPath('templates', TEMPLATES_ANCHOR);
+const REPO_ROOT = path.dirname(TEMPLATES_DIR);
+// ─── JetBrains support ────────────────────────────────────────────────────
+/**
+ * Language overlays that have a defined JetBrains backend mapping.
+ * Used both in getJetBrainsBackend() and in the language filter for
+ * generateJetBrainsArtifacts() — kept in one place for consistency.
+ */
+const JETBRAINS_SUPPORTED_LANGUAGES = new Set([
+    'nodejs',
+    'bun',
+    'python',
+    'mkdocs',
+    'go',
+    'dotnet',
+    'java',
+    'rust',
+]);
+/**
+ * Map a language overlay ID to the appropriate JetBrains backend identifier.
+ * Falls back to 'IntelliJIdea' when the language is unknown or unspecified.
+ *
+ * When multiple language overlays are selected, the first match in the
+ * provided array determines the backend; the array order reflects the user's
+ * selection order.
+ */
+function getJetBrainsBackend(languageOverlays) {
+    for (const lang of languageOverlays) {
+        switch (lang) {
+            case 'nodejs':
+            case 'bun':
+                return 'WebStorm';
+            case 'python':
+            case 'mkdocs':
+                return 'PyCharm';
+            case 'go':
+                return 'GoLand';
+            case 'dotnet':
+                return 'Rider';
+            case 'rust':
+                return 'RustRover';
+            case 'java':
+                return 'IntelliJIdea';
+        }
+    }
+    return 'IntelliJIdea';
+}
+/**
+ * Generate the content of .idea/.gitignore for a JetBrains project.
+ * Marks shared settings (run configurations, code style) as tracked and
+ * excludes user-local entries (workspace.xml, shelf/).
+ */
+function generateIdeaGitignore() {
+    return `# Default ignored files
+/shelf/
+/workspace.xml
+
+# Editor-based HTTP Client requests
+/httpRequests/
+
+# Datasource local storage
+/dataSources/
+/dataSources.local.xml
+`;
+}
+/**
+ * Generate a JetBrains run configuration XML for the given language overlay.
+ * Returns an object with the filename and XML content, or null when no
+ * configuration is defined for the supplied language.
+ */
+function generateRunConfiguration(lang) {
+    switch (lang) {
+        case 'nodejs':
+        case 'bun': {
+            const manager = lang === 'bun' ? 'bun' : 'npm';
+            const runScript = lang === 'bun' ? 'bun run dev' : 'npm run dev';
+            return {
+                filename: `${manager}_dev.xml`,
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="${runScript}" type="js.build_tools.npm" factoryName="npm">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="dev" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'mkdocs': {
+            return {
+                filename: 'mkdocs_serve.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="MkDocs: mkdocs serve" type="PythonConfigurationType" factoryName="Python">
+    <module name="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <envs>
+      <env name="PYTHONUNBUFFERED" value="1" />
+    </envs>
+    <option name="SDK_HOME" value="" />
+    <option name="SDK_NAME" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="IS_MODULE_SDK" value="false" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
+    <option name="SCRIPT_NAME" value="-m" />
+    <option name="MODULE_MODE" value="true" />
+    <option name="PARAMETERS" value="mkdocs serve" />
+    <option name="SHOW_COMMAND_LINE" value="false" />
+    <option name="EMULATE_TERMINAL" value="false" />
+    <option name="REDIRECT_INPUT" value="false" />
+    <option name="INPUT_FILE" value="" />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'python': {
+            return {
+                filename: 'python_main.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Python: main.py" type="PythonConfigurationType" factoryName="Python">
+    <module name="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <envs>
+      <env name="PYTHONUNBUFFERED" value="1" />
+    </envs>
+    <option name="SDK_HOME" value="" />
+    <option name="SDK_NAME" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="IS_MODULE_SDK" value="false" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
+    <option name="SCRIPT_NAME" value="$PROJECT_DIR$/main.py" />
+    <option name="PARAMETERS" value="" />
+    <option name="SHOW_COMMAND_LINE" value="false" />
+    <option name="EMULATE_TERMINAL" value="false" />
+    <option name="MODULE_MODE" value="false" />
+    <option name="REDIRECT_INPUT" value="false" />
+    <option name="INPUT_FILE" value="" />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'go': {
+            return {
+                filename: 'go_run.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Go: run ./..." type="GoApplicationRunConfiguration" factoryName="Go Application">
+    <module name="" />
+    <working_directory value="$PROJECT_DIR$" />
+    <parameters value="" />
+    <kind value="PACKAGE" />
+    <package value="./..." />
+    <directory value="$PROJECT_DIR$" />
+    <filePath value="$PROJECT_DIR$" />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'dotnet': {
+            return {
+                filename: 'dotnet_run.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name=".NET: dotnet run" type="DotNetRunConfiguration" factoryName="Run">
+    <option name="EXE_PATH" value="" />
+    <option name="PROGRAM_PARAMETERS" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="PASS_PARENT_ENVS" value="1" />
+    <option name="USE_EXTERNAL_CONSOLE" value="0" />
+    <option name="RUNTIME_ARGUMENTS" value="" />
+    <option name="PROJECT_PATH" value="$PROJECT_DIR$" />
+    <option name="TARGET_FRAMEWORK_ID" value="" />
+    <option name="RUNTIME_ID" value="" />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'java': {
+            return {
+                filename: 'java_run.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Java: Application" type="Application" factoryName="Application">
+    <option name="MAIN_CLASS_NAME" value="Main" />
+    <module name="" />
+    <option name="VM_PARAMETERS" value="" />
+    <option name="PROGRAM_PARAMETERS" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="ALTERNATIVE_JRE_PATH_ENABLED" value="false" />
+    <option name="ENABLE_SWING_INSPECTOR" value="false" />
+    <option name="ENV_VARIABLES" />
+    <option name="PASS_PARENT_ENVS" value="true" />
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'rust': {
+            return {
+                filename: 'rust_run.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Rust: cargo run" type="CargoCommandRunConfiguration" factoryName="Cargo Command">
+    <option name="command" value="run" />
+    <option name="workingDirectory" value="$PROJECT_DIR$" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Generate JetBrains IDE artifacts (.idea/.gitignore and run configurations)
+ * into the project root directory (parent of outputPath).
+ *
+ * Returns a list of project-root-relative paths that were written so the
+ * caller can register them and report what was generated.
+ */
+function generateJetBrainsArtifacts(projectRoot, languageOverlays) {
+    const ideaDir = path.join(projectRoot, '.idea');
+    const runConfigsDir = path.join(ideaDir, 'runConfigurations');
+    const written = [];
+    // Ensure directories exist
+    if (!fs.existsSync(ideaDir)) {
+        fs.mkdirSync(ideaDir, { recursive: true });
+    }
+    if (!fs.existsSync(runConfigsDir)) {
+        fs.mkdirSync(runConfigsDir, { recursive: true });
+    }
+    // Write .idea/.gitignore (only if not already present)
+    const gitignorePath = path.join(ideaDir, '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+        fs.writeFileSync(gitignorePath, generateIdeaGitignore());
+        written.push('.idea/.gitignore');
+    }
+    // Write run configurations for each recognised language overlay
+    const generated = [];
+    const skipped = [];
+    for (const lang of languageOverlays) {
+        const runConfig = generateRunConfiguration(lang);
+        if (!runConfig)
+            continue;
+        const xmlPath = path.join(runConfigsDir, runConfig.filename);
+        if (!fs.existsSync(xmlPath)) {
+            fs.writeFileSync(xmlPath, runConfig.content);
+            written.push(`.idea/runConfigurations/${runConfig.filename}`);
+            generated.push(lang);
+        }
+        else {
+            skipped.push(runConfig.filename);
+        }
+    }
+    if (generated.length > 0) {
+        console.log(chalk.dim(`   💡 Generated JetBrains run configuration(s) for: ${generated.join(', ')}`));
+    }
+    if (skipped.length > 0) {
+        console.log(chalk.dim(`   ⏭️  Skipped existing JetBrains run configuration(s): ${skipped.join(', ')}`));
+    }
+    if (languageOverlays.length === 0) {
+        console.log(chalk.dim(`   ℹ️  No language overlays selected — no JetBrains run configurations generated`));
+    }
+    return written;
+}
+// ─── End JetBrains support ────────────────────────────────────────────────
 /**
  * Merge packages from apt-get-packages feature
  */
@@ -82,6 +373,8 @@ function loadJson(filePath) {
 function getAllOverlayDefs(config) {
     return config.overlays;
 }
+/** ID for the meta overlay that expands to all available overlays */
+const META_OVERLAY_ID = 'all';
 /**
  * Resolve dependencies for a set of overlays
  * Returns the expanded list with dependencies and metadata about what was added
@@ -89,11 +382,22 @@ function getAllOverlayDefs(config) {
 function resolveDependencies(requestedOverlays, allOverlayDefs) {
     const overlayMap = new Map();
     allOverlayDefs.forEach((def) => overlayMap.set(def.id, def));
-    const resolved = new Set(requestedOverlays);
+    // Expand the meta overlay to all known non-meta overlay IDs
+    let expandedRequest = requestedOverlays;
+    if (requestedOverlays.includes(META_OVERLAY_ID)) {
+        const allIds = allOverlayDefs
+            .filter((def) => def.id !== META_OVERLAY_ID && def.category !== 'preset' && !def.hidden)
+            .map((def) => def.id);
+        expandedRequest = [
+            ...requestedOverlays.filter((id) => id !== META_OVERLAY_ID),
+            ...allIds.filter((id) => !requestedOverlays.includes(id)),
+        ];
+    }
+    const resolved = new Set(expandedRequest);
     const autoAdded = [];
     const resolutionReasons = [];
     // Resolve dependencies recursively
-    const toProcess = [...requestedOverlays];
+    const toProcess = [...expandedRequest];
     const processed = new Set();
     while (toProcess.length > 0) {
         const current = toProcess.shift();
@@ -236,7 +540,7 @@ function prepareOverlaysForGeneration(answers, overlaysDir) {
 /**
  * Generate superposition.json manifest
  */
-function generateManifest(outputPath, answers, overlays, autoResolved, containerName) {
+function generateManifest(outputPath, answers, overlays, autoResolved, containerName, effectiveTarget) {
     const toolVersion = getToolVersion();
     const manifest = {
         manifestVersion: CURRENT_MANIFEST_VERSION,
@@ -252,7 +556,14 @@ function generateManifest(outputPath, answers, overlays, autoResolved, container
         preset: answers.preset,
         presetChoices: answers.presetChoices,
         containerName,
+        target: effectiveTarget ?? answers.target ?? 'local',
     };
+    if (answers.minimal) {
+        manifest.minimal = true;
+    }
+    if (answers.editor && answers.editor !== 'vscode') {
+        manifest.editor = answers.editor;
+    }
     if (autoResolved.added.length > 0) {
         manifest.autoResolved = autoResolved;
     }
@@ -275,6 +586,23 @@ function generateManifest(outputPath, answers, overlays, autoResolved, container
         console.log(chalk.cyan(`   ℹ️  Used preset: ${answers.preset}`));
     }
 }
+/**
+ * Validate that an import path is within the allowed .shared/ directory (path traversal prevention).
+ * Returns an error message if invalid, or null if the path is safe.
+ */
+function validateImportPath(importPath, overlaysDir) {
+    // FR-006: All imports must start with '.shared/'
+    if (!importPath.startsWith('.shared/')) {
+        return `Import path must begin with '.shared/': ${importPath}`;
+    }
+    // Normalize both the resolved path and the allowed base to detect traversal
+    const sharedBase = path.resolve(overlaysDir, '.shared');
+    const resolved = path.resolve(overlaysDir, importPath);
+    if (!resolved.startsWith(sharedBase + path.sep) && resolved !== sharedBase) {
+        return `Import path resolves outside '.shared/' directory (path traversal rejected): ${importPath}`;
+    }
+    return null;
+}
 /**
  * Load and resolve imports from shared files for an overlay
  */
@@ -294,23 +622,30 @@ function loadImportsForOverlay(overlayName, overlaysDir) {
             manifest.imports.length === 0) {
             return importedConfig;
         }
-        // Process each import
+        // Process each import in declaration order
         for (const importPath of manifest.imports) {
+            // FR-006: Reject path traversal attempts
+            const traversalError = validateImportPath(importPath, overlaysDir);
+            if (traversalError) {
+                throw new Error(`Path traversal rejected in overlay '${overlayName}': ${traversalError}`);
+            }
             const fullImportPath = path.join(overlaysDir, importPath);
             if (!fs.existsSync(fullImportPath)) {
-                console.warn(chalk.yellow(`⚠️  Import not found: ${importPath} (for overlay: ${overlayName})`));
-                continue;
+                // FR-007: Missing imports are errors, not warnings
+                throw new Error(`Import not found: '${importPath}' (referenced by overlay: ${overlayName})`);
             }
             // Determine file type and merge appropriately
             const ext = path.extname(importPath).toLowerCase();
             if (ext === '.json') {
                 // JSON files are merged as devcontainer patches
+                console.log(chalk.dim(`   📎 Applying shared import: ${importPath}`));
                 const importedPatch = loadJson(fullImportPath);
                 importedConfig = deepMerge(importedConfig, importedPatch);
             }
             else if (ext === '.yaml' || ext === '.yml') {
                 // YAML files are loaded and merged as devcontainer patches
                 try {
+                    console.log(chalk.dim(`   📎 Applying shared import: ${importPath}`));
                     const yamlContent = fs.readFileSync(fullImportPath, 'utf8');
                     const importedPatch = yaml.load(yamlContent);
                     if (importedPatch && typeof importedPatch === 'object') {
@@ -318,13 +653,25 @@ function loadImportsForOverlay(overlayName, overlaysDir) {
                     }
                 }
                 catch (error) {
-                    console.warn(chalk.yellow(`⚠️  Failed to parse YAML import: ${importPath}`));
+                    throw new Error(`Failed to parse YAML import '${importPath}' (overlay: ${overlayName}): ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
-            // .env files are handled separately during env merging
+            else if (ext === '.env') {
+                // .env files are handled separately during env merging — skip here
+                console.log(chalk.dim(`   📎 Shared .env import noted: ${importPath}`));
+            }
+            else {
+                // FR-007: Unsupported file types are errors
+                throw new Error(`Unsupported import type '${ext}' for '${importPath}' (overlay: ${overlayName}). Supported types: .json, .yaml, .yml, .env`);
+            }
         }
     }
     catch (error) {
+        if (error instanceof Error) {
+            // Fail fast on any error while loading imports so configuration issues are not silently ignored
+            throw error;
+        }
+        // Non-Error throwables are unexpected; log a warning but continue
         console.warn(chalk.yellow(`⚠️  Failed to load imports for overlay: ${overlayName}`));
     }
     return importedConfig;
@@ -492,6 +839,164 @@ function copyOverlayFiles(outputPath, overlayName, registry, overlaysDir) {
         console.log(chalk.dim(`   📋 Copied ${copiedFiles} file(s) from ${chalk.cyan(overlayName)}`));
     }
 }
+const PROJECT_ENV_REFERENCE_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-[^}]*)?\}/g;
+function parseSimpleEnvFile(content) {
+    const env = {};
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const match = trimmed.match(/^([^=]+)=(.*)$/);
+        if (!match) {
+            continue;
+        }
+        env[match[1].trim()] = match[2].trim();
+    }
+    return env;
+}
+function loadEnvFileIfExists(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    return parseSimpleEnvFile(fs.readFileSync(filePath, 'utf8'));
+}
+function resolveProjectEnvTarget(entry, stack) {
+    const target = entry.target ?? 'auto';
+    if (target === 'remoteEnv') {
+        return 'remoteEnv';
+    }
+    if (target === 'composeEnv') {
+        if (stack !== 'compose') {
+            throw new Error('Project env target "composeEnv" requires stack: compose because no docker-compose.yml is generated for plain stacks');
+        }
+        return 'composeEnv';
+    }
+    return stack === 'compose' ? 'composeEnv' : 'remoteEnv';
+}
+function resolveRootEnvReferences(value, rootEnv) {
+    return value.replace(PROJECT_ENV_REFERENCE_PATTERN, (match, name) => {
+        if (rootEnv[name] !== undefined) {
+            return rootEnv[name];
+        }
+        const defaultMatch = match.match(/^\$\{[A-Za-z_][A-Za-z0-9_]*:-([^}]*)\}$/);
+        return defaultMatch ? defaultMatch[1] : match;
+    });
+}
+function hasUnresolvedProjectEnvReference(value) {
+    PROJECT_ENV_REFERENCE_PATTERN.lastIndex = 0;
+    const result = PROJECT_ENV_REFERENCE_PATTERN.test(value);
+    PROJECT_ENV_REFERENCE_PATTERN.lastIndex = 0;
+    return result;
+}
+function buildResolvedProjectRemoteEnvEntries(projectEnv, stack, rootEnv) {
+    const entries = {};
+    for (const [key, entry] of Object.entries(projectEnv ?? {})) {
+        if (resolveProjectEnvTarget(entry, stack) !== 'remoteEnv') {
+            continue;
+        }
+        entries[key] = resolveRootEnvReferences(entry.value, rootEnv ?? {});
+    }
+    return entries;
+}
+function buildComposeProjectEnvInterpolationEntries(projectEnv, stack) {
+    const entries = {};
+    for (const [key, entry] of Object.entries(projectEnv ?? {})) {
+        if (resolveProjectEnvTarget(entry, stack) !== 'composeEnv') {
+            continue;
+        }
+        entries[key] = `\${${key}}`;
+    }
+    return entries;
+}
+function buildComposeProjectRemoteEnvRefs(projectEnv, stack) {
+    const entries = {};
+    for (const [key, entry] of Object.entries(projectEnv ?? {})) {
+        if (resolveProjectEnvTarget(entry, stack) !== 'composeEnv') {
+            continue;
+        }
+        entries[key] = `\${containerEnv:${key}}`;
+    }
+    return entries;
+}
+function materializeComposeProjectEnvValues(projectEnv, stack, rootEnv) {
+    const entries = {};
+    for (const [key, entry] of Object.entries(projectEnv ?? {})) {
+        if (resolveProjectEnvTarget(entry, stack) !== 'composeEnv') {
+            continue;
+        }
+        const resolvedValue = resolveRootEnvReferences(entry.value, rootEnv);
+        // Leave unresolved variables to shell/docker-compose fallback instead of
+        // persisting placeholder syntax into .devcontainer/.env.
+        if (hasUnresolvedProjectEnvReference(resolvedValue)) {
+            continue;
+        }
+        entries[key] = resolvedValue;
+    }
+    return entries;
+}
+function applyProjectEnvToDevcontainer(config, projectEnv, stack, rootEnv) {
+    const remoteEnv = {
+        ...buildResolvedProjectRemoteEnvEntries(projectEnv, stack, rootEnv),
+        ...buildComposeProjectRemoteEnvRefs(projectEnv, stack),
+    };
+    if (Object.keys(remoteEnv).length === 0) {
+        return config;
+    }
+    console.log(chalk.dim(`   🌱 Applying project env to remoteEnv`));
+    return deepMerge(config, { remoteEnv });
+}
+function mergeComposeEnvFile(outputPath, entries) {
+    if (Object.keys(entries).length === 0) {
+        return false;
+    }
+    const envPath = path.join(outputPath, '.env');
+    const originalContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8') : '';
+    const lines = originalContent === '' ? [] : originalContent.replace(/\n$/, '').split('\n');
+    const indexByKey = new Map();
+    lines.forEach((line, index) => {
+        const match = line.match(/^([^#=\s][^=]*)=(.*)$/);
+        if (match) {
+            indexByKey.set(match[1].trim(), index);
+        }
+    });
+    let changed = false;
+    let insertedSpacer = false;
+    for (const [key, value] of Object.entries(entries)) {
+        const rendered = `${key}=${value}`;
+        const existingIndex = indexByKey.get(key);
+        if (existingIndex !== undefined) {
+            if (lines[existingIndex] !== rendered) {
+                lines[existingIndex] = rendered;
+                changed = true;
+            }
+            continue;
+        }
+        if (lines.length > 0 && !insertedSpacer && lines[lines.length - 1] !== '') {
+            lines.push('');
+            insertedSpacer = true;
+        }
+        lines.push(rendered);
+        indexByKey.set(key, lines.length - 1);
+        changed = true;
+    }
+    if (!changed && originalContent !== '') {
+        return false;
+    }
+    fs.writeFileSync(envPath, `${lines.join('\n')}\n`);
+    return true;
+}
+function materializeComposeProjectEnvFile(outputPath, projectEnv, stack, rootEnv) {
+    if (stack !== 'compose') {
+        return false;
+    }
+    const materializedEntries = materializeComposeProjectEnvValues(projectEnv, stack, rootEnv);
+    if (!mergeComposeEnvFile(outputPath, materializedEntries)) {
+        return false;
+    }
+    console.log(chalk.dim(`   🔁 Materialized ${Object.keys(materializedEntries).length} project env value(s) into .devcontainer/.env for docker-compose`));
+    return true;
+}
 /**
  * Merge .env.example files from all selected overlays
  */
@@ -510,21 +1015,33 @@ function mergeEnvExamples(outputPath, overlays, overlaysDir, portOffset, glueCon
                 const manifest = yaml.load(manifestContent);
                 if (manifest.imports && Array.isArray(manifest.imports)) {
                     for (const importPath of manifest.imports) {
+                        // FR-006: Reject path traversal
+                        const traversalError = validateImportPath(importPath, overlaysDir);
+                        if (traversalError) {
+                            throw new Error(`Path traversal rejected in overlay '${overlay}': ${traversalError}`);
+                        }
                         const ext = path.extname(importPath).toLowerCase();
                         if (ext === '.env') {
                             const fullImportPath = path.join(overlaysDir, importPath);
                             if (fs.existsSync(fullImportPath)) {
+                                console.log(chalk.dim(`   📎 Merging shared .env import: ${importPath}`));
                                 const content = fs.readFileSync(fullImportPath, 'utf-8').trim();
                                 if (content) {
-                                    envSections.push(`# Imported from ${importPath}\n${content}`);
+                                    envSections.push(`# from ${importPath}\n${content}`);
                                 }
                             }
+                            else {
+                                throw new Error(`Import not found: '${importPath}' (referenced by overlay: ${overlay})`);
+                            }
                         }
                     }
                 }
             }
             catch (error) {
-                // Ignore errors reading manifest
+                if (error instanceof Error) {
+                    // Fail fast on import errors so .env import violations are not silently ignored
+                    throw error;
+                }
             }
         }
         // Then add the overlay's own .env.example
@@ -641,25 +1158,166 @@ function applyGlueConfig(outputPath, glueConfig, presetName, fileRegistry) {
     }
     console.log('');
 }
+/**
+ * Parse the effective host port from any docker-compose port binding format:
+ *   "8081:8081", "127.0.0.1:8081:8081", "${VAR:-8081}:8081", 8081, {published:8081}
+ */
+function parseHostPortFromBinding(binding) {
+    if (typeof binding === 'number') {
+        // A bare number in docker-compose ports means container port → random host port.
+        // There is no deterministic host port to conflict on, so treat as "no host port".
+        return null;
+    }
+    if (typeof binding === 'object' && binding !== null) {
+        const pub = binding.published;
+        if (pub == null)
+            return null;
+        if (typeof pub === 'number')
+            return pub;
+        const m = String(pub).match(/^(\d+)$/);
+        return m ? parseInt(m[1], 10) : null;
+    }
+    if (typeof binding !== 'string')
+        return null;
+    // "${VAR:-8081}:..." — extract default
+    const envMatch = binding.match(/^\$\{[^}]+:-(\d+)\}/);
+    if (envMatch)
+        return parseInt(envMatch[1], 10);
+    const parts = binding.split(':');
+    if (parts.length === 3) {
+        const n = parseInt(parts[1], 10);
+        return isNaN(n) ? null : n;
+    }
+    if (parts.length === 2) {
+        const n = parseInt(parts[0], 10);
+        return isNaN(n) ? null : n;
+    }
+    // Single segment: "8081" string — same as bare number, random host port.
+    return null;
+}
+/**
+ * Replace the host port in a binding, preserving its format.
+ */
+function replaceHostPortInBinding(binding, newPort) {
+    if (typeof binding === 'number')
+        return `${newPort}:${binding}`;
+    if (typeof binding === 'object' && binding !== null)
+        return { ...binding, published: newPort };
+    if (typeof binding !== 'string')
+        return binding;
+    // "${VAR:-8081}:container"
+    const replaced = binding.replace(/^(\$\{[^:}]+:-)(\d+)(\})/, `$1${newPort}$3`);
+    if (replaced !== binding)
+        return replaced;
+    const parts = binding.split(':');
+    if (parts.length === 3)
+        return `${parts[0]}:${newPort}:${parts[2]}`;
+    if (parts.length === 2)
+        return `${newPort}:${parts[1]}`;
+    return `${newPort}:${binding}`;
+}
+/**
+ * Detect and auto-resolve host port conflicts in a merged services map.
+ * The first service that claims a port keeps it; later ones are bumped to the
+ * next free port. Returns a list of remappings made (for logging).
+ */
+function resolveDockerComposePortConflicts(services) {
+    const remappings = [];
+    // Build port → [serviceNames] map
+    const portOwners = new Map();
+    const allocatedPorts = new Set();
+    for (const [serviceName, service] of Object.entries(services)) {
+        if (!Array.isArray(service?.ports))
+            continue;
+        for (const binding of service.ports) {
+            const p = parseHostPortFromBinding(binding);
+            if (p == null)
+                continue;
+            allocatedPorts.add(p);
+            if (!portOwners.has(p))
+                portOwners.set(p, serviceName);
+        }
+    }
+    function nextFreePort(start) {
+        let p = start + 1;
+        while (allocatedPorts.has(p))
+            p++;
+        return p;
+    }
+    for (const [serviceName, service] of Object.entries(services)) {
+        if (!Array.isArray(service?.ports))
+            continue;
+        const newBindings = [];
+        for (const binding of service.ports) {
+            const p = parseHostPortFromBinding(binding);
+            if (p != null && portOwners.get(p) !== serviceName) {
+                // This service lost the port; remap it
+                const newPort = nextFreePort(p);
+                allocatedPorts.add(newPort);
+                portOwners.set(newPort, serviceName);
+                remappings.push({ service: serviceName, originalPort: p, newPort });
+                newBindings.push(replaceHostPortInBinding(binding, newPort));
+            }
+            else {
+                newBindings.push(binding);
+            }
+        }
+        service.ports = newBindings;
+    }
+    return remappings;
+}
 /**
  * Merge docker-compose.yml files from base and overlays into a single file
  */
-function mergeDockerComposeFiles(outputPath, baseStack, overlays, overlaysDir, portOffset, customImage) {
+function mergeDockerComposeFiles(outputPath, baseStack, overlays, overlaysDir, portOffset, customImage, projectEnv) {
     const composeFiles = [];
     // Add base docker-compose if exists
     const baseComposePath = path.join(TEMPLATES_DIR, baseStack, '.devcontainer', 'docker-compose.yml');
     if (fs.existsSync(baseComposePath)) {
         composeFiles.push(baseComposePath);
     }
-    // Add overlay docker-compose files
+    // Add overlay docker-compose files, interleaving any compose_imports before each overlay's own file
     for (const overlay of overlays) {
+        // First load any compose_imports for this overlay (shared fragments applied before own file)
+        const manifestPath = path.join(overlaysDir, overlay, 'overlay.yml');
+        if (fs.existsSync(manifestPath)) {
+            try {
+                const manifestContent = fs.readFileSync(manifestPath, 'utf8');
+                const manifest = yaml.load(manifestContent);
+                if (manifest.compose_imports && Array.isArray(manifest.compose_imports)) {
+                    for (const importPath of manifest.compose_imports) {
+                        const traversalError = validateImportPath(importPath, overlaysDir);
+                        if (traversalError) {
+                            throw new Error(`compose_import path traversal rejected in overlay '${overlay}': ${traversalError}`);
+                        }
+                        const fullImportPath = path.join(overlaysDir, importPath);
+                        if (!fs.existsSync(fullImportPath)) {
+                            throw new Error(`compose_import not found: '${importPath}' (referenced by overlay: ${overlay})`);
+                        }
+                        const ext = path.extname(importPath).toLowerCase();
+                        if (ext !== '.yml' && ext !== '.yaml') {
+                            throw new Error(`compose_import must be a .yml or .yaml file: '${importPath}' (overlay: ${overlay})`);
+                        }
+                        console.log(chalk.dim(`   📎 Applying shared compose fragment: ${importPath}`));
+                        composeFiles.push(fullImportPath);
+                    }
+                }
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    throw error;
+                }
+                // Non-Error throwables are unexpected; wrap and re-throw so compose_imports failures always fail fast
+                throw new Error(`Unexpected error loading compose_imports for overlay '${overlay}': ${String(error)}`);
+            }
+        }
         const overlayComposePath = path.join(overlaysDir, overlay, 'docker-compose.yml');
         if (fs.existsSync(overlayComposePath)) {
             composeFiles.push(overlayComposePath);
         }
     }
     if (composeFiles.length === 0) {
-        return; // No docker-compose files to merge
+        return []; // No docker-compose files to merge
     }
     // Merge all compose files
     let merged = {
@@ -690,6 +1348,11 @@ function mergeDockerComposeFiles(outputPath, baseStack, overlays, overlaysDir, p
     }
     // Ensure devcontainer service has an image
     if (merged.services.devcontainer) {
+        const composeEnv = buildComposeProjectEnvInterpolationEntries(projectEnv, baseStack);
+        if (Object.keys(composeEnv).length > 0) {
+            merged.services.devcontainer.environment = deepMerge(merged.services.devcontainer.environment ?? {}, composeEnv);
+            console.log(chalk.dim(`   🌱 Applying project env to docker-compose devcontainer service`));
+        }
         if (customImage) {
             // Apply custom base image if specified
             merged.services.devcontainer.image = customImage;
@@ -719,6 +1382,15 @@ function mergeDockerComposeFiles(outputPath, baseStack, overlays, overlaysDir, p
         delete merged.volumes;
     if (Object.keys(merged.networks).length === 0)
         delete merged.networks;
+    // Auto-resolve host port conflicts across composed services
+    const portRemappings = resolveDockerComposePortConflicts(merged.services);
+    if (portRemappings.length > 0) {
+        console.log(chalk.yellow('\n⚠️  Host port conflicts detected and auto-resolved:'));
+        for (const { service, originalPort, newPort } of portRemappings) {
+            console.log(chalk.yellow(`   • ${service}: host port ${originalPort} → ${newPort}`));
+        }
+        console.log();
+    }
     // Write combined docker-compose.yml
     const outputComposePath = path.join(outputPath, 'docker-compose.yml');
     const yamlContent = yaml.dump(merged, {
@@ -728,6 +1400,7 @@ function mergeDockerComposeFiles(outputPath, baseStack, overlays, overlaysDir, p
     });
     fs.writeFileSync(outputComposePath, yamlContent);
     console.log(chalk.dim(`   🐳 Created combined docker-compose.yml with ${serviceNames.length} service(s)`));
+    return portRemappings;
 }
 /**
  * Apply custom devcontainer patch from .devcontainer/custom/
@@ -1049,17 +1722,60 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
         }
     }
     const overlays = orderedOverlays;
-    // 5. Create output directory and file registry for cleanup
+    // 5b. Resolve overlay parameters ({{cs.KEY}} substitution)
+    // Collect parameter declarations from all selected overlays
+    const declaredParams = collectOverlayParameters(overlays, allOverlayDefs);
+    const { values: resolvedParams, missingRequired, unknownSupplied, } = resolveParameters(declaredParams, answers.overlayParameters ?? {});
+    if (missingRequired.length > 0) {
+        throw new Error(`Missing required overlay parameters: ${missingRequired.join(', ')}. ` +
+            `Provide values in superposition.yml under the parameters: section, ` +
+            `or via --param KEY=VALUE on the command line.`);
+    }
+    if (unknownSupplied.length > 0) {
+        console.warn(chalk.yellow(`   ⚠️  Unknown overlay parameters (not declared by any selected overlay): ${unknownSupplied.join(', ')}`));
+    }
+    const hasResolvedParams = Object.keys(resolvedParams).length > 0;
+    // Log resolved parameter values (sensitive values are redacted)
+    if (hasResolvedParams) {
+        const displayValues = redactSensitiveValues(resolvedParams, declaredParams);
+        console.log(chalk.dim(`   ⚙️  Overlay parameters:`));
+        for (const [k, v] of Object.entries(displayValues)) {
+            console.log(chalk.dim(`      ${k}=${v}`));
+        }
+    }
     const outputPath = path.resolve(answers.outputPath);
+    const projectRoot = path.dirname(outputPath);
     const fileRegistry = new FileRegistry();
+    const rootEnv = loadEnvFileIfExists(path.join(projectRoot, '.env'));
     if (!fs.existsSync(outputPath)) {
         fs.mkdirSync(outputPath, { recursive: true });
     }
+    // 5a. Remove stale project-root artifacts from a previous target run
+    const manifestPath_existing = path.join(outputPath, 'superposition.json');
+    let manifestTarget;
+    if (fs.existsSync(manifestPath_existing)) {
+        try {
+            const existingManifest = JSON.parse(fs.readFileSync(manifestPath_existing, 'utf-8'));
+            manifestTarget = existingManifest.target;
+        }
+        catch {
+            // If manifest is unreadable, skip stale cleanup gracefully
+        }
+    }
+    // When answers.target is undefined (e.g. regen without --target), fall back to the
+    // target recorded in the existing manifest so the correct artifacts are reproduced.
+    const activeTarget = answers.target ?? manifestTarget ?? 'local';
+    const previousTarget = manifestTarget ?? 'local';
+    if (previousTarget !== activeTarget) {
+        removeStaleTargetArtifacts(previousTarget, activeTarget, projectRoot);
+        console.log(chalk.dim(`   🧹 Removed stale target artifacts for previous target '${previousTarget}'`));
+    }
     // 6. Apply overlays
     for (const overlay of overlays) {
         console.log(chalk.dim(`   🔧 Applying overlay: ${chalk.cyan(overlay)}`));
         config = applyOverlay(config, overlay, actualOverlaysDir);
     }
+    config = applyProjectEnvToDevcontainer(config, answers.projectEnv, answers.stack, rootEnv);
     // 7. Copy template files (docker-compose, scripts, etc.)
     const entries = fs.readdirSync(templatePath);
     for (const entry of entries) {
@@ -1096,13 +1812,25 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
     // 9. Merge runServices array in correct order
     mergeRunServices(config, overlays, actualOverlaysDir);
     // 11. Merge docker-compose files into single combined file
+    let composePortRemappings = [];
     if (answers.stack === 'compose') {
         const customImage = config._customImage;
-        mergeDockerComposeFiles(outputPath, answers.stack, overlays, actualOverlaysDir, answers.portOffset, customImage);
+        composePortRemappings = mergeDockerComposeFiles(outputPath, answers.stack, overlays, actualOverlaysDir, answers.portOffset, customImage, answers.projectEnv);
         // Update devcontainer.json to reference the combined file
         if (config.dockerComposeFile) {
             config.dockerComposeFile = 'docker-compose.yml';
         }
+        // Apply parameter substitution to the merged docker-compose.yml
+        if (hasResolvedParams) {
+            const composePath = path.join(outputPath, 'docker-compose.yml');
+            if (fs.existsSync(composePath)) {
+                const original = fs.readFileSync(composePath, 'utf8');
+                const substituted = substituteParameters(original, resolvedParams);
+                if (substituted !== original) {
+                    fs.writeFileSync(composePath, substituted);
+                }
+            }
+        }
     }
     // Apply port offset to devcontainer.json if specified
     if (answers.portOffset) {
@@ -1131,24 +1859,62 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
     if (answers.editor === 'none' || answers.editor === 'jetbrains') {
         // Remove VS Code customizations
         if (config.customizations?.vscode) {
-            if (answers.editor === 'none') {
-                delete config.customizations.vscode;
-                console.log(chalk.dim(`   🎨 Editor profile 'none': Removed VS Code customizations`));
-            }
-            else if (answers.editor === 'jetbrains') {
-                // For JetBrains, remove VS Code customizations (future: could add JetBrains-specific settings)
-                delete config.customizations.vscode;
-                console.log(chalk.dim(`   🎨 Editor profile 'jetbrains': Removed VS Code customizations`));
-            }
+            delete config.customizations.vscode;
+            const profileLabel = answers.editor === 'none' ? 'none' : 'jetbrains';
+            console.log(chalk.dim(`   🎨 Editor profile '${profileLabel}': Removed VS Code customizations`));
             // Clean up empty customizations object
             if (config.customizations && Object.keys(config.customizations).length === 0) {
                 delete config.customizations;
             }
         }
     }
+    // Add JetBrains-specific devcontainer.json customizations and generate .idea/ artifacts
+    if (answers.editor === 'jetbrains') {
+        const selectedLanguages = answers.language ?? [];
+        const languageOverlays = selectedLanguages.filter((lang) => JETBRAINS_SUPPORTED_LANGUAGES.has(lang));
+        if (languageOverlays.length === 0 && selectedLanguages.length > 0) {
+            const selectedLabel = selectedLanguages.join(', ');
+            console.log(chalk.yellow(`   ⚠️  No supported JetBrains language overlays selected (selected: ${selectedLabel})`));
+        }
+        const backend = getJetBrainsBackend(languageOverlays);
+        // Add customizations.jetbrains block to devcontainer.json
+        if (!config.customizations) {
+            config.customizations = {};
+        }
+        config.customizations.jetbrains = { backend };
+        console.log(chalk.dim(`   🧠 Editor profile 'jetbrains': Set backend to '${backend}'`));
+        // Generate .idea/ artifacts in the project root
+        console.log(chalk.cyan('\n💡 Generating JetBrains project artifacts...'));
+        const jetbrainsFiles = generateJetBrainsArtifacts(projectRoot, languageOverlays);
+        for (const relPath of jetbrainsFiles) {
+            console.log(chalk.dim(`   📄 Created ${relPath} at project root`));
+        }
+    }
+    // 11b. Apply target-specific devcontainer.json patch
+    const targetRule = getTargetRule(activeTarget);
+    const overlayMetadataMapForTarget = new Map(allOverlayDefs.map((o) => [o.id, o]));
+    const targetCtx = {
+        overlays,
+        overlayMetadata: overlayMetadataMapForTarget,
+        portOffset: answers.portOffset ?? 0,
+        stack: answers.stack,
+        outputPath,
+        projectRoot,
+    };
+    const targetPatch = targetRule.devcontainerPatch(targetCtx);
+    if (Object.keys(targetPatch).length > 0) {
+        config = deepMerge(config, targetPatch);
+        console.log(chalk.dim(`   🎯 Applied ${activeTarget} target patch to devcontainer.json`));
+    }
     // 12. Write merged devcontainer.json
+    // Apply parameter substitution to the config object (before JSON.stringify) so that
+    // any JSON-special characters in parameter values are properly escaped by JSON.stringify.
     const configPath = path.join(outputPath, 'devcontainer.json');
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+    const finalConfig = hasResolvedParams
+        ? substituteParametersInObject(config, resolvedParams)
+        : config;
+    const devcontainerContent = JSON.stringify(finalConfig, null, 2) + '\n';
+    fs.writeFileSync(configPath, devcontainerContent);
     fileRegistry.addFile('devcontainer.json');
     console.log(chalk.dim(`   📝 Wrote devcontainer.json`));
     // Apply custom docker-compose patch (after writing base docker-compose.yml)
@@ -1156,13 +1922,39 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
         applyCustomDockerComposePatch(outputPath, customPatches);
     }
     // 13. Generate superposition.json manifest
-    generateManifest(outputPath, answers, overlays, autoResolved, answers.containerName || config.name);
+    generateManifest(outputPath, answers, overlays, autoResolved, answers.containerName || config.name, activeTarget);
     fileRegistry.addFile('superposition.json');
     // 14. Merge .env.example files from overlays and apply glue config environment variables
     const envCreated = mergeEnvExamples(outputPath, overlays, actualOverlaysDir, answers.portOffset, answers.presetGlueConfig, answers.preset);
     if (envCreated) {
         fileRegistry.addFile('.env.example');
     }
+    // Apply parameter substitution to .env.example
+    // This must happen after mergeEnvExamples but before any consumer of .env reads it,
+    // because mergeEnvExamples may have written {{cs.*}} tokens into .env.example.
+    // We also regenerate .env (the port-offset copy) from the substituted content so that
+    // applyPortOffsetToEnv can correctly match numeric port values that were previously
+    // hidden behind {{cs.POSTGRES_PORT}} tokens.
+    if (hasResolvedParams) {
+        const envExamplePath = path.join(outputPath, '.env.example');
+        if (fs.existsSync(envExamplePath)) {
+            const original = fs.readFileSync(envExamplePath, 'utf8');
+            const substituted = substituteParameters(original, resolvedParams);
+            if (substituted !== original) {
+                fs.writeFileSync(envExamplePath, substituted);
+                // Regenerate .env from the substituted content when a port offset is active.
+                // mergeEnvExamples already wrote .env from the pre-substitution content, so
+                // the port offset was applied to unresolved tokens (e.g. {{cs.POSTGRES_PORT}})
+                // that had no numeric value to match — we must regenerate .env now that the
+                // tokens have been replaced with real numeric port values.
+                if (answers.portOffset) {
+                    const envPath = path.join(outputPath, '.env');
+                    const offsetContent = applyPortOffsetToEnv(substituted, answers.portOffset);
+                    fs.writeFileSync(envPath, offsetContent);
+                }
+            }
+        }
+    }
     // Apply custom environment variables (after .env.example is created)
     if (customPatches) {
         const customEnvCreated = applyCustomEnvironment(outputPath, customPatches);
@@ -1171,6 +1963,7 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
             fileRegistry.addFile('.env.example');
         }
     }
+    materializeComposeProjectEnvFile(outputPath, answers.projectEnv, answers.stack, rootEnv);
     // 14b. Merge .gitignore files from overlays into project root .gitignore
     // Note: .gitignore lives at the project root (parent of outputPath), not inside outputPath,
     // so it is intentionally NOT added to fileRegistry (cleanupStaleFiles must not touch it).
@@ -1209,6 +2002,19 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
     if (shouldGeneratePortsDocumentation) {
         console.log(chalk.cyan('\n📡 Generating ports documentation...'));
         portsDoc = generatePortsDocumentation(selectedOverlayMetadata, portOffset, envVars);
+        // Propagate host-port conflict remappings into the generated docs so that
+        // ports.json and services.md reflect the actual ports in docker-compose.yml.
+        if (composePortRemappings.length > 0) {
+            // Build a lookup map: original (post-offset) host port → remapped host port.
+            const remapByOriginal = new Map(composePortRemappings.map(({ originalPort, newPort }) => [originalPort, newPort]));
+            portsDoc = {
+                ...portsDoc,
+                ports: portsDoc.ports.map((p) => {
+                    const remapped = remapByOriginal.get(p.actualPort);
+                    return remapped !== undefined ? { ...p, actualPort: remapped } : p;
+                }),
+            };
+        }
         const portsPath = path.join(outputPath, 'ports.json');
         fs.writeFileSync(portsPath, JSON.stringify(portsDoc, null, 2) + '\n');
         fileRegistry.addFile('ports.json');
@@ -1236,12 +2042,63 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
     const envLocalContent = generateEnvLocalExample(selectedOverlayMetadata, actualOverlaysDir, portOffset);
     if (envLocalContent) {
         const envLocalPath = path.join(outputPath, 'env.local.example');
-        fs.writeFileSync(envLocalPath, envLocalContent);
+        const finalEnvLocalContent = hasResolvedParams
+            ? substituteParameters(envLocalContent, resolvedParams)
+            : envLocalContent;
+        fs.writeFileSync(envLocalPath, finalEnvLocalContent);
         fileRegistry.addFile('env.local.example');
         console.log(chalk.dim(`   📄 Created env.local.example with optional overrides`));
     }
+    // 17d. Generate target-specific workspace artifacts and guidance
+    if (activeTarget !== 'local') {
+        console.log(chalk.cyan(`\n🎯 Generating ${activeTarget} target artifacts...`));
+        const targetFiles = targetRule.generateFiles(targetCtx);
+        for (const [key, content] of targetFiles) {
+            const absPath = resolveTargetFilePath(key, outputPath, projectRoot);
+            fs.writeFileSync(absPath, content);
+            if (key.startsWith('../')) {
+                // Project-root file: log but do NOT add to fileRegistry
+                // (fileRegistry only tracks outputPath-relative files)
+                console.log(chalk.dim(`   📄 Created ${path.basename(absPath)} at project root`));
+            }
+            else {
+                fileRegistry.addFile(key);
+                console.log(chalk.dim(`   📄 Created ${key} in .devcontainer/`));
+            }
+        }
+    }
     // 18. Clean up stale files from previous runs (preserves superposition.json and .env)
     cleanupStaleFiles(outputPath, fileRegistry);
+    // 18b. Validate that no unresolved {{cs.*}} tokens remain in any generated file.
+    // Run unconditionally — an overlay author could accidentally ship {{cs.*}} tokens
+    // in files that don't have a matching parameters declaration, and we must catch those
+    // regardless of whether any parameters were resolved in this run.
+    // Only text-like files (not binaries) are scanned; skip missing files gracefully.
+    const BINARY_EXTENSIONS = new Set(['.png', '.jpg', '.gif', '.ico', '.woff', '.woff2', '.ttf']);
+    {
+        const allGeneratedFiles = Array.from(fileRegistry.getFiles());
+        const unresolvedByFile = {};
+        for (const relFile of allGeneratedFiles) {
+            const ext = path.extname(relFile).toLowerCase();
+            if (BINARY_EXTENSIONS.has(ext))
+                continue;
+            const absPath = path.join(outputPath, relFile);
+            if (!fs.existsSync(absPath))
+                continue;
+            const content = fs.readFileSync(absPath, 'utf8');
+            const unresolved = findUnresolvedTokens(content);
+            if (unresolved.length > 0) {
+                unresolvedByFile[relFile] = [...new Set(unresolved)];
+            }
+        }
+        if (Object.keys(unresolvedByFile).length > 0) {
+            const details = Object.entries(unresolvedByFile)
+                .map(([file, tokens]) => `${file}: ${tokens.join(', ')}`)
+                .join('; ');
+            throw new Error(`Unresolved {{cs.*}} parameter tokens remain in generated files: ${details}. ` +
+                `Declare these parameters in the overlay's overlay.yml and provide values in your project file (superposition.yml).`);
+        }
+    }
     // 19. Generate and return summary
     const files = Array.from(fileRegistry.getFiles());
     const services = overlaysToServices(selectedOverlayMetadata);
@@ -1308,6 +2165,14 @@ function mergeSetupScripts(config, overlays, outputPath, fileRegistry, overlaysD
         fs.existsSync(path.join(overlaysDir, o, 'verify.sh')));
     if (hasScripts) {
         fileRegistry.addDirectory('scripts');
+        // Emit shared setup utilities so overlay scripts can source them
+        const setupUtilsSrc = path.join(TEMPLATES_DIR, 'scripts', 'setup-utils.sh');
+        if (fs.existsSync(setupUtilsSrc)) {
+            const setupUtilsDest = path.join(scriptsDir, 'setup-utils.sh');
+            fs.copyFileSync(setupUtilsSrc, setupUtilsDest);
+            fs.chmodSync(setupUtilsDest, 0o755);
+            fileRegistry.addFile('scripts/setup-utils.sh');
+        }
     }
     for (const overlay of overlays) {
         // Handle setup scripts