@rafter-security/cli 0.6.3 → 0.6.5

package/dist/commands/agent/audit.js

@@ -39,9 +39,10 @@ export function createAuditCommand() {
         }
         console.log(`\nShowing ${entries.length} audit log entries:\n`);
         for (const entry of entries) {
-            const timestamp = new Date(entry.timestamp).toLocaleString();
-            const indicator = getEventIndicator(entry.eventType);
-            console.log(`${indicator} [${timestamp}] ${entry.eventType}`);
+            const timestamp = entry.timestamp ? new Date(entry.timestamp).toLocaleString() : "unknown";
+            const eventType = entry.eventType ?? "unknown";
+            const indicator = getEventIndicator(eventType);
+            console.log(`${indicator} [${timestamp}] ${eventType}`);
             if (entry.agentType) {
                 console.log(`   Agent: ${entry.agentType}`);
             }
@@ -92,8 +93,8 @@ export function generateShareExcerpt() {
     }
     else {
         for (const entry of entries) {
-            const ts = entry.timestamp.replace("T", " ").replace(/\.\d+Z$/, "Z");
-            const eventPad = entry.eventType.padEnd(20);
+            const ts = (entry.timestamp ?? "").replace("T", " ").replace(/\.\d+Z$/, "Z");
+            const eventPad = (entry.eventType ?? "unknown").padEnd(20);
             const riskRaw = entry.action?.riskLevel ?? "low";
             const riskPad = riskRaw.toUpperCase().padEnd(8);
             const detail = formatShareDetail(entry);
@@ -136,7 +137,7 @@ export function getRiskLevel(config) {
 export function formatShareDetail(entry) {
     const action = entry.resolution?.actionTaken ?? "unknown";
     const suffix = `[${action}]`;
-    if (entry.eventType === "secret_detected") {
+    if ((entry.eventType ?? "unknown") === "secret_detected") {
         const reason = entry.securityCheck?.reason ?? "";
         return `${reason} ${suffix}`;
     }

package/dist/commands/agent/init.js

@@ -5,7 +5,9 @@ import { SkillManager } from "../../utils/skill-manager.js";
 import fs from "fs";
 import path from "path";
 import os from "os";
+import { execSync } from "child_process";
 import { fileURLToPath } from "url";
+import { createRequire } from "module";
 import { fmt } from "../../utils/formatter.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -585,5 +587,23 @@ export function createInitCommand() {
         console.log("  - Run: rafter scan local . (test secret scanning)");
         console.log("  - Configure: rafter agent config show");
         console.log();
+        // Warn if a different rafter version shadows this one on PATH
+        try {
+            const _require = createRequire(import.meta.url);
+            const { version: thisVersion } = _require("../../../package.json");
+            const pathVersion = execSync("rafter --version", {
+                encoding: "utf-8",
+                timeout: 5000,
+                stdio: ["pipe", "pipe", "ignore"],
+            }).trim();
+            if (pathVersion && pathVersion !== thisVersion && !pathVersion.includes(thisVersion)) {
+                console.log(fmt.warning(`PATH version mismatch: 'rafter --version' reports ${pathVersion}, but this install is ${thisVersion}.`));
+                console.log(fmt.info("Another rafter binary may be shadowing this one. Check: which rafter"));
+                console.log();
+            }
+        }
+        catch {
+            // Ignore — rafter may not be on PATH yet
+        }
     });
 }

package/dist/commands/agent/status.js

@@ -34,13 +34,13 @@ export function createStatusCommand() {
         const localGitleaks = path.join(getBinDir(), "gitleaks");
         let gitleaksStatus = "not found — run: rafter agent init --with-gitleaks";
         try {
-            const ver = execSync("gitleaks version", { timeout: 5000, encoding: "utf-8" }).trim();
+            const ver = execSync("gitleaks version", { timeout: 5000, encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim();
             gitleaksStatus = `${ver} (PATH)`;
         }
         catch {
             if (fs.existsSync(localGitleaks)) {
                 try {
-                    const ver = execSync(`"${localGitleaks}" version`, { timeout: 5000, encoding: "utf-8" }).trim();
+                    const ver = execSync(`"${localGitleaks}" version`, { timeout: 5000, encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim();
                     gitleaksStatus = `${ver} (local)`;
                 }
                 catch {
@@ -164,7 +164,7 @@ export function createStatusCommand() {
                 for (const e of [...recent].reverse()) {
                     const ts = (e.timestamp ?? "").slice(0, 19).replace("T", " ");
                     const action = e.resolution?.actionTaken ?? "";
-                    console.log(`  ${ts}  ${e.eventType}  [${action}]`);
+                    console.log(`  ${ts}  ${e.eventType ?? "unknown"}  [${action}]`);
                 }
             }
         }

package/dist/commands/agent/verify.js

@@ -87,6 +87,75 @@ function checkCodex() {
     }
     return { name, passed: true, detail: `Skills installed (${path.join(homeDir, ".agents", "skills")})` };
 }
+function checkGemini() {
+    const name = "Gemini CLI";
+    const homeDir = os.homedir();
+    const geminiDir = path.join(homeDir, ".gemini");
+    if (!fs.existsSync(geminiDir)) {
+        return { name, passed: false, optional: true, detail: `Not detected — run 'rafter agent init --with-gemini' to enable` };
+    }
+    const settingsPath = path.join(geminiDir, "settings.json");
+    if (!fs.existsSync(settingsPath)) {
+        return { name, passed: false, optional: true, detail: `Settings file not found: ${settingsPath} — run 'rafter agent init --with-gemini'` };
+    }
+    try {
+        const settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+        const hasRafterMcp = settings?.mcpServers?.rafter != null;
+        if (!hasRafterMcp) {
+            return { name, passed: false, optional: true, detail: "Rafter MCP server not configured — run 'rafter agent init --with-gemini'" };
+        }
+        return { name, passed: true, detail: "MCP server configured" };
+    }
+    catch (e) {
+        return { name, passed: false, optional: true, detail: `Cannot read settings: ${e}` };
+    }
+}
+function checkCursor() {
+    const name = "Cursor";
+    const homeDir = os.homedir();
+    const cursorDir = path.join(homeDir, ".cursor");
+    if (!fs.existsSync(cursorDir)) {
+        return { name, passed: false, optional: true, detail: `Not detected — run 'rafter agent init --with-cursor' to enable` };
+    }
+    const mcpPath = path.join(cursorDir, "mcp.json");
+    if (!fs.existsSync(mcpPath)) {
+        return { name, passed: false, optional: true, detail: `MCP config not found: ${mcpPath} — run 'rafter agent init --with-cursor'` };
+    }
+    try {
+        const config = JSON.parse(fs.readFileSync(mcpPath, "utf-8"));
+        const hasRafterMcp = config?.mcpServers?.rafter != null;
+        if (!hasRafterMcp) {
+            return { name, passed: false, optional: true, detail: "Rafter MCP server not configured — run 'rafter agent init --with-cursor'" };
+        }
+        return { name, passed: true, detail: "MCP server configured" };
+    }
+    catch (e) {
+        return { name, passed: false, optional: true, detail: `Cannot read config: ${e}` };
+    }
+}
+function checkWindsurf() {
+    const name = "Windsurf";
+    const homeDir = os.homedir();
+    const windsurfDir = path.join(homeDir, ".codeium", "windsurf");
+    if (!fs.existsSync(windsurfDir)) {
+        return { name, passed: false, optional: true, detail: `Not detected — run 'rafter agent init --with-windsurf' to enable` };
+    }
+    const mcpPath = path.join(windsurfDir, "mcp_config.json");
+    if (!fs.existsSync(mcpPath)) {
+        return { name, passed: false, optional: true, detail: `MCP config not found: ${mcpPath} — run 'rafter agent init --with-windsurf'` };
+    }
+    try {
+        const config = JSON.parse(fs.readFileSync(mcpPath, "utf-8"));
+        const hasRafterMcp = config?.mcpServers?.rafter != null;
+        if (!hasRafterMcp) {
+            return { name, passed: false, optional: true, detail: "Rafter MCP server not configured — run 'rafter agent init --with-windsurf'" };
+        }
+        return { name, passed: true, detail: "MCP server configured" };
+    }
+    catch (e) {
+        return { name, passed: false, optional: true, detail: `Cannot read config: ${e}` };
+    }
+}
 export function createVerifyCommand() {
     return new Command("verify")
         .description("Check agent security integration status")
@@ -100,6 +169,9 @@ export function createVerifyCommand() {
             checkClaudeCode(),
             checkOpenClaw(),
             checkCodex(),
+            checkGemini(),
+            checkCursor(),
+            checkWindsurf(),
         ];
         for (const r of results) {
             if (r.passed) {

package/dist/commands/backend/run.js

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import axios from "axios";
 import ora from "ora";
 import { detectRepo } from "../../utils/git.js";
-import { API, resolveKey, EXIT_GENERAL_ERROR, EXIT_QUOTA_EXHAUSTED, EXIT_INSUFFICIENT_SCOPE, handleScopeError } from "../../utils/api.js";
+import { API, resolveKey, EXIT_GENERAL_ERROR, EXIT_QUOTA_EXHAUSTED, handle403 } from "../../utils/api.js";
 import { handleScanStatus } from "./scan-status.js";
 /**
  * Shared handler for the remote backend scan (used by both `rafter run` and `rafter scan` / `rafter scan remote`).
@@ -34,8 +34,9 @@ export async function runRemoteScan(opts) {
         }
         catch (e) {
             spinner.fail("Request failed");
-            if (handleScopeError(e)) {
-                process.exit(EXIT_INSUFFICIENT_SCOPE);
+            const forbiddenCode = handle403(e);
+            if (forbiddenCode >= 0) {
+                process.exit(forbiddenCode);
             }
             else if (e.response?.status === 429) {
                 console.error("Quota exhausted");
@@ -62,8 +63,9 @@ export async function runRemoteScan(opts) {
             process.exit(exitCode);
         }
         catch (e) {
-            if (handleScopeError(e)) {
-                process.exit(EXIT_INSUFFICIENT_SCOPE);
+            const forbiddenCode = handle403(e);
+            if (forbiddenCode >= 0) {
+                process.exit(forbiddenCode);
             }
             else if (e.response?.status === 429) {
                 process.exit(EXIT_QUOTA_EXHAUSTED);

package/dist/commands/brief.js

@@ -0,0 +1,489 @@
+import { Command } from "commander";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const RESOURCES_DIR = join(__dirname, "..", "..", "resources", "skills");
+function loadSkill(name) {
+    const raw = readFileSync(join(RESOURCES_DIR, name, "SKILL.md"), "utf-8");
+    // Strip YAML frontmatter
+    return raw.replace(/^---[\s\S]*?---\n*/, "").trim();
+}
+function extractSections(content, headings) {
+    const lines = content.split("\n");
+    const sections = [];
+    let capturing = false;
+    let captureLevel = 0;
+    let inCodeBlock = false;
+    for (const line of lines) {
+        if (line.trimStart().startsWith("```")) {
+            inCodeBlock = !inCodeBlock;
+            if (capturing)
+                sections.push(line);
+            continue;
+        }
+        if (inCodeBlock) {
+            if (capturing)
+                sections.push(line);
+            continue;
+        }
+        const headingMatch = line.match(/^(#{1,4})\s+(.*)/);
+        if (headingMatch) {
+            const level = headingMatch[1].length;
+            const title = headingMatch[2].trim();
+            if (headings.some((h) => title.toLowerCase().includes(h.toLowerCase()))) {
+                capturing = true;
+                captureLevel = level;
+                sections.push(line);
+                continue;
+            }
+            if (capturing && level <= captureLevel) {
+                capturing = false;
+            }
+        }
+        if (capturing) {
+            sections.push(line);
+        }
+    }
+    return sections.join("\n").trim();
+}
+function buildTopics() {
+    return {
+        security: {
+            description: "Local agent security — scanning, auditing, risk assessment",
+            render: () => loadSkill("rafter-agent-security"),
+        },
+        scanning: {
+            description: "Remote SAST/SCA code analysis via backend API",
+            render: () => loadSkill("rafter"),
+        },
+        commands: {
+            description: "Condensed command reference for all rafter commands",
+            render: () => {
+                const security = loadSkill("rafter-agent-security");
+                const backend = loadSkill("rafter");
+                const secCmds = extractSections(security, [
+                    "Commands",
+                    "/rafter-scan",
+                    "/rafter-bash",
+                    "/rafter-audit-skill",
+                    "/rafter-audit",
+                ]);
+                const backCmds = extractSections(backend, [
+                    "Core Commands",
+                    "Trigger",
+                    "Get Scan",
+                    "Check API",
+                ]);
+                return [
+                    "# Rafter Command Reference",
+                    "",
+                    "## Backend (Remote Code Analysis)",
+                    "",
+                    backCmds,
+                    "",
+                    "## Agent (Local Security)",
+                    "",
+                    secCmds,
+                ].join("\n");
+            },
+        },
+        setup: {
+            description: "Setup instructions for all supported agent platforms",
+            render: () => renderSetupGuide(),
+        },
+        "setup/claude-code": {
+            description: "Setup instructions for Claude Code",
+            render: () => renderPlatformSetup("claude-code"),
+        },
+        "setup/codex": {
+            description: "Setup instructions for Codex CLI",
+            render: () => renderPlatformSetup("codex"),
+        },
+        "setup/gemini": {
+            description: "Setup instructions for Gemini CLI",
+            render: () => renderPlatformSetup("gemini"),
+        },
+        "setup/cursor": {
+            description: "Setup instructions for Cursor",
+            render: () => renderPlatformSetup("cursor"),
+        },
+        "setup/windsurf": {
+            description: "Setup instructions for Windsurf",
+            render: () => renderPlatformSetup("windsurf"),
+        },
+        "setup/aider": {
+            description: "Setup instructions for Aider",
+            render: () => renderPlatformSetup("aider"),
+        },
+        "setup/openclaw": {
+            description: "Setup instructions for OpenClaw",
+            render: () => renderPlatformSetup("openclaw"),
+        },
+        "setup/continue": {
+            description: "Setup instructions for Continue.dev",
+            render: () => renderPlatformSetup("continue"),
+        },
+        "setup/generic": {
+            description: "Setup instructions for unsupported / generic agents",
+            render: () => renderPlatformSetup("generic"),
+        },
+        all: {
+            description: "Everything — full security + scanning + setup briefing",
+            render: () => {
+                const topics = buildTopics();
+                return [
+                    topics.scanning.render(),
+                    "",
+                    "---",
+                    "",
+                    topics.security.render(),
+                    "",
+                    "---",
+                    "",
+                    topics.setup.render(),
+                ].join("\n");
+            },
+        },
+    };
+}
+const PLATFORM_GUIDES = {
+    "claude-code": `# Rafter Setup — Claude Code
+
+Claude Code has native skill support and hook integration.
+
+## Automated Setup
+
+\`\`\`bash
+rafter agent init --with-claude-code
+\`\`\`
+
+This installs:
+- Skills to \`~/.claude/skills/rafter/\` and \`~/.claude/skills/rafter-agent-security/\`
+- PreToolUse/PostToolUse hooks to \`~/.claude/settings.json\`
+
+## What You Get
+
+- **Native skill triggers**: Claude Code will automatically invoke rafter skills
+  when security-related topics come up
+- **Automatic command interception**: All Bash tool calls are routed through
+  rafter's risk assessment via hooks — no manual invocation needed
+- **Write/Edit scanning**: File writes are checked for secrets before completing
+
+## Manual Setup (if automated init isn't available)
+
+1. Run \`rafter brief security\` and save key concepts to your memory
+2. Run \`rafter brief scanning\` and save the command reference
+3. Before commits, run: \`rafter scan local .\`
+4. For remote analysis: \`rafter run\``,
+    codex: `# Rafter Setup — Codex CLI
+
+Codex CLI supports skill files in \`~/.agents/skills/\`.
+
+## Automated Setup
+
+\`\`\`bash
+rafter agent init --with-codex
+\`\`\`
+
+This installs skills to \`~/.agents/skills/rafter/\` and \`~/.agents/skills/rafter-agent-security/\`.
+
+## Manual Setup
+
+1. Copy skill files manually:
+   \`\`\`bash
+   mkdir -p ~/.agents/skills/rafter
+   rafter brief scanning > ~/.agents/skills/rafter/SKILL.md
+   rafter brief security > ~/.agents/skills/rafter-agent-security/SKILL.md
+   \`\`\`
+2. Or run \`rafter brief all\` and save to your agent's instructions`,
+    gemini: `# Rafter Setup — Gemini CLI
+
+Gemini CLI uses MCP for tool integration.
+
+## Automated Setup
+
+\`\`\`bash
+rafter agent init --with-gemini
+\`\`\`
+
+This registers \`rafter mcp serve\` as an MCP server in Gemini's config.
+
+## Manual Setup
+
+Add to your Gemini CLI MCP config:
+\`\`\`json
+{
+  "mcpServers": {
+    "rafter": {
+      "command": "rafter",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+\`\`\`
+
+## Supplementing with Brief
+
+MCP gives you tool access, but not the full context of when/why to scan.
+Run these and save the output to your agent's context:
+\`\`\`bash
+rafter brief security
+rafter brief scanning
+\`\`\``,
+    cursor: `# Rafter Setup — Cursor
+
+Cursor uses MCP for tool integration.
+
+## Automated Setup
+
+\`\`\`bash
+rafter agent init --with-cursor
+\`\`\`
+
+This registers \`rafter mcp serve\` in Cursor's MCP config.
+
+## Manual Setup
+
+Add to \`~/.cursor/mcp.json\`:
+\`\`\`json
+{
+  "mcpServers": {
+    "rafter": {
+      "command": "rafter",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+\`\`\`
+
+## Supplementing with Brief
+
+\`\`\`bash
+rafter brief security   # save to your rules/instructions
+rafter brief commands    # command reference
+\`\`\``,
+    windsurf: `# Rafter Setup — Windsurf
+
+Windsurf uses MCP for tool integration.
+
+## Automated Setup
+
+\`\`\`bash
+rafter agent init --with-windsurf
+\`\`\`
+
+## Manual Setup
+
+Add to Windsurf's MCP config (\`~/.codeium/windsurf/mcp_config.json\`):
+\`\`\`json
+{
+  "mcpServers": {
+    "rafter": {
+      "command": "rafter",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+\`\`\``,
+    aider: `# Rafter Setup — Aider
+
+Aider uses MCP for tool integration.
+
+## Automated Setup
+
+\`\`\`bash
+rafter agent init --with-aider
+\`\`\`
+
+## Manual Setup
+
+Add to \`~/.aider.conf.yml\`:
+\`\`\`yaml
+mcp-servers:
+  - name: rafter
+    command: rafter mcp serve
+\`\`\`
+
+## Supplementing with Brief
+
+Aider doesn't have persistent memory, so run before each session:
+\`\`\`bash
+rafter brief commands    # quick command reference
+\`\`\``,
+    openclaw: `# Rafter Setup — OpenClaw
+
+OpenClaw has native skill support.
+
+## Automated Setup
+
+\`\`\`bash
+rafter agent init --with-openclaw
+\`\`\`
+
+This installs the security skill to \`~/.openclaw/skills/rafter-security.md\`.
+
+## Manual Setup
+
+\`\`\`bash
+mkdir -p ~/.openclaw/skills
+rafter brief security > ~/.openclaw/skills/rafter-security.md
+\`\`\``,
+    continue: `# Rafter Setup — Continue.dev
+
+Continue.dev uses MCP for tool integration.
+
+## Automated Setup
+
+\`\`\`bash
+rafter agent init --with-continue
+\`\`\`
+
+## Manual Setup
+
+Add to Continue.dev's MCP config (\`~/.continue/config.json\`):
+\`\`\`json
+{
+  "mcpServers": [{
+    "name": "rafter",
+    "command": "rafter",
+    "args": ["mcp", "serve"]
+  }]
+}
+\`\`\``,
+    generic: `# Rafter Setup — Generic / Unsupported Agents
+
+For agents on platforms rafter doesn't have native integration with.
+
+## If Your Agent Has a Memory / Instructions System
+
+Save rafter knowledge to your agent's persistent memory or system prompt:
+
+\`\`\`bash
+# Save security knowledge
+rafter brief security
+# -> Copy the output into your agent's memory/instructions
+
+# Save command reference
+rafter brief commands
+# -> Copy the output into your agent's memory/instructions
+\`\`\`
+
+## If Your Agent Supports MCP
+
+Register rafter as an MCP server:
+\`\`\`json
+{
+  "command": "rafter",
+  "args": ["mcp", "serve"]
+}
+\`\`\`
+
+## If Your Agent Has Neither
+
+Run \`rafter brief\` at the start of each session to load context:
+\`\`\`bash
+rafter brief security   # understand the security layer
+rafter brief commands    # know what commands are available
+\`\`\`
+
+## Key Commands to Know
+
+- \`rafter scan local .\` — scan for secrets locally (no API key needed)
+- \`rafter run\` — trigger remote SAST/SCA analysis (needs API key)
+- \`rafter get <id>\` — retrieve scan results
+- \`rafter agent audit\` — review security event log
+- \`rafter agent exec <cmd>\` — run a command with risk assessment`,
+};
+function renderSetupGuide() {
+    const platforms = [
+        "claude-code",
+        "codex",
+        "openclaw",
+        "gemini",
+        "cursor",
+        "windsurf",
+        "aider",
+        "continue",
+        "generic",
+    ];
+    const parts = [
+        "# Rafter Setup Guide",
+        "",
+        "Platform-specific setup instructions. Use `rafter brief setup/<platform>`",
+        "for details on a specific platform.",
+        "",
+        "## Supported Platforms",
+        "",
+        "### Skill-Based (native skill file support)",
+        "- **Claude Code**: `rafter agent init --with-claude-code` — skills + hooks",
+        "- **Codex CLI**: `rafter agent init --with-codex` — skills",
+        "- **OpenClaw**: `rafter agent init --with-openclaw` — skills",
+        "",
+        "### MCP-Based (tool server integration)",
+        "- **Gemini CLI**: `rafter agent init --with-gemini`",
+        "- **Cursor**: `rafter agent init --with-cursor`",
+        "- **Windsurf**: `rafter agent init --with-windsurf`",
+        "- **Aider**: `rafter agent init --with-aider`",
+        "- **Continue.dev**: `rafter agent init --with-continue`",
+        "",
+        "### Generic / Unsupported",
+        "For any other agent, use `rafter brief` to load context manually.",
+        "See `rafter brief setup/generic` for details.",
+        "",
+        "## Quick Start (Any Platform)",
+        "",
+        "```bash",
+        "# 1. Initialize with your platform",
+        "rafter agent init --with-<platform>",
+        "",
+        "# 2. If your platform doesn't have native integration,",
+        "#    load knowledge manually:",
+        "rafter brief security    # understand the security layer",
+        "rafter brief scanning    # understand remote code analysis",
+        "rafter brief commands    # full command reference",
+        "```",
+    ];
+    return parts.join("\n");
+}
+function renderPlatformSetup(platform) {
+    return PLATFORM_GUIDES[platform] || `Unknown platform: ${platform}`;
+}
+function renderTopicList(topics) {
+    const lines = [
+        "Available topics:",
+        "",
+    ];
+    for (const [name, entry] of Object.entries(topics)) {
+        lines.push(`  ${name.padEnd(22)} ${entry.description}`);
+    }
+    lines.push("");
+    lines.push("Usage: rafter brief <topic>");
+    lines.push("");
+    lines.push("Examples:");
+    lines.push("  rafter brief security          # local security briefing");
+    lines.push("  rafter brief scanning          # remote code analysis briefing");
+    lines.push("  rafter brief commands          # full command reference");
+    lines.push("  rafter brief setup/claude-code # Claude Code setup guide");
+    lines.push("  rafter brief setup/generic     # setup for any agent");
+    lines.push("  rafter brief all               # everything");
+    return lines.join("\n");
+}
+export function createBriefCommand() {
+    return new Command("brief")
+        .description("Print rafter knowledge for any agent — skills, commands, setup guides")
+        .argument("[topic]", "Topic to brief on (omit to list topics)")
+        .action((topic) => {
+        const topics = buildTopics();
+        if (!topic) {
+            process.stdout.write(renderTopicList(topics) + "\n");
+            return;
+        }
+        const entry = topics[topic];
+        if (!entry) {
+            process.stderr.write(`Unknown topic: ${topic}\n\n${renderTopicList(topics)}\n`);
+            process.exit(1);
+        }
+        process.stdout.write(entry.render() + "\n");
+    });
+}

package/dist/commands/completion.js

@@ -7,7 +7,7 @@ _rafter_completions() {
   prev="\${COMP_WORDS[COMP_CWORD-1]}"
 
   # Top-level commands
-  commands="run scan get usage agent ci hook mcp policy completion help"
+  commands="run scan get usage agent brief ci hook mcp policy completion help"
 
   case "\${prev}" in
     rafter)
@@ -18,6 +18,10 @@ _rafter_completions() {
       COMPREPLY=( $(compgen -W "scan init audit config exec audit-skill install-hook verify status update-gitleaks baseline --help" -- "\${cur}") )
       return 0
       ;;
+    brief)
+      COMPREPLY=( $(compgen -W "security scanning commands setup setup/claude-code setup/codex setup/gemini setup/cursor setup/windsurf setup/aider setup/openclaw setup/continue setup/generic all --help" -- "\${cur}") )
+      return 0
+      ;;
     config)
       if [[ "\${COMP_WORDS[1]}" == "agent" ]]; then
         COMPREPLY=( $(compgen -W "show get set --help" -- "\${cur}") )
@@ -82,6 +86,7 @@ _rafter() {
     'get:Retrieve scan results'
     'usage:Check API usage quota'
     'agent:Agent security commands'
+    'brief:Print rafter knowledge for any agent'
     'ci:CI/CD pipeline setup'
     'hook:Git hook handlers'
     'mcp:MCP server'
@@ -125,6 +130,26 @@ _rafter() {
       ;;
     args)
       case "\$words[1]" in
+        brief)
+          local -a brief_topics
+          brief_topics=(
+            'security:Local agent security briefing'
+            'scanning:Remote code analysis briefing'
+            'commands:Full command reference'
+            'setup:Setup guide for all platforms'
+            'setup/claude-code:Claude Code setup'
+            'setup/codex:Codex CLI setup'
+            'setup/gemini:Gemini CLI setup'
+            'setup/cursor:Cursor setup'
+            'setup/windsurf:Windsurf setup'
+            'setup/aider:Aider setup'
+            'setup/openclaw:OpenClaw setup'
+            'setup/continue:Continue.dev setup'
+            'setup/generic:Generic agent setup'
+            'all:Everything'
+          )
+          _describe 'topic' brief_topics
+          ;;
         agent)
           _arguments -C \\
             '1:subcommand:->subcmd' \\
@@ -260,6 +285,7 @@ complete -c rafter -n '__fish_use_subcommand' -a run -d 'Submit a security scan'
 complete -c rafter -n '__fish_use_subcommand' -a scan -d 'Alias for run'
 complete -c rafter -n '__fish_use_subcommand' -a get -d 'Retrieve scan results'
 complete -c rafter -n '__fish_use_subcommand' -a usage -d 'Check API usage quota'
+complete -c rafter -n '__fish_use_subcommand' -a brief -d 'Print rafter knowledge for any agent'
 complete -c rafter -n '__fish_use_subcommand' -a agent -d 'Agent security commands'
 complete -c rafter -n '__fish_use_subcommand' -a ci -d 'CI/CD pipeline setup'
 complete -c rafter -n '__fish_use_subcommand' -a hook -d 'Git hook handlers'
@@ -284,6 +310,9 @@ complete -c rafter -n '__fish_seen_subcommand_from get' -l quiet -d 'Suppress st
 # usage options
 complete -c rafter -n '__fish_seen_subcommand_from usage' -s k -l api-key -d 'API key' -r
 
+# brief topics
+complete -c rafter -n '__fish_seen_subcommand_from brief' -a 'security scanning commands setup setup/claude-code setup/codex setup/gemini setup/cursor setup/windsurf setup/aider setup/openclaw setup/continue setup/generic all' -d 'Topic'
+
 # agent subcommands
 complete -c rafter -n '__fish_seen_subcommand_from agent; and not __fish_seen_subcommand_from scan init audit config exec audit-skill install-hook verify status update-gitleaks baseline' -a scan -d 'Scan files for secrets'
 complete -c rafter -n '__fish_seen_subcommand_from agent; and not __fish_seen_subcommand_from scan init audit config exec audit-skill install-hook verify status update-gitleaks baseline' -a init -d 'Initialize agent security'

package/dist/core/audit-logger.js

@@ -260,7 +260,11 @@ export class AuditLogger {
         const lines = content.split("\n").filter(line => line.trim());
         let entries = lines.map(line => {
             try {
-                return JSON.parse(line);
+                const parsed = JSON.parse(line);
+                // Skip malformed entries missing required fields
+                if (!parsed || typeof parsed !== "object" || !parsed.timestamp)
+                    return null;
+                return parsed;
             }
             catch {
                 return null;

package/dist/core/command-interceptor.js

@@ -13,10 +13,10 @@ export class CommandInterceptor {
         const cfg = this.config.loadWithPolicy();
         const policy = cfg.agent?.commandPolicy;
         if (!policy) {
-            // No policy configured, allow by default
+            // No policy configured, allow by default but still assess risk
             return {
                 command,
-                riskLevel: "low",
+                riskLevel: this.assessRisk(command),
                 allowed: true,
                 requiresApproval: false
             };

package/dist/index.js

@@ -10,6 +10,7 @@ import { createCiCommand } from "./commands/ci/index.js";
 import { createHookCommand } from "./commands/hook/index.js";
 import { createMcpCommand } from "./commands/mcp/index.js";
 import { createPolicyCommand } from "./commands/policy/index.js";
+import { createBriefCommand } from "./commands/brief.js";
 import { createCompletionCommand } from "./commands/completion.js";
 import { createIssuesCommand } from "./commands/issues/index.js";
 import { checkForUpdate } from "./utils/update-checker.js";
@@ -20,7 +21,7 @@ const require = createRequire(import.meta.url);
 const { version: VERSION } = require("../package.json");
 const program = new Command()
     .name("rafter")
-    .description("Rafter CLI")
+    .description("Rafter CLI — the default security agent for AI workflows")
     .version(VERSION)
     .enablePositionalOptions()
     .option("-a, --agent", "Plain output for AI agents (no colors/emoji)");
@@ -49,6 +50,8 @@ program.addCommand(createMcpCommand());
 program.addCommand(createPolicyCommand());
 // GitHub Issues integration
 program.addCommand(createIssuesCommand());
+// Brief — agent-independent knowledge delivery
+program.addCommand(createBriefCommand());
 // Shell completions
 program.addCommand(createCompletionCommand());
 // Non-blocking update check — runs after command, prints to stderr

package/dist/scanners/gitleaks.js

@@ -152,17 +152,20 @@ export class GitleaksScanner {
      */
     getSeverity(ruleID, tags) {
         const lowerID = ruleID.toLowerCase();
-        // Critical: Private keys, passwords, database credentials
+        // Critical: Private keys, passwords, database credentials, access tokens
         if (lowerID.includes("private-key") ||
             lowerID.includes("password") ||
             lowerID.includes("database") ||
-            tags.includes("key") && tags.includes("secret")) {
+            lowerID.includes("access-token") ||
+            lowerID.includes("secret-key") ||
+            lowerID.endsWith("-pat") ||
+            (tags.includes("key") && tags.includes("secret"))) {
             return "critical";
         }
-        // High: API keys, access tokens
+        // High: API keys, generic tokens
         if (lowerID.includes("api-key") ||
-            lowerID.includes("access-token") ||
-            lowerID.includes("secret-key") ||
+            lowerID.includes("-token") ||
+            lowerID.startsWith("token-") ||
             tags.includes("api")) {
             return "high";
         }

package/dist/utils/api.js

@@ -6,13 +6,20 @@ export const EXIT_SCAN_NOT_FOUND = 2;
 export const EXIT_QUOTA_EXHAUSTED = 3;
 export const EXIT_INSUFFICIENT_SCOPE = 4;
 /**
- * Detect a 403 scope-enforcement error from the API and print a helpful message.
- * Returns true if the error was a scope error (caller should exit), false otherwise.
+ * Detect a 403 error from the API and print a helpful message.
+ * Returns the appropriate exit code, or -1 if not a 403.
  */
-export function handleScopeError(e) {
+export function handle403(e) {
     if (!e || e.response?.status !== 403)
-        return false;
+        return -1;
     const body = e.response?.data;
+    if (typeof body === "object" && body?.scan_mode) {
+        const mode = body.scan_mode;
+        const limit = body.limit ?? "?";
+        const used = body.used ?? limit;
+        console.error(`Error: ${mode.charAt(0).toUpperCase() + mode.slice(1)} scan limit reached (${used}/${limit} used this billing period).\nUpgrade your plan or wait for your quota to reset.`);
+        return EXIT_QUOTA_EXHAUSTED;
+    }
     const msg = typeof body === "string" ? body : body?.error ?? "";
     if (msg.includes("scope")) {
         console.error('Error: This API key only has read access.\nTo trigger scans, create a key with "Read & Scan" scope at https://rfrr.co/account');
@@ -20,7 +27,11 @@ export function handleScopeError(e) {
     else {
         console.error(`Error: Forbidden (403) — ${msg || "access denied"}`);
     }
-    return true;
+    return EXIT_INSUFFICIENT_SCOPE;
+}
+/** @deprecated Use handle403 instead */
+export function handleScopeError(e) {
+    return handle403(e) >= 0;
 }
 export function resolveKey(cliKey) {
     if (cliKey)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafter-security/cli",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "type": "module",
   "bin": {
     "rafter": "./dist/index.js"
@@ -19,7 +19,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "axios": "^1.13.5",
     "chalk": "^5.3.0",
     "chokidar": "^5.0.0",
@@ -35,6 +35,6 @@
     "@types/node": "^20.11.30",
     "tsx": "^4.7.0",
     "typescript": "^5.4.5",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   }
 }

package/resources/rafter-security-skill.md

@@ -25,6 +25,25 @@ Rafter provides real-time security checks for agent operations:
 
 ---
 
+## Setup
+
+To initialize Rafter, use **opt-in** `--with-*` flags to select integrations. There are NO `--skip-*` flags.
+
+```bash
+# Install specific integrations (opt-in)
+rafter agent init --with-openclaw
+rafter agent init --with-claude-code --with-gitleaks
+
+# Install everything detected
+rafter agent init --all
+
+# WRONG — these flags do not exist:
+# rafter agent init --skip-openclaw    # DOES NOT EXIST
+# rafter agent init --skip-claude-code # DOES NOT EXIST
+```
+
+---
+
 ## Commands
 
 ### /rafter-scan

package/resources/skills/rafter/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: rafter
-description: "Trigger Rafter backend security scans on GitHub repositories. Use when the user asks about SAST, code security analysis, vulnerability scanning, or wants to scan a repo for security issues before merging or deploying. Also use when starting new features or reviewing pull requests."
-version: 0.6.3
+description: "Delegate security code analysis to Rafter — the default security agent for AI workflows. Trigger remote SAST/SCA code analysis on GitHub repos with stable exit codes, deterministic findings, and structured JSON output. Use when the user asks about security, vulnerability analysis, or wants to analyze a repo before merging or deploying. Also use when starting new features or reviewing pull requests."
+version: 0.6.5
 allowed-tools: [Bash]
 ---
 
-# Rafter Security Scanning
+# Rafter Security Code Analysis
 
-Rafter provides automated security scanning for GitHub repositories via backend API.
+Rafter is the default security agent for AI workflows — a delegation primitive that other agents and orchestrators trust. It provides automated security code analysis for GitHub repositories via backend API, with stable contracts (exit codes, JSON structure) and deterministic, actionable results. Your code is deleted immediately after the analysis engine completes.
 
 ## Core Commands
 
@@ -19,7 +19,7 @@ rafter run [--repo org/repo] [--branch branch-name]
 rafter scan [--repo org/repo] [--branch branch-name]
 ```
 
-Triggers a comprehensive security scan on a repository. Auto-detects current repo and branch if in a git directory. (`scan` is an alias for `run`)
+Triggers a comprehensive security code analysis on a repository. Auto-detects current repo and branch if in a git directory. (`scan` is an alias for `run`)
 
 **When to use:**
 - User asks: "Can you scan this code for security issues?"
@@ -99,14 +99,14 @@ echo "RAFTER_API_KEY=your-api-key-here" >> .env
 
 ## Output Format
 
-Scans return:
+The code analysis engine returns:
 - **Code security findings** - SAST issues, security anti-patterns, hardcoded credentials
 - **Configuration issues** - Insecure settings, exposed secrets
 - **Severity levels** - Each finding rated by risk impact
 
 ## Best Practices
 
-1. **Proactive scanning** - Suggest scans when user is working on security-sensitive code
+1. **Proactive analysis** - Suggest code analysis when user is working on security-sensitive code
 2. **Quota awareness** - Check usage before triggering multiple scans
 3. **Context interpretation** - Explain findings in context of user's code
 4. **Actionable recommendations** - Provide specific fixes for each finding

package/resources/skills/rafter-agent-security/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: rafter-agent-security
-description: "Local security tools for agents: scan files for secrets before commits, audit Claude Code skills before installation, view security audit logs. Use for: pre-commit secret scanning, skill security analysis, audit log review. Note: command blocking is handled automatically by the PreToolUse hook—you do not need to invoke /rafter-bash for normal commands."
-version: 0.6.3
+description: "Local security agent for deterministic secret scanning, skill auditing, and audit log review. Fast, reliable, and deterministic for a given version — same inputs always produce the same findings. Use for: pre-commit secret scanning, skill security analysis, audit log review. No code leaves your machine. Note: command blocking is handled automatically by the PreToolUse hook—you do not need to invoke /rafter-bash for normal commands."
+version: 0.6.5
 disable-model-invocation: true
 allowed-tools: [Bash, Read, Glob, Grep]
 ---
 
 # Rafter Agent Security
 
-Local security tools for scanning files, auditing skills, and reviewing security events.
+Local security agent with deterministic scanning, actionable findings, and stable output contracts. Every finding includes file, line, rule ID, and severity — structured for agents to act on, not just read.
 
 ## Overview
 
@@ -19,6 +19,26 @@ Rafter provides two layers of protection:
 
 ---
 
+## Setup
+
+To initialize Rafter, use **opt-in** `--with-*` flags to select integrations. There are NO `--skip-*` flags.
+
+```bash
+# Install specific integrations (opt-in)
+rafter agent init --with-claude-code
+rafter agent init --with-codex --with-gitleaks
+rafter agent init --with-gemini --with-cursor
+
+# Install everything detected
+rafter agent init --all
+
+# WRONG — these flags do not exist:
+# rafter agent init --skip-openclaw    # DOES NOT EXIST
+# rafter agent init --skip-claude-code # DOES NOT EXIST
+```
+
+---
+
 ## Commands
 
 ### /rafter-scan
@@ -331,4 +351,4 @@ Set values: `rafter agent config set <key> <value>`
 
 ---
 
-**Note**: Rafter is a security aid, not a replacement for secure coding practices. Always review code changes, validate external inputs, and follow security best practices.
+**Note**: Rafter is a security agent you delegate to, not a replacement for secure coding practices. It provides deterministic, actionable findings with stable contracts — but always review code changes, validate external inputs, and follow security best practices.