archbyte 0.2.3 → 0.2.6

package/README.md

@@ -6,21 +6,49 @@ AI-powered architecture visualization for your codebase. Analyzes code, generate
 
 ```bash
 # Install
-npm install -g archbyte
-# or from source
-git clone https://github.com/diabhey/archbyte.git && cd archbyte && npm install && npm run build && npm link
+curl -fsSL https://archbyte.heartbyte.io/install.sh | bash
+
+# Sign in or create a free account
+archbyte login
+
+# Configure your AI provider (BYOK)
+archbyte init
+
+# Or, if you use Claude Code / Codex — skip BYOK entirely:
+archbyte mcp install
 ```
 
+Your API keys stay on your machine. ArchByte never stores or transmits your provider credentials.
+
 ### Setup with Claude Code
 
-Slash commands are installed globally so they work in any project:
+**Option A: MCP (recommended)** — use ArchByte tools directly in Claude Code, no API key needed:
+
+```bash
+archbyte mcp install
+# or manually:
+claude mcp add archbyte --transport stdio -- npx -y archbyte@latest mcp
+```
+
+Then just ask Claude Code in plain English:
+
+```
+"Analyze the architecture of this project"
+"Export the architecture as a Mermaid diagram"
+"Show me the architecture stats"
+"Read the current architecture diagram"
+```
+
+Available MCP tools: `archbyte_analyze`, `archbyte_generate`, `archbyte_validate` (Pro), `archbyte_export`, `archbyte_stats`, `archbyte_diff`, `archbyte_read_diagram`.
+
+**Option B: Slash commands** — installed globally so they work in any project:
 
 ```bash
 mkdir -p ~/.claude/commands
 cp commands/archbyte-*.md ~/.claude/commands/
 ```
 
-Run `/archbyte-help` in Claude Code to see all commands. Every command shows its flags and examples when run without arguments (e.g. `/archbyte-export -h`).
+Run `/archbyte-help` in Claude Code to see all commands.
 
 ## Usage (Claude Code slash commands)
 

package/bin/archbyte.js

@@ -47,7 +47,7 @@ program
 
 program
   .command('login')
-  .description('Sign in to ArchByte (required for scan/analyze/generate)')
+  .description('Sign in or create a free account (required for scan/analyze/generate)')
   .option('--token <jwt>', 'Login with a pre-existing JWT token')
   .option('--github', 'Sign in with GitHub')
   .option('--google', 'Sign in with Google')
@@ -236,6 +236,24 @@ program
     await handleUpdate();
   });
 
