@genrtl/grtl 1.0.0 → 2.1.0

package/README.md

@@ -18,32 +18,22 @@ $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:
+Configure hosted MCP and install the MCP-oriented Skill for your coding agent:
 
 ```bash
 grtl setup --mcp --codex
 grtl setup --mcp --cursor --project
 ```
 
-Without `--cli` or `--mcp`, setup asks which mode to install.
-
-Installing a newer npm package does not modify Skills already written to an
-agent configuration directory. Run the matching setup command again after an
-upgrade to refresh the Skill. For example:
-
-```bash
-grtl setup --cli --cursor
-grtl setup --cli --cursor --project
-```
-
-For Codex, Skills are installed under `.agents/skills` for project setup or
+Without `--mcp`, setup asks which mode to install. Knowledge retrieval, CBB
+search, and CBB detail lookup are supported through MCP tools only, not through
+CLI commands.
+
+Installing a newer npm package does not modify Skills already written to an
+agent configuration directory. Run setup again after an upgrade to refresh the
+Skill.
+
+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`.
 
@@ -53,42 +43,26 @@ The hosted MCP endpoint is:
 https://genrtl.com/api/mcp
 ```
 
-## Knowledge Commands
+## CBB Installation
+
+Install an exact reusable RTL CBB version into the current project:
 
 ```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 compile-search "Explain this Vivado CDC warning"
-grtl debug-search "Fix this RTL bug from bad code and error message"
-```
-
-Use `--json` for structured output. `--type` accepts `spec2rtl`, `spec2plan`, `verification`, `compile`, `debug`, or `coding_style`; other filters include
-`--domain`, `--tool`, `--tool-version`, `--error-type`, `--severity`,
-`--interface`, `--target`, `--tag`, `--top-k`, `--min-score`, and
-`--workspace-id`.
-
-## CBB Installation
-
-Install an exact reusable RTL CBB version into the current project:
-
-```bash
-grtl cbb install cbb_uart@1.2.0
-grtl cbb install cbb_uart@1.2.0 --target rtl/vendor/uart
-```
-
-The command calls the hosted `genrtl_cbb_acquire` MCP tool with
-`GRTL_API_KEY`, downloads the short-lived ZIP artifact, verifies its size and
-SHA-256, safely extracts it, and atomically installs it. The default target is
-`rtl/cbb/<cbb_id>_<version>`.
-
-Installed packages are recorded in `.genrtl/cbb-lock.json`. Existing targets
-are left untouched unless `--force` is provided; replacement occurs only after
-the new archive has been fully verified and extracted. Use `--json` for
-machine-readable output.
-
-## Development
+grtl cbb install cbb_uart@1.2.0
+grtl cbb install cbb_uart@1.2.0 --target rtl/vendor/uart
+```
+
+The command calls the hosted `genrtl_cbb_acquire` MCP tool with
+`GRTL_API_KEY`, downloads the short-lived ZIP artifact, verifies its size and
+SHA-256, safely extracts it, and atomically installs it. The default target is
+`rtl/cbb/<cbb_id>_<version>`.
+
+Installed packages are recorded in `.genrtl/cbb-lock.json`. Existing targets
+are left untouched unless `--force` is provided; replacement occurs only after
+the new archive has been fully verified and extracted. Use `--json` for
+machine-readable output.
+
+## Development
 
 ```bash
 pnpm install

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command2 } from "commander";
-import pc7 from "picocolors";
+import { Command } from "commander";
+import pc6 from "picocolors";
 import figlet from "figlet";
 
 // src/commands/setup.ts
