@aiwg/cli 2026.9.7 → 2026.9.10

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

@@ -40,6 +40,48 @@ const PROVIDER_AGENT_DIRS = {
 export async function currentBundledAgentBasenames(frameworkRoot) {
     return new Set((await collectPackagedAgentInventory(frameworkRoot)).keys());
 }
+/**
+ * Basenames of every rule the current package can deploy.
+ *
+ * Symmetric to {@link currentBundledAgentBasenames}. A rule absent from this set
+ * is residue from a deploy model that no longer writes it (#2540).
+ *
+ * Every group that can ship a `rules/` directory must be listed here: the set is
+ * the prune's definition of "still shipped", so a missed group makes live rules
+ * look orphaned and deletes them. `extensions` ships 22 rules and was the group
+ * this nearly lost.
+ */
+export const BUNDLED_RULE_SOURCE_GROUPS = ['frameworks', 'addons', 'plugins', 'extensions'];
+export async function currentBundledRuleBasenames(frameworkRoot) {
+    const names = new Set();
+    const codeRoot = path.join(frameworkRoot, 'agentic', 'code');
+    for (const group of BUNDLED_RULE_SOURCE_GROUPS) {
+        let units;
+        try {
+            units = await fs.readdir(path.join(codeRoot, group), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const unit of units) {
+            if (!unit.isDirectory())
+                continue;
+            const rulesDir = path.join(codeRoot, group, unit.name, 'rules');
+            let entries;
+            try {
+                entries = await fs.readdir(rulesDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.isFile() && entry.name.endsWith('.md'))
+                    names.add(entry.name);
+            }
+        }
+    }
+    return names;
+}
 async function readFrameworkVersion(frameworkRoot) {
     try {
         const pkg = JSON.parse(await fs.readFile(path.join(frameworkRoot, 'package.json'), 'utf8'));
@@ -186,6 +228,7 @@ export async function partitionTrackedPaths(projectRoot, relativePaths) {
 }
 export async function pruneStaleManagedAgentFiles(options) {
     const desired = await currentBundledAgentBasenames(options.frameworkRoot);
+    const desiredRules = await currentBundledRuleBasenames(options.frameworkRoot);
     const currentVersion = options.currentVersion ?? await readFrameworkVersion(options.frameworkRoot);
     const crossProvider = options.crossProvider ?? 'skip';
     const removals = [];
@@ -204,7 +247,10 @@ export async function pruneStaleManagedAgentFiles(options) {
         // provider only drops agents whose source no longer ships them.
         if (!isTargetProvider && crossProvider === 'skip')
             continue;
-        const kinds = isTargetProvider ? ['agents'] : PRUNABLE_ARTIFACT_KINDS;
+        // Rules were excluded from the target-provider pass, so a project carried
+        // every rule any past version ever deployed. On long-lived projects that is
+        // the bulk of the startup-context budget (#2540).
+        const kinds = isTargetProvider ? ['agents', 'rules'] : PRUNABLE_ARTIFACT_KINDS;
         const hits = await collectManagedProviderArtifacts(options.projectRoot, provider, kinds);
         const eligible = hits.filter((hit) => {
             if (isTargetProvider) {
@@ -212,6 +258,8 @@ export async function pruneStaleManagedAgentFiles(options) {
                 // marker to the top-level package version makes a successful refresh
                 // delete freshly restored addon agents, so the active provider removes
                 // only artifacts absent from current sources.
+                if (hit.kind === 'rules')
+                    return !desiredRules.has(path.basename(hit.relativePath));
                 return !desired.has(hit.artifactName);
             }
             return currentVersion !== null && isOlderManagedVersion(hit.version, currentVersion);
@@ -583,7 +631,11 @@ export const refreshHandler = {
         }
         let staleAgentRemovals = [];
         let trackedSkipped = [];
-        if (!dryRun && deploymentFailures.length === 0) {
+        // A dry run still reports what a real run would remove. Skipping the pass
+        // entirely meant `refresh --dry-run` printed "Checking for stale deployments..."
+        // and nothing else, so orphaned artifacts were invisible until they had
+        // pushed the project over its context budget (#2540).
+        if (deploymentFailures.length === 0) {
             try {
                 const pruneResult = await pruneStaleManagedAgentFiles({
                     projectRoot: ctx.cwd,
@@ -591,6 +643,7 @@ export const refreshHandler = {
                     provider: detectedProvider,
                     crossProvider: pruneOtherProviders ? 'prune' : 'skip',
                     allowTrackedDeletes: pruneTracked,
+                    dryRun,
                 });
                 staleAgentRemovals = pruneResult.removals;
                 trackedSkipped = pruneResult.trackedSkipped;
@@ -607,19 +660,24 @@ export const refreshHandler = {
                 }
                 if (staleAgentRemovals.length > 0 && !quiet) {
                     const total = staleAgentRemovals.reduce((sum, item) => sum + item.paths.length, 0);
-                    ui.warn(`Removed ${total} stale AIWG-managed file${total === 1 ? '' : 's'} ` +
+                    ui.warn(`${dryRun ? 'Would remove' : 'Removed'} ${total} stale AIWG-managed file${total === 1 ? '' : 's'} ` +
                         `across ${staleAgentRemovals.length} provider${staleAgentRemovals.length === 1 ? '' : 's'}`);
                     for (const removal of staleAgentRemovals) {
                         const shown = removal.paths.slice(0, 3).join(', ');
                         const remainder = removal.paths.length - 3;
                         ui.dim(`    ${removal.provider}: ${removal.paths.length} (${shown}${remainder > 0 ? `, ...and ${remainder} more` : ''})`);
                     }
-                    ui.dim('    Review `git status` before committing — deployed artifacts may be tracked.');
+                    ui.dim(dryRun
+                        ? '    Re-run without --dry-run to remove them.'
+                        : '    Review `git status` before committing — deployed artifacts may be tracked.');
                 }
                 // #2506: keep the recorded deployment state consistent with what the
                 // prune actually left on disk, so a later run does not trust counts
-                // for artifacts that no longer exist.
-                await reconcileDeployedToAfterPrune(ctx.cwd, staleAgentRemovals, pruneOtherProviders ? detectedProvider : null);
+                // for artifacts that no longer exist. A dry run deleted nothing, so the
+                // recorded state is already accurate.
+                if (!dryRun) {
+                    await reconcileDeployedToAfterPrune(ctx.cwd, staleAgentRemovals, pruneOtherProviders ? detectedProvider : null);
+                }
             }
             catch {
                 if (!quiet)
@@ -685,7 +743,9 @@ export const refreshHandler = {
                         // #2506: a run that deleted artifacts is not an "up to date" run.
                         const removed = staleAgentRemovals.reduce((sum, item) => sum + item.paths.length, 0);
                         if (!quiet) {
-                            ui.warn(`Deployments current, but ${removed} stale artifact(s) were removed this run — review the list above`);
+                            ui.warn(dryRun
+                                ? `Deployments current, but ${removed} stale artifact(s) would be removed — review the list above`
+                                : `Deployments current, but ${removed} stale artifact(s) were removed this run — review the list above`);
                         }
                     }
                     else {

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/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)
@@ -259,7 +276,15 @@ async function handleSteward(args, ctx) {
                 return;
             }
             const diagnostics = await auditLegacyPermissions(projectDir, config);
-            console.log(`  ${dryRun ? 'Would normalize' : 'Normalizing'} ${diagnostics.filter(d => d.code.startsWith('legacy-')).length} legacy permission source(s).`);
+            const legacyCount = diagnostics.filter(d => d.code.startsWith('legacy-')).length;
+            if (legacyCount === 0 && !config.authorization) {
+                // Nothing legacy to convert: the only work is writing the initial
+                // default-deny block, which is what clears doctor's warning (#2563).
+                console.log(`  ${dryRun ? 'Would write' : 'Writing'} an initial default-deny authorization block (no legacy permission sources found).`);
+            }
+            else {
+                console.log(`  ${dryRun ? 'Would normalize' : 'Normalizing'} ${legacyCount} legacy permission source(s).`);
+            }
             console.log(`  Result: ${Object.keys(normalized.authorization?.permissions ?? {}).length} permissions, ${Object.keys(normalized.authorization?.roles ?? {}).length} roles, ${normalized.authorization?.assignments.length ?? 0} assignments; default deny.`);
             if (apply) {
                 const backup = await backupConfig(projectDir);
@@ -273,7 +298,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 +623,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

@@ -694,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.',
@@ -736,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,
@@ -1253,6 +1256,10 @@ async function deployOneProjectLocalBundle(opts) {
             // never reach <provider>/.aiwg/skills/, leaving them invisible to
             // both the platform and the index.
             '--copy-all',
+            // That copy-all is the deployer's doing, not the operator's, so the
+            // provider's startup listing cap still applies; overflow lands on the
+            // standard tier instead of over the cap (#2561).
+            '--listing-budget',
             // 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
@@ -1269,7 +1276,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

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

@@ -12,7 +12,7 @@ import { getVersionInfo } from '../../channel/manager.mjs';
 import { getLoggerInfo } from '../log.js';
 import * as ui from '../ui.js';
 import { maybePrintCommunityFooter } from '../../community/footer.js';
-import { existsSync, statSync, readdirSync } from 'fs';
+import { existsSync, statSync, readdirSync, readFileSync } from 'fs';
 import path from 'path';
 /**
  * Version command handler
@@ -30,6 +30,27 @@ export const versionHandler = {
         return { exitCode: 0 };
     },
 };
+/**
+ * Print the installation-drift notice when the canonical declaration and the
+ * running binary disagree. Keeps `aiwg version` honest about which one it is
+ * describing, and names the command that explains the rest (#2529).
+ */
+function printDrift(fp) {
+    if (fp.drift) {
+        const method = fp.installation?.identity?.method ?? 'unrecorded';
+        const declared = fp.drift.canonicalVersion ? ` (${fp.drift.canonicalVersion})` : '';
+        ui.dim(`    ! canonical install declares ${method} at ${fp.drift.canonicalRoot}${declared} — run \`aiwg installation show\``);
+        return;
+    }
+    // Same root, different method (a source checkout recorded as npm, or the
+    // reverse) is drift too; `version` is the first recovery command an operator
+    // reaches for, so it must say so instead of looking aligned (#2559).
+    const state = fp.installation?.state;
+    if (state && state !== 'aligned' && state !== 'unrecorded') {
+        const reasons = Array.isArray(fp.installation?.drift) ? fp.installation.drift : [];
+        ui.dim(`    ! installation identity ${state}: ${reasons.join('; ') || 'see aiwg installation show'} — run \`aiwg installation show\``);
+    }
+}
 function collectFingerprint(versionInfo) {
     const loggerInfo = getLoggerInfo();
     const fp = {
@@ -62,6 +83,22 @@ function collectFingerprint(versionInfo) {
             path: versionInfo.edgePath ?? versionInfo.packageRoot,
         };
     }
+    // `version` is the first thing anyone runs to answer "what am I on". If the
+    // canonical install declares a different root than the one executing, say so
+    // here rather than letting drift persist while every check looks correct.
+    const canonicalRoot = fp.installation?.identity?.root;
+    const actualRoot = fp.installation?.actualRoot;
+    if (canonicalRoot && actualRoot && path.resolve(canonicalRoot) !== path.resolve(actualRoot)) {
+        let canonicalVersion = null;
+        try {
+            const pkg = JSON.parse(readFileSync(path.join(canonicalRoot, 'package.json'), 'utf8'));
+            canonicalVersion = pkg.version ?? null;
+        }
+        catch {
+            // Canonical root may not exist or be readable; report the drift regardless.
+        }
+        fp.drift = { canonicalRoot, canonicalVersion, actualRoot };
+    }
     // Locale / timezone are useful for timezone-dependent bug reports.
     try {
         fp.locale = Intl.DateTimeFormat().resolvedOptions().locale;
@@ -96,13 +133,12 @@ async function displayVersion(opts) {
     ui.blank();
     console.log(`  ${ui.brandMark()} ${ui.bold('aiwg')}  ${ui.bold(fp.version)}  ${ui.channelLabel(fp.channel)}`);
     if (!opts.verbose) {
-        if (fp.git) {
+        if (fp.git)
             ui.dim(`    git: ${fp.git.sha} (${fp.git.branch})`);
-            ui.dim(`    path: ${fp.git.path}`);
-        }
-        else {
-            ui.dim(`    path: ${fp.packageRoot}`);
-        }
+        // Always the root that actually executed — not the declared edge checkout,
+        // which is what made drift invisible here (#2529).
+        ui.dim(`    path: ${fp.packageRoot}`);
+        printDrift(fp);
         maybePrintCommunityFooter();
         ui.blank();
         return;
@@ -110,15 +146,14 @@ async function displayVersion(opts) {
     // --verbose: the full environment fingerprint.
     if (fp.git) {
         ui.dim(`    git:       ${fp.git.sha} (${fp.git.branch})`);
-        ui.dim(`    path:      ${fp.git.path}`);
-    }
-    else {
-        ui.dim(`    path:      ${fp.packageRoot}`);
+        if (fp.git.path !== fp.packageRoot)
+            ui.dim(`    edge:      ${fp.git.path}`);
     }
+    ui.dim(`    path:      ${fp.packageRoot}`);
     ui.dim(`    channel:   ${fp.channel}`);
-    ui.dim(`    install:   ${fp.installation.identity?.method ?? 'unrecorded'} (${fp.installation.state})`);
-    ui.dim(`    canonical: ${fp.installation.identity?.root ?? '(unrecorded)'}`);
-    ui.dim(`    actual:    ${fp.installation.actualRoot}`);
+    ui.dim(`    install:   ${fp.installation?.identity?.method ?? 'unrecorded'} (${fp.installation?.state ?? 'unknown'})`);
+    ui.dim(`    canonical: ${fp.installation?.identity?.root ?? '(unrecorded)'}`);
+    ui.dim(`    actual:    ${fp.installation?.actualRoot ?? fp.packageRoot}`);
     ui.dim(`    node:      ${fp.node}`);
     ui.dim(`    platform:  ${fp.platform.os} ${fp.platform.arch} (${fp.platform.release})`);
     ui.dim(`    tty:       stdin=${fp.tty.stdin} stdout=${fp.tty.stdout} stderr=${fp.tty.stderr}`);

package/dist/src/cli/handlers/workspace-context.js

@@ -55,6 +55,14 @@ export const workspaceContextHandler = {
                     console.log(JSON.stringify(result, null, 2));
                 else {
                     console.log(`${result.dryRun ? 'Migration dry run' : 'Migration applied'}: ${result.changed ? 'changes found' : 'already canonical'}`);
+                    for (const entry of result.audit.plan.routing) {
+                        console.log(`  ${entry.source}: ${entry.operatorBytes.toLocaleString()} chars -> ${entry.destination} (${entry.scope})`);
+                    }
+                    for (const entry of result.audit.plan.scopeReview) {
+                        console.log(`  REVIEW ${entry.source} carries ${entry.operatorBytes.toLocaleString()} chars of operator content and is scoped to ${entry.scope} by filename.`);
+                        console.log('         Content in .aiwg/context/providers/ is read by that provider only.');
+                        console.log("         If this is project-neutral methodology, move it into WORKSPACE.md's Project Context section first.");
+                    }
                     for (const file of result.written)
                         console.log(`  ${result.dryRun ? 'would write' : 'wrote'} ${file}`);
                     if (result.transactionId)