@aiwg/cli 2026.10.5 → 2026.10.6

package/tools/agents/deploy-agents.mjs

@@ -32,6 +32,7 @@
  *   --model-tier <tier>      Override all artifacts with economy|standard|premium
  *   --as-agents-md               Aggregate to single AGENTS.md (OpenAI/Codex)
  *   --create-agents-md           Create/update AGENTS.md template
+  --no-context-files           Preserve WORKSPACE.md, AIWG.md and AGENTS.md (including managed blocks)
  *   --skip-commands-migration    Skip deleting the commands directory (warns about duplicate TUI entries) (Factory/Codex/OpenCode/Cursor)
  *   --deploy-source <name>       Managed-marker source for deployed artifacts (default: bundled)
  *   --deploy-version <version>   Managed-marker version for deployed artifacts (default: source package.json)
@@ -75,6 +76,8 @@ const staticModelCatalog = _require('../../agentic/code/providers/model-catalog.
 let fs;
 try { const gfs = _require('graceful-fs'); gfs.gracefulify(realFs); fs = realFs; } catch { fs = realFs; }
 import path from 'path';
+import { importImpl } from '../_resolve-impl.mjs';
+const { resolveDeployVersion } = await importImpl(import.meta.url, 'providers/deploy-version.mjs');
 import os from 'os';
 import readline from 'readline';
 import { fileURLToPath } from 'url';
@@ -96,20 +99,6 @@ import {
   resolveAiwgRoot,
   updateSidecarManifest,
 } from './providers/base.mjs';
-const modelCatalog = loadRuntimeModelCatalog(staticModelCatalog);
-
-/**
- * Read version from package.json at the source root.
- * Falls back to 'unknown' if unavailable.
- */
-function getDeployVersion(srcRoot) {
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(srcRoot, 'package.json'), 'utf8'));
-    return pkg.version || 'unknown';
-  } catch {
-    return 'unknown';
-  }
-}
 
 // ============================================================================
 // Provider Registry
@@ -421,10 +410,8 @@ function pruneStaleAiwgArtifacts(provider, target, srcRoot, opts, explicitSource
   }
 
   if (opts.kernelOnly) {
-    // A kernel-only run deploys skills and nothing else (deployCommands /
-    // deployRules / deployBehaviors are all forced false above), so it has no
-    // basis for judging any flat artifact stale. The empty desired set below
-    // exists for one narrow migration: clearing agents/commands/rules left by
+    // Kernel-only delivers skills and rules. The empty desired set below
+    // applies only to bulk agents/commands left by
     // the pre-#152 bulk default, when the bulk install is the only thing this
     // project ever deployed.
     //
@@ -438,7 +425,7 @@ function pruneStaleAiwgArtifacts(provider, target, srcRoot, opts, explicitSource
       }
       return;
     }
