@genrtl/grtl 0.1.1 → 0.3.0

package/README.md

@@ -1,106 +1,70 @@
-# grtl
-
-Command-line client for the GenRTL RTL engineering knowledge service.
-
-## Requirements
-
-- Node.js 20.12 or newer
-- A GenRTL API key
-
-## Installation
-
-```bash
-npm install --global @genrtl/grtl
-```
-
-Set the API key in your environment:
-
-```bash
-export GRTL_API_KEY="gtr_live_your_api_key"
-```
-
-PowerShell:
-
-```powershell
-$env:GRTL_API_KEY = "gtr_live_your_api_key"
-```
-
-`GENRTL_API_KEY` is also supported.
-
-## Knowledge Tools
-
-The CLI exposes the same four tools as the hosted GenRTL MCP server:
-
-```bash
-grtl genrtl_knowledge_search "How should this AXI stream handle backpressure?"
-grtl genrtl_spec2rtl_search "Implement an APB register block with byte enables"
-grtl genrtl_verification_search "Build a self-checking testbench for an async FIFO"
-grtl genrtl_debug_search "Explain this Vivado CDC warning and suggest a safe fix"
-```
-
-Short aliases are available:
-
-```bash
-grtl knowledge-search "..."
-grtl spec2rtl-search "..."
-grtl verification-search "..."
-grtl debug-search "..."
-```
-
-Search options include `--type`, `--domain`, `--tool`, `--tool-version`,
-`--error-type`, `--severity`, `--interface`, `--target`, `--tag`, `--top-k`,
-`--min-score`, `--workspace-id`, and `--json`.
-
-Example:
-
-```bash
-grtl debug-search "FSM hangs after reset" \
-  --tool Vivado \
-  --target fpga \
-  --tag reset fsm \
-  --top-k 8 \
-  --json
-```
-
-## Agent Setup
-
-Configure the hosted HTTP MCP endpoint for a supported coding agent:
-
-```bash
-grtl setup --cursor
-grtl setup --codex --project
-grtl setup --claude --opencode
-```
-
-Supported agent flags are `--claude`, `--cursor`, `--codex`, `--opencode`,
-`--gemini`, and `--antigravity`. Without a flag, `grtl setup` presents an
-interactive selection.
-
-The API key is written to the selected agent's MCP configuration because the
-agent must send it as a Bearer token. Protect that configuration file and do
-not commit project-level MCP configuration containing a real key.
-
-The default endpoint is:
-
-```text
-https://genrtl.com/api/mcp
-```
-
-Use `--base-url` for another deployment:
-
-```bash
-grtl --base-url http://localhost:3005 setup --cursor --project
-grtl --base-url http://localhost:3005 debug-search "compile error"
-```
-
-## Development
-
-```bash
-pnpm install
-pnpm --filter @genrtl/grtl lint:check
-pnpm --filter @genrtl/grtl typecheck
-pnpm --filter @genrtl/grtl test
-pnpm --filter @genrtl/grtl build
-```
-
-This project is derived from Upstash Context7 and retains its MIT license.
+# @genrtl/grtl
+
+CLI and coding-agent integration for the GenRTL RTL engineering knowledge
+service.
+
+## Install
+
+```bash
+npm install --global @genrtl/grtl
+export GRTL_API_KEY="gtr_live_your_api_key"
+```
+
+PowerShell:
+
+```powershell
+$env:GRTL_API_KEY = "gtr_live_your_api_key"
+```
+
+## Agent Setup
+
+Install a Skill that tells the agent to call the `grtl` CLI:
+
+```bash
+grtl setup --cli --codex
+grtl setup --cli --cursor --project
+```
+
+Configure hosted MCP and install a Skill for the four MCP tools:
+
+```bash
+grtl setup --mcp --codex
+grtl setup --mcp --cursor --project
+```
+
+Without `--cli` or `--mcp`, setup asks which mode to install.
+
+For Codex, Skills are installed under `.agents/skills` for project setup or
+`~/.agents/skills` for global setup. MCP mode also updates
+`.codex/config.toml` or `~/.codex/config.toml`.
+
+The hosted MCP endpoint is:
+
+```text
+https://genrtl.com/api/mcp
+```
+
+## Knowledge Commands
+
+```bash
+grtl knowledge-search "AXI stream backpressure design"
+grtl spec2rtl-search "Design an APB register block"
+grtl spec2plan-search "Plan an APB register block implementation"
+grtl verification-search "Verify an async FIFO"
+grtl debug-search "Explain this Vivado CDC warning"
+```
+
+Use `--json` for structured output. `--type` accepts `spec2rtl`, `spec2plan`, `verification`, or `debug`; other filters include
+`--domain`, `--tool`, `--tool-version`, `--error-type`, `--severity`,
+`--interface`, `--target`, `--tag`, `--top-k`, `--min-score`, and
+`--workspace-id`.
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter @genrtl/grtl lint:check
+pnpm --filter @genrtl/grtl typecheck
+pnpm --filter @genrtl/grtl test
+pnpm --filter @genrtl/grtl build
+```

package/dist/index.js

@@ -6,106 +6,16 @@ import pc6 from "picocolors";
 import figlet from "figlet";
 
 // src/commands/setup.ts
-import pc3 from "picocolors";
+import { select } from "@inquirer/prompts";
+import { dirname as dirname4, join as join2 } from "path";
+import { mkdir as mkdir3, readFile as readFile2, writeFile as writeFile3 } from "fs/promises";
 import ora from "ora";
-import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname2, join as join2 } from "path";
-
-// src/utils/logger.ts
-import pc from "picocolors";
-var ANSI_PATTERN = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
-function visibleLength(text) {
-  return text.replace(ANSI_PATTERN, "").length;
-}
-function padVisible(text, width) {
-  const padding = Math.max(0, width - visibleLength(text));
-  return text + " ".repeat(padding);
-}
-function box(lines, color = pc.green) {
-  const contentWidth = Math.max(...lines.map((line) => visibleLength(line)), 0);
-  const top = color(`\u250C${"\u2500".repeat(contentWidth + 2)}\u2510`);
-  const bottom = color(`\u2514${"\u2500".repeat(contentWidth + 2)}\u2518`);
-  console.log(top);
-  for (const line of lines) {
-    console.log(color("\u2502 ") + padVisible(line, contentWidth) + color(" \u2502"));
-  }
-  console.log(bottom);
-}
-var log = {
-  info: (message) => console.log(pc.cyan(message)),
-  success: (message) => console.log(pc.green(`\u2714 ${message}`)),
-  warn: (message) => console.log(pc.yellow(`\u26A0 ${message}`)),
-  error: (message) => console.log(pc.red(`\u2716 ${message}`)),
-  dim: (message) => console.log(pc.dim(message)),
-  item: (message) => console.log(pc.green(`  ${message}`)),
-  itemAdd: (message) => console.log(`  ${pc.green("+")} ${message}`),
-  plain: (message) => console.log(message),
-  blank: () => console.log(""),
-  box
-};
-
-// src/utils/prompts.ts
-import pc2 from "picocolors";
-import { checkbox } from "@inquirer/prompts";
-import readline from "readline";
-async function checkboxWithHover(config, options) {
-  const choices = config.choices.filter(
-    (c) => typeof c === "object" && c !== null && !("type" in c && c.type === "separator")
-  );
-  const values = choices.map((c) => c.value);
-  const totalItems = values.length;
-  let cursorPosition = choices.findIndex((c) => !c.disabled);
-  if (cursorPosition < 0) cursorPosition = 0;
-  const getName = options?.getName ?? ((v) => v.name);
-  const keypressHandler = (_str, key) => {
-    if (key.name === "up") {
-      let next = cursorPosition - 1;
-      while (next >= 0 && choices[next].disabled) next--;
-      if (next >= 0) cursorPosition = next;
-    } else if (key.name === "down") {
-      let next = cursorPosition + 1;
-      while (next < totalItems && choices[next].disabled) next++;
-      if (next < totalItems) cursorPosition = next;
-    }
-  };
-  readline.emitKeypressEvents(process.stdin);
-  process.stdin.on("keypress", keypressHandler);
-  const customConfig = {
-    ...config,
-    theme: {
-      ...config.theme,
-      style: {
-        answer: (text) => pc2.green(text),
-        ...config.theme?.style,
-        highlight: (text) => pc2.green(text),
-        renderSelectedChoices: (selected, _allChoices) => {
-          if (selected.length === 0) {
-            return pc2.dim(getName(values[cursorPosition]));
-          }
-          return selected.map((c) => getName(c.value)).join(", ");
-        }
-      }
-    }
-  };
-  try {
-    const selected = await checkbox(customConfig);
-    if (selected.length === 0) {
-      return [values[cursorPosition]];
-    }
-    return selected;
-  } finally {
-    process.stdin.removeListener("keypress", keypressHandler);
-  }
-}
-
-// src/utils/tracking.ts
-function trackEvent(_event, _data) {
-}
+import pc3 from "picocolors";
 
-// src/setup/http-agents.ts
+// src/setup/agents.ts
 import { access } from "fs/promises";
-import { homedir } from "os";
 import { join } from "path";
+import { homedir } from "os";
 var SETUP_AGENT_NAMES = {
   claude: "Claude Code",
   cursor: "Cursor",
@@ -115,18 +25,38 @@ var SETUP_AGENT_NAMES = {
   gemini: "Gemini CLI"
 };
 var mcpBaseUrl = "https://genrtl.com/api/mcp";
+var STDIO_PACKAGE = "@upstash/genrtl-mcp";
 function setMcpBaseUrl(url) {
   const normalized = url.replace(/\/+$/, "");
   mcpBaseUrl = normalized.endsWith("/api/mcp") ? normalized : `${normalized}/api/mcp`;
 }
-function headers(auth) {
-  return { Authorization: `Bearer ${auth.apiKey}` };
+function stdioArgs(auth) {
+  const args = ["-y", STDIO_PACKAGE];
+  if (auth.mode === "api-key" && auth.apiKey) {
+    args.push("--api-key", auth.apiKey);
+  }
+  return args;
+}
+function stdioEntry(auth) {
+  return { command: "npx", args: stdioArgs(auth) };
 }
 function claudeConfigDir() {
   return process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
 }
 function claudeGlobalMcpPath() {
-  return process.env.CLAUDE_CONFIG_DIR ? join(claudeConfigDir(), ".claude.json") : join(homedir(), ".claude.json");
+  if (process.env.CLAUDE_CONFIG_DIR) {
+    return join(claudeConfigDir(), ".claude.json");
+  }
+  return join(homedir(), ".claude.json");
+}
+function mcpUrl(_auth) {
+  return mcpBaseUrl;
+}
+function withHeaders(base, auth) {
+  if (auth.mode === "api-key" && auth.apiKey) {
+    return { ...base, headers: { Authorization: `Bearer ${auth.apiKey}` } };
+  }
+  return base;
 }
 var agents = {
   claude: {
@@ -138,17 +68,17 @@ var agents = {
         return [claudeGlobalMcpPath()];
       },
       configKey: "mcpServers",
-      buildEntry: (auth) => ({
-        type: "http",
-        url: mcpBaseUrl,
-        headers: headers(auth)
-      })
+      buildEntry: (auth, transport) => transport === "stdio" ? stdioEntry(auth) : withHeaders({ type: "http", url: mcpUrl(auth) }, auth)
     },
     rule: {
       kind: "file",
       dir: (scope) => scope === "global" ? join(claudeConfigDir(), "rules") : join(".claude", "rules"),
       filename: "genrtl.md"
     },
+    skill: {
+      name: "genrtl-mcp",
+      dir: (scope) => scope === "global" ? join(claudeConfigDir(), "skills") : join(".claude", "skills")
+    },
     detect: {
       projectPaths: [".mcp.json", ".claude"],
       get globalPaths() {
@@ -163,13 +93,17 @@ var agents = {
       projectPaths: [join(".cursor", "mcp.json")],
       globalPaths: [join(homedir(), ".cursor", "mcp.json")],
       configKey: "mcpServers",
-      buildEntry: (auth) => ({ url: mcpBaseUrl, headers: headers(auth) })
+      buildEntry: (auth, transport) => transport === "stdio" ? stdioEntry(auth) : withHeaders({ url: mcpUrl(auth) }, auth)
     },
     rule: {
       kind: "file",
       dir: (scope) => scope === "global" ? join(homedir(), ".cursor", "rules") : join(".cursor", "rules"),
       filename: "genrtl.mdc"
     },
+    skill: {
+      name: "genrtl-mcp",
+      dir: (scope) => scope === "global" ? join(homedir(), ".cursor", "skills") : join(".cursor", "skills")
+    },
     detect: {
       projectPaths: [".cursor"],
       globalPaths: [join(homedir(), ".cursor")]
@@ -187,18 +121,17 @@ var agents = {
         join(homedir(), ".config", "opencode", ".opencode.jsonc")
       ],
       configKey: "mcp",
-      buildEntry: (auth) => ({
-        type: "remote",
-        url: mcpBaseUrl,
-        enabled: true,
-        headers: headers(auth)
-      })
+      buildEntry: (auth, transport) => transport === "stdio" ? { type: "local", command: ["npx", ...stdioArgs(auth)], enabled: true } : withHeaders({ type: "remote", url: mcpUrl(auth), enabled: true }, auth)
     },
     rule: {
       kind: "append",
       file: (scope) => scope === "global" ? join(homedir(), ".config", "opencode", "AGENTS.md") : "AGENTS.md",
       sectionMarker: "<!-- genrtl -->"
     },
+    skill: {
+      name: "genrtl-mcp",
+      dir: (scope) => scope === "global" ? join(homedir(), ".agents", "skills") : join(".agents", "skills")
+    },
     detect: {
       projectPaths: ["opencode.json", "opencode.jsonc", ".opencode.json", ".opencode.jsonc"],
       globalPaths: [join(homedir(), ".config", "opencode")]
@@ -211,14 +144,16 @@ var agents = {
       projectPaths: [join(".codex", "config.toml")],
       globalPaths: [join(homedir(), ".codex", "config.toml")],
       configKey: "mcp_servers",
-      buildEntry: (auth) => auth.apiKeyEnvVar ? {
-        type: "http",
-        url: mcpBaseUrl,
-        bearer_token_env_var: auth.apiKeyEnvVar
-      } : {
-        type: "http",
-        url: mcpBaseUrl,
-        headers: headers(auth)
+      buildEntry: (auth, transport) => {
+        if (transport === "stdio") return stdioEntry(auth);
+        if (auth.mode === "api-key" && auth.apiKeyEnvVar) {
+          return {
+            type: "http",
+            url: mcpUrl(auth),
+            bearer_token_env_var: auth.apiKeyEnvVar
+          };
+        }
+        return withHeaders({ type: "http", url: mcpUrl(auth) }, auth);
       }
     },
     rule: {
@@ -226,25 +161,37 @@ var agents = {
       file: (scope) => scope === "global" ? join(homedir(), ".codex", "AGENTS.md") : "AGENTS.md",
       sectionMarker: "<!-- genrtl -->"
     },
+    skill: {
+      name: "genrtl-mcp",
+      dir: (scope) => scope === "global" ? join(homedir(), ".agents", "skills") : join(".agents", "skills")
+    },
     detect: {
       projectPaths: [".codex"],
       globalPaths: [join(homedir(), ".codex")]
     }
   },
+  // Antigravity is built on Gemini infrastructure and shares ~/.gemini/. Per
+  // the official Codelabs guide, Antigravity 2.0/IDE/CLI read MCP servers from
+  // ~/.gemini/config/mcp_config.json globally; there is no project-level MCP
+  // config, so projectPaths is empty and setupAgent falls back to global.
   antigravity: {
     name: "antigravity",
     displayName: "Antigravity",
     mcp: {
       projectPaths: [],
-      globalPaths: [join(homedir(), ".gemini", "antigravity", "mcp_config.json")],
+      globalPaths: [join(homedir(), ".gemini", "config", "mcp_config.json")],
       configKey: "mcpServers",
-      buildEntry: (auth) => ({ serverUrl: mcpBaseUrl, headers: headers(auth) })
+      buildEntry: (auth, transport) => transport === "stdio" ? stdioEntry(auth) : withHeaders({ serverUrl: mcpUrl(auth) }, auth)
     },
     rule: {
       kind: "append",
       file: (scope) => scope === "global" ? join(homedir(), ".gemini", "GEMINI.md") : "GEMINI.md",
       sectionMarker: "<!-- genrtl -->"
     },
+    skill: {
+      name: "genrtl-mcp",
+      dir: (scope) => scope === "global" ? join(homedir(), ".agent", "skills") : join(".agent", "skills")
+    },
     detect: {
       projectPaths: [".agent"],
       globalPaths: [join(homedir(), ".gemini", "antigravity"), join(homedir(), ".agent")]
@@ -257,13 +204,17 @@ var agents = {
       projectPaths: [join(".gemini", "settings.json")],
       globalPaths: [join(homedir(), ".gemini", "settings.json")],
       configKey: "mcpServers",
-      buildEntry: (auth) => ({ httpUrl: mcpBaseUrl, headers: headers(auth) })
+      buildEntry: (auth, transport) => transport === "stdio" ? stdioEntry(auth) : withHeaders({ httpUrl: mcpUrl(auth) }, auth)
     },
     rule: {
       kind: "append",
       file: (scope) => scope === "global" ? join(homedir(), ".gemini", "GEMINI.md") : "GEMINI.md",
       sectionMarker: "<!-- genrtl -->"
     },
+    skill: {
+      name: "genrtl-mcp",
+      dir: (scope) => scope === "global" ? join(homedir(), ".gemini", "skills") : join(".gemini", "skills")
+    },
     detect: {
       projectPaths: [".gemini"],
       globalPaths: [join(homedir(), ".gemini")]
@@ -274,9 +225,9 @@ function getAgent(name) {
   return agents[name];
 }
 var ALL_AGENT_NAMES = Object.keys(agents);
-async function pathExists(path) {
+async function pathExists(p) {
   try {
-    await access(path);
+    await access(p);
     return true;
   } catch {
     return false;
@@ -286,8 +237,8 @@ async function detectAgents(scope) {
   const detected = [];
   for (const agent of Object.values(agents)) {
     const paths = scope === "global" ? agent.detect.globalPaths : agent.detect.projectPaths;
-    for (const path of paths) {
-      const fullPath = scope === "global" ? path : join(process.cwd(), path);
+    for (const p of paths) {
+      const fullPath = scope === "global" ? p : join(process.cwd(), p);
       if (await pathExists(fullPath)) {
         detected.push(agent.name);
         break;
@@ -297,56 +248,6 @@ async function detectAgents(scope) {
   return detected;
 }
 
-// src/setup/templates.ts
-var GITHUB_RAW_URLS = ["https://raw.githubusercontent.com/xroting/grtl/main/rules"];
-var FALLBACK_MCP = `Use GenRTL MCP tools for grounded RTL engineering knowledge.
-
-Choose one tool:
-- \`genrtl_knowledge_search\` for cross-domain RTL questions
-- \`genrtl_spec2rtl_search\` for requirements and RTL design
-- \`genrtl_verification_search\` for testbenches and verification
-- \`genrtl_debug_search\` for lint, CDC, compile, synthesis, and RTL bugs
-
-Pass the complete engineering question in \`query\`. Add filters only when useful.`;
-var FALLBACK_CLI = `Use the \`grtl\` CLI for grounded RTL engineering knowledge.
-
-Choose one command:
-- \`npx @genrtl/grtl@latest knowledge-search "<query>"\`
-- \`npx @genrtl/grtl@latest spec2rtl-search "<query>"\`
-- \`npx @genrtl/grtl@latest verification-search "<query>"\`
-- \`npx @genrtl/grtl@latest debug-search "<query>"\`
-
-Pass the complete engineering question. Add filters such as \`--tool\`,
-\`--tool-version\`, \`--target\`, \`--interface\`, or \`--tag\` when known.
-If authentication fails, set \`GRTL_API_KEY\`.`;
-var CURSOR_FRONTMATTER = `---
-alwaysApply: true
----
-
-`;
-var CODEX_CLI_SANDBOX_GUIDANCE = `Run GenRTL CLI requests outside Codex's default sandbox. If a GenRTL CLI command fails with DNS or network errors such as ENOTFOUND, host resolution failures, or fetch failed, rerun it outside the sandbox instead of retrying inside the sandbox.`;
-async function fetchRule(filename, fallback) {
-  for (const base of GITHUB_RAW_URLS) {
-    try {
-      const res = await fetch(`${base}/${filename}`);
-      if (res.ok) return await res.text();
-    } catch {
-      continue;
-    }
-  }
-  return fallback;
-}
-async function getRuleContent(mode, agent) {
-  const [filename, fallback] = mode === "mcp" ? ["genrtl-mcp.md", FALLBACK_MCP] : ["genrtl-cli.md", FALLBACK_CLI];
-  let body = await fetchRule(filename, fallback);
-  if (mode === "cli" && agent === "codex" && !body.includes(CODEX_CLI_SANDBOX_GUIDANCE)) {
-    body = `${body.trimEnd()}
-${CODEX_CLI_SANDBOX_GUIDANCE}
-`;
-  }
-  return agent === "cursor" ? `${CURSOR_FRONTMATTER}${body}` : body;
-}
-
 // src/setup/mcp-writer.ts
 import { access as access2, readFile, writeFile, mkdir } from "fs/promises";
 import { dirname } from "path";
