@aiwg/cli 2026.8.8 → 2026.8.11

package/dist/src/issues/cli.js

@@ -8,6 +8,10 @@
  * @issue #1462
  */
 import { readFile, writeFile } from 'fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { getFrameworkRoot } from '../channel/manager.mjs';
+import { readAiwgConfig } from '../config/aiwg-config.js';
 import { LocalIssueProviderCore, buildExternalIssueSnapshotFromLocal, buildLocalIssueConflictReport, createLiveIssueClient, localIssueRoot, parseCommentIdMappings, parseExternalIssueSnapshot, } from './index.js';
 export async function main(args, cwd = process.cwd()) {
     const parsed = parseArgs(args);
@@ -27,7 +31,11 @@ export async function main(args, cwd = process.cwd()) {
             return;
         case 'new':
         case 'create':
-            await handleNew(issues, parsed);
+            await handleNew(issues, parsed, cwd);
+            return;
+        case 'plan':
+        case 'draft-plan':
+            await handlePlan(parsed, cwd);
             return;
         case 'list':
         case 'ls':
@@ -68,12 +76,19 @@ async function handleInit(issues, args) {
     });
     printJsonOrText(args, config, `Initialized local issues with prefix ${config.issue_key.prefix}`);
 }
-async function handleNew(issues, args) {
+async function loadIssueComposer() {
+    const frameworkRoot = await getFrameworkRoot();
+    const modulePath = path.join(frameworkRoot, 'tools', 'issues', 'policy-boundary-composer.mjs');
+    return import(pathToFileURL(modulePath).href);
+}
+async function buildIssuePlan(args, cwd) {
     const title = stringFlag(args, 'title') ?? args.positional[1];
     if (!title)
-        throw new Error('Usage: aiwg issue new --title <title> [--body <text>|--body-file <path>]');
+        throw new Error('Usage: aiwg issue plan --title <title> [--body <text>|--body-file <path>]');
     const body = await readBody(args);
-    const issue = await issues.createIssue({
+    const config = await readAiwgConfig(cwd);
+    const composer = await loadIssueComposer();
+    return composer.planIssueDraft({
         title,
         body,
         type: stringFlag(args, 'type'),
@@ -81,8 +96,76 @@ async function handleNew(issues, args) {
         labels: csvFlag(args, 'label'),
         assignees: csvFlag(args, 'assignee'),
         author: stringFlag(args, 'author'),
-    });
-    printJsonOrText(args, issue, `Created ${issue.fields.id}: ${issue.fields.title}`);
+    }, { threatAssessment: config?.security?.threatAssessment });
+}
+async function handlePlan(args, cwd) {
+    const plan = await buildIssuePlan(args, cwd);
+    console.log(JSON.stringify(plan, null, 2));
+}
+async function handleNew(issues, args, cwd) {
+    const plan = await buildIssuePlan(args, cwd);
+    if (plan.disposition === 'blocked') {
+        throw new Error(`Issue draft rejected by ${plan.blockingRule}; no issue was written. Run aiwg issue plan to inspect suggested segments.`);
+    }
+    const authorizationDigest = stringFlag(args, 'authorize-policy');
+    if (plan.authorizationRequired && authorizationDigest !== plan.digest) {
+        throw new Error(`Issue draft requires explicit policy authorization. Review 'aiwg issue plan', then pass --authorize-policy ${plan.digest}. No issue was written.`);
+    }
+    const composer = await loadIssueComposer();
+    const records = new Map();
+    const adapter = {
+        async findByMarker(marker) {
+            const listed = await issues.listIssues({ limit: 10_000 });
+            for (const entry of listed.issues) {
+                const record = await issues.getIssue(entry.id, { body: true, comments: 0 });
+                if (record.body.includes(marker)) {
+                    records.set(record.fields.id, record);
+                    return { id: record.fields.id, reference: record.fields.id, body: record.body };
+                }
+            }
+            return null;
+        },
+        async create(draft) {
+            const record = await issues.createIssue({
+                title: draft.title,
+                body: draft.body,
+                type: stringFlag(args, 'type'),
+                priority: stringFlag(args, 'priority'),
+                labels: draft.labels,
+                assignees: draft.assignees,
+                author: stringFlag(args, 'author'),
+            });
+            records.set(record.fields.id, record);
+            return { id: record.fields.id, reference: record.fields.id, body: record.body };
+        },
+        async update(issue, patch) {
+            const record = records.get(issue.id) ?? await issues.getIssue(issue.id, { body: true, comments: 0 });
+            const references = [...patch.body.matchAll(/(?:Depends on|Related):\s+([A-Z][A-Z0-9_-]*-\d+)/g)]
+                .map((match) => match[1])
+                .filter((reference) => reference !== issue.id);
+            await issues.updateIssueFields(issue.id, {
+                links: {
+                    ...record.fields.links,
+                    related: [...new Set([...record.fields.links.related, ...references])],
+                    parent: patch.body.match(/Depends on:\s+([A-Z][A-Z0-9_-]*-\d+)/)?.[1] ?? record.fields.links.parent,
+                },
+            });
+            await issues.commentIssue(issue.id, patch.body.slice(patch.body.indexOf('## Related')), {
+                author: stringFlag(args, 'author') ?? 'aiwg',
+            });
+        },
+    };
+    const result = await composer.executeIssuePlan(plan, adapter, { authorizationDigest });
+    if (result.status !== 'created') {
+        throw new Error(`Issue creation ${result.status}: ${result.error ?? 'review the recovery envelope'}\n${JSON.stringify(result.recovery ?? result, null, 2)}`);
+    }
+    if (args.flags.has('json') || result.created.length > 1) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        const issue = result.created[0];
+        console.log(`Created ${issue.reference}: ${plan.segments[0].title}`);
+    }
 }
 async function handleList(issues, args) {
     const limit = stringFlag(args, 'limit');
@@ -313,7 +396,8 @@ function csvFlag(args, name) {
 function printUsage() {
     console.log(`Usage:
   aiwg issue init [--prefix KEY] [--padding N]
-  aiwg issue new --title "..." [--body "..."] [--body-file path]
+  aiwg issue plan --title "..." [--body "..."] [--body-file path] [--json]
+  aiwg issue new --title "..." [--body "..."] [--body-file path] [--authorize-policy DIGEST]
   aiwg issue list [--status open] [--label bug] [--search text] [--limit 20] [--json]
   aiwg issue show <KEY> [--comments last:10|all]
   aiwg issue import --from gitea|github --snapshot-file path [--json]

package/dist/src/mcp/server.mjs

@@ -7,7 +7,7 @@
  * @see https://modelcontextprotocol.io/specification/2025-11-25
  * @architecture @.aiwg/architecture/software-architecture-doc.md - Section 2.1 CLI Layer
  * @reference @docs/references/REF-066-mcp-specification-2025.md
- * @cli @docs/CLI_USAGE.md - mcp serve command
+ * @cli @docs/cli/agent-usage.md - mcp serve command
  * @frameworks @agentic/code/frameworks/sdlc-complete/
  * @frameworks @agentic/code/frameworks/media-marketing-kit/
  */

package/dist/src/ops/registry.js

@@ -13,7 +13,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { execSync } from 'child_process';
 import { resolveConfigDir } from '../config/user-config.js';
 import { resolveWorkspace } from '../config/workspace.js';
-import { projectAiwgPath } from '../config/project-artifacts.js';
+import { projectControlPath } from '../config/project-artifacts.js';
 /**
  * Extension type abbreviations
  */
@@ -455,7 +455,7 @@ export class OpsRegistry {
             throw new Error(`Workspace "${name}" not found`);
         }
         let canonical = null;
-        const canonicalConfigPath = projectAiwgPath(workspace.home, 'aiwg.config');
+        const canonicalConfigPath = projectControlPath(workspace.home, 'aiwg.config');
         let canonicalDeclared = false;
         if (existsSync(canonicalConfigPath)) {
             try {

package/dist/src/policy/authorization.js

@@ -9,7 +9,7 @@
 import { access, copyFile, mkdir, readFile, rename } from 'node:fs/promises';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { load as loadYaml } from 'js-yaml';
-import { projectAiwgPath } from '../config/project-artifacts.js';
+import { projectAiwgPath, projectControlPath } from '../config/project-artifacts.js';
 /**
  * Export provider mappings without inventing provider grants. Stable IDs,
  * principals, scopes, resources, actions, and conditions survive unchanged;
@@ -375,7 +375,7 @@ export async function archiveLegacyPermissionManifests(projectDir) {
     return archived;
 }
 export async function backupConfig(projectDir) {
-    const source = projectAiwgPath(projectDir, 'aiwg.config');
+    const source = projectControlPath(projectDir, 'aiwg.config');
     const backupDir = projectAiwgPath(projectDir, 'backups');
     await mkdir(backupDir, { recursive: true });
     const content = await readFile(source);

package/dist/src/providers/capability-matrix.yaml

@@ -323,9 +323,9 @@ providers:
     aggregated_output: true
 
   windsurf:
-    display_name: Windsurf
-    status: experimental
-    # Windsurf is an IDE extension requiring VS Code host — daemon not supported
+    display_name: Devin Desktop
+    status: stable
+    # Devin Desktop uses the Windsurf compatibility surface and requires a VS Code host — daemon not supported
     daemon_tier: unsupported
     daemon_pty_adapter: false
     artifact_paths:

package/dist/src/providers/provider-definitions.js

@@ -704,11 +704,13 @@ const BUILT_IN_SEEDS = [
     },
     {
         id: 'windsurf',
-        aliases: ['devin-desktop', 'devin-local', 'cascade'],
+        displayName: 'Devin Desktop',
+        status: 'stable',
+        aliases: ['devin', 'devin-desktop', 'devin-local', 'cascade'],
         builtIn: true,
         surfaces: {
-            primary: 'windsurf',
-            compatibility: ['devin-desktop', 'devin-local', 'cascade'],
+            primary: 'devin',
+            compatibility: ['devin-desktop', 'windsurf', 'devin-local', 'cascade'],
             precedence: ['.devin/rules/', '.windsurf/rules/', 'AGENTS.md', '.windsurfrules'],
             related: [
                 {
@@ -716,7 +718,7 @@ const BUILT_IN_SEEDS = [
                     displayName: 'Devin Desktop',
                     relationship: 'same-provider',
                     deployable: true,
-                    aliases: ['windsurf', 'cascade'],
+                    aliases: ['devin', 'windsurf', 'cascade'],
                     paths: {
                         rules: ['.devin/rules/*.md', '.windsurf/rules/*.md'],
                         skills: [],
@@ -724,7 +726,7 @@ const BUILT_IN_SEEDS = [
                         legacy: ['.windsurfrules'],
                     },
                     notes: [
-                        'Devin Desktop is the renamed Windsurf local IDE surface; --provider windsurf remains the deployable compatibility id.',
+                        'Devin Desktop is the current product name; --provider devin is preferred and --provider windsurf remains a deprecated compatibility id.',
                         '.devin/rules is preferred by Devin Desktop, but AIWG keeps .devin/ as ignored local provider output and currently emits the compatibility surface through .windsurf/ plus AGENTS.md.',
                     ],
                 },

package/dist/src/providers/provider-definitions.mjs

@@ -70,7 +70,7 @@ const MCP_INJECTION_DEFINITIONS = [
   },
   {
     id: 'windsurf',
-    aliases: ['devin-desktop'],
+    aliases: ['devin', 'devin-desktop', 'devin-local', 'cascade'],
     mcp: {
       providerId: 'windsurf',
       includeInSupportedProviders: true,

package/dist/src/serve/pty-bridge.js

@@ -288,16 +288,10 @@ async function spawnSandboxWsPty(session, agentId, wsEndpoint, opts) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     let wsMod;
     try {
-        wsMod = await (new Function('m', 'return import(m)'))('ws');
+        wsMod = await loadFeaturePackage('ws');
     }
     catch {
-        try {
-            // @ts-expect-error Optional runtime dependency; this workspace does not ship @types/ws.
-            wsMod = await import('ws');
-        }
-        catch {
-            throw new Error('ws package required for sandbox PTY bridge. Run: npm install ws');
-        }
+        throw new Error('WebSocket support is required for the sandbox PTY bridge; run `aiwg features install webserver`');
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const WS = wsMod.WebSocket ?? wsMod.default?.WebSocket ?? wsMod.default;

package/dist/src/serve/screen-reader.js

@@ -10,15 +10,12 @@
  * @see src/serve/pty-bridge.ts — PTY WebSocket bridge
  */
 import { EventEmitter } from 'events';
-import { createRequire } from 'module';
-// @xterm/headless is an optional dependency. Load it once at module level
-// using createRequire so we can import the CJS bundle from ESM.
-const _require = createRequire(import.meta.url);
+import { requireFeaturePackage } from '../features/runtime.js';
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 let XtermTerminal;
 try {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const xterm = _require('@xterm/headless');
+    const xterm = requireFeaturePackage('@xterm/headless');
     XtermTerminal = xterm.Terminal;
 }
 catch {
@@ -48,7 +45,7 @@ export class ScreenReader {
     disposed = false;
     constructor(opts) {
         if (!XtermTerminal) {
-            throw new Error('@xterm/headless is required for ScreenReader. Install it: npm install @xterm/headless');
+            throw new Error('Terminal screen parsing is unavailable; run `aiwg features install terminal`');
         }
         this._rows = opts?.rows ?? 24;
         this._cols = opts?.cols ?? 80;

package/dist/src/smiths/context-pipeline/aiwg-md.js

@@ -16,7 +16,7 @@
  */
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
-import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { projectControlPath } from '../../config/project-artifacts.js';
 import { buildParallelismSection, replaceOrAppendParallelismBlock } from './parallelism-section.js';
 import { buildContextFinalizationBlock, replaceOrAppendFinalizationBlock } from './finalization.js';
 import { buildExternalLinksSection, replaceOrAppendExternalLinksBlock, } from './external-links-section.js';
@@ -79,7 +79,7 @@ export async function buildAiwgMdContent(projectPath, stagedClaudeMdContent) {
         return replaceOrAppendExternalLinksBlock(withFinalization, externalLinksSection);
     }
     // Fallback stub.
-    const normalizedPath = projectAiwgPath(projectPath, 'AIWG.md');
+    const normalizedPath = projectControlPath(projectPath, 'AIWG.md');
     const normalizedRelative = path.relative(projectPath, normalizedPath).replace(/\\/g, '/');
     const normalizedLink = normalizedRelative.startsWith('.') ? normalizedRelative : `./${normalizedRelative}`;
     const stub = [

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

@@ -10,7 +10,7 @@ import * as path from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { readAiwgConfig } from '../../config/aiwg-config.js';
-import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from '../../config/project-artifacts.js';
 import { renderTrackerProtocol, resolveTrackerAuthority } from '../../tracker/capability-protocol.js';
 import { buildExternalLinksSection, replaceOrAppendExternalLinksBlock, } from './external-links-section.js';
 export const FINALIZATION_START = '<!-- aiwg-context-finalization:START -->';
@@ -61,7 +61,7 @@ export async function buildContextFinalizationBlock(projectPath) {
     const installed = Object.entries(config?.installed ?? {});
     const installedNames = installed.map(([name]) => name);
     const providerDeployments = new Set();
-    const normalizedAiwgMdPath = displayProjectPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
+    const normalizedAiwgMdPath = displayProjectPath(projectPath, projectControlPath(projectPath, 'AIWG.md'));
     const normalizedAiwgMdLabel = `\`${normalizedAiwgMdPath}\``;
     for (const [, entry] of installed) {
         for (const provider of Object.keys(entry.deployedTo ?? {})) {
@@ -114,7 +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 normalizedAiwgMdPath = displayProjectPath(projectPath, projectControlPath(projectPath, 'AIWG.md'));
     const base = existing.trim().length > 0
         ? existing
         : [
@@ -132,7 +132,7 @@ export async function buildNormalizedAiwgMd(projectPath, existing = '') {
     return replaceOrAppendExternalLinksBlock(withFinalization, externalLinksSection);
 }
 export async function writeNormalizedAiwgMd(projectPath) {
-    const targetPath = projectAiwgPath(projectPath, 'AIWG.md');
+    const targetPath = projectControlPath(projectPath, 'AIWG.md');
     let existing = '';
     try {
         existing = await fs.readFile(targetPath, 'utf8');
@@ -143,7 +143,20 @@ export async function writeNormalizedAiwgMd(projectPath) {
     }
     const content = await buildNormalizedAiwgMd(projectPath, existing);
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
-    await fs.writeFile(targetPath, content.endsWith('\n') ? content : `${content}\n`, 'utf8');
+    const normalizedContent = content.endsWith('\n') ? content : `${content}\n`;
+    await fs.writeFile(targetPath, normalizedContent, 'utf8');
+    const artifactRoot = resolveProjectAiwgDir(projectPath);
+    const artifactPath = projectAiwgPath(projectPath, 'AIWG.md');
+    if (artifactPath !== targetPath) {
+        try {
+            await fs.access(artifactRoot);
+            await fs.writeFile(artifactPath, normalizedContent, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
     return targetPath;
 }
 //# sourceMappingURL=finalization.js.map

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

@@ -21,7 +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';
+import { projectControlPath } from '../../config/project-artifacts.js';
 const SECTION_TITLES = {
     agents: 'Agents',
     rules: 'Rules',
@@ -137,7 +137,7 @@ 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).');
-    const configRelative = path.relative(opts.projectPath, projectAiwgPath(opts.projectPath, 'aiwg.config')).replace(/\\/g, '/');
+    const configRelative = path.relative(opts.projectPath, projectControlPath(opts.projectPath, 'aiwg.config')).replace(/\\/g, '/');
     const configLink = configRelative.startsWith('.') ? configRelative : `./${configRelative}`;
     parts.push(`Tracker and delivery source of truth: [${configRelative}](${configLink}).`);
     parts.push('');

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

@@ -12,7 +12,8 @@ import * as path from 'node:path';
 import { buildAiwgMdContent } from './aiwg-md.js';
 import { buildNormalizedAiwgMd } from './finalization.js';
 import { getProviderDefinition, listProviderDefinitions, } from '../../providers/provider-definitions.js';
-import { projectAiwgPath, resolveProjectAiwgDir } from '../../config/project-artifacts.js';
+import { readAiwgConfig } from '../../config/aiwg-config.js';
+import { projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from '../../config/project-artifacts.js';
 export const WORKSPACE_MANAGED_START = '<!-- AIWG:workspace-context:start -->';
 export const WORKSPACE_MANAGED_END = '<!-- AIWG:workspace-context:end -->';
 export const WORKSPACE_OPERATOR_START = '<!-- AIWG:workspace-operator:start -->';
@@ -306,8 +307,8 @@ function providerForPath(relativePath) {
     }
     return null;
 }
-function projectArtifactMarkdownPath(projectPath, ...segments) {
-    const rel = path.relative(projectPath, projectAiwgPath(projectPath, ...segments)).replace(/\\/g, '/');
+function projectControlMarkdownPath(projectPath, ...segments) {
+    const rel = path.relative(projectPath, projectControlPath(projectPath, ...segments)).replace(/\\/g, '/');
     if (rel === '')
         return '.';
     return rel.startsWith('.') ? rel : `./${rel}`;
@@ -315,14 +316,15 @@ function projectArtifactMarkdownPath(projectPath, ...segments) {
 function workspaceLinks(projectPath, providerFiles = []) {
     const links = new Set([
         '[AIWG framework context](./AIWG.md)',
-        `[AIWG project configuration](${projectArtifactMarkdownPath(projectPath, 'aiwg.config')})`,
+        `[AIWG project configuration](${projectControlMarkdownPath(projectPath, 'aiwg.config')})`,
     ]);
     if (providerFiles.length > 0) {
         for (const file of providerFiles)
             links.add(`[Provider-specific context](./${file.replace(/\\/g, '/')})`);
     }
-    // The quickref source is linked, not copied into each provider directory.
-    links.add(`[Project-local quickref](${projectArtifactMarkdownPath(projectPath, 'quickref.json')}) (when configured)`);
+    // Keep the logical project path portable in committed context. Runtime
+    // quickref readers follow `.aiwg-location` to the external corpus.
+    links.add('[Project-local quickref](.aiwg/quickref.json) (when configured)');
     return [...links];
 }
 export function buildWorkspaceManagedBlock(projectPath, providerFiles = []) {
@@ -692,16 +694,13 @@ function providerMigrationContent(source) {
     ].join('\n');
 }
 async function configuredProviders(projectPath) {
-    const config = await readOptional(projectAiwgPath(projectPath, 'aiwg.config'));
-    if (config) {
-        try {
-            const parsed = JSON.parse(config);
-            if (Array.isArray(parsed.providers))
-                return parsed.providers.filter((provider) => typeof provider === 'string');
-        }
-        catch {
-            // Audit/migration reports malformed provider config through the normal CLI path.
-        }
+    try {
+        const config = await readAiwgConfig(projectPath);
+        if (config)
+            return config.providers.filter((provider) => typeof provider === 'string');
+    }
+    catch {
+        // Audit/migration reports malformed provider config through the normal CLI path.
     }
     return ['claude'];
 }
@@ -783,7 +782,7 @@ async function stageMigrationWrites(projectPath, audit, options = {}) {
         writes.set(configPath, `${JSON.stringify(config, null, 2)}\n`);
     }
     if (options.includeGeneratedContext) {
-        const normalizedPath = projectOutputPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
+        const normalizedPath = projectOutputPath(projectPath, projectControlPath(projectPath, 'AIWG.md'));
         const existingNormalized = await readOptional(path.join(projectPath, normalizedPath)) ?? '';
         writes.set(normalizedPath, await buildNormalizedAiwgMd(projectPath, existingNormalized));
         const stagedClaude = writes.has('CLAUDE.md')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.8",
+  "version": "2026.8.11",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,7 @@
   },
   "files": [
     "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
     "bin/",
     "agentic/code/providers/",
     "dist/src/",

package/tools/agents/deploy-agents.mjs

@@ -20,7 +20,7 @@
  *   --rules-only             Deploy only rules (skip agents)
  *   --dry-run                Show what would be deployed without writing
  *   --force                  Overwrite existing files
- *   --provider <name>        Target provider: claude (default), openai, codex, cursor, opencode, copilot, factory, warp, windsurf, hermes, or openclaw
+ *   --provider <name>        Target provider: claude (default), openai, codex, cursor, opencode, copilot, factory, warp, devin, hermes, or openclaw
  *   --model <name>            Override model for all tiers (blanket)
  *   --reasoning-model <name> Override model for reasoning tasks
  *   --coding-model <name>    Override model for coding tasks
@@ -49,7 +49,8 @@
  *   copilot   - GitHub Copilot - .github/agents/, .github/commands/, .github/skills/, .github/copilot-rules/
  *   cursor    - Cursor IDE - .cursor/agents/, .cursor/commands/, .cursor/skills/, .cursor/rules/
  *   warp      - Warp Terminal - .warp/agents/, .warp/commands/, .warp/skills/, .warp/rules/ + WARP.md
- *   windsurf  - Windsurf - .windsurf/agents/, .windsurf/workflows/, .windsurf/skills/, .windsurf/rules/
+ *   devin     - Devin Desktop - .windsurf/agents/, .windsurf/workflows/, .windsurf/skills/, .windsurf/rules/
+ *   windsurf  - Deprecated alias for devin
  *   openclaw  - OpenClaw - ~/.openclaw/agents/, ~/.openclaw/commands/, ~/.openclaw/skills/, ~/.openclaw/rules/, ~/.openclaw/behaviors/
  *
  * Defaults:
@@ -103,6 +104,7 @@ function getDeployVersion(srcRoot) {
 
 const PROVIDER_ALIASES = {
   'openai': 'codex',
+  'devin': 'windsurf',
   'devin-desktop': 'windsurf',
   'devin-local': 'windsurf',
   'cascade': 'windsurf',
@@ -111,15 +113,9 @@ const PROVIDER_ALIASES = {
 const AVAILABLE_PROVIDERS = ['claude', 'factory', 'codex', 'opencode', 'copilot', 'cursor', 'warp', 'windsurf', 'hermes', 'openclaw', 'openhuman'];
 
 const UNSUPPORTED_PROVIDER_HINTS = {
-  devin: [
-    'Devin Desktop is supported through the Windsurf compatibility adapter:',
-    '  aiwg use sdlc --provider windsurf',
-    '  aiwg use sdlc --provider devin-desktop',
-    'Devin CLI has distinct rules/skills surfaces and is recorded as future-provider metadata; AIWG does not emit .devin/ provider output yet.',
-  ],
   'devin-cli': [
     'Devin CLI has distinct rules/skills surfaces and is not a deployable AIWG provider yet.',
-    'Use --provider windsurf or --provider devin-desktop for Devin Desktop/Windsurf local IDE deployments.',
+    'Use --provider devin for Devin Desktop deployments.',
   ],
 };
 
@@ -531,7 +527,7 @@ Providers (all deploy agents, commands, skills, and rules):
               Paths: .cursor/agents/, .cursor/commands/, .cursor/skills/, .cursor/rules/
   warp      - Warp Terminal
               Paths: .warp/agents/, .warp/commands/, .warp/skills/, .warp/rules/ + WARP.md
-  windsurf  - Windsurf
+  devin     - Devin Desktop (preferred; aliases: devin-desktop, windsurf)
               Paths: .windsurf/agents/, .windsurf/workflows/, .windsurf/skills/, .windsurf/rules/
   hermes    - Hermes Agent (MCP-based integration)
               Skills: ~/.hermes/skills/ (user-global) | Agents: AGENTS.md (lean routing guide)
@@ -865,7 +861,10 @@ export async function main() {
     srcRoot,
     target: cfg.target,
     mode: cfg.mode,
-    provider: cfg.provider,
+    // Provider aliases are selectors, not artifact identities. Passing the
+    // canonical id keeps generated frontmatter byte-identical for devin,
+    // devin-desktop, and the deprecated windsurf selector.
+    provider: resolveProvider(cfg.provider),
     dryRun: cfg.dryRun,
     force: cfg.force,
     reasoningModel: cfg.reasoningModel,