@aiwg/cli 2026.9.9 → 2026.9.10

package/tools/agents/providers/base.mjs

@@ -281,10 +281,14 @@ export function extractFrameworkSlug(srcPath) {
  * Priority: Project models.json > User ~/.config/aiwg/models.json > AIWG defaults
  */
 export function loadModelConfig(srcRoot) {
+  // An addon/framework/bundle `--source` is not the AIWG root, so resolve the
+  // shipped defaults through the corpus root; otherwise addon deploys fell
+  // through to the hardcoded fallback and deployed bare aliases (#2563).
+  const aiwgRoot = (srcRoot && resolveAiwgRoot(srcRoot)) || srcRoot;
   const locations = [
     { path: path.join(process.cwd(), 'models.json'), label: 'project' },
     { path: path.join(process.env.HOME || process.env.USERPROFILE, '.config', 'aiwg', 'models.json'), label: 'user' },
-    { path: path.join(srcRoot, 'agentic', 'code', 'frameworks', 'sdlc-complete', 'config', 'models.json'), label: 'AIWG defaults' }
+    { path: path.join(aiwgRoot, 'agentic', 'code', 'frameworks', 'sdlc-complete', 'config', 'models.json'), label: 'AIWG defaults' }
   ];
 
   for (const loc of locations) {
@@ -302,9 +306,9 @@ export function loadModelConfig(srcRoot) {
   // Fallback to hardcoded defaults if no config found
   return {
     claude: {
-      reasoning: { model: 'opus' },
-      coding: { model: 'sonnet' },
-      efficiency: { model: 'haiku' }
+      reasoning: { model: 'claude-opus-4-7' },
+      coding: { model: 'claude-sonnet-4-6' },
+      efficiency: { model: 'claude-haiku-4-5' }
     },
     factory: {
       reasoning: { model: 'heavy' },
@@ -312,9 +316,9 @@ export function loadModelConfig(srcRoot) {
       efficiency: { model: 'light' }
     },
     shorthand: {
-      'opus': 'claude-opus-4-6',
+      'opus': 'claude-opus-4-7',
       'sonnet': 'claude-sonnet-4-6',
-      'haiku': 'claude-haiku-4-5-20251001',
+      'haiku': 'claude-haiku-4-5',
       'inherit': 'inherit'
     },
     claude_shorthand: {
@@ -2354,9 +2358,137 @@ export function getAddonSkillDirs(srcRoot, excludeAddons = []) {
  */
 export function ruleEnforcementLevel(content) {
   const m = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!m) return null;
-  const e = m[1].match(/^enforcement:\s*([A-Za-z]+)/m);
-  return e ? e[1].toLowerCase() : null;
+  if (m) {
+    const e = m[1].match(/^enforcement:\s*([A-Za-z]+)/m);
+    if (e) return e[1].toLowerCase();
+  }
+  // Rules without frontmatter declare the level in the body header.
+  const body = content.match(/^\*\*Enforcement Level\*\*:\s*([A-Za-z]+)/m);
+  return body ? body[1].toLowerCase() : null;
+}
+
+/**
+ * Default inline rule budget (#2562). Every inlined rule is loaded into every
+ * session AND every subagent dispatch, so the always-on set must leave room
+ * for the agent definition, the system prompt, and the task itself inside the
+ * standard 200K window. 64K tokens (~256 KB) keeps a full CRITICAL+HIGH
+ * deployment dispatchable; `AIWG_RULES_INLINE_BUDGET_TOKENS=0` disables the
+ * budget, any other value overrides it.
+ */
+export const DEFAULT_RULES_INLINE_BUDGET_TOKENS = 64_000;
+const RULE_CHARS_PER_TOKEN = 4;
+
+export function resolveRulesInlineBudgetTokens(env = process.env) {
+  const raw = env.AIWG_RULES_INLINE_BUDGET_TOKENS;
+  if (raw === undefined || raw === '') return DEFAULT_RULES_INLINE_BUDGET_TOKENS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_RULES_INLINE_BUDGET_TOKENS;
+  return parsed;
+}
+
+/** Sidecar recording which rules the inline budget moved on demand (#2562). */
+export const RULE_BUDGET_SIDECAR = '.aiwg-rules-budget.json';
+
+export function readRuleBudgetSidecar(destDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(destDir, RULE_BUDGET_SIDECAR), 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.demoted)) return null;
+    return { budgetTokens: Number(parsed.budgetTokens) || 0, demoted: parsed.demoted.map(String) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Keep a provider rule directory under the inline budget (#2562).
+ *
+ * Rules reach the directory over several deploy passes (the framework pass,
+ * then one per addon), so the budget is enforced against what is actually on
+ * disk after each pass rather than against any single pass's file list. When
+ * the inlined set exceeds the budget, the largest HIGH rules (then unlabelled
+ * ones; never CRITICAL or the indexes) are removed from the directory and
+ * recorded in the sidecar; the next pass skips re-deploying them and the
+ * on-demand index lists them as binding rules fetched via `aiwg show rule`.
+ * A changed budget invalidates the sidecar so the set is recomputed.
+ *
+ * Returns `{ demoted, removed }` — all demoted stems (sidecar state) and the
+ * stems removed by this call.
+ */
+export function reconcileInlineRuleBudget(destDir, budgetTokens = resolveRulesInlineBudgetTokens(), opts = {}) {
+  const sidecarPath = path.join(destDir, RULE_BUDGET_SIDECAR);
+  if (!budgetTokens || budgetTokens <= 0) {
+    if (fs.existsSync(sidecarPath) && !opts.dryRun) fs.rmSync(sidecarPath, { force: true });
+    return { demoted: [], removed: [] };
+  }
+  const previous = readRuleBudgetSidecar(destDir);
+  const carried = previous && previous.budgetTokens === budgetTokens ? previous.demoted : [];
+  let files = [];
+  try {
+    files = fs.readdirSync(destDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+      .map((entry) => path.join(destDir, entry.name))
+      .filter((file) => {
+        const base = path.basename(file);
+        if (base === 'RULES-INDEX.md' || base === 'RULES-ONDEMAND.md') return false;
+        try { return MANAGED_MARKER_RE.test(fs.readFileSync(file, 'utf8')); } catch { return false; }
+      });
+  } catch {
+    return { demoted: carried, removed: [] };
+  }
+  const { demoted } = applyInlineRuleBudget(files, budgetTokens);
+  const removed = demoted.map((file) => artifactStem(path.basename(file)));
+  if (!opts.dryRun) {
+    for (const file of demoted) fs.rmSync(file, { force: true });
+  }
+  const all = [...new Set([...carried, ...removed])].sort();
+  if (!opts.dryRun) {
+    if (all.length > 0) {
+      fs.writeFileSync(sidecarPath, `${JSON.stringify({ budgetTokens, demoted: all }, null, 2)}\n`, 'utf8');
+    } else if (fs.existsSync(sidecarPath)) {
+      fs.rmSync(sidecarPath, { force: true });
+    }
+  }
+  return { demoted: all, removed };
+}
+
+/**
+ * Fit an always-on rule set under the inline budget (#2562).
+ *
+ * CRITICAL rules and the generated indexes are never demoted. When the
+ * remaining set still exceeds the budget, HIGH rules are demoted largest-first
+ * (fewest rules leave the always-on set), then rules with no declared level.
+ * Demoted rules stay reachable via `aiwg show rule <name>` and are listed in
+ * RULES-ONDEMAND.md under their own heading. Returns `{ inline, demoted }`
+ * with the original order preserved for `inline`.
+ */
+export function applyInlineRuleBudget(ruleFiles, budgetTokens = resolveRulesInlineBudgetTokens()) {
+  const files = [...(ruleFiles || [])];
+  if (!budgetTokens || budgetTokens <= 0) return { inline: files, demoted: [] };
+  const sized = files.map((file) => {
+    const base = path.basename(file);
+    let content = '';
+    try { content = fs.readFileSync(file, 'utf8'); } catch { /* unreadable → keep inline */ }
+    const level = base === 'RULES-INDEX.md' || base === 'RULES-ONDEMAND.md' ? 'critical' : ruleEnforcementLevel(content);
+    return { file, tokens: Math.ceil(Buffer.byteLength(content, 'utf8') / RULE_CHARS_PER_TOKEN), level };
+  });
+  let total = sized.reduce((sum, item) => sum + item.tokens, 0);
+  if (total <= budgetTokens) return { inline: files, demoted: [] };
+  const demotable = sized
+    .filter((item) => item.level !== 'critical')
+    .sort((a, b) => {
+      const rank = (level) => (level === 'high' ? 0 : level === null ? 1 : 2);
+      return rank(a.level) - rank(b.level) || b.tokens - a.tokens;
+    });
+  const demoted = new Set();
+  for (const item of demotable) {
+    if (total <= budgetTokens) break;
+    demoted.add(item.file);
+    total -= item.tokens;
+  }
+  return {
+    inline: files.filter((file) => !demoted.has(file)),
+    demoted: files.filter((file) => demoted.has(file)),
+  };
 }
 
 /**
@@ -2454,8 +2586,9 @@ export function renderOnDemandRuleSection(onDemandFiles, opts = {}) {
  */
 export function writeOnDemandRuleIndex(destDir, onDemandFiles, opts = {}) {
   const indexPath = path.join(destDir, 'RULES-ONDEMAND.md');
-  const names = onDemandRuleNames(onDemandFiles);
-  if (names.length === 0) {
+  const demotedNames = [...new Set([...onDemandRuleNames(opts.demotedFiles || []), ...(opts.demotedNames || [])])].sort();
+  const names = onDemandRuleNames(onDemandFiles, demotedNames);
+  if (names.length === 0 && demotedNames.length === 0) {
     try {
       if (fs.existsSync(indexPath) && !opts.dryRun) fs.rmSync(indexPath);
     } catch { /* ignore */ }
@@ -2475,10 +2608,25 @@ export function writeOnDemandRuleIndex(destDir, onDemandFiles, opts = {}) {
     ...names.map((n) => `- \`${n}\` — \`aiwg show rule ${n}\``),
     '',
   ];
+  if (demotedNames.length > 0) {
+    // HIGH rules that did not fit the inline budget (#2562). They remain
+    // binding; they are fetched on demand so subagent dispatch keeps working.
+    lines.push(
+      '## Binding rules moved on demand to fit the inline budget',
+      '',
+      'These HIGH-enforcement rules still apply in full. They are not inlined because the',
+      `always-on rule set would otherwise exceed the ${(opts.inlineBudgetTokens ?? DEFAULT_RULES_INLINE_BUDGET_TOKENS).toLocaleString()}-token inline budget`,
+      '(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}\``),
+      '',
+    );
+  }
   let content = lines.join('\n');
   content = addManagedMarker(content, opts.deployVersion || 'unknown', opts.deploySource || 'bundled');
   if (!opts.dryRun) fs.writeFileSync(indexPath, content, 'utf8');
-  return names.length;
+  return names.length + demotedNames.length;
 }
 
 export function getAddonRuleFiles(srcRoot, excludeAddons = []) {

package/tools/agents/providers/claude.mjs

@@ -49,6 +49,9 @@ import {
   getAddonRuleFiles,
   listOnDemandRuleFiles,
   writeOnDemandRuleIndex,
+  readRuleBudgetSidecar,
+  reconcileInlineRuleBudget,
+  resolveRulesInlineBudgetTokens,
   assembleRulesIndex,
   normalizeDeploymentMode,
   collectFrameworkArtifacts,
@@ -162,7 +165,7 @@ export function mapModel(shorthand, modelCfg, modelsConfig) {
 export function transformAgent(srcPath, content, opts) {
   const { reasoningModel, codingModel, efficiencyModel } = opts;
 
-  // Only transform if model overrides specified
+  // Explicit overrides re-map every classified model, pinned or not.
   if (reasoningModel || codingModel || efficiencyModel) {
     const models = {
       reasoning: reasoningModel || 'opus',
@@ -172,7 +175,40 @@ export function transformAgent(srcPath, content, opts) {
     return replaceModelFrontmatter(content, models);
   }
 
-  return content;
+  // Default compilation (#2563): a bare alias in source frontmatter is
+  // provider-neutral intent, not a deployable pin. Deployed Claude agents get
+  // the pinned variant from the models.json `claude` tiers so subagent
+  // dispatch never inherits a 1M-context parent (#1442). Already-pinned
+  // values, `inherit`, and explicit `[1m]` opt-ins are left untouched.
+  const tiers = opts.modelsConfig?.claude;
+  if (!tiers) return content;
+  return pinBareModelAlias(content, {
+    reasoning: tiers.reasoning?.model,
+    coding: tiers.coding?.model,
+    efficiency: tiers.efficiency?.model,
+  });
+}
+
+const BARE_MODEL_ALIAS_ROLE = { opus: 'reasoning', sonnet: 'coding', haiku: 'efficiency' };
+
+/**
+ * Replace a bare `model: opus|sonnet|haiku` frontmatter alias with the pinned
+ * variant for its role. Anything else (pinned ids, `inherit`, `sonnet[1m]`,
+ * placeholders) is returned unchanged.
+ */
+export function pinBareModelAlias(content, pinned) {
+  if (!content.startsWith('---')) return content;
+  const fmEnd = content.indexOf('\n---', 3);
+  if (fmEnd === -1) return content;
+  const header = content.slice(0, fmEnd + 4);
+  const body = content.slice(fmEnd + 4);
+  const match = header.match(/^model:[ \t]*['"]?([A-Za-z]+)['"]?[ \t]*$/m);
+  if (!match) return content;
+  const alias = match[1].toLowerCase();
+  const role = BARE_MODEL_ALIAS_ROLE[alias];
+  const target = role ? pinned?.[role] : null;
+  if (!target || target === alias) return content;
+  return header.replace(match[0], `model: ${target}`) + body;
 }
 
 /**
@@ -510,7 +546,7 @@ export async function deploy(opts) {
   const agentFiles = [];
   const commandFiles = [];
   const skillDirs = [];
-  const ruleFiles = [];
+  let ruleFiles = [];
 
   // Check for addon-style directory structure (direct agents/, commands/, skills/ subdirs)
   // This handles deployment when --source points to an addon directory
@@ -628,7 +664,17 @@ export async function deploy(opts) {
     pruneStaleAiwgSkills(kernelDestDir, computeAllKernelNames(srcRoot), opts);
   }
 
+  const inlineBudgetTokens = resolveRulesInlineBudgetTokens();
+  let demotedRuleNames = [];
   if (shouldDeployRules || rulesOnly) {
+    // Inline budget (#2562): rules a previous pass already moved on demand are
+    // not re-inlined; the directory is reconciled against the budget after
+    // this pass deploys (see below).
+    const sidecar = readRuleBudgetSidecar(path.join(target, paths.rules));
+    if (sidecar && sidecar.budgetTokens === inlineBudgetTokens && sidecar.demoted.length > 0) {
+      const skip = new Set(sidecar.demoted);
+      ruleFiles = ruleFiles.filter((f) => !skip.has(path.basename(f).replace(/\.md$/, '')));
+    }
     // Try assembled rules index (combines all component indexes)
     const assembled = assembleRulesIndex(srcRoot);
     if (assembled) {
@@ -661,7 +707,17 @@ export async function deploy(opts) {
     // On-demand index (#1673): list the MEDIUM/LOW rules that were tier-gated
     // out of the always-on set so agents can fetch them via `aiwg show rule`.
     const rulesDestDir = path.join(target, paths.rules);
-    const onDemandCount = writeOnDemandRuleIndex(rulesDestDir, listOnDemandRuleFiles(srcRoot), opts);
+    // Keep the always-on directory small enough that a subagent dispatch
+    // still fits (#2562). Demoted HIGH rules remain binding and are listed
+    // in RULES-ONDEMAND.md with their fetch hint.
+    const budget = reconcileInlineRuleBudget(rulesDestDir, inlineBudgetTokens, opts);
+    demotedRuleNames = budget.demoted;
+    if (budget.removed.length > 0 && !opts.quiet) {
+      console.log(`  Inline rule budget: ${budget.removed.length} HIGH rule(s) moved on demand to fit ${inlineBudgetTokens.toLocaleString()} tokens: ${budget.removed.join(', ')} (see RULES-ONDEMAND.md)`);
+    }
+    const onDemandCount = writeOnDemandRuleIndex(rulesDestDir, listOnDemandRuleFiles(srcRoot), {
+      ...opts, demotedNames: demotedRuleNames, inlineBudgetTokens,
+    });
     if (verbose && onDemandCount > 0) {
       console.log(`  On-demand rules (not inlined): ${onDemandCount} → RULES-ONDEMAND.md`);
     }
@@ -700,6 +756,7 @@ export default {
   transformAgent,
   transformCommand,
   mapModel,
+  pinBareModelAlias,
   deployAgents,
   deployCommands,
   deploySkills,

package/tools/agents/providers/codex.mjs

@@ -263,6 +263,9 @@ export async function deployCommands(targetDir, srcRoot, opts) {
     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',
@@ -302,10 +305,16 @@ export async function deploySkills(targetDir, srcRoot, opts) {
 
   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',

package/tools/skills/deploy-skills-codex.mjs

@@ -44,6 +44,66 @@ const MAX_NAME_LENGTH = 100;
 const MAX_DESCRIPTION_LENGTH = 500;
 const LEGACY_RENAMED_SKILLS = new Set(['aiwg-mcp']);
 
+/** Codex's built-in startup skill-listing cap, in characters (see doctor). */
+export const CODEX_LISTING_CHAR_CAP = 8000;
+
+export function resolveCodexListingCap(env = process.env) {
+  const raw = env.AIWG_CODEX_LISTING_CAP;
+  if (raw === undefined || raw === '') return CODEX_LISTING_CHAR_CAP;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : CODEX_LISTING_CHAR_CAP;
+}
+
+/** Chars one skill contributes to Codex's startup listing ("- name: desc\n"). */
+export function listingEntryChars(name, description) {
+  return String(name ?? '').length + String(description ?? '').length + 5;
+}
+
+function deployedSkillListing(skillDir) {
+  let raw;
+  try { raw = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8'); } catch { return null; }
+  const fm = raw.match(/^---\n([\s\S]*?)\n---/)?.[1];
+  if (!fm) return null;
+  const name = stripWrappingQuotes(fm.match(/^\s*name:\s*(.+?)\s*$/m)?.[1] ?? '');
+  const description = stripWrappingQuotes(fm.match(/^\s*description:\s*(.+?)\s*$/m)?.[1] ?? '');
+  return name ? { name, description } : null;
+}
+
+/**
+ * Decide which planned skills must leave the startup-visible kernel dir so
+ * the projected listing stays under the cap (#2561). Existing kernel skills
+ * that this run does not replace count toward the projection. Kernel-flagged
+ * skills are never demoted; the rest are demoted largest-entry-first so the
+ * fewest skills lose startup visibility. Returns the demoted set plus the
+ * projected listing sizes for reporting.
+ */
+export function planCodexListingBudget(planned, kernelDir, cap) {
+  const incomingNames = new Set(planned.map((item) => item.skill.name));
+  let projected = 0;
+  let existing = 0;
+  if (fs.existsSync(kernelDir)) {
+    for (const entry of fs.readdirSync(kernelDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const listing = deployedSkillListing(path.join(kernelDir, entry.name));
+      if (!listing || incomingNames.has(listing.name) || incomingNames.has(entry.name)) continue;
+      existing += listingEntryChars(listing.name, listing.description);
+    }
+  }
+  projected = existing + planned.reduce((sum, item) => sum + listingEntryChars(item.skill.name, item.skill.description), 0);
+  const before = projected;
+  const demoted = new Set();
+  if (!cap || projected <= cap) return { demoted, before, after: projected, cap };
+  const demotable = planned
+    .filter((item) => !item.kernel)
+    .sort((a, b) => listingEntryChars(b.skill.name, b.skill.description) - listingEntryChars(a.skill.name, a.skill.description));
+  for (const item of demotable) {
+    if (projected <= cap) break;
+    demoted.add(item);
+    projected -= listingEntryChars(item.skill.name, item.skill.description);
+  }
+  return { demoted, before, after: projected, cap };
+}
+
 function parseArgs() {
   const args = process.argv.slice(2);
   const cfg = {
@@ -53,6 +113,17 @@ function parseArgs() {
     dryRun: false,
     force: false,
     copyStandardSkills: false,
+    // Codex lists every skill under the kernel dir at startup and truncates the
+    // listing at 8,000 chars. Skills that would push the listing past the cap
+    // are placed on the standard tier instead (#2561). The budget is active
+    // only when the caller names a standard tier (`--standard-target`, set by
+    // the codex provider for project deploys) or passes `--listing-cap`
+    // explicitly; standalone/legacy home-dir invocations keep deploying every
+    // selected skill to the target. 0 disables the budget.
+    listingCap: resolveCodexListingCap(),
+    listingCapExplicit: false,
+    listingBudget: false,
+    standardTarget: null,
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -63,6 +134,9 @@ function parseArgs() {
     else if (a === '--dry-run') cfg.dryRun = true;
     else if (a === '--force') cfg.force = true;
     else if (a === '--copy-all' || a === '--copy-standard-skills') cfg.copyStandardSkills = true;
+    else if (a === '--listing-cap' && args[i + 1]) { cfg.listingCap = Math.max(0, Number(args[++i]) || 0); cfg.listingCapExplicit = true; }
+    else if (a === '--standard-target' && args[i + 1]) cfg.standardTarget = path.resolve(args[++i]);
+    else if (a === '--listing-budget') cfg.listingBudget = true;
   }
 
   cfg.mode = normalizeDeploymentMode(cfg.mode);
@@ -492,6 +566,9 @@ function isFullAiwgSourceRoot(srcRoot) {
     }
   }
 
+  // Plan every skill first so the listing budget can be judged across the
+  // whole run rather than per source directory (#2561).
+  const planned = [];
   for (const { dir, label } of skillDirs) {
     const found = findSkillDirs(dir);
     if (found.length === 0) continue;
@@ -503,10 +580,6 @@ function isFullAiwgSourceRoot(srcRoot) {
       : found.filter(s => isKernelSkill(s));
     if (skills.length === 0) continue;
 
-    for (const s of skills) desiredNames.add(path.basename(s));
-
-    console.log(`\n${label} (${skills.length} skills):`);
-
     for (const skillDir of skills) {
       const skill = transformToCodexSkill(skillDir);
       if (!skill) {
@@ -516,11 +589,52 @@ function isFullAiwgSourceRoot(srcRoot) {
         totalSkipped++;
         continue;
       }
+      planned.push({ skill, skillDir, label, kernel: isKernelSkill(skillDir) });
+    }
+  }
 
-      const result = deploySkill(skill, target, { force, dryRun });
-      if (result.action === 'deploy') totalDeployed++;
-      else totalSkipped++;
+  const standardTarget = cfg.standardTarget
+    || path.join(path.dirname(path.dirname(target)), '.codex', '.aiwg', 'skills');
+  // An operator `--copy-all` asks for every standard skill in the listing;
+  // honoring the cap there would silently undo the request and break the
+  // documented kernel/standard contract. `--listing-budget` is how the caller
+  // says the copy-all was its own doing (project-local bundles force it so
+  // their skills are reachable at all) and the cap still applies (#2561).
+  const budgetActive = cfg.listingCapExplicit
+    || cfg.listingBudget
+    || (Boolean(cfg.standardTarget) && !copyStandardSkills);
+  const budget = planCodexListingBudget(planned, target, budgetActive ? cfg.listingCap : 0);
+  for (const item of planned) {
+    if (budget.demoted.has(item)) continue;
+    desiredNames.add(path.basename(item.skillDir));
+    desiredNames.add(item.skill.name);
+  }
+
+  let currentLabel = null;
+  for (const item of planned) {
+    if (item.label !== currentLabel) {
+      currentLabel = item.label;
+      console.log(`\n${item.label} (${planned.filter((p) => p.label === item.label).length} skills):`);
     }
+    const demoted = budget.demoted.has(item);
+    const result = deploySkill(item.skill, demoted ? standardTarget : target, { force, dryRun });
+    if (demoted) console.log(`    ↳ standard tier (${path.relative(process.cwd(), standardTarget) || standardTarget}) — startup listing budget`);
+    if (result.action === 'deploy') totalDeployed++;
+    else totalSkipped++;
+  }
+
+  if (budget.demoted.size > 0) {
+    const names = [...budget.demoted].map((item) => item.skill.name).join(', ');
+    console.log(
+      `\nCodex listing budget: ${budget.demoted.size} skill(s) placed on the standard tier so the startup listing ` +
+      `stays at ~${budget.after.toLocaleString()} of ${budget.cap.toLocaleString()} chars (was ~${budget.before.toLocaleString()}): ${names}. ` +
+      'They remain reachable through `aiwg discover` / `aiwg show`. Override with --listing-cap <chars> (0 disables) or AIWG_CODEX_LISTING_CAP.',
+    );
+  } else if (budgetActive && budget.cap && budget.after > budget.cap) {
+    console.log(
+      `\nWarning: kernel skills alone estimate ~${budget.after.toLocaleString()} chars, above Codex's ${budget.cap.toLocaleString()}-char listing cap; ` +
+      'nothing non-kernel is left to demote.',
+    );
   }
 
   // Post-deploy cleanup: remove AIWG-managed skills that are stale for the