@orchid-labs/pluxx 0.1.3 → 0.1.5

package/dist/index.js

@@ -7132,27 +7132,67 @@ function mergeAction(current, next) {
   return ACTION_PRIORITY[next] > ACTION_PRIORITY[current] ? next : current;
 }
 function permissionRulesNeedToolLevelDowngrade(permissions) {
-  return collectPermissionRules(permissions).some((rule) => rule.pattern !== "*");
+  return collectPermissionRules(permissions).some((rule) => rule.kind === "MCP");
 }
 function buildOpenCodePermissionMap(permissions) {
   const rules = collectPermissionRules(permissions);
   const output = {};
-  const toolAliases = {
-    Bash: ["bash", "shell"],
-    Edit: ["edit", "write"],
-    Read: ["read"],
-    MCP: ["mcp"],
-    // OpenCode's native permission surface is tool-level and does not expose
-    // a dedicated skill permission key.
-    Skill: []
-  };
   for (const rule of rules) {
-    for (const tool of toolAliases[rule.kind]) {
-      output[tool] = mergeAction(output[tool], rule.action);
+    if (rule.kind === "MCP") {
+      const toolName = translateCanonicalMcpPermission(rule.pattern);
+      if (!toolName) continue;
+      output[toolName] = mergeScalarPermission(output[toolName], rule.action);
+      continue;
     }
+    const tool = toOpenCodePermissionTool(rule.kind);
+    if (!tool) continue;
+    output[tool] = mergePatternPermission(output[tool], rule.pattern, rule.action);
   }
   return output;
 }
+function toOpenCodePermissionTool(kind) {
+  switch (kind) {
+    case "Bash":
+      return "bash";
+    case "Edit":
+      return "edit";
+    case "Read":
+      return "read";
+    case "Skill":
+      return "skill";
+    case "MCP":
+      return null;
+  }
+}
+function mergeScalarPermission(current, next) {
+  if (!current) return next;
+  if (typeof current === "string") {
+    return mergeAction(current, next);
+  }
+  const merged = { ...current };
+  merged["*"] = mergeAction(merged["*"], next);
+  return merged;
+}
+function mergePatternPermission(current, pattern, next) {
+  if (pattern === "*") {
+    return mergeScalarPermission(current, next);
+  }
+  const merged = typeof current === "string" ? { "*": current } : { ...current ?? {} };
+  merged[pattern] = mergeAction(merged[pattern], next);
+  return merged;
+}
+function translateCanonicalMcpPermission(pattern) {
+  const trimmed = pattern.trim();
+  if (!trimmed || trimmed === "*") return null;
+  const dot = trimmed.indexOf(".");
+  if (dot === -1) {
+    return `${trimmed}_*`;
+  }
+  const server = trimmed.slice(0, dot).trim();
+  const tool = trimmed.slice(dot + 1).trim();
+  if (!server || !tool) return null;
+  return `${server}_${tool.replace(/\./g, "_")}`;
+}
 function buildGeneratedPermissionHookScript(permissions) {
   const rules = collectPermissionRules(permissions);
   if (rules.length === 0) return null;
@@ -7290,6 +7330,7 @@ function claudeResponse(match) {
   if (!match) return {};
   return {
     hookSpecificOutput: {
+      hookEventName: "PreToolUse",
       permissionDecision: match.action,
       permissionDecisionReason: "Pluxx permissions matched " + match.rule.raw,
     },
@@ -7748,10 +7789,22 @@ var PLATFORM_LIMIT_POLICIES = {
   },
   "codex": {
     ...NULL_LIMIT_POLICIES,
-    skillDescriptionMax: { kind: "hard" },
-    skillNameMustMatchDir: { kind: "hard" },
-    manifestPromptMax: { kind: "hard" },
-    manifestPromptCountMax: { kind: "hard" },
+    skillDescriptionMax: {
+      kind: "advisory",
+      notes: "Pluxx keeps Codex descriptions concise at 1,024 characters as a conservative compatibility heuristic; the current docs do not state this as an official hard cap."
+    },
+    skillNameMustMatchDir: {
+      kind: "advisory",
+      notes: "Pluxx keeps Codex skill directory names aligned with skill names for portability and predictability, but the current docs do not state this as a formal hard requirement."
+    },
+    manifestPromptMax: {
+      kind: "advisory",
+      notes: "Pluxx keeps Codex default prompts short at 128 characters as a conservative listing heuristic; the current docs do not publish this as a hard limit."
+    },
+    manifestPromptCountMax: {
+      kind: "advisory",
+      notes: "Pluxx keeps Codex default prompt count to three as a conservative listing heuristic; the current docs do not publish this as a hard limit."
+    },
     manifestPathPrefix: { kind: "hard" },
     instructionsMaxBytes: {
       kind: "hard",
@@ -7804,7 +7857,7 @@ var PLATFORM_LIMIT_POLICIES = {
 var PLATFORM_VALIDATION_RULES = {
   "claude-code": {
     platform: "claude-code",
-    summary: "Claude Code plugins use an optional manifest at .claude-plugin/plugin.json with auto-discovery for skills, commands, agents, hooks, MCP, and output styles.",
+    summary: "Claude Code plugins use an optional manifest at .claude-plugin/plugin.json with auto-discovery for skills, commands, agents, hooks, MCP, marketplaces, and output styles.",
     limits: PLATFORM_LIMITS["claude-code"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["claude-code"],
     skillDiscoveryDirs: [
@@ -7812,7 +7865,21 @@ var PLATFORM_VALIDATION_RULES = {
     ],
     frontmatter: {
       standard: [...STANDARD_SKILL_FRONTMATTER],
-      additional: []
+      additional: [
+        "when_to_use",
+        "argument-hint",
+        "arguments",
+        "user-invocable",
+        "allowed-tools",
+        "model",
+        "effort",
+        "context",
+        "agent",
+        "hooks",
+        "paths",
+        "shell"
+      ],
+      notes: "Claude exposes the richest documented skill frontmatter of the core four."
     },
     manifest: {
       files: [".claude-plugin/plugin.json"],
@@ -7820,43 +7887,58 @@ var PLATFORM_VALIDATION_RULES = {
       notes: "The manifest is optional; if present, name is the only required field."
     },
     mcp: {
-      files: [".mcp.json"],
+      files: [".mcp.json", ".claude-plugin/plugin.json"],
       rootKey: "mcpServers",
       transports: ["stdio", "http", "sse"],
-      auth: ["headers", "env interpolation"],
-      notes: "Claude Code supports either inline MCP config in plugin.json or a separate .mcp.json file."
+      auth: ["headers", "env interpolation", "OAuth 2.0", "bearer tokens", "dynamic headers"],
+      notes: "Claude Code supports either inline MCP config in plugin.json or a separate .mcp.json file, with marketplace and dependency-aware install flows."
     },
     hooks: {
       supported: true,
-      files: ["hooks/hooks.json"],
-      eventNames: [],
-      notes: "Hook configs can be stored in hooks/hooks.json or inlined in plugin.json."
+      files: ["hooks/hooks.json", ".claude-plugin/plugin.json", "~/.claude/settings.json", ".claude/settings.json", ".claude/settings.local.json"],
+      eventNames: ["SessionStart", "PreToolUse", "PostToolUse", "PermissionRequest", "TaskCreated", "TaskCompleted", "Stop", "Notification", "ConfigChange"],
+      notes: "Hook configs can be stored in hooks/hooks.json, inlined in plugin.json, added in settings files, or scoped through skill and agent frontmatter."
     },
     instructions: {
       files: ["CLAUDE.md"],
-      format: "markdown"
+      format: "markdown",
+      notes: "Claude keeps persistent instructions in CLAUDE.md and pushes longer procedures into skills."
     },
     sources: [
-      { label: "Claude Code headless docs", url: "https://code.claude.com/docs/en/headless" },
+      { label: "Claude Code MCP docs", url: "https://code.claude.com/docs/en/mcp" },
+      { label: "Claude Code plugin marketplaces docs", url: "https://code.claude.com/docs/en/plugin-marketplaces" },
+      { label: "Claude Code plugin dependencies docs", url: "https://code.claude.com/docs/en/plugin-dependencies" },
+      { label: "Claude Code features overview", url: "https://code.claude.com/docs/en/features-overview" },
+      { label: "Claude Code best practices", url: "https://code.claude.com/docs/en/best-practices" },
       { label: "Claude Code CLI reference", url: "https://code.claude.com/docs/en/cli-reference" },
       { label: "Claude Code discover plugins docs", url: "https://code.claude.com/docs/en/discover-plugins" },
+      { label: "Claude Code plugins docs", url: "https://code.claude.com/docs/en/plugins" },
       { label: "Claude Code plugins reference", url: "https://code.claude.com/docs/en/plugins-reference" },
+      { label: "Claude Code hooks guide", url: "https://code.claude.com/docs/en/hooks-guide" },
       { label: "Claude Code hooks docs", url: "https://code.claude.com/docs/en/hooks" },
-      { label: "Claude Code skills docs", url: "https://code.claude.com/docs/en/skills" }
+      { label: "Claude Code skills docs", url: "https://code.claude.com/docs/en/skills" },
+      { label: "Claude Code sub-agents docs", url: "https://code.claude.com/docs/en/sub-agents" },
+      { label: "Claude Code env vars docs", url: "https://code.claude.com/docs/en/env-vars" }
     ]
   },
   "cursor": {
     platform: "cursor",
-    summary: "Cursor plugins use .cursor-plugin/plugin.json plus auto-discovered rules, skills, agents, commands, hooks, and mcp.json at the plugin root; Cursor subagents are a related but separate surface under .cursor/agents and ~/.cursor/agents.",
+    summary: "Cursor plugins use .cursor-plugin/plugin.json plus native rules, skills, hooks, MCP, marketplace metadata, and subagent surfaces, with additional project and user config outside the plugin bundle.",
     limits: PLATFORM_LIMITS["cursor"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["cursor"],
     skillDiscoveryDirs: [
       { path: "skills/", level: "supported" },
-      { path: "SKILL.md", level: "fallback", notes: "Used when no skills directory or manifest skill path is present." }
+      { path: ".cursor/skills/", level: "supported" },
+      { path: "~/.cursor/skills/", level: "supported" },
+      { path: ".agents/skills/", level: "supported" },
+      { path: "~/.agents/skills/", level: "supported" },
+      { path: ".claude/skills/", level: "supported", notes: "Compatibility directory" },
+      { path: ".codex/skills/", level: "supported", notes: "Compatibility directory" }
     ],
     frontmatter: {
       standard: [...STANDARD_SKILL_FRONTMATTER],
-      additional: []
+      additional: [],
+      notes: "Cursor skills document the shared frontmatter set plus compatibility metadata and supporting-file patterns."
     },
     manifest: {
       files: [".cursor-plugin/plugin.json"],
@@ -7864,16 +7946,16 @@ var PLATFORM_VALIDATION_RULES = {
       notes: "Cursor documents plugin.json as the required plugin manifest."
     },
     mcp: {
-      files: ["mcp.json"],
+      files: ["mcp.json", ".cursor/mcp.json", "~/.cursor/mcp.json"],
       rootKey: "mcpServers",
-      transports: ["stdio", "http", "sse"],
-      auth: ["headers", "env interpolation"]
+      transports: ["stdio", "sse", "streamable-http"],
+      auth: ["headers", "env interpolation", "OAuth", "static OAuth credentials"]
     },
     hooks: {
       supported: true,
-      files: ["hooks/hooks.json"],
-      eventNames: [],
-      notes: "Cursor plugin hooks live under hooks/hooks.json; project hooks also exist separately in .cursor/hooks.json."
+      files: ["hooks/hooks.json", ".cursor/hooks.json", "~/.cursor/hooks.json"],
+      eventNames: ["sessionStart", "preToolUse", "postToolUse", "subagentStart", "subagentStop", "beforeShellExecution", "afterShellExecution"],
+      notes: "Cursor plugin hooks live under hooks/hooks.json; project and user hooks also exist separately and reload on save."
     },
     instructions: {
       files: ["rules/", "AGENTS.md"],
@@ -7881,25 +7963,32 @@ var PLATFORM_VALIDATION_RULES = {
       notes: "rules/ is the plugin-native instruction surface. AGENTS.md remains useful as shared repo guidance. Cursor subagents use markdown files under .cursor/agents or ~/.cursor/agents (with .claude/.codex compatibility paths)."
     },
     sources: [
-      { label: "Cursor plugins reference", url: "https://cursor.com/docs/reference/plugins" },
       { label: "Cursor plugins overview", url: "https://cursor.com/docs/plugins" },
       { label: "Cursor hooks docs", url: "https://cursor.com/docs/hooks" },
       { label: "Cursor skills docs", url: "https://cursor.com/docs/skills" },
       { label: "Cursor rules docs", url: "https://cursor.com/docs/rules" },
       { label: "Cursor MCP docs", url: "https://cursor.com/docs/mcp" },
       { label: "Cursor CLI headless docs", url: "https://cursor.com/docs/cli/headless" },
+      { label: "Cursor CLI slash commands", url: "https://cursor.com/docs/cli/reference/slash-commands" },
       { label: "Cursor CLI parameters", url: "https://cursor.com/docs/cli/reference/parameters" },
       { label: "Cursor CLI authentication", url: "https://cursor.com/docs/cli/reference/authentication" },
+      { label: "Cursor CLI permissions", url: "https://cursor.com/docs/cli/reference/permissions" },
+      { label: "Cursor CLI configuration", url: "https://cursor.com/docs/cli/reference/configuration" },
+      { label: "Cursor ACP docs", url: "https://cursor.com/docs/cli/acp" },
       { label: "Cursor subagents docs", url: "https://cursor.com/docs/subagents" }
     ]
   },
   "codex": {
     platform: "codex",
-    summary: "Codex plugins use .codex-plugin/plugin.json with skills, .mcp.json, optional app mappings, and AGENTS.md; current docs separate plugin packaging from hooks configuration and do not document plugin-provided slash commands.",
+    summary: "Codex plugins use .codex-plugin/plugin.json with skills, optional .mcp.json and .app.json, marketplace catalogs, cache installs, AGENTS.md instructions, and separate hook configuration.",
     limits: PLATFORM_LIMITS["codex"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["codex"],
     skillDiscoveryDirs: [
-      { path: "skills/", level: "supported" }
+      { path: "skills/", level: "supported" },
+      { path: "$CWD/.agents/skills/", level: "supported" },
+      { path: "ancestor .agents/skills/", level: "supported", notes: "Walks upward until repo root" },
+      { path: "$HOME/.agents/skills/", level: "supported" },
+      { path: "/etc/codex/skills/", level: "supported" }
     ],
     frontmatter: {
       standard: [...STANDARD_SKILL_FRONTMATTER],
@@ -7911,68 +8000,95 @@ var PLATFORM_VALIDATION_RULES = {
       notes: "The build plugins guide documents plugin.json, skills/, .mcp.json, .app.json, and assets/ as the standard plugin structure."
     },
     mcp: {
-      files: [".mcp.json"],
+      files: [".mcp.json", ".codex/config.toml"],
       rootKey: "mcpServers",
-      transports: ["stdio", "http", "sse"],
-      auth: ["bearer_token_env_var", "env_http_headers", "http_headers", "platform-managed auth"],
-      notes: "The current build guide documents mcpServers as a path to .mcp.json in the plugin bundle."
+      transports: ["stdio", "streamable-http"],
+      auth: ["bearer token", "OAuth", "header env vars"],
+      notes: "The current build guide documents mcpServers as a path to .mcp.json in the plugin bundle, while active MCP state also lives in config.toml."
     },
     hooks: {
       supported: true,
       files: [".codex/hooks.json", "~/.codex/hooks.json"],
-      eventNames: [],
-      notes: "Codex documents hooks in project/user config, but the current plugin build guide does not document plugin-packaged hooks."
+      eventNames: ["SessionStart", "PreToolUse", "PermissionRequest", "PostToolUse", "UserPromptSubmit", "Stop"],
+      notes: "Codex documents hooks in project/user config, guarded by the codex_hooks feature flag; the current plugin build guide does not document plugin-packaged hooks."
     },
     instructions: {
-      files: ["AGENTS.md"],
-      format: "markdown"
+      files: ["AGENTS.md", "AGENTS.override.md"],
+      format: "markdown",
+      notes: "Codex also supports model instruction overrides plus configurable fallback filenames for project docs."
     },
     sources: [
+      { label: "Codex plugins docs", url: "https://developers.openai.com/codex/plugins" },
       { label: "Codex build plugins docs", url: "https://developers.openai.com/codex/plugins/build" },
+      { label: "Codex CLI features docs", url: "https://developers.openai.com/codex/cli/features" },
+      { label: "Codex CLI reference docs", url: "https://developers.openai.com/codex/cli/reference" },
+      { label: "Codex slash commands docs", url: "https://developers.openai.com/codex/cli/slash-commands" },
+      { label: "Codex advanced config docs", url: "https://developers.openai.com/codex/config-advanced" },
+      { label: "Codex rules docs", url: "https://developers.openai.com/codex/rules" },
       { label: "Codex hooks docs", url: "https://developers.openai.com/codex/hooks" },
       { label: "Codex skills docs", url: "https://developers.openai.com/codex/skills" },
       { label: "Codex MCP docs", url: "https://developers.openai.com/codex/mcp" },
-      { label: "Codex AGENTS.md guide", url: "https://developers.openai.com/codex/guides/agents-md" }
+      { label: "Codex AGENTS.md guide", url: "https://developers.openai.com/codex/guides/agents-md" },
+      { label: "Codex subagents docs", url: "https://developers.openai.com/codex/subagents" },
+      { label: "Codex subagents concept docs", url: "https://developers.openai.com/codex/concepts/subagents" },
+      { label: "Codex noninteractive docs", url: "https://developers.openai.com/codex/noninteractive" },
+      { label: "Codex SDK docs", url: "https://developers.openai.com/codex/sdk" },
+      { label: "Codex agents SDK guide", url: "https://developers.openai.com/codex/guides/agents-sdk" }
     ]
   },
   "opencode": {
     platform: "opencode",
-    summary: "OpenCode plugins are code-first TypeScript or JavaScript modules that register skills, commands, MCP servers, and hook handlers programmatically.",
+    summary: "OpenCode plugins are code-first JS or TS modules loaded from local plugin dirs or npm references in config, with native skills, commands, agents, MCP, and permission surfaces.",
     limits: PLATFORM_LIMITS["opencode"],
     limitPolicies: PLATFORM_LIMIT_POLICIES["opencode"],
     skillDiscoveryDirs: [
-      { path: "skills/", level: "supported" }
+      { path: "skills/", level: "supported" },
+      { path: ".opencode/skills/", level: "supported" },
+      { path: "~/.config/opencode/skills/", level: "supported" },
+      { path: ".claude/skills/", level: "supported", notes: "Compatibility directory" },
+      { path: ".agents/skills/", level: "supported", notes: "Compatibility directory" }
     ],
     frontmatter: {
       standard: [...STANDARD_SKILL_FRONTMATTER],
-      additional: []
+      additional: [],
+      notes: "OpenCode supports Agent Skills semantics, but plugin runtime behavior is code-first rather than manifest-first."
     },
     manifest: {
-      files: ["package.json", "index.ts"],
-      required: true,
-      notes: "OpenCode plugins are loaded as local modules or npm packages rather than a JSON manifest-only bundle."
+      files: ["opencode.json", ".opencode/plugins/", "~/.config/opencode/plugins/"],
+      required: false,
+      notes: "OpenCode plugins are loaded as local modules or npm packages through config rather than a dedicated manifest-only bundle."
     },
     mcp: {
-      files: ["index.ts"],
+      files: ["opencode.json"],
+      rootKey: "mcp",
       transports: ["local", "remote"],
-      auth: ["headers", "programmatic env interpolation", "OAuth"],
-      notes: 'OpenCode plugin code mutates Config["mcp"] programmatically; the underlying platform config supports local and remote servers.'
+      auth: ["headers", "env interpolation", "OAuth"],
+      notes: "OpenCode config owns MCP; plugins can also extend runtime behavior programmatically."
     },
     hooks: {
       supported: true,
-      files: ["index.ts"],
+      files: ["plugin module (index.ts/index.js)"],
       eventNames: [],
       notes: "OpenCode hooks are plugin event handlers implemented in code, not a separate hooks.json file."
     },
     instructions: {
-      files: ["index.ts"],
-      format: "typescript",
-      notes: "Plugins inject instructions into the runtime system prompt from code."
+      files: ["AGENTS.md", "CLAUDE.md", "opencode.json"],
+      format: "markdown + json + code",
+      notes: "OpenCode supports AGENTS.md, CLAUDE.md fallback, config instructions, and plugin runtime instruction injection."
     },
     sources: [
+      { label: "OpenCode SDK docs", url: "https://opencode.ai/docs/sdk/" },
+      { label: "OpenCode server docs", url: "https://opencode.ai/docs/server/" },
+      { label: "OpenCode config docs", url: "https://opencode.ai/docs/config/" },
       { label: "OpenCode plugins docs", url: "https://opencode.ai/docs/plugins/" },
       { label: "OpenCode skills docs", url: "https://opencode.ai/docs/skills/" },
-      { label: "OpenCode MCP servers docs", url: "https://opencode.ai/docs/mcp-servers/" }
+      { label: "OpenCode commands docs", url: "https://opencode.ai/docs/commands/" },
+      { label: "OpenCode agents docs", url: "https://opencode.ai/docs/agents/" },
+      { label: "OpenCode MCP servers docs", url: "https://opencode.ai/docs/mcp-servers/" },
+      { label: "OpenCode custom tools docs", url: "https://opencode.ai/docs/custom-tools/" },
+      { label: "OpenCode permissions docs", url: "https://opencode.ai/docs/permissions/" },
+      { label: "OpenCode rules docs", url: "https://opencode.ai/docs/rules/" },
+      { label: "OpenCode ACP docs", url: "https://opencode.ai/docs/acp/" }
     ]
   },
   "openhands": {
@@ -8236,7 +8352,8 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       commands: {
         mode: "preserve",
-        nativeSurfaces: ["commands/*.md"]
+        nativeSurfaces: ["commands/*.md", "skills/<skill>/SKILL.md"],
+        notes: "Claude still supports command files, but the product is increasingly converging command workflows into skills."
       },
       agents: {
         mode: "preserve",
@@ -8245,7 +8362,7 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       hooks: {
         mode: "preserve",
-        nativeSurfaces: ["hooks/hooks.json", ".claude-plugin/plugin.json"]
+        nativeSurfaces: ["hooks/hooks.json", ".claude-plugin/plugin.json", "settings hooks", "skill/agent frontmatter hooks"]
       },
       permissions: {
         mode: "translate",
@@ -8258,8 +8375,8 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       distribution: {
         mode: "translate",
-        nativeSurfaces: [".claude-plugin/plugin.json", "install scopes", "user configuration"],
-        notes: "Distribution surfaces are native, but shared brand metadata is narrower than Codex."
+        nativeSurfaces: [".claude-plugin/plugin.json", "marketplaces", "install scopes", "user configuration", "/reload-plugins"],
+        notes: "Distribution surfaces are native, including plugin marketplaces and explicit reload behavior."
       }
     },
     sources: PLATFORM_VALIDATION_RULES["claude-code"].sources
@@ -8278,7 +8395,7 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       commands: {
         mode: "preserve",
-        nativeSurfaces: ["commands/*"]
+        nativeSurfaces: ["commands/*", "slash commands"]
       },
       agents: {
         mode: "translate",
@@ -8296,11 +8413,11 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       runtime: {
         mode: "preserve",
-        nativeSurfaces: ["mcp.json", ".cursor-plugin/plugin.json", "scripts/", "assets/"]
+        nativeSurfaces: ["mcp.json", ".cursor/mcp.json", "~/.cursor/mcp.json", ".cursor-plugin/plugin.json", "scripts/", "assets/"]
       },
       distribution: {
         mode: "preserve",
-        nativeSurfaces: [".cursor-plugin/plugin.json", ".cursor-plugin/marketplace.json", "local marketplace install path"]
+        nativeSurfaces: [".cursor-plugin/plugin.json", ".cursor-plugin/marketplace.json", "local marketplace install path", "reload window / restart"]
       }
     },
     sources: PLATFORM_VALIDATION_RULES["cursor"].sources
@@ -8343,7 +8460,7 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       distribution: {
         mode: "preserve",
-        nativeSurfaces: [".codex-plugin/plugin.json", "~/.agents/plugins/marketplace.json", "$REPO_ROOT/.agents/plugins/marketplace.json"]
+        nativeSurfaces: [".codex-plugin/plugin.json", "~/.agents/plugins/marketplace.json", "$REPO_ROOT/.agents/plugins/marketplace.json", "cache install path", "restart after update"]
       }
     },
     sources: PLATFORM_VALIDATION_RULES["codex"].sources
@@ -8353,7 +8470,7 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
     buckets: {
       instructions: {
         mode: "translate",
-        nativeSurfaces: ["config instructions", "plugin code"],
+        nativeSurfaces: ["AGENTS.md", "CLAUDE.md", "config instructions", "plugin code"],
         notes: "OpenCode instructions are native, but the surface is config- and code-driven rather than manifest markdown only."
       },
       skills: {
@@ -8366,7 +8483,8 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       agents: {
         mode: "preserve",
-        nativeSurfaces: ["agents/*.md", "config agent definitions"]
+        nativeSurfaces: ["agents/*.md", "config agent definitions"],
+        notes: "OpenCode agents are first-class native surfaces. Prefer permission-first agent config for new builds; legacy tools remains compatibility input, not the preferred emitted shape."
       },
       hooks: {
         mode: "translate",
@@ -8375,15 +8493,16 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       },
       permissions: {
         mode: "preserve",
-        nativeSurfaces: ["config permission", "per-agent overrides"]
+        nativeSurfaces: ["config permission", "per-agent overrides"],
+        notes: "OpenCode permission is keyed by tool name and patterns, including native skill and task controls. Legacy tools booleans are deprecated in favor of permission."
       },
       runtime: {
         mode: "preserve",
-        nativeSurfaces: ["config mcp", "plugin JS/TS runtime", "scripts/", "assets/"]
+        nativeSurfaces: ["opencode.json", "config mcp", "plugin JS/TS runtime", "scripts/", "assets/"]
       },
       distribution: {
         mode: "translate",
-        nativeSurfaces: ["local plugin dir", "npm package", "plugin JS/TS entrypoint"],
+        nativeSurfaces: [".opencode/plugins/", "~/.config/opencode/plugins/", "opencode.json", "npm package", "plugin JS/TS entrypoint"],
         notes: "Distribution is native, but there is no single shared manifest analog to Claude, Cursor, or Codex."
       }
     },
@@ -8686,9 +8805,9 @@ function collectChecks(args) {
   const gitStatus = args.runCommand("git", ["status", "--porcelain"], { cwd: args.rootDir });
   checks.push({
     name: "git-clean",
-    ok: gitStatus.status === 0 && gitStatus.stdout.trim() === "",
+    ok: args.allowDirty || gitStatus.status === 0 && gitStatus.stdout.trim() === "",
     code: "git-clean",
-    detail: gitStatus.status !== 0 ? gitStatus.stderr || gitStatus.stdout || "Unable to read git status" : gitStatus.stdout.trim() === "" ? "Working tree is clean." : "Working tree has uncommitted changes."
+    detail: args.allowDirty ? "Working tree cleanliness check skipped via --allow-dirty." : gitStatus.status !== 0 ? gitStatus.stderr || gitStatus.stdout || "Unable to read git status" : gitStatus.stdout.trim() === "" ? "Working tree is clean." : "Working tree has uncommitted changes."
   });
   if (args.npmEnabled) {
     checks.push({
@@ -8740,6 +8859,7 @@ function planPublish(config, options = {}) {
     config,
     npmEnabled,
     githubReleaseEnabled,
+    allowDirty: options.allowDirty ?? false,
     packageDir,
     packageName,
     githubRepo,
@@ -9003,7 +9123,7 @@ rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
 
 echo "Installed $PLUGIN_NAME to $INSTALL_DIR"
-echo "If Cursor is already open, restart or reload it so the plugin is picked up."
+echo "If Cursor is already open, use Developer: Reload Window or restart Cursor so the plugin is picked up."
 `;
 }
 function renderInstallCodexScript(config) {
@@ -9117,7 +9237,7 @@ NODE
 
 echo "Installed $PLUGIN_NAME to $INSTALL_DIR"
 echo "Updated Codex marketplace catalog at $MARKETPLACE_PATH"
-echo "If Codex is already open, restart it so the plugin is picked up."
+echo "If Codex is already open, use Plugins > Refresh if that action is available in your current UI, or restart Codex so the plugin is picked up."
 `;
 }
 function renderInstallOpenCodeScript(config) {
@@ -9494,7 +9614,7 @@ function getInstallTargets(pluginName) {
     {
       platform: "opencode",
       pluginDir: resolve3(home, ".config/opencode/plugins", pluginName),
-      description: `~/.config/opencode/plugins/${pluginName}.ts`
+      description: `~/.config/opencode/plugins/${pluginName}.ts + ~/.config/opencode/plugins/${pluginName}/`
     },
     {
       platform: "github-copilot",

package/dist/permissions.d.ts

@@ -8,7 +8,7 @@ export interface ParsedPermissionRule {
     pattern: string;
 }
 export interface OpenCodePermissionMap {
-    [tool: string]: PermissionAction;
+    [tool: string]: PermissionAction | Record<string, PermissionAction>;
 }
 export declare function parsePermissionRule(raw: string): Omit<ParsedPermissionRule, 'action'> | null;
 export declare function collectPermissionRules(permissions: Partial<Record<PermissionAction, string[]>> | undefined): ParsedPermissionRule[];

package/dist/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,yBAAyB,mDAAoD,CAAA;AAE1F,MAAM,MAAM,kBAAkB,GAAG,OAAO,yBAAyB,CAAC,MAAM,CAAC,CAAA;AACzE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAA;AAEvD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,gBAAgB,CAAA;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,kBAAkB,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAA;CACjC;AAMD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,GAAG,IAAI,CAc5F;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,GACnE,oBAAoB,EAAE,CAkBxB;AAaD,wBAAgB,qCAAqC,CACnD,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,GACnE,OAAO,CAET;AAED,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,GACnE,qBAAqB,CAqBvB;AAED,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,GACnE,MAAM,GAAG,IAAI,CA6Jf"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,yBAAyB,mDAAoD,CAAA;AAE1F,MAAM,MAAM,kBAAkB,GAAG,OAAO,yBAAyB,CAAC,MAAM,CAAC,CAAA;AACzE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAA;AAEvD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,gBAAgB,CAAA;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,kBAAkB,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CACpE;AAMD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,GAAG,IAAI,CAc5F;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,GACnE,oBAAoB,EAAE,CAkBxB;AAaD,wBAAgB,qCAAqC,CACnD,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,GACnE,OAAO,CAET;AAED,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,GACnE,qBAAqB,CAkBvB;AAiED,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,GACnE,MAAM,GAAG,IAAI,CA8Jf"}