@aiwg/cli 2026.8.12 → 2026.8.14

package/dist/src/artifacts/output-policy.js

@@ -0,0 +1,87 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export function defaultArtifactOutputs() {
+    return { canonical: 'aiwg', provider_native: 'explicit-only', destinations: {} };
+}
+export function validateArtifactOutputs(value) {
+    if (value === undefined)
+        return [];
+    const errors = [];
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return ['artifact_outputs must be an object'];
+    if (value.canonical !== undefined && value.canonical !== 'aiwg')
+        errors.push("artifact_outputs.canonical must be 'aiwg'");
+    if (value.provider_native !== undefined && !['disabled', 'explicit-only', 'project-default'].includes(value.provider_native))
+        errors.push('artifact_outputs.provider_native must be disabled, explicit-only, or project-default');
+    for (const [id, destination] of Object.entries(value.destinations ?? {})) {
+        if (!/^[a-z0-9][a-z0-9.-]*$/.test(id))
+            errors.push(`artifact_outputs destination '${id}' has an invalid stable ID`);
+        if (!destination || typeof destination !== 'object' || Array.isArray(destination)) {
+            errors.push(`artifact_outputs.destinations.${id} must be an object`);
+            continue;
+        }
+        if (destination.enabled !== undefined && typeof destination.enabled !== 'boolean')
+            errors.push(`artifact_outputs.destinations.${id}.enabled must be boolean`);
+        if (destination.use_when !== undefined && !['disabled', 'user-requested', 'project-default'].includes(destination.use_when))
+            errors.push(`artifact_outputs.destinations.${id}.use_when is invalid`);
+    }
+    return errors;
+}
+export function resolveArtifactOutputs(options) {
+    const project = { ...defaultArtifactOutputs(), ...(options.project ?? {}) };
+    const supported = new Set(options.supportedDestinations ?? []);
+    const presentations = [];
+    const authority = {};
+    const diagnostics = [];
+    const explicit = new Set(options.explicitDestinations ?? []);
+    const candidateAuthority = new Map();
+    for (const id of options.providerDefaults ?? [])
+        candidateAuthority.set(id, 'provider-default');
+    if (project.provider_native === 'project-default') {
+        for (const [id, destination] of Object.entries(project.destinations ?? {})) {
+            if (destination.use_when === 'project-default')
+                candidateAuthority.set(id, 'project-default');
+        }
+    }
+    if (options.userPreference?.provider_native === 'project-default') {
+        for (const [id, destination] of Object.entries(options.userPreference.destinations ?? {})) {
+            if (destination.enabled !== false && destination.use_when === 'project-default')
+                candidateAuthority.set(id, 'user-preference');
+        }
+    }
+    for (const id of explicit)
+        candidateAuthority.set(id, 'explicit-task');
+    const candidates = candidateAuthority.keys();
+    for (const id of candidates) {
+        if (!supported.has(id)) {
+            diagnostics.push(`Destination '${id}' is unknown or unsupported and was not selected.`);
+            continue;
+        }
+        const policy = project.destinations?.[id];
+        if (project.provider_native === 'disabled' || policy?.enabled === false || policy?.use_when === 'disabled') {
+            diagnostics.push(`Destination '${id}' is disabled by project policy.`);
+            continue;
+        }
+        const selectedBy = candidateAuthority.get(id);
+        if (selectedBy === 'explicit-task') {
+            presentations.push(id);
+            authority[id] = 'explicit-task';
+            continue;
+        }
+        if (project.provider_native === 'project-default' && policy?.use_when === 'project-default') {
+            presentations.push(id);
+            authority[id] = selectedBy;
+            continue;
+        }
+        diagnostics.push(`Destination '${id}' requires an explicit per-task request; provider and user defaults cannot select it.`);
+    }
+    return { canonical: 'aiwg', presentations: [...new Set(presentations)].sort(), authority, diagnostics };
+}
+export async function recordArtifactOutputProvenance(artifactRoot, record) {
+    const path = join(artifactRoot, 'provenance', 'artifact-outputs.jsonl');
+    await mkdir(dirname(path), { recursive: true });
+    const value = { schemaVersion: 'aiwg.artifact-output-provenance.v1', createdAt: new Date().toISOString(), ...record };
+    await appendFile(path, `${JSON.stringify(value)}\n`, 'utf8');
+    return path;
+}
+//# sourceMappingURL=output-policy.js.map

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

@@ -62,12 +62,13 @@ import { jobHandler } from './job.js';
 import { costReportHandler } from './cost-report.js';
 import { evidenceHandler } from './evidence.js';
 import { artifactVerifyHandler } from './artifact-verify.js';