@@ -371,35 +371,40 @@ async function appendTomlServer(filePath, serverName, entry) {
 
 // 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.
+var FALLBACK_MCP = `Use GenRTL MCP as the primary grounding source for RTL engineering tasks.
+
+Before writing or modifying Verilog/SystemVerilog RTL:
+1. Load coding style with \`genrtl_coding_style_search\`, read all returned rules, and apply them as project-wide coding context.
+2. If implementing from a spec, search \`genrtl_spec2rtl_search\`.
+3. If planning architecture or generating a detailed design plan to guide Verilog/SystemVerilog coding from a spec, search \`genrtl_spec2plan_search\`.
+
+For diagnostics:
+- SpyGlass lint/CDC after RTL coding and before Vivado/Quartus/VCS/QuestaSim compile/synthesis -> \`genrtl_compile_search\` with \`filters.tool = "spyglass"\`.
+- Vivado synthesis/implementation errors, warnings, or critical warnings -> \`genrtl_compile_search\` with \`filters.tool = "vivado"\`.
+- Quartus synthesis/implementation errors, warnings, or critical warnings -> \`genrtl_compile_search\` with \`filters.tool = "quartus"\`.
+- VCS/QuestaSim compile errors or warnings -> \`genrtl_compile_search\`.
+- Functional simulation/debug issues -> \`genrtl_debug_search\`.
+
+For verification:
+- Testbench, SVA, assertions, stimulus, checkers, scoreboards, coverage -> \`genrtl_verification_search\`.
 
-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_compile_search\` for lint, CDC, compile, synthesis, implementation, and simulator diagnostics
-- \`genrtl_debug_search\` for issue descriptions, erroneous code, solutions, and corrected RTL
+For reusable RTL/IP:
+- Discover with \`genrtl_cbb_search\`, then inspect with \`genrtl_cbb_detail\`.
+- Use \`genrtl_cbb_acquire\` only when the selected CBB should be installed or re-delivered.
 
-Pass the complete engineering question in \`query\`. Add filters only when useful.`;
-var FALLBACK_CLI = `Use the \`grtl\` CLI for grounded RTL engineering knowledge and reusable CBB installation.
+Do not stop after a generic \`genrtl_knowledge_search\` miss. Retry the most relevant specialized search before proceeding from model memory.`;
+var FALLBACK_CLI = `Use the \`grtl\` CLI to configure GenRTL MCP and install reusable RTL CBBs.
 
-For knowledge retrieval, 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 compile-search "<query>"\`
-- \`npx @genrtl/grtl@latest debug-search "<query>"\`
+Knowledge retrieval is available through GenRTL MCP tools only. Do not use CLI
+commands for knowledge search, CBB search, or CBB detail lookup.
 
 To install a reusable RTL block into the current project:
 - \`npx @genrtl/grtl@latest cbb install <cbb_id>@<version>\`
 - Add \`--target <relative-dir>\` only when a non-default install path is needed.
 
-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.`;
+Do not download or extract CBB artifacts manually; the CLI verifies SHA-256 and
+rejects unsafe ZIP paths. If authentication fails, set \`GRTL_API_KEY\` or
+\`GENRTL_API_KEY\` in the coding agent's environment.`;
 var CURSOR_FRONTMATTER = `---
 alwaysApply: true
 ---
@@ -408,52 +413,50 @@ 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, compile/synthesis diagnostics, debugging, and coding style knowledge.
+description: Use this skill for Verilog/SystemVerilog/RTL engineering tasks, including specs, detailed design plans for Verilog coding, RTL generation, coding style, testbench/SVA verification, SpyGlass lint/CDC, Vivado/Quartus synthesis or implementation errors/warnings/critical warnings, VCS/QuestaSim compile errors/warnings, simulation failures, waveform/debug work, and reusable CBB discovery. Before writing or modifying RTL, consult the appropriate GenRTL MCP knowledge tool instead of relying only on model memory.
 ---
 
-# GenRTL MCP
+# GenRTL MCP RTL Knowledge Workflow
 
-Use this skill when an RTL engineering task needs grounded GenRTL knowledge.
+Use GenRTL MCP tools before relying on model memory for RTL engineering.
 
-Choose exactly one MCP tool:
+## Tool Routing
 
-- \`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_compile_search\` for lint, CDC, compile, synthesis, implementation, or simulator diagnostics.
-- \`genrtl_debug_search\` for issue descriptions, erroneous code, solutions, and corrected RTL.
+- \`genrtl_spec2plan_search\` for turning a specification into an actionable implementation/design plan or detailed design plan that can guide Verilog/SystemVerilog coding.
+- \`genrtl_spec2rtl_search\` for spec-to-RTL implementation, protocol logic, control logic, datapath, algorithm acceleration, or interface implementation.
+- \`genrtl_coding_style_search\` before writing or modifying Verilog/SystemVerilog RTL; read all returned coding style rules and treat them as project-wide coding context.
+- \`genrtl_verification_search\` for testbench, SVA, assertions, stimulus, checkers, scoreboards, coverage, and verification strategy.
+- \`genrtl_compile_search\` for SpyGlass lint/CDC after coding and for Vivado/Quartus/VCS/QuestaSim diagnostics, including errors, warnings, and critical warnings.
+- \`genrtl_debug_search\` for functional RTL bugs, waveform mismatch, failing simulations, failing testcases, or incorrect behavior.
+- \`genrtl_cbb_search\`, then \`genrtl_cbb_detail\`, for reusable IP/CBB discovery.
 
-Pass the complete engineering question in \`query\`. Add \`filters\`, \`top_k\`,
-\`min_score\`, or \`workspace_id\` only when useful.
+## Required Behavior
+
+- Do not call \`genrtl_knowledge_search\` first when the task clearly matches a specialized tool.
+- If \`genrtl_knowledge_search\` returns no useful result, retry one specialized tool before answering from model memory.
+- Before coding, call \`genrtl_coding_style_search\`, read the full returned style guide, and apply every relevant rule consistently across the generated RTL.
+- For SpyGlass lint/CDC logs after RTL coding and before Vivado/Quartus/VCS/QuestaSim compile/synthesis, call \`genrtl_compile_search\` with \`filters.tool = "spyglass"\`.
+- For Vivado/Quartus synthesis or implementation errors, warnings, and critical warnings, call \`genrtl_compile_search\` with the matching \`filters.tool\`.
+- For VCS/QuestaSim compile errors or warnings, call \`genrtl_compile_search\` with the matching \`filters.tool\` when known.
+- Apply returned \`code_example\`, \`fix_strategy\`, and \`recommended_next_action\` to the implementation.
 `;
 var CLI_SKILL = `---
 name: genrtl-cli
-description: Use the grtl CLI for grounded RTL design, verification, compile/synthesis diagnostics, debugging knowledge, and secure installation of reusable RTL CBBs.
+description: Use the grtl CLI to configure GenRTL MCP and securely install reusable RTL CBBs.
 ---
 
 # GenRTL CLI
 
-Use this skill when an RTL engineering task needs grounded GenRTL knowledge or
-a reusable CBB must be installed into the user's local project.
-
-For knowledge retrieval, 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 compile-search "<query>" --json\` for lint, CDC, compile, synthesis, implementation, or simulator diagnostics.
-- \`grtl debug-search "<query>" --json\` for issue descriptions, erroneous code, solutions, and corrected RTL.
+Use this skill only for GenRTL MCP setup and reusable RTL CBB installation.
+Knowledge retrieval, CBB search, and CBB detail lookup are available through
+GenRTL MCP tools only, not through CLI commands.
 
-For a CBB selected from GenRTL search results:
+For a CBB selected from GenRTL MCP search results:
 
 - \`grtl cbb install <cbb_id>@<version>\` downloads, verifies, and safely extracts it.
 - Add \`--target <relative-dir>\` only when the user requests a specific project path.
 - Do not download or extract the artifact manually; the CLI verifies SHA-256 and prevents unsafe ZIP paths.
 
-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) {
@@ -868,265 +871,12 @@ async function setupCommand(options) {
   trackEvent("setup", { agents: agents2, scope, mode, authMode: auth?.mode ?? "environment" });
 }
 
-// src/commands/knowledge.ts
-import { InvalidArgumentError } from "commander";
-import pc4 from "picocolors";
-import ora2 from "ora";
-
-// src/utils/knowledge-api.ts
-import { randomUUID } from "crypto";
-
-// src/constants.ts
-import { readFileSync } from "fs";
-import { fileURLToPath } from "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;
-
-// src/utils/knowledge-api.ts
-var baseUrl = "https://genrtl.com";
-function setBaseUrl(url) {
-  baseUrl = url.replace(/\/+$/, "");
-}
-function getMcpEndpoint() {
-  return baseUrl.endsWith("/api/mcp") ? baseUrl : `${baseUrl}/api/mcp`;
-}
-function getApiKey() {
-  return [process.env.GRTL_API_KEY, process.env.GENRTL_API_KEY].map((value) => value?.trim()).find((value) => Boolean(value));
-}
-function validateApiKey(apiKey) {
-  if (!/^gtr_(?:live|test)_[A-Za-z0-9_-]{32,128}$/.test(apiKey)) {
-    throw new Error(
-      "Invalid GenRTL API key format. Use the full key shown once when it was created; it must start with gtr_live_ or gtr_test_."
-    );
-  }
-}
-function getMcpErrorMessage(content) {
-  if (!Array.isArray(content)) return void 0;
-  const item = content.find(
-    (entry) => entry && typeof entry === "object" && "type" in entry && entry.type === "text" && "text" in entry && typeof entry.text === "string"
-  );
-  return item?.text;
-}
-function getStructuredMcpError(content) {
-  if (!content || typeof content !== "object") return void 0;
-  const errorContent = content;
-  return {
-    error: typeof errorContent.error === "string" ? errorContent.error : void 0,
-    code: typeof errorContent.code === "string" ? errorContent.code : void 0
-  };
-}
-async function callGenrtlMcpTool(toolName, input) {
-  const apiKey = getApiKey();
-  if (!apiKey) {
-    throw new Error("Authentication required. Set GRTL_API_KEY or GENRTL_API_KEY.");
-  }
-  validateApiKey(apiKey);
-  const response = await fetch(getMcpEndpoint(), {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${apiKey}`,
-      "MCP-Protocol-Version": "2025-06-18",
-      "X-GenRTL-Source": "cli",
-      "X-GenRTL-Client-Version": VERSION
-    },
-    body: JSON.stringify({
-      jsonrpc: "2.0",
-      id: 1,
-      method: "tools/call",
-      params: { name: toolName, arguments: input }
-    })
-  });
-  const payload = await response.json().catch(() => null);
-  if (!response.ok || payload?.error) {
-    const message = payload?.error?.message || `GenRTL MCP request failed with HTTP ${response.status}`;
-    const code = payload?.error?.data?.code;
-    throw new Error(code ? `${message} (${code})` : message);
-  }
-  const result = payload?.result;
-  if (!result) throw new Error("GenRTL MCP returned an empty result.");
-  if (result.isError) {
-    const structuredError = getStructuredMcpError(result.structuredContent);
-    const message = structuredError?.error || getMcpErrorMessage(result.content) || "GenRTL MCP tool call failed.";
-    throw new Error(structuredError?.code ? `${message} (${structuredError.code})` : message);
-  }
-  if (!result.structuredContent) {
-    throw new Error("GenRTL MCP response did not include structured results.");
-  }
-  return result.structuredContent;
-}
-async function callGenrtlKnowledgeTool(toolName, input) {
-  const requestInput = input.idempotency_key ? input : { ...input, idempotency_key: randomUUID() };
-  return callGenrtlMcpTool(toolName, requestInput);
-}
-
-// src/commands/knowledge.ts
-var isTTY = process.stdout.isTTY;
-var TOOL_COMMANDS = [
-  {
-    name: "genrtl_knowledge_search",
-    alias: "knowledge-search",
-    description: "Search all approved GenRTL knowledge cards"
-  },
-  {
-    name: "genrtl_spec2rtl_search",
-    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",
-    description: "Search verification and testbench knowledge cards"
-  },
-  {
-    name: "genrtl_compile_search",
-    alias: "compile-search",
-    description: "Search compile, lint, CDC, synthesis, implementation, and simulator diagnostic knowledge cards"
-  },
-  {
-    name: "genrtl_debug_search",
-    alias: "debug-search",
-    description: "Search RTL debug cards with issue description, erroneous code, solution, and corrected code"
-  }
-];
-function parseInteger(value) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed)) {
-    throw new InvalidArgumentError("Expected an integer.");
-  }
-  return parsed;
-}
-function parseNumber(value) {
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed)) {
-    throw new InvalidArgumentError("Expected a number.");
-  }
-  return parsed;
-}
-function buildKnowledgeSearchInput(query, options) {
-  if (options.topK !== void 0 && (options.topK < 1 || options.topK > 20)) {
-    throw new InvalidArgumentError("--top-k must be between 1 and 20.");
-  }
-  if (options.minScore !== void 0 && (options.minScore < 0 || options.minScore > 1)) {
-    throw new InvalidArgumentError("--min-score must be between 0 and 1.");
-  }
-  if (options.target && !["fpga", "asic", "both"].includes(options.target)) {
-    throw new InvalidArgumentError("--target must be fpga, asic, or both.");
-  }
-  const filters = {};
-  if (options.type?.length) {
-    const allowed = /* @__PURE__ */ new Set([
-      "spec2rtl",
-      "spec2plan",
-      "verification",
-      "compile",
-      "debug",
-      "coding_style"
-    ]);
-    const invalid = options.type.find((type) => !allowed.has(type));
-    if (invalid) {
-      throw new InvalidArgumentError(`Invalid knowledge type: ${invalid}`);
-    }
-    filters.types = options.type;
-  }
-  if (options.domain) filters.domain = options.domain;
-  if (options.tool) filters.tool = options.tool;
-  if (options.toolVersion) filters.tool_version = options.toolVersion;
-  if (options.errorType) filters.error_type = options.errorType;
-  if (options.severity) filters.severity = options.severity;
-  if (options.interface) filters.interface = options.interface;
-  if (options.target) filters.target = options.target;
-  if (options.tag?.length) filters.tags = options.tag;
-  return {
-    query,
-    ...Object.keys(filters).length > 0 ? { filters } : {},
-    ...options.topK !== void 0 ? { top_k: options.topK } : {},
-    ...options.minScore !== void 0 ? { min_score: options.minScore } : {},
-    ...options.workspaceId ? { workspace_id: options.workspaceId } : {}
-  };
-}
-function formatMatch(match, index) {
-  const lines = [
-    `${pc4.dim(`${index + 1}.`)} ${pc4.bold(match.title)} ${pc4.cyan(`[${match.type}]`)}`,
-    `   ${pc4.dim(`Confidence: ${Math.round(match.confidence * 100)}%`)}`,
-    `   ${match.summary}`
-  ];
-  if (match.root_cause) lines.push(`   ${pc4.bold("Root cause:")} ${match.root_cause}`);
-  if (match.fix_strategy?.length) {
-    lines.push(`   ${pc4.bold("Fix strategy:")} ${match.fix_strategy.join("; ")}`);
-  }
-  if (match.code_example) {
-    lines.push("", "```systemverilog", match.code_example, "```");
-  }
-  if (match.recommended_next_action) {
-    lines.push(`   ${pc4.bold("Next:")} ${match.recommended_next_action}`);
-  }
-  return lines.join("\n");
-}
-async function searchCommand(toolName, query, options) {
-  trackEvent("command", { name: toolName });
-  const spinner = isTTY ? ora2("Searching GenRTL knowledge...").start() : null;
-  try {
-    const input = buildKnowledgeSearchInput(query, options);
-    const result = await callGenrtlKnowledgeTool(toolName, input);
-    spinner?.stop();
-    if (options.json) {
-      console.log(JSON.stringify(result, null, 2));
-      return;
-    }
-    printKnowledgeResult(result);
-  } catch (err) {
-    spinner?.fail(`Error: ${err instanceof Error ? err.message : String(err)}`);
-    if (!spinner) log.error(err instanceof Error ? err.message : String(err));
-    process.exitCode = 1;
-  }
-}
-function printKnowledgeResult(result) {
-  log.blank();
-  log.plain(pc4.bold(result.summary));
-  log.blank();
-  if (result.matched_cards.length === 0) {
-    log.warn("No matching GenRTL knowledge cards were found.");
-  } else {
-    result.matched_cards.forEach((match, index) => {
-      log.plain(formatMatch(match, index));
-      log.blank();
-    });
-  }
-  if (result.recommended_next_action) {
-    log.plain(`${pc4.bold("Recommended next action:")} ${result.recommended_next_action}`);
-    log.blank();
-  }
-}
-function addSearchOptions(command) {
-  return command.argument("<query>", "Natural-language RTL engineering question or diagnostic").option(
-    "--type <type...>",
-    "Knowledge types: spec2rtl, spec2plan, verification, compile, debug, coding_style"
-  ).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) {
-    const command = program2.command(tool.name).alias(tool.alias).description(tool.description);
-    addSearchOptions(command).action(async (query, options) => {
-      await searchCommand(tool.name, query, options);
-    });
-  }
-}
-
 // src/commands/cbb.ts