+// — MCP server —
+
+const mcpCmd = program
+  .command('mcp')
+  .description('Start MCP server for AI coding tools (Claude Code, Codex)')
+  .action(async () => {
+    const { startMcpServer } = await import('../dist/cli/mcp-server.js');
+    await startMcpServer();
+  });
+
+mcpCmd
+  .command('install')
+  .description('Auto-configure Claude Code and/or Codex CLI')
+  .action(async () => {
+    const { handleMcpInstall } = await import('../dist/cli/mcp.js');
+    await handleMcpInstall();
+  });
+
 // Default: show help
 program
   .action(() => {

package/dist/cli/analyze.js

@@ -27,7 +27,7 @@ export async function handleAnalyze(options) {
         const diagramPath = path.join(rootDir, ".archbyte", "architecture.json");
         const diagramExists = fs.existsSync(diagramPath);
         const outputPath = options.output ?? ".archbyte/analysis.json";
-        console.log(chalk.bold("ArchByte Analyze — Dry Run"));
+        console.log(chalk.bold("ArchByte Analyze: Dry Run"));
         console.log(chalk.gray(`  Project:   ${path.basename(rootDir)}`));
         console.log(chalk.gray(`  Mode:      ${mode}`));
         console.log(chalk.gray(`  Provider:  ${provider}`));
@@ -123,7 +123,7 @@ export async function handleAnalyze(options) {
         }
         const { affected, unmapped } = mapFilesToComponents(changedFiles, priorSpec);
         if (!shouldRunAgents(affected, unmapped)) {
-            console.log(chalk.green("Only config changes detected — no re-scan needed. Use --force to re-scan."));
+            console.log(chalk.green("Only config changes detected. No re-scan needed. Use --force to re-scan."));
             console.log();
             return;
         }
@@ -319,8 +319,9 @@ function printSummary(analysis, durationMs, mode) {
     console.log();
     console.log(chalk.bold("Next steps:"));
     console.log(chalk.gray(`  ${chalk.cyan("archbyte serve")}    -- view the architecture diagram`));
-    console.log(chalk.gray(`  ${chalk.cyan("archbyte validate")} -- check architecture fitness rules`));
     console.log(chalk.gray(`  ${chalk.cyan("archbyte export")}   -- export to mermaid, plantuml, etc.`));
+    console.log(chalk.gray(`  ${chalk.cyan("archbyte validate")} -- check architecture fitness rules ${chalk.yellow("[Pro]")}`));
+    console.log(chalk.gray(`  ${chalk.cyan("archbyte patrol")}   -- continuous architecture monitoring ${chalk.yellow("[Pro]")}`));
     console.log();
 }
 // ─── Analysis converters ───

package/dist/cli/auth.js

@@ -7,6 +7,7 @@ import { CONFIG_DIR, CREDENTIALS_PATH, API_BASE, CLI_CALLBACK_PORT, OAUTH_TIMEOU
 export async function handleLogin(provider) {
     console.log();
     console.log(chalk.bold.cyan("ArchByte Login"));
+    console.log(chalk.gray("Sign in or create a free account to get started."));
     console.log();
     const existing = loadCredentials();
     if (existing && !isExpired(existing)) {
@@ -33,7 +34,8 @@ export async function handleLogin(provider) {
         return;
     }
     const selectedProvider = provider ?? "github";
-    console.log(chalk.gray(`Opening browser for ${selectedProvider} authentication...`));
+    console.log(chalk.gray(`Opening browser for ${selectedProvider} sign-in...`));
+    console.log(chalk.gray("Don't have an account? One will be created automatically."));
     console.log();
     try {
         const credentials = await startOAuthFlow(selectedProvider);
@@ -43,6 +45,9 @@ export async function handleLogin(provider) {
         console.log();
         console.log(chalk.green(`Logged in as ${chalk.bold(credentials.email)} (${credentials.tier} tier)`));
         console.log(chalk.gray(`Credentials saved to ${CREDENTIALS_PATH}`));
+        console.log();
+        console.log(chalk.gray("Your credentials and API keys are stored locally on your machine."));
+        console.log(chalk.gray("ArchByte never transmits or stores your model provider keys."));
     }
     catch (err) {
         console.error(chalk.red(`Login failed: ${err instanceof Error ? err.message : "Unknown error"}`));

package/dist/cli/config.js

@@ -30,10 +30,10 @@ export async function handleConfig(options) {
         return;
     }
     console.error(chalk.red(`Unknown action: ${action}`));
-    console.error(chalk.gray("  archbyte config show       — show current config"));
-    console.error(chalk.gray("  archbyte config set <k> <v> — set a config value"));
-    console.error(chalk.gray("  archbyte config get <k>     — get a config value"));
-    console.error(chalk.gray("  archbyte config path        — show config file path"));
+    console.error(chalk.gray("  archbyte config show          show current config"));
+    console.error(chalk.gray("  archbyte config set <k> <v>   set a config value"));
+    console.error(chalk.gray("  archbyte config get <k>       get a config value"));
+    console.error(chalk.gray("  archbyte config path          show config file path"));
     process.exit(1);
 }
 function loadConfig() {
@@ -105,7 +105,7 @@ function setConfig(key, value) {
                 console.log(chalk.green(`Switched to ${value} (credentials on file)`));
             }
             else {
-                console.log(chalk.yellow(`Switched to ${value} — run archbyte init to configure API key`));
+                console.log(chalk.yellow(`Switched to ${value}. Run archbyte init to configure API key.`));
             }
             break;
         }

package/dist/cli/diff.js

@@ -17,7 +17,7 @@ export async function handleDiff(options) {
     const currentArch = loadArchitectureFile(currentPath);
     const projectName = process.cwd().split("/").pop() || "project";
     console.log();
-    console.log(chalk.bold.cyan(`⚡ ArchByte Diff — ${projectName}`));
+    console.log(chalk.bold.cyan(`⚡ ArchByte Diff: ${projectName}`));
     console.log(chalk.gray(`  Baseline: ${options.baseline}`));
     console.log(chalk.gray(`  Current:  ${options.current || ".archbyte/architecture.json"}`));
     console.log();

package/dist/cli/export.js

@@ -104,7 +104,7 @@ function exportMarkdown(arch) {
     const realNodes = arch.nodes;
     const projectName = process.cwd().split("/").pop() || "project";
     const lines = [];
-    lines.push(`# Architecture — ${projectName}`);
+    lines.push(`# Architecture: ${projectName}`);
     lines.push("");
     lines.push(`> Generated by ArchByte on ${new Date().toISOString().slice(0, 10)}`);
     lines.push("");
@@ -127,7 +127,7 @@ function exportMarkdown(arch) {
     for (const node of realNodes) {
         const tech = node.techStack && node.techStack.length > 0
             ? node.techStack.join(", ")
-            : "—";
+            : "-";
         lines.push(`| ${node.label} | ${node.type} | ${node.layer} | ${tech} |`);
     }
     lines.push("");
@@ -145,7 +145,7 @@ function exportMarkdown(arch) {
         for (const edge of arch.edges) {
             const src = nodeMap.get(edge.source)?.label || edge.source;
             const tgt = nodeMap.get(edge.target)?.label || edge.target;
-            const label = edge.label ? ` — ${edge.label}` : "";
+            const label = edge.label ? `: ${edge.label}` : "";
             lines.push(`- **${src}** → **${tgt}**${label}`);
         }
     }

package/dist/cli/license-gate.js

@@ -22,10 +22,10 @@ export async function requireLicense(action) {
         console.error();
         console.error(chalk.red("Authentication required."));
         console.error();
-        console.error(chalk.gray("Sign in to use ArchByte:"));
+        console.error(chalk.gray("Sign in or create a free account:"));
         console.error(chalk.gray("  archbyte login"));
         console.error();
-        console.error(chalk.gray("Basic tier includes unlimited scans."));
+        console.error(chalk.gray("Free tier includes unlimited scans. No credit card required."));
         process.exit(1);
     }
     // Token expired locally

package/dist/cli/mcp-server.d.ts

@@ -0,0 +1 @@
+export declare function startMcpServer(): Promise<void>;

package/dist/cli/mcp-server.js

@@ -0,0 +1,443 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { loadCredentials, getVerifiedTier, cacheVerifiedTier, resetOfflineActions, checkOfflineAction, } from "./auth.js";
+import { API_BASE, NETWORK_TIMEOUT_MS } from "./constants.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// At runtime, __dirname = dist/cli/ — project root is two levels up
+const PROJECT_ROOT = path.resolve(__dirname, "..", "..");
+const BIN_PATH = path.join(PROJECT_ROOT, "bin", "archbyte.js");
+// Read version from package.json
+function getVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(PROJECT_ROOT, "package.json"), "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+// ─── ANSI strip ───
+const ANSI_RE = /\x1B\[[0-9;]*[A-Za-z]/g;
+function stripAnsi(s) {
+    return s.replace(ANSI_RE, "");
+}
+// ─── Auth check ───
+function checkAuth() {
+    const creds = loadCredentials();
+    if (!creds) {
+        return {
+            ok: false,
+            error: "Not logged in. Run `archbyte login` to sign in.",
+        };
+    }
+    if (new Date(creds.expiresAt) < new Date()) {
+        return {
+            ok: false,
+            error: "Session expired. Run `archbyte login` to refresh.",
+        };
+    }
+    return { ok: true };
+}
+// ─── License check ───
+async function checkLicense(action) {
+    const creds = loadCredentials();
+    if (!creds) {
+        return {
+            allowed: false,
+            reason: "Not logged in. Run `archbyte login` to sign in.",
+        };
+    }
+    try {
+        const res = await fetch(`${API_BASE}/api/v1/check-usage`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ action }),
+            signal: AbortSignal.timeout(NETWORK_TIMEOUT_MS),
+        });
+        if (res.status === 401) {
+            return {
+                allowed: false,
+                reason: "Session invalid. Run `archbyte login` again.",
+            };
+        }
+        if (!res.ok) {
+            return handleOffline();
+        }
+        const data = (await res.json());
+        const tier = data.tier === "premium" ? "premium" : "free";
+        cacheVerifiedTier(tier, creds.email);
+        resetOfflineActions();
+        if (!data.allowed) {
+            return {
+                allowed: false,
+                reason: data.message ?? "Scan not allowed. Check your account status.",
+            };
+        }
+        return { allowed: true };
+    }
+    catch {
+        return handleOffline();
+    }
+}
+function handleOffline() {
+    const { allowed, reason } = checkOfflineAction();
+    if (!allowed) {
+        return {
+            allowed: false,
+            reason: reason ??
+                "License server unreachable and offline actions not permitted.",
+        };
+    }
+    return { allowed: true };
+}
+function runArchbyte(args, cwd, timeoutMs = 300_000) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [BIN_PATH, ...args], {
+            cwd,
+            env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: timeoutMs,
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+        child.on("close", (code) => {
+            resolve({
+                stdout: stripAnsi(Buffer.concat(stdoutChunks).toString("utf-8")),
+                stderr: stripAnsi(Buffer.concat(stderrChunks).toString("utf-8")),
+                exitCode: code ?? 1,
+            });
+        });
+        child.on("error", (err) => {
+            resolve({
+                stdout: "",
+                stderr: `Failed to spawn archbyte: ${err.message}`,
+                exitCode: 1,
+            });
+        });
+    });
+}
+// ─── Result helpers ───
+function errorResult(msg) {
+    return { content: [{ type: "text", text: msg }], isError: true };
+}
+function textResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}
+function defineTools() {
+    return [
+        {
+            tool: {
+                name: "archbyte_analyze",
+                description: "Run AI-powered architecture analysis on a codebase. Scans source code and produces a structured analysis of components, services, connections, and data flows. Requires a configured model provider (archbyte init) unless --static is used.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                        static: {
+                            type: "boolean",
+                            description: "Static-only analysis. No model needed, free.",
+                        },
+                        provider: {
+                            type: "string",
+                            description: "Model provider: anthropic, openai, google",
+                        },
+                        apiKey: {
+                            type: "string",
+                            description: "Model API key (overrides config)",
+                        },
+                        force: {
+                            type: "boolean",
+                            description: "Force full re-scan (skip incremental detection)",
+                        },
+                    },
+                },
+            },
+            minTier: "free",
+            licenseAction: "analyze",
+            handler: async (params) => {
+                const args = ["analyze"];
+                const cwd = params.dir ?? process.cwd();
+                if (params.dir)
+                    args.push("--dir", params.dir);
+                if (params.static)
+                    args.push("--static");
+                if (params.provider)
+                    args.push("--provider", params.provider);
+                if (params.apiKey)
+                    args.push("--api-key", params.apiKey);
+                if (params.force)
+                    args.push("--force");
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "Analysis complete.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_generate",
+                description: "Generate an interactive architecture diagram from analysis output. Reads analysis.json and produces architecture.json for the visualization UI.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        input: {
+                            type: "string",
+                            description: "Input analysis path (default: .archbyte/analysis.json)",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                },
+            },
+            minTier: "free",
+            licenseAction: "generate",
+            handler: async (params) => {
+                const args = ["generate"];
+                const cwd = params.dir ?? process.cwd();
+                if (params.input)
+                    args.push("--input", params.input);
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "Diagram generated.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_validate",
+                description: "Run architecture fitness function rules against the current diagram. Returns structured JSON results with pass/fail status for each rule. Useful for CI/CD pipelines and automated quality checks.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        diagram: {
+                            type: "string",
+                            description: "Path to architecture JSON (default: .archbyte/architecture.json)",
+                        },
+                        config: {
+                            type: "string",
+                            description: "Path to archbyte.yaml config",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                },
+            },
+            minTier: "premium",
+            licenseAction: "analyze",
+            handler: async (params) => {
+                const args = ["validate", "--ci"];
+                const cwd = params.dir ?? process.cwd();
+                if (params.diagram)
+                    args.push("--diagram", params.diagram);
+                if (params.config)
+                    args.push("--config", params.config);
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "Validation complete.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_export",
+                description: "Export architecture diagram to various formats: mermaid, markdown, json, plantuml, or dot. Returns the exported content as text.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        format: {
+                            type: "string",
+                            enum: ["mermaid", "markdown", "json", "plantuml", "dot"],
+                            description: "Output format (default: mermaid)",
+                        },
+                        diagram: {
+                            type: "string",
+                            description: "Path to architecture JSON (default: .archbyte/architecture.json)",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                },
+            },
+            minTier: "free",
+            licenseAction: null,
+            handler: async (params) => {
+                const args = ["export"];
+                const cwd = params.dir ?? process.cwd();
+                if (params.format)
+                    args.push("--format", params.format);
+                if (params.diagram)
+                    args.push("--diagram", params.diagram);
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "Export complete.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_stats",
+                description: "Show architecture health dashboard with metrics: node count, edge count, complexity scores, and component breakdown.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        diagram: {
+                            type: "string",
+                            description: "Path to architecture JSON (default: .archbyte/architecture.json)",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                },
+            },
+            minTier: "free",
+            licenseAction: null,
+            handler: async (params) => {
+                const args = ["stats"];
+                const cwd = params.dir ?? process.cwd();
+                if (params.diagram)
+                    args.push("--diagram", params.diagram);
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "No stats available.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_diff",
+                description: "Compare two architecture snapshots to detect drift. Shows added, removed, and modified nodes and edges between a baseline and current diagram.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        baseline: {
+                            type: "string",
+                            description: "Path to baseline architecture JSON",
+                        },
+                        current: {
+                            type: "string",
+                            description: "Path to current architecture JSON (default: .archbyte/architecture.json)",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                    required: ["baseline"],
+                },
+            },
+            minTier: "free",
+            licenseAction: null,
+            handler: async (params) => {
+                const args = ["diff", "--baseline", params.baseline];
+                const cwd = params.dir ?? process.cwd();
+                if (params.current)
+                    args.push("--current", params.current);
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "No differences found.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_read_diagram",
+                description: "Read the current architecture diagram JSON. Returns the full architecture.json content including all nodes, edges, and metadata. Useful for understanding the project structure without re-running analysis.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        diagram: {
+                            type: "string",
+                            description: "Path to architecture JSON (default: .archbyte/architecture.json)",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                },
+            },
+            minTier: "free",
+            licenseAction: null,
+            handler: async (params) => {
+                const cwd = params.dir ?? process.cwd();
+                const diagramPath = params.diagram ??
+                    path.join(cwd, ".archbyte", "architecture.json");
+                const resolved = path.isAbsolute(diagramPath)
+                    ? diagramPath
+                    : path.join(cwd, diagramPath);
+                try {
+                    const content = fs.readFileSync(resolved, "utf-8");
+                    return textResult(content);
+                }
+                catch {
+                    return errorResult(`Diagram not found at ${resolved}. Run \`archbyte analyze\` then \`archbyte generate\` first.`);
+                }
+            },
+        },
+    ];
+}
+// ─── Tier comparison ───
+const TIER_RANK = { free: 0, premium: 1 };
+function tierSatisfies(userTier, required) {
+    return TIER_RANK[userTier] >= TIER_RANK[required];
+}
+// ─── Start MCP server ───
+export async function startMcpServer() {
+    const allTools = defineTools();
+    const toolMap = new Map(allTools.map((t) => [t.tool.name, t]));
+    const server = new Server({ name: "archbyte", version: getVersion() }, { capabilities: { tools: { listChanged: true } } });
+    // ─── tools/list — filtered by user tier ───
+    // Always show free-tier tools (even when not logged in) so the AI agent
+    // can attempt to call them and receive the "please login" error message.
+    // Premium tools are only shown to premium users.
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const auth = checkAuth();
+        const userTier = auth.ok ? getVerifiedTier() : "free";
+        const visible = allTools
+            .filter((t) => tierSatisfies(userTier, t.minTier))
+            .map((t) => t.tool);
+        return { tools: visible };
+    });
+    // ─── tools/call — auth + license + execute ───
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const def = toolMap.get(name);
+        if (!def) {
+            return errorResult(`Unknown tool: ${name}`);
+        }
+        // Auth check
+        const auth = checkAuth();
+        if (!auth.ok)
+            return errorResult(auth.error);
+        // Tier check (defense in depth — tool might not be in list but called directly)
+        const userTier = getVerifiedTier();
+        if (!tierSatisfies(userTier, def.minTier)) {
+            return errorResult(`${name} requires a Pro subscription. Upgrade at https://archbyte.heartbyte.io`);
+        }
+        // License check for gated tools
+        if (def.licenseAction) {
+            const license = await checkLicense(def.licenseAction);
+            if (!license.allowed)
+                return errorResult(license.reason);
+        }
+        return def.handler(args ?? {});
+    });
+    // ─── Connect transport ───
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/cli/mcp.d.ts

