@aiwg/cli 2026.9.6 → 2026.9.7

package/dist/src/cli/handlers/use.js

@@ -581,6 +581,7 @@ async function mirrorStandardCommandSkills(opts) {
             projectPath: opts.target,
             dryRun: opts.dryRun,
             verbose: opts.verbose,
+            deployVersion: (await getVersionInfo()).version,
             nameFilter: shouldMirrorStandardCommandSkill,
         });
         count += result.translated.length;
@@ -1053,6 +1054,43 @@ async function countBundleDeployedArtifacts(bundlePath, target, provider) {
     };
 }
 const SKILL_SUPPORT_REFERENCE = /(?:^|[\s`('"\[])((?:templates|references|scripts|assets)\/[A-Za-z0-9._@/+\-]+)(?=$|[\s`)'"\],:;])/gm;
+/** Copy one support file, preserving its executable bit. */
+async function copySkillSupportFile(source, destination) {
+    await fs.mkdir(path.dirname(destination), { recursive: true });
+    await fs.copyFile(source, destination);
+    await fs.chmod(destination, (await fs.stat(source)).mode & 0o777);
+}
+/**
+ * Materialize a directory-valued support-asset reference (#2503).
+ *
+ * Applies the same rules the single-file path applies, per entry: symlinks are
+ * refused rather than followed (a link inside a bundle can point anywhere), and
+ * file modes are preserved so script packs stay executable. Empty directories
+ * are still created — a reference to an empty pack is odd but not an error.
+ */
+async function copySkillSupportTree(source, destination, sourceSkillMd, reference, deployFile) {
+    await fs.mkdir(destination, { recursive: true });
+    const label = reference.replace(/\/+$/, '');
+    const entries = await fs.readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+        const from = path.join(source, entry.name);
+        const to = path.join(destination, entry.name);
+        if (entry.isSymbolicLink()) {
+            throw new Error(`unsafe skill support asset '${label}/${entry.name}' referenced by ${sourceSkillMd}: symbolic links are not deployed`);
+        }
+        if (entry.isDirectory()) {
+            await copySkillSupportTree(from, to, sourceSkillMd, `${label}/${entry.name}`, deployFile);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (deployFile) {
+            deployFile(from, to);
+            continue;
+        }
+        await copySkillSupportFile(from, to);
+    }
+}
 /**
  * Skill-relative support files may live beside the skill or at the bundle root
  * (plugin payloads commonly share report templates). Materialize
@@ -1103,11 +1141,18 @@ async function reconcileDeployedSkillAssets(bundlePath, target, provider, option
             }
             const candidates = [path.join(sourceSkillDir, normalized), path.join(bundlePath, normalized)];
             let source;
+            let sourceIsDirectory = false;
             for (const candidate of candidates) {
                 try {
                     const stat = await fs.lstat(candidate);
-                    if (stat.isFile() && !stat.isSymbolicLink()) {
+                    if (stat.isSymbolicLink())
+                        continue;
+                    // A reference may name a whole support directory (a templates pack,
+                    // a references folder). Rejecting those as "missing" aborted the
+                    // bundle deploy over a path that was present all along (#2503).
+                    if (stat.isFile() || stat.isDirectory()) {
                         source = candidate;
+                        sourceIsDirectory = stat.isDirectory();
                         break;
                     }
                 }
@@ -1119,6 +1164,9 @@ async function reconcileDeployedSkillAssets(bundlePath, target, provider, option
                 }
                 continue;
             }
+            if (sourceIsDirectory && declaredEntrypoints.has(relative)) {
+                throw new Error(`skill entrypoint '${relative}' in ${sourceSkillMd} resolves to a directory; an entrypoint must be a file`);
+            }
             let deployedSkillRoot;
             for (const root of deployRoots) {
                 // The deployer may select the bulk or kernel tier; use the tier that
@@ -1131,18 +1179,36 @@ async function reconcileDeployedSkillAssets(bundlePath, target, provider, option
             if (!deployedSkillRoot)
                 throw new Error(`deployed skill '${skillName}' not found while reconciling support assets`);
             const destination = path.join(deployedSkillRoot, skillName, ...normalized.split('/'));
-            if (provider === 'omp') {
-                const adapter = await import(pathToFileURL(path.join(await getFrameworkRoot(), 'tools/agents/providers/omp.mjs')).href);
-                adapter.deploySkillSupportAsset(source, destination, { quiet: true });
+            const deployFile = provider === 'omp'
+                ? await (async () => {
+                    const adapter = await import(pathToFileURL(path.join(await getFrameworkRoot(), 'tools/agents/providers/omp.mjs')).href);
+                    return (from, to) => adapter.deploySkillSupportAsset(from, to, { quiet: true });
+                })()
+                : null;
+            if (sourceIsDirectory) {
+                await copySkillSupportTree(source, destination, sourceSkillMd, relative, deployFile);
+                continue;
+            }
+            if (deployFile) {
+                deployFile(source, destination);
                 continue;
             }
-            await fs.mkdir(path.dirname(destination), { recursive: true });
-            await fs.copyFile(source, destination);
-            const mode = (await fs.stat(source)).mode & 0o777;
-            await fs.chmod(destination, mode);
+            await copySkillSupportFile(source, destination);
         }
     }
 }
+/**
+ * Managed-marker version for a project-local bundle's deployed artifacts (#2502).
+ *
+ * The deployer otherwise derives this from a `package.json` in the `--source`
+ * tree; project-local bundles carry a `manifest.json` instead, so every
+ * artifact was stamped `vunknown`. Falls back to `unknown` only when the
+ * manifest itself omits a version.
+ */
+function projectLocalDeployVersion(bundle) {
+    const version = bundle.manifest.version;
+    return typeof version === 'string' && version.length > 0 ? version : 'unknown';
+}
 /**
  * Deploy a single project-local bundle to one provider via deploy-agents.mjs.
  * Runs the same script and flags used for upstream addons, with the bundle
@@ -1187,6 +1253,12 @@ async function deployOneProjectLocalBundle(opts) {
             // never reach <provider>/.aiwg/skills/, leaving them invisible to
             // both the platform and the index.
             '--copy-all',
+            // Provenance for the managed marker (#2502). Without this the deployer
+            // stamps `bundled`/`unknown`, and `aiwg refresh`'s stale-artifact prune —
+            // whose desired set is the packaged framework corpus — deletes every
+            // project-local agent in the same run that re-deployed it.
+            '--deploy-source', 'project-local',
+            '--deploy-version', projectLocalDeployVersion(bundle),
             ...modelArgs,
         ];
         if (dryRun)
@@ -2122,6 +2194,35 @@ async function mirrorProjectLocalBundleToUserScope(opts) {
  * Deploys framework agents, commands, and skills to the current project,
  * then registers them in the extension registry for discovery.
  */
+const USE_HELP = `Usage: aiwg use <bundle> [options]
+
+Deploy an AIWG framework, addon, or extension into the current project.
+
+Bundles:
+  all                       Kernel surface only (kernel skills, rules, behaviors)
+  sdlc | research | ops | forensics | marketing | media-curator | ...
+                            Full framework surface (agents, commands, skills, rules)
+  <addon> | <extension>     Any installed addon or extension name
+
+Options:
+  --provider <name>         Target provider (default: .aiwg/aiwg.config providers)
+  --target <dir>            Deploy into <dir> instead of the current directory
+  --scope project|user      Deploy to the project (default) or the user scope
+  --force                   Re-write every artifact, replacing files AIWG does
+                            not currently manage. Use this to reclaim a
+                            directory left behind by an older AIWG install.
+  --copy-all                Mirror standard-tier skills into the project instead
+                            of relying on index-driven discovery
+  --dry-run                 Preview the deployment without writing files
+  --verbose, -v             Show per-artifact deploy decisions
+  --json                    Emit the machine-readable deployment result
+  --no-project-local        Skip project-local bundles under .aiwg/
+  --no-context-files        Skip WORKSPACE.md / AIWG.md / AGENTS.md emission
+  -h, --help                Show this help without deploying
+
+Deployment counts report what the run wrote or already manages. Files AIWG does
+not own are listed separately as unmanaged and are never counted as deployed.
+`;
 export class UseHandler {
     id = 'use';
     name = 'Use Framework';
@@ -2129,6 +2230,9 @@ export class UseHandler {
     category = 'framework';
     aliases = [];
     orchestrationDepth = 0;
+    async help() {
+        return { exitCode: 0, message: USE_HELP, rawOutput: true };
+    }
     async execute(ctx) {
         const requestedBundle = firstUsePositional(ctx.args)
             ?? (ctx.args[0] === '--profile' ? 'all' : undefined);
@@ -3400,6 +3504,7 @@ export class UseHandler {
                     projectPath: target,
                     dryRun,
                     verbose,
+                    deployVersion: (await getVersionInfo()).version,
                 });
                 if (verbose && translationResult.translated.length > 0) {
                     ui.success(`Translated ${translationResult.translated.length} skills → commands (${provider})`);
@@ -3450,6 +3555,7 @@ export class UseHandler {
                         projectPath: target,
                         dryRun,
                         verbose,
+                        deployVersion: (await getVersionInfo()).version,
                         nameFilter: shouldMirrorKernelCommandSkill,
                     });
                     if (verbose && kernel.translated.length > 0) {

package/dist/src/cli/handlers/utilities.js

@@ -548,18 +548,34 @@ export const doctorHandler = {
                     namespace: 'aiwg',
                     skillsBaseDir: skillsDir,
                 });
-                const errorAndWarn = collisions.filter(r => r.severity === 'error' || r.severity === 'warn');
-                if (errorAndWarn.length > 0) {
-                    // In doctor context we report stale skills, not deployment blocks.
-                    // Re-running `aiwg use` will auto-clean aiwg-owned stale skills.
+                // Two distinct causes share this scan, and conflating them mislabels
+                // one as the other: an `error` is a name that shadows a Claude
+                // built-in; a `warn` is a deployed skill this namespace does not own
+                // (#2504). Report each under its own heading with its own remedy.
+                const builtinCollisions = collisions.filter(r => r.severity === 'error');
+                const unownedCollisions = collisions.filter(r => r.severity === 'warn');
+                if (builtinCollisions.length > 0 || unownedCollisions.length > 0) {
                     console.log('\n── Skill collision scan ──');
-                    console.log('');
-                    console.log('⚠ Stale skills detected (names collide with Claude built-ins):');
-                    for (const r of errorAndWarn) {
-                        console.log(`  ✗ ${r.skillName}: ${r.reason}`);
+                    if (builtinCollisions.length > 0) {
+                        console.log('');
+                        console.log('⚠ Stale skills detected (names collide with Claude built-ins):');
+                        for (const r of builtinCollisions) {
+                            console.log(`  ✗ ${r.skillName}: ${r.reason}`);
+                        }
+                        console.log('');
+                        console.log('  Fix: run `aiwg use <framework>` to redeploy and auto-clean stale skill directories.');
+                    }
+                    if (unownedCollisions.length > 0) {
+                        console.log('');
+                        console.log("⚠ Deployed skills not owned by namespace 'aiwg' (a redeploy would overwrite them):");
+                        for (const r of unownedCollisions) {
+                            console.log(`  ✗ ${r.skillName}: ${r.reason}`);
+                        }
+                        console.log('');
+                        console.log("  Fix: if the skill is yours, move it out of the AIWG-managed skills directory");
+                        console.log("  or give it its own namespace. If AIWG generated it, re-run `aiwg use` to");
+                        console.log('  restore the ownership marker.');
                     }
-                    console.log('');
-                    console.log('  Fix: run `aiwg use <framework>` to redeploy and auto-clean stale skill directories.');
                 }
             }
         }

package/dist/src/cli/services/deployment-verification.js

@@ -1,4 +1,4 @@
-import { access, readFile, readdir } from 'node:fs/promises';
+import { access, readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { loadGraphIndexFile } from '../../artifacts/index-reader.js';
 import { readAiwgConfig } from '../../config/aiwg-config.js';
@@ -111,6 +111,101 @@ async function countEntries(candidate) {
 function emptyCounts() {
     return { agents: 0, commands: 0, skills: 0, rules: 0, behaviors: 0 };
 }
+/**
+ * Flat-artifact attribution (#2507).
+ *
+ * Deployment counts used to be a plain `readdir` of the provider directory, so
+ * a run that wrote nothing still reported every pre-existing file as deployed —
+ * a no-op deploy over a stale, unmanaged tree was indistinguishable from a
+ * successful one. An artifact now counts as deployed only when this run wrote
+ * it (mtime at or after the invocation start) or AIWG owns it (sidecar entry or
+ * in-file managed marker). Everything else is reported as unmanaged.
+ */
+const MANAGED_SIDECAR = '.aiwg-manifest.json';
+const MANAGED_MARKER_PATTERN = /^(?:<!--\s*aiwg:managed\s|#\s*aiwg:managed\s)/m;
+const FLAT_ARTIFACT_KINDS = ['agents', 'commands', 'rules'];
+const FLAT_ARTIFACT_EXTENSIONS = ['.md', '.mdc', '.toml'];
+/** Clock skew tolerance between the recorded invocation start and file mtimes. */
+const WRITE_ATTRIBUTION_SKEW_MS = 2_000;
+const FLAT_ARTIFACT_NOUNS = {
+    agents: 'agent',
+    commands: 'command',
+    rules: 'rule',
+};
+async function readManagedSidecarNames(dir) {
+    try {
+        const raw = await readFile(path.join(dir, MANAGED_SIDECAR), 'utf8');
+        const parsed = JSON.parse(raw);
+        return new Set(Object.keys(parsed.managed ?? {}));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Split one flat artifact directory into artifacts this deployment accounts for
+ * and artifacts it does not. Returns `null` when the directory cannot be
+ * attributed (missing, unreadable, or no invocation boundary to compare
+ * against), so callers fall back to the plain entry count.
+ */
+async function tallyFlatArtifacts(dir, writtenSince) {
+    if (!dir || writtenSince === null)
+        return null;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const managedNames = await readManagedSidecarNames(dir);
+    const tally = { deployed: 0, unmanaged: [] };
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (!entry.isFile()) {
+            // Nested directories (e.g. deployed behaviors under rules/) are counted
+            // as-is; they are not flat artifacts and have their own lifecycle.
+            tally.deployed += 1;
+            continue;
+        }
+        const lower = entry.name.toLowerCase();
+        if (!FLAT_ARTIFACT_EXTENSIONS.some((extension) => lower.endsWith(extension)))
+            continue;
+        const absolute = path.join(dir, entry.name);
+        if (managedNames.has(entry.name)) {
+            tally.deployed += 1;
+            continue;
+        }
+        let writtenThisRun = false;
+        try {
+            const info = await stat(absolute);
+            writtenThisRun = info.mtimeMs + WRITE_ATTRIBUTION_SKEW_MS >= writtenSince;
+        }
+        catch {
+            writtenThisRun = false;
+        }
+        if (writtenThisRun) {
+            tally.deployed += 1;
+            continue;
+        }
+        let owned = false;
+        try {
+            owned = MANAGED_MARKER_PATTERN.test(await readFile(absolute, 'utf8'));
+        }
+        catch {
+            // Unreadable files are not claimed as deployed, but neither are they
+            // reported as shadowing artifacts we could not inspect.
+            continue;
+        }
+        if (owned)
+            tally.deployed += 1;
+        else
+            tally.unmanaged.push(entry.name);
+    }
+    tally.unmanaged.sort((a, b) => a.localeCompare(b));
+    return tally;
+}
 function phase(id, state, required, summary, evidence) {
     return { id, state, required, summary, evidence };
 }
@@ -249,9 +344,30 @@ export async function verifyProviderDeployment(options) {
         const artifactPaths = options.scope === 'user'
             ? USER_SCOPE_PATHS[normalized] ?? definition.paths.artifacts
             : definition.paths.artifacts;
+        const writtenSince = options.invocationStartedAt
+            ? Date.parse(options.invocationStartedAt)
+            : Number.NaN;
+        const attributionBoundary = Number.isFinite(writtenSince) ? writtenSince : null;
         for (const type of ['agents', 'commands', 'skills', 'rules', 'behaviors']) {
             const resolved = resolveProviderPathValue(artifactPaths[type], deploymentRoot);
             counts[type] = await countEntries(resolved);
+            // #2507: flat artifact directories report what this deployment accounts
+            // for, not whatever happens to be sitting in the directory.
+            const flatKind = FLAT_ARTIFACT_KINDS.find((kind) => kind === type);
+            if (!flatKind)
+                continue;
+            const tally = await tallyFlatArtifacts(resolved, attributionBoundary);
+            if (!tally)
+                continue;
+            counts[flatKind] = tally.deployed;
+            if (tally.unmanaged.length === 0)
+                continue;
+            const shown = tally.unmanaged.slice(0, 3).join(', ');
+            const remainder = tally.unmanaged.length - 3;
+            findings.push(finding(normalized, `unmanaged-artifacts:${flatKind}`, 'advisory', `${tally.unmanaged.length} unmanaged ${FLAT_ARTIFACT_NOUNS[flatKind]} file(s) left in place at ${artifactPaths[flatKind]}: `
+                + `${shown}${remainder > 0 ? `, and ${remainder} more` : ''}. `
+                + 'They are not managed by AIWG and were not counted as deployed.', `Re-run aiwg use ${options.requestedBundles[0] ?? 'all'} --provider ${normalized} --force to replace them, `
+                + `or delete ${artifactPaths[flatKind]} so AIWG can reclaim the directory.`, { kind: flatKind, unmanaged: tally.unmanaged }));
         }
         const resolvedSkillsPath = resolveProviderPathValue(artifactPaths.skills, deploymentRoot);
         const kernelPath = options.scope === 'user'

package/dist/src/cli/watch-service.js

@@ -46,10 +46,6 @@ export class WatchService {
         this.watcher.on('add', (path) => this.handleEvent('add', path));
         this.watcher.on('change', (path) => this.handleEvent('change', path));
         this.watcher.on('unlink', (path) => this.handleEvent('unlink', path));
-        this.watcher.on('ready', () => {
-            const watched = this.watcher?.getWatched() || {};
-            this.stats.filesWatched = Object.values(watched).reduce((sum, files) => sum + files.length, 0);
-        });
         this.watcher.on('error', (error) => {
             this.stats.errors++;
             console.error('Watch error:', error);
@@ -64,6 +60,53 @@ export class WatchService {
                 resolve();
             }
         });
+        // `ready` only means chokidar finished its initial scan. Because the
+        // watcher runs with `ignoreInitial: true`, a file created between the scan
+        // and the watch actually being armed is reported by neither — the event is
+        // absent rather than late, so no caller-side wait can recover it (#2518).
+        // Resolving `start()` only once every target appears in `getWatched()`
+        // makes readiness mean armed.
+        await this.waitUntilArmed(patterns);
+        const watched = this.watcher?.getWatched() ?? {};
+        this.stats.filesWatched = Object.values(watched).reduce((sum, files) => sum + files.length, 0);
+    }
+    /**
+     * Poll `getWatched()` until every requested target is present, or the budget
+     * expires. Bounded on purpose: a target that does not exist on disk can never
+     * be armed, and `start()` must not hang waiting for one.
+     *
+     * The healthy path satisfies the first synchronous check and never awaits, so
+     * a test that mocks the watcher under fake timers must report its targets
+     * from `getWatched()` — otherwise the poll waits on a clock nothing advances.
+     */
+    async waitUntilArmed(patterns, timeoutMs = 500, pollIntervalMs = 25) {
+        const deadline = Date.now() + timeoutMs;
+        while (!this.allTargetsArmed(patterns)) {
+            if (Date.now() >= deadline) {
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+    }
+    /** True when chokidar reports a watch covering every requested target. */
+    allTargetsArmed(patterns) {
+        if (!this.watcher) {
+            return true;
+        }
+        const watched = this.watcher.getWatched();
+        // chokidar keys `getWatched()` with the spelling it was given, so resolve
+        // both sides before comparing.
+        const armed = new Set();
+        for (const [dir, entries] of Object.entries(watched)) {
+            const absoluteDir = path.resolve(dir);
+            armed.add(absoluteDir);
+            for (const entry of entries) {
+                armed.add(path.join(absoluteDir, entry));
+            }
+        }
+        // A directory target is keyed directly; a file target is listed under its
+        // parent. Either spelling resolves into the same set.
+        return patterns.every((pattern) => armed.has(path.resolve(pattern)));
     }
     /**
      * Stop watching

package/dist/src/config/project-artifacts-health.mjs

@@ -89,10 +89,23 @@ export function auditProjectArtifactHealth(projectDir, env = process.env) {
       severity = 'error';
       repairable = controls.filter((item) => !item.local).every((item) => item.external);
       action = 'Run `aiwg artifacts repair --dry-run`, then `aiwg artifacts repair --apply` after reviewing the plan.';
-    } else if (divergentControl.length || divergentPayload.length) {
+    } else if (divergentControl.length) {
+      // Only control-plane divergence is genuinely manual: `repairProjectArtifacts`
+      // refuses outright on it, because AIWG.md / aiwg.config / registry.json have
+      // no safe automatic winner (#2516).
       classification = 'duplicated-divergent';
       severity = 'error';
-      action = 'Reconcile the reported local and external files manually; no automatic repair will overwrite divergent content.';
+      action = 'Reconcile the reported control-plane files manually; automatic repair refuses while they diverge.';
+    } else if (divergentPayload.length) {
+      // Divergent *payload* is repairable and always has been — repair archives the
+      // local variant under archive/local-corpus-migration/conflicts/local/, leaves
+      // the external variant untouched, and removes local only after byte
+      // verification. Reporting this as manual-only steered operators away from a
+      // working automatic path and into hand-migrating corpora (#2516).
+      classification = 'duplicated-divergent-payload';
+      severity = 'warning';
+      repairable = true;
+      action = 'Run `aiwg artifacts repair --dry-run`, then `aiwg artifacts repair --apply`; divergent local variants are archived, never overwritten.';
     } else if (localPayload.length) {
       classification = 'duplicated-identical';
       severity = 'warning';

package/dist/src/cost/fleet-report.js

@@ -179,13 +179,27 @@ function requestSignal(parent) {
 }
 async function openRouterGet(endpoint, key, options) {
     const fetchImpl = options.fetchImpl ?? fetch;
-    const response = await fetchImpl(`${options.apiBaseUrl ?? OPENROUTER_API}${endpoint}`, {
-        headers: { Authorization: `Bearer ${key}` },
-        signal: requestSignal(options.signal),
-    });
+    let response;
+    try {
+        response = await fetchImpl(`${options.apiBaseUrl ?? OPENROUTER_API}${endpoint}`, {
+            headers: { Authorization: `Bearer ${key}` },
+            signal: requestSignal(options.signal),
+        });
+    }
+    catch {
+        // Transport diagnostics can embed Authorization headers or request bodies.
+        throw new Error('OpenRouter request could not complete. Check connectivity, timeout, or cancellation.');
+    }
     if (!response.ok)
         throw new Error(`OpenRouter request failed with status ${response.status}.`);
-    const payload = await response.json();
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        // Decoder exceptions can quote arbitrary response content.
+        throw new Error('OpenRouter returned unreadable JSON. Check the API response format.');
+    }
     if (!payload || typeof payload !== 'object' || !payload.data)
         throw new Error('OpenRouter returned an invalid response.');
     return payload.data;

package/dist/src/extensions/project-local-doctor.js

@@ -67,7 +67,7 @@ export async function buildProjectLocalDoctorSection(opts) {
     }
     // No project-local content → no section at all
     if (discovery.isEmpty && discovery.errors.length === 0 && !quickrefAudit.exists && quickrefErrors.length === 0) {
-        return { output: '', validationErrors: 0, denylistViolations: 0, driftCount: 0, hasFailures: false };
+        return { output: '', validationErrors: 0, denylistViolations: 0, driftCount: 0, undeployedCount: 0, hasFailures: false };
     }
     const lines = ['', '── Project-local artifacts ────────────────────────────────────'];
     // Counts
@@ -108,12 +108,17 @@ export async function buildProjectLocalDoctorSection(opts) {
     lines.push('');
     // Shadows + denylist
     let denylistViolations = 0;
+    // Bundles the resolver deliberately refused are already reported below as
+    // denylist violations; the undeployed check must not double-count them.
+    const refusedBundleIds = new Set();
     if (discovery.bundles.length > 0) {
         try {
             const upstream = await buildUpstreamRegistry({ frameworkRoot });
             const shadowResult = await resolveShadows(discovery.bundles, upstream);
             const refusals = shadowResult.resolutions.filter(r => r.verdict === 'refuse-unsafe' || r.verdict === 'refuse-phantom' || r.verdict === 'refuse-duplicate');
             denylistViolations = refusals.length;
+            for (const refusal of refusals)
+                refusedBundleIds.add(refusal.bundleId);
             if (!quiet) {
                 const informational = shadowResult.shadows.filter(s => s.verdict === 'deploy-with-warning' || s.verdict === 'deploy-acknowledged');
                 if (informational.length > 0) {
@@ -188,6 +193,37 @@ export async function buildProjectLocalDoctorSection(opts) {
         }
         lines.push('');
     }
+    // Undeployed bundles (#2503).
+    //
+    // A bundle whose deploy aborted (a bad support-asset reference, a failed CLI
+    // contribution) leaves no `installed` entry, so every check above — manifest
+    // validation, drift — silently skips it and reports a clean bill of health
+    // for a bundle that is not actually available. The only prior signal was a
+    // WARN line in `aiwg use` output, long scrolled away by the time anyone
+    // wonders where the skill went.
+    const undeployed = config
+        ? discovery.bundles.filter((bundle) => {
+            if (refusedBundleIds.has(bundle.id))
+                return false;
+            const entry = config.installed[bundle.id];
+            return !entry || entry.source !== 'project-local';
+        })
+        : [];
+    if (undeployed.length > 0) {
+        lines.push(`  Deployment: ✗ ${undeployed.length} discovered bundle${undeployed.length === 1 ? '' : 's'} not deployed`);
+        for (const bundle of undeployed.slice(0, 5)) {
+            lines.push(`    ✗ ${bundle.type}/${bundle.id} (${bundle.localPath}) — no deployment recorded`);
+        }
+        if (undeployed.length > 5)
+            lines.push(`    + ${undeployed.length - 5} more`);
+        lines.push(`    Run \`aiwg use ${undeployed[0].id}\` and read the output — a deploy that`);
+        lines.push('    fails reports the reason there.');
+        lines.push('');
+    }
+    else if (!quiet && config && discovery.bundles.length > 0) {
+        lines.push('  Deployment: ✓ all discovered bundles deployed');
+        lines.push('');
+    }
     // Provider deployment matrix
     if (!quiet && config) {
         const projectLocalEntries = Object.entries(config.installed).filter(([, e]) => e.source === 'project-local');
@@ -252,12 +288,14 @@ export async function buildProjectLocalDoctorSection(opts) {
             lines.push('');
         }
     }
-    const hasFailures = validationErrors > 0 || denylistViolations > 0 || driftCount > 0 || gitignoredCount > 0;
+    const hasFailures = validationErrors > 0 || denylistViolations > 0 || driftCount > 0
+        || gitignoredCount > 0 || undeployed.length > 0;
     return {
         output: lines.join('\n'),
         validationErrors,
         denylistViolations,
         driftCount,
+        undeployedCount: undeployed.length,
         hasFailures,
     };
 }

package/dist/src/extensions/project-quickref.js

@@ -258,6 +258,10 @@ export function renderProjectQuickref(definition) {
         '---',
         `name: ${skillName}`,
         `description: ${JSON.stringify(`Project-specific orientation for ${definition.project.name}`)}`,
+        // AIWG generates and deploys this skill, so it must declare AIWG ownership.
+        // Without it the collision scan treats every redeploy of AIWG's own artifact
+        // as an unowned overwrite and warns permanently (#2504).
+        'namespace: aiwg',
         'kernel: true',
         'platforms: [all]',
         '---',

package/dist/src/installation/manager.mjs

@@ -176,13 +176,44 @@ export function inspectInstallation(options = {}) {
   const actualRoot = canonicalPath(options.actualRoot);
   const actualMethod = options.actualMethod ?? inferInstallationMethod(actualRoot);
   const identity = options.identity ?? loadInstallationIdentity({ ...options, actualRoot });
-  if (!identity) return { state: 'unrecorded', identity: null, actualRoot, actualMethod, drift: ['installation identity is not recorded'] };
+  if (!identity) {
+    return {
+      state: 'unrecorded',
+      identity: null,
+      actualRoot,
+      actualMethod,
+      frameworkRoot: actualRoot,
+      launcher: null,
+      drift: ['installation identity is not recorded'],
+    };
+  }
 
   const drift = [];
   const canonicalRoot = canonicalPath(identity.root);
+
+  // Edge/customize mode deliberately separates the *launcher* (the executable
+  // that ran, typically an npm-global install) from the *framework root* (the
+  // local clone named by `edgePath`). Comparing the launcher's package root
+  // against the canonical root then reports the supported configuration as
+  // drift, and does so only for the commands that happen to run from the
+  // npm-global copy — `aiwg doctor`, loaded through the redirect, saw the
+  // clone and reported aligned for the same workspace (#2505).
+  //
+  // The redirect is only trusted when the identity actually declares it: the
+  // channel is `edge` and `edgePath` resolves to the canonical root.
+  const edgePath = identity.edgePath ? canonicalPath(identity.edgePath) : null;
+  const rootsDiffer = canonicalRoot !== actualRoot;
+  const launcherRedirect = identity.channel === 'edge' && edgePath !== null && edgePath === canonicalRoot && rootsDiffer;
+  const launcher = launcherRedirect ? { root: actualRoot, method: actualMethod } : null;
+  // The framework root is what AIWG actually reads its corpus from, and it is
+  // the single value that drives `state`.
+  const frameworkRoot = launcherRedirect ? canonicalRoot : actualRoot;
+
   if (!existsSync(canonicalRoot)) drift.push(`canonical root does not exist: ${canonicalRoot}`);
-  if (canonicalRoot !== actualRoot) drift.push(`actual root ${actualRoot} differs from canonical root ${canonicalRoot}`);
-  if (identity.method !== actualMethod) drift.push(`actual method ${actualMethod} differs from canonical method ${identity.method}`);
+  if (rootsDiffer && !launcherRedirect) drift.push(`actual root ${actualRoot} differs from canonical root ${canonicalRoot}`);
+  if (identity.method !== actualMethod && !launcherRedirect) {
+    drift.push(`actual method ${actualMethod} differs from canonical method ${identity.method}`);
+  }
   if (identity.method !== 'web' && !identity.managerExecutable) {
     drift.push(`canonical ${identity.method} installation has no recorded manager executable`);
   }
@@ -214,6 +245,10 @@ export function inspectInstallation(options = {}) {
     canonicalRoot,
     actualRoot,
     actualMethod,
+    /** Where the corpus is read from. Equals actualRoot unless a launcher redirect applies. */
+    frameworkRoot,
+    /** Non-null only in edge/customize mode: the executable's own package root. */
+    launcher,
     drift,
     managerProbe,
   };