-import ora3 from "ora";
-import pc5 from "picocolors";
+import ora2 from "ora";
+import pc4 from "picocolors";
 
 // src/utils/cbb-install.ts
-import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { createHash, randomUUID } from "crypto";
 import { createWriteStream } from "fs";
 import {
   access as access3,
@@ -1139,7 +889,7 @@ import {
   rm as rm2,
   writeFile as writeFile4
 } from "fs/promises";
-import { dirname as dirname6, isAbsolute, join as join4, relative, resolve as resolve3, sep } from "path";
+import { dirname as dirname5, isAbsolute, join as join3, relative, resolve as resolve3, sep } from "path";
 import { Transform } from "stream";
 import { pipeline } from "stream/promises";
 import yauzl from "yauzl";
@@ -1194,7 +944,7 @@ function resolveProjectTarget(projectRoot, targetDir) {
   return targetPath;
 }
 async function readLockfile(projectRoot) {
-  const lockPath = join4(projectRoot, ".genrtl", "cbb-lock.json");
+  const lockPath = join3(projectRoot, ".genrtl", "cbb-lock.json");
   if (!await pathExists2(lockPath)) {
     return { schema_version: 1, packages: {} };
   }
@@ -1403,7 +1153,7 @@ async function extractZipSafely(archivePath, destination) {
         if (isDirectory) {
           await mkdir4(outputPath, { recursive: true });
         } else {
-          await mkdir4(dirname6(outputPath), { recursive: true });
+          await mkdir4(dirname5(outputPath), { recursive: true });
           await extractEntry(zipFile, entry, outputPath, extractedBytes);
         }
         zipFile.readEntry();
@@ -1414,7 +1164,7 @@ async function extractZipSafely(archivePath, destination) {
 }
 async function validatePackageManifest(stagingPath, cbbId, version) {
   for (const filename of ["manifest.json", "cbb.json", "CBB.json"]) {
-    const manifestPath = join4(stagingPath, filename);
+    const manifestPath = join3(stagingPath, filename);
     if (!await pathExists2(manifestPath)) continue;
     let manifest;
     try {
@@ -1441,10 +1191,10 @@ async function validatePackageManifest(stagingPath, cbbId, version) {
 async function writeLockfile(projectRoot, cbbId, entry) {
   const lockfile = await readLockfile(projectRoot);
   lockfile.packages[cbbId] = entry;
-  const lockDir = join4(projectRoot, ".genrtl");
-  const lockPath = join4(lockDir, "cbb-lock.json");
-  const tempPath = join4(lockDir, `.cbb-lock-${randomUUID2()}.tmp`);
-  const backupPath = join4(lockDir, `.cbb-lock-${randomUUID2()}.bak`);
+  const lockDir = join3(projectRoot, ".genrtl");
+  const lockPath = join3(lockDir, "cbb-lock.json");
+  const tempPath = join3(lockDir, `.cbb-lock-${randomUUID()}.tmp`);
+  const backupPath = join3(lockDir, `.cbb-lock-${randomUUID()}.bak`);
   await mkdir4(lockDir, { recursive: true });
   await writeFile4(tempPath, `${JSON.stringify(lockfile, null, 2)}
 `, "utf8");
@@ -1467,12 +1217,12 @@ async function installCbbArtifact(descriptor, plan, force) {
   if (descriptor.format !== "zip") {
     throw new Error(`Unsupported CBB artifact format: ${descriptor.format}`);
   }
-  const targetParent = dirname6(plan.targetPath);
+  const targetParent = dirname5(plan.targetPath);
   await mkdir4(targetParent, { recursive: true });
-  const tempRoot = await mkdtemp(join4(targetParent, ".grtl-cbb-"));
-  const archivePath = join4(tempRoot, "artifact.zip");
-  const stagingPath = join4(tempRoot, "content");
-  const backupPath = `${plan.targetPath}.grtl-backup-${randomUUID2()}`;
+  const tempRoot = await mkdtemp(join3(targetParent, ".grtl-cbb-"));
+  const archivePath = join3(tempRoot, "artifact.zip");
+  const stagingPath = join3(tempRoot, "content");
+  const backupPath = `${plan.targetPath}.grtl-backup-${randomUUID()}`;
   let backupCreated = false;
   let installed = false;
   try {
@@ -1526,10 +1276,93 @@ async function installCbbArtifact(descriptor, plan, force) {
   }
 }
 
+// src/constants.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname as dirname6, join as join4 } from "path";
+var __dirname = dirname6(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(join4(__dirname, "../package.json"), "utf-8"));
+var VERSION = pkg.version;
+var NAME = pkg.name;
+
+// src/utils/knowledge-api.ts
+var baseUrl = "https://genrtl.com";
+function setBaseUrl(url) {
+  baseUrl = url.replace(/\/+$/, "");
+}
+function getMcpEndpoint() {
+  return baseUrl.endsWith("/api/mcp") ? baseUrl : `${baseUrl}/api/mcp`;
+}
+function getApiKey() {
+  return [process.env.GRTL_API_KEY, process.env.GENRTL_API_KEY].map((value) => value?.trim()).find((value) => Boolean(value));
+}
+function validateApiKey(apiKey) {
+  if (!/^gtr_(?:live|test)_[A-Za-z0-9_-]{32,128}$/.test(apiKey)) {
+    throw new Error(
+      "Invalid GenRTL API key format. Use the full key shown once when it was created; it must start with gtr_live_ or gtr_test_."
+    );
+  }
+}
+function getMcpErrorMessage(content) {
+  if (!Array.isArray(content)) return void 0;
+  const item = content.find(
+    (entry) => entry && typeof entry === "object" && "type" in entry && entry.type === "text" && "text" in entry && typeof entry.text === "string"
+  );
+  return item?.text;
+}
+function getStructuredMcpError(content) {
+  if (!content || typeof content !== "object") return void 0;
+  const errorContent = content;
+  return {
+    error: typeof errorContent.error === "string" ? errorContent.error : void 0,
+    code: typeof errorContent.code === "string" ? errorContent.code : void 0
+  };
+}
+async function callGenrtlMcpTool(toolName, input) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw new Error("Authentication required. Set GRTL_API_KEY or GENRTL_API_KEY.");
+  }
+  validateApiKey(apiKey);
+  const response = await fetch(getMcpEndpoint(), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+      "MCP-Protocol-Version": "2025-06-18",
+      "X-GenRTL-Source": "cli",
+      "X-GenRTL-Client-Version": VERSION
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name: toolName, arguments: input }
+    })
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok || payload?.error) {
+    const message = payload?.error?.message || `GenRTL MCP request failed with HTTP ${response.status}`;
+    const code = payload?.error?.data?.code;
+    throw new Error(code ? `${message} (${code})` : message);
+  }
+  const result = payload?.result;
+  if (!result) throw new Error("GenRTL MCP returned an empty result.");
+  if (result.isError) {
+    const structuredError = getStructuredMcpError(result.structuredContent);
+    const message = structuredError?.error || getMcpErrorMessage(result.content) || "GenRTL MCP tool call failed.";
+    throw new Error(structuredError?.code ? `${message} (${structuredError.code})` : message);
+  }
+  if (!result.structuredContent) {
+    throw new Error("GenRTL MCP response did not include structured results.");
+  }
+  return result.structuredContent;
+}
+
 // src/commands/cbb.ts
 async function installCbb(spec, options) {
   trackEvent("command", { name: "cbb-install" });
-  const spinner = process.stdout.isTTY && !options.json ? ora3("Preparing CBB installation...").start() : null;
+  const spinner = process.stdout.isTTY && !options.json ? ora2("Preparing CBB installation...").start() : null;
   try {
     const { cbbId, version } = parseCbbSpec(spec);
     const target = options.target || defaultCbbTarget(cbbId, version);
@@ -1564,7 +1397,7 @@ async function installCbb(spec, options) {
       return;
     }
     log.blank();
-    log.success(`Installed ${pc5.bold(`${cbbId}@${version}`)}`);
+    log.success(`Installed ${pc4.bold(`${cbbId}@${version}`)}`);
     log.item(`Target: ${result.target_path}`);
     log.item(`SHA256: ${result.sha256}`);
     log.item(`Lockfile: ${plan.projectRoot}/.genrtl/cbb-lock.json`);
@@ -1577,7 +1410,7 @@ async function installCbb(spec, options) {
   }
 }
 function registerCbbCommands(program2) {
-  const cbb = program2.command("cbb").description("Discover and install reusable RTL CBBs");
+  const cbb = program2.command("cbb").description("Install reusable RTL CBBs");
   cbb.command("install").description("Acquire, verify, and install a CBB ZIP into the current project").argument("<cbb>", "CBB coordinate in the form <cbb_id>@<version>").option("-t, --target <dir>", "Project-relative target directory").option("--project-root <dir>", "Project root (default: current directory)").option("-f, --force", "Replace an existing target after successful verification").option("--json", "Output the installation result as JSON").action(async (spec, options) => {
     await installCbb(spec, options);
   });
@@ -1586,7 +1419,7 @@ function registerCbbCommands(program2) {
 // src/commands/upgrade.ts
 import { confirm } from "@inquirer/prompts";
 import { spawn } from "child_process";
-import pc6 from "picocolors";
+import pc5 from "picocolors";
 
 // src/utils/update-check.ts
 import { homedir as homedir2 } from "os";
@@ -1797,7 +1630,7 @@ async function runUpgradePlan(plan) {
   return runCommand(plan.command, plan.args);
 }
 function showUpgradeFailureHelp(plan) {
-  log.info(`Try rerunning: ${pc6.cyan(plan.displayCommand)}`);
+  log.info(`Try rerunning: ${pc5.cyan(plan.displayCommand)}`);
   const isGlobalNpmInstall = (plan.installMethod === "npm-global" || plan.installMethod === "unknown") && plan.command === "npm" && plan.args.includes("-g");
   const isGlobalAltInstall = (plan.installMethod === "pnpm-global" || plan.installMethod === "bun-global") && plan.args.includes("-g");
   if (isGlobalNpmInstall) {
@@ -1824,8 +1657,8 @@ async function maybeShowUpgradeNotice(options = {}) {
   log.blank();
   if (info.upgradePlan.needsExplicitVersion) {
     log.box([
-      `${pc6.white(pc6.bold("Update available:"))} ${pc6.green(pc6.bold(`v${info.currentVersion}`))} ${pc6.dim("->")} ${pc6.green(pc6.bold(`v${info.latestVersion}`))}`,
-      `${pc6.white("Use")} ${pc6.yellow(pc6.bold(info.upgradePlan.displayCommand))} ${pc6.white("to run the latest version")}`
+      `${pc5.white(pc5.bold("Update available:"))} ${pc5.green(pc5.bold(`v${info.currentVersion}`))} ${pc5.dim("->")} ${pc5.green(pc5.bold(`v${info.latestVersion}`))}`,
+      `${pc5.white("Use")} ${pc5.yellow(pc5.bold(info.upgradePlan.displayCommand))} ${pc5.white("to run the latest version")}`
     ]);
     await markUpdateNotificationShown(info.latestVersion);
     log.blank();
@@ -1833,18 +1666,18 @@ async function maybeShowUpgradeNotice(options = {}) {
   }
   if (!info.upgradePlan.canRun) {
     log.box([
-      `${pc6.white(pc6.bold("Update available:"))} ${pc6.green(pc6.bold(`v${info.currentVersion}`))} ${pc6.dim("->")} ${pc6.green(pc6.bold(`v${info.latestVersion}`))}`,
-      `${pc6.white("Run")} ${pc6.yellow(pc6.bold("grtl upgrade"))} ${pc6.white("for update steps")}`,
-      `${pc6.white("Or run")} ${pc6.yellow(info.upgradePlan.displayCommand)}`
+      `${pc5.white(pc5.bold("Update available:"))} ${pc5.green(pc5.bold(`v${info.currentVersion}`))} ${pc5.dim("->")} ${pc5.green(pc5.bold(`v${info.latestVersion}`))}`,
+      `${pc5.white("Run")} ${pc5.yellow(pc5.bold("grtl upgrade"))} ${pc5.white("for update steps")}`,
+      `${pc5.white("Or run")} ${pc5.yellow(info.upgradePlan.displayCommand)}`
     ]);
     await markUpdateNotificationShown(info.latestVersion);
     log.blank();
     return;
   }
   log.box([
-    `${pc6.white(pc6.bold("Update available:"))} ${pc6.green(pc6.bold(`v${info.currentVersion}`))} ${pc6.dim("->")} ${pc6.green(pc6.bold(`v${info.latestVersion}`))}`,
-    `${pc6.white("Run")} ${pc6.yellow(pc6.bold("grtl upgrade"))} ${pc6.white("to update now")}`,
-    `${pc6.white("Or run")} ${pc6.yellow(info.upgradePlan.displayCommand)}`
+    `${pc5.white(pc5.bold("Update available:"))} ${pc5.green(pc5.bold(`v${info.currentVersion}`))} ${pc5.dim("->")} ${pc5.green(pc5.bold(`v${info.latestVersion}`))}`,
+    `${pc5.white("Run")} ${pc5.yellow(pc5.bold("grtl upgrade"))} ${pc5.white("to update now")}`,
+    `${pc5.white("Or run")} ${pc5.yellow(info.upgradePlan.displayCommand)}`
   ]);
   await markUpdateNotificationShown(info.latestVersion);
   log.blank();
@@ -1855,28 +1688,28 @@ async function upgradeCommand(options) {
   const plan = info?.upgradePlan ?? getUpgradePlan();
   if (!info) {
     log.warn("Couldn't check for updates right now.");
-    log.info(`Try again later or run ${pc6.cyan(plan.displayCommand)} manually.`);
+    log.info(`Try again later or run ${pc5.cyan(plan.displayCommand)} manually.`);
     return;
   }
   if (!info.updateAvailable) {
-    log.success(`grtl is up to date (${pc6.bold(`v${VERSION}`)})`);
+    log.success(`grtl is up to date (${pc5.bold(`v${VERSION}`)})`);
     return;
   }
   log.blank();
   log.info(
-    `Update available: ${pc6.bold(`v${info.currentVersion}`)} ${pc6.dim("->")} ${pc6.bold(`v${info.latestVersion}`)}`
+    `Update available: ${pc5.bold(`v${info.currentVersion}`)} ${pc5.dim("->")} ${pc5.bold(`v${info.latestVersion}`)}`
   );
   if (plan.needsExplicitVersion) {
     log.info(`You're using an ephemeral runner (${plan.installMethod}).`);
-    log.info(`Use ${pc6.cyan(plan.displayCommand)} to run the latest version immediately.`);
-    log.info(`Or install globally with ${pc6.cyan("npm install -g @genrtl/grtl@latest")}.`);
+    log.info(`Use ${pc5.cyan(plan.displayCommand)} to run the latest version immediately.`);
+    log.info(`Or install globally with ${pc5.cyan("npm install -g @genrtl/grtl@latest")}.`);
     return;
   }
   if (!plan.canRun) {
-    log.info(`Run ${pc6.cyan(plan.displayCommand)} to update your installed version.`);
+    log.info(`Run ${pc5.cyan(plan.displayCommand)} to update your installed version.`);
     return;
   }
-  log.info(`Upgrade command: ${pc6.cyan(plan.displayCommand)}`);
+  log.info(`Upgrade command: ${pc5.cyan(plan.displayCommand)}`);
   if (options.check) {
     return;
   }
@@ -1896,7 +1729,7 @@ async function upgradeCommand(options) {
   if (exitCode === 0) {
     log.blank();
     log.success("Upgrade complete.");
-    log.info(`Run ${pc6.cyan("grtl --version")} to verify the installed version.`);
+    log.info(`Run ${pc5.cyan("grtl --version")} to verify the installed version.`);
     return;
   }
   log.blank();
@@ -1907,11 +1740,11 @@ async function upgradeCommand(options) {
 
 // src/index.ts
 var brand = {
-  primary: pc7.green,
-  dim: pc7.dim
+  primary: pc6.green,
+  dim: pc6.dim
 };
-var program = new Command2();
-program.name("grtl").description("GenRTL CLI - Search RTL engineering knowledge and configure GenRTL").version(VERSION).option("--base-url <url>").hook("preAction", (thisCommand) => {
+var program = new Command();
+program.name("grtl").description("GenRTL CLI - Configure GenRTL and install reusable RTL CBBs").version(VERSION).option("--base-url <url>").hook("preAction", (thisCommand) => {
   const opts = thisCommand.opts();
   if (opts.baseUrl) {
     setBaseUrl(opts.baseUrl);
@@ -1926,35 +1759,25 @@ program.name("grtl").description("GenRTL CLI - Search RTL engineering knowledge
   "after",
   `
 Examples:
-  ${brand.dim("# Configure GenRTL for your coding agent")}
-  ${brand.primary("npx @genrtl/grtl setup --cli --codex --project")}
+  ${brand.dim("# Configure GenRTL MCP for your coding agent")}
   ${brand.primary("GRTL_API_KEY=your_key npx @genrtl/grtl setup --mcp --codex --project")}
 
-  ${brand.dim("# Search the same six knowledge 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 compile-search "Explain this Vivado CDC warning"')}
-  ${brand.primary('npx @genrtl/grtl debug-search "Fix this RTL bug from bad code and error message"')}
-
   ${brand.dim("# Acquire and install a reusable RTL CBB")}
   ${brand.primary("npx @genrtl/grtl cbb install cbb_uart@1.2.0")}
 `
 );
 registerSetupCommand(program);
-registerKnowledgeCommands(program);
 registerCbbCommands(program);
 registerUpgradeCommand(program);
 program.action(() => {
   console.log("");
   const banner = figlet.textSync("GenRTL", { font: "ANSI Shadow" });
   console.log(brand.primary(banner));
-  console.log(brand.dim("  RTL engineering knowledge for AI coding agents"));
+  console.log(brand.dim("  Configure GenRTL MCP and install reusable RTL CBBs"));
   console.log("");
   console.log("  Quick start:");
-  console.log(`    ${brand.primary("npx @genrtl/grtl setup")}`);
-  console.log(`    ${brand.primary('npx @genrtl/grtl knowledge-search "your RTL question"')}`);
+  console.log(`    ${brand.primary("npx @genrtl/grtl setup --mcp")}`);
+  console.log(`    ${brand.primary("npx @genrtl/grtl cbb install cbb_uart@1.2.0")}`);
   console.log("");
   console.log(`  Run ${brand.primary("npx @genrtl/grtl --help")} for all commands and options`);
   console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genrtl/grtl",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "description": "CLI, MCP, and coding-agent Skills for GenRTL RTL engineering knowledge",
   "type": "module",
   "bin": {