pan-wizard 3.8.0 → 3.12.0

package/bin/install.js

@@ -18,9 +18,13 @@ const {
   convertClaudeToOpencodeFrontmatter, convertClaudeToGeminiToml, convertClaudeToGeminiAgent,
   rewriteAskUserQuestionForCopilot, stripSubTags,
   getCodexSkillAdapterHeader, convertClaudeCommandToCodexSkill,
+  convertClaudeCommandToUnifiedSkill,
   getCopilotSkillAdapterHeader, convertClaudeCommandToCopilotSkill, convertClaudeToCopilotAgent,
   processAttribution, parseJsonc,
   detectModelCapabilities, buildClaudeSkillShim, stripThinkingFrontmatter,
+  geminiTransitionNotice,
+  convertClaudeAgentToCodexToml, codexTrustNotice,
+  buildCopilotHooksConfig,
 } = lib;
 
 // Colors
@@ -104,6 +108,18 @@ function getOpencodeGlobalDir() {
  * @param {string} runtime - 'claude', 'opencode', 'gemini', or 'codex'
  * @param {string|null} explicitDir - Explicit directory from --config-dir flag
  */
+/**
+ * Codex skills root. Codex reads skills from the shared `.agents/skills/`
+ * tree — repo scope `$REPO_ROOT/.agents/skills`, user scope `~/.agents/skills`.
+ * `$CODEX_HOME/skills` is NOT a documented read location (verified against
+ * developers.openai.com/codex/skills, 2026-06).
+ */
+function getCodexSkillsRoot(isGlobal) {
+  return isGlobal
+    ? path.join(os.homedir(), '.agents', 'skills')
+    : path.join(process.cwd(), '.agents', 'skills');
+}
+
 function getGlobalDir(runtime, explicitDir = null) {
   if (runtime === 'opencode') {
     // For OpenCode, --config-dir overrides env vars
@@ -195,12 +211,15 @@ function parseConfigDirArg() {
 const explicitConfigDir = parseConfigDirArg();
 const hasHelp = args.includes('--help') || args.includes('-h');
 const forceStatusline = args.includes('--force-statusline');
+// ADR-0028 Phase 1 (opt-in): compile commands once into the shared
+// .agents/skills/ tree for every runtime instead of per-runtime command trees.
+const unifiedSkills = args.includes('--unified-skills');
 
 console.log(banner);
 
 // Show help if requested
 if (hasHelp) {
-  console.log(`  ${yellow}Usage:${reset} npx pan-wizard [options]\n\n  ${yellow}Options:${reset}\n    ${cyan}-l, --local${reset}               Install locally to current directory (default)\n    ${cyan}-g, --global${reset}              Install globally to config directory\n    ${cyan}--claude${reset}                  Install for Claude Code only\n    ${cyan}--opencode${reset}                Install for OpenCode only\n    ${cyan}--gemini${reset}                  Install for Gemini only\n    ${cyan}--codex${reset}                   Install for Codex only\n    ${cyan}--all${reset}                     Install for all runtimes\n    ${cyan}-u, --uninstall${reset}           Uninstall PAN (remove all PAN files)\n    ${cyan}-c, --config-dir <path>${reset}   Specify custom config directory\n    ${cyan}-h, --help${reset}                Show this help message\n    ${cyan}--force-statusline${reset}        Replace existing statusline config\n\n  ${yellow}Examples:${reset}\n    ${dim}# Interactive install (prompts for runtime; installs project-level)${reset}\n    npx pan-wizard\n\n    ${dim}# Install for Claude Code in current project (default, --local implied)${reset}\n    npx pan-wizard --claude\n\n    ${dim}# Install for all runtimes in current project${reset}\n    npx pan-wizard --all --local\n\n    ${dim}# Install globally (available in all projects)${reset}\n    npx pan-wizard --claude --global\n\n    ${dim}# Install for Gemini globally${reset}\n    npx pan-wizard --gemini --global\n\n    ${dim}# Install to custom config directory${reset}\n    npx pan-wizard --codex --global --config-dir ~/.codex-work\n\n    ${dim}# Uninstall PAN from Codex globally${reset}\n    npx pan-wizard --codex --global --uninstall\n\n  ${yellow}Notes:${reset}\n    By default, PAN installs into the current project directory only.\n    Use --global to install system-wide (writes to ~/.claude, ~/.gemini, etc.).\n    The --config-dir option takes priority over CLAUDE_CONFIG_DIR / GEMINI_CONFIG_DIR / CODEX_HOME.\n`);
+  console.log(`  ${yellow}Usage:${reset} npx pan-wizard [options]\n\n  ${yellow}Options:${reset}\n    ${cyan}-l, --local${reset}               Install locally to current directory (default)\n    ${cyan}-g, --global${reset}              Install globally to config directory\n    ${cyan}--claude${reset}                  Install for Claude Code only\n    ${cyan}--opencode${reset}                Install for OpenCode only\n    ${cyan}--gemini${reset}                  Install for Gemini only\n    ${cyan}--codex${reset}                   Install for Codex only\n    ${cyan}--all${reset}                     Install for all runtimes\n    ${cyan}-u, --uninstall${reset}           Uninstall PAN (remove all PAN files)\n    ${cyan}-c, --config-dir <path>${reset}   Specify custom config directory\n    ${cyan}-h, --help${reset}                Show this help message\n    ${cyan}--force-statusline${reset}        Replace existing statusline config\n    ${cyan}--unified-skills${reset}          Install commands as one shared .agents/skills/ tree (ADR-0028 alpha)\n\n  ${yellow}Examples:${reset}\n    ${dim}# Interactive install (prompts for runtime; installs project-level)${reset}\n    npx pan-wizard\n\n    ${dim}# Install for Claude Code in current project (default, --local implied)${reset}\n    npx pan-wizard --claude\n\n    ${dim}# Install for all runtimes in current project${reset}\n    npx pan-wizard --all --local\n\n    ${dim}# Install globally (available in all projects)${reset}\n    npx pan-wizard --claude --global\n\n    ${dim}# Install for Gemini globally${reset}\n    npx pan-wizard --gemini --global\n\n    ${dim}# Install to custom config directory${reset}\n    npx pan-wizard --codex --global --config-dir ~/.codex-work\n\n    ${dim}# Uninstall PAN from Codex globally${reset}\n    npx pan-wizard --codex --global --uninstall\n\n  ${yellow}Notes:${reset}\n    By default, PAN installs into the current project directory only.\n    Use --global to install system-wide (writes to ~/.claude, ~/.gemini, etc.).\n    The --config-dir option takes priority over CLAUDE_CONFIG_DIR / GEMINI_CONFIG_DIR / CODEX_HOME.\n`);
   process.exit(0);
 }
 
@@ -266,8 +285,13 @@ function getCommitAttribution(runtime) {
       result = settings.attribution.commit;
     }
   } else if (runtime === 'copilot') {
-    // Copilot CLI: check config.json for attribution setting
-    const config = readSettings(path.join(getGlobalDir('copilot', explicitConfigDir), 'config.json'));
+    // Copilot CLI: user-editable settings live in settings.json; config.json is
+    // legacy (auto-migrated by the CLI, now internal state) — fall back for old installs
+    const copilotDir = getGlobalDir('copilot', explicitConfigDir);
+    let config = readSettings(path.join(copilotDir, 'settings.json'));
+    if (!config.attribution) {
+      config = readSettings(path.join(copilotDir, 'config.json'));
+    }
     if (!config.attribution || config.attribution.commit === undefined) {
       result = undefined;
     } else if (config.attribution.commit === '') {
@@ -290,11 +314,11 @@ function getCommitAttribution(runtime) {
 
 /**
  * Copy commands to a flat structure for OpenCode
- * OpenCode expects: command/pan-help.md (invoked as /pan-help)
+ * OpenCode expects: commands/pan-help.md (invoked as /pan-help)
  * Source structure: commands/pan/help.md
- * 
+ *
  * @param {string} srcDir - Source directory (e.g., commands/pan/)
- * @param {string} destDir - Destination directory (e.g., command/)
+ * @param {string} destDir - Destination directory (e.g., commands/)
  * @param {string} prefix - Prefix for filenames (e.g., 'pan')
  * @param {string} pathPrefix - Path prefix for file references
  * @param {string} runtime - Target runtime ('claude' or 'opencode')
@@ -308,11 +332,11 @@ function copyFlattenedCommands(srcDir, destDir, prefix, pathPrefix, runtime) {
   if (fs.existsSync(destDir)) {
     for (const file of fs.readdirSync(destDir)) {
       if (file.startsWith(`${prefix}-`) && file.endsWith('.md')) {
-        try { fs.unlinkSync(path.join(destDir, file)); } catch {}
+        try { fs.unlinkSync(path.join(destDir, file)); } catch (err) { pushInstallWarning('staleCleanup', file, err); }
       }
     }
   } else {
-    try { fs.mkdirSync(destDir, { recursive: true }); } catch {}
+    try { fs.mkdirSync(destDir, { recursive: true }); } catch (err) { pushInstallWarning('mkdir', destDir, err); }
   }
   
   const entries = fs.readdirSync(srcDir, { withFileTypes: true });
@@ -360,13 +384,13 @@ function copyCommandsAsCodexSkills(srcDir, skillsDir, prefix, pathPrefix, runtim
     return;
   }
 
-  try { fs.mkdirSync(skillsDir, { recursive: true }); } catch {}
+  try { fs.mkdirSync(skillsDir, { recursive: true }); } catch (err) { pushInstallWarning('mkdir', skillsDir, err); }
 
   // Remove previous PAN Codex skills to avoid stale command skills.
   const existing = fs.readdirSync(skillsDir, { withFileTypes: true });
   for (const entry of existing) {
     if (entry.isDirectory() && entry.name.startsWith(`${prefix}-`)) {
-      try { fs.rmSync(path.join(skillsDir, entry.name), { recursive: true }); } catch {}
+      try { fs.rmSync(path.join(skillsDir, entry.name), { recursive: true }); } catch (err) { pushInstallWarning('staleCleanup', entry.name, err); }
     }
   }
 
@@ -409,6 +433,187 @@ function copyCommandsAsCodexSkills(srcDir, skillsDir, prefix, pathPrefix, runtim
   recurse(srcDir, prefix);
 }
 
+/**
+ * Copy PAN commands as runtime-neutral unified skills (ADR-0028 Phase 1).
+ * Same tree layout as the Codex path (.agents/skills/pan-{name}/SKILL.md) but
+ * the content carries the runtime-neutral adapter so every runtime can consume it.
+ * Core references resolve against the shared .agents/pan-wizard-core/ copy
+ * (Phase 2), so the compiled skills are identical regardless of which runtime
+ * installed them — only the rare agent-file references stay runtime-local.
+ */
+function copyCommandsAsUnifiedSkills(srcDir, skillsDir, prefix, pathPrefix, corePrefix, runtime) {
+  if (!fs.existsSync(srcDir)) {
+    return;
+  }
+
+  try { fs.mkdirSync(skillsDir, { recursive: true }); } catch (err) { pushInstallWarning('mkdir', skillsDir, err); }
+
+  // Remove previous PAN skills to avoid stale command skills.
+  const existing = fs.readdirSync(skillsDir, { withFileTypes: true });
+  for (const entry of existing) {
+    if (entry.isDirectory() && entry.name.startsWith(`${prefix}-`)) {
+      try { fs.rmSync(path.join(skillsDir, entry.name), { recursive: true }); } catch (err) { pushInstallWarning('staleCleanup', entry.name, err); }
+    }
+  }
+
+  function recurse(currentSrcDir, currentPrefix) {
+    const entries = fs.readdirSync(currentSrcDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const srcPath = path.join(currentSrcDir, entry.name);
+      if (entry.isDirectory()) {
+        recurse(srcPath, `${currentPrefix}-${entry.name}`);
+        continue;
+      }
+
+      if (!entry.name.endsWith('.md')) {
+        continue;
+      }
+
+      const baseName = entry.name.replace('.md', '');
+      const skillName = `${currentPrefix}-${baseName}`;
+      const skillDir = path.join(skillsDir, skillName);
+      fs.mkdirSync(skillDir, { recursive: true });
+
+      let content = fs.readFileSync(srcPath, 'utf8');
+      // Core + agent-definition references → shared .agents/ copies (specific,
+      // before the generic rewrites); everything else .claude-scoped → the
+      // installing runtime. Agent refs point at the canonical reference copies
+      // shipped with the shared core — the runtime's own agents dir may carry
+      // a different format (Codex TOML, Copilot .agent.md).
+      content = content.replace(/~\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
+      content = content.replace(/\.\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
+      content = content.replace(/~\/\.claude\/agents\//g, `${corePrefix}pan-wizard-core/agents/`);
+      content = content.replace(/\.\/\.claude\/agents\//g, `${corePrefix}pan-wizard-core/agents/`);
+      content = content.replace(/~\/\.claude\//g, pathPrefix);
+      content = content.replace(/\.\/\.claude\//g, `./${getDirName(runtime)}/`);
+      // Not every runtime puts a `pan-tools` bin on PATH — invoke via node.
+      const panToolsPath = `${corePrefix}pan-wizard-core/bin/pan-tools.cjs`;
+      content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${panToolsPath}`);
+      content = processAttribution(content, getCommitAttribution(runtime));
+      content = convertClaudeCommandToUnifiedSkill(content, skillName);
+
+      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
+    }
+  }
+
+  recurse(srcDir, prefix);
+}
+
+/**
+ * Remove a runtime's proprietary command surface after a --unified-skills
+ * install so commands don't resolve twice (ADR-0028 Phase 1 sweep).
+ */
+function sweepProprietaryCommandSurfaces(targetDir, runtime) {
+  if (runtime === 'opencode') {
+    for (const dirName of ['commands', 'command']) {
+      const commandDir = path.join(targetDir, dirName);
+      try {
+        for (const file of fs.readdirSync(commandDir)) {
+          if (file.startsWith('pan-') && file.endsWith('.md')) {
+            try { fs.unlinkSync(path.join(commandDir, file)); } catch {}
+          }
+        }
+      } catch { /* dir absent — nothing to sweep */ }
+    }
+  } else if (runtime === 'copilot') {
+    const skillsDir = path.join(targetDir, 'skills');
+    try {
+      for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name.startsWith('pan-')) {
+          try { fs.rmSync(path.join(skillsDir, entry.name), { recursive: true }); } catch {}
+        }
+      }
+    } catch { /* dir absent — nothing to sweep */ }
+  } else if (runtime === 'codex') {
+    // Legacy .codex/skills location (dead read path; swept on upgrade anyway)
+    const legacySkillsDir = path.join(targetDir, 'skills');
+    try {
+      for (const entry of fs.readdirSync(legacySkillsDir, { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name.startsWith('pan-')) {
+          try { fs.rmSync(path.join(legacySkillsDir, entry.name), { recursive: true }); } catch {}
+        }
+      }
+    } catch { /* dir absent — nothing to sweep */ }
+  } else {
+    // Claude Code & Gemini: nested commands/pan tree (+ Claude skill shims)
+    try { fs.rmSync(path.join(targetDir, 'commands', 'pan'), { recursive: true }); } catch {}
+    if (runtime === 'claude') {
+      const skillsDir = path.join(targetDir, 'skills');
+      try {
+        for (const file of fs.readdirSync(skillsDir)) {
+          if (file.startsWith('pan-') && file.endsWith('.md')) {
+            try { fs.unlinkSync(path.join(skillsDir, file)); } catch {}
+          }
+        }
+      } catch { /* dir absent — nothing to sweep */ }
+    }
+  }
+}
+
+/**
+ * Copy pan-wizard-core into the shared .agents/ root for unified installs
+ * (ADR-0028 Phase 2). Core-internal references resolve against the shared
+ * prefix, so the copy is runtime-neutral and rewrites across runtimes are
+ * idempotent; the few non-core references (agent files, cache paths) resolve
+ * against the installing runtime. Skill mentions are normalized to the
+ * neutral /pan-{name} form to match the unified SKILL.md content.
+ */
+function copySharedCore(srcDir, destDir, corePrefix, runtimePathPrefix, runtime) {
+  try {
+    if (fs.existsSync(destDir)) {
+      fs.rmSync(destDir, { recursive: true });
+    }
+    fs.mkdirSync(destDir, { recursive: true });
+  } catch (err) {
+    throw new Error(`copySharedCore: cannot prepare ${destDir}: ${err.message}`);
+  }
+
+  const dirName = getDirName(runtime);
+
+  (function recurse(currentSrc, currentDest) {
+    for (const entry of fs.readdirSync(currentSrc, { withFileTypes: true })) {
+      const srcPath = path.join(currentSrc, entry.name);
+      const destPath = path.join(currentDest, entry.name);
+
+      if (entry.isDirectory()) {
+        try { fs.mkdirSync(destPath, { recursive: true }); } catch (err) { pushInstallWarning('copySharedCore(mkdir)', destPath, err); }
+        recurse(srcPath, destPath);
+      } else if (entry.name.endsWith('.md')) {
+        try {
+          let content = fs.readFileSync(srcPath, 'utf8');
+          content = content.replace(/~\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
+          content = content.replace(/\.\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
+          // Agent-definition refs → the canonical reference copies in the
+          // shared core (runtime agents dirs carry runtime-specific formats).
+          content = content.replace(/~\/\.claude\/agents\//g, `${corePrefix}pan-wizard-core/agents/`);
+          content = content.replace(/\.\/\.claude\/agents\//g, `${corePrefix}pan-wizard-core/agents/`);
+          content = content.replace(/~\/\.claude\//g, runtimePathPrefix);
+          content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
+          content = processAttribution(content, getCommitAttribution(runtime));
+          content = convertSlashCommandsToCopilotSkillMentions(content);
+          fs.writeFileSync(destPath, content);
+        } catch (err) {
+          pushInstallWarning('copySharedCore(md)', destPath, err);
+        }
+      } else {
+        try {
+          fs.copyFileSync(srcPath, destPath);
+        } catch (err) {
+          pushInstallWarning('copySharedCore(copy)', destPath, err);
+        }
+      }
+    }
+  })(srcDir, destDir);
+
+  // learnings/internal is source-only — strip it like the per-runtime copy does
+  try {
+    fs.rmSync(path.join(destDir, 'learnings', 'internal'), { recursive: true, force: true });
+  } catch (err) {
+    if (err.code !== 'ENOENT') pushInstallWarning('stripInternalLearnings', 'learnings/internal', err);
+  }
+}
+
 /**
  * Copy PAN commands as Copilot CLI skills.
  * Creates skills/pan-{name}/SKILL.md directory structure.
@@ -419,13 +624,13 @@ function copyCommandsAsCopilotSkills(srcDir, skillsDir, prefix, pathPrefix, runt
     return;
   }
 
-  try { fs.mkdirSync(skillsDir, { recursive: true }); } catch {}
+  try { fs.mkdirSync(skillsDir, { recursive: true }); } catch (err) { pushInstallWarning('mkdir', skillsDir, err); }
 
   // Remove previous PAN Copilot skills to avoid stale command skills
   const existing = fs.readdirSync(skillsDir, { withFileTypes: true });
   for (const entry of existing) {
     if (entry.isDirectory() && entry.name.startsWith(`${prefix}-`)) {
-      try { fs.rmSync(path.join(skillsDir, entry.name), { recursive: true }); } catch {}
+      try { fs.rmSync(path.join(skillsDir, entry.name), { recursive: true }); } catch (err) { pushInstallWarning('staleCleanup', entry.name, err); }
     }
   }
 
@@ -670,25 +875,54 @@ function uninstall(isGlobal, runtime = 'claude') {
 
   let removedCount = 0;
 
+  // ADR-0028 Phase 2 ref-counting: another runtime still tracking the shared
+  // .agents tree (manifest keys reaching outside its config dir) keeps the
+  // tree alive when this runtime uninstalls.
+  function otherRuntimeTrackingShared(currentRuntime) {
+    const others = ['claude', 'codex', 'gemini', 'opencode', 'copilot']
+      .filter(r => r !== currentRuntime);
+    for (const rt of others) {
+      const dir = isGlobal
+        ? getGlobalDir(rt, null)
+        : path.join(process.cwd(), getDirName(rt));
+      try {
+        const m = JSON.parse(fs.readFileSync(path.join(dir, MANIFEST_NAME), 'utf8'));
+        if (Object.keys(m.files || {}).some(k => k.startsWith('../'))) return rt;
+      } catch { /* no manifest for that runtime */ }
+    }
+    return null;
+  }
+
   // 1. Remove PAN commands/skills
   if (isOpencode) {
-    // OpenCode: remove command/pan-*.md files
-    const commandDir = path.join(targetDir, 'command');
-    if (fs.existsSync(commandDir)) {
-      const files = fs.readdirSync(commandDir);
-      for (const file of files) {
-        if (file.startsWith('pan-') && file.endsWith('.md')) {
-          try { fs.unlinkSync(path.join(commandDir, file)); } catch {}
-          removedCount++;
+    // OpenCode: remove commands/pan-*.md files (plus legacy singular command/
+    // left by pre-plural installs).
+    for (const dirName of ['commands', 'command']) {
+      const commandDir = path.join(targetDir, dirName);
+      if (fs.existsSync(commandDir)) {
+        const files = fs.readdirSync(commandDir);
+        let removedHere = 0;
+        for (const file of files) {
+          if (file.startsWith('pan-') && file.endsWith('.md')) {
+            try { fs.unlinkSync(path.join(commandDir, file)); } catch {}
+            removedCount++;
+            removedHere++;
+          }
+        }
+        if (removedHere > 0) {
+          console.log(`  ${green}✓${reset} Removed PAN commands from ${dirName}/`);
         }
       }
-      console.log(`  ${green}✓${reset} Removed PAN commands from command/`);
     }
   } else if (isCodex || isCopilot) {
-    // Codex & Copilot CLI: remove skills/pan-*/SKILL.md skill directories
-    const skillsDir = path.join(targetDir, 'skills');
-    if (fs.existsSync(skillsDir)) {
-      let skillCount = 0;
+    // Codex & Copilot CLI: remove skills/pan-*/SKILL.md skill directories from
+    // the runtime-local locations. The shared .agents/skills tree (Codex's
+    // primary surface, plus any --unified-skills install) is handled by the
+    // ref-counted sweep below.
+    const skillDirs = [path.join(targetDir, 'skills')];
+    let skillCount = 0;
+    for (const skillsDir of skillDirs) {
+      if (!fs.existsSync(skillsDir)) continue;
       const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.isDirectory() && entry.name.startsWith('pan-')) {
@@ -696,10 +930,10 @@ function uninstall(isGlobal, runtime = 'claude') {
           skillCount++;
         }
       }
-      if (skillCount > 0) {
-        removedCount++;
-        console.log(`  ${green}✓${reset} Removed ${skillCount} ${isCopilot ? 'Copilot CLI' : 'Codex'} skills`);
-      }
+    }
+    if (skillCount > 0) {
+      removedCount++;
+      console.log(`  ${green}✓${reset} Removed ${skillCount} ${isCopilot ? 'Copilot CLI' : 'Codex'} skills`);
     }
   } else {
     // Claude Code & Gemini: remove commands/pan/ directory
@@ -733,6 +967,57 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
   }
 
+  // ADR-0028 unified tree: sweep the shared .agents tree when this runtime
+  // tracks it (manifest ../ keys; Codex always uses it) AND no other runtime
+  // still does (Phase 2 ref-counting). The last tracker also removes the
+  // shared core and prunes empty .agents directories.
+  {
+    let manifestHasShared = false;
+    try {
+      const m = JSON.parse(fs.readFileSync(path.join(targetDir, MANIFEST_NAME), 'utf8'));
+      manifestHasShared = Object.keys(m.files || {}).some(k => k.startsWith('../'));
+    } catch { /* no manifest — nothing tracked out-of-tree */ }
+
+    if (isCodex || manifestHasShared) {
+      const stillTracking = otherRuntimeTrackingShared(runtime);
+      if (stillTracking) {
+        console.log(`  ${dim}ℹ Shared .agents/skills left in place — still tracked by ${stillTracking}${reset}`);
+      } else {
+        const sharedDir = getCodexSkillsRoot(isGlobal);
+        let sharedCount = 0;
+        try {
+          for (const entry of fs.readdirSync(sharedDir, { withFileTypes: true })) {
+            if (entry.isDirectory() && entry.name.startsWith('pan-')) {
+              try { fs.rmSync(path.join(sharedDir, entry.name), { recursive: true }); } catch {}
+              sharedCount++;
+            }
+          }
+        } catch { /* shared tree absent */ }
+        if (sharedCount > 0) {
+          removedCount++;
+          console.log(`  ${green}✓${reset} Removed ${sharedCount} unified skills from .agents/skills/`);
+        }
+        // Shared core ships only with --unified-skills installs; remove it
+        // alongside the last tracked skills sweep.
+        const agentsRoot = path.dirname(sharedDir);
+        const sharedCore = path.join(agentsRoot, 'pan-wizard-core');
+        if (fs.existsSync(sharedCore)) {
+          try {
+            fs.rmSync(sharedCore, { recursive: true });
+            removedCount++;
+            console.log(`  ${green}✓${reset} Removed shared pan-wizard-core from .agents/`);
+          } catch { /* best-effort */ }
+        }
+        // Prune now-empty shared directories (never directories with foreign content)
+        for (const dir of [sharedDir, agentsRoot]) {
+          try {
+            if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+          } catch { /* non-empty or absent — keep */ }
+        }
+      }
+    }
+  }
+
   // 2. Remove pan-wizard-core directory
   const panDir = path.join(targetDir, 'pan-wizard-core');
   if (fs.existsSync(panDir)) {
@@ -741,13 +1026,13 @@ function uninstall(isGlobal, runtime = 'claude') {
     console.log(`  ${green}✓${reset} Removed pan-wizard-core/`);
   }
 
-  // 3. Remove PAN agents (pan-*.md files only)
+  // 3. Remove PAN agents (pan-*.md / pan-*.agent.md / pan-*.toml files only)
   const agentsDir = path.join(targetDir, 'agents');
   if (fs.existsSync(agentsDir)) {
     const files = fs.readdirSync(agentsDir);
     let agentCount = 0;
     for (const file of files) {
-      if (file.startsWith('pan-') && file.endsWith('.md')) {
+      if (file.startsWith('pan-') && (file.endsWith('.md') || file.endsWith('.toml'))) {
         try { fs.unlinkSync(path.join(agentsDir, file)); } catch {}
         agentCount++;
       }
@@ -758,10 +1043,10 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
   }
 
-  // 4. Remove PAN hooks
+  // 4. Remove PAN hooks (scripts + Copilot CLI hooks config file)
   const hooksDir = path.join(targetDir, 'hooks');
   if (fs.existsSync(hooksDir)) {
-    const panHooks = ['pan-statusline.js', 'pan-check-update.js', 'pan-check-update.sh', 'pan-context-monitor.js', 'pan-cost-logger.js', 'pan-trace-logger.js'];
+    const panHooks = ['pan-statusline.js', 'pan-check-update.js', 'pan-check-update.sh', 'pan-context-monitor.js', 'pan-cost-logger.js', 'pan-trace-logger.js', 'pan.json'];
     let hookCount = 0;
     for (const hook of panHooks) {
       const hookPath = path.join(hooksDir, hook);
@@ -776,6 +1061,44 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
   }
 
+  // 4a. Remove native workflow scripts (Claude-only surface)
+  const workflowsDir = path.join(targetDir, 'workflows');
+  if (fs.existsSync(workflowsDir)) {
+    let wfCount = 0;
+    for (const file of fs.readdirSync(workflowsDir)) {
+      if (file.startsWith('pan-') && file.endsWith('.js')) {
+        try { fs.unlinkSync(path.join(workflowsDir, file)); } catch {}
+        wfCount++;
+      }
+    }
+    if (wfCount > 0) {
+      removedCount++;
+      console.log(`  ${green}✓${reset} Removed ${wfCount} native workflows`);
+    }
+  }
+
+  // 4b. Codex: strip PAN entries from the shared .codex/hooks.json (foreign
+  // hook registrations are preserved; the file is deleted only when nothing
+  // but PAN content remained).
+  if (isCodex) {
+    const hooksJsonPath = path.join(targetDir, 'hooks.json');
+    try {
+      const rawText = fs.readFileSync(hooksJsonPath, 'utf8');
+      const before = JSON.stringify(JSON.parse(rawText));
+      // removeCodexPanHooks mutates its argument — parse a fresh copy for it.
+      const stripped = lib.removeCodexPanHooks(JSON.parse(rawText));
+      if (stripped === null) {
+        fs.unlinkSync(hooksJsonPath);
+        removedCount++;
+        console.log(`  ${green}✓${reset} Removed hooks.json (only PAN hooks remained)`);
+      } else if (JSON.stringify(stripped) !== before) {
+        fs.writeFileSync(hooksJsonPath, JSON.stringify(stripped, null, 2) + '\n');
+        removedCount++;
+        console.log(`  ${green}✓${reset} Removed PAN hooks from hooks.json`);
+      }
+    } catch { /* absent or unparseable — nothing to strip */ }
+  }
+
   // 5. Remove PAN package.json (CommonJS mode marker)
   const pkgJsonPath = path.join(targetDir, 'package.json');
   if (fs.existsSync(pkgJsonPath)) {
@@ -856,6 +1179,35 @@ function uninstall(isGlobal, runtime = 'claude') {
         // Ignore JSON parse errors
       }
     }
+
+    // Clean PAN statusline from the documented settings read paths:
+    // settings.json (global ~/.copilot/) and copilot/settings.json (.github/).
+    for (const { settingsPath, removableDir } of [
+      { settingsPath: path.join(targetDir, 'settings.json'), removableDir: false },
+      { settingsPath: path.join(targetDir, 'copilot', 'settings.json'), removableDir: true },
+    ]) {
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        if (settings.statusLine && settings.statusLine.command &&
+            settings.statusLine.command.includes('pan-statusline')) {
+          delete settings.statusLine;
+          if (Object.keys(settings).length === 0) {
+            fs.unlinkSync(settingsPath);
+            if (removableDir) {
+              // Only the nested .github/copilot/ dir PAN may have created —
+              // never the user's ~/.copilot home.
+              try { fs.rmdirSync(path.dirname(settingsPath)); } catch { /* non-empty — keep */ }
+            }
+          } else {
+            fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+          }
+          console.log(`  ${green}✓${reset} Removed PAN statusline from settings`);
+          removedCount++;
+        }
+      } catch {
+        // Missing file or parse error — nothing to clean
+      }
+    }
   }
 
   // 6b. Clean up settings.json (remove PAN hooks and statusline)
@@ -916,6 +1268,27 @@ function uninstall(isGlobal, runtime = 'claude') {
       }
     }
 
+    // Remove PAN hooks from SubagentStop (cost logger v3.4+, trace logger v3.5+)
+    if (settings.hooks && settings.hooks.SubagentStop) {
+      const before = settings.hooks.SubagentStop.length;
+      settings.hooks.SubagentStop = settings.hooks.SubagentStop.filter(entry => {
+        if (entry.hooks && Array.isArray(entry.hooks)) {
+          const hasPanHook = entry.hooks.some(h =>
+            h.command && (h.command.includes('pan-cost-logger') || h.command.includes('pan-trace-logger'))
+          );
+          return !hasPanHook;
+        }
+        return true;
+      });
+      if (settings.hooks.SubagentStop.length < before) {
+        settingsModified = true;
+        console.log(`  ${green}✓${reset} Removed cost/trace logger hooks from settings`);
+      }
+      if (settings.hooks.SubagentStop.length === 0) {
+        delete settings.hooks.SubagentStop;
+      }
+    }
+
     // Clean up empty hooks object
     if (settings.hooks && Object.keys(settings.hooks).length === 0) {
       delete settings.hooks;
@@ -997,13 +1370,42 @@ function uninstall(isGlobal, runtime = 'claude') {
     console.log(`  ${green}✓${reset} Removed ${MANIFEST_NAME}`);
   }
 
+  // 7b. AGENTS.md / CLAUDE.md rules layer (ADR-0028 Phase 3): strip the PAN
+  // marker block when this was the last PAN runtime in the project (the
+  // manifest scan runs AFTER this runtime's manifest was removed above, so
+  // any hit means another runtime still needs the section). Local only.
+  if (!isGlobal) {
+    const anotherRuntimeInstalled = ['.claude', '.codex', '.gemini', '.opencode', '.github']
+      .some(d => fs.existsSync(path.join(process.cwd(), d, MANIFEST_NAME)));
+    if (!anotherRuntimeInstalled) {
+      for (const fileName of ['AGENTS.md', 'CLAUDE.md']) {
+        const filePath = path.join(process.cwd(), fileName);
+        try {
+          const existing = fs.readFileSync(filePath, 'utf8');
+          const stripped = lib.removeAgentsMdSection(existing);
+          if (stripped === existing) continue; // no PAN block — leave untouched
+          if (stripped === null) {
+            fs.unlinkSync(filePath);
+            console.log(`  ${green}✓${reset} Removed ${fileName} (only the PAN section remained)`);
+          } else {
+            fs.writeFileSync(filePath, stripped);
+            console.log(`  ${green}✓${reset} Removed PAN section from ${fileName}`);
+          }
+          removedCount++;
+        } catch { /* file absent — nothing to strip */ }
+      }
+    }
+  }
+
   // 8. Clean up empty PAN directories
   const dirsToClean = [
     path.join(targetDir, 'agents'),
     path.join(targetDir, 'hooks'),
     path.join(targetDir, 'skills'),
+    path.join(targetDir, 'workflows'),
     path.join(targetDir, 'commands', 'pan'),
     path.join(targetDir, 'commands'),
+    path.join(targetDir, 'command'), // legacy OpenCode singular dir
   ];
   for (const dir of dirsToClean) {
     try {
@@ -1183,14 +1585,23 @@ function generateManifest(dir, baseDir) {
 /**
  * Write file manifest after installation for future modification detection
  */
-function writeManifest(configDir, runtime = 'claude') {
+function writeManifest(configDir, runtime = 'claude', isGlobal = false) {
   const isOpencode = runtime === 'opencode';
   const isCodex = runtime === 'codex';
   const isCopilot = runtime === 'copilot';
   const panDir = path.join(configDir, 'pan-wizard-core');
   const commandsDir = path.join(configDir, 'commands', 'pan');
-  const opencodeCommandDir = path.join(configDir, 'command');
-  const codexSkillsDir = path.join(configDir, 'skills');
+  const opencodeCommandDir = path.join(configDir, 'commands');
+  // Codex skills (and every runtime under --unified-skills, ADR-0028) live in
+  // the shared .agents/skills tree (outside configDir); Copilot otherwise uses
+  // configDir/skills. Out-of-tree manifest keys are stored relative to
+  // configDir (e.g. "../.agents/skills/...") so existing
+  // path.join(configDir, key) consumers resolve them.
+  const skillsShared = isCodex || unifiedSkills;
+  const codexSkillsDir = skillsShared ? getCodexSkillsRoot(isGlobal) : path.join(configDir, 'skills');
+  const codexSkillsPrefix = skillsShared
+    ? path.relative(configDir, codexSkillsDir).replace(/\\/g, '/')
+    : 'skills';
   const agentsDir = path.join(configDir, 'agents');
   const manifest = { version: pkg.version, timestamp: new Date().toISOString(), files: {} };
 
@@ -1198,31 +1609,31 @@ function writeManifest(configDir, runtime = 'claude') {
   for (const [rel, hash] of Object.entries(panHashes)) {
     manifest.files['pan-wizard-core/' + rel] = hash;
   }
-  if (!isOpencode && !isCodex && fs.existsSync(commandsDir)) {
+  if (!isOpencode && !isCodex && !unifiedSkills && fs.existsSync(commandsDir)) {
     const cmdHashes = generateManifest(commandsDir);
     for (const [rel, hash] of Object.entries(cmdHashes)) {
       manifest.files['commands/pan/' + rel] = hash;
     }
   }
-  if (isOpencode && fs.existsSync(opencodeCommandDir)) {
+  if (isOpencode && !unifiedSkills && fs.existsSync(opencodeCommandDir)) {
     for (const file of fs.readdirSync(opencodeCommandDir)) {
       if (file.startsWith('pan-') && file.endsWith('.md')) {
-        manifest.files['command/' + file] = fileHash(path.join(opencodeCommandDir, file));
+        manifest.files['commands/' + file] = fileHash(path.join(opencodeCommandDir, file));
       }
     }
   }
-  if ((isCodex || isCopilot) && fs.existsSync(codexSkillsDir)) {
+  if ((isCodex || isCopilot || unifiedSkills) && fs.existsSync(codexSkillsDir)) {
     for (const skillName of listCodexSkillNames(codexSkillsDir)) {
       const skillRoot = path.join(codexSkillsDir, skillName);
       const skillHashes = generateManifest(skillRoot);
       for (const [rel, hash] of Object.entries(skillHashes)) {
-        manifest.files[`skills/${skillName}/${rel}`] = hash;
+        manifest.files[`${codexSkillsPrefix}/${skillName}/${rel}`] = hash;
       }
     }
   }
   if (fs.existsSync(agentsDir)) {
     for (const file of fs.readdirSync(agentsDir)) {
-      if (file.startsWith('pan-') && file.endsWith('.md')) {
+      if (file.startsWith('pan-') && (file.endsWith('.md') || file.endsWith('.toml'))) {
         manifest.files['agents/' + file] = fileHash(path.join(agentsDir, file));
       }
     }
@@ -1236,6 +1647,15 @@ function writeManifest(configDir, runtime = 'claude') {
       }
     }
   }
+  // Track native workflow scripts (Claude-only surface)
+  const workflowsDir = path.join(configDir, 'workflows');
+  if (fs.existsSync(workflowsDir)) {
+    for (const file of fs.readdirSync(workflowsDir)) {
+      if (file.startsWith('pan-') && file.endsWith('.js')) {
+        manifest.files['workflows/' + file] = fileHash(path.join(workflowsDir, file));
+      }
+    }
+  }
 
   try {
     fs.writeFileSync(path.join(configDir, MANIFEST_NAME), JSON.stringify(manifest, null, 2));
@@ -1260,6 +1680,11 @@ function saveLocalPatches(configDir) {
   const modified = [];
 
   for (const [relPath, originalHash] of Object.entries(manifest.files || {})) {
+    // Keys reaching outside configDir (Codex skills in ../.agents/skills/)
+    // can't be backed up under patchesDir — path.join would collapse the
+    // `..` and write outside the patches tree. Skip them; they're still
+    // overwritten cleanly on reinstall.
+    if (relPath.split('/').includes('..')) continue;
     const fullPath = path.join(configDir, relPath);
     if (!fs.existsSync(fullPath)) continue;
     const currentHash = fileHash(fullPath);
@@ -1378,31 +1803,108 @@ function install(isGlobal, runtime = 'claude') {
   // Clean up orphaned files from previous versions
   cleanupOrphanedFiles(targetDir);
 
-  // OpenCode uses command/ (flat), Codex uses skills/, Claude/Gemini use commands/pan/
+  // OpenCode uses commands/ (flat), Codex uses skills/, Claude/Gemini use commands/pan/
   try {
-    if (isOpencode) {
-      // OpenCode: flat structure in command/ directory
-      const commandDir = path.join(targetDir, 'command');
+    if (unifiedSkills) {
+      // ADR-0028 Phase 1: every runtime consumes one runtime-neutral
+      // .agents/skills/ tree; the proprietary command surface is swept so
+      // commands don't resolve twice.
+      const skillsDir = getCodexSkillsRoot(isGlobal);
+      const agentsRoot = path.dirname(skillsDir);
+      const corePrefix = isGlobal
+        ? `${agentsRoot.replace(/\\/g, '/')}/`
+        : './.agents/';
+
+      // ADR-0028 Phase 2: shared runtime-neutral core. Skills resolve
+      // pan-tools against this copy regardless of which runtime installed
+      // last; the per-runtime core remains for agents/hooks.
+      const sharedCoreDest = path.join(agentsRoot, 'pan-wizard-core');
+      copySharedCore(path.join(src, 'pan-wizard-core'), sharedCoreDest, corePrefix, pathPrefix, runtime);
+      try { fs.writeFileSync(path.join(sharedCoreDest, 'VERSION'), pkg.version); } catch { /* non-fatal */ }
+
+      // Canonical agent-definition reference copies (ADR-0028 agent-ref
+      // canonicalization): shared content references these instead of the
+      // runtime's agents dir, whose files carry runtime-specific formats.
+      // These are reading material for agents, not runtime registrations —
+      // the per-runtime installed agents still drive subagent spawning.
+      try {
+        const agentsRefDir = path.join(sharedCoreDest, 'agents');
+        fs.mkdirSync(agentsRefDir, { recursive: true });
+        const agentsSrc = path.join(src, 'agents');
+        for (const f of fs.readdirSync(agentsSrc).filter(n => n.endsWith('.md'))) {
+          let content = fs.readFileSync(path.join(agentsSrc, f), 'utf8');
+          content = content.replace(/~\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
+          content = content.replace(/\.\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
+          content = convertSlashCommandsToCopilotSkillMentions(content);
+          fs.writeFileSync(path.join(agentsRefDir, f), content);
+        }
+      } catch (e) {
+        pushInstallWarning('unifiedAgentRefs', 'pan-wizard-core/agents', e);
+      }
+      console.log(`  ${green}✓${reset} Installed shared pan-wizard-core to ${isGlobal ? '~/.agents/' : '.agents/'}`);
+
+      const panSrc = path.join(src, 'commands', 'pan');
+      copyCommandsAsUnifiedSkills(panSrc, skillsDir, 'pan', pathPrefix, corePrefix, runtime);
+      sweepProprietaryCommandSurfaces(targetDir, runtime);
+
+      const installedSkillNames = listCodexSkillNames(skillsDir);
+      if (installedSkillNames.length > 0) {
+        const label = isGlobal ? '~/.agents/skills/' : '.agents/skills/';
+        console.log(`  ${green}✓${reset} Installed ${installedSkillNames.length} unified skills to ${label} (ADR-0028)`);
+      } else {
+        failures.push('.agents/skills/pan-* (unified)');
+      }
+    } else if (isOpencode) {
+      // OpenCode: flat structure in commands/ directory. Plural since
+      // OpenCode 2026 releases — singular command/ is back-compat only.
+      const commandDir = path.join(targetDir, 'commands');
       fs.mkdirSync(commandDir, { recursive: true });
 
-      // Copy commands/pan/*.md as command/pan-*.md (flatten structure)
+      // Copy commands/pan/*.md as commands/pan-*.md (flatten structure)
       const panSrc = path.join(src, 'commands', 'pan');
       copyFlattenedCommands(panSrc, commandDir, 'pan', pathPrefix, runtime);
-      if (verifyInstalled(commandDir, 'command/pan-*')) {
+
+      // Upgrade path: remove PAN files left in the legacy singular command/
+      // directory by older installs so commands don't resolve twice.
+      const legacyCommandDir = path.join(targetDir, 'command');
+      if (fs.existsSync(legacyCommandDir)) {
+        for (const file of fs.readdirSync(legacyCommandDir)) {
+          if (file.startsWith('pan-') && file.endsWith('.md')) {
+            try { fs.unlinkSync(path.join(legacyCommandDir, file)); } catch {}
+          }
+        }
+      }
+
+      if (verifyInstalled(commandDir, 'commands/pan-*')) {
         const count = fs.readdirSync(commandDir).filter(f => f.startsWith('pan-')).length;
-        console.log(`  ${green}✓${reset} Installed ${count} commands to command/`);
+        console.log(`  ${green}✓${reset} Installed ${count} commands to commands/`);
       } else {
-        failures.push('command/pan-*');
+        failures.push('commands/pan-*');
       }
     } else if (isCodex) {
-      const skillsDir = path.join(targetDir, 'skills');
+      // Codex reads skills from the shared .agents/skills tree (repo or user
+      // scope) — $CODEX_HOME/skills is no longer a read location (2026-06).
+      const skillsDir = getCodexSkillsRoot(isGlobal);
       const panSrc = path.join(src, 'commands', 'pan');
       copyCommandsAsCodexSkills(panSrc, skillsDir, 'pan', pathPrefix, runtime);
+
+      // Upgrade path: remove pan-* skills left in the legacy .codex/skills/
+      // location by older installs (dead directory for current Codex).
+      const legacySkillsDir = path.join(targetDir, 'skills');
+      if (fs.existsSync(legacySkillsDir)) {
+        for (const entry of fs.readdirSync(legacySkillsDir, { withFileTypes: true })) {
+          if (entry.isDirectory() && entry.name.startsWith('pan-')) {
+            try { fs.rmSync(path.join(legacySkillsDir, entry.name), { recursive: true }); } catch {}
+          }
+        }
+      }
+
       const installedSkillNames = listCodexSkillNames(skillsDir);
       if (installedSkillNames.length > 0) {
-        console.log(`  ${green}✓${reset} Installed ${installedSkillNames.length} skills to skills/`);
+        const label = isGlobal ? '~/.agents/skills/' : '.agents/skills/';
+        console.log(`  ${green}✓${reset} Installed ${installedSkillNames.length} skills to ${label}`);
       } else {
-        failures.push('skills/pan-*');
+        failures.push('.agents/skills/pan-*');
       }
     } else if (isCopilot) {
       const skillsDir = path.join(targetDir, 'skills');
@@ -1474,8 +1976,9 @@ function install(isGlobal, runtime = 'claude') {
     if (fs.existsSync(internalLearningsDir)) {
       try {
         fs.rmSync(internalLearningsDir, { recursive: true, force: true });
-      } catch {
-        // Best-effort: install proceeds even if cleanup fails
+      } catch (err) {
+        // Surface it: a failed strip would ship source-only internal learnings.
+        if (err.code !== 'ENOENT') pushInstallWarning('stripInternalLearnings', 'learnings/internal', err);
       }
     }
 
@@ -1496,10 +1999,10 @@ function install(isGlobal, runtime = 'claude') {
       const agentsDest = path.join(targetDir, 'agents');
       fs.mkdirSync(agentsDest, { recursive: true });
 
-      // Remove old PAN agents (pan-*.md and pan-*.agent.md) before copying new ones
+      // Remove old PAN agents (pan-*.md, pan-*.agent.md, pan-*.toml) before copying new ones
       if (fs.existsSync(agentsDest)) {
         for (const file of fs.readdirSync(agentsDest)) {
-          if (file.startsWith('pan-') && file.endsWith('.md')) {
+          if (file.startsWith('pan-') && (file.endsWith('.md') || file.endsWith('.toml'))) {
             fs.unlinkSync(path.join(agentsDest, file));
           }
         }
@@ -1514,6 +2017,18 @@ function install(isGlobal, runtime = 'claude') {
           const dirRegex = /~\/\.claude\//g;
           content = content.replace(dirRegex, pathPrefix);
           content = processAttribution(content, getCommitAttribution(runtime));
+          // Codex custom agents are standalone TOML files (2026-06 format);
+          // markdown in .codex/agents/ is not recognized. Handle before
+          // stripThinkingFrontmatter so `effort:` survives to be mapped to
+          // Codex's native model_reasoning_effort field.
+          if (isCodex) {
+            const toml = convertClaudeAgentToCodexToml(stripSubTags(content));
+            if (toml) {
+              const tomlName = entry.name.replace(/\.md$/, '.toml');
+              fs.writeFileSync(path.join(agentsDest, tomlName), toml);
+            }
+            continue;
+          }
           // E-3 (per-runtime): strip unsupported thinking frontmatter and inject
           // prose preamble for runtimes without native extended thinking.
           content = stripThinkingFrontmatter(content, runtime);
@@ -1522,8 +2037,6 @@ function install(isGlobal, runtime = 'claude') {
             content = convertClaudeToOpencodeFrontmatter(content);
           } else if (isGemini) {
             content = convertClaudeToGeminiAgent(content);
-          } else if (isCodex) {
-            content = convertClaudeToCodexMarkdown(content);
           } else if (isCopilot) {
             content = convertClaudeToCopilotAgent(content);
           }
@@ -1599,9 +2112,10 @@ function install(isGlobal, runtime = 'claude') {
     }
   }
 
-  if (!isCodex && !isOpencode) {
+  if (!isOpencode) {
     // Copy hooks from dist/ (bundled with dependencies)
-    // Hooks are only supported by Claude Code, Gemini, and Copilot CLI
+    // Hooks are supported by Claude Code, Gemini, Copilot CLI, and (since
+    // 2026-06) Codex via .codex/hooks.json. OpenCode has no hook support.
     // Template paths for the target runtime (replaces '.claude' with correct config dir)
     try {
       const hooksSrc = path.join(src, 'hooks', 'dist');
@@ -1636,15 +2150,60 @@ function install(isGlobal, runtime = 'claude') {
     }
   }
 
+  // Native Claude Code workflows (2026-06): deterministic orchestration
+  // scripts for PAN's fan-out-shaped protocols. Claude-only — no other
+  // runtime has an equivalent discovery surface.
+  if (runtime === 'claude') {
+    try {
+      const workflowsDir = path.join(targetDir, 'workflows');
+      fs.mkdirSync(workflowsDir, { recursive: true });
+      const scripts = lib.buildNativeWorkflowScripts();
+      for (const { name, content } of scripts) {
+        fs.writeFileSync(path.join(workflowsDir, name), content);
+      }
+      console.log(`  ${green}✓${reset} Installed ${scripts.length} native workflows to workflows/`);
+    } catch (e) {
+      pushInstallWarning('nativeWorkflows', 'workflows/pan-*', e);
+    }
+  }
+
   if (failures.length > 0) {
     console.error(`\n  ${yellow}Installation incomplete!${reset} Failed: ${failures.join(', ')}`);
     process.exit(1);
   }
 
   // Write file manifest for future modification detection
-  const manifest = writeManifest(targetDir, runtime);
+  const manifest = writeManifest(targetDir, runtime, isGlobal);
   console.log(`  ${green}✓${reset} Wrote file manifest (${MANIFEST_NAME})`);
 
+  // AGENTS.md universal rules layer (ADR-0028 Phase 3): contribute one
+  // marker-fenced PAN section to the project's AGENTS.md (read natively by
+  // every PAN runtime), and bridge CLAUDE.md to it via @AGENTS.md for the
+  // Claude runtime. Project-scoped — local installs only; user content
+  // outside the markers is never touched.
+  if (!isGlobal) {
+    try {
+      const agentsMdPath = path.join(process.cwd(), 'AGENTS.md');
+      let agentsExisting = null;
+      try { agentsExisting = fs.readFileSync(agentsMdPath, 'utf8'); } catch { /* absent */ }
+      fs.writeFileSync(agentsMdPath, lib.upsertAgentsMdSection(agentsExisting, lib.buildAgentsMdSection()));
+      console.log(`  ${green}✓${reset} ${agentsExisting === null ? 'Created' : 'Updated'} AGENTS.md (PAN section)`);
+
+      if (runtime === 'claude') {
+        const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
+        let claudeExisting = null;
+        try { claudeExisting = fs.readFileSync(claudeMdPath, 'utf8'); } catch { /* absent */ }
+        const bridged = lib.ensureClaudeMdImport(claudeExisting);
+        if (bridged !== claudeExisting) {
+          fs.writeFileSync(claudeMdPath, bridged);
+          console.log(`  ${green}✓${reset} Bridged CLAUDE.md to AGENTS.md (@AGENTS.md import)`);
+        }
+      }
+    } catch (e) {
+      pushInstallWarning('agentsMd', 'AGENTS.md', e);
+    }
+  }
+
   // Report any backed-up local patches
   reportLocalPatches(targetDir, runtime);
 
@@ -1657,12 +2216,17 @@ function install(isGlobal, runtime = 'claude') {
     for (const w of verifyResult.warnings) console.error(`    - ${w}`);
   }
   if (!verifyResult.ok) {
-    console.error(`\n  ${red}✖ Install verification FAILED — ${verifyResult.missing.length} file(s) missing:${reset}`);
-    // Limit output to first 20 missing to avoid screen-flooding
-    const sample = verifyResult.missing.slice(0, 20);
+    const emptyFiles = verifyResult.empty || [];
+    const problems = [
+      ...verifyResult.missing.map(m => `${m} (missing)`),
+      ...emptyFiles.map(e => `${e} (empty — copy failed)`),
+    ];
+    console.error(`\n  ${red}✖ Install verification FAILED — ${verifyResult.missing.length} missing, ${emptyFiles.length} empty:${reset}`);
+    // Limit output to first 20 to avoid screen-flooding
+    const sample = problems.slice(0, 20);
     for (const m of sample) console.error(`    - ${m}`);
-    if (verifyResult.missing.length > sample.length) {
-      console.error(`    ... and ${verifyResult.missing.length - sample.length} more`);
+    if (problems.length > sample.length) {
+      console.error(`    ... and ${problems.length - sample.length} more`);
     }
     console.error(`\n  Run ${cyan}pan-tools validate deployment${reset} for full diagnostics, then re-run the installer.\n`);
     process.exit(1);
@@ -1682,10 +2246,6 @@ function install(isGlobal, runtime = 'claude') {
     }
   }
 
-  if (isCodex) {
-    return { settingsPath: null, settings: null, statuslineCommand: null, runtime };
-  }
-
   const updateCheckCommand = isGlobal
     ? buildHookCommand(targetDir, 'pan-check-update.js')
     : 'node ' + dirName + '/hooks/pan-check-update.js';
@@ -1702,45 +2262,76 @@ function install(isGlobal, runtime = 'claude') {
     ? buildHookCommand(targetDir, 'pan-trace-logger.js')
     : 'node ' + dirName + '/hooks/pan-trace-logger.js';
 
-  // Copilot CLI uses config.json with its own hook format
+  if (isCodex) {
+    // Codex hooks (2026-06): Claude-compatible PascalCase events in the shared
+    // .codex/hooks.json — merge PAN entries non-destructively (foreign hooks
+    // preserved, reinstall idempotent). Project-scoped hooks load once the
+    // project is trusted; codexTrustNotice() already covers that.
+    try {
+      const hooksJsonPath = path.join(targetDir, 'hooks.json');
+      let existing = null;
+      try { existing = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8')); } catch { /* absent or invalid — start fresh */ }
+      const merged = lib.mergeCodexHooksConfig(existing, {
+        updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand,
+      });
+      fs.writeFileSync(hooksJsonPath, JSON.stringify(merged, null, 2) + '\n');
+      console.log(`  ${green}✓${reset} Configured hooks (.codex/hooks.json: update check, context monitor, cost + trace loggers)`);
+    } catch (e) {
+      pushInstallWarning('codexHooks', 'hooks.json', e);
+    }
+    return { settingsPath: null, settings: null, statuslineCommand: null, runtime };
+  }
+
+  // Copilot CLI reads hook config from .github/hooks/*.json (version:1 schema),
+  // NOT from config.json. Write a dedicated PAN hooks file and migrate away
+  // from any legacy config.json registration.
   if (isCopilot) {
+    const hooksConfigPath = path.join(targetDir, 'hooks', 'pan.json');
+    const hooksConfig = buildCopilotHooksConfig({ updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand });
+    try {
+      fs.mkdirSync(path.dirname(hooksConfigPath), { recursive: true });
+      fs.writeFileSync(hooksConfigPath, JSON.stringify(hooksConfig, null, 2) + '\n');
+      console.log(`  ${green}✓${reset} Configured hooks (.github/hooks/pan.json: update check, context monitor, cost + trace loggers)`);
+    } catch (e) {
+      console.error(`  ${yellow}✗${reset} Failed to write Copilot hooks config: ${e.message}`);
+    }
+
+    // Upgrade cleanup: strip PAN hook + statusline registrations left in
+    // config.json by pre-2026-06 installs. Copilot CLI never read them there —
+    // user-editable settings live in settings.json (~/.copilot/ global,
+    // .github/copilot/ repo-level); config.json is internal CLI state.
     const configPath = path.join(targetDir, 'config.json');
     const config = readSettings(configPath);
-
-    if (!config.hooks) {
-      config.hooks = {};
+    let legacyModified = false;
+    if (config.hooks) {
+      for (const evt of ['sessionStart', 'postToolUse']) {
+        if (Array.isArray(config.hooks[evt])) {
+          config.hooks[evt] = config.hooks[evt].filter(h =>
+            !(h.command && (h.command.includes('pan-check-update') || h.command.includes('pan-context-monitor')))
+          );
+          if (config.hooks[evt].length === 0) delete config.hooks[evt];
+        }
+      }
+      if (Object.keys(config.hooks).length === 0) delete config.hooks;
+      legacyModified = true;
     }
-
-    // Register sessionStart hook for update checking
-    if (!config.hooks.sessionStart) {
-      config.hooks.sessionStart = [];
+    if (config.statusLine && config.statusLine.command &&
+        config.statusLine.command.includes('pan-statusline')) {
+      delete config.statusLine;
+      legacyModified = true;
     }
-    const hasPanUpdateHook = config.hooks.sessionStart.some(h =>
-      h.command && h.command.includes('pan-check-update')
-    );
-    if (!hasPanUpdateHook) {
-      config.hooks.sessionStart.push({
-        command: updateCheckCommand
-      });
-      console.log(`  ${green}✓${reset} Configured update check hook`);
+    if (legacyModified) {
+      writeSettings(configPath, config);
     }
 
-    // Register postToolUse hook for context monitoring
-    if (!config.hooks.postToolUse) {
-      config.hooks.postToolUse = [];
-    }
-    const hasContextHook = config.hooks.postToolUse.some(h =>
-      h.command && h.command.includes('pan-context-monitor')
-    );
-    if (!hasContextHook) {
-      config.hooks.postToolUse.push({
-        command: contextMonitorCommand
-      });
-      console.log(`  ${green}✓${reset} Configured context window monitor hook`);
-    }
+    // Documented Copilot CLI settings read paths: ~/.copilot/settings.json
+    // (global) or .github/copilot/settings.json (repo-level, committed).
+    const copilotSettingsPath = isGlobal
+      ? path.join(targetDir, 'settings.json')
+      : path.join(targetDir, 'copilot', 'settings.json');
+    const copilotSettings = readSettings(copilotSettingsPath);
 
-    writeSettings(configPath, config);
-    return { settingsPath: configPath, settings: config, statuslineCommand, runtime };
+    return { settingsPath: copilotSettingsPath, settings: copilotSettings, statuslineCommand, runtime };
   }
 
   // Configure statusline and hooks in settings.json
@@ -1856,22 +2447,25 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   const isCopilot = runtime === 'copilot';
 
   if (shouldInstallStatusline && !isOpencode && !isCodex) {
+    // Same schema everywhere — Copilot CLI also uses {type: "command", command}
+    // in settings.json (statusline is experimental there as of 2026-05).
+    settings.statusLine = {
+      type: 'command',
+      command: statuslineCommand
+    };
+    console.log(`  ${green}✓${reset} Configured statusline`);
     if (isCopilot) {
-      // Copilot CLI: statusline stored in config.json
-      settings.statusLine = {
-        command: statuslineCommand
-      };
-    } else {
-      settings.statusLine = {
-        type: 'command',
-        command: statuslineCommand
-      };
+      console.log(`  ${dim}ℹ Copilot CLI statusline is experimental — if it doesn't render, start with 'copilot --experimental'${reset}`);
     }
-    console.log(`  ${green}✓${reset} Configured statusline`);
   }
 
-  // Write settings/config when runtime supports it
-  if (!isCodex) {
+  // Write settings/config when runtime supports it. For Copilot, skip the
+  // write when there is nothing to persist (avoids creating an empty
+  // .github/copilot/settings.json).
+  if (!isCodex && !(isCopilot && Object.keys(settings).length === 0)) {
+    if (isCopilot) {
+      try { fs.mkdirSync(path.dirname(settingsPath), { recursive: true }); } catch { /* surfaced by writeSettings */ }
+    }
     writeSettings(settingsPath, settings);
   }
 
@@ -1896,8 +2490,8 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
             !caps.has_thinking ? 'extended thinking (E-3, E-10, E-11)' : null,
           ].filter(Boolean).join(', ');
           console.log(`
-  ${yellow}ℹ${reset} PAN 2.10+ is tuned for Opus 4.7. Default model "${modelField}" lacks: ${missing}.
-     Features degrade gracefully, but upgrade to claude-opus-4-7 for best results.`);
+  ${yellow}ℹ${reset} PAN 2.10+ is tuned for Opus 4.7+ class models. Default model "${modelField}" lacks: ${missing}.
+     Features degrade gracefully, but upgrade to claude-opus-4-8 (or claude-fable-5) for best results.`);
         }
       }
     } catch {
@@ -1905,6 +2499,18 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
     }
   }
 
+  // Gemini CLI → Antigravity transition (2026-06): informational, non-blocking.
+  if (runtime === 'gemini' && !args.includes('--skip-warnings')) {
+    console.log(`\n  ${yellow}ℹ${reset} ${geminiTransitionNotice().split('\n').join('\n     ')}`);
+  }
+
+  // Codex project-trust gate (2026-06): project-scoped .codex/ config only
+  // loads once the project is trusted. Local installs only — personal
+  // ~/.codex/ config is not gated.
+  if (runtime === 'codex' && !isGlobal && !args.includes('--skip-warnings')) {
+    console.log(`\n  ${yellow}ℹ${reset} ${codexTrustNotice().split('\n').join('\n     ')}`);
+  }
+
   let program = 'Claude Code';
   if (runtime === 'opencode') program = 'OpenCode';
   if (runtime === 'gemini') program = 'Gemini';