codex-plugin-doctor 0.8.0 → 0.10.0

package/README.md

@@ -87,9 +87,10 @@ If you already have Codex installed locally and do not know plugin paths, discov
 
 ```bash
 codex-plugin-doctor list --installed
-codex-plugin-doctor check --installed
-codex-plugin-doctor check --installed --all-summary
-codex-plugin-doctor check --installed github
+codex-plugin-doctor check --installed
+codex-plugin-doctor check --installed --all-summary
+codex-plugin-doctor check --installed --compat --all-summary
+codex-plugin-doctor check --installed github
 codex-plugin-doctor explain plugin.manifest.missing
 ```
 
@@ -161,11 +162,17 @@ x plugin.security.hard_coded_secret
 Run these from a Codex plugin package root:
 
 ```bash
-codex-plugin-doctor --version
+codex-plugin-doctor --version
 codex-plugin-doctor self-test
 codex-plugin-doctor doctor
+codex-plugin-doctor doctor clients
+codex-plugin-doctor doctor --update-check
 codex-plugin-doctor init my-plugin
+codex-plugin-doctor init my-mcp --template mcp-stdio
+codex-plugin-doctor init remote-mcp --template mcp-http
+codex-plugin-doctor init runtime-demo --template full-runtime
 codex-plugin-doctor compat .
+codex-plugin-doctor compat . --all --scorecard
 codex-plugin-doctor compat . --client codex
 codex-plugin-doctor compat . --client generic-mcp
 codex-plugin-doctor compat . --client claude-desktop
@@ -184,6 +191,7 @@ codex-plugin-doctor check . --profile ci
 codex-plugin-doctor check . --profile strict
 codex-plugin-doctor check . --profile publish
 codex-plugin-doctor check . --json
+codex-plugin-doctor check . --explain
 codex-plugin-doctor check . --json --output report.json
 codex-plugin-doctor check . --markdown --output report.md
 codex-plugin-doctor check . --badge-json --output doctor-badge.json
@@ -198,13 +206,16 @@ codex-plugin-doctor history validation-history.jsonl
 codex-plugin-doctor history validation-history.jsonl --json
 codex-plugin-doctor history validation-history.jsonl --fail-on-regression
 codex-plugin-doctor fix . --dry-run
+codex-plugin-doctor fix . --interactive --backup
 codex-plugin-doctor fix . --apply --backup
 codex-plugin-doctor check . --json --runtime --verbose-runtime
 ```
 
 `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
 
-`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility.
+`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
+
+`init [path] --template ...` creates targeted starter packages. `skill-only` is the default minimal skill package, `mcp-stdio` adds a local stdio MCP config and mock server, `mcp-http` scaffolds a streamable HTTP MCP config, and `full-runtime` generates a stdio sample that passes the runtime protocol probes.
 
 `compat --client claude-desktop` checks whether the MCP package can be added to the local Claude Desktop setup. On Windows it looks for `%APPDATA%\Claude\claude_desktop_config.json`; on macOS it looks for `~/Library/Application Support/Claude/claude_desktop_config.json`. A valid existing config returns `PASS`, a missing Claude Desktop install returns `WARN`, and a malformed local config returns `FAIL` so you do not add new servers into a broken config file. If the package server name already exists in Claude Desktop, the command returns `WARN` with the duplicate server name. Add `--install-preview` to print the JSON snippet that should be merged into `claude_desktop_config.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
 
@@ -212,15 +223,19 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `compat --client cline` checks whether the MCP package can be added to Cline. It uses `CLINE_DIR/data/settings/cline_mcp_settings.json` when `CLINE_DIR` is set, otherwise `~/.cline/data/settings/cline_mcp_settings.json`. Add `--install-preview` to print the JSON snippet that should be merged into `cline_mcp_settings.json`.
 
-`compat --scorecard` turns the compatibility matrix into a compact score summary. `PASS` maps to `100`, `WARN` maps to `70`, and `FAIL` or `SKIPPED` maps to `0`.
+`compat --all` makes the all-client matrix explicit when you want Codex, Generic MCP, Claude Desktop, Cursor, Cline, and Windsurf in one run. `compat --scorecard` turns the compatibility matrix into a compact score summary. `PASS` maps to `100`, `WARN` maps to `70`, and `FAIL` or `SKIPPED` maps to `0`.
+
+`check --installed --compat --all-summary` validates every discovered Codex plugin from the local plugin cache and appends a compact compatibility summary for Codex, Generic MCP, Claude Desktop, Cursor, Cline, and Windsurf. This is the fastest repo-free audit when a user does not know individual plugin paths.
 
 `check --profile ci|strict|publish` applies named validation policies. `ci` keeps default behavior, `strict` fails on warnings, and `publish` fails on warnings while enabling runtime probing by default.
 
+`check --explain` adds inline rule catalog context to text reports, including why a finding matters, a more detailed fix path, and a compact example.
+
 `check --badge-json` emits Shields endpoint-compatible JSON such as `{"schemaVersion":1,"label":"doctor","message":"PASS","color":"brightgreen"}`. `check --badge-markdown` emits a static shields.io Markdown badge for README or release notes. Badge output is intentionally limited to single package checks, not `check --installed`.
 
 `check --history <path>` appends a compact JSONL validation snapshot after a single package check. `history <path>` reads the JSONL file and compares the latest run to the previous run, including status, finding-count deltas, and whether the latest run regressed. Add `history --json` for automation output or `history --fail-on-regression` when CI should fail after a worse latest run.
 
