@aiwg/cli 2026.8.7 → 2026.8.10

package/dist/src/smiths/context-pipeline/finalization.js

@@ -10,7 +10,7 @@ import * as path from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { readAiwgConfig } from '../../config/aiwg-config.js';
-import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from '../../config/project-artifacts.js';
 import { renderTrackerProtocol, resolveTrackerAuthority } from '../../tracker/capability-protocol.js';
 import { buildExternalLinksSection, replaceOrAppendExternalLinksBlock, } from './external-links-section.js';
 export const FINALIZATION_START = '<!-- aiwg-context-finalization:START -->';
@@ -61,7 +61,7 @@ export async function buildContextFinalizationBlock(projectPath) {
     const installed = Object.entries(config?.installed ?? {});
     const installedNames = installed.map(([name]) => name);
     const providerDeployments = new Set();
-    const normalizedAiwgMdPath = displayProjectPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
+    const normalizedAiwgMdPath = displayProjectPath(projectPath, projectControlPath(projectPath, 'AIWG.md'));
     const normalizedAiwgMdLabel = `\`${normalizedAiwgMdPath}\``;
     for (const [, entry] of installed) {
         for (const provider of Object.keys(entry.deployedTo ?? {})) {
@@ -114,7 +114,7 @@ export function replaceOrAppendFinalizationBlock(content, block) {
 export async function buildNormalizedAiwgMd(projectPath, existing = '') {
     const block = await buildContextFinalizationBlock(projectPath);
     const externalLinksSection = await buildExternalLinksSection(projectPath);
-    const normalizedAiwgMdPath = displayProjectPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
+    const normalizedAiwgMdPath = displayProjectPath(projectPath, projectControlPath(projectPath, 'AIWG.md'));
     const base = existing.trim().length > 0
         ? existing
         : [
@@ -132,7 +132,7 @@ export async function buildNormalizedAiwgMd(projectPath, existing = '') {
     return replaceOrAppendExternalLinksBlock(withFinalization, externalLinksSection);
 }
 export async function writeNormalizedAiwgMd(projectPath) {
-    const targetPath = projectAiwgPath(projectPath, 'AIWG.md');
+    const targetPath = projectControlPath(projectPath, 'AIWG.md');
     let existing = '';
     try {
         existing = await fs.readFile(targetPath, 'utf8');
@@ -143,7 +143,20 @@ export async function writeNormalizedAiwgMd(projectPath) {
     }
     const content = await buildNormalizedAiwgMd(projectPath, existing);
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
-    await fs.writeFile(targetPath, content.endsWith('\n') ? content : `${content}\n`, 'utf8');
+    const normalizedContent = content.endsWith('\n') ? content : `${content}\n`;
+    await fs.writeFile(targetPath, normalizedContent, 'utf8');
+    const artifactRoot = resolveProjectAiwgDir(projectPath);
+    const artifactPath = projectAiwgPath(projectPath, 'AIWG.md');
+    if (artifactPath !== targetPath) {
+        try {
+            await fs.access(artifactRoot);
+            await fs.writeFile(artifactPath, normalizedContent, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
     return targetPath;
 }
 //# sourceMappingURL=finalization.js.map

package/dist/src/smiths/context-pipeline/generator.js

@@ -21,7 +21,7 @@ import { shouldEmitAgentsMd, shouldEmitAiwgMd, shouldEmitClaudeMdHook } from './
 import { ensureClaudeMdHook } from './claude-hook.js';
 import { ensureManagedHook } from './managed-hook.js';
 import { buildProviderBootstrapBlock, ensureWorkspaceContext, registerProviderContext, } from './workspace-context.js';
-import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { projectControlPath } from '../../config/project-artifacts.js';
 const SECTION_TITLES = {
     agents: 'Agents',
     rules: 'Rules',
@@ -137,7 +137,7 @@ export async function buildAgentsMd(opts) {
     parts.push('');
     parts.push('See [AIWG.md](./AIWG.md) for the full AIWG framework context');
     parts.push('(active frameworks, addons, agents, behaviors, rules).');
-    const configRelative = path.relative(opts.projectPath, projectAiwgPath(opts.projectPath, 'aiwg.config')).replace(/\\/g, '/');
+    const configRelative = path.relative(opts.projectPath, projectControlPath(opts.projectPath, 'aiwg.config')).replace(/\\/g, '/');
     const configLink = configRelative.startsWith('.') ? configRelative : `./${configRelative}`;
     parts.push(`Tracker and delivery source of truth: [${configRelative}](${configLink}).`);
     parts.push('');

package/dist/src/smiths/context-pipeline/workspace-context.js

@@ -12,7 +12,8 @@ import * as path from 'node:path';
 import { buildAiwgMdContent } from './aiwg-md.js';
 import { buildNormalizedAiwgMd } from './finalization.js';
 import { getProviderDefinition, listProviderDefinitions, } from '../../providers/provider-definitions.js';
-import { projectAiwgPath, resolveProjectAiwgDir } from '../../config/project-artifacts.js';
+import { readAiwgConfig } from '../../config/aiwg-config.js';
+import { projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from '../../config/project-artifacts.js';
 export const WORKSPACE_MANAGED_START = '<!-- AIWG:workspace-context:start -->';
 export const WORKSPACE_MANAGED_END = '<!-- AIWG:workspace-context:end -->';
 export const WORKSPACE_OPERATOR_START = '<!-- AIWG:workspace-operator:start -->';
@@ -306,8 +307,8 @@ function providerForPath(relativePath) {
     }
     return null;
 }
-function projectArtifactMarkdownPath(projectPath, ...segments) {
-    const rel = path.relative(projectPath, projectAiwgPath(projectPath, ...segments)).replace(/\\/g, '/');
+function projectControlMarkdownPath(projectPath, ...segments) {
+    const rel = path.relative(projectPath, projectControlPath(projectPath, ...segments)).replace(/\\/g, '/');
     if (rel === '')
         return '.';
     return rel.startsWith('.') ? rel : `./${rel}`;
@@ -315,14 +316,15 @@ function projectArtifactMarkdownPath(projectPath, ...segments) {
 function workspaceLinks(projectPath, providerFiles = []) {
     const links = new Set([
         '[AIWG framework context](./AIWG.md)',
-        `[AIWG project configuration](${projectArtifactMarkdownPath(projectPath, 'aiwg.config')})`,
+        `[AIWG project configuration](${projectControlMarkdownPath(projectPath, 'aiwg.config')})`,
     ]);
     if (providerFiles.length > 0) {
         for (const file of providerFiles)
             links.add(`[Provider-specific context](./${file.replace(/\\/g, '/')})`);
     }
-    // The quickref source is linked, not copied into each provider directory.
-    links.add(`[Project-local quickref](${projectArtifactMarkdownPath(projectPath, 'quickref.json')}) (when configured)`);
+    // Keep the logical project path portable in committed context. Runtime
+    // quickref readers follow `.aiwg-location` to the external corpus.
+    links.add('[Project-local quickref](.aiwg/quickref.json) (when configured)');
     return [...links];
 }
 export function buildWorkspaceManagedBlock(projectPath, providerFiles = []) {
@@ -692,16 +694,13 @@ function providerMigrationContent(source) {
     ].join('\n');
 }
 async function configuredProviders(projectPath) {
-    const config = await readOptional(projectAiwgPath(projectPath, 'aiwg.config'));
-    if (config) {
-        try {
-            const parsed = JSON.parse(config);
-            if (Array.isArray(parsed.providers))
-                return parsed.providers.filter((provider) => typeof provider === 'string');
-        }
-        catch {
-            // Audit/migration reports malformed provider config through the normal CLI path.
-        }
+    try {
+        const config = await readAiwgConfig(projectPath);
+        if (config)
+            return config.providers.filter((provider) => typeof provider === 'string');
+    }
+    catch {
+        // Audit/migration reports malformed provider config through the normal CLI path.
     }
     return ['claude'];
 }
@@ -783,7 +782,7 @@ async function stageMigrationWrites(projectPath, audit, options = {}) {
         writes.set(configPath, `${JSON.stringify(config, null, 2)}\n`);
     }
     if (options.includeGeneratedContext) {
-        const normalizedPath = projectOutputPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
+        const normalizedPath = projectOutputPath(projectPath, projectControlPath(projectPath, 'AIWG.md'));
         const existingNormalized = await readOptional(path.join(projectPath, normalizedPath)) ?? '';
         writes.set(normalizedPath, await buildNormalizedAiwgMd(projectPath, existingNormalized));
         const stagedClaude = writes.has('CLAUDE.md')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.7",
+  "version": "2026.8.10",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,7 @@
   },
   "files": [
     "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
     "bin/",
     "agentic/code/providers/",
     "dist/src/",

package/tools/agents/deploy-agents.mjs

@@ -20,7 +20,7 @@
  *   --rules-only             Deploy only rules (skip agents)
  *   --dry-run                Show what would be deployed without writing
  *   --force                  Overwrite existing files
- *   --provider <name>        Target provider: claude (default), openai, codex, cursor, opencode, copilot, factory, warp, windsurf, hermes, or openclaw
+ *   --provider <name>        Target provider: claude (default), openai, codex, cursor, opencode, copilot, factory, warp, devin, hermes, or openclaw
  *   --model <name>            Override model for all tiers (blanket)
  *   --reasoning-model <name> Override model for reasoning tasks
  *   --coding-model <name>    Override model for coding tasks
@@ -49,7 +49,8 @@
  *   copilot   - GitHub Copilot - .github/agents/, .github/commands/, .github/skills/, .github/copilot-rules/
  *   cursor    - Cursor IDE - .cursor/agents/, .cursor/commands/, .cursor/skills/, .cursor/rules/
  *   warp      - Warp Terminal - .warp/agents/, .warp/commands/, .warp/skills/, .warp/rules/ + WARP.md
- *   windsurf  - Windsurf - .windsurf/agents/, .windsurf/workflows/, .windsurf/skills/, .windsurf/rules/
+ *   devin     - Devin Desktop - .windsurf/agents/, .windsurf/workflows/, .windsurf/skills/, .windsurf/rules/
+ *   windsurf  - Deprecated alias for devin
  *   openclaw  - OpenClaw - ~/.openclaw/agents/, ~/.openclaw/commands/, ~/.openclaw/skills/, ~/.openclaw/rules/, ~/.openclaw/behaviors/
  *
  * Defaults:
@@ -103,6 +104,7 @@ function getDeployVersion(srcRoot) {
 
 const PROVIDER_ALIASES = {
   'openai': 'codex',
+  'devin': 'windsurf',
   'devin-desktop': 'windsurf',
   'devin-local': 'windsurf',
   'cascade': 'windsurf',
@@ -111,15 +113,9 @@ const PROVIDER_ALIASES = {
 const AVAILABLE_PROVIDERS = ['claude', 'factory', 'codex', 'opencode', 'copilot', 'cursor', 'warp', 'windsurf', 'hermes', 'openclaw', 'openhuman'];
 
 const UNSUPPORTED_PROVIDER_HINTS = {
-  devin: [
-    'Devin Desktop is supported through the Windsurf compatibility adapter:',
-    '  aiwg use sdlc --provider windsurf',
-    '  aiwg use sdlc --provider devin-desktop',
-    'Devin CLI has distinct rules/skills surfaces and is recorded as future-provider metadata; AIWG does not emit .devin/ provider output yet.',
-  ],
   'devin-cli': [
     'Devin CLI has distinct rules/skills surfaces and is not a deployable AIWG provider yet.',
-    'Use --provider windsurf or --provider devin-desktop for Devin Desktop/Windsurf local IDE deployments.',
+    'Use --provider devin for Devin Desktop deployments.',
   ],
 };
 
@@ -531,7 +527,7 @@ Providers (all deploy agents, commands, skills, and rules):
               Paths: .cursor/agents/, .cursor/commands/, .cursor/skills/, .cursor/rules/
   warp      - Warp Terminal
               Paths: .warp/agents/, .warp/commands/, .warp/skills/, .warp/rules/ + WARP.md
-  windsurf  - Windsurf
+  devin     - Devin Desktop (preferred; aliases: devin-desktop, windsurf)
               Paths: .windsurf/agents/, .windsurf/workflows/, .windsurf/skills/, .windsurf/rules/
   hermes    - Hermes Agent (MCP-based integration)
               Skills: ~/.hermes/skills/ (user-global) | Agents: AGENTS.md (lean routing guide)
@@ -865,7 +861,10 @@ export async function main() {
     srcRoot,
     target: cfg.target,
     mode: cfg.mode,
-    provider: cfg.provider,
+    // Provider aliases are selectors, not artifact identities. Passing the
+    // canonical id keeps generated frontmatter byte-identical for devin,
+    // devin-desktop, and the deprecated windsurf selector.
+    provider: resolveProvider(cfg.provider),
     dryRun: cfg.dryRun,
     force: cfg.force,
     reasoningModel: cfg.reasoningModel,

package/tools/agents/providers/base.mjs

@@ -44,6 +44,48 @@ export function ensureDir(d, dryRun = false) {
   if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
 }
 
+const PROJECT_ARTIFACT_ENV_KEYS = [
+  'AIWG_ARTIFACTS_PATH',
+  'AIWG_PROJECT_ARTIFACTS_PATH',
+  'AIWG_PROJECT_AIWG_DIR',
+];
+
+function expandProjectArtifactPath(value, projectDir) {
+  const trimmed = value.trim();
+  if (trimmed === '~') return os.homedir();
+  if (trimmed.startsWith('~/')) return path.resolve(os.homedir(), trimmed.slice(2));
+  return path.isAbsolute(trimmed) ? trimmed : path.resolve(projectDir, trimmed);
+}
+
+function parseProjectArtifactLocation(contents) {
+  for (const rawLine of contents.split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('export ')) line = line.slice('export '.length).trim();
+    const assignment = line.match(/^AIWG_ARTIFACTS_PATH\s*=\s*(.+)$/);
+    if (assignment) line = assignment[1].trim();
+    if ((line.startsWith('"') && line.endsWith('"')) || (line.startsWith("'") && line.endsWith("'"))) {
+      line = line.slice(1, -1);
+    }
+    return line || null;
+  }
+  return null;
+}
+
+/** Resolve the artifact corpus root used for framework-generated workspace data. */
+export function resolveFrameworkWorkspaceRoot(projectDir, env = process.env) {
+  for (const key of PROJECT_ARTIFACT_ENV_KEYS) {
+    const value = env[key];
+    if (typeof value === 'string' && value.trim()) return expandProjectArtifactPath(value, projectDir);
+  }
+  const pointer = path.join(projectDir, '.aiwg-location');
+  if (fs.existsSync(pointer)) {
+    const configured = parseProjectArtifactLocation(fs.readFileSync(pointer, 'utf8'));
+    if (configured) return expandProjectArtifactPath(configured, projectDir);
+  }
+  return path.join(projectDir, '.aiwg');
+}
+
 /**
  * List markdown files in a directory (non-recursive)
  */
@@ -1441,7 +1483,7 @@ export function deploySkillDir(skillDir, destDir, opts) {
  * Creates .aiwg/frameworks/{framework-id}/ directories
  */
 export function initializeFrameworkWorkspace(target, mode, dryRun, srcRoot = null) {
-  const aiwgBase = path.join(target, '.aiwg');
+  const aiwgBase = resolveFrameworkWorkspaceRoot(target);
   const frameworksDir = path.join(aiwgBase, 'frameworks');
   const sharedDir = path.join(aiwgBase, 'shared');
 
@@ -1498,7 +1540,7 @@ export function initializeFrameworkWorkspace(target, mode, dryRun, srcRoot = nul
       }
       for (const entry of fw.memoryCreates || []) {
         if (entry && typeof entry.path === 'string') {
-          console.log(`[dry-run]   ${path.join(target, entry.path)}${entry.path.endsWith('/') ? '/' : ''}`);
+          console.log(`[dry-run]   ${path.join(aiwgBase, entry.path.slice('.aiwg/'.length))}${entry.path.endsWith('/') ? '/' : ''}`);
         }
       }
     }
@@ -1515,7 +1557,7 @@ export function initializeFrameworkWorkspace(target, mode, dryRun, srcRoot = nul
     for (const subdir of fw.subdirs) {
       ensureDir(path.join(fwBase, subdir));
     }
-    initializeMemoryCreates(target, fw.path, fw.memoryCreates);
+    initializeMemoryCreates(aiwgBase, fw.path, fw.memoryCreates);
   }
 
   // Initialize registry.json if it doesn't exist
@@ -1536,12 +1578,12 @@ export function initializeFrameworkWorkspace(target, mode, dryRun, srcRoot = nul
 }
 
 
-function initializeMemoryCreates(target, frameworkPath, creates) {
+function initializeMemoryCreates(aiwgBase, frameworkPath, creates) {
   for (const entry of creates || []) {
     if (!entry || typeof entry.path !== 'string') continue;
     if (!entry.path.startsWith('.aiwg/')) continue;
 
-    const targetPath = path.join(target, entry.path);
+    const targetPath = path.join(aiwgBase, entry.path.slice('.aiwg/'.length));
     const isDirectory = entry.path.endsWith('/') || path.extname(entry.path) === '';
     if (isDirectory) {
       ensureDir(targetPath);

package/tools/agents/providers/openclaw.mjs

@@ -209,10 +209,13 @@ function deploySkills(skillDirs, opts) {
     ? skillDirs
     : skillDirs.filter(d => isKernelSkill(d));
   if (crossAgentSkills.length > 0) {
-    const crossAgentDir = path.join(process.cwd(), '.agents', 'skills');
+    // Honor the deployment target selected by `aiwg use --target`. Provider
+    // subprocesses execute from AIWG_ROOT so process.cwd() would otherwise
+    // mutate the framework checkout during isolated/project-targeted deploys.
+    const crossAgentDir = path.join(opts.target || process.cwd(), '.agents', 'skills');
     ensureDir(crossAgentDir, opts.dryRun);
     if (!opts.dryRun) {
-      console.log(`Deploying cross-agent skills to ${path.relative(process.cwd(), crossAgentDir)}...`);
+      console.log(`Deploying cross-agent skills to ${path.relative(opts.target || process.cwd(), crossAgentDir)}...`);
     } else {
       console.log(`[dry-run] Would deploy cross-agent skills to .agents/skills/`);
     }

package/tools/agents/providers/windsurf.mjs

@@ -1,7 +1,9 @@
 /**
- * Windsurf Provider (EXPERIMENTAL)
+ * Devin Desktop Provider (Windsurf compatibility adapter)
  *
- * Deploys agents to Windsurf format with aggregated AGENTS.md and trigger-frontmatter rules.
+ * Deploys agents to the Devin Desktop/Windsurf compatibility surface with
+ * aggregated AGENTS.md and trigger-frontmatter rules. The provider id and
+ * generated `.windsurf/` paths remain stable for backward compatibility.
  *
  * Deployment paths:
  *   - Output: AGENTS.md (aggregated agents)
@@ -18,7 +20,7 @@
  *   - Capabilities tags for tools
  *   - Workflow format for commands
  *   - Conventional skills and rules deployment
- *   - EXPERIMENTAL: Untested, may require adjustments
+ *   - Devin Desktop selectors resolve to the stable `windsurf` provider id
  */
 
 import realFs from 'fs';
@@ -57,7 +59,7 @@ import {
 // ============================================================================
 
 export const name = 'windsurf';
-export const aliases = [];
+export const aliases = ['devin', 'devin-desktop', 'devin-local', 'cascade'];
 
 export const paths = {
   agents: '.windsurf/agents/',      // Discrete mirrors alongside AGENTS.md
@@ -85,17 +87,6 @@ export const capabilities = {
   yamlFormat: false
 };
 
-// ============================================================================
-// Warning Display
-// ============================================================================
-
-function displayWarning() {
-  console.log('\n' + '='.repeat(70));
-  console.log('[EXPERIMENTAL] Windsurf provider support is experimental and untested.');
-  console.log('Please report issues: https://github.com/jmagly/aiwg/issues');
-  console.log('='.repeat(70) + '\n');
-}
-
 // ============================================================================
 // Content Transformation
 // ============================================================================
@@ -253,12 +244,12 @@ export function generateAgentsMd(files, destPath, opts) {
   // refuses to replace the legacy 2MB+ aggregate writer's output.
   lines.push('<!-- aiwg-managed -->');
   lines.push('');
-  lines.push('> AIWG Agent Directory for Windsurf');
+  lines.push('> AIWG Agent Directory for Devin Desktop');
   lines.push('');
   lines.push('<!--');
-  lines.push('  [EXPERIMENTAL] Generated by AIWG for Windsurf');
-  lines.push('  Windsurf reads this file for directory-scoped AI instructions.');
-  lines.push('  See: https://docs.windsurf.com/windsurf/cascade/agents-md');
+  lines.push('  Generated by AIWG for Devin Desktop using the Windsurf compatibility adapter.');
+  lines.push('  Devin Desktop reads this file for directory-scoped AI instructions.');
+  lines.push('  See: https://docs.devin.ai/onboard-devin/agents-md');
   lines.push('-->');
   lines.push('');
   lines.push('## Table of Contents');
@@ -316,10 +307,10 @@ export function generateWindsurfRules(srcRoot, target, opts) {
   lines.push('trigger: always_on');
   lines.push('---');
   lines.push('');
-  lines.push('# AIWG Orchestration for Windsurf');
+  lines.push('# AIWG Orchestration for Devin Desktop');
   lines.push('');
   lines.push('<!--');
-  lines.push('  [EXPERIMENTAL] Generated by AIWG for Windsurf');
+  lines.push('  Generated by AIWG for Devin Desktop using the Windsurf compatibility adapter.');
   lines.push('  This file provides orchestration context for AIWG SDLC workflows.');
   lines.push('  trigger: always_on — included in system prompt on every message.');
   lines.push('-->');
@@ -556,9 +547,7 @@ export async function deploy(opts) {
     dryRun
   } = opts;
 
-  displayWarning();
-
-  console.log(`\n=== Windsurf Provider (EXPERIMENTAL) ===`);
+  console.log(`\n=== Devin Desktop Provider (windsurf compatibility adapter) ===`);
   console.log(`Target: ${target}`);
   console.log(`Mode: ${mode}`);
   const normalizedMode = normalizeDeploymentMode(mode);

package/tools/plugin/package-plugins.mjs

@@ -657,6 +657,13 @@ for (const [id, sourceRoot] of MANIFEST_PLUGIN_SOURCES) {
     keywords: manifest.keywords || manifest.tags || [],
     category: manifest.category || 'productivity',
     sourceRoot,
+    declaredSkills: manifest.skills ?? [],
+    // Plugin payloads run outside the checkout. Rewrite references back to
+    // their packaged root, including the pre-rename Ralph path retained by
+    // older Agent Loop documentation.
+    selfReferenceRoots: id === 'agent-loop'
+      ? [sourceRoot, 'agentic/code/addons/ralph']
+      : [sourceRoot],
   };
 }
 
@@ -774,6 +781,48 @@ function copyDir(src, dest, dryRun = false, filter = null) {
   return copied;
 }
 
+function rewritePackagedSelfReferences(pluginDir, roots = []) {
+  if (roots.length === 0) return;
+  const pending = [pluginDir];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const target = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        pending.push(target);
+      } else if (entry.isFile() && /\.(?:md|json|ya?ml)$/.test(entry.name)) {
+        const original = fs.readFileSync(target, 'utf8');
+        let rewritten = original;
+        for (const root of roots) {
+          rewritten = rewritten.replaceAll(`${root}/`, '${CLAUDE_PLUGIN_ROOT}/');
+        }
+        if (rewritten !== original) fs.writeFileSync(target, rewritten, 'utf8');
+      }
+    }
+  }
+}
+
+function pruneUndeclaredPackagedSkills(pluginDir, declaredSkills) {
+  if (!declaredSkills) return;
+  const skillsRoot = path.join(pluginDir, 'skills');
+  if (!fs.existsSync(skillsRoot)) return;
+  const allowed = new Set(declaredSkills);
+  for (const entry of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (entry.isDirectory() && !allowed.has(entry.name)) {
+      fs.rmSync(path.join(skillsRoot, entry.name), { recursive: true, force: true });
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const skillId = path.basename(entry.name, '.md');
+      if (allowed.has(skillId)) {
+        const skillDir = path.join(skillsRoot, skillId);
+        fs.mkdirSync(skillDir, { recursive: true });
+        fs.renameSync(path.join(skillsRoot, entry.name), path.join(skillDir, 'SKILL.md'));
+      } else {
+        fs.rmSync(path.join(skillsRoot, entry.name), { force: true });
+      }
+    }
+  }
+}
+
 // Clean plugin directory (except .claude-plugin)
 function cleanPlugin(pluginDir) {
   if (!fs.existsSync(pluginDir)) return;
@@ -811,6 +860,10 @@ function packagePlugin(name, config, options) {
     console.log(`  📁 Copying self-contained source from ${config.sourceRoot}...`);
     const count = copyDir(config.sourceRoot, pluginDir, options.dryRun);
     console.log(`     ${count} files`);
+    if (!options.dryRun) {
+      rewritePackagedSelfReferences(pluginDir, config.selfReferenceRoots);
+      pruneUndeclaredPackagedSkills(pluginDir, config.declaredSkills);
+    }
   }
 
   // Copy sources

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

@@ -417,6 +417,17 @@ function isFullAiwgSourceRoot(srcRoot) {
   const repoRoot = path.resolve(scriptDir, '..', '..');
   const srcRoot = source || repoRoot;
   const fullAiwgSourceRoot = isFullAiwgSourceRoot(srcRoot);
+  const copyStandardSkills = cfg.copyStandardSkills === true;
+  // Component-scoped deploys (the way `aiwg use all` installs selected
+  // frameworks/addons) still need a complete inventory for stale-skill
+  // reconciliation.  AIWG_ROOT is supplied by the orchestrator for exactly
+  // this purpose; fall back to the script checkout for standalone use.
+  const configuredAiwgRoot = process.env.AIWG_ROOT
+    ? path.resolve(process.env.AIWG_ROOT)
+    : repoRoot;
+  const inventoryRoot = fullAiwgSourceRoot
+    ? srcRoot
+    : (!copyStandardSkills && isFullAiwgSourceRoot(configuredAiwgRoot) ? configuredAiwgRoot : null);
 
   console.log(`Deploying skills to Codex`);
   console.log(`  Source: ${srcRoot}`);
@@ -440,8 +451,6 @@ function isFullAiwgSourceRoot(srcRoot) {
   // Codex normally deploys to the project `.agents/skills/` target, so the
   // kernel/standard split is enforced at filter time rather than via separate
   // destination directories. The standalone legacy default remains supported.
-  const copyStandardSkills = cfg.copyStandardSkills === true;
-
   // Track every AIWG-managed source skill name so we can scope post-deploy
   // cleanup to skills AIWG ships — never delete user-authored or
   // third-party skills sitting alongside.
@@ -457,10 +466,13 @@ function isFullAiwgSourceRoot(srcRoot) {
   // so full-root cleanup can remove stale AIWG skills. Component-scoped
   // cleanup is limited below to names owned by that component, preserving
   // user-authored skills alongside the generated set.
-  for (const { dir } of getSkillDirectories(srcRoot, 'all')) {
+  for (const { dir } of getSkillDirectories(inventoryRoot || srcRoot, 'all')) {
     const allSkills = findSkillDirs(dir);
     for (const s of allSkills) {
       allManagedNames.add(path.basename(s));
+      if (!copyStandardSkills && isKernelSkill(s)) {
+        desiredNames.add(path.basename(s));
+      }
       // Also record the frontmatter `name:` since Codex uses that as the
       // target dir. Best-effort — ignore parse errors.
       try {
@@ -469,7 +481,11 @@ function isFullAiwgSourceRoot(srcRoot) {
         if (fmMatch) {
           const nameMatch = fmMatch[1].match(/^\s*name:\s*(.+?)\s*$/m);
           if (nameMatch) {
-            allManagedNames.add(stripWrappingQuotes(nameMatch[1]));
+            const deployedName = stripWrappingQuotes(nameMatch[1]);
+            allManagedNames.add(deployedName);
+            if (!copyStandardSkills && isKernelSkill(s)) {
+              desiredNames.add(deployedName);
+            }
           }
         }
       } catch { /* ignore */ }
@@ -528,7 +544,7 @@ function isFullAiwgSourceRoot(srcRoot) {
       // the .aiwg-managed marker. Treat only the exact historical names as
       // managed so malformed legacy frontmatter cannot survive an upgrade.
       let isAiwgManaged = allManagedNames.has(name) || LEGACY_RENAMED_SKILLS.has(name);
-      if (!isAiwgManaged && fullAiwgSourceRoot) {
+      if (!isAiwgManaged && (fullAiwgSourceRoot || inventoryRoot)) {
         // Check for the .aiwg-managed marker file (preferred — survives
         // frontmatter transforms) or fall back to namespace check.
         const markerFile = path.join(target, name, '.aiwg-managed');