+import { outputModeHandler } from './output-mode.js';
 // Re-export individual handlers
 export { 
 // Maintenance
 helpHandler, versionHandler, authHandler, doctorHandler, contextFirewallHandler, updateHandler, refreshHandler, regenerateHandler, workspaceContextHandler, 
 // Framework management
-useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, artifactVerifyHandler, 
+useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, artifactVerifyHandler, outputModeHandler, 
 // Project
 newBundleHandler, quickrefHandler, newProjectHandler, sessionHandler, sessionsHandler, 
 // Workspace
@@ -150,6 +151,7 @@ export const allHandlers = [
     costReportHandler,
     evidenceHandler,
     artifactVerifyHandler,
+    outputModeHandler,
     // Workspace management
     ...workspaceHandlers,
     // Subcommand handlers (MCP, catalog, index, skills)

package/dist/src/cli/handlers/output-mode.js

@@ -0,0 +1,69 @@
+import { loadOutputModeRegistry, readOutputModeState, resolveOutputModes, writeOutputModeState } from '../../output-modes/registry.js';
+function flagValue(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function parseScope(args) {
+    const scope = flagValue(args, '--scope') ?? 'session';
+    if (!['invocation', 'session', 'project'].includes(scope))
+        throw new Error(`Invalid scope '${scope}'; expected invocation, session, or project.`);
+    return scope;
+}
+async function execute(ctx) {
+    const [action = 'status', id] = ctx.args.filter((arg, index, all) => !arg.startsWith('-') && all[index - 1] !== '--scope');
+    const registry = await loadOutputModeRegistry(ctx.cwd, ctx.frameworkRoot);
+    if (action === 'list') {
+        const rows = [...registry.values()].sort((a, b) => a.id.localeCompare(b.id)).map(p => `${p.id}\t${p.kind}\t${p.validation.level}\t${p.source}\t${p.description}`);
+        return { exitCode: 0, rawOutput: true, message: `ID\tKIND\tVALIDATION\tSOURCE\tDESCRIPTION\n${rows.join('\n')}` };
+    }
+    if (action === 'show') {
+        if (!id)
+            return { exitCode: 1, message: 'Usage: aiwg output-mode show <id>' };
+        const p = registry.get(id);
+        if (!p)
+            return { exitCode: 1, message: `Unknown output mode '${id}'.` };
+        return { exitCode: 0, rawOutput: true, message: JSON.stringify(p, null, 2) };
+    }
+    if (action === 'status') {
+        const invocation = ctx.args.flatMap((arg, i) => arg === '--output-mode' && ctx.args[i + 1] ? [ctx.args[i + 1]] : []);
+        const resolved = await resolveOutputModes(ctx.cwd, ctx.frameworkRoot, invocation);
+        if (resolved.modes.length === 0)
+            return { exitCode: 0, rawOutput: true, message: 'Effective output mode: unaltered\nContext cost: 0 tokens\nNo transformations active.' };
+        const lines = resolved.modes.map((p, i) => `${i + 1}. ${p.id} [${p.kind}/${p.stage}] source=${p.source} scope=${p.scope} validation=${p.validation.level} context≈${p.contextCost ?? 0}`);
+        return { exitCode: 0, rawOutput: true, message: `Effective ordered stack:\n${lines.join('\n')}\nEstimated context cost: ${resolved.modes.reduce((n, p) => n + (p.contextCost ?? 0), 0)} tokens` };
+    }
+    if (!['enable', 'disable', 'clear'].includes(action))
+        return { exitCode: 1, message: `Unknown output-mode action '${action}'.` };
+    const scope = parseScope(ctx.args);
+    if (scope === 'invocation') {
+        if (action !== 'enable' || !id)
+            return { exitCode: 1, message: 'Invocation scope is ephemeral; pass --output-mode <id> to the command being run.' };
+        if (!registry.has(id))
+            return { exitCode: 1, message: `Unknown output mode '${id}'.` };
+        return { exitCode: 0, message: `Invocation mode '${id}' validated. Pass --output-mode ${id} to the command being run; no files were modified.` };
+    }
+    const state = await readOutputModeState(ctx.cwd, scope);
+    let modes = [...state.modes];
+    if (action === 'clear')
+        modes = [];
+    else {
+        if (!id)
+            return { exitCode: 1, message: `Usage: aiwg output-mode ${action} <id> --scope ${scope}` };
+        if (!registry.has(id))
+            return { exitCode: 1, message: `Unknown output mode '${id}'.` };
+        modes = action === 'enable' ? [...new Set([...modes, id])] : modes.filter(value => value !== id);
+    }
+    await resolveOutputModes(ctx.cwd, ctx.frameworkRoot, scope === 'session' ? modes : []);
+    const path = await writeOutputModeState(ctx.cwd, scope, modes);
+    return { exitCode: 0, message: `${action === 'clear' ? 'Cleared' : `${action}d`} ${scope} output modes (${modes.join(', ') || 'unaltered'}) at ${path}` };
+}
+export const outputModeHandler = {
+    id: 'output-mode', name: 'Output Modes', description: 'List, inspect, and select composable output modes', category: 'project', aliases: ['output-modes'],
+    async execute(ctx) { try {
+        return await execute(ctx);
+    }
+    catch (error) {
+        return { exitCode: 1, message: error.message };
+    } },
+};
+//# sourceMappingURL=output-mode.js.map

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

@@ -16,6 +16,23 @@ import { spawn } from 'child_process';
 import { readAiwgConfig, getProjectDir } from '../../config/aiwg-config.js';
 import { handlerResultFromError } from '../errors.js';
 import * as ui from '../ui.js';
+import { resolveOutputModes } from '../../output-modes/registry.js';
+function extractOutputModes(args) {
+    const cleaned = [];
+    const modes = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--output-mode') {
+            const id = args[i + 1];
+            if (!id || id.startsWith('-'))
+                throw new Error('--output-mode requires a mode ID');
+            modes.push(id);
+            i += 1;
+        }
+        else
+            cleaned.push(args[i]);
+    }
+    return { args: cleaned, modes };
+}
 /**
  * Execute a shell command with inherited stdio.
  * Returns the exit code.
@@ -41,8 +58,28 @@ export const runHandler = {
     category: 'utility',
     aliases: [],
     async execute(ctx) {
-        const scriptName = ctx.args[0];
+        let parsed;
+        try {
+            parsed = extractOutputModes(ctx.args);
+        }
+        catch (error) {
+            return { exitCode: 1, message: error.message };
+        }
+        const scriptName = parsed.args[0];
         const projectDir = getProjectDir(ctx, ctx.args);
+        let outputModeEnv = {};
+        try {
+            const resolved = await resolveOutputModes(projectDir, ctx.frameworkRoot, parsed.modes);
+            if (resolved.modes.length > 0) {
+                outputModeEnv = {
+                    AIWG_OUTPUT_MODES: resolved.modes.map(mode => mode.id).join(','),
+                    AIWG_OUTPUT_MODES_JSON: JSON.stringify(resolved.modes),
+                };
+            }
+        }
+        catch (error) {
+            return { exitCode: 1, message: `Output mode resolution failed: ${error.message}` };
+        }
         // #1231 — intercept --help/-h before script lookup so the user sees
         // help for both run forms, not "No script named '--help'".
         if (scriptName === '--help' || scriptName === '-h') {
@@ -55,7 +92,7 @@ export const runHandler = {
         if (scriptName === 'skill') {
             try {
                 const { main } = await import('../../skills/run.js');
-                const exitCode = await main(ctx.args);
+                const exitCode = await main(parsed.args, outputModeEnv);
                 return { exitCode };
             }
             catch (error) {
@@ -119,6 +156,7 @@ export const runHandler = {
         const env = {
             AIWG_PROJECT: projectDir,
             AIWG_PROVIDERS: config.providers.join(','),
+            ...outputModeEnv,
         };
         ui.blank();
         console.log(`  ${ui.brandMark()} ${ui.bold(`aiwg run ${scriptName}`)}`);
@@ -140,8 +178,8 @@ export const runHandler = {
     },
 };
 function printRunUsage() {
-    console.log('Usage: aiwg run <script-name> [args...]');
-    console.log('       aiwg run skill <skill-name> [--cwd <path>] [-- <args forwarded to script>]');
+    console.log('Usage: aiwg run <script-name> [--output-mode <id>] [args...]');
+    console.log('       aiwg run skill <skill-name> [--output-mode <id>] [--cwd <path>] [-- <args forwarded to script>]');
     console.log('');
     console.log('Two forms share the `run` namespace:');
     console.log('');

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

@@ -674,7 +674,7 @@ const SESSION_RELOAD_NOTICE = {
         rationale: 'OpenCode loads agent files on session start and does not hot-reload.',
     },
     hermes: {
-        action: 'In an active Hermes session, run /reload-skills to pick up new skills in ~/.hermes/skills/ and /reload-mcp to pick up MCP server changes (~/.hermes/config.yaml) — both are in-session slash commands, no chat restart needed. Restart the chat only as a fallback if the slash commands are unavailable.',
+        action: 'In an active Hermes session, run /reload-skills to pick up new skills in $HERMES_HOME/skills/ and /reload-mcp to pick up MCP server changes ($HERMES_HOME/config.yaml) — both are in-session slash commands, no chat restart needed. Restart the chat only as a fallback if the slash commands are unavailable.',
         rationale: 'Hermes loads skills and MCP config at session start (verified in hermes_cli/commands.py:178 and hermes_cli/config.py:1228). The /reload-skills and /reload-mcp slash commands re-scan in place; /reload-mcp prompts for confirmation by default.',
         symptom: 'Until reloaded, newly deployed kernel skills are missing from `hermes skills list` and unreachable via natural-language invocation; new MCP servers (incl. AIWG) are missing from the tool surface.',
     },
@@ -3249,11 +3249,12 @@ export class UseHandler {
         // Collect deployment counts for registry persistence and the final
         // orchestrated report. Presentation happens once, after verification, so
         // users do not see a second competing summary.
-        let counts = { agents: 0, commands: 0, skills: 0, rules: 0, behaviors: 0 };
-        if (quiet) {
-            const paths = getProviderPaths(provider);
-            counts = await countDeployedArtifacts(target, paths, provider);
-        }
+        //
+        // Counts are always populated from the on-disk artifacts so that the
+        // registry record written below (#621) reflects the real deploy even on
+        // a verbose run — the prior `if (quiet)` guard left the record
+        // `{agents: 0, commands: 0, skills: 0, rules: 0}` on `-v` runs.
+        const counts = await countDeployedArtifacts(target, paths, provider);
         // Deploy CI workflow files when --ci-hooks-enabled is set (#661)
         if (ciHooksEnabled) {
             await deployCiHooks({ frameworkRoot, framework, target, dryRun });

package/dist/src/cli/scope-resolver.js

@@ -11,6 +11,8 @@
  */
 import { homedir } from 'node:os';
 import * as path from 'node:path';
+import { resolveHermesHome, resolveHermesHomePath } from '../providers/hermes-home.js';
+export const hermesHome = resolveHermesHome;
 /**
  * User-scope deploy paths per provider per ADR-4 §2. Each path is absolute
  * (rooted in os.homedir()) so the orchestrator's existing path-join logic
@@ -159,7 +161,10 @@ export const USER_SCOPE_PATHS = {
     },
     hermes: {
         agents: '',
-        skills: path.join(homedir(), '.hermes', 'skills'),
+        // #2119: honor HERMES_HOME so `--scope user` deploys land under the same
+        // root the running Hermes session scans, matching the hermes provider's
+        // paths.skills resolution.
+        skills: resolveHermesHomePath('skills'),
         commands: '',
         rules: '',
         behaviors: '',

package/dist/src/config/aiwg-config.js

@@ -16,6 +16,7 @@ import { getProviderDefinition, getProviderKernelSkillPath, PROVIDER_IDS, resolv
 import { validateAuthorization, } from '../policy/authorization.js';
 import { projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from './project-artifacts.js';
 import { defaultThreatAssessmentConfig, validateThreatAssessmentConfig, } from '../security/threat-assessment-config.js';
+import { defaultArtifactOutputs, validateArtifactOutputs } from '../artifacts/output-policy.js';
 const CONFIG_FILENAME = 'aiwg.config';
 /**
  * Operations that a workspace may authorize for one member repository.
@@ -638,6 +639,7 @@ export function emptyConfig(providers = ['claude']) {
         security: {
             threatAssessment: defaultThreatAssessmentConfig(),
         },
+        artifact_outputs: defaultArtifactOutputs(),
         delivery: {
             mode: 'pr-required',
             default_branch: 'main',
@@ -730,6 +732,9 @@ export async function readAiwgConfig(projectDir) {
     if (threatAssessmentErrors.length > 0) {
         throw new Error(`Invalid .aiwg/aiwg.config:\n${threatAssessmentErrors.join('\n')}`);
     }
+    const artifactOutputErrors = validateArtifactOutputs(parsed.artifact_outputs);
+    if (artifactOutputErrors.length > 0)
+        throw new Error(`Invalid .aiwg/aiwg.config:\n${artifactOutputErrors.join('\n')}`);
     return parsed;
 }
 /**
@@ -742,6 +747,9 @@ export async function writeAiwgConfig(projectDir, config) {
     if (threatAssessmentErrors.length > 0) {
         throw new Error(`Invalid .aiwg/aiwg.config:\n${threatAssessmentErrors.join('\n')}`);
     }
+    const artifactOutputErrors = validateArtifactOutputs(config.artifact_outputs);
+    if (artifactOutputErrors.length > 0)
+        throw new Error(`Invalid .aiwg/aiwg.config:\n${artifactOutputErrors.join('\n')}`);
     const localPath = getConfigPath(projectDir);
     const artifactDir = resolveProjectAiwgDir(projectDir);
     const artifactPath = join(artifactDir, CONFIG_FILENAME);

package/dist/src/config/cli.js

@@ -155,6 +155,8 @@ const ENUM_RULES = {
     'remotes.transport.protocol': ['ssh', 'https'],
     'repo_maintainer.tiers.local': ['collaborator', 'maintainer', 'admin'],
     'security.threatAssessment.mode': ['off', 'audit', 'enforce'],
+    'artifact_outputs.canonical': ['aiwg'],
+    'artifact_outputs.provider_native': ['disabled', 'explicit-only', 'project-default'],
 };
 const BOOLEAN_FIELDS = new Set([
     'delivery.delete_branch_on_merge',

package/dist/src/extensions/commands/definitions.js

@@ -1061,6 +1061,24 @@ export const sessionCommand = {
         },
     },
 };
+export const outputModeCommand = {
+    id: 'output-mode',
+    type: 'command',
+    name: 'Output Modes',
+    description: 'List, inspect, enable, disable, clear, and report composable output modes',
+    version: '1.0.0',
+    capabilities: ['cli', 'voice', 'output-mode', 'controlled-language', 'presentation'],
+    keywords: ['output-mode', 'voice', 'style', 'asd-ste', 'presentation'],
+    category: 'project',
+    platforms: { claude: 'full', generic: 'full' },
+    deployment: { pathTemplate: '.{platform}/commands/{id}.md', core: true },
+    metadata: {
+        type: 'command',
+        template: 'utility',
+        argumentHint: '<list|show|enable|disable|clear|status> [id] [--scope invocation|session|project]',
+        allowedTools: ['Read', 'Write'],
+    },
+};
 // Session Catalog Command (#1903)
 export const sessionsCommand = {
     id: 'sessions',
@@ -3701,6 +3719,7 @@ export const commandDefinitions = [
     // Session (#884)
     sessionCommand,
     sessionsCommand,
+    outputModeCommand,
 ];
 // ============================================
 // Helper Functions

package/dist/src/extensions/project-quickref.js

@@ -11,6 +11,7 @@ import { basename, dirname, isAbsolute, join, resolve } from 'path';
 import { homedir } from 'os';
 import { z } from 'zod';
 import { getProviderDefinition, normalizeProviderDefinitionId, } from '../providers/provider-definitions.js';
+import { resolveHermesHome } from '../providers/hermes-home.js';
 import { OPERATIONAL_SHOW_TYPES } from '../artifacts/types.js';
 import { projectAiwgPath } from '../config/project-artifacts.js';
 import { appendAiwgSourceTrackBlock } from './project-local-gitignore.js';
@@ -339,6 +340,14 @@ function resolveProviderSkillsRoot(provider, projectDir, homeDir) {
     const definition = getProviderDefinition(normalized);
     if (!definition)
         throw new Error(`Provider definition unavailable for '${provider}'`);
+    if (normalized === 'hermes') {
+        return {
+            provider: normalized,
+            root: resolve(resolveHermesHome(homeDir), 'skills'),
+            emulated: false,
+            global: true,
+        };
+    }
     const configured = definition.paths.kernelSkills ?? definition.paths.artifacts.skills;
     if (!configured)
         throw new Error(`Provider '${normalized}' has no supported skill or aggregation target`);

package/dist/src/output-modes/registry.js

@@ -0,0 +1,158 @@
+import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { dirname, extname, join, resolve } from 'node:path';
+import { parse, stringify } from 'yaml';
+const PROTECTED = ['code', 'commands', 'citations', 'quoted-text', 'identifiers', 'machine-readable-blocks'];
+const STAGE_ORDER = ['semantic', 'voice', 'controlled-language', 'structure', 'presentation'];
+const BUILTINS = [
+    {
+        id: 'unaltered', version: '1.0.0', description: 'No-op mode; preserves the provider output path unchanged.',
+        kind: 'presentation', stage: 'presentation', order: -1000, instructions: '',
+        provenance: { source: 'AIWG', license: 'MIT' }, validation: { level: 'advisory' }, contextCost: 0,
+        protectedContent: PROTECTED,
+    },
+    {
+        id: 'wittgenstein-inspired', version: '1.0.0', description: 'Concise, proposition-oriented stylistic profile; not impersonation or attribution.',
+        kind: 'voice', stage: 'voice', order: 100, instructions: 'Prefer concise propositions, clarify terms in use, and expose category errors. Do not imitate or attribute text to Ludwig Wittgenstein.',
+        provenance: { source: 'AIWG original style guidance', license: 'MIT' }, validation: { level: 'advisory' }, contextCost: 48,
+        protectedContent: PROTECTED,
+    },
+    {
+        id: 'asd-ste', version: '1.0.0', description: 'Operator-configured ASD Simplified Technical English adapter.',
+        kind: 'controlled-language', stage: 'controlled-language', order: 200,
+        instructions: 'Apply only operator-supplied ASD-STE rules and approved terminology. Without licensed rules and a configured validator, describe output as advisory and never claim conformance.',
+        provenance: { source: 'AIWG adapter; standard content supplied by operator', license: 'MIT adapter only' },
+        validation: { level: 'advisory', standardVersion: 'operator-configured' }, contextCost: 64,
+        protectedContent: PROTECTED,
+    },
+];
+function profileDirs(cwd) {
+    return [
+        { dir: join(cwd, '.aiwg', 'output-modes'), source: 'project' },
+        { dir: join(homedir(), '.config', 'aiwg', 'output-modes'), source: 'user' },
+    ];
+}
+async function readable(path) {
+    try {
+        await access(path, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function validateProfile(value, path) {
+    if (!value || typeof value !== 'object')
+        throw new Error(`Invalid output mode profile at ${path}: expected an object`);
+    const p = value;
+    for (const field of ['id', 'version', 'description', 'kind', 'stage', 'instructions', 'provenance', 'validation']) {
+        if (p[field] === undefined)
+            throw new Error(`Invalid output mode profile at ${path}: missing ${field}`);
+    }
+    if (!['voice', 'controlled-language', 'structure', 'presentation'].includes(String(p.kind)))
+        throw new Error(`Invalid output mode kind in ${path}: ${p.kind}`);
+    if (!STAGE_ORDER.includes(String(p.stage)))
+        throw new Error(`Invalid output mode stage in ${path}: ${p.stage}`);
+    return p;
+}
+async function loadDirectory(dir, source) {
+    if (!(await readable(dir)))
+        return [];
+    const result = [];
+    for (const name of (await readdir(dir)).sort()) {
+        if (!['.yaml', '.yml', '.json'].includes(extname(name)))
+            continue;
+        const sourcePath = join(dir, name);
+        const raw = await readFile(sourcePath, 'utf8');
+        const value = extname(name) === '.json' ? JSON.parse(raw) : parse(raw);
+        result.push({ ...validateProfile(value, sourcePath), source, sourcePath });
+    }
+    return result;
+}
+async function loadVoiceAdapters(frameworkRoot) {
+    const dir = join(frameworkRoot, 'agentic', 'code', 'addons', 'voice-framework', 'voices', 'templates');
+    if (!(await readable(dir)))
+        return [];
+    const result = [];
+    for (const name of (await readdir(dir)).filter(n => /\.ya?ml$/.test(n)).sort()) {
+        const sourcePath = join(dir, name);
+        const voice = parse(await readFile(sourcePath, 'utf8'));
+        const id = String(voice.id ?? name.replace(/\.ya?ml$/, ''));
+        result.push({
+            id, version: String(voice.version ?? '1.0.0'), description: String(voice.description ?? `Adapted voice profile: ${id}`),
+            kind: 'voice', stage: 'voice', order: 100, instructions: `Apply the existing voice profile '${id}' through voice-apply.`,
+            provenance: { source: sourcePath, license: String(voice.license ?? 'project license') },
+            validation: { level: 'advisory' }, protectedContent: PROTECTED, contextCost: 32,
+            mergeStrategy: 'weighted-voice', source: 'voice-adapter', sourcePath,
+        });
+    }
+    return result;
+}
+export async function loadOutputModeRegistry(cwd, frameworkRoot) {
+    const registry = new Map();
+    for (const profile of BUILTINS)
+        registry.set(profile.id, { ...profile, source: 'builtin' });
+    for (const profile of await loadVoiceAdapters(frameworkRoot))
+        if (!registry.has(profile.id))
+            registry.set(profile.id, profile);
+    // User overrides built-ins; project overrides user.
+    for (const entry of [...profileDirs(cwd)].reverse())
+        for (const profile of await loadDirectory(entry.dir, entry.source))
+            registry.set(profile.id, profile);
+    return registry;
+}
+function statePath(cwd, scope) {
+    if (scope === 'project')
+        return join(cwd, '.aiwg', 'output-modes.yaml');
+    const workspace = createHash('sha256').update(resolve(cwd)).digest('hex').slice(0, 16);
+    const session = process.env.AIWG_SESSION_ID?.replace(/[^a-zA-Z0-9_.-]/g, '_') || 'default';
+    return join(tmpdir(), 'aiwg-output-modes', `${workspace}-${session}.yaml`);
+}
+export async function readOutputModeState(cwd, scope) {
+    const path = statePath(cwd, scope);
+    if (!(await readable(path)))
+        return { version: 1, modes: [] };
+    const value = parse(await readFile(path, 'utf8'));
+    return { version: 1, modes: Array.isArray(value.modes) ? value.modes.map(String) : [] };
+}
+export async function writeOutputModeState(cwd, scope, modes) {
+    const path = statePath(cwd, scope);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, stringify({ version: 1, modes }), 'utf8');
+    return path;
+}
+export async function resolveOutputModes(cwd, frameworkRoot, invocation = []) {
+    const registry = await loadOutputModeRegistry(cwd, frameworkRoot);
+    const project = await readOutputModeState(cwd, 'project');
+    const session = await readOutputModeState(cwd, 'session');
+    const selected = [...project.modes.map(id => ({ id, scope: 'project' })), ...session.modes.map(id => ({ id, scope: 'session' })), ...invocation.map(id => ({ id, scope: 'invocation' }))];
+    const effective = new Map();
+    const diagnostics = [];
+    for (const item of selected) {
+        const profile = registry.get(item.id);
+        if (!profile)
+            throw new Error(`Unknown output mode '${item.id}'. Unknown provider-native or custom modes fail safe; run 'aiwg output-mode list'.`);
+        effective.set(item.id, { ...profile, scope: item.scope });
+    }
+    const modes = [...effective.values()].sort((a, b) => STAGE_ORDER.indexOf(a.stage) - STAGE_ORDER.indexOf(b.stage) || (a.order ?? 0) - (b.order ?? 0) || a.id.localeCompare(b.id));
+    for (let i = 0; i < modes.length; i++)
+        for (let j = i + 1; j < modes.length; j++) {
+            const a = modes[i], b = modes[j];
+            if (a.conflicts?.includes(b.id) || b.conflicts?.includes(a.id))
+                throw new Error(`Output modes '${a.id}' and '${b.id}' conflict. Disable one or configure an explicit merge strategy.`);
+            if (a.kind === b.kind && a.kind !== 'voice')
+                throw new Error(`Output modes '${a.id}' and '${b.id}' share kind '${a.kind}' without a merge strategy.`);
+            if (a.kind === 'voice' && b.kind === 'voice' && a.mergeStrategy !== 'weighted-voice' && b.mergeStrategy !== 'weighted-voice')
+                throw new Error(`Voice modes '${a.id}' and '${b.id}' require an explicit weighted-voice merge strategy.`);
+        }
+    for (const mode of modes)
+        for (const requirement of mode.requires ?? [])
+            if (!effective.has(requirement))
+                throw new Error(`Output mode '${mode.id}' requires '${requirement}'.`);
+    if (modes.length === 0)
+        diagnostics.push('unaltered: no configured modes; no instructions or post-processing are added');
+    return { modes, diagnostics };
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/output-modes/runtime.js

@@ -0,0 +1,64 @@
+function protectedPattern(classes) {
+    const set = new Set(classes);
+    const alternatives = [];
+    if (set.has('machine-readable-blocks') || set.has('code'))
+        alternatives.push('```[\\s\\S]*?```');
+    if (set.has('code') || set.has('commands'))
+        alternatives.push('`[^`\\n]+`');
+    if (set.has('quoted-text'))
+        alternatives.push('^>.*(?:\\n>.*)*', '“[^”]*”', '"[^"\\n]+"');
+    if (set.has('citations'))
+        alternatives.push('\\[[^\\]\\n]+\\]\\([^\\s)]+\\)', '\\[[0-9]+\\]');
+    if (set.has('identifiers'))
+        alternatives.push('\\b(?:[A-Za-z_$][\\w$]*\\.)+[A-Za-z_$][\\w$]*\\b', '\\b[A-Z][A-Z0-9_]{2,}\\b');
+    return alternatives.length ? new RegExp(alternatives.join('|'), 'gm') : null;
+}
+function protect(content, classes) {
+    const literals = [];
+    const pattern = protectedPattern(classes);
+    const protectedContent = pattern ? content.replace(pattern, value => {
+        const token = `\uE000${literals.length}\uE001`;
+        literals.push({ token, value });
+        return token;
+    }) : content;
+    return { content: protectedContent, literals };
+}
+function restore(content, literals, mode) {
+    let restored = content;
+    for (const literal of literals) {
+        if (!restored.includes(literal.token))
+            throw new Error(`Output mode '${mode}' modified or removed a protected literal.`);
+        restored = restored.replaceAll(literal.token, literal.value);
+    }
+    return restored;
+}
+export async function applyOutputModes(input, modes, options) {
+    if (modes.length === 0)
+        return { content: input, diagnostics: [], applied: [], fallback: 'none' };
+    let content = input;
+    const diagnostics = [];
+    const applied = [];
+    for (const mode of modes) {
+        const snapshot = content;
+        const masked = protect(content, mode.protectedContent ?? []);
+        const transformed = await options.transform(masked.content, mode);
+        content = restore(transformed, masked.literals, mode.id);
+        if (mode.validation.level !== 'advisory') {
+            if (!options.validate)
+                throw new Error(`Output mode '${mode.id}' declares ${mode.validation.level} validation but no validator is configured.`);
+            const result = await options.validate(content, mode);
+            if (!result.valid) {
+                diagnostics.push({ mode: mode.id, level: mode.validation.level, message: result.message ?? 'validation failed' });
+                if ((options.onMandatoryValidationFailure ?? 'unaltered') === 'fail')
+                    throw new Error(`Output mode '${mode.id}' validation failed: ${result.message ?? 'no diagnostic'}`);
+                return { content: input, diagnostics, applied, fallback: 'unaltered' };
+            }
+        }
+        // A transform may only change semantic presentation, never return an absent result.
+        if (typeof content !== 'string')
+            content = snapshot;
+        applied.push(mode.id);
+    }
+    return { content, diagnostics, applied, fallback: 'none' };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/src/output-modes/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/providers/hermes-home.js

@@ -0,0 +1,20 @@
+import { homedir } from 'node:os';
+import * as path from 'node:path';
+/** Match Hermes Agent's process-level HERMES_HOME resolution contract. */
+export function resolveHermesHome(userHome = homedir()) {
+    const configured = (process.env.HERMES_HOME || '').trim();
+    if (configured)
+        return configured;
+    if (process.platform === 'win32') {
+        const localAppData = (process.env.LOCALAPPDATA || '').trim();
+        return localAppData
+            ? path.join(localAppData, 'hermes')
+            : path.join(userHome, 'AppData', 'Local', 'hermes');
+    }
+    return path.join(userHome, '.hermes');
+}
+/** Resolve a path exactly as a Hermes process would consume HERMES_HOME. */
+export function resolveHermesHomePath(...segments) {
+    return path.resolve(resolveHermesHome(), ...segments);
+}
+//# sourceMappingURL=hermes-home.js.map

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { homedir } from 'os';
 import { join } from 'path';
+import { resolveHermesHomePath } from './hermes-home.js';
 import { getProviderCapabilities, } from './capability-matrix.js';
 const ArtifactPathsSchema = z.object({
     agents: z.string().nullable(),
@@ -464,7 +465,7 @@ const BUILT_IN_SEEDS = [
         id: 'hermes',
         aliases: [],
         builtIn: true,
-        surfaces: { primary: 'hermes', compatibility: [], precedence: ['AGENTS.md', '.hermes.md', '~/.hermes/skills/'], related: [] },
+        surfaces: { primary: 'hermes', compatibility: [], precedence: ['.hermes.md', 'AGENTS.md', resolveHermesHomePath('skills')], related: [] },
         detection: {
             env: [],
             process: ['hermes'],
@@ -474,18 +475,18 @@ const BUILT_IN_SEEDS = [
             artifacts: {
                 agents: null,
                 commands: null,
-                skills: '~/.hermes/.aiwg/skills',
+                skills: resolveHermesHomePath('skills', '.aiwg'),
                 rules: null,
                 behaviors: null,
             },
-            kernelSkills: '~/.hermes/skills',
+            kernelSkills: resolveHermesHomePath('skills'),
             configFile: 'AGENTS.md',
             contextFiles: { aiwgMd: true, agentsMd: true, claudeMdHook: false, hookFile: '.hermes.md', contextFile: 'AGENTS.md' },
         },
         smithPaths: {
             agents: null,
             commands: null,
-            skills: '~/.hermes/skills',
+            skills: resolveHermesHomePath('skills'),
             rules: null,
             fileExtension: '.md',
             configFile: 'AGENTS.md',

package/dist/src/skills/deployer.js

@@ -15,6 +15,7 @@ import { getProviderDefinition, normalizeProviderDefinitionId, } from '../provid
 import { AGENT_SKILLS_SIDECAR_SCHEMA, AIWG_SKILL_CONTROL_FIELDS, createAgentSkillSidecar, projectStrictAgentSkill, } from './agent-skills.js';
 import { getImportedAgentSkill } from './importer.js';
 import { validateAgentSkillContent } from './validator.js';
+import { resolveHermesHomePath } from '../providers/hermes-home.js';
 export const AGENT_SKILL_MANAGED_MARKER = '.aiwg-managed';
 export const AGENT_SKILL_DEPLOYMENT_SIDECAR = '.aiwg-agent-skill.json';
 const MARKER_CONTENT = 'aiwg-agent-skill-v1\n';
@@ -78,7 +79,10 @@ function resolvePolicy(target, options) {
             reasons.push('applies the Factory description guidance before strict validation');
             break;
         case 'hermes':
-            reasons.push('uses the user-global ~/.hermes/skills bundle surface with strict managed ownership markers');
+            if (options.homeDir === undefined) {
+                root = resolveHermesHomePath('skills');
+            }
+            reasons.push('uses the active HERMES_HOME skills surface with strict managed ownership markers');
             break;
         case 'openhuman':
             status = 'projected';

package/dist/src/skills/run.js

@@ -148,6 +148,7 @@ export async function runSkill(opts) {
         AIWG_SKILL_DIR: skillDir,
         AIWG_PROJECT_ROOT: opts.cwd,
         ...(aiwgRoot ? { AIWG_ROOT: aiwgRoot } : {}),
+        ...opts.env,
     };
     const fullArgs = [...invocation.prefixArgs, entrypointPath, ...opts.args];
     return new Promise((resolve) => {
@@ -181,7 +182,7 @@ export async function runSkill(opts) {
  * Anything after `--` is verbatim-forwarded. If no `--`, all args after
  * the skill name are forwarded.
  */
-export async function main(args) {
+export async function main(args, env) {
     // First positional must be the kind ("skill" — reserved for future kinds).
     if (args.length === 0) {
         printUsage();
@@ -243,6 +244,7 @@ export async function main(args) {
         name,
         args: scriptArgs,
         cwdOverride,
+        env,
     });
 }
 function printUsage() {

package/dist/src/smiths/context-pipeline/claude-hook.js

@@ -24,18 +24,30 @@ import * as path from 'path';
 import { buildProviderBootstrapBlock, PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END, } from './workspace-context.js';
 export const CLAUDE_HOOK_START = '<!-- AIWG:claude-md-hook:start -->';
 export const CLAUDE_HOOK_END = '<!-- AIWG:claude-md-hook:end -->';
-/**
- * The managed block that gets inserted into CLAUDE.md. Tells Claude Code
- * to load AIWG.md as the project context entry point. Kept short — the
- * actual context lives in AIWG.md.
- */
-export function buildClaudeHookBlock() {
+function buildClaudeArtifactOutputPolicy(policy = {}) {
+    const providerNative = policy.provider_native ?? 'explicit-only';
+    const design = policy.destinations?.['claude-code.design'];
+    const designEnabled = design?.enabled !== false && design?.use_when !== 'disabled';
+    return [
+        '## AIWG artifact output policy',
+        '',
+        `- Canonical durable artifacts: AIWG artifact store (policy: ${policy.canonical ?? 'aiwg'}).`,
+        `- Provider-native presentation/export: ${providerNative}.`,
+        `- Claude Design: ${designEnabled ? 'available only when explicitly selected by the resolved policy or requested by the user' : 'disabled by project policy'}.`,
+        '- Never substitute, relocate, or omit the canonical AIWG plan/review artifact because Claude adds or changes a provider default.',
+        '- When both canonical and presentation outputs are selected, write the canonical artifact first; treat Design as a derived export and record provenance linking it to the canonical source of truth.',
+        '- Unknown provider-native destinations fail safe with a diagnostic. Higher-authority project policy overrides user preferences; explicit task selection overrides provider defaults only within the project policy ceiling.',
+    ];
+}
+export function buildClaudeHookBlock(policy = {}) {
     return [
         CLAUDE_HOOK_START,
         '',
         buildProviderBootstrapBlock('claude'),
         '@.aiwg/aiwg.config',
         '',
+        ...buildClaudeArtifactOutputPolicy(policy),
+        '',
         '<!--',
         '  This block is managed by `aiwg regenerate` and `aiwg use`.',
         '  Operator content above and below this block is preserved on regenerate.',
@@ -57,7 +69,15 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         action: 'skipped',
         warnings: [],
     };
-    const block = buildClaudeHookBlock();
+    let policy = {};
+    try {
+        const config = JSON.parse(await fs.readFile(path.join(projectPath, '.aiwg', 'aiwg.config'), 'utf8'));
+        policy = config.artifact_outputs ?? {};
+    }
+    catch {
+        // Missing/legacy/temporarily malformed config receives the safe default.
+    }
+    const block = buildClaudeHookBlock(policy);
     // Case 1: CLAUDE.md does not exist — create a minimal one with just the block.
     let existing;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.12",
+  "version": "2026.8.14",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",

package/tools/agents/deploy-agents.mjs

@@ -210,7 +210,13 @@ function resolveCommandMirrorDir(provider, target) {
   // Closest conventional location for providers whose primary command
   // surface is MCP/aggregation rather than a documented command directory.
   if (provider.name === 'hermes') {
-    return path.join(os.homedir(), '.hermes', 'commands');
+    // #2119: HERMES_HOME is the single source of truth the running Hermes
+    // runtime uses to locate its files — resolve the home the same way the
+    // provider does instead of hardcoding $HOME/.hermes.
+    const hermesHome = typeof provider.getHermesHome === 'function'
+      ? provider.getHermesHome()
+      : path.join(os.homedir(), '.hermes');
+    return path.resolve(hermesHome, 'commands');
   }
 
   return null;
@@ -530,7 +536,7 @@ Providers (all deploy agents, commands, skills, and rules):
   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)
+              Skills: $HERMES_HOME/skills/ (user-global; defaults to ~/.hermes/skills/) | Agents: AGENTS.md
               Commands/Rules: served via MCP, not file-deployed
 
 Modes:

package/tools/agents/providers/base.mjs

@@ -463,9 +463,36 @@ export function injectPlatformInContent(content, targetPlatform) {
   return open + fmLines.join('\n') + close + body;
 }
 
-/** @deprecated Use injectPlatformInContent instead */
+/**
+ * Remove the `platforms:` field from a SKILL.md frontmatter block.
+ *
+ * Hermes (and other providers that treat `platforms:` as an OS gate —
+ * linux / macos / windows) hide any skill whose value isn't a recognized
+ * OS. AIWG source skills use the field as a *provider* restriction token
+ * (`[all]`, provider names), which is the opposite meaning, so deployed
+ * copies destined for such providers must drop the field entirely. An
+ * absent field is the documented "compatible with all platforms" default.
+ */
 export function stripPlatformsFromContent(content) {
-  return injectPlatformInContent(content, null);
+  const fmMatch = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))([\s\S]*)$/);
+  if (!fmMatch) return content;
+
+  const [, open, fm, close, body] = fmMatch;
+  let updated = fm.replace(/^platforms:[^\r\n]*(?:\r?\n|$)/m, '');
+
+  // Multi-line list form:
+  //   platforms:
+  //     - claude-code
+  //     - hermes
+  if (updated === fm) {
+    updated = fm.replace(
+      /^platforms:[ \t]*\r?\n(?:[ \t]+-[ \t]+\S[^\r\n]*(?:\r?\n|$))*/m,
+      '',
+    );
+  }
+
+  if (updated === fm) return content;
+  return open + updated + close + body;
 }
 
 /**

package/tools/agents/providers/hermes.mjs

@@ -5,8 +5,8 @@
  * server is an optional enrichment hook that Hermes can call when configured.
  *
  * What this provider DOES deploy:
- *   - Skills: ~/.hermes/skills/ (user-global, for agentic skills callable by Hermes)
- *   - AGENTS.md: project root (lean routing guide that Hermes loads on every turn)
+ *   - Skills: $HERMES_HOME/skills/ (user-global, for agentic skills callable by Hermes)
+ *   - AGENTS.md: project root (full AIWG routing guide referenced by .hermes.md)
  *
  * What this provider SKIPS:
  *   - Commands: Hermes has no AIWG slash-command file surface
@@ -22,6 +22,7 @@ let fs;
 try { const gfs = _require('graceful-fs'); gfs.gracefulify(realFs); fs = realFs; } catch { fs = realFs; }
 import path from 'path';
 import os from 'os';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import {
   ensureDir,
   listMdFiles,
@@ -37,8 +38,61 @@ import {
   collectFrameworkArtifacts,
   listOnDemandRuleFiles,
   renderOnDemandRuleSection,
+  stripPlatformsFromContent,
 } from './base.mjs';
 
+// ============================================================================
+// Hermes home resolution (HERMES_HOME) — #2119
+// ============================================================================
+//
+// Mirrors `hermes_constants.get_hermes_home()` in the Hermes Agent runtime.
+// Resolution order (upstream, hermes_constants.py:114-):
+//   1. A context-local override installed in-process via
+//      set_hermes_home_override() — AIWG runs in a separate node process and
+//      cannot observe that token, so step 1 is intentionally NOT part of the
+//      cross-process contract.
+//   2. The process `HERMES_HOME` env var.
+//   3. The platform-native default:
+//        win32 → %LOCALAPPDATA%/hermes   (falls back to %USERPROFILE%/AppData/
+//                  Local/hermes when LOCALAPPDATA is unset)
+//        other → $HOME/.hermes
+//
+// AIWG reads the env var when `getHermesHome()` is invoked; the module-level
+// constants below lock in the value captured at first use so every consumer
+// (paths, kernels, orchestrate, legacy migration) sees the same resolved root
+// for the life of the process.
+
+/**
+ * Resolve the Hermes home directory.
+ *
+ * Honors HERMES_HOME the way the running Hermes runtime does, so that
+ * `aiwg use --provider hermes` writes skills under the same root the live
+ * session scans. See #2119 — before this helper, the provider hardcoded
+ * `os.homedir()/.hermes` and any operator running Hermes under a non-default
+ * HERMES_HOME (multi-profile, hermes-role wrappers, dev containers) got a
+ * silently divergent deployment.
+ */
+export function getHermesHome() {
+  const env = (process.env.HERMES_HOME || '').trim();
+  if (env) {
+    // Match upstream's Path(env) contract exactly. Hermes does not expand a
+    // leading `~` or resolve relative values here; both remain relative to the
+    // process working directory when the path is consumed.
+    return env;
+  }
+  if (process.platform === 'win32') {
+    const localAppData = (process.env.LOCALAPPDATA || '').trim();
+    return localAppData
+      ? path.join(localAppData, 'hermes')
+      : path.join(os.homedir(), 'AppData', 'Local', 'hermes');
+  }
+  return path.join(os.homedir(), '.hermes');
+}
+
+// The value captured below is the target any running Hermes session with the
+// same environ would use as its scan root.
+const HERMES_HOME = getHermesHome();
+
 // ============================================================================
 // Provider Configuration
 // ============================================================================
@@ -49,10 +103,15 @@ export const aliases = [];
 export const paths = {
   agents: 'AGENTS.md',                           // Aggregated routing guide at project root
   commands: '',                                   // Not applicable — no AIWG slash-command file surface
-  // Standard skills under ~/.hermes/skills/.aiwg/ — child of Hermes's scanned root,
-  // recursively discovered (verified `agent/skill_utils.py:478-489`, os.walk follows
-  // subdirs except .git/.github/.hub/.archive). Kernel skills land in the parent.
-  skills: path.join(os.homedir(), '.hermes', 'skills', '.aiwg'),
+  // Standard skills under <HERMES_HOME>/skills/.aiwg/ — child of Hermes's
+  // scanned root, recursively discovered (verified `agent/skill_utils.py:478-489`,
+  // os.walk follows subdirs except .git/.github/.hub/.archive).
+  //
+  // HERMES_HOME honors the process env var and falls back to $HOME/.hermes
+  // (win32: %LOCALAPPDATA%/hermes), matching hermes_constants.get_hermes_home().
+  // #2119: previously hardcoded os.homedir() — wrong for any operator running
+  // Hermes under a non-default HERMES_HOME (multi-profile, hermes-role, etc.).
+  skills: path.resolve(HERMES_HOME, 'skills', '.aiwg'),
   rules: '',                                      // Inlined into AGENTS.md + reachable via `aiwg show rule`
 };
 
@@ -60,12 +119,17 @@ export const paths = {
 // Standard skills land in the .aiwg/ subdirectory under the same root —
 // Hermes recursively walks the skill root (verified against upstream v0.13.0,
 // `agent/skill_utils.py:478-489`).
-export const kernelSkillsPath = path.join(os.homedir(), '.hermes', 'skills');
+export const kernelSkillsPath = path.resolve(HERMES_HOME, 'skills');
+
+// Resolved home directory this provider's paths were computed against.
+// Consumers (deploy verification, doctor, status) should use this rather than
+// re-reading os.homedir() to stay consistent with the deploy target.
+export const hermesHome = HERMES_HOME;
 
 export const support = {
   agents: 'aggregated',      // Agents aggregated into lean AGENTS.md
   commands: 'none',          // Hermes has no AIWG slash-command file surface
-  skills: 'native',          // ~/.hermes/skills/ is native Hermes skill location
+  skills: 'native',          // $HERMES_HOME/skills/ is the native skill location
   rules: 'agents-md+cli',    // compressed in AGENTS.md; full bodies via CLI/MCP
 };
 
@@ -77,6 +141,43 @@ export const capabilities = {
   homeDirectoryDeploy: true,  // Skills deploy to home dir
 };
 
+/**
+ * Project portable Agent Skills metadata into Hermes's native frontmatter.
+ *
+ * The portable Agent Skills contract restricts `metadata` values to strings,
+ * while Hermes expects tags at `metadata.hermes.tags`. AIWG stores the tag
+ * list as a comma-separated `metadata.hermes-tags` string in source and
+ * performs the provider-specific projection only in the deployed copy.
+ */
+export function transformHermesSkillContent(content) {
+  const stripped = stripPlatformsFromContent(content);
+  const match = stripped.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+  if (!match) return stripped;
+
+  let frontmatter;
+  try {
+    frontmatter = parseYaml(match[1]);
+  } catch {
+    return stripped;
+  }
+  if (!frontmatter || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    return stripped;
+  }
+
+  const metadata = frontmatter.metadata;
+  const encodedTags = metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+    ? metadata['hermes-tags']
+    : undefined;
+  if (typeof encodedTags !== 'string') return stripped;
+
+  const tags = encodedTags.split(',').map((tag) => tag.trim()).filter(Boolean);
+  delete metadata['hermes-tags'];
+  metadata.hermes = { tags };
+
+  const body = stripped.slice(match[0].length);
+  return `---\n${stringifyYaml(frontmatter).trimEnd()}\n---\n${body}`;
+}
+
 // ============================================================================
 // Model Mapping (not applicable — Hermes uses local Ollama models)
 // ============================================================================
@@ -203,7 +304,8 @@ export function generateAgentsMd(agentCount, skillCount, targetDir, opts) {
   const header = `# AIWG Integration
 
 AIWG connected through file-based deployment. Native Hermes skills are available
-at \`~/.hermes/skills/\` (kernel) and \`~/.hermes/skills/.aiwg/\` (standard).
+at \`$HERMES_HOME/skills/\` (kernel) and \`$HERMES_HOME/skills/.aiwg/\` (standard).
+When unset, \`HERMES_HOME\` defaults to the platform-native Hermes home.
 Use \`aiwg discover\` and \`aiwg show <type> <name>\` for the on-demand catalog.
 The MCP sidecar (\`aiwg mcp serve\`) is optional.
 
@@ -285,10 +387,12 @@ AIWG project context lives in \`AGENTS.md\` (this file is a thin Hermes pointer)
 
 **Routing**: see \`AGENTS.md\` in this directory.
 **MCP**: AIWG is reachable via \`mcp_aiwg_*\` tools.
-**Skills**: kernel skills at \`~/.hermes/skills/\`; standard skills at \`~/.hermes/skills/.aiwg/\`.
+**Skills**: kernel skills at \`$HERMES_HOME/skills/\`; standard skills at \`$HERMES_HOME/skills/.aiwg/\`.
+When unset, \`HERMES_HOME\` defaults to the platform-native Hermes home.
 
-Hermes loads \`.hermes.md\` before \`AGENTS.md\` (first-match-wins). Keep this
-file minimal — Hermes will load AGENTS.md content next via the routing chain.
+Hermes loads only \`.hermes.md\` when it is present (first-match-wins). Keep
+this file minimal; its routing instruction tells the agent to read \`AGENTS.md\`
+when the full AIWG project context is needed.
 `;
   const destPath = path.join(targetDir, '.hermes.md');
   if (dryRun) {
@@ -309,8 +413,8 @@ file minimal — Hermes will load AGENTS.md content next via the routing chain.
  *
  * Skills are user-global in Hermes, deployed once, available in all
  * projects. Kernel routing per the cross-provider pattern:
- *   - kernel skills → ~/.hermes/skills/         (platform-native, always-loaded)
- *   - standard      → ~/.hermes/skills/.aiwg/   (recursively walked by Hermes)
+ *   - kernel skills → $HERMES_HOME/skills/         (platform-native, always-loaded)
+ *   - standard      → $HERMES_HOME/skills/.aiwg/   (recursively walked by Hermes)
  */
 export function deploySkills(skillDirs, opts) {
   const standardDestDir = paths.skills;
@@ -375,7 +479,18 @@ export async function deploy(opts) {
     allSkillDirs.push(...(artifacts.skills || []));
 
     if (allSkillDirs.length > 0) {
-      deploySkills(allSkillDirs, opts);
+      // Hermes's skill loader reads `platforms:` as an OS gate
+      // (linux / macos / windows). AIWG's shared deploy path injects
+      // `[hermes]` into that field, which then filters every skill out
+      // on Linux. Strip the field post-injection — hermes documents
+      // "absent field = all platforms" as its default. This leaves the
+      // other providers' `transformSkillMd` pipeline untouched.
+      const skillOpts = {
+        ...opts,
+        provider: 'hermes', // ensure deploySkillDir's injectPlatform branch runs
+        transformSkillMd: transformHermesSkillContent,
+      };
+      deploySkills(allSkillDirs, skillOpts);
     } else if (!opts.quiet) {
       console.log('  No skills found to deploy');
     }
@@ -424,7 +539,7 @@ export async function deploy(opts) {
 
   // ── aiwg-orchestrate convenience skill (#1242) ──────────────────────────────
   // First-deploy-only copy: lays down the delegate_task wrapper at
-  // ~/.hermes/skills/aiwg-orchestrate/SKILL.md if it isn't already present.
+  // $HERMES_HOME/skills/aiwg-orchestrate/SKILL.md if it isn't already present.
   // The skill provides ~95% per-workflow context reduction by routing AIWG
   // calls through Hermes's `delegate_task` instead of inline MCP. Idempotent
   // on re-run — operator edits are preserved across `aiwg use` invocations.
@@ -435,10 +550,35 @@ export async function deploy(opts) {
   // ── Post-deployment hint ───────────────────────────────────────────────────
   if (!opts.quiet) {
     console.log('');
+    console.log(`Skills root: ${kernelSkillsPath}`);
     console.log('Rules are in AGENTS.md as compressed directives; full bodies via `aiwg show rule <name>`.');
-    console.log('Optional: configure ~/.hermes/config.yaml to connect AIWG MCP server.');
+    console.log('Optional: configure config.yaml to connect AIWG MCP server.');
     console.log('See: docs/integrations/hermes-quickstart.md (optional MCP setup)');
   }
+
+  // ── Consumer visibility check (#2119) ──────────────────────────────────────
+  // The running Hermes runtime reads skills from get_skills_dir(), which is
+  // HERMES_HOME/skills (hermes_constants.get_hermes_home: context-local
+  // override → HERMES_HOME env → $HOME/.hermes). AIWG can observe only ITS
+  // own process environment, so this check reports which root AIWG resolved
+  // and warns when that root may be invisible to a Hermes session the
+  // operator launched elsewhere (custom HERMES_HOME, hermes-role wrapper).
+  //
+  // Before #2119 this was a silent failure: AIWG wrote to $HOME/.hermes/skills
+  // unconditionally and `aiwg status --probe` reported healthy even when the
+  // live session scanned a different HERMES_HOME.
+  if (!dryRun && !opts.quiet) {
+    const envHome = (process.env.HERMES_HOME || '').trim();
+    const hermesActive = Boolean(
+      process.env.HERMES_SESSION_ID ||
+      (process.env.AI_AGENT || '').includes('hermes')
+    );
+    if (hermesActive && !envHome) {
+      console.warn(`Warning: HERMES_HOME is not set in this AIWG process — deployed skills landed under \`${kernelSkillsPath}\` (default $HOME/.hermes).`);
+      console.warn('  If your running Hermes session uses a non-default HERMES_HOME, it CANNOT see these skills.');
+      console.warn('  Re-run with the matching value: HERMES_HOME=<that value> aiwg use --provider hermes');
+    }
+  }
 }
 
 // ============================================================================
@@ -584,7 +724,7 @@ export function migrateLegacySkillPath(opts) {
 // ============================================================================
 
 /**
- * Copy the aiwg-orchestrate skill template to ~/.hermes/skills/ on first
+ * Copy the aiwg-orchestrate skill template to $HERMES_HOME/skills/ on first
  * deploy. Skip if a SKILL.md already exists — preserves operator edits and
  * any prior version they're running. Errors during the copy are non-fatal:
  * the rest of the deploy must succeed even if the home dir is read-only or
@@ -631,7 +771,11 @@ function deployAiwgOrchestrateSkill(srcRoot, opts) {
   try {
     ensureDir(destDir);
     const content = fs.readFileSync(templatePath, 'utf8');
-    fs.writeFileSync(destPath, content, 'utf8');
+    // Defensive: the template is hermes-specific and should not carry a
+    // `platforms:` field (hermes reads that as an OS gate). Strip it if a
+    // future template regression reintroduces one so this orphan path
+    // stays consistent with the main deploy pipeline.
+    fs.writeFileSync(destPath, transformHermesSkillContent(content), 'utf8');
     if (!opts.quiet) {
       console.log(`  Installed aiwg-orchestrate to ${destPath} (delegate_task wrapper, 95% context reduction)`);
     }