pan-wizard 3.8.0 → 3.12.0

package/bin/install-lib.cjs

@@ -360,9 +360,11 @@ function convertClaudeToOpencodeFrontmatter(content) {
   }
 
   if (allowedTools.length > 0) {
-    newLines.push('tools:');
+    // OpenCode 2026 agent frontmatter: `permission` (allow/ask/deny) replaced
+    // the deprecated `tools: {name: true}` map.
+    newLines.push('permission:');
     for (const tool of allowedTools) {
-      newLines.push(`  ${convertToolName(tool)}: true`);
+      newLines.push(`  ${convertToolName(tool)}: allow`);
     }
   }
 
@@ -431,6 +433,51 @@ function convertClaudeCommandToCodexSkill(content, skillName) {
   return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
 
+/**
+ * Generate the runtime-neutral skill adapter header (ADR-0028 Phase 1).
+ *
+ * Unlike the Codex/Copilot adapters, this header makes no assumptions about
+ * the consuming runtime — the same SKILL.md in the shared `.agents/skills/`
+ * tree is read by every runtime, so invocation, delegation, and interaction
+ * guidance are phrased in terms of "your runtime's native mechanism".
+ */
+function getUnifiedSkillAdapterHeader(skillName) {
+  return `<pan_skill_adapter>
+PAN unified skill (Agent Skills standard, shared .agents/skills/ tree):
+- This skill is invoked through your runtime's skill mechanism — slash command (\`/${skillName}\`), mention (\`$${skillName}\`), or skill picker.
+- Treat all user text after the invocation as \`{{PAN_ARGS}}\`. If none is present, treat \`{{PAN_ARGS}}\` as empty.
+- References like \`/pan-<name>\` in this document denote other PAN skills — invoke them with your runtime's own skill syntax.
+
+Sub-agent orchestration:
+- Any \`Task(...)\` pattern in referenced workflow docs is legacy syntax.
+- Delegate with your runtime's native mechanism (Claude Code \`Task\` tool, Codex \`spawn_agent\`, Copilot CLI \`/agent\`, OpenCode agents, Gemini sub-agents).
+- Treat legacy \`subagent_type\` names as the role of the sub-agent to invoke.
+
+User interaction (runtimes without a native question tool):
+- Ask one question at a time; show numbered options; mark the recommended option with **(recommended)**.
+- Accept numbers ("1"), labels, or free-text descriptions as valid answers.
+- Native interaction tools (e.g. AskUserQuestion blocks), where supported by your runtime, take precedence over this fallback.
+</pan_skill_adapter>`;
+}
+
+/** Claude command → runtime-neutral SKILL.md (ADR-0028 Phase 1) */
+function convertClaudeCommandToUnifiedSkill(content, skillName) {
+  // Normalize command mentions to the readable /pan-<name> form; the adapter
+  // header tells each runtime to map that onto its own invocation syntax.
+  let converted = convertSlashCommandsToCopilotSkillMentions(content);
+  converted = converted.replace(/\$ARGUMENTS\b/g, '{{PAN_ARGS}}');
+  const { frontmatter, body } = extractFrontmatterAndBody(converted);
+  let description = `Run PAN workflow ${skillName}.`;
+  if (frontmatter) {
+    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
+    if (maybeDescription) description = maybeDescription;
+  }
+  description = toSingleLine(description);
+  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
+  const adapter = getUnifiedSkillAdapterHeader(skillName);
+  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+}
+
 /** Generate Copilot CLI skill adapter header */
 function getCopilotSkillAdapterHeader(skillName) {
   const invocation = `/pan-${skillName.replace(/^pan-/, '')}`;
@@ -618,49 +665,78 @@ function buildClaudeSkillShim(opts) {
 }
 
 /**
- * Translate a thinking directive from the generic PAN frontmatter shape
- * into the runtime-specific syntax (or prose fallback).
+ * Translate a reasoning-depth directive from the generic PAN frontmatter
+ * shape into runtime-specific syntax (or prose fallback).
+ *
+ * Current shape (2026-06, adaptive-thinking era): PAN agents declare
+ * `effort: low|medium|high|xhigh|max` in frontmatter. Claude Code consumes
+ * `effort` natively — adaptive thinking replaced fixed thinking budgets,
+ * and `thinking_budget`-style controls were removed from the API on
+ * Opus 4.7+ models. Runtimes without a native effort field get a prose
+ * preamble that coaches the model to think before tool calls.
  *
- * PAN agents declare: `thinking: enabled` and `thinking_budget: 8000` in
- * frontmatter. Runtimes that support native extended thinking consume those
- * fields directly. Runtimes without native support get a prose preamble
- * that coaches the model to think step-by-step before tool calls.
+ * Legacy shape `{enabled: boolean, budget: number}` (from the retired
+ * `thinking:` / `thinking_budget:` fields) is still accepted; budgets map
+ * to effort levels (≤4000 → medium, ≤6000 → high, >6000 → xhigh).
  *
  * @param {string} runtime - 'claude'|'codex'|'gemini'|'opencode'|'copilot'
- * @param {Object} directive - {enabled: boolean, budget: number}
+ * @param {Object} directive - {effort: string} or legacy {enabled, budget}
  * @returns {{frontmatter: Object, preamble: string}} Translated directive.
  *   `frontmatter` = fields to add to the agent's YAML header.
  *   `preamble` = prose to inject at top of agent prompt.
  */
+const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+function effortFromLegacyBudget(budget) {
+  const b = Number(budget) > 0 ? Number(budget) : 2000;
+  if (b <= 4000) return 'medium';
+  if (b <= 6000) return 'high';
+  return 'xhigh';
+}
+
 function translateThinkingDirective(runtime, directive) {
   const result = { frontmatter: {}, preamble: '' };
-  if (!directive || !directive.enabled) return result;
-  const budget = Number(directive.budget) > 0 ? Number(directive.budget) : 2000;
+  if (!directive) return result;
+
+  let effort = null;
+  const rawEffort = typeof directive.effort === 'string' ? directive.effort.toLowerCase().trim() : '';
+  if (EFFORT_LEVELS.includes(rawEffort)) {
+    effort = rawEffort;
+  } else if (directive.enabled) {
+    effort = effortFromLegacyBudget(directive.budget);
+  }
+  if (!effort) return result;
 
   switch (runtime) {
     case 'claude':
-      // Claude Code consumes these natively.
-      result.frontmatter = { thinking: 'enabled', thinking_budget: budget };
+      // Claude Code consumes `effort` natively (adaptive thinking is the default).
+      result.frontmatter = { effort };
       return result;
     case 'codex':
     case 'opencode':
     case 'gemini':
     case 'copilot':
-    default:
-      // Prose fallback — host runtime has no native thinking support.
-      result.preamble = `Think through the problem step-by-step before taking any action. Reason about edge cases, hidden dependencies, and likely failure modes. Use up to ~${budget} tokens of internal reasoning. Only after that, call tools or write output.`;
+    default: {
+      // Prose fallback — host runtime has no native effort field.
+      const depth = effort === 'low'
+        ? 'Keep reasoning brief and focused on the immediate task.'
+        : effort === 'medium'
+          ? 'Reason about edge cases, hidden dependencies, and likely failure modes.'
+          : 'Be thorough: reason about edge cases, hidden dependencies, and likely failure modes, preferring deeper analysis over speed.';
+      result.preamble = `Think through the problem step-by-step before taking any action. ${depth} Only after that, call tools or write output.`;
       return result;
+    }
   }
 }
 
 /**
- * Strip Opus 4.7 `thinking` / `thinking_budget` frontmatter fields from an
- * agent markdown file for runtimes that don't support native extended
- * thinking. When thinking was enabled, inject a prose preamble at the top
- * of the body instructing the model to think step-by-step.
+ * Strip reasoning-depth frontmatter (`effort`, plus the legacy `thinking` /
+ * `thinking_budget` pair) from an agent markdown file for runtimes that
+ * don't support those fields natively. When a directive was present,
+ * inject a prose preamble at the top of the body instead.
  *
- * Claude runtime is a no-op — those fields stay in frontmatter so the
- * host runtime consumes them.
+ * Claude runtime is a no-op — `effort` stays in frontmatter so Claude Code
+ * consumes it natively.
  *
  * @param {string} content - Full agent .md content
  * @param {string} runtime - 'claude'|'codex'|'gemini'|'opencode'|'copilot'
@@ -675,21 +751,25 @@ function stripThinkingFrontmatter(content, runtime) {
 
   const thinkingValue = extractFrontmatterField(frontmatter, 'thinking');
   const budgetValue = extractFrontmatterField(frontmatter, 'thinking_budget');
-  if (!thinkingValue && !budgetValue) return content;
+  const effortValue = extractFrontmatterField(frontmatter, 'effort');
+  if (!thinkingValue && !budgetValue && !effortValue) return content;
 
-  // Remove the two fields (match on their own lines only).
+  // Remove the fields (match on their own lines only).
   let fmBody = frontmatter
     .replace(/^thinking:\s*[^\n]*\n?/gm, '')
-    .replace(/^thinking_budget:\s*[^\n]*\n?/gm, '');
+    .replace(/^thinking_budget:\s*[^\n]*\n?/gm, '')
+    .replace(/^effort:\s*[^\n]*\n?/gm, '');
 
   const rebuilt = `---\n${fmBody.replace(/^---\n|\n---$/g, '')}\n---`;
   let out = rebuilt.replace(/\n\n+/g, '\n\n') + '\n\n';
 
-  // If thinking was enabled, prepend a prose preamble.
+  // Build the directive: `effort` wins; legacy thinking/budget falls back.
   const enabled = String(thinkingValue || '').toLowerCase().trim() === 'enabled'
     || String(thinkingValue || '').toLowerCase().trim() === 'true';
-  if (enabled) {
-    const directive = { enabled: true, budget: Number(budgetValue) || 2000 };
+  const directive = effortValue
+    ? { effort: String(effortValue) }
+    : (enabled ? { enabled: true, budget: Number(budgetValue) || 2000 } : null);
+  if (directive) {
     const { preamble } = translateThinkingDirective(runtime, directive);
     if (preamble) {
       out += `<!-- pan:thinking -->\n${preamble}\n<!-- /pan:thinking -->\n\n`;
@@ -700,6 +780,214 @@ function stripThinkingFrontmatter(content, runtime) {
   return out;
 }
 
+// ─── Copilot CLI hooks config (2026-06) ─────────────────────────────────────
+
+/**
+ * Build a Copilot CLI hooks config object for `.github/hooks/pan.json`.
+ *
+ * Copilot CLI reads hook configuration from `.github/hooks/*.json` (repo) with
+ * a `version: 1` envelope and per-event arrays of `{type, command, ...}`
+ * entries — NOT from `config.json`. A command hook supplies one of `bash`,
+ * `powershell`, or `command` (cross-platform fallback). PAN's hooks are
+ * Node.js scripts invoked via `node …`, so the cross-platform `command` key
+ * is the correct fit on every OS. Verified against
+ * docs.github.com/en/copilot/reference/hooks-configuration (2026-06).
+ *
+ * Pure function so the generated config is unit-testable.
+ *
+ * @param {Object} commands
+ * @param {string} commands.updateCheckCommand   - node invocation for pan-check-update.js
+ * @param {string} commands.contextMonitorCommand - node invocation for pan-context-monitor.js
+ * @returns {Object} A `.github/hooks/pan.json` config object
+ */
+function buildCopilotHooksConfig(commands) {
+  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand } = commands || {};
+  const config = { version: 1, hooks: {} };
+  if (updateCheckCommand) {
+    config.hooks.sessionStart = [{ type: 'command', command: updateCheckCommand }];
+  }
+  if (contextMonitorCommand) {
+    config.hooks.postToolUse = [{ type: 'command', command: contextMonitorCommand }];
+  }
+  // subagentStop is Copilot's SubagentStop equivalent (verified docs.github.com
+  // 2026-06) — carries the cost + trace loggers, same as Claude/Gemini.
+  const subagentStop = [];
+  if (costLoggerCommand) subagentStop.push({ type: 'command', command: costLoggerCommand });
+  if (traceLoggerCommand) subagentStop.push({ type: 'command', command: traceLoggerCommand });
+  if (subagentStop.length > 0) {
+    config.hooks.subagentStop = subagentStop;
+  }
+  return config;
+}
+
+// ─── Codex hooks config (2026-06) ───────────────────────────────────────────
+
+/**
+ * Cross-runtime hook event map (canonical PAN event → per-runtime name).
+ * Claude/Gemini register in settings.json; Codex in `.codex/hooks.json`
+ * (Claude-compatible PascalCase events — verified developers.openai.com
+ * 2026-06, project-scoped hooks load once the project is trusted); Copilot
+ * in `.github/hooks/pan.json` (camelCase — verified docs.github.com 2026-06).
+ * OpenCode has no hook support.
+ */
+const HOOK_EVENT_MAP = Object.freeze({
+  claude: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop' },
+  gemini: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop' },
+  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop' },
+  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', postToolUse: 'postToolUse', subagentStop: 'subagentStop' },
+  opencode: null,
+});
+
+/**
+ * Merge PAN hook registrations into a `.codex/hooks.json` config.
+ *
+ * Codex hooks use the Claude-style shape — `{hooks: {EventName: [{matcher?,
+ * hooks: [{type: 'command', command}]}]}}` with PascalCase event names —
+ * and `.codex/hooks.json` is a single shared file, so PAN entries are merged
+ * non-destructively: existing non-PAN entries are preserved, and PAN entries
+ * are deduplicated by their pan-* command substring (idempotent reinstall).
+ *
+ * @param {object|null} existing - Parsed existing hooks.json content, or null
+ * @param {Object} commands - node invocations keyed like buildCopilotHooksConfig
+ * @returns {object} Merged config object to serialize back to hooks.json
+ */
+function mergeCodexHooksConfig(existing, commands) {
+  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand } = commands || {};
+  const config = (existing && typeof existing === 'object') ? existing : {};
+  if (!config.hooks || typeof config.hooks !== 'object') config.hooks = {};
+
+  const wanted = [
+    ['SessionStart', updateCheckCommand, 'pan-check-update'],
+    ['PostToolUse', contextMonitorCommand, 'pan-context-monitor'],
+    ['SubagentStop', costLoggerCommand, 'pan-cost-logger'],
+    ['SubagentStop', traceLoggerCommand, 'pan-trace-logger'],
+  ];
+
+  for (const [event, command, marker] of wanted) {
+    if (!command) continue;
+    if (!Array.isArray(config.hooks[event])) config.hooks[event] = [];
+    const present = config.hooks[event].some(group =>
+      Array.isArray(group.hooks) && group.hooks.some(h => h.command && h.command.includes(marker)));
+    if (!present) {
+      config.hooks[event].push({ hooks: [{ type: 'command', command }] });
+    }
+  }
+  return config;
+}
+
+/**
+ * Remove PAN hook registrations from a `.codex/hooks.json` config.
+ * @param {object|null} existing - Parsed existing hooks.json content
+ * @returns {object|null} Config without PAN entries, or null when nothing
+ *   meaningful remains (caller should delete the file).
+ */
+function removeCodexPanHooks(existing) {
+  if (!existing || typeof existing !== 'object' || !existing.hooks) return existing || null;
+  for (const event of Object.keys(existing.hooks)) {
+    if (!Array.isArray(existing.hooks[event])) continue;
+    existing.hooks[event] = existing.hooks[event].filter(group =>
+      !(Array.isArray(group.hooks) && group.hooks.some(h => h.command && /pan-(check-update|context-monitor|cost-logger|trace-logger)/.test(h.command))));
+    if (existing.hooks[event].length === 0) delete existing.hooks[event];
+  }
+  if (Object.keys(existing.hooks).length === 0) delete existing.hooks;
+  return Object.keys(existing).length === 0 ? null : existing;
+}
+
+// ─── Codex agents (TOML) + trust notice (2026-06) ───────────────────────────
+
+/**
+ * Convert a Claude agent markdown file into a Codex custom-agent TOML file.
+ *
+ * Codex custom agents are standalone TOML files in `.codex/agents/` (project)
+ * or `~/.codex/agents/` (personal). Required fields: name, description,
+ * developer_instructions. PAN's `effort` frontmatter maps to Codex's
+ * `model_reasoning_effort`. Model/tier is left to inherit from the parent
+ * session (PAN tiers don't map to OpenAI model ids).
+ * Verified against developers.openai.com/codex/subagents (2026-06).
+ *
+ * @param {string} content - Full Claude agent .md content
+ * @returns {string|null} TOML string, or null when content has no frontmatter
+ */
+function convertClaudeAgentToCodexToml(content) {
+  if (typeof content !== 'string' || !content.startsWith('---')) return null;
+  const endIndex = content.indexOf('---', 3);
+  if (endIndex === -1) return null;
+
+  const frontmatter = content.substring(3, endIndex);
+  const body = content.substring(endIndex + 3).replace(/^\n+/, '');
+
+  const field = (key) => {
+    const m = frontmatter.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+    return m ? m[1].trim() : '';
+  };
+
+  const name = field('name');
+  const description = field('description');
+  const effort = field('effort').toLowerCase();
+  if (!name) return null;
+
+  // TOML multi-line basic string: escape backslashes, then break any """ runs.
+  const instructions = body
+    .replace(/\\/g, '\\\\')
+    .replace(/"""/g, '"\\""');
+
+  const lines = [
+    `name = ${JSON.stringify(name)}`,
+    `description = ${JSON.stringify(description)}`,
+  ];
+  if (['minimal', 'low', 'medium', 'high', 'xhigh'].includes(effort)) {
+    lines.push(`model_reasoning_effort = ${JSON.stringify(effort)}`);
+  }
+  lines.push('developer_instructions = """');
+  lines.push(instructions.replace(/\n+$/, ''));
+  lines.push('"""');
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Informational notice shown after a local (project-scoped) Codex install.
+ *
+ * Codex gates project-level `.codex/` configuration (including custom agents)
+ * behind project trust: untrusted projects silently skip it. Pure function so
+ * the installer message is unit-testable.
+ *
+ * @returns {string} Multi-line plain-text notice (no ANSI codes).
+ */
+function codexTrustNotice() {
+  return [
+    'Codex trust note: project-scoped .codex/ configuration (including the',
+    'installed pan-* agents) only loads once the project is trusted in Codex.',
+    'If commands or agents seem missing, approve the project when Codex prompts,',
+    'or set trust_level for this path in ~/.codex/config.toml.',
+  ].join('\n');
+}
+
+// ─── Gemini CLI → Antigravity transition notice (2026-06) ──────────────────
+
+/**
+ * Informational notice shown after a Gemini CLI install.
+ *
+ * Google announced (2026-05-19) that from 2026-06-18 the Gemini CLI serves
+ * Gemini Code Assist (Standard/Enterprise) customers only; individual
+ * free / AI Pro / Ultra accounts are directed to Antigravity CLI instead.
+ * PAN's --gemini target installs for Gemini CLI; Antigravity CLI is not yet
+ * a PAN install target (tracked in docs/ECOSYSTEM-REVIEW-2026-06.md).
+ *
+ * Pure function so the installer message is unit-testable.
+ *
+ * @returns {string} Multi-line plain-text notice (no ANSI codes).
+ */
+function geminiTransitionNotice() {
+  return [
+    'Gemini CLI transition notice: from June 18, 2026, Google\'s Gemini CLI serves',
+    'Gemini Code Assist (Standard/Enterprise) customers; individual free / AI Pro /',
+    'Ultra accounts are directed to Antigravity CLI instead. This install targets',
+    'Gemini CLI. Antigravity CLI is not yet a PAN install target, but it reads the',
+    'shared .agents/skills/ tree natively — PAN skills installed there (today via',
+    'the --codex target) are usable from Antigravity in the same project.',
+  ].join('\n');
+}
+
 // ─── Opus 4.7 Capability Detection ──────────────────────────────────────────
 
 /**
@@ -707,7 +995,11 @@ function stripThinkingFrontmatter(content, runtime) {
  * Used by installer to warn users when their default model lacks features
  * PAN 2.10+ relies on (1M context, extended thinking, prompt caching).
  *
- * @param {string} modelName - e.g. "claude-opus-4-7", "claude-sonnet-4-6", "gpt-5"
+ * Capability data refreshed 2026-06: Fable 5 and Opus 4.8/4.7/4.6 plus
+ * Sonnet 4.6 all carry a 1M context window; only the legacy Opus/Sonnet
+ * 4.0–4.5 generations are 200K.
+ *
+ * @param {string} modelName - e.g. "claude-fable-5", "claude-opus-4-8", "gpt-5"
  * @returns {{has_1m_ctx: boolean, has_thinking: boolean, has_cache: boolean, tier: string}}
  */
 function detectModelCapabilities(modelName) {
@@ -716,13 +1008,21 @@ function detectModelCapabilities(modelName) {
   const n = modelName.toLowerCase();
 
   // Anthropic Claude family
-  if (n.includes('opus-4-7') || n.includes('opus-4.7')) {
+  if (n.includes('fable')) {
+    return { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'reasoning' };
+  }
+  if (n.includes('opus-4-8') || n.includes('opus-4.8')
+    || n.includes('opus-4-7') || n.includes('opus-4.7')
+    || n.includes('opus-4-6') || n.includes('opus-4.6')) {
     return { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'reasoning' };
   }
-  if (n.includes('opus-4-6') || n.includes('opus-4.6') || n.includes('opus-4')) {
+  if (n.includes('opus-4')) { // legacy Opus 4.0 / 4.1 / 4.5 — 200K context
     return { has_1m_ctx: false, has_thinking: true, has_cache: true, tier: 'reasoning' };
   }
-  if (n.includes('sonnet-4-6') || n.includes('sonnet-4.6') || n.includes('sonnet-4')) {
+  if (n.includes('sonnet-4-6') || n.includes('sonnet-4.6')) {
+    return { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'mid' };
+  }
+  if (n.includes('sonnet-4')) { // legacy Sonnet 4.0 / 4.5 — 200K context
     return { has_1m_ctx: false, has_thinking: true, has_cache: true, tier: 'mid' };
   }
   if (n.includes('haiku-4-5') || n.includes('haiku-4.5') || n.includes('haiku-4')) {
@@ -778,33 +1078,48 @@ const path_v = require('path');
  * Verify installed files against the manifest.
  *
  * For each entry in manifest.files, check the file is present on disk at
- * the expected location. We do NOT re-hash (the manifest was just written
- * from these files, so re-hashing would only catch corruption-after-write
- * which is a different concern). We DO catch the much more common case of
- * "file silently failed to land in the first place."
+ * the expected location AND non-empty. We do NOT re-hash: the manifest was
+ * just written from these files, so re-hashing is tautological — a 0-byte
+ * copy gets a 0-byte hash recorded and would "verify" cleanly. The size
+ * check is what actually catches the canonical silent copy failure
+ * (truncated/empty file landed instead of content).
  *
- * Also verifies critical anchor files that, if missing, mean the install is
- * unusable: pan-tools.cjs, the dispatcher.
+ * Also verifies critical anchor files that, if missing or empty, mean the
+ * install is unusable: pan-tools.cjs, the dispatcher.
  *
  * @param {string} configDir - install root (e.g., ~/.claude or ./.codex)
  * @param {object} manifest - the manifest object returned by writeManifest()
- * @returns {object} { ok: bool, missing: string[], warnings: string[] }
+ * @returns {object} { ok: bool, missing: string[], empty: string[], warnings: string[] }
  */
 function verifyInstall(configDir, manifest) {
   const missing = [];
+  const empty = [];
   const warnings = [];
 
-  // Critical anchor: pan-tools.cjs MUST exist; without it, no command works.
-  const dispatcherPath = path_v.join(configDir, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
-  if (!fs_v.existsSync(dispatcherPath)) {
-    missing.push('pan-wizard-core/bin/pan-tools.cjs (dispatcher — install is unusable without it)');
+  // Critical anchor: pan-tools.cjs MUST exist and carry content; without it,
+  // no command works.
+  const dispatcherRel = 'pan-wizard-core/bin/pan-tools.cjs';
+  const dispatcherPath = path_v.join(configDir, dispatcherRel);
+  try {
+    const st = fs_v.statSync(dispatcherPath);
+    if (st.size === 0) {
+      empty.push(`${dispatcherRel} (dispatcher is empty — copy failed; install is unusable)`);
+    }
+  } catch {
+    missing.push(`${dispatcherRel} (dispatcher — install is unusable without it)`);
   }
 
-  // Manifest-level: every tracked file must exist.
+  // Manifest-level: every tracked file must exist and be non-empty. No
+  // shipped PAN file is legitimately 0 bytes.
   if (manifest && manifest.files) {
     for (const rel of Object.keys(manifest.files)) {
       const abs = path_v.join(configDir, rel);
-      if (!fs_v.existsSync(abs)) {
+      try {
+        const st = fs_v.statSync(abs);
+        if (st.size === 0) {
+          empty.push(rel);
+        }
+      } catch {
         missing.push(rel);
       }
     }
@@ -812,7 +1127,284 @@ function verifyInstall(configDir, manifest) {
     warnings.push('manifest is missing or has no files entry — verification is degraded');
   }
 
-  return { ok: missing.length === 0, missing, warnings };
+  return { ok: missing.length === 0 && empty.length === 0, missing, empty, warnings };
+}
+
+// ─── Claude Code plugin packaging (2026-06) ─────────────────────────────────
+
+/**
+ * Build the .claude-plugin/plugin.json manifest for the PAN plugin build.
+ * Format verified against code.claude.com/docs/en/plugins-reference (2026-06):
+ * manifest is optional metadata; components auto-discover from commands/,
+ * agents/, hooks/hooks.json in the plugin root.
+ *
+ * @param {object} pkg - parsed package.json
+ * @returns {object} plugin.json object
+ */
+function buildPluginManifest(pkg) {
+  return {
+    name: 'pan-wizard',
+    displayName: 'PAN Wizard',
+    version: pkg.version,
+    description: pkg.description || 'Structured, phase-based planning and execution for AI coding agents.',
+    author: { name: 'PAN Wizard contributors', url: 'https://github.com/oharms/PanWizard' },
+    repository: 'https://github.com/oharms/PanWizard',
+    license: pkg.license || 'MIT',
+    keywords: ['planning', 'workflow', 'agents', 'phases'],
+  };
+}
+
+/**
+ * Build the plugin hooks/hooks.json — PAN's four hooks registered with
+ * ${CLAUDE_PLUGIN_ROOT}-anchored commands (the documented plugin-relative
+ * path convention for hook configs).
+ * @returns {object} hooks.json object
+ */
+function buildPluginHooksConfig() {
+  const hook = (script) => ({
+    hooks: [{ type: 'command', command: `node "\${CLAUDE_PLUGIN_ROOT}/hooks/${script}"` }],
+  });
+  return {
+    hooks: {
+      SessionStart: [hook('pan-check-update.js')],
+      PostToolUse: [hook('pan-context-monitor.js')],
+      SubagentStop: [hook('pan-cost-logger.js'), hook('pan-trace-logger.js')],
+    },
+  };
+}
+
+// ─── Native Claude Code workflows (2026-06) ─────────────────────────────────
+//
+// Claude Code discovers deterministic orchestration scripts in
+// `.claude/workflows/*.js` (export const meta + agent()/parallel()/pipeline()
+// hooks). PAN ships native scripts only for protocols that are genuinely
+// deterministic fan-outs — the markdown protocols remain the source of truth
+// for judgment-heavy flows. Claude-only; other runtimes have no equivalent.
+
+/**
+ * Build the PAN native workflow scripts.
+ * Pure function — returns [{name, content}] for the installer to write.
+ * @returns {Array<{name: string, content: string}>}
+ */
+function buildNativeWorkflowScripts() {
+  const reviewPipeline = `export const meta = {
+  name: 'pan-review-pipeline',
+  description: 'PAN deep review: reviewer + hardener fan-out, meta-reviewer merge',
+  whenToUse: 'Deterministic version of the /pan-review-deep fan-out. Pass the phase number or a description of the change set as args.',
+  phases: [
+    { title: 'Find', detail: 'reviewer + security hardener in parallel' },
+    { title: 'Merge', detail: 'meta-reviewer dedupes, disputes, and issues the verdict' },
+  ],
+}
+
+const target = (typeof args === 'string' && args.trim())
+  ? args.trim()
+  : 'the uncommitted/current phase changes in this repository'
+
+const FINDINGS = {
+  type: 'object',
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          file: { type: 'string' },
+          severity: { type: 'string', enum: ['critical', 'major', 'minor', 'info'] },
+          detail: { type: 'string' },
+        },
+        required: ['title', 'severity', 'detail'],
+      },
+    },
+  },
+  required: ['findings'],
+}
+
+phase('Find')
+const results = await parallel([
+  () => agent(
+    'Review ' + target + '. Report EVERY finding you see, tagged with the right severity tier — coverage, not filtering; the meta-reviewer downstream is the filter.',
+    { agentType: 'pan-reviewer', label: 'review', phase: 'Find', schema: FINDINGS }),
+  () => agent(
+    'Security-audit ' + target + ' (OWASP Top 10 + STRIDE). Report every concrete finding with severity.',
+    { agentType: 'pan-hardener', label: 'harden', phase: 'Find', schema: FINDINGS }),
+])
+const found = results.filter(Boolean).flatMap(r => r.findings)
+log(found.length + ' raw findings collected')
+
+phase('Merge')
+const VERDICT = {
+  type: 'object',
+  properties: {
+    verdict: { type: 'string', enum: ['ok', 'ok_with_minor', 'fix_before_merge', 'review_required', 'block'] },
+    confirmed: { type: 'array', items: { type: 'object' } },
+    disputed: { type: 'array', items: { type: 'object' } },
+    summary: { type: 'string' },
+  },
+  required: ['verdict', 'summary'],
+}
+const merged = await agent(
+  'Merge these raw review findings: dedupe overlaps, dispute overstated ones, then issue a single verdict on the PAN ladder (ok / ok_with_minor / fix_before_merge / review_required / block).\\n\\nFindings:\\n' + JSON.stringify(found, null, 2),
+  { agentType: 'pan-meta-reviewer', label: 'merge', phase: 'Merge', schema: VERDICT })
+
+return merged
+`;
+
+  const mapCodebase = `export const meta = {
+  name: 'pan-map-codebase',
+  description: 'PAN codebase mapping: shard fan-out per top-level area, then synthesis',
+  whenToUse: 'Deterministic version of the /pan-map-codebase shard pattern for repositories too large for a single pass.',
+  phases: [
+    { title: 'Scan', detail: 'discover top-level areas worth documenting' },
+    { title: 'Map', detail: 'one documenter per area, in parallel' },
+    { title: 'Synthesize', detail: 'merge area maps into one codebase overview' },
+  ],
+}
+
+phase('Scan')
+const AREAS = {
+  type: 'object',
+  properties: { areas: { type: 'array', items: { type: 'string' } } },
+  required: ['areas'],
+}
+const scan = await agent(
+  'List the top-level areas of this repository worth documenting separately (source dirs, test dirs, docs, infra). Skip vendored/generated content (node_modules, dist, build artifacts). Return at most 8 area paths.',
+  { label: 'scan', phase: 'Scan', schema: AREAS })
+const areas = (scan && scan.areas ? scan.areas : []).slice(0, 8)
+if (areas.length === 0) return { error: 'no areas discovered' }
+log('mapping ' + areas.length + ' areas')
+
+phase('Map')
+const AREA_MAP = {
+  type: 'object',
+  properties: {
+    area: { type: 'string' },
+    purpose: { type: 'string' },
+    key_files: { type: 'array', items: { type: 'string' } },
+    conventions: { type: 'array', items: { type: 'string' } },
+    risks: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['area', 'purpose'],
+}
+const maps = await parallel(areas.map(a => () =>
+  agent('Document the "' + a + '" area of this repository: purpose, key files, conventions in force, and risks/gotchas. Be specific and cite file paths.',
+    { agentType: 'pan-document_code', label: 'map:' + a, phase: 'Map', schema: AREA_MAP })))
+
+phase('Synthesize')
+const synthesis = await agent(
+  'Merge these per-area maps into one coherent codebase overview (architecture summary, cross-area conventions, integration points, top risks). Write the result to .planning/codebase/ using the PAN codebase templates if a .planning directory exists; otherwise return it as your final answer.\\n\\nArea maps:\\n' + JSON.stringify(maps.filter(Boolean), null, 2),
+  { label: 'synthesize', phase: 'Synthesize' })
+
+return { areas_mapped: maps.filter(Boolean).length, synthesis }
+`;
+
+  return [
+    { name: 'pan-review-pipeline.js', content: reviewPipeline },
+    { name: 'pan-map-codebase.js', content: mapCodebase },
+  ];
+}
+
+// ─── AGENTS.md universal rules layer (ADR-0028 Phase 3) ─────────────────────
+//
+// AGENTS.md is the cross-runtime project-instructions standard; every PAN
+// target runtime (and Antigravity CLI) reads it natively. PAN contributes one
+// marker-fenced section so agents in any runtime understand the PAN context
+// when reading the repo. User content outside the markers is never touched.
+
+const PAN_AGENTS_BEGIN = '<!-- BEGIN PAN WIZARD -->';
+const PAN_AGENTS_END = '<!-- END PAN WIZARD -->';
+
+/**
+ * Build the PAN section for AGENTS.md (marker-fenced, runtime-neutral).
+ * @returns {string} The fenced section, no leading/trailing blank lines.
+ */
+function buildAgentsMdSection() {
+  return [
+    PAN_AGENTS_BEGIN,
+    '## PAN Wizard',
+    '',
+    'This project uses PAN Wizard for structured, phase-based planning and execution.',
+    '',
+    '- `.planning/` is PAN\'s state directory (state.md, roadmap.md, phase directories). Treat it as the source of truth for planning state and modify it through PAN commands, not by hand.',
+    '- PAN commands install as `pan-*` skills/commands (for example `/pan-help`, `/pan-new-project`, `/pan-exec-phase`). Start with `/pan-help`.',
+    '- The `pan-tools` dispatcher backs every command; it lives under `pan-wizard-core/` inside the runtime\'s config directory (or `.agents/` for unified installs).',
+    PAN_AGENTS_END,
+  ].join('\n');
+}
+
+/**
+ * Insert or replace the PAN section in AGENTS.md content.
+ * - No existing content (null/empty) → just the section.
+ * - Markers present → replace exactly the fenced block, preserving everything
+ *   around it.
+ * - Markers absent → append with a separating blank line.
+ * @param {string|null} existing - Current AGENTS.md content, or null if absent
+ * @param {string} section - Output of buildAgentsMdSection()
+ * @returns {string} New file content (always newline-terminated)
+ */
+function upsertAgentsMdSection(existing, section) {
+  if (!existing || !existing.trim()) {
+    return section + '\n';
+  }
+  const beginIdx = existing.indexOf(PAN_AGENTS_BEGIN);
+  const endIdx = existing.indexOf(PAN_AGENTS_END);
+  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+    const before = existing.slice(0, beginIdx);
+    const after = existing.slice(endIdx + PAN_AGENTS_END.length);
+    return before + section + after;
+  }
+  return existing.trimEnd() + '\n\n' + section + '\n';
+}
+
+/**
+ * Remove the PAN section from AGENTS.md content.
+ * @param {string} existing - Current AGENTS.md content
+ * @returns {string|null} Content without the PAN block, or null when nothing
+ *   meaningful remains (caller should delete the file).
+ */
+function removeAgentsMdSection(existing) {
+  if (!existing) return null;
+  const beginIdx = existing.indexOf(PAN_AGENTS_BEGIN);
+  const endIdx = existing.indexOf(PAN_AGENTS_END);
+  if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {
+    return existing; // no PAN block — leave untouched
+  }
+  const before = existing.slice(0, beginIdx);
+  const after = existing.slice(endIdx + PAN_AGENTS_END.length);
+  const remaining = (before.trimEnd() + '\n\n' + after.trimStart()).trim();
+  return remaining ? remaining + '\n' : null;
+}
+
+/**
+ * Ensure CLAUDE.md bridges to AGENTS.md via a marker-fenced @AGENTS.md import
+ * (Claude Code's documented pattern for adopting the universal rules file).
+ * Idempotent; preserves all user content.
+ * @param {string|null} existing - Current CLAUDE.md content, or null if absent
+ * @returns {string} New file content
+ */
+function ensureClaudeMdImport(existing) {
+  const block = `${PAN_AGENTS_BEGIN}\n@AGENTS.md\n${PAN_AGENTS_END}`;
+  if (!existing || !existing.trim()) {
+    return block + '\n';
+  }
+  if (existing.includes(PAN_AGENTS_BEGIN)) {
+    return existing; // bridge (or another PAN block) already present
+  }
+  if (/^@AGENTS\.md\s*$/m.test(existing)) {
+    return existing; // user already imports AGENTS.md themselves
+  }
+  return existing.trimEnd() + '\n\n' + block + '\n';
+}
+
+/**
+ * Remove the PAN bridge block from CLAUDE.md content.
+ * @param {string} existing - Current CLAUDE.md content
+ * @returns {string|null} Content without the bridge, or null when nothing
+ *   meaningful remains (caller should delete the file).
+ */
+function removeClaudeMdImport(existing) {
+  return removeAgentsMdSection(existing);
 }
 
 // ─── Exports ────────────────────────────────────────────────────────────────
@@ -851,6 +1443,8 @@ module.exports = {
   // Skill/agent builders
   getCodexSkillAdapterHeader,
   convertClaudeCommandToCodexSkill,
+  getUnifiedSkillAdapterHeader,
+  convertClaudeCommandToUnifiedSkill,
   getCopilotSkillAdapterHeader,
   convertClaudeCommandToCopilotSkill,
   convertClaudeToCopilotAgent,
@@ -863,6 +1457,27 @@ module.exports = {
   buildClaudeSkillShim,
   translateThinkingDirective,
   stripThinkingFrontmatter,
+  // Gemini CLI → Antigravity transition (2026-06)
+  geminiTransitionNotice,
+  // Codex agents (TOML) + trust notice (2026-06)
+  convertClaudeAgentToCodexToml,
+  codexTrustNotice,
+  // Copilot CLI hooks config (2026-06)
+  buildCopilotHooksConfig,
+  HOOK_EVENT_MAP,
+  mergeCodexHooksConfig,
+  removeCodexPanHooks,
+  buildNativeWorkflowScripts,
+  buildPluginManifest,
+  buildPluginHooksConfig,
   // Install verification (v3.7.10)
   verifyInstall,
+  // AGENTS.md universal rules layer (ADR-0028 Phase 3)
+  buildAgentsMdSection,
+  upsertAgentsMdSection,
+  removeAgentsMdSection,
+  ensureClaudeMdImport,
+  removeClaudeMdImport,
+  PAN_AGENTS_BEGIN,
+  PAN_AGENTS_END,
 };