@@ -0,0 +1 @@
+export declare function handleMcpInstall(): Promise<void>;

package/dist/cli/mcp.js

@@ -0,0 +1,102 @@
+import { execSync, spawnSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+function isInPath(cmd) {
+    try {
+        execSync(`which ${cmd}`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function handleMcpInstall() {
+    console.log();
+    console.log(chalk.bold.cyan("ArchByte MCP Setup"));
+    console.log();
+    let configured = false;
+    // ─── Claude Code ───
+    if (isInPath("claude")) {
+        console.log(chalk.white("Detected Claude Code."));
+        const result = spawnSync("claude", ["mcp", "add", "archbyte", "--transport", "stdio", "--", "npx", "-y", "archbyte@latest", "mcp"], { stdio: "inherit" });
+        if (result.status === 0) {
+            console.log(chalk.green("  Configured Claude Code MCP server."));
+            configured = true;
+        }
+        else {
+            console.log(chalk.yellow("  Failed to configure Claude Code. See error above."));
+        }
+        console.log();
+    }
+    // ─── Codex CLI ───
+    const codexDir = path.join(process.env.HOME ?? process.env.USERPROFILE ?? ".", ".codex");
+    const codexConfig = path.join(codexDir, "config.toml");
+    if (fs.existsSync(codexDir)) {
+        console.log(chalk.white("Detected Codex CLI."));
+        let existing = "";
+        try {
+            existing = fs.readFileSync(codexConfig, "utf-8");
+        }
+        catch {
+            // File doesn't exist yet — we'll create it
+        }
+        if (existing.includes("[mcp_servers.archbyte]")) {
+            console.log(chalk.gray("  Codex already configured for archbyte."));
+            configured = true;
+        }
+        else {
+            const block = `
+[mcp_servers.archbyte]
+type = "stdio"
+command = "npx"
+args = ["-y", "archbyte@latest", "mcp"]
+`;
+            fs.appendFileSync(codexConfig, block, "utf-8");
+            console.log(chalk.green("  Configured Codex CLI MCP server."));
+            configured = true;
+        }
+        console.log();
+    }
+    // ─── Fallback instructions ───
+    if (!configured) {
+        console.log(chalk.yellow("No supported AI coding tool detected."));
+        console.log();
+    }
+    // ─── Usage examples ───
+    if (configured) {
+        console.log(chalk.bold("What to do next:"));
+        console.log();
+        console.log(chalk.white("  Open your AI coding tool and ask it to use ArchByte. For example:"));
+        console.log();
+        console.log(chalk.cyan('    "Analyze the architecture of this project"'));
+        console.log(chalk.cyan('    "Export the architecture as a Mermaid diagram"'));
+        console.log(chalk.cyan('    "Show me the architecture stats"'));
+        console.log(chalk.cyan('    "Read the current architecture diagram"'));
+        console.log();
+        console.log(chalk.gray("  Your AI tool will call ArchByte tools automatically via MCP."));
+        console.log(chalk.gray("  No commands to memorize. Just describe what you need."));
+        console.log();
+    }
+    console.log(chalk.bold("Manual setup:"));
+    console.log();
+    console.log(chalk.white("  Claude Code:"));
+    console.log(chalk.gray("    claude mcp add archbyte --transport stdio -- npx -y archbyte@latest mcp"));
+    console.log();
+    console.log(chalk.white("  Codex CLI:"));
+    console.log(chalk.gray("    Add to ~/.codex/config.toml:"));
+    console.log(chalk.gray('    [mcp_servers.archbyte]'));
+    console.log(chalk.gray('    type = "stdio"'));
+    console.log(chalk.gray('    command = "npx"'));
+    console.log(chalk.gray('    args = ["-y", "archbyte@latest", "mcp"]'));
+    console.log();
+    console.log(chalk.bold("  Available MCP tools:"));
+    console.log(chalk.gray("    archbyte_analyze        Scan codebase with AI agents"));
+    console.log(chalk.gray("    archbyte_generate       Generate diagram from analysis"));
+    console.log(chalk.gray("    archbyte_validate       Run fitness rules (Pro)"));
+    console.log(chalk.gray("    archbyte_export         Export to Mermaid, PlantUML, DOT, etc."));
+    console.log(chalk.gray("    archbyte_stats          Architecture health metrics"));
+    console.log(chalk.gray("    archbyte_diff           Compare snapshots, detect drift"));
+    console.log(chalk.gray("    archbyte_read_diagram   Read current architecture JSON"));
+    console.log();
+}

package/dist/cli/patrol.js

@@ -106,7 +106,7 @@ function printPatrolResult(record, cycleNum) {
     const time = new Date(record.timestamp).toLocaleTimeString();
     const status = record.passed ? chalk.green("HEALTHY") : chalk.red("VIOLATION");
     console.log();
-    console.log(chalk.bold.cyan(`  Patrol #${cycleNum} — ${time} — ${status}`));
+    console.log(chalk.bold.cyan(`  Patrol #${cycleNum} | ${time} | ${status}`));
     if (record.newViolations.length > 0) {
         console.log(chalk.red(`  ${record.newViolations.length} new violation(s):`));
         for (const v of record.newViolations) {
@@ -121,7 +121,7 @@ function printPatrolResult(record, cycleNum) {
         }
     }
     if (record.newViolations.length === 0 && record.resolvedViolations.length === 0) {
-        console.log(chalk.gray(`  No changes — ${record.errors} errors, ${record.warnings} warnings`));
+        console.log(chalk.gray(`  No changes. ${record.errors} errors, ${record.warnings} warnings`));
     }
 }
 function printHistory(patrolDir) {
@@ -137,7 +137,7 @@ function printHistory(patrolDir) {
     }
     const projectName = process.cwd().split("/").pop() || "project";
     console.log();
-    console.log(chalk.bold.cyan(`  ArchByte Patrol History — ${projectName}`));
+    console.log(chalk.bold.cyan(`  ArchByte Patrol History: ${projectName}`));
     console.log();
     // Show last 20 records (skip malformed lines)
     const records = lines.slice(-20).flatMap((l) => {
@@ -208,7 +208,7 @@ export async function handlePatrol(options) {
     const intervalStr = options.interval || "5m";
     const action = options.onViolation || "log";
     console.log();
-    console.log(chalk.bold.cyan(`  ArchByte Patrol — ${projectName}`));
+    console.log(chalk.bold.cyan(`  ArchByte Patrol: ${projectName}`));
     console.log(chalk.gray(`  Interval: ${intervalStr} | On violation: ${action}`));
     console.log(chalk.gray(`  History: ${path.join(PATROL_DIR, HISTORY_FILE)}`));
     console.log(chalk.gray("  Press Ctrl+C to stop."));

package/dist/cli/setup.js

@@ -1,6 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
+import { execSync } from "child_process";
 import chalk from "chalk";
 import { resolveModel } from "../agents/runtime/types.js";
 import { createProvider } from "../agents/providers/router.js";
@@ -111,10 +112,48 @@ async function validateProviderSilent(providerName, apiKey) {
 function getProfiles(config) {
     return config.profiles ?? {};
 }
+function isInPath(cmd) {
+    try {
+        execSync(`which ${cmd}`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function handleSetup() {
     console.log();
     console.log(chalk.bold.cyan("ArchByte Setup"));
     console.log(chalk.gray("Configure your model provider and API key.\n"));
+    // Detect AI coding tools — suggest MCP instead of BYOK
+    const hasClaude = isInPath("claude");
+    const codexDir = path.join(process.env.HOME ?? process.env.USERPROFILE ?? ".", ".codex");
+    const hasCodex = fs.existsSync(codexDir);
+    if (hasClaude || hasCodex) {
+        const tools = [hasClaude && "Claude Code", hasCodex && "Codex CLI"].filter(Boolean).join(" and ");
+        console.log(chalk.cyan(`  Detected ${tools} on this machine.`));
+        console.log(chalk.white(`  You can use ArchByte directly through MCP. No API key needed.`));
+        console.log(chalk.white(`  Your AI tool already provides the model, so you skip the BYOK step.`));
+        console.log();
+        console.log(chalk.white(`  Run: `) + chalk.bold.cyan(`archbyte mcp install`));
+        console.log();
+        const continueIdx = await select("Continue with BYOK setup anyway?", [
+            `Skip ${chalk.gray("(use MCP instead, recommended)")}`,
+            `Continue ${chalk.gray("(set up your own API key)")}`,
+        ]);
+        if (continueIdx === 0) {
+            console.log();
+            console.log(chalk.gray("  Run `archbyte mcp install` to configure MCP for your AI tool."));
+            console.log();
+            console.log(chalk.gray("  Then open your AI tool and try:"));
+            console.log(chalk.cyan('    "Analyze the architecture of this project"'));
+            console.log(chalk.cyan('    "Export the architecture as a Mermaid diagram"'));
+            console.log(chalk.cyan('    "Show me the architecture stats"'));
+            console.log();
+            return;
+        }
+        console.log();
+    }
     const config = loadConfig();
     const profiles = getProfiles(config);
     // Migrate legacy flat config → profiles
@@ -151,7 +190,7 @@ export async function handleSetup() {
     const idx = await select("Choose your model provider:", PROVIDERS.map((p) => {
         const active = config.provider === p.name ? chalk.green(" (active)") : "";
         const hasKey = profiles[p.name]?.apiKey ? chalk.cyan(" ✓ configured") : "";
-        return `${p.label} ${chalk.gray("— " + p.hint)}${hasKey}${active}`;
+        return `${p.label} ${chalk.gray(p.hint)}${hasKey}${active}`;
     }));
     const provider = PROVIDERS[idx].name;
     config.provider = provider;
@@ -163,7 +202,7 @@ export async function handleSetup() {
     if (existing?.apiKey) {
         console.log(chalk.gray(`\n  Existing key: ${maskKey(existing.apiKey)}`));
         const keepIdx = await select("  Update API key?", [
-            `Keep existing ${chalk.gray("— " + maskKey(existing.apiKey))}`,
+            `Keep existing ${chalk.gray("(" + maskKey(existing.apiKey) + ")")}`,
             "Enter new key",
         ]);
         if (keepIdx === 0) {
@@ -199,7 +238,7 @@ export async function handleSetup() {
         const currentModel = profiles[provider].model;
         const modelIdx = await select("\n  Choose a model:", models.map((m) => {
             const current = currentModel === m.id && m.id ? chalk.green(" (current)") : "";
-            return `${m.label} ${chalk.gray("— " + m.hint)}${current}`;
+            return `${m.label} ${chalk.gray(m.hint)}${current}`;
         }));
         const chosen = models[modelIdx];
         if (chosen.id) {
@@ -243,6 +282,8 @@ export async function handleSetup() {
     // Save config
     saveConfig(config);
     console.log(chalk.gray(`\n  Config saved to ${CONFIG_PATH}`));
+    console.log(chalk.gray("  Your API key is stored locally on this machine and never sent to ArchByte."));
+    console.log(chalk.gray("  All model calls go directly from your machine to your provider."));
     // Generate archbyte.yaml in .archbyte/ if it doesn't exist
     const projectDir = process.cwd();
     const archbyteDir = path.join(projectDir, ".archbyte");
@@ -271,6 +312,8 @@ export async function handleSetup() {
     else {
         console.log(chalk.gray(`  .archbyte/archbyte.yaml already exists`));
     }
+    // Generate README.md in .archbyte/
+    writeArchbyteReadme(archbyteDir);
     console.log();
     console.log(chalk.green("  Setup complete!"));
     console.log();
@@ -278,3 +321,39 @@ export async function handleSetup() {
     console.log(chalk.gray("        Run from your project root, or use ") + chalk.cyan("archbyte run -d /path/to/project"));
     console.log();
 }
+function writeArchbyteReadme(archbyteDir) {
+    const readmePath = path.join(archbyteDir, "README.md");
+    if (fs.existsSync(readmePath))
+        return;
+    const content = `# .archbyte
+
+This directory is managed by [ArchByte](https://diabhey.com) — your codebase's architecture intelligence layer.
+
+## Files
+
+| File | What it does |
+|------|-------------|
+| \`archbyte.yaml\` | Your architecture spec. Human-readable, human-editable. This is the source of truth. |
+| \`architecture.json\` | Generated diagram data. Fed directly to the interactive UI. |
+| \`analysis.json\` | Raw analysis output from the agent pipeline. Used by \`archbyte generate\`. |
+| \`metadata.json\` | Scan metadata — duration, mode, commit hash. Powers \`archbyte stats\` and \`archbyte diff\`. |
+| \`analysis-status.json\` | Status of the last scan (success/error). Used by the dev server for live updates. |
+| \`static-context.json\` | Cached static scanner output. Speeds up incremental re-scans. |
+
+## Workflow
+
+\`\`\`
+archbyte analyze  →  writes archbyte.yaml + analysis.json
+archbyte generate →  reads archbyte.yaml → writes architecture.json
+archbyte serve    →  reads architecture.json → opens interactive diagram
+\`\`\`
+
+You can edit \`archbyte.yaml\` by hand — your changes are preserved on re-scan.
+
+---
+
+Thanks for using ArchByte. Built with love by [diabhey](https://diabhey.com).
+`;
+    fs.writeFileSync(readmePath, content, "utf-8");
+    console.log(chalk.green(`  Created .archbyte/README.md`));
+}

package/dist/cli/stats.js

@@ -17,7 +17,7 @@ export async function handleStats(options) {
     // Auto-detect project name from cwd
     const projectName = process.cwd().split("/").pop() || "project";
     console.log();
-    console.log(chalk.bold.cyan(`⚡ ArchByte Stats — ${projectName}`));
+    console.log(chalk.bold.cyan(`⚡ ArchByte Stats: ${projectName}`));
     console.log();
     // ── Scan Info (from metadata.json, fallback to analysis.json) ──
     const metadataJsonPath = path.join(process.cwd(), ".archbyte", "metadata.json");

package/dist/cli/ui.js

@@ -89,8 +89,8 @@ export function select(prompt, options) {
                 cleanup();
                 resolve(selected);
             }
-            else if (data === "\x03") {
-                // Ctrl+C
+            else if (data === "\x03" || data === "q" || data === "Q") {
+                // Ctrl+C or q to quit
                 cleanup();
                 process.exit(0);
             }
@@ -173,7 +173,7 @@ export function confirm(prompt) {
                 process.stdout.write("n\n");
                 resolve(false);
             }
-            else if (data === "\x03") {
+            else if (data === "\x03" || data === "q" || data === "Q") {
                 process.stdout.write("\n");
                 process.exit(0);
             }

package/dist/cli/validate.js

@@ -225,7 +225,7 @@ export async function handleValidate(options) {
 function printValidationReport(result) {
     const projectName = process.cwd().split("/").pop() || "project";
     console.log();
-    console.log(chalk.bold.cyan(`⚡ ArchByte Validate — ${projectName}`));
+    console.log(chalk.bold.cyan(`⚡ ArchByte Validate: ${projectName}`));
     console.log();
     // Group violations by rule for display
     const ruleViolations = new Map();
@@ -248,7 +248,7 @@ function printValidationReport(result) {
     }
     console.log();
     const resultStr = result.errors > 0 ? chalk.red("FAIL") : chalk.green("PASS");
-    console.log(`  Result: ${result.warnings} warning${result.warnings !== 1 ? "s" : ""}, ${result.errors} error${result.errors !== 1 ? "s" : ""} — ${resultStr}`);
+    console.log(`  Result: ${result.warnings} warning${result.warnings !== 1 ? "s" : ""}, ${result.errors} error${result.errors !== 1 ? "s" : ""} ${resultStr}`);
     console.log();
 }
 function printRuleResult(rule, level, count, violations) {

package/dist/cli/workflow.js

@@ -349,7 +349,7 @@ async function runWorkflow(workflow) {
         // Check dependencies
         const unmetDeps = step.needs.filter((dep) => state.steps[dep]?.status !== "completed");
         if (unmetDeps.length > 0) {
-            console.log(chalk.yellow(`  [skip] ${step.name} — waiting on: ${unmetDeps.join(", ")}`));
+            console.log(chalk.yellow(`  [skip] ${step.name} (waiting on: ${unmetDeps.join(", ")})`));
             state.steps[step.id] = { status: "pending" };
             saveState(state);
             continue;
@@ -414,7 +414,7 @@ function listWorkflows() {
     const workflows = loadWorkflows();
     const projectName = process.cwd().split("/").pop() || "project";
     console.log();
-    console.log(chalk.bold.cyan(`  ArchByte Workflows — ${projectName}`));
+    console.log(chalk.bold.cyan(`  ArchByte Workflows: ${projectName}`));
     console.log();
     for (const w of workflows) {
         const state = loadState(w.id);
@@ -428,7 +428,7 @@ function listWorkflows() {
         const builtinTag = BUILTIN_WORKFLOWS.some((b) => b.id === w.id)
             ? chalk.gray(" (built-in)")
             : "";
-        console.log(`  ${chalk.bold(w.id)}${builtinTag} — ${statusStr}`);
+        console.log(`  ${chalk.bold(w.id)}${builtinTag} ${statusStr}`);
         console.log(chalk.gray(`    ${w.description}`));
         console.log(chalk.gray(`    Steps: ${w.steps.map((s) => s.id).join(" → ")}`));
         console.log();
@@ -464,7 +464,7 @@ function showWorkflow(id) {
         }
         else if (stepState?.status === "failed") {
             icon = chalk.red("FAIL");
-            statusLabel = chalk.red(` — ${stepState.error?.slice(0, 60)}`);
+            statusLabel = chalk.red(` ${stepState.error?.slice(0, 60)}`);
         }
         const depsStr = step.needs.length > 0
             ? chalk.gray(` [needs: ${step.needs.join(", ")}]`)
@@ -481,7 +481,7 @@ function showStatus() {
     const workflows = loadWorkflows();
     const projectName = process.cwd().split("/").pop() || "project";
     console.log();
-    console.log(chalk.bold.cyan(`  Workflow Status — ${projectName}`));
+    console.log(chalk.bold.cyan(`  Workflow Status: ${projectName}`));
     console.log();
     let anyActive = false;
     for (const w of workflows) {
@@ -499,7 +499,7 @@ function showStatus() {
             statusIcon = chalk.green("done");
         if (state.status === "failed")
             statusIcon = chalk.red("failed");
-        console.log(`  ${chalk.bold(w.id)} [${bar}] ${pct}% — ${statusIcon}`);
+        console.log(`  ${chalk.bold(w.id)} [${bar}] ${pct}% ${statusIcon}`);
         console.log(chalk.gray(`    ${completed}/${total} steps complete`));
         console.log();
     }
@@ -583,7 +583,7 @@ export async function handleWorkflow(options) {
         }
         const projectName = process.cwd().split("/").pop() || "project";
         console.log();
-        console.log(chalk.bold.cyan(`  ArchByte Workflow: ${workflow.name} — ${projectName}`));
+        console.log(chalk.bold.cyan(`  ArchByte Workflow: ${workflow.name} | ${projectName}`));
         console.log(chalk.gray(`  ${workflow.description}`));
         console.log(chalk.gray(`  Steps: ${workflow.steps.length}`));
         await runWorkflow(workflow);

package/dist/cli/yaml-io.js

@@ -36,7 +36,7 @@ export function writeSpec(rootDir, spec) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    const header = `# Generated by ArchByte — ${new Date().toISOString().split("T")[0]}\n# Human-editable. Changes are preserved on re-scan.\n\n`;
+    const header = `# Generated by ArchByte ${new Date().toISOString().split("T")[0]}\n# Human-editable. Changes are preserved on re-scan.\n\n`;
     const yamlStr = yaml.dump(spec, {
         indent: 2,
         lineWidth: 120,

package/dist/server/src/index.js

@@ -1384,4 +1384,16 @@ export async function startServer(cfg) {
     setupWatcher();
     console.error(`[archbyte] Serving ${config.name}`);
     console.error(`[archbyte] Diagram: ${config.diagramPath}`);
+    // Listen for 'q' keypress to quit gracefully
+    if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (key) => {
+            if (key === "q" || key === "Q" || key === "\x03") {
+                process.emit("SIGINT");
+            }
+        });
+        console.error(`[archbyte] Press q to quit`);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archbyte",
-  "version": "0.2.3",
+  "version": "0.2.6",
   "description": "ArchByte - See what agents build. As they build it.",
   "type": "module",
   "bin": {
@@ -37,11 +37,13 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.74.0",
     "@google/generative-ai": "^0.24.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.3.0",
     "chokidar": "^3.5.3",
     "commander": "^12.0.0",
     "js-yaml": "^4.1.1",
-    "openai": "^6.19.0"
+    "openai": "^6.19.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/ui/dist/index.html

@@ -4,7 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>ArchByte</title>
-  <link rel="icon" href="/favicon.ico">
+  <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32.png">
+  <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16.png">
   <script type="module" crossorigin src="/assets/index-BdfGbhpp.js"></script>
   <link rel="stylesheet" crossorigin href="/assets/index-0_XpUUZQ.css">
 </head>