@aiwg/cli 2026.9.6 → 2026.9.9

package/dist/src/cli/handlers/repo-access.js

@@ -1,13 +1,16 @@
 import { checkRepoAccess, findRepoEntry, formatRepoAccessEntry, loadRepoAccessManifest, } from '../../policy/repo-access.js';
 import { resolveWorkspace } from '../../config/workspace.js';
+import { getProjectDir, readAiwgConfig, writeAiwgConfig, WORKSPACE_REPO_ACTIONS, } from '../../config/aiwg-config.js';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
 function valueAfter(args, flag) {
     const index = args.indexOf(flag);
     if (index < 0)
         return null;
     return args[index + 1] ?? null;
 }
-function printHelp() {
-    console.log(`
+function usage() {
+    return `
   aiwg repo-access — repo authorization manifest preflight
 
   Usage:
@@ -15,12 +18,149 @@ function printHelp() {
     aiwg repo-access status
     aiwg repo-access explain --path <repo-or-file>
     aiwg repo-access check --path <repo-or-file> --action <read|write|commit|push|issue-comment|service-action|destructive>
+    aiwg repo-access add --path <p> --name <n> --allow <a,b,c> [--provider <gitea|github|gitlab>] [--notes "..."]
+    aiwg repo-access remove --name <n>
+    aiwg repo-access audit
 
   Manifest:
     .aiwg/aiwg.config workspace + repos blocks (preferred)
     .aiwg/ops/security/repo-access.manifest.yaml
     .aiwg/security/repo-access.manifest.yaml (fallback)
-`);
+`;
+}
+function printHelp() {
+    console.log(usage());
+}
+/**
+ * The manifest is mandatory and default-deny, but until now it had no write path:
+ * registering a repo meant hand-editing JSON, and the rule's own recovery text
+ * ("ask for a manifest update") had no supported way to be carried out (#2531).
+ */
+async function addRepo(ctx, args) {
+    const repoPath = valueAfter(args, '--path');
+    const name = valueAfter(args, '--name');
+    const allowRaw = valueAfter(args, '--allow');
+    if (!repoPath)
+        return { exitCode: 2, message: 'repo-access add requires --path <repo-or-file>' };
+    if (!name)
+        return { exitCode: 2, message: 'repo-access add requires --name <name>' };
+    if (!allowRaw) {
+        return { exitCode: 2, message: `repo-access add requires --allow <${WORKSPACE_REPO_ACTIONS.join('|')}>` };
+    }
+    const allowed = allowRaw.split(',').map((item) => item.trim()).filter(Boolean);
+    const invalid = allowed.filter((item) => !WORKSPACE_REPO_ACTIONS.includes(item));
+    if (invalid.length > 0) {
+        return {
+            exitCode: 2,
+            message: `Unknown action(s): ${invalid.join(', ')}. Valid: ${WORKSPACE_REPO_ACTIONS.join(', ')}`,
+        };
+    }
+    const provider = valueAfter(args, '--provider') ?? undefined;
+    if (provider && !['gitea', 'github', 'gitlab'].includes(provider)) {
+        return { exitCode: 2, message: `Unknown provider: ${provider}. Valid: gitea, github, gitlab` };
+    }
+    const projectDir = getProjectDir(ctx, args);
+    const config = await readAiwgConfig(projectDir);
+    if (!config)
+        return { exitCode: 2, message: `No .aiwg/aiwg.config found in ${projectDir}` };
+    const repos = config.repos ? [...config.repos] : [];
+    const entry = {
+        name,
+        path: repoPath,
+        allowed: allowed,
+        ...(provider ? { provider: provider } : {}),
+        ...(valueAfter(args, '--notes') ? { notes: valueAfter(args, '--notes') } : {}),
+    };
+    const existingIndex = repos.findIndex((repo) => repo.name === name);
+    if (existingIndex >= 0) {
+        repos[existingIndex] = { ...repos[existingIndex], ...entry };
+    }
+    else {
+        repos.push(entry);
+    }
+    await writeAiwgConfig(projectDir, { ...config, repos });
+    console.log(`${existingIndex >= 0 ? 'Updated' : 'Registered'} ${name}: ${repoPath} [${allowed.join(', ')}]`);
+    return { exitCode: 0 };
+}
+async function removeRepo(ctx, args) {
+    const name = valueAfter(args, '--name');
+    if (!name)
+        return { exitCode: 2, message: 'repo-access remove requires --name <name>' };
+    const projectDir = getProjectDir(ctx, args);
+    const config = await readAiwgConfig(projectDir);
+    if (!config)
+        return { exitCode: 2, message: `No .aiwg/aiwg.config found in ${projectDir}` };
+    const repos = config.repos ?? [];
+    const remaining = repos.filter((repo) => repo.name !== name);
+    if (remaining.length === repos.length) {
+        return { exitCode: 1, message: `No repo named '${name}' in the manifest.` };
+    }
+    // An empty `repos` array fails config validation, so drop the key entirely
+    // when the last entry goes rather than writing a config that cannot be read back.
+    const next = { ...config };
+    if (remaining.length > 0)
+        next.repos = remaining;
+    else
+        delete next.repos;
+    await writeAiwgConfig(projectDir, next);
+    console.log(`Removed ${name}. It now falls under the default-deny policy.`);
+    return { exitCode: 0 };
+}
+/**
+ * Report workspace subdirectories that are git repos but carry no manifest entry.
+ * Manifests drift out of sync with reality; on the reporting workspace two
+ * actively-used repos were both unlisted and therefore formally denied (#2531).
+ */
+async function auditRepos(ctx, args) {
+    // A missing manifest is the most important case to audit, not a reason to fail:
+    // every repo is then unlisted and formally denied.
+    let manifest = null;
+    try {
+        manifest = loadRepoAccessManifest(ctx.cwd);
+    }
+    catch {
+        manifest = null;
+    }
+    const root = manifest?.workspaceProjectRoot ?? getProjectDir(ctx, args);
+    let children = [];
+    try {
+        children = readdirSync(root);
+    }
+    catch {
+        return { exitCode: 2, message: `Cannot read workspace root: ${root}` };
+    }
+    const unlisted = [];
+    for (const child of children.sort()) {
+        if (child.startsWith('.'))
+            continue;
+        const full = nodePath.join(root, child);
+        try {
+            if (!statSync(full).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (!existsSync(nodePath.join(full, '.git')))
+            continue;
+        if (manifest && findRepoEntry(manifest, full, ctx.cwd))
+            continue;
+        unlisted.push(child);
+    }
+    console.log(`Repo access manifest: ${manifest?.path ?? '(none — every repo is denied)'}`);
+    console.log(`Workspace root: ${root}`);
+    console.log(`Default policy: ${manifest?.defaultPolicy ?? 'deny'}`);
+    if (unlisted.length === 0) {
+        console.log('All git repositories under the workspace root are registered.');
+        return { exitCode: 0 };
+    }
+    console.log('');
+    console.log(`Unlisted git repositories (${unlisted.length}) — denied by default:`);
+    for (const name of unlisted) {
+        console.log(`  - ${name}`);
+        console.log(`      aiwg repo-access add --path ./${name} --name ${name} --allow read`);
+    }
+    return { exitCode: 1 };
 }
 async function handleRepoAccess(ctx) {
     const [subcommand = 'help', ...args] = ctx.args;
@@ -28,6 +168,14 @@ async function handleRepoAccess(ctx) {
         printHelp();
         return { exitCode: 0 };
     }
+    // add/remove write .aiwg/aiwg.config directly and must work before any manifest
+    // exists — registering the first repo is exactly the bootstrap case (#2531).
+    if (subcommand === 'add')
+        return await addRepo(ctx, args);
+    if (subcommand === 'remove')
+        return await removeRepo(ctx, args);
+    if (subcommand === 'audit')
+        return await auditRepos(ctx, args);
     try {
         const manifest = loadRepoAccessManifest(ctx.cwd);
         if (subcommand === 'list' || subcommand === 'status') {
@@ -87,7 +235,7 @@ async function handleRepoAccess(ctx) {
             }
             return { exitCode: decision.allowed ? 0 : 1 };
         }
-        return { exitCode: 2, message: `Unknown repo-access subcommand: ${subcommand}` };
+        return { exitCode: 2, message: `Unknown repo-access subcommand: ${subcommand}\n${usage()}` };
     }
     catch (error) {
         return {
@@ -103,6 +251,9 @@ export const repoAccessHandler = {
     description: 'Validate and query repo access manifest permissions',
     category: 'utility',
     aliases: [],
+    async help() {
+        return { exitCode: 0, message: usage(), rawOutput: true };
+    },
     execute: handleRepoAccess,
 };
 export const repoAccessHandlers = [repoAccessHandler];

package/dist/src/cli/handlers/runtime-info.js

@@ -298,6 +298,9 @@ async function handleRuntimeInfo(args, cwd = process.cwd()) {
             console.log(`\nAIWG Installation:`);
             console.log(`  Canonical: ${installation.identity?.method ?? 'unrecorded'} at ${installation.identity?.root ?? '(unrecorded)'}`);
             console.log(`  Actual:    ${installation.actualMethod} at ${installation.actualRoot}`);
+            if (installation.launcher) {
+                console.log(`  Launcher:  ${installation.launcher.method} at ${installation.launcher.root} (edge redirect)`);
+            }
             console.log(`  Run mode:  ${installation.identity?.runMode ?? '(unrecorded)'}`);
             console.log(`  State:     ${installation.state}`);
             // Scheduler backend detection

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

@@ -16,6 +16,8 @@ import { sandboxRegistry, normalizeSandboxEvent, } from '../../serve/sandbox-reg
 import { routeTask } from '../../serve/agent-router.js';
 import { routeDispatch } from '../../serve/dispatch-router.js';
 import { observeA2ATerminalState } from '../../serve/a2a-terminal-observer.js';
+import { respondToA2AMission } from '../../serve/mission-hitl.js';
+import { A2A_HITL_PROMPT_V1 } from '../../a2a/client.js';
 import { executorRegistry, validateRegisterPayload, validateDispatchPayload, validateEventEnvelope, } from '../../serve/executor-registry.js';
 import { handleWebhook, IdempotencyCache, PushSecretRegistry, } from '../../a2a/webhook.js';
 import { AiwgError, EXIT_CODES } from '../errors.js';
@@ -807,6 +809,7 @@ export async function startServer(opts) {
         const a2aProtocolPolicy = configuredA2AProtocolPolicy;
         try {
             const result = await routeDispatch(executor, payload, {
+                optionalExtensions: [A2A_HITL_PROMPT_V1],
                 a2aProtocolPolicy,
                 allowA2AProtocolFallback: configuredA2AProtocolFallback,
                 allowLegacyExecutorFallback: configuredLegacyExecutorFallback,
@@ -872,7 +875,14 @@ export async function startServer(opts) {
                 ...(a2aFallbackReason ? { fallbackReason: a2aFallbackReason } : {}),
             });
         }
-        executorRegistry.assignMission(missionId, executor.executorId);
+        const existingMission = executorRegistry.getMission(missionId);
+        // An idempotent replay must not discard in-flight/accepted approvals.
+        if (!(dispatchPath === 'v2' && a2aTask && a2aInstanceId
+            && existingMission?.executorId === executor.executorId
+            && existingMission.a2a?.taskId === a2aTask.id
+            && existingMission.a2a.instanceId === a2aInstanceId)) {
+            executorRegistry.assignMission(missionId, executor.executorId);
+        }
         if (dispatchPath === 'v2' && a2aTask && a2aInstanceId) {
             void observeA2ATerminalState(executorRegistry, executor, missionId, a2aInstanceId, a2aTask, {
                 onError: (err) => {
@@ -929,7 +939,7 @@ export async function startServer(opts) {
             error: mission.error,
         });
     });
-    // POST /api/v1/missions/:id/hitl_response → 200; forwards to owning executor over WS
+    // POST /api/v1/missions/:id/hitl_response → owning task's negotiated transport
     app.post('/api/v1/missions/:id/hitl_response', async (c) => {
         const missionId = c.req.param('id');
         const mission = executorRegistry.getMission(missionId);
@@ -944,9 +954,17 @@ export async function startServer(opts) {
         }
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const payload = body;
-        if (!payload.hitl_id || !payload.response) {
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+            || typeof payload.hitl_id !== 'string' || !payload.hitl_id || !Object.hasOwn(payload, 'response')) {
             return c.json({ error: 'hitl_id and response are required' }, 400);
         }
+        if (mission.a2a) {
+            const result = await respondToA2AMission(executorRegistry, missionId, payload.hitl_id, payload.response);
+            return c.json(result.body, result.status);
+        }
+        if (typeof payload.response !== 'string' || !payload.response) {
+            return c.json({ error: 'Legacy HITL response must be a non-empty string' }, 400);
+        }
         // Push hitl_responded event to the executor over WS
         const envelope = {
             event: 'mission.hitl_responded',

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

@@ -1,6 +1,6 @@
 import { spawnSync } from 'child_process';
 import { existsSync } from 'fs';
-import { emptyConfig, getConfigPath, getProjectDir, readAiwgConfig, resolveRemoteProvider, VALID_PROVIDERS, writeAiwgConfig, } from '../../config/aiwg-config.js';
+import { emptyConfig, FORCE_PUSH_POLICY_ALIAS_NOTE, normalizeForcePushPolicy as normalizeForcePushPolicyShared, getConfigPath, getProjectDir, readAiwgConfig, resolveRemoteProvider, VALID_PROVIDERS, writeAiwgConfig, } from '../../config/aiwg-config.js';
 import { AiwgError, EXIT_CODES } from '../errors.js';
 import { askChoice, askString, askYesNo, createPromptInterface } from '../prompt-utils.js';
 import * as ui from '../ui.js';
@@ -165,11 +165,11 @@ function secondaryRemotes(remotes, primary, issueTracker, ci) {
     }));
 }
 function normalizeForcePushPolicy(value, warnings) {
-    if (value === 'main-only-blocked') {
-        warnings.push('delivery.force_push_policy=main-only-blocked is a legacy alias; setup normalized it to own-branch-only.');
-        return 'own-branch-only';
+    const { policy, deprecatedFrom } = normalizeForcePushPolicyShared(value);
+    if (deprecatedFrom) {
+        warnings.push(`delivery.force_push_policy=${deprecatedFrom} is a legacy alias; setup normalized it to ${policy}. ${FORCE_PUSH_POLICY_ALIAS_NOTE}`);
     }
-    return value;
+    return policy;
 }
 function cloneConfig(config) {
     return JSON.parse(JSON.stringify(config));

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

@@ -185,6 +185,18 @@ function printFullMatrix(matrix) {
     }
 }
 // ── Main execution ─────────────────────────────────────────────────────────────
+function permissionsUsage() {
+    return `
+  aiwg steward permissions — authorization model audit and normalization
+
+  Usage:
+    aiwg steward permissions audit                 Find normalized-model errors and legacy grants
+    aiwg steward permissions migrate --dry-run     Preview legacy permission normalization
+    aiwg steward permissions migrate --apply       Back up and atomically normalize config
+
+  Reads .aiwg/aiwg.config authorization block. Migration backs up before writing.
+`;
+}
 async function handleSteward(args, ctx) {
     const subcommand = args[0];
     if (!subcommand || subcommand === '--help' || subcommand === 'help') {
@@ -221,6 +233,11 @@ async function handleSteward(args, ctx) {
     }
     if (subcommand === 'permissions') {
         const operation = args[1];
+        // `<namespace> --help` must reach the same usage block bare invocation prints (#2533).
+        if (!operation || operation === 'help' || operation === '--help' || operation === '-h') {
+            console.log(permissionsUsage());
+            return;
+        }
         const projectDir = ctx ? getProjectDir(ctx, args) : process.cwd();
         const config = await readAiwgConfig(projectDir);
         if (!config)
@@ -273,7 +290,7 @@ async function handleSteward(args, ctx) {
         }
         throw new AiwgError({
             code: 'ERR_USAGE_UNKNOWN_PERMISSION_OPERATION',
-            message: `Unknown permissions operation: ${operation ?? '(missing)'}`,
+            message: `Unknown permissions operation: ${operation}`,
             hint: 'Use audit or migrate --dry-run|--apply.',
             exitCode: EXIT_CODES.USAGE,
         });
@@ -598,6 +615,18 @@ export const stewardHandler = {
     description: 'Provider capability routing and permission normalization',
     category: 'maintenance',
     aliases: [],
+    // The router intercepts --help before execute(), so a handler without this
+    // property gets the generic "no detailed help" stub even when its own usage
+    // text exists. Route to the same block bare invocation prints, and keep
+    // sub-namespace help reachable, without executing anything (#2533).
+    async help(ctx) {
+        const positional = ctx.args.filter((arg) => !arg.startsWith('-'));
+        if (positional[0] === 'permissions') {
+            return { exitCode: 0, message: permissionsUsage(), rawOutput: true };
+        }
+        await handleSteward([], ctx);
+        return { exitCode: 0 };
+    },
     async execute(ctx) {
         try {
             await handleSteward(ctx.args, ctx);

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;
@@ -693,8 +694,10 @@ const SESSION_RELOAD_NOTICE = {
         rationale: 'Claude Code reads .claude/agents/ at session start. A running session retains its old registry until reloaded.',
     },
     codex: {
-        action: 'Restart/open Codex in this target workspace so it picks up newly deployed agents and .agents/skills entries.',
-        rationale: 'Codex caches its agent and skill registry per session. Project .agents/skills/ and .codex/agents/ are scanned from the Codex working directory up to the repo root on startup.',
+        required: false,
+        action: 'No restart needed for deployed skills — Codex exposes them on the next turn. Reopen Codex in this workspace only if a deployed skill or agent is still missing after that.',
+        rationale: 'A running Codex desktop session listed the newly deployed project skills on the very next user turn without any restart (#2309). Custom agent registry and MCP server changes were not observed to refresh live, so reopening remains the fallback for those.',
+        symptom: 'If a deployed skill or agent stays absent after the next turn, the registry did not rescan — reopen Codex in this workspace.',
     },
     copilot: {
         action: 'Reload the VS Code window (`Developer: Reload Window`) so Copilot picks up the new .github/agents/ entries.',
@@ -735,7 +738,8 @@ function printSessionReloadNotice(provider) {
     if (!notice)
         return;
     const defaultSymptom = 'Until reloaded, the Agent/Task tool will report "Agent type not found" for the newly deployed agents.';
-    ui.section('Session reload required:', [
+    const required = notice.required !== false;
+    ui.section(required ? 'Session reload required:' : 'Session reload (only if something is missing):', [
         notice.action,
         `Why: ${notice.rationale}`,
         notice.symptom ?? defaultSymptom,
@@ -1053,6 +1057,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 +1144,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 +1167,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 +1182,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 +1256,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)
@@ -1197,7 +1272,9 @@ async function deployOneProjectLocalBundle(opts) {
             args.push('--quiet');
         // Project-local bundles are addon-shaped — never trigger the legacy commands
         // migration prompt (which is only relevant for full-framework deploys).
-        args.push('--skip-commands-migration');
+        // This is a structural opt-out, not the operator declining, so suppress the
+        // duplicate-commands warning too: it fired once per bundle (#2541).
+        args.push('--skip-commands-migration', '--no-commands-warning');
         const captureOpts = quiet && !verbose ? { capture: true } : {};
         // Inject AIWG_ROOT so the deploy subprocess can resolve the upstream AIWG
         // install root. The bundle's `--source` is its project-local path, so
@@ -2122,6 +2199,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 +2235,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 +3509,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 +3560,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.');
                 }
             }
         }