@aiwg/cli 2026.7.18 → 2026.7.20

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

@@ -62,6 +62,7 @@ export async function buildContextFinalizationBlock(projectPath) {
     const installedNames = installed.map(([name]) => name);
     const providerDeployments = new Set();
     const normalizedAiwgMdPath = displayProjectPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
+    const normalizedAiwgMdLabel = `\`${normalizedAiwgMdPath}\``;
     for (const [, entry] of installed) {
         for (const provider of Object.keys(entry.deployedTo ?? {})) {
             providerDeployments.add(provider);
@@ -94,9 +95,9 @@ export async function buildContextFinalizationBlock(projectPath) {
         '',
         '### Source Model',
         '',
-        '- `.aiwg/AIWG.md` is the normalized project-local context entry point.',
+        `- ${normalizedAiwgMdLabel} is the normalized project-local context entry point.`,
         '- Root `AIWG.md` is the generated cross-provider companion loaded through `AGENTS.md` and provider twins.',
-        '- `AGENTS.md`, `WARP.md`, `.hermes.md`, and `.github/copilot-instructions.md` are provider-facing bridges, not replacements for `.aiwg/AIWG.md`.',
+        `- \`AGENTS.md\`, \`WARP.md\`, \`.hermes.md\`, and \`.github/copilot-instructions.md\` are provider-facing bridges, not replacements for ${normalizedAiwgMdLabel}.`,
         FINALIZATION_END,
         '',
     ];
@@ -113,6 +114,7 @@ export function replaceOrAppendFinalizationBlock(content, block) {
 export async function buildNormalizedAiwgMd(projectPath, existing = '') {
     const block = await buildContextFinalizationBlock(projectPath);
     const externalLinksSection = await buildExternalLinksSection(projectPath);
+    const normalizedAiwgMdPath = displayProjectPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
     const base = existing.trim().length > 0
         ? existing
         : [
@@ -120,7 +122,7 @@ export async function buildNormalizedAiwgMd(projectPath, existing = '') {
             AIWG_SIGNATURE_COMMENT,
             '<!-- Normalized project-local AIWG context. Operator notes may live outside AIWG-managed blocks. -->',
             '',
-            'This file is the stable `.aiwg/AIWG.md` entry point for AIWG skills, rules, and generated provider context.',
+            `This file is the stable \`${normalizedAiwgMdPath}\` entry point for AIWG skills, rules, and generated provider context.`,
             '',
         ].join('\n');
     const signed = base.includes(AIWG_SIGNATURE_COMMENT)

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

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

package/dist/src/smiths/context-pipeline/parallelism-section.js

@@ -16,6 +16,27 @@
 import { readAiwgConfig, resolveParallelism, PROVIDER_PARALLELISM_DEFAULTS } from '../../config/aiwg-config.js';
 export const PARALLELISM_BLOCK_START = '<!-- AIWG-PARALLELISM-CAP:START -->';
 export const PARALLELISM_BLOCK_END = '<!-- AIWG-PARALLELISM-CAP:END -->';
+function delegationSupport(provider) {
+    switch (provider) {
+        case 'claude':
+        case 'codex':
+        case 'copilot':
+        case 'cursor':
+        case 'factory':
+        case 'opencode':
+        case 'openclaw':
+            return `**Provider behavior (${provider})**: native custom subagents can select the deployed model-worker wrapper. Verify the resolved model when provider or account policy may substitute it.`;
+        case 'openhuman':
+            return '**Provider behavior (openhuman)**: wrapper roles compile to OpenHuman agent definitions; exact pins validate while semantic hints may be routed dynamically.';
+        case 'warp':
+        case 'hermes':
+            return `**Provider behavior (${provider})**: delegation is available, but model selection is global/run-scoped. Use the wrapper rubric for task selection while reporting that heterogeneous per-worker pinning is not enforced.`;
+        case 'windsurf':
+            return '**Provider behavior (windsurf)**: portable subagent model selection is unsupported. Apply the decomposition rubric in the primary agent and do not claim wrapper pinning or parallel delegation.';
+        default:
+            return '**Provider behavior (unknown)**: delegation and per-worker model selection are unverified. Apply the rubric only where the active provider exposes those capabilities, and state any fallback explicitly.';
+    }
+}
 /**
  * Build the parallelism-cap markdown section for injection into context files.
  * Returns `''` when injection should be skipped:
@@ -61,7 +82,19 @@ export async function buildParallelismSection(projectPath) {
         lines.push(`*Rationale*: ${resolved.rationale}`);
     }
     lines.push('');
-    lines.push('When spawning parallel subagents, take the MIN of: this cap, `AIWG_CONTEXT_WINDOW` budget, the RLM 7-agent hard cap (RLM dispatches only), and the natural task decomposition. Bump via `aiwg config set --project parallelism.max_parallel_subagents N`.');
+    lines.push('### Model-selected delegation rubric');
+    lines.push('');
+    lines.push('For each non-trivial task, assess whether it contains independent, bounded subtasks that can run concurrently. When delegation is supported, prefer the deployed model-pinned wrappers by task characteristics and consequence:');
+    lines.push('');
+    lines.push('- `aiwg-model-efficiency-worker`: discovery, inventory, focused edits, and other bounded low-cost work.');
+    lines.push('- `aiwg-model-coding-worker`: implementation, tests, debugging, and routine technical delivery.');
+    lines.push('- `aiwg-model-reasoning-worker`: architecture, synthesis, difficult analysis, and high-consequence review.');
+    lines.push('');
+    lines.push('Do not delegate trivial work, tightly coupled changes, serial dependencies, or tasks likely to collide in shared state; also keep work local when coordination costs exceed the expected benefit. Parallelize only independent work, and take the MIN of provider limits, `max_parallel_subagents`, `AIWG_CONTEXT_WINDOW` budget, framework-specific caps (including the RLM 7-agent hard cap for RLM dispatches), and natural task decomposition. Bump the project cap via `aiwg config set --project parallelism.max_parallel_subagents N`.');
+    lines.push('');
+    lines.push('The primary agent retains orchestration, final integration, conflict resolution, validation, and user-facing accountability.');
+    lines.push('');
+    lines.push(delegationSupport(primary));
     lines.push('');
     lines.push(PARALLELISM_BLOCK_END);
     lines.push('');

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

@@ -384,7 +384,15 @@ export async function ensureWorkspaceContext(projectPath, options = {}) {
     }
     const block = buildWorkspaceManagedBlock(projectPath, options.providerFiles);
     if (existing.includes(WORKSPACE_MANAGED_START) || existing.includes(WORKSPACE_MANAGED_END)) {
-        const updated = replaceBlock(existing, WORKSPACE_MANAGED_START, WORKSPACE_MANAGED_END, block);
+        let updated = replaceBlock(existing, WORKSPACE_MANAGED_START, WORKSPACE_MANAGED_END, block);
+        // A managed project-extraction block explicitly points operators back to
+        // README/package metadata as its source. Refresh that block during normal
+        // regeneration so the documented edit-source-then-regenerate contract is
+        // true (#1866). Workspaces without an extraction remain opt-in.
+        if (updated.includes(PROJECT_EXTRACTION_START) || updated.includes(PROJECT_EXTRACTION_END)) {
+            const extracted = await extractExistingProjectContext(projectPath);
+            updated = replaceBlock(updated, PROJECT_EXTRACTION_START, PROJECT_EXTRACTION_END, extracted.content);
+        }
         if (updated === existing)
             return { path: workspacePath, action: 'unchanged', warnings };
         await atomicWrite(workspacePath, updated);
@@ -512,6 +520,7 @@ function sensitiveEvidence(content) {
 async function nestedInstructionFiles(projectPath) {
     const found = [];
     const ignored = new Set(['.git', 'node_modules', 'dist', 'build', 'coverage', '.aiwg']);
+    const artifactRoot = path.resolve(resolveProjectAiwgDir(projectPath));
     async function walk(directory) {
         let entries;
         try {
@@ -522,8 +531,11 @@ async function nestedInstructionFiles(projectPath) {
         }
         for (const entry of entries) {
             if (entry.isDirectory()) {
-                if (!ignored.has(entry.name) && !entry.name.startsWith('.context-migration-'))
-                    await walk(path.join(directory, entry.name));
+                const child = path.join(directory, entry.name);
+                if (!ignored.has(entry.name)
+                    && !entry.name.startsWith('.context-migration-')
+                    && path.resolve(child) !== artifactRoot)
+                    await walk(child);
             }
             else if (['AGENTS.md', 'CLAUDE.md', 'WARP.md'].includes(entry.name)) {
                 const relative = path.relative(projectPath, path.join(directory, entry.name)).replace(/\\/g, '/');

package/dist/src/smiths/mcpsmith/example.js

@@ -12,6 +12,7 @@ import { analyzeCLI } from './analyzers/cli-analyzer.js';
 import { generateServer, updateRegistry } from './generator.js';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 async function main() {
     console.log('MCPsmith Example: Generating Git MCP Server\n');
@@ -28,7 +29,8 @@ async function main() {
     console.log();
     // Step 2: Generate the MCP server
     console.log('Step 2: Generating MCP server...');
-    const outputDir = path.join(__dirname, '..', '..', '..', '.aiwg', 'smiths', 'mcpsmith', 'servers');
+    const projectRoot = path.resolve(__dirname, '..', '..', '..');
+    const outputDir = projectAiwgPath(projectRoot, 'smiths', 'mcpsmith', 'servers');
     const generatedServer = await generateServer({
         serverId: 'git',
         serverName: 'Git CLI MCP Server',

package/dist/src/smiths/mcpsmith/generator.js

@@ -10,6 +10,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import crypto from 'crypto';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 /**
  * Generate MCP server from analyzer result
@@ -174,7 +175,8 @@ function createManifest(serverId, serverName, analyzerResult, config) {
  */
 async function generateServerCode(serverId, serverName, analyzerResult) {
     // Load template
-    const templatePath = path.join(path.dirname(__dirname), '..', '..', '.aiwg', 'smiths', 'mcpsmith', 'templates', 'server-template.mjs');
+    const projectRoot = path.resolve(path.dirname(__dirname), '..', '..');
+    const templatePath = projectAiwgPath(projectRoot, 'smiths', 'mcpsmith', 'templates', 'server-template.mjs');
     let template = await fs.readFile(templatePath, 'utf-8');
     // Replace template variables
     const now = new Date().toISOString();

package/dist/src/smiths/toolsmith/runtime-discovery.mjs

@@ -13,6 +13,7 @@ import { existsSync, constants } from 'fs';
 import { resolve, join, dirname } from 'path';
 import { platform, arch, homedir, tmpdir, cpus, totalmem, freemem } from 'os';
 import { fileURLToPath } from 'url';
+import { projectAiwgPath } from '../../config/project-artifacts-runtime.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -22,7 +23,7 @@ const __dirname = dirname(__filename);
  */
 export class RuntimeDiscovery {
   constructor(basePath = null) {
-    this.basePath = basePath || resolve(process.cwd(), '.aiwg/smiths/toolsmith');
+    this.basePath = basePath || projectAiwgPath(process.cwd(), 'smiths', 'toolsmith');
     this.knownTools = this.#loadKnownTools();
   }
 

package/dist/src/storage/cli.js

@@ -18,6 +18,7 @@ import { existsSync } from 'fs';
 import { mkdir, readFile, writeFile, appendFile } from 'fs/promises';
 import { dirname, join, resolve as resolvePath } from 'path';
 import { BACKEND_TYPES, FilesystemAdapter, ObsidianAdapter, LogseqAdapter, FortemiAdapter, SUBSYSTEM_KEYS, getLoadedConfig, initStorage, resolveStorage, resolveSubsystemRoot, storageConfigPath, } from './index.js';
+import { projectAiwgPath, resolveProjectAiwgDir } from '../config/project-artifacts.js';
 export async function main(args) {
     const subcommand = args[0];
     const subArgs = args.slice(1);
@@ -47,7 +48,7 @@ async function handleShow(projectRoot) {
     const config = await getLoadedConfig(projectRoot);
     const cfgPath = storageConfigPath(projectRoot);
     if (!config) {
-        console.log(`No storage.config — every subsystem uses the default fs backend under .aiwg/.\n`);
+        console.log(`No storage.config — every subsystem uses the default fs backend under ${resolveProjectAiwgDir(projectRoot)}.\n`);
         console.log(`Expected location (when configured): ${cfgPath}\n`);
     }
     else {
@@ -178,7 +179,7 @@ async function handleMigrate(projectRoot, args) {
         return;
     }
     // Resume support: read the per-migration log; skip already-done paths
-    const migrationLogPath = resolvePath(projectRoot, '.aiwg', '.storage-cache', 'migrations', `${opts.subsystem}-${specSlug(opts.from)}-to-${specSlug(opts.to)}.jsonl`);
+    const migrationLogPath = projectAiwgPath(projectRoot, '.storage-cache', 'migrations', `${opts.subsystem}-${specSlug(opts.from)}-to-${specSlug(opts.to)}.jsonl`);
     const completed = await readCompletedSet(migrationLogPath);
     let copied = 0;
     let skipped = 0;

package/dist/src/storage/subsystem-cli.js

@@ -20,6 +20,7 @@
  */
 import { getLoadedConfig, resolveStorage } from './index.js';
 import { resolveSubsystemRootRuntime } from './config.js';
+import { projectAiwgPath, resolveProjectAiwgDir } from '../config/project-artifacts.js';
 export async function runSubsystemCli(subsystem, args, opts = {}) {
     const subcommand = args[0];
     const subArgs = args.slice(1);
@@ -177,6 +178,9 @@ async function readStdin() {
     return Buffer.concat(chunks).toString('utf-8');
 }
 function printUsage(subsystem, display) {
+    const projectRoot = process.cwd();
+    const subsystemPath = projectAiwgPath(projectRoot, subsystem);
+    const configPath = projectAiwgPath(projectRoot, 'storage.config');
     console.log(`Usage: aiwg ${display} <subcommand>
 
 Subcommands:
@@ -195,7 +199,8 @@ Examples:
   echo "# page" | aiwg ${display} put some/page.md
   echo '{"event":"x"}' | aiwg ${display} append-log some/log.jsonl
 
-The ${display} subsystem persists at .aiwg/${subsystem}/ on the default fs backend.
-Configure .aiwg/storage.config to redirect (#934).`);
+The ${display} subsystem persists at ${subsystemPath} on the default fs backend
+(artifact root: ${resolveProjectAiwgDir(projectRoot)}).
+Configure ${configPath} to redirect (#934).`);
 }
 //# sourceMappingURL=subsystem-cli.js.map

package/dist/src/update/notifier.mjs

@@ -218,7 +218,7 @@ export function maybePrintNotice() {
   const cache = readCache();
   if (!cache?.hasUpdate || !cache.current || !cache.latest) return;
   // One-line, non-intrusive. Users who want to update run `aiwg update`.
-  const msg = `aiwg: update available ${cache.current} → ${cache.latest} (run: npm install -g aiwg)`;
+  const msg = `aiwg: update available ${cache.current} → ${cache.latest} (run: aiwg update)`;
   process.stderr.write(`\n${msg}\n`);
 }
 

package/dist/src/update/service.mjs

@@ -0,0 +1,123 @@
+/**
+ * Install-aware AIWG update service.
+ *
+ * This is the single package-update primitive shared by `aiwg update` and
+ * `aiwg refresh`. It deliberately keeps provider/framework redeployment in
+ * the calling handlers.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { getPackageRoot, loadConfig } from '../channel/manager.mjs';
+
+const VALID_MODES = new Set(['npm', 'web', 'source']);
+
+function readPackageName(packageRoot) {
+  try {
+    return JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).name;
+  } catch {
+    return null;
+  }
+}
+
+export async function detectInstallMode(options = {}) {
+  const packageRoot = options.packageRoot ?? getPackageRoot();
+  const override = options.env?.AIWG_INSTALL_MODE ?? process.env.AIWG_INSTALL_MODE;
+  if (override) {
+    if (!VALID_MODES.has(override)) {
+      throw new Error(`AIWG_INSTALL_MODE must be one of: ${[...VALID_MODES].join(', ')}`);
+    }
+    return { mode: override, packageRoot, packageName: readPackageName(packageRoot) };
+  }
+
+  const config = options.config ?? await loadConfig();
+  const packageName = readPackageName(packageRoot);
+  if (packageName === '@aiwg/cli') return { mode: 'web', packageRoot, packageName };
+  if (config.devMode || config.channel === 'edge' || existsSync(path.join(packageRoot, '.git'))) {
+    return { mode: 'source', packageRoot, packageName };
+  }
+  return { mode: 'npm', packageRoot, packageName };
+}
+
+function npmTag(channel) {
+  if (channel === 'next') return 'next';
+  if (channel === 'nightly') return 'nightly';
+  return 'latest';
+}
+
+/**
+ * Update the active distribution.
+ *
+ * `web` means the lightweight CLI's signed resource distribution. Its
+ * resources resolve the selected signed channel on demand; it must not replace
+ * itself with the full global npm package. `source` is intentionally manual.
+ */
+export async function updateInstallation(options = {}) {
+  const config = options.config ?? await loadConfig();
+  const detected = await detectInstallMode({ ...options, config });
+  const channel = options.channel ?? config.channel ?? 'stable';
+  const dryRun = options.dryRun === true;
+  const offline = options.offline === true;
+
+  if (detected.mode === 'web') {
+    if (offline) {
+      return {
+        ...detected,
+        channel,
+        status: 'unsupported-offline',
+        changed: false,
+        message: 'Web-backed AIWG cannot refresh signed resources while offline; verified cached resources remain available.',
+      };
+    }
+    if (dryRun) {
+      return {
+        ...detected,
+        channel,
+        status: 'dry-run',
+        changed: false,
+        message: `Would refresh the verified signed '${channel}' web resource release; no global package install would be attempted.`,
+      };
+    }
+    const refreshWebResources = options.refreshWebResources ?? (async (selector) => {
+      const { resolveWebRelease } = await import('../resources/web-release.js');
+      return resolveWebRelease({ selector });
+    });
+    const release = await refreshWebResources(channel);
+    return {
+      ...detected,
+      channel,
+      version: release.version,
+      status: 'updated',
+      changed: true,
+      message: `Refreshed the verified signed '${channel}' web resource release${release.version ? ` (${release.version})` : ''}; no global package install was attempted.`,
+    };
+  }
+
+  if (detected.mode === 'source') {
+    return {
+      ...detected,
+      channel,
+      status: 'manual',
+      changed: false,
+      message: `Source checkout detected at ${detected.packageRoot}. Update it with 'git pull --ff-only', then run 'npm ci && npm run build'; AIWG will not overwrite it with npm.`,
+    };
+  }
+
+  const tag = npmTag(channel);
+  const command = ['install', '--global', `aiwg@${tag}`];
+  if (!dryRun) {
+    const execute = options.execute ?? ((file, args) => execFileSync(file, args, { stdio: 'inherit' }));
+    execute('npm', command);
+  }
+  return {
+    ...detected,
+    channel,
+    status: dryRun ? 'dry-run' : 'updated',
+    changed: !dryRun,
+    command: `npm ${command.join(' ')}`,
+    message: dryRun
+      ? `Would update the full AIWG npm distribution on the '${tag}' channel.`
+      : `Updated the full AIWG npm distribution on the '${tag}' channel.`,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.7.18",
+  "version": "2026.7.20",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",
@@ -56,7 +56,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@fortemi/core": "2026.7.11",
+    "@fortemi/core": "2026.7.13",
     "@modelcontextprotocol/sdk": "^1.24.0",
     "chalk": "^4.1.2",
     "chokidar": "^3.6.0",
@@ -66,6 +66,7 @@
     "js-yaml": "^4.1.0",
     "listr2": "^8.2.5",
     "ora": "^5.4.1",
+    "semver": "^7.8.5",
     "yaml": "^2.8.1",
     "zod": "^3.25.0"
   },