@aiwg/cli 2026.8.12 → 2026.8.13

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.12",
+  "version": "2026.8.13",
   "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)`);
     }