-`fix --dry-run` renders safe automatic fix plans without changing files. `fix --apply --backup` applies only supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.
+`fix --dry-run` renders safe automatic fix plans without changing files. `fix --interactive --backup` shows the same numbered plan, then applies everything after `yes` or only selected action numbers such as `1,3`. `fix --apply --backup` applies supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.
 
 Optional local policy file:
 
@@ -235,9 +250,10 @@ Run these when you want Codex Plugin Doctor to find plugins from the local Codex
 
 ```bash
 codex-plugin-doctor list --installed
-codex-plugin-doctor check --installed
-codex-plugin-doctor check --installed --all-summary
-codex-plugin-doctor check --installed github
+codex-plugin-doctor check --installed
+codex-plugin-doctor check --installed --all-summary
+codex-plugin-doctor check --installed --compat --all-summary
+codex-plugin-doctor check --installed github
 codex-plugin-doctor check --installed github --runtime --no-animations
 codex-plugin-doctor explain plugin.security.hard_coded_secret
 ```
@@ -255,9 +271,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: Esquetta/CodexPluginDoctor@v0.8.0
+      - uses: Esquetta/CodexPluginDoctor@v0.9.0
         with:
-          version: "0.8.0"
+          version: "0.9.0"
           path: .
           runtime: "false"
 ```
@@ -300,11 +316,12 @@ Recent validation waves covered:
 
 Release preparation is reproducible from the repository:
 
-```bash
-npm run prepare-release
-```
-
-This runs tests, builds the TypeScript output, and performs `npm pack --dry-run`.
+```bash
+npm run prepare-release
+npm run release-check
+```
+
+`prepare-release` runs tests, builds the TypeScript output, and performs `npm pack --dry-run`. `release-check` adds release preflight checks for a clean git tree, existing npm versions, existing version tags, tests, build, and pack dry-run.
 
 Related docs:
 

package/dist/core/environment-doctor.d.ts

@@ -14,6 +14,16 @@ export interface EnvironmentDoctorReport {
         path: string | null;
     };
 }
+export interface ClientDoctorResult {
+    client: string;
+    status: "pass" | "warn";
+    configPath: string | null;
+    configExists: boolean;
+    directoryWritable: boolean;
+    summary: string;
+}
 export declare function renderEnvironmentDoctor(terminalContext: CliTerminalContext): Promise<string>;
+export declare function buildClientDoctorReport(terminalContext: CliTerminalContext): Promise<ClientDoctorResult[]>;
+export declare function renderClientDoctor(terminalContext: CliTerminalContext): Promise<string>;
 export declare function buildEnvironmentDoctorReport(terminalContext: CliTerminalContext): Promise<EnvironmentDoctorReport>;
 export declare function renderEnvironmentDoctorJson(terminalContext: CliTerminalContext): Promise<string>;

package/dist/core/environment-doctor.js

@@ -1,3 +1,4 @@
+import { constants } from "node:fs";
 import { access } from "node:fs/promises";
 import path from "node:path";
 import { packageVersion } from "../version.js";
@@ -10,6 +11,15 @@ async function pathExists(targetPath) {
         return false;
     }
 }
+async function pathWritable(targetPath) {
+    try {
+        await access(targetPath, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function resolveCodexHome(env) {
     if (env.CODEX_HOME) {
         return path.resolve(env.CODEX_HOME);
@@ -22,6 +32,89 @@ function resolveCodexHome(env) {
     }
     return null;
 }
+function resolveHomeDirectory(env) {
+    return env.USERPROFILE ?? env.HOME ?? null;
+}
+function resolveClaudeConfigPath(terminalContext) {
+    const platform = terminalContext.platform ?? process.platform;
+    const homeDirectory = resolveHomeDirectory(terminalContext.env);
+    if (platform === "win32") {
+        return terminalContext.env.APPDATA
+            ? path.join(terminalContext.env.APPDATA, "Claude", "claude_desktop_config.json")
+            : null;
+    }
+    if (platform === "darwin" && homeDirectory) {
+        return path.join(homeDirectory, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    return null;
+}
+function resolveClineConfigPath(env) {
+    const homeDirectory = resolveHomeDirectory(env);
+    const clineDirectory = env.CLINE_DIR
+        ? path.resolve(env.CLINE_DIR)
+        : homeDirectory
+            ? path.join(homeDirectory, ".cline")
+            : null;
+    return clineDirectory
+        ? path.join(clineDirectory, "data", "settings", "cline_mcp_settings.json")
+        : null;
+}
+function resolveClientConfigPaths(terminalContext) {
+    const env = terminalContext.env;
+    const homeDirectory = resolveHomeDirectory(env);
+    return [
+        {
+            client: "Codex",
+            configPath: resolveCodexHome(env)
+        },
+        {
+            client: "Claude Desktop",
+            configPath: resolveClaudeConfigPath(terminalContext)
+        },
+        {
+            client: "Cursor",
+            configPath: homeDirectory ? path.join(homeDirectory, ".cursor", "mcp.json") : null
+        },
+        {
+            client: "Cline",
+            configPath: resolveClineConfigPath(env)
+        },
+        {
+            client: "Windsurf",
+            configPath: homeDirectory
+                ? path.join(homeDirectory, ".codeium", "windsurf", "mcp_config.json")
+                : null
+        }
+    ];
+}
+async function inspectClientConfig(client, configPath) {
+    if (!configPath) {
+        return {
+            client,
+            status: "warn",
+            configPath,
+            configExists: false,
+            directoryWritable: false,
+            summary: "Config path could not be resolved."
+        };
+    }
+    const configExists = await pathExists(configPath);
+    const directory = client === "Codex" ? configPath : path.dirname(configPath);
+    const directoryExists = await pathExists(directory);
+    const directoryWritable = directoryExists ? await pathWritable(directory) : false;
+    return {
+        client,
+        status: configExists || directoryWritable ? "pass" : "warn",
+        configPath,
+        configExists,
+        directoryWritable,
+        summary: configExists
+            ? "Config path exists."
+            : directoryWritable
+                ? "Config directory exists and is writable."
+                : "Config path was not detected on this machine."
+    };
+}
 export async function renderEnvironmentDoctor(terminalContext) {
     const report = await buildEnvironmentDoctorReport(terminalContext);
     return [
@@ -32,9 +125,35 @@ export async function renderEnvironmentDoctor(terminalContext) {
         `Node: ${report.node}`,
         `npm global prefix: ${report.npmGlobalPrefix}`,
         `Codex home: ${report.codexHome.status.toUpperCase()}${report.codexHome.path ? ` (${report.codexHome.path})` : ""}`,
-        `Codex plugin cache: ${report.codexPluginCache.status.toUpperCase()}${report.codexPluginCache.path ? ` (${report.codexPluginCache.path})` : ""}`
+        `Codex plugin cache: ${report.codexPluginCache.status.toUpperCase()}${report.codexPluginCache.path ? ` (${report.codexPluginCache.path})` : ""}`,
+        "",
+        "Recommended next commands",
+        "-------------------------",
+        "codex-plugin-doctor self-test",
+        "codex-plugin-doctor list --installed",
+        "codex-plugin-doctor check . --runtime --explain",
+        "codex-plugin-doctor compat . --all --scorecard",
+        "codex-plugin-doctor init-ci ."
     ].join("\n");
 }
+export async function buildClientDoctorReport(terminalContext) {
+    return Promise.all(resolveClientConfigPaths(terminalContext).map((item) => inspectClientConfig(item.client, item.configPath)));
+}
+export async function renderClientDoctor(terminalContext) {
+    const results = await buildClientDoctorReport(terminalContext);
+    const lines = [
+        "Codex Plugin Doctor Clients",
+        "===========================",
+        ""
+    ];
+    for (const result of results) {
+        lines.push(`${result.client}: ${result.status.toUpperCase()} - ${result.summary}`);
+        lines.push(`  Config: ${result.configPath ?? "(unknown)"}`);
+        lines.push(`  Exists: ${result.configExists ? "yes" : "no"}`);
+        lines.push(`  Writable: ${result.directoryWritable ? "yes" : "no"}`);
+    }
+    return lines.join("\n");
+}
 export async function buildEnvironmentDoctorReport(terminalContext) {
     const codexHome = resolveCodexHome(terminalContext.env);
     const codexHomeExists = codexHome ? await pathExists(codexHome) : false;

package/dist/core/fix-plan.d.ts

@@ -14,6 +14,9 @@ export interface ApplyFixPlanResult {
     filesChanged: number;
     backupDirectory: string;
 }
+export interface ApplyFixPlanOptions {
+    actionIndexes?: number[];
+}
 export interface FixPlanJsonReport {
     schemaVersion: "1.0.0";
     mode: "dry-run" | "apply";
@@ -25,8 +28,8 @@ export interface FixPlanJsonReport {
     }>;
 }
 export declare function buildFixPlan(targetPath: string): Promise<FixPlan>;
-export declare function renderFixPlan(plan: FixPlan, mode: "dry-run"): string;
-export declare function applyFixPlan(targetPath: string): Promise<ApplyFixPlanResult>;
+export declare function renderFixPlan(plan: FixPlan, mode: "dry-run" | "interactive"): string;
+export declare function applyFixPlan(targetPath: string, options?: ApplyFixPlanOptions): Promise<ApplyFixPlanResult>;
 export declare function renderApplyFixResult(result: ApplyFixPlanResult): string;
 export declare function renderFixPlanJsonReport(plan: FixPlan, options: {
     mode: "dry-run" | "apply";

package/dist/core/fix-plan.js

@@ -167,11 +167,19 @@ async function backupFile(rootPath, backupDirectory, filePath) {
     await mkdir(path.dirname(backupPath), { recursive: true });
     await copyFile(filePath, backupPath);
 }
-export async function applyFixPlan(targetPath) {
+export async function applyFixPlan(targetPath, options = {}) {
     const plan = await buildFixPlan(targetPath);
+    const selectedIndexes = new Set(options.actionIndexes ?? []);
+    const actions = selectedIndexes.size === 0
+        ? plan.actions
+        : plan.actions.filter((_, index) => selectedIndexes.has(index + 1));
+    const appliedPlan = {
+        ...plan,
+        actions
+    };
     const backupDirectory = path.join(plan.targetPath, ".codex-doctor-backups", timestampForPath());
     let filesChanged = 0;
-    for (const action of plan.actions) {
+    for (const action of appliedPlan.actions) {
         if (action.operation === "update-json" && action.id === "manifest.safe_defaults") {
             await backupFile(plan.targetPath, backupDirectory, action.targetPath);
             const manifest = JSON.parse(await readFile(action.targetPath, "utf8"));
@@ -210,7 +218,7 @@ export async function applyFixPlan(targetPath) {
         }
     }
     return {
-        plan,
+        plan: appliedPlan,
         filesChanged,
         backupDirectory
     };

package/dist/core/init-plugin.d.ts

@@ -1,6 +1,15 @@
+export declare const initPluginTemplates: readonly ["skill-only", "mcp-stdio", "mcp-http", "full-runtime"];
+export type InitPluginTemplate = (typeof initPluginTemplates)[number];
+export interface InitPluginOptions {
+    template?: InitPluginTemplate;
+}
 export interface InitPluginResult {
     rootPath: string;
     manifestPath: string;
     skillPath: string;
+    template: InitPluginTemplate;
+    mcpConfigPath?: string;
+    serverPath?: string;
 }
-export declare function initPluginPackage(targetPath: string): Promise<InitPluginResult>;
+export declare function isInitPluginTemplate(value: string): value is InitPluginTemplate;
+export declare function initPluginPackage(targetPath: string, options?: InitPluginOptions): Promise<InitPluginResult>;

package/dist/core/init-plugin.js

@@ -1,39 +1,186 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+export const initPluginTemplates = [
+    "skill-only",
+    "mcp-stdio",
+    "mcp-http",
+    "full-runtime"
+];
 function toPackageName(inputPath) {
     return path.basename(path.resolve(inputPath))
         .toLowerCase()
         .replace(/[^a-z0-9-]+/g, "-")
         .replace(/^-+|-+$/g, "") || "codex-plugin";
 }
-export async function initPluginPackage(targetPath) {
+export function isInitPluginTemplate(value) {
+    return initPluginTemplates.includes(value);
+}
+function buildSkillMarkdown(template) {
+    const description = template === "skill-only"
+        ? "Use when verifying that this Codex plugin package loads correctly."
+        : "Use when testing this Codex plugin package and its bundled MCP server.";
+    return [
+        "---",
+        "name: hello",
+        `description: ${description}`,
+        "---",
+        "",
+        "# Hello",
+        "",
+        template === "skill-only"
+            ? "This starter skill confirms the plugin package structure is valid."
+            : "This starter skill confirms the plugin package and MCP server wiring are valid.",
+        ""
+    ].join("\n");
+}
+function buildStdioMcpConfig(packageName) {
+    return `${JSON.stringify({
+        mcpServers: {
+            [packageName]: {
+                command: "node",
+                args: ["./mock-server.js"]
+            }
+        }
+    }, null, 2)}\n`;
+}
+function buildHttpMcpConfig(packageName) {
+    return `${JSON.stringify({
+        mcpServers: {
+            [packageName]: {
+                url: "http://localhost:8787/mcp"
+            }
+        }
+    }, null, 2)}\n`;
+}
+function buildFullRuntimeServer() {
+    return [
+        "const readline = require(\"node:readline\");",
+        "",
+        "const rl = readline.createInterface({",
+        "  input: process.stdin,",
+        "  crlfDelay: Infinity",
+        "});",
+        "",
+        "function send(id, payload) {",
+        "  process.stdout.write(`${JSON.stringify({ jsonrpc: \"2.0\", id, ...payload })}\\n`);",
+        "}",
+        "",
+        "rl.on(\"line\", (line) => {",
+        "  const message = JSON.parse(line);",
+        "  const cursor = message.params && message.params.cursor;",
+        "",
+        "  if (message.method === \"initialize\") {",
+        "    send(message.id, {",
+        "      result: {",
+        "        protocolVersion: \"2025-11-25\",",
+        "        capabilities: { tools: {}, resources: {}, prompts: {} },",
+        "        serverInfo: { name: \"codex-plugin-template\", version: \"0.1.0\" }",
+        "      }",
+        "    });",
+        "    return;",
+        "  }",
+        "",
+        "  if (message.method === \"tools/list\") {",
+        "    send(message.id, {",
+        "      result: cursor === \"tools-page-2\"",
+        "        ? { tools: [{ name: \"format_status\", description: \"Return a formatted health status.\", inputSchema: { type: \"object\", properties: {}, required: [] } }] }",
+        "        : { tools: [{ name: \"ping\", description: \"Return a healthcheck response.\", inputSchema: { type: \"object\", properties: {}, required: [] } }], nextCursor: \"tools-page-2\" }",
+        "    });",
+        "    return;",
+        "  }",
+        "",
+        "  if (message.method === \"tools/call\") {",
+        "    send(message.id, { result: { content: [{ type: \"text\", text: \"codex-plugin-template-ok\" }] } });",
+        "    return;",
+        "  }",
+        "",
+        "  if (message.method === \"resources/list\") {",
+        "    send(message.id, {",
+        "      result: cursor === \"resources-page-2\"",
+        "        ? { resources: [{ name: \"workspace-license\", uri: \"file:///workspace/LICENSE\" }] }",
+        "        : { resources: [{ name: \"workspace-readme\", uri: \"file:///workspace/README.md\" }], nextCursor: \"resources-page-2\" }",
+        "    });",
+        "    return;",
+        "  }",
+        "",
+        "  if (message.method === \"resources/read\") {",
+        "    send(message.id, { result: { contents: [{ uri: \"file:///workspace/README.md\", text: \"# Workspace README\" }] } });",
+        "    return;",
+        "  }",
+        "",
+        "  if (message.method === \"resources/templates/list\") {",
+        "    send(message.id, {",
+        "      result: cursor === \"templates-page-2\"",
+        "        ? { resourceTemplates: [{ name: \"log\", uriTemplate: \"file:///workspace/logs/{name}.log\" }] }",
+        "        : { resourceTemplates: [{ name: \"doc\", uriTemplate: \"file:///workspace/docs/{name}.md\" }], nextCursor: \"templates-page-2\" }",
+        "    });",
+        "    return;",
+        "  }",
+        "",
+        "  if (message.method === \"prompts/list\") {",
+        "    send(message.id, {",
+        "      result: cursor === \"prompts-page-2\"",
+        "        ? { prompts: [{ name: \"summary\", description: \"Summarize the current change.\" }] }",
+        "        : { prompts: [{ name: \"code_review\", description: \"Review code for bugs.\", arguments: [{ name: \"diff\", required: true }] }], nextCursor: \"prompts-page-2\" }",
+        "    });",
+        "    return;",
+        "  }",
+        "",
+        "  if (message.method === \"prompts/get\") {",
+        "    if (!message.params || !message.params.arguments || message.params.arguments.diff !== \"codex-plugin-doctor-probe\") {",
+        "      send(message.id, { error: { code: -32602, message: \"Missing required diff argument\" } });",
+        "      return;",
+        "    }",
+        "",
+        "    send(message.id, {",
+        "      result: {",
+        "        description: \"Prompt for code review\",",
+        "        messages: [{ role: \"user\", content: { type: \"text\", text: \"Review this diff for bugs.\" } }]",
+        "      }",
+        "    });",
+        "    return;",
+        "  }",
+        "",
+        "  send(message.id, { error: { code: -32601, message: `Unsupported method: ${message.method}` } });",
+        "});",
+        ""
+    ].join("\n");
+}
+export async function initPluginPackage(targetPath, options = {}) {
+    const template = options.template ?? "skill-only";
     const rootPath = path.resolve(targetPath);
     const manifestDirectory = path.join(rootPath, ".codex-plugin");
     const skillsDirectory = path.join(rootPath, "skills", "hello");
     const manifestPath = path.join(manifestDirectory, "plugin.json");
     const skillPath = path.join(skillsDirectory, "SKILL.md");
+    const mcpConfigPath = path.join(rootPath, ".mcp.json");
+    const serverPath = path.join(rootPath, "mock-server.js");
+    const packageName = toPackageName(rootPath);
     await mkdir(manifestDirectory, { recursive: true });
     await mkdir(skillsDirectory, { recursive: true });
     await writeFile(manifestPath, `${JSON.stringify({
-        name: toPackageName(rootPath),
+        name: packageName,
         version: "0.1.0",
         description: "A Codex plugin package scaffolded by Codex Plugin Doctor.",
-        skills: "skills"
+        skills: "skills",
+        ...(template === "skill-only" ? {} : { mcpServers: ".mcp.json" })
     }, null, 2)}\n`, "utf8");
-    await writeFile(skillPath, [
-        "---",
-        "name: hello",
-        "description: Use when verifying that this Codex plugin package loads correctly.",
-        "---",
-        "",
-        "# Hello",
-        "",
-        "This starter skill confirms the plugin package structure is valid.",
-        ""
-    ].join("\n"), "utf8");
+    await writeFile(skillPath, buildSkillMarkdown(template), "utf8");
+    if (template === "mcp-stdio" || template === "full-runtime") {
+        await writeFile(mcpConfigPath, buildStdioMcpConfig(packageName), "utf8");
+        await writeFile(serverPath, buildFullRuntimeServer(), "utf8");
+    }
+    if (template === "mcp-http") {
+        await writeFile(mcpConfigPath, buildHttpMcpConfig(packageName), "utf8");
+    }
     return {
         rootPath,
         manifestPath,
-        skillPath
+        skillPath,
+        template,
+        mcpConfigPath: template === "skill-only" ? undefined : mcpConfigPath,
+        serverPath: template === "mcp-stdio" || template === "full-runtime"
+            ? serverPath
+            : undefined
     };
 }

package/dist/reporting/render-installed-summary.d.ts

@@ -1,7 +1,9 @@
 import type { CheckResult } from "../domain/types.js";
 import type { InstalledPlugin } from "../core/discover-installed-plugins.js";
+import type { CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
 export interface InstalledPluginCheckResult {
     plugin: InstalledPlugin;
     result: CheckResult;
+    compatibilityMatrix?: CompatibilityMatrix;
 }
 export declare function renderInstalledSummary(checkedPlugins: InstalledPluginCheckResult[]): string;

package/dist/reporting/render-installed-summary.js

@@ -1,3 +1,36 @@
+function statusLabel(status) {
+    return status.toUpperCase();
+}
+function statusCount(matrix, status) {
+    return matrix.results.filter((result) => result.status === status).length;
+}
+function renderCompatibilitySummary(checkedPlugins) {
+    const pluginsWithCompatibility = checkedPlugins.filter((item) => item.compatibilityMatrix);
+    if (pluginsWithCompatibility.length === 0) {
+        return [];
+    }
+    const lines = [
+        "",
+        "Installed Compatibility Summary",
+        "===============================",
+        `Checked: ${pluginsWithCompatibility.length}`,
+        "",
+        "Clients",
+        "-------"
+    ];
+    for (const item of pluginsWithCompatibility) {
+        const matrix = item.compatibilityMatrix;
+        if (!matrix) {
+            continue;
+        }
+        lines.push("", `${item.plugin.name} - ${item.plugin.relativePath}`);
+        lines.push(`  Score: ${statusCount(matrix, "pass")} pass, ${statusCount(matrix, "warn")} warn, ${statusCount(matrix, "fail")} fail, ${statusCount(matrix, "skipped")} skipped`);
+        for (const result of matrix.results) {
+            lines.push(`  ${result.client}: ${statusLabel(result.status)} - ${result.summary}`);
+        }
+    }
+    return lines;
+}
 export function renderInstalledSummary(checkedPlugins) {
     const passCount = checkedPlugins.filter((item) => item.result.status === "pass").length;
     const warnCount = checkedPlugins.filter((item) => item.result.status === "warn").length;
@@ -18,5 +51,6 @@ export function renderInstalledSummary(checkedPlugins) {
         const suffix = findingIds.length > 0 ? ` (${findingIds.join(", ")})` : "";
         lines.push(`${item.result.status.toUpperCase()} ${item.plugin.name} - ${item.plugin.relativePath}${suffix}`);
     }
+    lines.push(...renderCompatibilitySummary(checkedPlugins));
     return lines.join("\n");
 }

package/dist/reporting/render-text-report.d.ts

@@ -1,4 +1,5 @@
 import type { CheckResult } from "../domain/types.js";
 export declare function renderTextReport(result: CheckResult, options?: {
     ascii?: boolean;
+    explain?: boolean;
 }): string;

package/dist/reporting/render-text-report.js

@@ -1,3 +1,4 @@
+import { findRuleDefinition } from "../rules/rule-catalog.js";
 function getCounts(result) {
     const failCount = result.findings.filter((finding) => finding.severity === "fail").length;
     const warnCount = result.findings.filter((finding) => finding.severity === "warn").length;
@@ -22,6 +23,7 @@ function getGlyphs(ascii) {
 }
 export function renderTextReport(result, options = {}) {
     const ascii = options.ascii ?? false;
+    const explain = options.explain ?? false;
     const glyphs = getGlyphs(ascii);
     const { failCount, warnCount, totalCount } = getCounts(result);
     const lines = [
@@ -58,6 +60,14 @@ export function renderTextReport(result, options = {}) {
             lines.push(`  Message: ${finding.message}`);
             lines.push(`  Impact: ${finding.impact}`);
             lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+            if (explain) {
+                const rule = findRuleDefinition(finding.id);
+                if (rule) {
+                    lines.push(`  Why: ${rule.why}`);
+                    lines.push(`  Fix detail: ${rule.fix}`);
+                    lines.push(`  Example: ${rule.example}`);
+                }
+            }
         }
     };
     appendSection("Failures", failures, glyphs.fail);

package/dist/run-cli.d.ts

@@ -2,6 +2,7 @@ import { runCheck } from "./index.js";
 export interface CliIo {
     writeStdout(message: string): void;
     writeStderr(message: string): void;
+    readStdin?(prompt: string): Promise<string>;
 }
 export interface CliTerminalContext {
     stdoutIsTTY: boolean;
@@ -12,5 +13,6 @@ export interface CliTerminalContext {
 export interface RunCliOptions {
     terminalContext?: CliTerminalContext;
     runCheckImpl?: typeof runCheck;
+    resolveLatestVersion?: () => Promise<string>;
 }
 export declare function runCli(args: string[], io?: CliIo, options?: RunCliOptions): Promise<number>;

package/dist/run-cli.js

@@ -1,5 +1,7 @@
+import { execFile } from "node:child_process";
 import { writeFile } from "node:fs/promises";
 import path from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
 import { appendValidationHistoryEntry, readValidationHistory, summarizeValidationHistory } from "./core/validation-history.js";
@@ -11,9 +13,9 @@ import { buildClineInstallPreview, renderClineInstallPreview } from "./compatibi
 import { buildWindsurfInstallPreview, renderWindsurfInstallPreview } from "./compatibility/windsurf-install-preview.js";
 import { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
 import { applyFixPlan, buildFixPlan, renderApplyFixResult, renderFixPlanJsonReport, renderFixPlan } from "./core/fix-plan.js";
-import { renderEnvironmentDoctor, renderEnvironmentDoctorJson } from "./core/environment-doctor.js";
+import { renderClientDoctor, renderEnvironmentDoctor, renderEnvironmentDoctorJson } from "./core/environment-doctor.js";
 import { initCiWorkflow } from "./core/init-ci.js";
-import { initPluginPackage } from "./core/init-plugin.js";
+import { initPluginPackage, initPluginTemplates, isInitPluginTemplate } from "./core/init-plugin.js";
 import { runCheck } from "./index.js";
 import { renderInstalledSummary } from "./reporting/render-installed-summary.js";
 import { renderBadgeJson, renderBadgeMarkdown } from "./reporting/render-badge-report.js";
@@ -36,10 +38,22 @@ const defaultIo = {
     },
     writeStderr(message) {
         process.stderr.write(`${message}\n`);
+    },
+    async readStdin(prompt) {
+        const readline = createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+        try {
+            return await readline.question(prompt);
+        }
+        finally {
+            readline.close();
+        }
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor fix <path> (--dry-run|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -113,6 +127,42 @@ function renderSelfTestReport(targetPath, validationStatus, findingsCount, compa
         renderCompatibilityScorecard(compatibilityMatrix)
     ].join("\n");
 }
+async function resolveLatestNpmVersion() {
+    return new Promise((resolve, reject) => {
+        execFile("npm", ["view", "codex-plugin-doctor", "version"], { shell: process.platform === "win32" }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new Error(stderr.trim() || error.message));
+                return;
+            }
+            resolve(stdout.trim());
+        });
+    });
+}
+function renderUpdateCheck(latestVersion) {
+    const updateAvailable = latestVersion !== packageVersion;
+    return [
+        "Codex Plugin Doctor Update Check",
+        "================================",
+        `Installed: ${packageVersion}`,
+        `Latest: ${latestVersion}`,
+        `Status: ${updateAvailable ? "UPDATE AVAILABLE" : "UP TO DATE"}`,
+        "",
+        updateAvailable
+            ? "Next: npm install -g codex-plugin-doctor@latest"
+            : "Next: no update needed"
+    ].join("\n");
+}
+function parseSelectedFixActionIndexes(answer, actionCount) {
+    if (!/^\d+(\s*,\s*\d+)*$/.test(answer)) {
+        return null;
+    }
+    const actionIndexes = [...new Set(answer.split(",").map((item) => Number(item.trim())))];
+    return actionIndexes.every((index) => Number.isInteger(index) &&
+        index >= 1 &&
+        index <= actionCount)
+        ? actionIndexes
+        : null;
+}
 export async function runCli(args, io = defaultIo, options = {}) {
     const [command, maybePath, ...remainingArgs] = args;
     if (command === "--version" || command === "-v" || command === "version") {
@@ -133,6 +183,18 @@ export async function runCli(args, io = defaultIo, options = {}) {
         return 0;
     }
     if (command === "doctor") {
+        const doctorFlags = maybePath?.startsWith("--")
+            ? [maybePath, ...remainingArgs]
+            : remainingArgs;
+        if (doctorFlags.includes("--update-check")) {
+            const latestVersion = await (options.resolveLatestVersion ?? resolveLatestNpmVersion)();
+            io.writeStdout(renderUpdateCheck(latestVersion));
+            return 0;
+        }
+        if (maybePath === "clients") {
+            io.writeStdout(await renderClientDoctor(terminalContext));
+            return 0;
+        }
         io.writeStdout(maybePath === "--json"
             ? await renderEnvironmentDoctorJson(terminalContext)
             : await renderEnvironmentDoctor(terminalContext));
@@ -189,14 +251,37 @@ export async function runCli(args, io = defaultIo, options = {}) {
     }
     if (command === "init") {
         const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
-        const result = await initPluginPackage(targetPath);
-        io.writeStdout([
+        const initFlags = maybePath && maybePath.startsWith("--")
+            ? [maybePath, ...remainingArgs]
+            : remainingArgs;
+        const templateIndex = initFlags.indexOf("--template");
+        const templateName = templateIndex === -1 ? "skill-only" : initFlags[templateIndex + 1];
+        if (templateIndex !== -1 && (!templateName || templateName.startsWith("--"))) {
+            io.writeStderr("Missing template after --template.");
+            return 2;
+        }
+        if (!isInitPluginTemplate(templateName)) {
+            io.writeStderr(`Unknown init template: ${templateName}. Supported templates: ${initPluginTemplates.join(", ")}.`);
+            return 2;
+        }
+        const result = await initPluginPackage(targetPath, { template: templateName });
+        const lines = [
             "Initialized Codex plugin package",
+            `Template: ${result.template}`,
             `Root: ${result.rootPath}`,
             `Manifest: ${result.manifestPath}`,
-            `Skill: ${result.skillPath}`,
+            `Skill: ${result.skillPath}`
+        ];
+        if (result.mcpConfigPath) {
+            lines.push(`MCP config: ${result.mcpConfigPath}`);
+        }
+        if (result.serverPath) {
+            lines.push(`Server: ${result.serverPath}`);
+        }
+        io.writeStdout([
+            ...lines,
             "",
-            `Next: codex-plugin-doctor check ${result.rootPath}`
+            `Next: codex-plugin-doctor check ${result.rootPath}${result.template === "full-runtime" ? " --runtime" : ""}`
         ].join("\n"));
         return 0;
     }
@@ -212,19 +297,24 @@ export async function runCli(args, io = defaultIo, options = {}) {
     }
     if (command === "fix") {
         if (!maybePath || maybePath.startsWith("--")) {
-            io.writeStderr("Missing target path. Usage: codex-plugin-doctor fix <path> (--dry-run|--apply --backup)");
+            io.writeStderr("Missing target path. Usage: codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)");
             return 2;
         }
         const dryRun = remainingArgs.includes("--dry-run");
         const apply = remainingArgs.includes("--apply");
+        const interactive = remainingArgs.includes("--interactive");
         const backup = remainingArgs.includes("--backup");
         const jsonOutput = remainingArgs.includes("--json");
-        if (apply && !backup) {
-            io.writeStderr("Fix apply requires --backup.");
+        if ((apply || interactive) && !backup) {
+            io.writeStderr("Fix mode requires --backup.");
+            return 2;
+        }
+        if ([dryRun, apply, interactive].filter(Boolean).length !== 1) {
+            io.writeStderr("Choose exactly one fix mode: --dry-run, --interactive --backup, or --apply --backup.");
             return 2;
         }
-        if (dryRun === apply) {
-            io.writeStderr("Choose exactly one fix mode: --dry-run or --apply --backup.");
+        if (interactive && jsonOutput) {
+            io.writeStderr("Interactive fix mode does not support --json.");
             return 2;
         }
         if (dryRun) {
@@ -234,6 +324,24 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 : renderFixPlan(plan, "dry-run"));
             return 0;
         }
+        if (interactive) {
+            const plan = await buildFixPlan(maybePath);
+            io.writeStdout([
+                renderFixPlan(plan, "interactive"),
+                "",
+                "Type yes to apply these fixes with a backup, or enter action numbers like 1,3. Anything else cancels."
+            ].join("\n"));
+            const answer = (await io.readStdin?.("Apply fixes? ") ?? "").trim().toLowerCase();
+            const selectedActionIndexes = answer === "yes"
+                ? null
+                : parseSelectedFixActionIndexes(answer, plan.actions.length);
+            if (answer !== "yes" && !selectedActionIndexes) {
+                io.writeStdout("Fix cancelled. No files changed.");
+                return 0;
+            }
+            io.writeStdout(renderApplyFixResult(await applyFixPlan(maybePath, selectedActionIndexes ? { actionIndexes: selectedActionIndexes } : {})));
+            return 0;
+        }
         const result = await applyFixPlan(maybePath);
         io.writeStdout(jsonOutput
             ? renderFixPlanJsonReport(result.plan, {
@@ -254,6 +362,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const installPreview = compatFlags.includes("--install-preview");
         const applyInstall = compatFlags.includes("--apply");
         const backupInstall = compatFlags.includes("--backup");
+        const allClients = compatFlags.includes("--all");
         const clientIndex = compatFlags.indexOf("--client");
         const clientFilter = clientIndex === -1 ? null : compatFlags[clientIndex + 1];
         const outputIndex = compatFlags.indexOf("--output");
@@ -262,6 +371,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStderr("Missing client after --client.");
             return 2;
         }
+        if (allClients && clientFilter) {
+            io.writeStderr("Use either --all or --client, not both.");
+            return 2;
+        }
         if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
             io.writeStderr("Missing path after --output.");
             return 2;
@@ -378,9 +491,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const sarifOutput = normalizedFlags.includes("--sarif");
     const runtimeProbeEnabled = normalizedFlags.includes("--runtime");
     const verboseRuntime = normalizedFlags.includes("--verbose-runtime");
+    const explainFindings = normalizedFlags.includes("--explain");
     const noAnimations = normalizedFlags.includes("--no-animations");
     const asciiMode = normalizedFlags.includes("--ascii");
     const installedSummary = normalizedFlags.includes("--all-summary");
+    const installedCompatibility = normalizedFlags.includes("--compat");
     const outputIndex = normalizedFlags.indexOf("--output");
     const outputPath = outputIndex === -1 ? null : normalizedFlags[outputIndex + 1];
     const configIndex = normalizedFlags.indexOf("--config");
@@ -441,6 +556,12 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const checkedPlugins = [];
         for (const plugin of installedPlugins) {
             const config = await loadDoctorConfig(plugin.rootPath, configPath);
+            const compatibilityMatrix = installedCompatibility
+                ? await buildCompatibilityMatrix(plugin.rootPath, {
+                    env: terminalContext.env,
+                    platform: terminalContext.platform
+                })
+                : undefined;
             checkedPlugins.push({
                 plugin,
                 result: applyDoctorConfig(await runCheckImpl(plugin.rootPath, {
@@ -448,7 +569,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
                         ? (line) => io.writeStderr(line)
                         : undefined
-                }), applyCheckProfile(config, checkProfile))
+                }), applyCheckProfile(config, checkProfile)),
+                compatibilityMatrix
             });
         }
         const report = installedSummary
@@ -460,13 +582,19 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     ? buildMarkdownReport(item.result, { runtimeProbeEnabled: effectiveRuntimeProbeEnabled })
                     : jsonOutput
                         ? renderJsonReport(item.result, { runtimeProbeEnabled: effectiveRuntimeProbeEnabled })
-                        : renderTextReport(item.result, { ascii: outputPolicy.style === "ascii" }))
+                        : renderTextReport(item.result, {
+                            ascii: outputPolicy.style === "ascii",
+                            explain: explainFindings
+                        }))
                 .join("\n\n");
         if (outputPath) {
             await writeFile(outputPath, report, "utf8");
         }
         io.writeStdout(report);
-        return checkedPlugins.some((item) => item.result.exitCode === 1) ? 1 : 0;
+        return checkedPlugins.some((item) => item.result.exitCode === 1 ||
+            (item.compatibilityMatrix && matrixExitCode(item.compatibilityMatrix) === 1))
+            ? 1
+            : 0;
     }
     const renderer = outputPolicy.interactive
         && !verboseRuntime
@@ -497,7 +625,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     ? renderBadgeJson(result)
                     : badgeMarkdownOutput
                         ? renderBadgeMarkdown(result)
-                        : renderTextReport(result, { ascii: outputPolicy.style === "ascii" });
+                        : renderTextReport(result, {
+                            ascii: outputPolicy.style === "ascii",
+                            explain: explainFindings
+                        });
     if (outputPath) {
         await writeFile(outputPath, report, "utf8");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,6 +26,7 @@
     "generate-validation-artifacts": "node scripts/generate-validation-artifacts.mjs",
     "prepare-rc": "tsx scripts/prepare-release-candidate.ts",
     "prepare-release": "npm test && npm run build && npm pack --dry-run",
+    "release-check": "node scripts/release-check.mjs",
     "prepublishOnly": "npm test && npm run build",
     "test": "vitest run",
     "test:watch": "vitest"