@@ -415,15 +316,15 @@ async function writeJsonConfig(filePath, config) {
 }
 function buildTomlServerBlock(serverName, entry) {
   const lines = [`[mcp_servers.${serverName}]`];
-  const headers2 = entry.headers;
+  const headers = entry.headers;
   for (const [key, value] of Object.entries(entry)) {
     if (key === "headers") continue;
     lines.push(`${key} = ${JSON.stringify(value)}`);
   }
-  if (headers2 && Object.keys(headers2).length > 0) {
+  if (headers && Object.keys(headers).length > 0) {
     lines.push("");
     lines.push(`[mcp_servers.${serverName}.http_headers]`);
-    for (const [key, value] of Object.entries(headers2)) {
+    for (const [key, value] of Object.entries(headers)) {
       lines.push(`${key} = ${JSON.stringify(value)}`);
     }
   }
@@ -468,6 +369,236 @@ async function appendTomlServer(filePath, serverName, entry) {
   return { alreadyExists };
 }
 
+// src/setup/templates.ts
+var GITHUB_RAW_URLS = ["https://raw.githubusercontent.com/xroting/grtl/main/rules"];
+var FALLBACK_MCP = `Use GenRTL MCP tools for grounded RTL engineering knowledge.
+
+Choose one tool:
+- \`genrtl_knowledge_search\` for cross-domain RTL questions
+- \`genrtl_spec2rtl_search\` for requirements and RTL design
+- \`genrtl_spec2plan_search\` for implementation planning from a specification
+- \`genrtl_verification_search\` for testbenches and verification
+- \`genrtl_debug_search\` for lint, CDC, compile, synthesis, and RTL bugs
+
+Pass the complete engineering question in \`query\`. Add filters only when useful.`;
+var FALLBACK_CLI = `Use the \`grtl\` CLI for grounded RTL engineering knowledge.
+
+Choose one command:
+- \`npx @genrtl/grtl@latest knowledge-search "<query>"\`
+- \`npx @genrtl/grtl@latest spec2rtl-search "<query>"\`
+- \`npx @genrtl/grtl@latest spec2plan-search "<query>"\`
+- \`npx @genrtl/grtl@latest verification-search "<query>"\`
+- \`npx @genrtl/grtl@latest debug-search "<query>"\`
+
+Pass the complete engineering question. Add filters such as \`--tool\`,
+\`--tool-version\`, \`--target\`, \`--interface\`, or \`--tag\` when known.
+If authentication fails, set \`GRTL_API_KEY\` or \`GENRTL_API_KEY\` in the
+coding agent's environment.`;
+var CURSOR_FRONTMATTER = `---
+alwaysApply: true
+---
+
+`;
+var CODEX_CLI_SANDBOX_GUIDANCE = `Run GenRTL CLI requests outside Codex's default sandbox. If a GenRTL CLI command fails with DNS or network errors such as ENOTFOUND, host resolution failures, or fetch failed, rerun it outside the sandbox instead of retrying inside the sandbox.`;
+var MCP_SKILL = `---
+name: genrtl-mcp
+description: Use GenRTL MCP tools for grounded RTL design, verification, lint, CDC, synthesis, compile, and debugging knowledge.
+---
+
+# GenRTL MCP
+
+Use this skill when an RTL engineering task needs grounded GenRTL knowledge.
+
+Choose exactly one MCP tool:
+
+- \`genrtl_knowledge_search\` for cross-domain RTL questions.
+- \`genrtl_spec2rtl_search\` for requirements, protocols, control logic, or algorithm-to-RTL work.
+- \`genrtl_spec2plan_search\` for turning a specification into an actionable implementation plan.
+- \`genrtl_verification_search\` for testbenches and verification.
+- \`genrtl_debug_search\` for lint, CDC, compile, synthesis, or RTL bugs.
+
+Pass the complete engineering question in \`query\`. Add \`filters\`, \`top_k\`,
+\`min_score\`, or \`workspace_id\` only when useful.
+`;
+var CLI_SKILL = `---
+name: genrtl-cli
+description: Use the grtl CLI for grounded RTL design, verification, lint, CDC, synthesis, compile, and debugging knowledge.
+---
+
+# GenRTL CLI
+
+Use this skill when an RTL engineering task needs grounded GenRTL knowledge and
+the GenRTL MCP server is not configured.
+
+Choose exactly one command:
+
+- \`grtl knowledge-search "<query>" --json\` for cross-domain RTL questions.
+- \`grtl spec2rtl-search "<query>" --json\` for requirements, protocols, control logic, or algorithm-to-RTL work.
+- \`grtl spec2plan-search "<query>" --json\` for turning a specification into an actionable implementation plan.
+- \`grtl verification-search "<query>" --json\` for testbenches and verification.
+- \`grtl debug-search "<query>" --json\` for lint, CDC, compile, synthesis, or RTL bugs.
+
+Pass the complete engineering question. Add filters such as \`--tool\`,
+\`--tool-version\`, \`--target\`, \`--interface\`, or \`--tag\` only when useful.
+The CLI requires \`GRTL_API_KEY\` or \`GENRTL_API_KEY\` in its environment.
+`;
+function getSkillContent(mode) {
+  return mode === "mcp" ? MCP_SKILL : CLI_SKILL;
+}
+async function fetchRule(filename, fallback) {
+  for (const base of GITHUB_RAW_URLS) {
+    try {
+      const res = await fetch(`${base}/${filename}`);
+      if (res.ok) return await res.text();
+    } catch {
+      continue;
+    }
+  }
+  return fallback;
+}
+async function getRuleContent(mode, agent) {
+  const [filename, fallback] = mode === "mcp" ? ["genrtl-mcp.md", FALLBACK_MCP] : ["genrtl-cli.md", FALLBACK_CLI];
+  let body = await fetchRule(filename, fallback);
+  if (mode === "cli" && agent === "codex" && !body.includes(CODEX_CLI_SANDBOX_GUIDANCE)) {
+    body = `${body.trimEnd()}
+${CODEX_CLI_SANDBOX_GUIDANCE}
+`;
+  }
+  return agent === "cursor" ? `${CURSOR_FRONTMATTER}${body}` : body;
+}
+
+// src/utils/installer.ts
+import { mkdir as mkdir2, writeFile as writeFile2, rm, symlink, lstat } from "fs/promises";
+import { resolve as resolve2, dirname as dirname3 } from "path";
+
+// src/utils/skill-name.ts
+import { resolve, dirname as dirname2, basename } from "path";
+var SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+function isSafeSkillName(name) {
+  if (typeof name !== "string") return false;
+  if (name.length === 0 || name.length > 128) return false;
+  if (name === "." || name === "..") return false;
+  if (name.includes("\0")) return false;
+  if (!SAFE_NAME.test(name)) return false;
+  return true;
+}
+function assertSkillNameInRoot(skillsRoot, skillName) {
+  if (!isSafeSkillName(skillName)) {
+    throw new Error(`Unsafe skill name: ${JSON.stringify(skillName)}`);
+  }
+  const root = resolve(skillsRoot);
+  const target = resolve(root, skillName);
+  if (dirname2(target) !== root || basename(target) !== skillName) {
+    throw new Error(`Skill name "${skillName}" escapes the skills root`);
+  }
+  return target;
+}
+
+// src/utils/installer.ts
+async function installSkillFiles(skillName, files, skillsRoot) {
+  const skillDir = assertSkillNameInRoot(skillsRoot, skillName);
+  for (const file of files) {
+    const filePath = resolve2(skillDir, file.path);
+    if (!filePath.startsWith(skillDir + "/") && !filePath.startsWith(skillDir + "\\") && filePath !== skillDir) {
+      throw new Error(`Skill file path "${file.path}" resolves outside the target directory`);
+    }
+    const fileDir = dirname3(filePath);
+    await mkdir2(fileDir, { recursive: true });
+    await writeFile2(filePath, file.content);
+  }
+}
+
+// src/utils/logger.ts
+import pc from "picocolors";
+var ANSI_PATTERN = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+function visibleLength(text) {
+  return text.replace(ANSI_PATTERN, "").length;
+}
+function padVisible(text, width) {
+  const padding = Math.max(0, width - visibleLength(text));
+  return text + " ".repeat(padding);
+}
+function box(lines, color = pc.green) {
+  const contentWidth = Math.max(...lines.map((line) => visibleLength(line)), 0);
+  const top = color(`\u250C${"\u2500".repeat(contentWidth + 2)}\u2510`);
+  const bottom = color(`\u2514${"\u2500".repeat(contentWidth + 2)}\u2518`);
+  console.log(top);
+  for (const line of lines) {
+    console.log(color("\u2502 ") + padVisible(line, contentWidth) + color(" \u2502"));
+  }
+  console.log(bottom);
+}
+var log = {
+  info: (message) => console.log(pc.cyan(message)),
+  success: (message) => console.log(pc.green(`\u2714 ${message}`)),
+  warn: (message) => console.log(pc.yellow(`\u26A0 ${message}`)),
+  error: (message) => console.log(pc.red(`\u2716 ${message}`)),
+  dim: (message) => console.log(pc.dim(message)),
+  item: (message) => console.log(pc.green(`  ${message}`)),
+  itemAdd: (message) => console.log(`  ${pc.green("+")} ${message}`),
+  plain: (message) => console.log(message),
+  blank: () => console.log(""),
+  box
+};
+
+// src/utils/prompts.ts
+import pc2 from "picocolors";
+import { checkbox } from "@inquirer/prompts";
+import readline from "readline";
+async function checkboxWithHover(config, options) {
+  const choices = config.choices.filter(
+    (c) => typeof c === "object" && c !== null && !("type" in c && c.type === "separator")
+  );
+  const values = choices.map((c) => c.value);
+  const totalItems = values.length;
+  let cursorPosition = choices.findIndex((c) => !c.disabled);
+  if (cursorPosition < 0) cursorPosition = 0;
+  const getName = options?.getName ?? ((v) => v.name);
+  const keypressHandler = (_str, key) => {
+    if (key.name === "up") {
+      let next = cursorPosition - 1;
+      while (next >= 0 && choices[next].disabled) next--;
+      if (next >= 0) cursorPosition = next;
+    } else if (key.name === "down") {
+      let next = cursorPosition + 1;
+      while (next < totalItems && choices[next].disabled) next++;
+      if (next < totalItems) cursorPosition = next;
+    }
+  };
+  readline.emitKeypressEvents(process.stdin);
+  process.stdin.on("keypress", keypressHandler);
+  const customConfig = {
+    ...config,
+    theme: {
+      ...config.theme,
+      style: {
+        answer: (text) => pc2.green(text),
+        ...config.theme?.style,
+        highlight: (text) => pc2.green(text),
+        renderSelectedChoices: (selected, _allChoices) => {
+          if (selected.length === 0) {
+            return pc2.dim(getName(values[cursorPosition]));
+          }
+          return selected.map((c) => getName(c.value)).join(", ");
+        }
+      }
+    }
+  };
+  try {
+    const selected = await checkbox(customConfig);
+    if (selected.length === 0) {
+      return [values[cursorPosition]];
+    }
+    return selected;
+  } finally {
+    process.stdin.removeListener("keypress", keypressHandler);
+  }
+}
+
+// src/utils/tracking.ts
+function trackEvent(_event, _data) {
+}
+
 // src/commands/setup.ts
 var CHECKBOX_THEME = {
   style: {
@@ -475,6 +606,10 @@ var CHECKBOX_THEME = {
     disabledChoice: (text) => ` ${pc3.dim("-")} ${pc3.dim(text)}`
   }
 };
+var SKILL_NAMES = {
+  cli: "genrtl-cli",
+  mcp: "genrtl-mcp"
+};
 function getSelectedAgents(options) {
   const agents2 = [];
   if (options.claude) agents2.push("claude");
@@ -486,20 +621,57 @@ function getSelectedAgents(options) {
   return agents2;
 }
 function resolveSetupAuth(options) {
-  if (options.apiKey) return { apiKey: options.apiKey };
+  if (options.apiKey) return { mode: "api-key", apiKey: options.apiKey };
   if (process.env.GRTL_API_KEY) {
-    return { apiKey: process.env.GRTL_API_KEY, apiKeyEnvVar: "GRTL_API_KEY" };
+    return {
+      mode: "api-key",
+      apiKey: process.env.GRTL_API_KEY,
+      apiKeyEnvVar: "GRTL_API_KEY"
+    };
   }
   if (process.env.GENRTL_API_KEY) {
-    return { apiKey: process.env.GENRTL_API_KEY, apiKeyEnvVar: "GENRTL_API_KEY" };
+    return {
+      mode: "api-key",
+      apiKey: process.env.GENRTL_API_KEY,
+      apiKeyEnvVar: "GENRTL_API_KEY"
+    };
   }
   return void 0;
 }
 function registerSetupCommand(program2) {
-  program2.command("setup").description("Configure the hosted GenRTL HTTP MCP server for a coding agent").option("--claude", "Set up Claude Code").option("--cursor", "Set up Cursor").option("--antigravity", "Set up Antigravity").option("--opencode", "Set up OpenCode").option("--codex", "Set up Codex").option("--gemini", "Set up Gemini CLI").option("-p, --project", "Configure the current project instead of the user profile").option("-y, --yes", "Use all detected agents without prompting").option("--api-key <key>", "GenRTL API key (prefer the GRTL_API_KEY environment variable)").action(async (options) => {
+  program2.command("setup").description("Install GenRTL CLI or MCP integration for a coding agent").option("--cli", "Install a Skill that calls the grtl CLI").option("--mcp", "Configure GenRTL MCP and install its Skill").option("--claude", "Set up Claude Code").option("--cursor", "Set up Cursor").option("--antigravity", "Set up Antigravity").option("--opencode", "Set up OpenCode").option("--codex", "Set up Codex").option("--gemini", "Set up Gemini CLI").option("-p, --project", "Configure the current project instead of the user profile").option("-y, --yes", "Use MCP mode and all detected agents without prompting").option("--api-key <key>", "GenRTL API key for MCP mode").action(async (options) => {
     await setupCommand(options);
   });
 }
+async function resolveMode(options) {
+  if (options.cli && options.mcp) {
+    log.error("Choose either --cli or --mcp, not both.");
+    process.exitCode = 1;
+    return null;
+  }
+  if (options.cli) return "cli";
+  if (options.mcp || options.yes) return "mcp";
+  try {
+    return await select({
+      message: "How should your coding agent access GenRTL?",
+      choices: [
+        {
+          name: "CLI Skill",
+          value: "cli",
+          description: "The agent runs the installed grtl command."
+        },
+        {
+          name: "MCP Server + Skill",
+          value: "mcp",
+          description: "The agent calls the four hosted GenRTL MCP tools."
+        }
+      ]
+    });
+  } catch {
+    log.warn("Setup cancelled");
+    return null;
+  }
+}
 async function promptAgents() {
   try {
     return await checkboxWithHover(
@@ -524,7 +696,7 @@ async function resolveAgents(options, scope) {
   const detected = await detectAgents(scope);
   if (detected.length > 0 && options.yes) return detected;
   if (options.yes) {
-    log.error("No supported coding agents were detected. Pass an agent flag such as --cursor.");
+    log.error("No supported coding agents were detected. Pass an agent flag such as --codex.");
     return [];
   }
   log.blank();
@@ -532,14 +704,14 @@ async function resolveAgents(options, scope) {
   if (!selected) log.warn("Setup cancelled");
   return selected ?? [];
 }
-async function installRule(agentName, scope) {
+async function installRule(agentName, scope, mode) {
   const rule = getAgent(agentName).rule;
-  const content = await getRuleContent("mcp", agentName);
+  const content = await getRuleContent(mode, agentName);
   if (rule.kind === "file") {
     const ruleDir = scope === "global" ? rule.dir("global") : join2(process.cwd(), rule.dir("project"));
     const rulePath = join2(ruleDir, rule.filename);
-    await mkdir2(dirname2(rulePath), { recursive: true });
-    await writeFile2(rulePath, content, "utf-8");
+    await mkdir3(dirname4(rulePath), { recursive: true });
+    await writeFile3(rulePath, content, "utf-8");
     return { status: "installed", path: rulePath };
   }
   const filePath = scope === "global" ? rule.file("global") : join2(process.cwd(), rule.file("project"));
@@ -554,69 +726,108 @@ ${rule.sectionMarker}`;
   }
   if (existing.includes(rule.sectionMarker)) {
     const regex = new RegExp(`${escapedMarker}\\n[\\s\\S]*?${escapedMarker}`);
-    await writeFile2(filePath, existing.replace(regex, section), "utf-8");
+    await writeFile3(filePath, existing.replace(regex, section), "utf-8");
     return { status: "updated", path: filePath };
   }
   const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n\n" : existing.length > 0 ? "\n" : "";
-  await mkdir2(dirname2(filePath), { recursive: true });
-  await writeFile2(filePath, `${existing}${separator}${section}
+  await mkdir3(dirname4(filePath), { recursive: true });
+  await writeFile3(filePath, `${existing}${separator}${section}
 `, "utf-8");
   return { status: "installed", path: filePath };
 }
-async function setupAgent(agentName, auth, scope) {
+async function installSkill(agentName, scope, mode) {
+  const agent = getAgent(agentName);
+  const skillName = SKILL_NAMES[mode];
+  const skillsRoot = scope === "global" ? agent.skill.dir("global") : join2(process.cwd(), agent.skill.dir("project"));
+  const skillPath = join2(skillsRoot, skillName);
+  await installSkillFiles(
+    skillName,
+    [{ path: "SKILL.md", content: getSkillContent(mode) }],
+    skillsRoot
+  );
+  return { status: "installed", path: skillPath };
+}
+async function configureMcp(agentName, auth, scope) {
   const agent = getAgent(agentName);
   const candidates = scope === "global" || agent.mcp.projectPaths.length === 0 ? agent.mcp.globalPaths : agent.mcp.projectPaths.map((path) => join2(process.cwd(), path));
   const mcpPath = await resolveMcpPath(candidates);
-  const entry = agent.mcp.buildEntry(auth);
+  const entry = agent.mcp.buildEntry(auth, "http");
+  if (mcpPath.endsWith(".toml")) {
+    const { alreadyExists: alreadyExists2 } = await appendTomlServer(mcpPath, "genrtl", entry);
+    return { status: alreadyExists2 ? "reconfigured" : "configured", path: mcpPath };
+  }
+  const existing = await readJsonConfig(mcpPath);
+  const { config, alreadyExists } = mergeServerEntry(
+    existing,
+    agent.mcp.configKey,
+    "genrtl",
+    entry
+  );
+  await writeJsonConfig(mcpPath, config);
+  return { status: alreadyExists ? "reconfigured" : "configured", path: mcpPath };
+}
+async function setupAgent(agentName, mode, auth, scope) {
+  const agent = getAgent(agentName);
   let mcpStatus;
-  try {
-    if (mcpPath.endsWith(".toml")) {
-      const { alreadyExists } = await appendTomlServer(mcpPath, "genrtl", entry);
-      mcpStatus = alreadyExists ? "reconfigured" : "configured";
-    } else {
-      const existing = await readJsonConfig(mcpPath);
-      const { config, alreadyExists } = mergeServerEntry(
-        existing,
-        agent.mcp.configKey,
-        "genrtl",
-        entry
-      );
-      await writeJsonConfig(mcpPath, config);
-      mcpStatus = alreadyExists ? "reconfigured" : "configured";
+  let mcpPath;
+  if (mode === "mcp" && auth) {
+    try {
+      const result = await configureMcp(agentName, auth, scope);
+      mcpStatus = result.status;
+      mcpPath = result.path;
+    } catch (error) {
+      mcpStatus = `failed: ${error instanceof Error ? error.message : String(error)}`;
     }
-  } catch (error) {
-    mcpStatus = `failed: ${error instanceof Error ? error.message : String(error)}`;
   }
   let ruleStatus;
   let rulePath = "";
   try {
-    const result = await installRule(agentName, scope);
+    const result = await installRule(agentName, scope, mode);
     ruleStatus = result.status;
     rulePath = result.path;
   } catch (error) {
     ruleStatus = `failed: ${error instanceof Error ? error.message : String(error)}`;
   }
-  return { agent: agent.displayName, mcpStatus, mcpPath, ruleStatus, rulePath };
+  let skillStatus;
+  let skillPath = "";
+  try {
+    const result = await installSkill(agentName, scope, mode);
+    skillStatus = result.status;
+    skillPath = result.path;
+  } catch (error) {
+    skillStatus = `failed: ${error instanceof Error ? error.message : String(error)}`;
+  }
+  return {
+    agent: agent.displayName,
+    mcpStatus,
+    mcpPath,
+    ruleStatus,
+    rulePath,
+    skillStatus,
+    skillPath
+  };
 }
 async function setupCommand(options) {
   trackEvent("command", { name: "setup" });
+  const mode = await resolveMode(options);
+  if (!mode) return;
   const auth = resolveSetupAuth(options);
-  if (!auth) {
-    log.error("Set GRTL_API_KEY or pass --api-key before running setup.");
+  if (mode === "mcp" && !auth) {
+    log.error("MCP mode requires GRTL_API_KEY, GENRTL_API_KEY, or --api-key.");
     process.exitCode = 1;
     return;
   }
   const scope = options.project ? "project" : "global";
   const agents2 = await resolveAgents(options, scope);
   if (agents2.length === 0) return;
-  const spinner = ora("Configuring GenRTL MCP...").start();
+  const spinner = ora(`Installing GenRTL ${mode.toUpperCase()} integration...`).start();
   const results = [];
   for (const agentName of agents2) {
     spinner.text = `Configuring ${getAgent(agentName).displayName}...`;
-    results.push(await setupAgent(agentName, auth, scope));
+    results.push(await setupAgent(agentName, mode, auth, scope));
   }
   const failed = results.some(
-    (result) => result.mcpStatus.startsWith("failed") || result.ruleStatus.startsWith("failed")
+    (result) => result.mcpStatus?.startsWith("failed") || result.ruleStatus.startsWith("failed") || result.skillStatus.startsWith("failed")
   );
   if (failed) {
     spinner.warn("GenRTL setup completed with errors");
@@ -627,13 +838,20 @@ async function setupCommand(options) {
   log.blank();
   for (const result of results) {
     log.plain(`  ${pc3.bold(result.agent)}`);
-    log.plain(`    ${pc3.green("+")} MCP server ${result.mcpStatus}`);
-    log.plain(`      ${pc3.dim(result.mcpPath)}`);
+    if (result.mcpStatus && result.mcpPath) {
+      log.plain(`    ${pc3.green("+")} MCP server ${result.mcpStatus}`);
+      log.plain(`      ${pc3.dim(result.mcpPath)}`);
+    }
+    log.plain(`    ${pc3.green("+")} Skill ${result.skillStatus}`);
+    log.plain(`      ${pc3.dim(result.skillPath)}`);
     log.plain(`    ${pc3.green("+")} Rule ${result.ruleStatus}`);
     log.plain(`      ${pc3.dim(result.rulePath)}`);
   }
   log.blank();
-  trackEvent("setup", { agents: agents2, scope, authMode: "api-key" });
+  if (mode === "cli" && !process.env.GRTL_API_KEY && !process.env.GENRTL_API_KEY) {
+    log.warn("Set GRTL_API_KEY or GENRTL_API_KEY in the coding agent's environment before use.");
+  }
+  trackEvent("setup", { agents: agents2, scope, mode, authMode: auth?.mode ?? "environment" });
 }
 
 // src/commands/knowledge.ts
@@ -644,8 +862,8 @@ import ora2 from "ora";
 // src/constants.ts
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
-import { dirname as dirname3, join as join3 } from "path";
-var __dirname = dirname3(fileURLToPath(import.meta.url));
+import { dirname as dirname5, join as join3 } from "path";
+var __dirname = dirname5(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(readFileSync(join3(__dirname, "../package.json"), "utf-8"));
 var VERSION = pkg.version;
 var NAME = pkg.name;
@@ -737,6 +955,11 @@ var TOOL_COMMANDS = [
     alias: "spec2rtl-search",
     description: "Search Spec2RTL knowledge cards"
   },
+  {
+    name: "genrtl_spec2plan_search",
+    alias: "spec2plan-search",
+    description: "Search Spec2Plan knowledge cards"
+  },
   {
     name: "genrtl_verification_search",
     alias: "verification-search",
@@ -774,7 +997,7 @@ function buildKnowledgeSearchInput(query, options) {
   }
   const filters = {};
   if (options.type?.length) {
-    const allowed = /* @__PURE__ */ new Set(["spec2rtl", "verification", "debug"]);
+    const allowed = /* @__PURE__ */ new Set(["spec2rtl", "spec2plan", "verification", "debug"]);
     const invalid = options.type.find((type) => !allowed.has(type));
     if (invalid) {
       throw new InvalidArgumentError(`Invalid knowledge type: ${invalid}`);
@@ -851,7 +1074,7 @@ function printKnowledgeResult(result) {
   }
 }
 function addSearchOptions(command) {
-  return command.argument("<query>", "Natural-language RTL engineering question or diagnostic").option("--type <type...>", "Knowledge types: spec2rtl, verification, debug").option("--domain <domain>", "Filter by engineering domain").option("--tool <tool>", "Filter by EDA tool").option("--tool-version <version>", "Filter by EDA tool version").option("--error-type <type>", "Filter by error type").option("--severity <severity>", "Filter by severity").option("--interface <interface>", "Filter by hardware interface").option("--target <target>", "Filter by target: fpga, asic, or both").option("--tag <tag...>", "Filter by one or more tags").option("--top-k <count>", "Maximum results (1-20)", parseInteger).option("--min-score <score>", "Minimum similarity score (0-1)", parseNumber).option("--workspace-id <id>", "GenRTL workspace ID").option("--json", "Output the structured MCP result as JSON");
+  return command.argument("<query>", "Natural-language RTL engineering question or diagnostic").option("--type <type...>", "Knowledge types: spec2rtl, spec2plan, verification, debug").option("--domain <domain>", "Filter by engineering domain").option("--tool <tool>", "Filter by EDA tool").option("--tool-version <version>", "Filter by EDA tool version").option("--error-type <type>", "Filter by error type").option("--severity <severity>", "Filter by severity").option("--interface <interface>", "Filter by hardware interface").option("--target <target>", "Filter by target: fpga, asic, or both").option("--tag <tag...>", "Filter by one or more tags").option("--top-k <count>", "Maximum results (1-20)", parseInteger).option("--min-score <score>", "Minimum similarity score (0-1)", parseNumber).option("--workspace-id <id>", "GenRTL workspace ID").option("--json", "Output the structured MCP result as JSON");
 }
 function registerKnowledgeCommands(program2) {
   for (const tool of TOOL_COMMANDS) {
@@ -869,8 +1092,8 @@ import pc5 from "picocolors";
 
 // src/utils/update-check.ts
 import { homedir as homedir2 } from "os";
-import { dirname as dirname4, join as join4 } from "path";
-import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname6, join as join4 } from "path";
+import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile4 } from "fs/promises";
 var DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 var UPDATE_STATE_FILE = join4(homedir2(), ".genrtl", "cli-state.json");
 function getStateFilePath(stateFile) {
@@ -886,8 +1109,8 @@ async function readUpdateState(stateFile) {
 }
 async function writeUpdateState(state, stateFile) {
   const path = getStateFilePath(stateFile);
-  await mkdir3(dirname4(path), { recursive: true });
-  await writeFile3(path, JSON.stringify(state, null, 2) + "\n", "utf-8");
+  await mkdir4(dirname6(path), { recursive: true });
+  await writeFile4(path, JSON.stringify(state, null, 2) + "\n", "utf-8");
 }
 function compareVersions(a, b) {
   const normalize = (version) => version.split("-", 1)[0].split(".").map((part) => Number.parseInt(part, 10) || 0);
@@ -1063,13 +1286,13 @@ function registerUpgradeCommand(program2) {
   });
 }
 function runCommand(command, args) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve3, reject) => {
     const child = spawn(command, args, {
       stdio: "inherit",
       shell: process.platform === "win32"
     });
     child.on("error", reject);
-    child.on("close", (code) => resolve(code));
+    child.on("close", (code) => resolve3(code));
   });
 }
 async function runUpgradePlan(plan) {
@@ -1206,12 +1429,13 @@ program.name("grtl").description("GenRTL CLI - Search RTL engineering knowledge
   `
 Examples:
   ${brand.dim("# Configure GenRTL for your coding agent")}
-  ${brand.primary("GRTL_API_KEY=your_key npx @genrtl/grtl setup --cursor")}
-  ${brand.primary("GRTL_API_KEY=your_key npx @genrtl/grtl setup --codex --project")}
+  ${brand.primary("npx @genrtl/grtl setup --cli --codex --project")}
+  ${brand.primary("GRTL_API_KEY=your_key npx @genrtl/grtl setup --mcp --codex --project")}
 
-  ${brand.dim("# Search the same four tools exposed by the GenRTL MCP server")}
+  ${brand.dim("# Search the same five tools exposed by the GenRTL MCP server")}
   ${brand.primary('npx @genrtl/grtl knowledge-search "AXI stream backpressure design"')}
   ${brand.primary('npx @genrtl/grtl spec2rtl-search "Generate an APB register block"')}
+  ${brand.primary('npx @genrtl/grtl spec2plan-search "Plan an APB register block implementation"')}
   ${brand.primary('npx @genrtl/grtl verification-search "Verify an async FIFO"')}
   ${brand.primary('npx @genrtl/grtl debug-search "Explain this Vivado CDC warning"')}
 `

package/package.json

@@ -1,21 +1,21 @@
-{
+{
   "name": "@genrtl/grtl",
-  "version": "0.1.1",
-  "description": "CLI for GenRTL RTL engineering knowledge and MCP setup",
+  "version": "0.3.0",
+  "description": "CLI, MCP, and coding-agent Skills for GenRTL RTL engineering knowledge",
   "type": "module",
   "bin": {
     "grtl": "dist/index.js"
   },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src --fix",
-    "lint:check": "eslint src",
-    "format": "prettier --write src",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --fix",
+    "lint:check": "eslint src",
+    "format": "prettier --write src",
     "format:check": "prettier --check src",
     "clean": "rm -rf dist node_modules",
     "test": "vitest run",
@@ -29,24 +29,24 @@
     "figlet": "^1.9.4",
     "ora": "^9.0.0",
     "picocolors": "^1.1.1"
-  },
-  "devDependencies": {
-    "@types/figlet": "^1.7.0",
-    "@types/node": "^22.19.1",
-    "@typescript-eslint/eslint-plugin": "^8.28.0",
-    "@typescript-eslint/parser": "^8.28.0",
-    "eslint": "^9.34.0",
-    "eslint-plugin-prettier": "^5.2.5",
-    "prettier": "^3.6.2",
-    "tsup": "^8.5.0",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.28.0",
-    "vitest": "^4.0.13"
-  },
-  "keywords": [
-    "genrtl",
-    "cli",
-    "ai",
+  },
+  "devDependencies": {
+    "@types/figlet": "^1.7.0",
+    "@types/node": "^22.19.1",
+    "@typescript-eslint/eslint-plugin": "^8.28.0",
+    "@typescript-eslint/parser": "^8.28.0",
+    "eslint": "^9.34.0",
+    "eslint-plugin-prettier": "^5.2.5",
+    "prettier": "^3.6.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.28.0",
+    "vitest": "^4.0.13"
+  },
+  "keywords": [
+    "genrtl",
+    "cli",
+    "ai",
     "rtl",
     "systemverilog",
     "verilog",
@@ -54,9 +54,9 @@
     "mcp"
   ],
   "author": "xroting",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
     "url": "git+https://github.com/xroting/grtl.git",
     "directory": "packages/cli"
   },