-    for (const type of ['agents', 'commands', 'rules']) {
+    for (const type of ['agents', 'commands']) {
       const relPath = provider.paths?.[type];
       if (!relPath || relPath.endsWith('.md')) continue;
       const destDir = path.isAbsolute(relPath) ? relPath : path.join(target, relPath);
@@ -499,6 +486,8 @@ export function parseArgs(args = process.argv.slice(2)) {
     efficiencyModel: null,
     asAgentsMd: false,
     createAgentsMd: false,
+    contextFiles: true,
+    projectScope: false,
     deployCommands: false,
     deploySkills: false,
     deployRules: false,
@@ -509,6 +498,8 @@ export function parseArgs(args = process.argv.slice(2)) {
     strict: false,
     reportOnly: true,
     kernelOnly: false,
+    deferRuleProjection: false,
+    additionalSources: [],
     filter: null,           // Glob pattern for agent names
     filterRole: null,       // Filter by role: reasoning|coding|efficiency
     save: false,            // Save model config to project models.json
@@ -532,6 +523,11 @@ export function parseArgs(args = process.argv.slice(2)) {
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--source' && args[i + 1]) cfg.source = path.resolve(args[++i]);
+    else if (a === '--additional-source') {
+      const source = args[++i];
+      if (!source || source.startsWith('--')) throw new Error('--additional-source requires a source directory');
+      cfg.additionalSources.push(path.resolve(source));
+    }
     else if (a === '--target' && args[i + 1]) cfg.target = path.resolve(args[++i]);
     else if (a === '--mode' && args[i + 1]) cfg.mode = String(args[++i]).toLowerCase();
     else if (a === '--scope') {
@@ -540,6 +536,7 @@ export function parseArgs(args = process.argv.slice(2)) {
         throw new Error(`--scope expected 'user' or 'project', got '${scope ?? '(missing)'}'`);
       }
       cfg.userScope = scope === 'user';
+      cfg.projectScope = scope === 'project';
     }
     else if (a === '--user') cfg.userScope = true;
     else if (a === '--dry-run') cfg.dryRun = true;
@@ -563,6 +560,8 @@ export function parseArgs(args = process.argv.slice(2)) {
     else if (a === '--allow-over-budget') cfg.allowOverBudget = true;
     else if (a === '--report-only') cfg.reportOnly = true;
     else if (a === '--kernel-only') cfg.kernelOnly = true;
+    // Internal use orchestration: the final source owns rule presentation.
+    else if (a === '--defer-rule-projection') cfg.deferRuleProjection = true;
     else if (a === '--deploy-behaviors') cfg.deployBehaviors = true;
     else if (a === '--filter' && args[i + 1]) cfg.filter = args[++i];
     else if (a === '--filter-role' && args[i + 1]) cfg.filterRole = args[++i];
@@ -579,12 +578,12 @@ export function parseArgs(args = process.argv.slice(2)) {
     // managed-hooks opt-out (default on, mirroring the Claude autoInstall policy).
     else if (a === '--mcp') cfg.mcp = true;
     else if (a === '--no-hooks') cfg.hooks = false;
+    else if (a === '--no-context-files') cfg.contextFiles = false;
     else if (a === '--deploy-source' && args[i + 1]) cfg.deploySource = String(args[++i]);
     else if (a === '--listing-budget') cfg.listingBudget = true;
     else if (a === '--deploy-version' && args[i + 1]) cfg.deployVersion = String(args[++i]);
     else if (a === '--help' || a === '-h') {
-      printHelp();
-      process.exit(0);
+      cfg.help = true;
     }
   }
   return cfg;
@@ -610,7 +609,7 @@ Options:
   --commands-only          Deploy only commands (skip agents)
   --skills-only            Deploy only skills (skip agents)
   --rules-only             Deploy only rules (skip agents)
-  --kernel-only            Deploy kernel skills only and prune managed bulk artifacts
+  --kernel-only            Deploy kernel skills and rules; prune managed bulk agents/commands
   --dry-run                Show what would be deployed without writing
   --force                  Overwrite existing files
   --provider <name>        Target provider (see below)
@@ -630,6 +629,7 @@ Options:
                            (.muse/hooks.json; installed by default)
   --as-agents-md               Aggregate to single AGENTS.md (Codex)
   --create-agents-md           Create/update AGENTS.md template
+  --no-context-files           Preserve WORKSPACE.md, AIWG.md and AGENTS.md (including managed blocks)
   --skip-commands-migration    Skip deleting the commands directory before skills deployment
   --listing-budget             Honor the provider startup-listing cap even with --copy-all
   --deploy-source <name>       Managed-marker source stamped into deployed artifacts.
@@ -743,7 +743,7 @@ function resolveProvider(name) {
       console.error('');
       for (const line of UNSUPPORTED_PROVIDER_HINTS[candidate]) console.error(line);
     }
-    process.exit(1);
+    throw new Error(`Unknown provider: ${name}`);
   }
   return resolved;
 }
@@ -753,14 +753,17 @@ function resolveProvider(name) {
  */
 async function loadProvider(providerName) {
   const resolved = resolveProvider(providerName);
-  const providerPath = `./providers/${resolved}.mjs`;
+  // Resolve against this module, not the caller's cwd: in-process callers
+  // (including module runners such as Vitest) cannot resolve a bare relative
+  // specifier held in a variable.
+  const providerUrl = new URL(`./providers/${resolved}.mjs`, import.meta.url).href;
 
   try {
-    const provider = await import(providerPath);
+    const provider = await import(providerUrl);
     return provider.default || provider;
   } catch (err) {
     console.error(`Failed to load provider '${resolved}':`, err.message);
-    process.exit(1);
+    throw err;
   }
 }
 
@@ -896,7 +899,7 @@ function deepMerge(target, source) {
  * @param {string} targetDir - Resolved target directory
  * @returns {Promise<boolean>} true = proceed with migration, false = skip
  */
-async function promptCommandsMigration(cfg, provider, targetDir) {
+async function promptCommandsMigration(cfg, provider, targetDir, interactive = process.stdout.isTTY) {
   // Home-directory providers share commands across projects — do not delete.
   if (provider.capabilities?.homeDirectoryDeploy) return false;
   // Some providers intentionally expose both surfaces with different runtime
@@ -914,7 +917,7 @@ async function promptCommandsMigration(cfg, provider, targetDir) {
   if (entries.length === 0) return false;
 
   // Non-interactive context: migrate silently.
-  if (cfg.quiet || !process.stdout.isTTY) return true;
+  if (cfg.quiet || !interactive) return true;
 
   const rel = path.relative(process.cwd(), commandsDir);
   console.log(`\n⚠  Commands → Skills Migration`);
@@ -948,6 +951,8 @@ async function promptCommandsMigration(cfg, provider, targetDir) {
 
 export async function main(args = process.argv.slice(2), internal = {}) {
   const cfg = parseArgs(args);
+  if (cfg.help) { printHelp(); return 0; }
+  const modelCatalog = loadRuntimeModelCatalog(staticModelCatalog);
 
   // Resolve source directory (default to repo root relative to this script)
   const __filename = fileURLToPath(import.meta.url);
@@ -956,8 +961,7 @@ export async function main(args = process.argv.slice(2), internal = {}) {
 
   // Validate source directory
   if (!fs.existsSync(srcRoot)) {
-    console.error(`Source directory not found: ${srcRoot}`);
-    process.exit(1);
+    throw new Error(`Source directory not found: ${srcRoot}`);
   }
 
   // Validate target directory
@@ -1020,6 +1024,10 @@ export async function main(args = process.argv.slice(2), internal = {}) {
 
   // Load provider module
   const provider = await loadProvider(cfg.provider);
+  if (cfg.additionalSources.length && provider.name !== 'omp') throw new Error('--additional-source requires the OMP provider');
+  for (const source of cfg.additionalSources) {
+    if (!fs.statSync(source).isDirectory()) throw new Error(`Additional source is not a directory: ${source}`);
+  }
   if (!cfg.quiet) console.log(`\nLoaded provider: ${provider.name}`);
 
   // Build options for provider
@@ -1038,11 +1046,15 @@ export async function main(args = process.argv.slice(2), internal = {}) {
     codingModel: cfg.codingModel,
     efficiencyModel: cfg.efficiencyModel,
     modelsConfig,
+    modelCatalog,
+    // Warnings belong to this pass, just as they do in an isolated CLI run.
+    warnedCommandsDirs: new Set(),
     asAgentsMd: cfg.asAgentsMd,
-    createAgentsMd: cfg.createAgentsMd,
+    createAgentsMd: cfg.contextFiles && cfg.createAgentsMd,
+    contextFiles: cfg.contextFiles,
     deployCommands: cfg.kernelOnly ? false : cfg.deployCommands,
     deploySkills: cfg.kernelOnly ? true : cfg.deploySkills,
-    deployRules: cfg.kernelOnly ? false : cfg.deployRules,
+    deployRules: !cfg.deferRuleProjection && (cfg.kernelOnly || cfg.deployRules),
     deployBehaviors: cfg.kernelOnly ? false : cfg.deployBehaviors,
     commandsOnly: cfg.commandsOnly,
     skillsOnly: cfg.skillsOnly || cfg.kernelOnly,
@@ -1051,6 +1063,8 @@ export async function main(args = process.argv.slice(2), internal = {}) {
     reportOnly: cfg.reportOnly,
     allowOverBudget: cfg.allowOverBudget === true,
     kernelOnly: cfg.kernelOnly,
+    deferRuleProjection: cfg.deferRuleProjection,
+    additionalSources: cfg.additionalSources,
     filter: cfg.filter,
     filterRole: cfg.filterRole,
     save: cfg.save,
@@ -1070,17 +1084,23 @@ export async function main(args = process.argv.slice(2), internal = {}) {
     mcp: cfg.mcp === true,
     hooks: cfg.hooks !== false,
     listingBudget: cfg.listingBudget === true,
-    deployVersion: cfg.deployVersion || getDeployVersion(srcRoot),
+    deployVersion: resolveDeployVersion(resolveAiwgRoot(srcRoot) || srcRoot, cfg.deployVersion),
     deploySource: cfg.deploySource || 'bundled',
   };
-  const { isRuleDeploymentPreparationActive } = await import('./providers/rule-delivery.mjs');
-  const preparationActive = isRuleDeploymentPreparationActive();
+  if (provider.name === 'hermes' && cfg.projectScope && !cfg.userScope) {
+    throw new Error('Hermes does not support --scope project: skills are discovered only under HERMES_HOME/skills (default ~/.hermes/skills). Use --scope user or an isolated HERMES_HOME profile shared with Hermes.');
+  }
+  // Deferred kernel source passes must not load the projection dependency
+  // graph. Preparation still owns their staged deployment when a hook is active.
+  const preparationActive = cfg.kernelOnly && cfg.deferRuleProjection
+    ? Boolean(globalThis[Symbol.for('aiwg.provider-preparation-hook.v1')])
+    : (await import('./providers/rule-delivery.mjs')).isRuleDeploymentPreparationActive();
 
   // Commands → Skills migration: prompt then delete the commands directory
   // so stale command files don't create duplicates in the provider TUI.
   if (!preparationActive && !internal.finalizeOnly) {
     if (!cfg.dryRun && !cfg.skipCommandsMigration) {
-      const doMigrate = await promptCommandsMigration(cfg, provider, cfg.target);
+      const doMigrate = await promptCommandsMigration(cfg, provider, cfg.target, internal.capture ? false : process.stdout.isTTY);
       if (doMigrate) {
         const commandsRelPath = provider.paths?.commands;
         if (commandsRelPath) {
@@ -1106,7 +1126,13 @@ export async function main(args = process.argv.slice(2), internal = {}) {
 
   // Delegate to provider
   try {
-    if (!internal.finalizeOnly) await provider.deploy(opts);
+    if (!internal.finalizeOnly) {
+      if (cfg.kernelOnly && (!cfg.deferRuleProjection || preparationActive)
+        && !['claude', 'codex', 'cursor', 'hermes', 'warp', 'openclaw', 'pi', 'copilot', 'factory', 'opencode', 'windsurf', 'antigravity', 'muse', 'omp', 'grok-build'].includes(provider.name)) {
+        const { deployWithRuleDelivery } = await import('./providers/rule-delivery.mjs');
+        await deployWithRuleDelivery(opts, provider, staged => provider.deploy(staged));
+      } else await provider.deploy(opts);
+    }
     if (preparationActive) return;
 
     const mirroredCommandCount = mirrorSkillsAsCommands(provider, cfg.target, srcRoot, opts);
@@ -1138,11 +1164,13 @@ export async function main(args = process.argv.slice(2), internal = {}) {
     if (cfg.dryRun) {
       console.error('(dry-run mode - no files were modified)');
     }
-    process.exit(1);
+    return 1;
   }
+  return 0;
 }
 
 const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : null;
 if (invokedPath === fileURLToPath(import.meta.url)) {
-  await main();
+  try { process.exitCode = (await main()) ?? 0; }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
 }

package/tools/agents/providers/antigravity.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {
+  withRuleDeployment,
   collectFrameworkArtifacts,
   createAgentsMdFromTemplate,
   deployFiles,
@@ -96,7 +97,7 @@ export async function postDeploy(target, opts) {
     throw new Error('Antigravity global skill deployment is disabled: official 1.1.26 path documentation conflicts');
   }
   if (opts.createAgentsMd || (!opts.commandsOnly && !opts.skillsOnly && !opts.rulesOnly)) {
-    createAgentsMd(target, opts.srcRoot, opts.dryRun);
+    if (opts.contextFiles !== false) createAgentsMd(target, opts.srcRoot, opts.dryRun);
   }
   if (!opts.quiet) {
     console.log('Antigravity resources are project scoped. Restart agy after resource changes; authenticate with the provider separately.');
@@ -106,6 +107,10 @@ export async function postDeploy(target, opts) {
 export function getFileExtension() { return '.md'; }
 
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath }, deploySelected);
+}
+
+async function deploySelected(opts) {
   if (opts.global || opts.user || opts.scope === 'user') {
     throw new Error('Antigravity global skill deployment is disabled: official 1.1.26 path documentation conflicts');
   }

package/tools/agents/providers/base.mjs

@@ -104,7 +104,7 @@ export function listMdFiles(dir, excludePatterns = []) {
   const excluded = [...defaultExcluded, ...excludePatterns];
   return fs
     .readdirSync(dir, { withFileTypes: true })
-    .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md') && !e.name.toLowerCase().endsWith('.soul.md') && !excluded.includes(e.name))
+    .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md') && !e.name.toLowerCase().endsWith('.soul.md') && !e.name.toLowerCase().endsWith('.core.md') && !excluded.includes(e.name))
     .map((e) => path.join(dir, e.name));
 }
 
@@ -2474,7 +2474,7 @@ export function applyInlineRuleBudget(ruleFiles) {
 /**
  * Tier gate (#1673, enforcement-tiered deployment ADR). Only CRITICAL and HIGH
  * rules are inlined into a provider's always-on rule directory; MEDIUM/LOW are
- * left on-demand (reachable via `aiwg show rule <name>` and the assembled
+ * left on-demand (reachable via `aiwg show rule <name> --body` and the assembled
  * RULES-INDEX pointer index). Index files and rules with no enforcement marker
  * default to always-on, so an un-triaged or structural file is never dropped.
  */
@@ -2558,17 +2558,17 @@ export function renderOnDemandRuleSection(onDemandFiles, opts = {}) {
     'on demand:',
     '',
     '```bash',
-    'aiwg show rule <name>',
+    'aiwg show rule <name> --body',
     '```',
     '',
-    ...names.map((n) => `- \`${n}\` — \`aiwg show rule ${n}\``),
+    ...names.map((n) => `- \`${n}\` — \`aiwg show rule ${n} --body\``),
   ].join('\n');
 }
 
 /**
  * Write a compact on-demand rule index (#1673) into a provider's rule dir.
  * Lists the MEDIUM/LOW rules that are NOT inlined at startup, with the
- * `aiwg show rule <name>` fetch hint. Removes a stale index when empty.
+ * `aiwg show rule <name> --body` fetch hint. Removes a stale index when empty.
  */
 export function writeOnDemandRuleIndex(destDir, onDemandFiles, opts = {}) {
   const indexPath = path.join(destDir, 'RULES-ONDEMAND.md');
@@ -2588,10 +2588,10 @@ export function writeOnDemandRuleIndex(destDir, onDemandFiles, opts = {}) {
     'fetch any rule body on demand:',
     '',
     '```bash',
-    'aiwg show rule <name>',
+    'aiwg show rule <name> --body',
     '```',
     '',
-    ...names.map((n) => `- \`${n}\` — \`aiwg show rule ${n}\``),
+    ...names.map((n) => `- \`${n}\` — \`aiwg show rule ${n} --body\``),
     '',
   ];
   if (demotedNames.length > 0) {
@@ -2605,7 +2605,7 @@ export function writeOnDemandRuleIndex(destDir, onDemandFiles, opts = {}) {
       '(AIWG_RULES_INLINE_BUDGET_TOKENS) and break subagent dispatch with "Prompt is too long".',
       'Fetch any of them before work they govern:',
       '',
-      ...demotedNames.map((n) => `- \`${n}\` — \`aiwg show rule ${n}\``),
+      ...demotedNames.map((n) => `- \`${n}\` — \`aiwg show rule ${n} --body\``),
       '',
     );
   }
@@ -2803,7 +2803,9 @@ export function getAddonFiles(srcRoot, options = {}) {
 // ============================================================================
 
 /**
- * Load rules manifest from source directory
+ * Load rules manifest from source directory.
+ * Inventory metadata only: delivery is decided by rule `activation` (rule-delivery.mjs);
+ * the former manifest `tiers` deploy policy was never consulted and was removed (#3450).
  * @param {string} srcRoot - Source root directory
  * @returns {object|null} - Parsed manifest or null if not found
  */
@@ -3168,8 +3170,9 @@ export function migrateCommandsDirectory(commandsDir, opts = {}) {
     const rel = path.relative(process.cwd(), commandsDir);
     // The condition is a property of the directory, not of each deployed unit;
     // emit it once per run no matter how many units pass through.
-    if (warnedCommandsDirs.has(commandsDir)) return false;
-    warnedCommandsDirs.add(commandsDir);
+    const warned = opts.warnedCommandsDirs || warnedCommandsDirs;
+    if (warned.has(commandsDir)) return false;
+    warned.add(commandsDir);
 
     const stale = listManagedCommandFiles(commandsDir);
     if (stale.length === 0) return false;
@@ -3338,7 +3341,7 @@ export function replaceBoundRulesBlock(content, rules = []) {
   const unique = [...new Map(rules.map(rule => [rule.name, rule])).values()]
     .sort((a, b) => a.name.localeCompare(b.name));
   return `${clean}${clean.endsWith('\n') ? '' : '\n'}\n<!-- AIWG:bound-rules:start -->\n## Bound rules\n\nRequired reading on every invocation: fetch and follow every bound rule below before starting governed work. A summary or discovery pointer does not discharge this obligation.\n\n${unique.map(rule =>
-    `- ${rule.name} — ${rule.summary}\n  Fetch and follow before governed work: \`aiwg show rule ${rule.name}\`.`
+    `- ${rule.name} — ${rule.summary}\n  Fetch and follow before governed work: \`aiwg show rule ${rule.name} --body\`.`
   ).join('\n')}\n<!-- AIWG:bound-rules:end -->\n`;
 }
 
@@ -3347,8 +3350,11 @@ export function injectBoundRules(content, source, opts = {}) {
   return replaceBoundRulesBlock(content, opts.ruleDelivery.bindings.get(path.resolve(source)) || []);
 }
 
-/** All provider output is staged; the complete startup guard runs before promotion. */
+/** Rule delivery stages output and guards startup before promotion. Deferred
+ * kernel passes leave rule delivery to the final source in the invocation. */
 export async function withRuleDeployment(opts, provider, deploy) {
+  if (opts.kernelOnly && opts.deferRuleProjection && provider.name !== 'warp'
+    && !globalThis[Symbol.for('aiwg.provider-preparation-hook.v1')]) return deploy(opts);
   const { deployWithRuleDelivery } = await import('./rule-delivery.mjs');
   return deployWithRuleDelivery(opts, provider, deploy);
 }

package/tools/agents/providers/claude.mjs

@@ -416,7 +416,7 @@ export async function postDeploy(targetDir, opts) {
   }
 
   // Hook file architecture: write AIWG.md and wire @AIWG.md into CLAUDE.md
-  if (opts.srcRoot) {
+  if (opts.srcRoot && opts.contextFiles !== false) {
     deployHookFile(targetDir, opts);
   }
 }

package/tools/agents/providers/codex.mjs

@@ -35,6 +35,7 @@ const staticModelCatalog = _require('../../../agentic/code/providers/model-catal
 import path from 'path';
 import os from 'os';
 import { spawn } from 'child_process';
+import { pathToFileURL } from 'node:url';
 import { load as loadYaml } from 'js-yaml';
 import { classifyModelRole, modelForRole } from './model-role.mjs';
 import {
@@ -66,7 +67,6 @@ import {
   parseFrontmatter,
   resolveAiwgRoot
 } from './base.mjs';
-const modelCatalog = loadRuntimeModelCatalog(staticModelCatalog);
 
 function resolveCodexHelperRoot(srcRoot) {
   const resolved = resolveAiwgRoot(srcRoot);
@@ -101,7 +101,6 @@ export const kernelSkillsPath = '.agents/skills/';
 // Legacy home-dir skills location written by AIWG versions prior to the #766
 // regression fix. Pruned on every codex skill deploy so codex-rs stops listing
 // each AIWG skill twice. Never touches non-AIWG (unmarked) skills.
-const legacyHomeSkillsDir = path.join(os.homedir(), '.codex', 'skills');
 
 export const support = {
   agents: 'native',
@@ -125,6 +124,7 @@ export const capabilities = {
  * Map model shorthand to OpenAI/GPT format
  */
 export function mapModel(originalModel, modelCfg, modelsConfig) {
+  const modelCatalog = modelCfg.modelCatalog || loadRuntimeModelCatalog(staticModelCatalog);
   const gptModels = {
     'opus': modelCatalog.providers.codex.roles.reasoning.id,
     'sonnet': modelCatalog.providers.codex.roles.coding.id,
@@ -204,7 +204,7 @@ export function renderAgentToml(srcPath, content, models) {
  */
 export function transformAgent(srcPath, content, opts) {
   const { reasoningModel, codingModel, efficiencyModel } = opts;
-  const catalogModels = modelCatalog.providers.codex.roles;
+  const catalogModels = (opts.modelCatalog || loadRuntimeModelCatalog(staticModelCatalog)).providers.codex.roles;
 
   const models = {
     reasoning: reasoningModel || catalogModels.reasoning.id,
@@ -239,6 +239,27 @@ export function deployAgents(agentFiles, targetDir, opts) {
   }, transformAgent);
 }
 
+/** Run the helper in this pass; retain process isolation for troubleshooting. */
+async function runCodexDeployer(scriptPath, args, helperRoot, opts) {
+  if (process.env.AIWG_DEPLOY_SUBPROCESS !== '1') {
+    const deployer = await import(pathToFileURL(scriptPath).href);
+    await deployer.main(args, { homeDir: opts.deploymentHome || os.homedir() });
+    return;
+  }
+  await new Promise((resolve, reject) => {
+    const child = spawn('node', [scriptPath, ...args], {
+      stdio: 'inherit',
+      cwd: helperRoot,
+      env: opts.deploymentHome ? { ...process.env, HOME: opts.deploymentHome } : process.env,
+    });
+    child.on('close', code => {
+      if (code === 0) resolve();
+      else reject(new Error(`${path.basename(scriptPath)} exited with code ${code}`));
+    });
+    child.on('error', reject);
+  });
+}
+
 /**
  * Deploy commands via external script
  *
@@ -257,30 +278,16 @@ export async function deployCommands(targetDir, srcRoot, opts) {
 
   console.log('Delegating command deployment to deploy-prompts-codex.mjs (~/.codex/prompts/)...');
 
-  return new Promise((resolve, reject) => {
-    // NOTE: Do NOT pass --target - Codex prompts belong in ~/.codex/prompts/ (home)
-    const args = ['--source', srcRoot];
-    if (opts.dryRun) args.push('--dry-run');
-    if (opts.force) args.push('--force');
-    if (opts.mode) args.push('--mode', opts.mode);
-    if (opts.copyStandardSkills === true) args.push('--copy-all');
-    // A copy-all the deployer forced on the caller's behalf (project-local
-    // bundles) still honors the startup listing cap (#2561).
-    if (opts.listingBudget === true) args.push('--listing-budget');
-
-    const child = spawn('node', [scriptPath, ...args], {
-      stdio: 'inherit',
-      cwd: helperRoot,
-      env: opts.deploymentHome ? { ...process.env, HOME: opts.deploymentHome } : process.env
-    });
-
-    child.on('close', (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`deploy-prompts-codex.mjs exited with code ${code}`));
-    });
-
-    child.on('error', reject);
-  });
+  // NOTE: Do NOT pass --target - Codex prompts belong in ~/.codex/prompts/ (home)
+  const args = ['--source', srcRoot];
+  if (opts.dryRun) args.push('--dry-run');
+  if (opts.force) args.push('--force');
+  if (opts.mode) args.push('--mode', opts.mode);
+  if (opts.copyStandardSkills === true) args.push('--copy-all');
+  // A copy-all the deployer forced on the caller's behalf (project-local
+  // bundles) still honors the startup listing cap (#2561).
+  if (opts.listingBudget === true) args.push('--listing-budget');
+  await runCodexDeployer(scriptPath, args, helperRoot, opts);
 }
 
 /**
@@ -305,37 +312,23 @@ export async function deploySkills(targetDir, srcRoot, opts) {
   const crossAgentSkillsDir = path.join(targetDir, '.agents', 'skills');
   console.log(`Deploying skills to ${crossAgentSkillsDir} (.agents/skills — codex-scanned path)...`);
 
-  await new Promise((resolve, reject) => {
-    const args = ['--source', srcRoot, '--target', crossAgentSkillsDir];
-    // Overflow past Codex's startup listing cap lands here instead of being
-    // deployed over the cap (#2561); the index still reaches these skills.
-    args.push('--standard-target', path.join(targetDir, ...paths.skills.split('/').filter(Boolean)));
-    if (opts.dryRun) args.push('--dry-run');
-    if (opts.force) args.push('--force');
-    if (opts.mode) args.push('--mode', opts.mode);
-    if (opts.copyStandardSkills === true) args.push('--copy-all');
-    // A copy-all the deployer forced on the caller's behalf (project-local
-    // bundles) still honors the startup listing cap (#2561).
-    if (opts.listingBudget === true) args.push('--listing-budget');
-
-    const child = spawn('node', [scriptPath, ...args], {
-      stdio: 'inherit',
-      cwd: helperRoot,
-      env: opts.deploymentHome ? { ...process.env, HOME: opts.deploymentHome } : process.env
-    });
-
-    child.on('close', (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`deploy-skills-codex.mjs exited with code ${code}`));
-    });
-
-    child.on('error', reject);
-  });
+  const args = ['--source', srcRoot, '--target', crossAgentSkillsDir];
+  // Overflow past Codex's startup listing cap lands here instead of being
+  // deployed over the cap (#2561); the index still reaches these skills.
+  args.push('--standard-target', path.join(targetDir, ...paths.skills.split('/').filter(Boolean)));
+  if (opts.dryRun) args.push('--dry-run');
+  if (opts.force) args.push('--force');
+  if (opts.mode) args.push('--mode', opts.mode);
+  if (opts.copyStandardSkills === true) args.push('--copy-all');
+  // A copy-all the deployer forced on the caller's behalf (project-local
+  // bundles) still honors the startup listing cap (#2561).
+  if (opts.listingBudget === true) args.push('--listing-budget');
+  await runCodexDeployer(scriptPath, args, helperRoot, opts);
 
   // Self-heal: prune AIWG-managed skill dirs left behind in the legacy
   // ~/.codex/skills/ home location by pre-fix versions, so codex-rs stops
   // listing each skill twice.
-  pruneLegacyCodexSkills(opts, opts.legacyCodexSkills || legacyHomeSkillsDir);
+  pruneLegacyCodexSkills(opts, opts.legacyCodexSkills || path.join(os.homedir(), '.codex', 'skills'));
 }
 
 /**
@@ -346,7 +339,7 @@ export async function deploySkills(targetDir, srcRoot, opts) {
  * the `.aiwg-managed` marker are removed — user-authored skills are never
  * touched. The now-empty legacy dir is removed if AIWG owned everything in it.
  */
-export function pruneLegacyCodexSkills(opts = {}, legacyDir = legacyHomeSkillsDir) {
+export function pruneLegacyCodexSkills(opts = {}, legacyDir = path.join(os.homedir(), '.codex', 'skills')) {
   let entries;
   try {
     entries = fs.readdirSync(legacyDir, { withFileTypes: true });
@@ -401,6 +394,7 @@ export function deployRules(ruleFiles, targetDir, opts) {
  * Aggregate agents to single AGENTS.md file
  */
 export function aggregateToAgentsMd(agentFiles, destPath, opts) {
+  if (opts.contextFiles === false) return 0;
   const lines = ['# AIWG agent definitions', '', 'Read the selected definition before invoking an agent.', ''];
   for (const file of agentFiles) {
     const { metadata } = parseFrontmatter(fs.readFileSync(file, 'utf8'));
@@ -518,7 +512,7 @@ export async function postDeploy(targetDir, opts) {
   initializeFrameworkWorkspace(targetDir, opts.mode, opts.dryRun, opts.srcRoot);
 
   if (opts.createAgentsMd) {
-    createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
+    if (opts.contextFiles !== false) createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
   }
 }