@aiwg/cli 2026.7.19 → 2026.7.20

package/dist/src/cli/handlers/resource-versions.js

@@ -0,0 +1,247 @@
+import path from "node:path";
+import { loadResourceTrustRootFile, readVerifiedRegularFile, resolveWebRelease, } from "../../resources/web-release.js";
+import { getProjectDir } from "../../config/aiwg-config.js";
+import { cleanWebResourceCache } from "../../resources/cache-cleanup.js";
+import { writeWebResourceLock } from "../../resources/lockfile.js";
+const MAX_RESOURCE_MANIFEST_BYTES = 4 * 1024 * 1024;
+const DEFAULT_CHANNELS = ["stable", "latest", "canary", "main"];
+function usage() {
+    return [
+        "Usage: aiwg versions <list|resolve|show|clean-cache> [selector] [--json] [--pretty] [--offline]",
+        "",
+        "Examples:",
+        "  aiwg versions list --json",
+        "  aiwg versions resolve stable --json",
+        "  aiwg versions resolve stable --write-lock",
+        "  aiwg versions show 2026.7.18",
+        "  aiwg versions clean-cache --dry-run",
+    ].join("\n");
+}
+function flagValue(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${flag} requires a value`);
+    return value;
+}
+function parseArgs(args) {
+    const [rawSubcommand = "list", ...rest] = args;
+    if (rawSubcommand !== "list" &&
+        rawSubcommand !== "resolve" &&
+        rawSubcommand !== "show" &&
+        rawSubcommand !== "clean-cache") {
+        throw new Error(`Unknown versions subcommand: ${rawSubcommand}\n\n${usage()}`);
+    }
+    const valueFlagIndexes = new Set();
+    for (const flag of ["--channels", "--target", "--prefix"]) {
+        const index = rest.indexOf(flag);
+        if (index !== -1) {
+            valueFlagIndexes.add(index);
+            valueFlagIndexes.add(index + 1);
+        }
+    }
+    const positionals = rest.filter((arg, index) => !arg.startsWith("--") && !valueFlagIndexes.has(index));
+    if ((rawSubcommand === "resolve" || rawSubcommand === "show") && positionals.length !== 1) {
+        throw new Error(`aiwg versions ${rawSubcommand} requires exactly one version, range, digest, or channel selector\n\n${usage()}`);
+    }
+    if (rawSubcommand === "list" && positionals.length > 0) {
+        throw new Error(`aiwg versions list does not accept positional selectors\n\n${usage()}`);
+    }
+    if (rawSubcommand === "clean-cache" && positionals.length > 0) {
+        throw new Error(`aiwg versions clean-cache does not accept positional selectors\n\n${usage()}`);
+    }
+    const writeLock = rest.includes("--write-lock");
+    if ((rawSubcommand === "list" || rawSubcommand === "clean-cache") && writeLock) {
+        throw new Error(`aiwg versions ${rawSubcommand} cannot write resources.lock.json; use resolve or show with --write-lock`);
+    }
+    const channelsValue = flagValue(rest, "--channels");
+    const channels = channelsValue
+        ? channelsValue.split(",").map((channel) => channel.trim()).filter(Boolean)
+        : [...DEFAULT_CHANNELS];
+    if (channels.length === 0)
+        throw new Error("--channels must include at least one channel");
+    return {
+        subcommand: rawSubcommand,
+        selector: positionals[0],
+        json: rest.includes("--json") || rest.includes("--format=json"),
+        pretty: rest.includes("--pretty"),
+        offline: rest.includes("--offline"),
+        writeLock,
+        dryRun: rest.includes("--dry-run"),
+        force: rest.includes("--force"),
+        channels,
+    };
+}
+function webReleaseOptionsFromEnvironment() {
+    const baseUrl = process.env.AIWG_RESOURCE_BASE_URL;
+    const cacheRoot = process.env.AIWG_RESOURCE_CACHE_ROOT;
+    const trustRootFile = process.env.AIWG_RESOURCE_TRUST_ROOT_FILE;
+    const publicKeyPem = trustRootFile === undefined
+        ? undefined
+        : loadResourceTrustRootFile(path.resolve(trustRootFile));
+    return {
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        ...(cacheRoot === undefined ? {} : { cacheRoot }),
+        ...(publicKeyPem === undefined ? {} : { publicKeyPem }),
+        ...(process.env.AIWG_RESOURCE_ALLOW_INSECURE_LOOPBACK_HTTP === "1"
+            ? { allowInsecureLoopbackHttp: true }
+            : {}),
+    };
+}
+function readManifestSummary(release) {
+    const bytes = readVerifiedRegularFile(release.releaseManifestPath, {
+        label: "verified AIWG resource release manifest",
+        maxBytes: MAX_RESOURCE_MANIFEST_BYTES,
+        expectedSha256: release.manifestDigest,
+    });
+    const value = JSON.parse(bytes.toString("utf8"));
+    const bundles = Array.isArray(value.bundles) ? value.bundles : [];
+    const files = Array.isArray(value.files) ? value.files : [];
+    return {
+        schemaVersion: value.schemaVersion,
+        version: value.version,
+        compatibility: value.compatibility,
+        source: value.source,
+        bundles,
+        fileCount: files.length,
+    };
+}
+function releaseJson(release, manifest, lockfilePath) {
+    return {
+        selector: release.selector,
+        selectorKind: release.selectorKind,
+        version: release.version,
+        manifestSha256: release.manifestDigest,
+        manifestUrl: release.manifestUrl,
+        baseUrl: release.baseUrl,
+        cacheDir: release.cacheDir,
+        channelSequence: release.channelSequence,
+        fortemiCore: {
+            manifestSha256: release.fortemiManifestSha256,
+            manifestSize: release.fortemiManifestSize,
+            exportSha256: release.fortemiExportSha256,
+            exportSize: release.fortemiExportSize,
+        },
+        descriptorCount: release.descriptors.size,
+        ...(lockfilePath === undefined ? {} : { lockfile: lockfilePath }),
+        ...(manifest === undefined ? {} : { manifest }),
+    };
+}
+function printJson(value, pretty) {
+    console.log(JSON.stringify(value, null, pretty ? 2 : 0));
+}
+function printReleaseText(release, manifest, lockfilePath) {
+    console.log(`selector: ${release.selector} (${release.selectorKind})`);
+    console.log(`version: ${release.version}`);
+    if (release.channelSequence !== undefined)
+        console.log(`channel_sequence: ${release.channelSequence}`);
+    console.log(`manifest_sha256: ${release.manifestDigest}`);
+    console.log(`manifest_url: ${release.manifestUrl}`);
+    console.log(`cache_dir: ${release.cacheDir}`);
+    console.log(`fortemi_manifest_sha256: ${release.fortemiManifestSha256}`);
+    console.log(`fortemi_export_sha256: ${release.fortemiExportSha256}`);
+    console.log(`descriptor_count: ${release.descriptors.size}`);
+    if (lockfilePath !== undefined)
+        console.log(`lockfile: ${lockfilePath}`);
+    if (manifest) {
+        console.log(`schema_version: ${String(manifest.schemaVersion)}`);
+        console.log(`file_count: ${manifest.fileCount}`);
+        console.log(`bundle_count: ${manifest.bundles.length}`);
+    }
+}
+export const versionsHandler = {
+    id: "versions",
+    name: "Resource Versions",
+    description: "Browse and resolve signed AIWG web resource releases",
+    category: "index",
+    aliases: [],
+    async execute(ctx) {
+        if (ctx.args[0] === "help" || ctx.args[0] === "--help" || ctx.args[0] === "-h") {
+            console.log(usage());
+            return { exitCode: 0 };
+        }
+        let parsed;
+        try {
+            parsed = parseArgs(ctx.args);
+        }
+        catch (error) {
+            return { exitCode: 2, message: error instanceof Error ? error.message : String(error) };
+        }
+        try {
+            const baseOptions = webReleaseOptionsFromEnvironment();
+            if (parsed.subcommand === "clean-cache") {
+                const result = cleanWebResourceCache(getProjectDir(ctx, ctx.args), {
+                    cacheRoot: process.env.AIWG_RESOURCE_CACHE_ROOT,
+                    dryRun: parsed.dryRun,
+                    force: parsed.force,
+                });
+                if (parsed.json) {
+                    printJson(result, parsed.pretty);
+                }
+                else {
+                    console.log(`cache_root: ${result.cacheRoot}`);
+                    console.log(`dry_run: ${result.dryRun}`);
+                    console.log(`force: ${result.force}`);
+                    console.log(`locked: ${result.locked.length}`);
+                    console.log(`preserved: ${result.preserved.length}`);
+                    console.log(`removed: ${result.removed.length}`);
+                    console.log(`skipped: ${result.skipped.length}`);
+                }
+                return { exitCode: 0 };
+            }
+            if (parsed.subcommand === "list") {
+                const resolved = [];
+                const unavailable = [];
+                for (const channel of parsed.channels) {
+                    try {
+                        const release = await resolveWebRelease({
+                            ...baseOptions,
+                            selector: channel,
+                            offline: parsed.offline,
+                        });
+                        resolved.push(releaseJson(release));
+                    }
+                    catch (error) {
+                        unavailable.push({
+                            channel,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+                if (parsed.json) {
+                    printJson({ channels: resolved, unavailable }, parsed.pretty);
+                }
+                else {
+                    for (const release of resolved) {
+                        console.log(`${release.selector}: ${release.version} ${release.manifestSha256}`);
+                    }
+                    if (resolved.length === 0)
+                        console.log("No configured channels resolved.");
+                }
+                return { exitCode: 0 };
+            }
+            const release = await resolveWebRelease({
+                ...baseOptions,
+                selector: parsed.selector,
+                offline: parsed.offline,
+            });
+            const manifest = parsed.subcommand === "show" ? readManifestSummary(release) : undefined;
+            const lockfilePath = parsed.writeLock
+                ? writeWebResourceLock(getProjectDir(ctx, ctx.args), release).path
+                : undefined;
+            if (parsed.json) {
+                printJson(releaseJson(release, manifest, lockfilePath), parsed.pretty);
+            }
+            else {
+                printReleaseText(release, manifest, lockfilePath);
+            }
+            return { exitCode: 0 };
+        }
+        catch (error) {
+            return { exitCode: 1, message: error instanceof Error ? error.message : String(error) };
+        }
+    },
+};
+//# sourceMappingURL=resource-versions.js.map

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

@@ -1115,9 +1115,44 @@ export const packagePluginHandler = {
     category: "plugin",
     aliases: ["-package-plugin", "--package-plugin"],
     async execute(ctx) {
+        if (ctx.args.includes("--help") || ctx.args.includes("-h")) {
+            return {
+                exitCode: 0,
+                message: [
+                    "aiwg package-plugin — package a project-local or built-in marketplace wrapper",
+                    "",
+                    "Usage:",
+                    "  aiwg package-plugin <name> [--source <path>] [--output <path>] [--provider <name>] [--clean] [--dry-run]",
+                    "  aiwg package-plugin --plugin <name> [options]  # compatibility form",
+                    "",
+                    "Options:",
+                    "  --source <path>    explicit project-local wrapper source (must stay inside the project)",
+                    "  --output <path>    standalone archive output (default: dist/plugins)",
+                    "  --provider <name>  claude, codex, or all for standalone wrappers; built-ins retain all formats",
+                    "  --clean            clean generated plugin output before packaging",
+                    "  --dry-run, -n      preview without writing",
+                    "  --help, -h         show this help",
+                    "",
+                    "Project-local wrappers are discovered under .aiwg/plugins and packaged as deterministic archives.",
+                ].join("\n"),
+            };
+        }
+        const hasExplicitPlugin = ctx.args.includes("--plugin") || ctx.args.includes("-p");
+        const positional = ctx.args[0] && !ctx.args[0].startsWith("-")
+            ? ctx.args[0]
+            : undefined;
+        if (!hasExplicitPlugin && !positional) {
+            return {
+                exitCode: 1,
+                message: "Error: plugin name is required.\n\nRun `aiwg package-plugin --help` for usage.",
+            };
+        }
+        const normalizedArgs = hasExplicitPlugin
+            ? ctx.args
+            : ["--plugin", positional, ...ctx.args.slice(1)];
         const frameworkRoot = await getFrameworkRoot();
         const runner = createScriptRunner(frameworkRoot);
-        return runner.run("tools/plugin/package-plugins.mjs", ctx.args, {
+        return runner.run("tools/plugin/package-plugins.mjs", normalizedArgs, {
             cwd: ctx.cwd,
         });
     },
@@ -1134,6 +1169,23 @@ export const packageAllPluginsHandler = {
     category: "plugin",
     aliases: ["-package-all-plugins", "--package-all-plugins"],
     async execute(ctx) {
+        if (ctx.args.includes("--help") || ctx.args.includes("-h")) {
+            return {
+                exitCode: 0,
+                message: [
+                    "aiwg package-all-plugins — package every built-in marketplace wrapper",
+                    "",
+                    "Usage:",
+                    "  aiwg package-all-plugins [--provider <name>] [--clean] [--dry-run]",
+                    "",
+                    "Options:",
+                    "  --provider <name>  claude, codex, cursor, factory, openclaw, or all",
+                    "  --clean            clean generated plugin output before packaging",
+                    "  --dry-run, -n      preview without writing",
+                    "  --help, -h         show this help",
+                ].join("\n"),
+            };
+        }
         const frameworkRoot = await getFrameworkRoot();
         const runner = createScriptRunner(frameworkRoot);
         return runner.run("tools/plugin/package-plugins.mjs", ["--all", ...ctx.args], {
@@ -1199,7 +1251,7 @@ export const corpusHandler = {
  * with the project's general-purpose artifact graph indices.
  *
  *   aiwg discover "<phrase>" [--limit N] [--type skill,agent,...] [--json]
- *     [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]
+ *     [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]
  */
 export const discoverHandler = {
     id: "discover",
@@ -1254,7 +1306,7 @@ export const featuresHandler = {
  * so consumers don't need to navigate AIWG's storage paths themselves.
  *
  *   aiwg show <name> [--type skill,agent,...] [--json] [--first]
- *     [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]
+ *     [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]
  */
 export const showHandler = {
     id: "show",

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

@@ -775,9 +775,18 @@ async function countBundleSourceArtifacts(bundlePath) {
  */
 async function deployOneProjectLocalBundle(opts) {
     const { bundle, ctx, frameworkRoot, provider, target, dryRun, verbose, quiet, modelArgs } = opts;
+    const counts = await countBundleSourceArtifacts(bundle.artifactPath);
+    const artifactTotal = counts.agents + counts.commands + counts.skills + counts.rules;
+    if (verbose || dryRun) {
+        ui.dim(`  Artifacts: agents=${counts.agents} commands=${counts.commands} skills=${counts.skills} rules=${counts.rules}`);
+    }
+    if (artifactTotal === 0) {
+        ui.warn(`Project-local ${bundle.type} '${bundle.id}' has no deployable agents, commands, skills, or rules at ${bundle.artifactPath}`);
+        return { exitCode: 1, counts };
+    }
     const runner = createScriptRunner(frameworkRoot);
     const args = [
-        '--source', bundle.bundlePath,
+        '--source', bundle.artifactPath,
         '--deploy-commands', '--deploy-skills', '--deploy-rules',
         '--provider', provider,
         '--target', target,
@@ -814,7 +823,6 @@ async function deployOneProjectLocalBundle(opts) {
     });
     // Approximate counts from the bundle's source dirs (deploy-agents.mjs is
     // idempotent and copies file-for-file from these dirs)
-    const counts = await countBundleSourceArtifacts(bundle.bundlePath);
     void ctx;
     return { exitCode: result.exitCode, counts };
 }
@@ -903,6 +911,10 @@ async function deployProjectLocalBundles(opts) {
         if (verbose || dryRun) {
             const action = dryRun ? '[dry-run] Would deploy' : 'Deploying';
             console.log(`${action} project-local ${bundle.type} '${bundle.id}' from ${bundle.localPath} → ${provider}`);
+            if (bundle.artifactPath !== bundle.bundlePath) {
+                const payloadDisplay = path.relative(projectDir, bundle.artifactPath) || '.';
+                ui.dim(`  Resolved plugin payload: ${payloadDisplay}`);
+            }
         }
         const result = await deployOneProjectLocalBundle({
             bundle, ctx, frameworkRoot, provider, target, dryRun, verbose, quiet, modelArgs,
@@ -941,7 +953,7 @@ async function deployProjectLocalBundles(opts) {
                 const mHash = await hashManifest(manifestAbsPath);
                 // #1037 — record per-artifact source hashes so `aiwg remove` can
                 // detect pristine vs mutated vs replaced deployed files.
-                const artifactHashes = await hashBundleArtifacts(bundle.bundlePath);
+                const artifactHashes = await hashBundleArtifacts(bundle.artifactPath);
                 const updated = updateInstalled(config, bundle.id, provider, result.counts, {
                     version: bundle.manifest.version,
                     source: 'project-local',

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

@@ -14,7 +14,7 @@ import fsp from 'fs/promises';
 import path from 'path';
 import { createScriptRunner } from './script-runner.js';
 import { getFrameworkRoot } from '../../channel/manager.mjs';
-import { forceUpdateCheck } from '../../update/checker.mjs';
+import { updateInstallation } from '../../update/service.mjs';
 import { useHandler as useFrameworkHandler } from './use.js';
 import { projectAiwgPath } from '../../config/project-artifacts.js';
 import { checkCollisions, } from '../../smiths/skillsmith/collision-detector.js';
@@ -536,6 +536,21 @@ export const doctorHandler = {
         catch {
             // Project-local section is non-fatal for doctor
         }
+        // Web-backed resource lock/cache diagnostics (#1850). Report lock source
+        // mode, cold cache, and digest drift without requiring web mode to be in use.
+        try {
+            const { buildWebResourceDoctorSection } = await import('../../resources/doctor.js');
+            const section = buildWebResourceDoctorSection(ctx.cwd || process.cwd(), {
+                cacheRoot: process.env.AIWG_RESOURCE_CACHE_ROOT,
+            });
+            if (section.output)
+                console.log(section.output);
+            if (section.hasFailures)
+                return { exitCode: 1, message: '' };
+        }
+        catch (error) {
+            console.log(`\n── Web resource cache ──\n  ⚠ unable to audit: ${error instanceof Error ? error.message : String(error)}`);
+        }
         // Canonical workspace-context graph diagnostics (#1811). Legacy projects
         // remain valid; drift, loops, conflicts, and possible credentials fail.
         try {
@@ -578,7 +593,7 @@ export const updateHandler = {
     name: 'Update',
     description: 'Update AIWG and re-deploy installed frameworks',
     category: 'maintenance',
-    aliases: ['-update', '--update'],
+    aliases: ['-update', '--update', 'upgrade'],
     async execute(ctx) {
         const args = ctx.args;
         const deployAll = args.includes('--all');
@@ -592,8 +607,12 @@ export const updateHandler = {
         // Step 1: Check for package updates (unless --skip-check)
         if (!skipCheck) {
             try {
-                console.log('Checking for AIWG updates...\n');
-                await forceUpdateCheck();
+                console.log('Updating AIWG installation...\n');
+                const update = await updateInstallation({
+                    dryRun,
+                    offline: args.includes('--offline'),
+                });
+                console.log(`${update.message}\n`);
             }
             catch (error) {
                 console.error(`Warning: Update check failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -626,30 +645,12 @@ export const updateHandler = {
             console.log('  aiwg use all');
             return { exitCode: 0 };
         }
-        // Map registry IDs to framework use-names
-        const installedFrameworks = [];
-        const unmapped = [];
-        for (const fw of registry.frameworks) {
-            const useName = REGISTRY_ID_TO_USE_NAME[fw.id];
-            if (useName) {
-                installedFrameworks.push(useName);
-            }
-            else {
-                unmapped.push(fw.id);
-            }
-        }
-        if (installedFrameworks.length === 0) {
-            console.log('No recognized frameworks in registry');
-            if (unmapped.length > 0) {
-                console.log(`Unrecognized entries: ${unmapped.join(', ')}`);
-            }
-            return { exitCode: 0 };
-        }
+        // Canonical framework IDs need their historical public aliases. Add-ons,
+        // extensions, and project-local bundles are already accepted by `aiwg use`,
+        // so preserve their registry IDs instead of silently skipping them.
+        const installedFrameworks = registry.frameworks.map(item => REGISTRY_ID_TO_USE_NAME[item.id] ?? item.id);
         // Report what will be updated
         console.log(`Installed frameworks: ${installedFrameworks.join(', ')}`);
-        if (unmapped.length > 0) {
-            console.log(`Skipping unrecognized: ${unmapped.join(', ')}`);
-        }
         console.log('');
         if (dryRun) {
             console.log('Dry run: Would re-deploy the following frameworks:');

package/dist/src/config/cli.js

@@ -21,6 +21,7 @@ import { fileURLToPath } from 'url';
 import path from 'path';
 import { UserConfig } from './user-config.js';
 import { AiwgError, EXIT_CODES } from '../cli/errors.js';
+import { projectAiwgPath, resolveProjectAiwgDir } from './project-artifacts.js';
 const _scriptDir = path.dirname(fileURLToPath(import.meta.url));
 /**
  * Main CLI entry point for `aiwg config <subcommand> [args]`
@@ -182,7 +183,7 @@ async function projectConfigGet(key, args) {
     if (!cfg) {
         throw new AiwgError({
             code: 'ERR_NO_PROJECT_CONFIG',
-            message: 'No .aiwg/aiwg.config in this project.',
+            message: 'No project AIWG config found at the resolved artifact root.',
             hint: 'Run `aiwg init`, then ask your AIWG agent to set up repo/tracker/delivery policy.',
             exitCode: EXIT_CODES.CONFIG,
         });
@@ -362,7 +363,7 @@ async function handleProjectValidate(args) {
     if (!cfg) {
         throw new AiwgError({
             code: 'ERR_NO_PROJECT_CONFIG',
-            message: 'No .aiwg/aiwg.config in this project.',
+            message: 'No project AIWG config found at the resolved artifact root.',
             hint: 'Run `aiwg init`, then configure project policy.',
             exitCode: EXIT_CODES.CONFIG,
         });
@@ -403,7 +404,8 @@ async function handleProjectValidate(args) {
             ? validateIssueLabels(cfg.issues)
             : resolveIssueLabels(undefined, 'local').diagnostics;
     const diagnostics = [...indexErrors, ...externalLinkErrors, ...labelDiagnostics];
-    console.log(`Project config: ${projectDir}/.aiwg/aiwg.config\n`);
+    console.log(`Project config: ${projectAiwgPath(projectDir, 'aiwg.config')}`);
+    console.log(`Artifact root:  ${resolveProjectAiwgDir(projectDir)}\n`);
     if (diagnostics.length === 0) {
         console.log('✓ Project config valid');
         return;
@@ -464,7 +466,7 @@ async function projectConfigReset(key, args) {
     if (!cfg) {
         throw new AiwgError({
             code: 'ERR_NO_PROJECT_CONFIG',
-            message: 'No .aiwg/aiwg.config in this project.',
+            message: 'No project AIWG config found at the resolved artifact root.',
             hint: 'Run `aiwg init`, then ask your AIWG agent to establish project policy.',
             exitCode: EXIT_CODES.CONFIG,
         });
@@ -553,7 +555,7 @@ For project-level config: aiwg config show --project [--json]
     if (!cfg) {
         throw new AiwgError({
             code: 'ERR_NO_PROJECT_CONFIG',
-            message: 'No .aiwg/aiwg.config in this project.',
+            message: 'No project AIWG config found at the resolved artifact root.',
             hint: 'Run `aiwg init`, then ask your AIWG agent to set up repo/tracker/delivery policy.',
             exitCode: EXIT_CODES.CONFIG,
         });
@@ -593,7 +595,8 @@ For project-level config: aiwg config show --project [--json]
         return;
     }
     // Human-readable view
-    console.log(`Project config: ${projectDir}/.aiwg/aiwg.config\n`);
+    console.log(`Project config: ${projectAiwgPath(projectDir, 'aiwg.config')}`);
+    console.log(`Artifact root:  ${resolveProjectAiwgDir(projectDir)}\n`);
     console.log(`Schema version: ${cfg.version}`);
     console.log(`Providers:      ${cfg.providers.join(', ') || '(none)'}`);
     console.log('');
@@ -663,13 +666,14 @@ function printUsage() {
 
 Subcommands:
   get <key>                       Read a user config value
-  get --project <key>             Read a project config value (.aiwg/aiwg.config)
+  get --project <key>             Read a project config value (default .aiwg/aiwg.config;
+                                  AIWG_ARTIFACTS_PATH may override the artifact root)
   set <key> <value>               Write a user config value
   set --project <key> <value>     Write a project config value (validates enums)
   list                Show all user config
-  show --project      Show resolved project config (.aiwg/aiwg.config)
+  show --project      Show resolved project config and artifact root
   validate            Validate user config files
-  validate --project  Validate .aiwg/aiwg.config taxonomy/index semantics
+  validate --project  Validate resolved project config taxonomy/index semantics
     [--provider gitea|github|local] [--available-label NAME ...]
   reset [<key>]       Reset key or all config to defaults
   path                Print config directory path

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

@@ -0,0 +1,68 @@
+/**
+ * Runtime implementation of project AIWG artifact directory resolution.
+ *
+ * Kept as ESM JavaScript so direct `.mjs` tools and compiled TypeScript
+ * consumers share exactly one resolver implementation.
+ */
+
+import { homedir } from 'os';
+import { existsSync, readFileSync } from 'fs';
+import { isAbsolute, join, resolve } from 'path';
+
+export const DEFAULT_PROJECT_AIWG_DIR = '.aiwg';
+export const AIWG_ARTIFACTS_PATH_ENV = 'AIWG_ARTIFACTS_PATH';
+export const PROJECT_AIWG_LOCATION_FILE = '.aiwg-location';
+
+const ARTIFACT_PATH_ENV_ALIASES = [
+  AIWG_ARTIFACTS_PATH_ENV,
+  'AIWG_PROJECT_ARTIFACTS_PATH',
+  'AIWG_PROJECT_AIWG_DIR',
+];
+
+export function expandProjectArtifactPath(pathValue, projectDir) {
+  const trimmed = pathValue.trim();
+  if (trimmed === '~') return homedir();
+  if (trimmed.startsWith('~/')) return resolve(homedir(), trimmed.slice(2));
+  if (isAbsolute(trimmed)) return trimmed;
+  return resolve(projectDir, trimmed);
+}
+
+export function parseProjectArtifactLocation(contents) {
+  for (const rawLine of contents.split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (line.length === 0 || line.startsWith('#')) continue;
+    if (line.startsWith('export ')) line = line.slice('export '.length).trim();
+    const assignment = line.match(/^AIWG_ARTIFACTS_PATH\s*=\s*(.+)$/);
+    if (assignment) line = assignment[1].trim();
+    if (
+      (line.startsWith('"') && line.endsWith('"')) ||
+      (line.startsWith("'") && line.endsWith("'"))
+    ) {
+      line = line.slice(1, -1);
+    }
+    return line.length > 0 ? line : null;
+  }
+  return null;
+}
+
+export function readProjectArtifactLocation(projectDir) {
+  const pointerPath = resolve(projectDir, PROJECT_AIWG_LOCATION_FILE);
+  if (!existsSync(pointerPath)) return null;
+  return parseProjectArtifactLocation(readFileSync(pointerPath, 'utf-8'));
+}
+
+export function resolveProjectAiwgDir(projectDir, env = process.env) {
+  for (const key of ARTIFACT_PATH_ENV_ALIASES) {
+    const value = env[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return expandProjectArtifactPath(value, projectDir);
+    }
+  }
+  const configuredLocation = readProjectArtifactLocation(projectDir);
+  if (configuredLocation) return expandProjectArtifactPath(configuredLocation, projectDir);
+  return resolve(projectDir, DEFAULT_PROJECT_AIWG_DIR);
+}
+
+export function projectAiwgPath(projectDir, ...segments) {
+  return join(resolveProjectAiwgDir(projectDir), ...segments);
+}