@rafter-security/cli 0.6.5 → 0.7.0

package/dist/commands/agent/init.js

@@ -8,9 +8,45 @@ import os from "os";
 import { execSync } from "child_process";
 import { fileURLToPath } from "url";
 import { createRequire } from "module";
+import { createInterface } from "readline";
 import { fmt } from "../../utils/formatter.js";
+import { injectInstructionFile } from "./instruction-block.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+/**
+ * Install global instruction files for platforms that support them.
+ *
+ * Only Claude Code (~/.claude/CLAUDE.md) and Cursor (~/.cursor/rules/*.mdc)
+ * have confirmed global instruction file paths. Other platforms (Codex, Gemini,
+ * Windsurf, Continue.dev, Aider) only support project-level instruction files
+ * (AGENTS.md, GEMINI.md, .windsurfrules, .continuerules, .aider/conventions.md)
+ * which are handled by `rafter agent init-project` (not yet implemented).
+ */
+function installGlobalInstructions(platforms) {
+    const homeDir = os.homedir();
+    // Claude Code — ~/.claude/CLAUDE.md (confirmed global instruction file)
+    if (platforms.claudeCode) {
+        try {
+            const filePath = path.join(homeDir, ".claude", "CLAUDE.md");
+            injectInstructionFile(filePath);
+            console.log(fmt.success(`Installed Rafter instructions to ${filePath}`));
+        }
+        catch (e) {
+            console.log(fmt.warning(`Failed to write Claude Code instructions: ${e}`));
+        }
+    }
+    // Cursor — ~/.cursor/rules/rafter-security.mdc (global rules directory, markdown format)
+    if (platforms.cursor) {
+        try {
+            const filePath = path.join(homeDir, ".cursor", "rules", "rafter-security.mdc");
+            injectInstructionFile(filePath);
+            console.log(fmt.success(`Installed Rafter instructions to ${filePath}`));
+        }
+        catch (e) {
+            console.log(fmt.warning(`Failed to write Cursor instructions: ${e}`));
+        }
+    }
+}
 function installClaudeCodeHooks() {
     const homeDir = os.homedir();
     const settingsPath = path.join(homeDir, ".claude", "settings.json");
@@ -54,6 +90,175 @@ function installClaudeCodeHooks() {
     console.log(fmt.success(`Installed PreToolUse hooks to ${settingsPath}`));
     console.log(fmt.success(`Installed PostToolUse hooks to ${settingsPath}`));
 }
+function installCodexHooks() {
+    const homeDir = os.homedir();
+    const codexDir = path.join(homeDir, ".codex");
+    if (!fs.existsSync(codexDir)) {
+        fs.mkdirSync(codexDir, { recursive: true });
+    }
+    const hooksPath = path.join(codexDir, "hooks.json");
+    let config = {};
+    if (fs.existsSync(hooksPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(hooksPath, "utf-8"));
+        }
+        catch {
+            console.log(fmt.warning("Existing Codex hooks.json was unreadable, creating new one"));
+        }
+    }
+    if (!config.hooks)
+        config.hooks = {};
+    if (!config.hooks.PreToolUse)
+        config.hooks.PreToolUse = [];
+    if (!config.hooks.PostToolUse)
+        config.hooks.PostToolUse = [];
+    // Codex uses the same hookSpecificOutput protocol as Claude Code (format=claude)
+    const preHook = { type: "command", command: "rafter hook pretool" };
+    const postHook = { type: "command", command: "rafter hook posttool" };
+    // Remove existing rafter hooks
+    config.hooks.PreToolUse = config.hooks.PreToolUse.filter((entry) => !(entry.hooks || []).some((h) => h.command?.startsWith("rafter hook pretool")));
+    config.hooks.PostToolUse = config.hooks.PostToolUse.filter((entry) => !(entry.hooks || []).some((h) => h.command?.startsWith("rafter hook posttool")));
+    config.hooks.PreToolUse.push({ matcher: "Bash", hooks: [preHook] });
+    config.hooks.PostToolUse.push({ matcher: ".*", hooks: [postHook] });
+    fs.writeFileSync(hooksPath, JSON.stringify(config, null, 2), "utf-8");
+    console.log(fmt.success(`Installed hooks to ${hooksPath}`));
+}
+function installCursorHooks() {
+    const homeDir = os.homedir();
+    const cursorDir = path.join(homeDir, ".cursor");
+    if (!fs.existsSync(cursorDir)) {
+        fs.mkdirSync(cursorDir, { recursive: true });
+    }
+    const hooksPath = path.join(cursorDir, "hooks.json");
+    let config = {};
+    if (fs.existsSync(hooksPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(hooksPath, "utf-8"));
+        }
+        catch {
+            console.log(fmt.warning("Existing Cursor hooks.json was unreadable, creating new one"));
+        }
+    }
+    if (!config.version)
+        config.version = 1;
+    if (!config.hooks)
+        config.hooks = {};
+    if (!config.hooks.beforeShellExecution)
+        config.hooks.beforeShellExecution = [];
+    // Remove existing rafter hooks
+    config.hooks.beforeShellExecution = config.hooks.beforeShellExecution.filter((entry) => !entry.command?.includes("rafter hook pretool"));
+    config.hooks.beforeShellExecution.push({
+        command: "rafter hook pretool --format cursor",
+        type: "command",
+        timeout: 5000,
+    });
+    fs.writeFileSync(hooksPath, JSON.stringify(config, null, 2), "utf-8");
+    console.log(fmt.success(`Installed hooks to ${hooksPath}`));
+}
+function installGeminiHooks() {
+    const homeDir = os.homedir();
+    const geminiDir = path.join(homeDir, ".gemini");
+    if (!fs.existsSync(geminiDir)) {
+        fs.mkdirSync(geminiDir, { recursive: true });
+    }
+    const settingsPath = path.join(geminiDir, "settings.json");
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+        }
+        catch {
+            console.log(fmt.warning("Existing Gemini settings.json was unreadable, creating new one"));
+        }
+    }
+    if (!settings.hooks)
+        settings.hooks = {};
+    if (!settings.hooks.BeforeTool)
+        settings.hooks.BeforeTool = [];
+    if (!settings.hooks.AfterTool)
+        settings.hooks.AfterTool = [];
+    // Remove existing rafter hooks
+    settings.hooks.BeforeTool = settings.hooks.BeforeTool.filter((entry) => !(entry.hooks || []).some((h) => h.command?.includes("rafter hook pretool")));
+    settings.hooks.AfterTool = settings.hooks.AfterTool.filter((entry) => !(entry.hooks || []).some((h) => h.command?.includes("rafter hook posttool")));
+    settings.hooks.BeforeTool.push({
+        matcher: "shell|write_file",
+        hooks: [{ type: "command", command: "rafter hook pretool --format gemini", timeout: 5000 }],
+    });
+    settings.hooks.AfterTool.push({
+        matcher: ".*",
+        hooks: [{ type: "command", command: "rafter hook posttool --format gemini", timeout: 5000 }],
+    });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
+    console.log(fmt.success(`Installed hooks to ${settingsPath}`));
+}
+function installWindsurfHooks() {
+    const homeDir = os.homedir();
+    const windsurfDir = path.join(homeDir, ".windsurf");
+    if (!fs.existsSync(windsurfDir)) {
+        fs.mkdirSync(windsurfDir, { recursive: true });
+    }
+    const hooksPath = path.join(windsurfDir, "hooks.json");
+    let config = {};
+    if (fs.existsSync(hooksPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(hooksPath, "utf-8"));
+        }
+        catch {
+            console.log(fmt.warning("Existing Windsurf hooks.json was unreadable, creating new one"));
+        }
+    }
+    if (!config.hooks)
+        config.hooks = {};
+    if (!config.hooks.pre_run_command)
+        config.hooks.pre_run_command = [];
+    if (!config.hooks.pre_write_code)
+        config.hooks.pre_write_code = [];
+    // Remove existing rafter hooks
+    config.hooks.pre_run_command = config.hooks.pre_run_command.filter((entry) => !entry.command?.includes("rafter hook pretool"));
+    config.hooks.pre_write_code = config.hooks.pre_write_code.filter((entry) => !entry.command?.includes("rafter hook pretool"));
+    config.hooks.pre_run_command.push({
+        command: "rafter hook pretool --format windsurf",
+        show_output: true,
+    });
+    config.hooks.pre_write_code.push({
+        command: "rafter hook pretool --format windsurf",
+        show_output: true,
+    });
+    fs.writeFileSync(hooksPath, JSON.stringify(config, null, 2), "utf-8");
+    console.log(fmt.success(`Installed hooks to ${hooksPath}`));
+}
+function installContinueDevHooks() {
+    const homeDir = os.homedir();
+    const continueDir = path.join(homeDir, ".continue");
+    if (!fs.existsSync(continueDir)) {
+        fs.mkdirSync(continueDir, { recursive: true });
+    }
+    const settingsPath = path.join(continueDir, "settings.json");
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+        }
+        catch {
+            console.log(fmt.warning("Existing Continue.dev settings.json was unreadable, creating new one"));
+        }
+    }
+    if (!settings.hooks)
+        settings.hooks = {};
+    if (!settings.hooks.PreToolUse)
+        settings.hooks.PreToolUse = [];
+    if (!settings.hooks.PostToolUse)
+        settings.hooks.PostToolUse = [];
+    // Continue.dev uses the same protocol as Claude Code
+    const preHook = { type: "command", command: "rafter hook pretool" };
+    const postHook = { type: "command", command: "rafter hook posttool" };
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((entry) => !(entry.hooks || []).some((h) => h.command?.startsWith("rafter hook pretool")));
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => !(entry.hooks || []).some((h) => h.command?.startsWith("rafter hook posttool")));
+    settings.hooks.PreToolUse.push({ matcher: "Bash", hooks: [preHook] }, { matcher: "Write|Edit", hooks: [preHook] });
+    settings.hooks.PostToolUse.push({ matcher: ".*", hooks: [postHook] });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
+    console.log(fmt.success(`Installed hooks to ${settingsPath}`));
+}
 /** MCP server entry for rafter — shared across MCP-native clients */
 const RAFTER_MCP_ENTRY = {
     command: "rafter",
@@ -214,10 +419,10 @@ async function installClaudeCodeSkills() {
     }
     if (fs.existsSync(backendTemplatePath)) {
         fs.copyFileSync(backendTemplatePath, backendSkillPath);
-        console.log(fmt.success(`Installed Rafter Backend skill to ${backendSkillPath}`));
+        console.log(fmt.success(`Installed Rafter Remote skill to ${backendSkillPath}`));
     }
     else {
-        console.log(fmt.warning(`Backend skill template not found at ${backendTemplatePath}`));
+        console.log(fmt.warning(`Remote skill template not found at ${backendTemplatePath}`));
     }
     // Install Agent Security Skill
     const agentSkillDir = path.join(claudeSkillsDir, "rafter-agent-security");
@@ -246,10 +451,10 @@ function installCodexSkills() {
     }
     if (fs.existsSync(backendTemplatePath)) {
         fs.copyFileSync(backendTemplatePath, backendSkillPath);
-        console.log(fmt.success(`Installed Rafter Backend skill to ${backendSkillPath}`));
+        console.log(fmt.success(`Installed Rafter Remote skill to ${backendSkillPath}`));
     }
     else {
-        console.log(fmt.warning(`Backend skill template not found at ${backendTemplatePath}`));
+        console.log(fmt.warning(`Remote skill template not found at ${backendTemplatePath}`));
     }
     // Install Agent Security Skill
     const agentDir = path.join(agentsSkillsDir, "rafter-agent-security");
@@ -266,6 +471,20 @@ function installCodexSkills() {
         console.log(fmt.warning(`Agent Security skill template not found at ${agentTemplatePath}`));
     }
 }
+async function askYesNo(question, defaultYes = true) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+    return new Promise((resolve) => {
+        rl.question(`  ${question} ${suffix} `, (answer) => {
+            rl.close();
+            const trimmed = answer.trim().toLowerCase();
+            if (trimmed === "")
+                resolve(defaultYes);
+            else
+                resolve(trimmed === "y" || trimmed === "yes");
+        });
+    });
+}
 export function createInitCommand() {
     return new Command("init")
         .description("Initialize agent security system")
@@ -280,6 +499,7 @@ export function createInitCommand() {
         .option("--with-continue", "Install Continue.dev integration")
         .option("--with-gitleaks", "Download and install Gitleaks binary")
         .option("--all", "Install all detected integrations and download Gitleaks")
+        .option("-i, --interactive", "Guided setup — prompts for each detected integration")
         .option("--update", "Re-download gitleaks and reinstall integrations without resetting config")
         .action(async (opts) => {
         console.log(fmt.header("Rafter Agent Security Setup"));
@@ -295,16 +515,41 @@ export function createInitCommand() {
         const hasWindsurf = fs.existsSync(path.join(os.homedir(), ".codeium", "windsurf"));
         const hasContinueDev = fs.existsSync(path.join(os.homedir(), ".continue"));
         const hasAider = fs.existsSync(path.join(os.homedir(), ".aider.conf.yml"));
-        // Resolve opt-in flags (--all enables all detected)
-        const wantOpenClaw = opts.withOpenclaw || opts.all;
-        const wantClaudeCode = opts.withClaudeCode || opts.all;
-        const wantCodex = opts.withCodex || opts.all;
-        const wantGemini = opts.withGemini || opts.all;
-        const wantCursor = opts.withCursor || opts.all;
-        const wantWindsurf = opts.withWindsurf || opts.all;
-        const wantContinue = opts.withContinue || opts.all;
-        const wantAider = opts.withAider || opts.all;
-        const wantGitleaks = opts.withGitleaks || opts.all;
+        // Resolve opt-in flags (--all enables all detected, --interactive prompts)
+        let wantOpenClaw = opts.withOpenclaw || opts.all;
+        let wantClaudeCode = opts.withClaudeCode || opts.all;
+        let wantCodex = opts.withCodex || opts.all;
+        let wantGemini = opts.withGemini || opts.all;
+        let wantCursor = opts.withCursor || opts.all;
+        let wantWindsurf = opts.withWindsurf || opts.all;
+        let wantContinue = opts.withContinue || opts.all;
+        let wantAider = opts.withAider || opts.all;
+        let wantGitleaks = opts.withGitleaks || opts.all;
+        // Interactive mode: prompt for each detected integration
+        if (opts.interactive && !opts.all) {
+            console.log();
+            console.log(fmt.info("Select integrations to install:"));
+            console.log();
+            if (hasClaudeCode && !wantClaudeCode)
+                wantClaudeCode = await askYesNo("Install Claude Code hooks + skills?");
+            if (hasCodex && !wantCodex)
+                wantCodex = await askYesNo("Install Codex CLI skills + hooks?");
+            if (hasOpenClaw && !wantOpenClaw)
+                wantOpenClaw = await askYesNo("Install OpenClaw skill?");
+            if (hasGemini && !wantGemini)
+                wantGemini = await askYesNo("Install Gemini CLI MCP + hooks?");
+            if (hasCursor && !wantCursor)
+                wantCursor = await askYesNo("Install Cursor MCP + hooks?");
+            if (hasWindsurf && !wantWindsurf)
+                wantWindsurf = await askYesNo("Install Windsurf MCP + hooks?");
+            if (hasContinueDev && !wantContinue)
+                wantContinue = await askYesNo("Install Continue.dev MCP + hooks?");
+            if (hasAider && !wantAider)
+                wantAider = await askYesNo("Install Aider MCP server?");
+            if (!wantGitleaks)
+                wantGitleaks = await askYesNo("Download Gitleaks binary (enhanced scanning)?");
+            console.log();
+        }
         // Show detected environments with opt-in hints
         const detected = [];
         if (hasOpenClaw)
@@ -453,8 +698,9 @@ export function createInitCommand() {
             }
         }
         // Install Claude Code skills + hooks if opted in
+        // When --with-claude-code is explicitly passed, install even if .claude doesn't exist yet
         let claudeCodeOk = false;
-        if (hasClaudeCode && wantClaudeCode) {
+        if ((hasClaudeCode || opts.withClaudeCode) && wantClaudeCode) {
             try {
                 await installClaudeCodeSkills();
                 installClaudeCodeHooks();
@@ -465,11 +711,12 @@ export function createInitCommand() {
                 console.error(fmt.error(`Failed to install Claude Code integration: ${e}`));
             }
         }
-        // Install Codex CLI skills if opted in
+        // Install Codex CLI skills + hooks if opted in
         let codexOk = false;
         if (hasCodex && wantCodex) {
             try {
                 installCodexSkills();
+                installCodexHooks();
                 manager.set("agent.environments.codex.enabled", true);
                 codexOk = true;
             }
@@ -477,11 +724,12 @@ export function createInitCommand() {
                 console.error(fmt.error(`Failed to install Codex CLI integration: ${e}`));
             }
         }
-        // Install Gemini CLI MCP if opted in
+        // Install Gemini CLI MCP + hooks if opted in
         let geminiOk = false;
         if (hasGemini && wantGemini) {
             try {
                 geminiOk = installGeminiMcp();
+                installGeminiHooks();
                 if (geminiOk)
                     manager.set("agent.environments.gemini.enabled", true);
             }
@@ -489,11 +737,12 @@ export function createInitCommand() {
                 console.error(fmt.error(`Failed to install Gemini CLI integration: ${e}`));
             }
         }
-        // Install Cursor MCP if opted in
+        // Install Cursor MCP + hooks if opted in
         let cursorOk = false;
         if (hasCursor && wantCursor) {
             try {
                 cursorOk = installCursorMcp();
+                installCursorHooks();
                 if (cursorOk)
                     manager.set("agent.environments.cursor.enabled", true);
             }
@@ -501,11 +750,12 @@ export function createInitCommand() {
                 console.error(fmt.error(`Failed to install Cursor integration: ${e}`));
             }
         }
-        // Install Windsurf MCP if opted in
+        // Install Windsurf MCP + hooks if opted in
         let windsurfOk = false;
         if (hasWindsurf && wantWindsurf) {
             try {
                 windsurfOk = installWindsurfMcp();
+                installWindsurfHooks();
                 if (windsurfOk)
                     manager.set("agent.environments.windsurf.enabled", true);
             }
@@ -513,11 +763,12 @@ export function createInitCommand() {
                 console.error(fmt.error(`Failed to install Windsurf integration: ${e}`));
             }
         }
-        // Install Continue.dev MCP if opted in
+        // Install Continue.dev MCP + hooks if opted in
         let continueOk = false;
         if (hasContinueDev && wantContinue) {
             try {
                 continueOk = installContinueDevMcp();
+                installContinueDevHooks();
                 if (continueOk)
                     manager.set("agent.environments.continueDev.enabled", true);
             }
@@ -537,6 +788,11 @@ export function createInitCommand() {
                 console.error(fmt.error(`Failed to install Aider integration: ${e}`));
             }
         }
+        // Install global instruction files for platforms that support them
+        installGlobalInstructions({
+            claudeCode: claudeCodeOk,
+            cursor: cursorOk,
+        });
         console.log();
         console.log(fmt.success("Agent security initialized!"));
         console.log();

package/dist/commands/agent/install-hook.js

@@ -4,6 +4,7 @@ import os from "os";
 import path from "path";
 import { execSync } from "child_process";
 import { fileURLToPath } from 'url';
+import { fmt } from "../../utils/formatter.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 export function createInstallHookCommand() {
@@ -28,7 +29,7 @@ async function installHook(opts) {
 function getTemplatePath(templateName) {
     const templatePath = path.join(__dirname, "..", "..", "..", "resources", templateName);
     if (!fs.existsSync(templatePath)) {
-        console.error("❌ Error: Hook template not found");
+        console.error(fmt.error("Hook template not found"));
         console.error(`   Expected at: ${templatePath}`);
         process.exit(1);
     }
@@ -42,7 +43,7 @@ async function installLocalHook(hookName, templateName) {
         execSync("git rev-parse --git-dir", { stdio: "pipe" });
     }
     catch (e) {
-        console.error("❌ Error: Not in a git repository");
+        console.error(fmt.error("Not in a git repository"));
         console.error("   Run this command from inside a git repository");
         process.exit(1);
     }
@@ -56,30 +57,30 @@ async function installLocalHook(hookName, templateName) {
         const existing = fs.readFileSync(hookPath, "utf-8");
         const marker = hookName === "pre-push" ? "Rafter Security Pre-Push Hook" : "Rafter Security Pre-Commit Hook";
         if (existing.includes(marker)) {
-            console.log(`✓ Rafter ${hookName} hook already installed`);
+            console.log(fmt.success(`Rafter ${hookName} hook already installed`));
             return;
         }
         const backupPath = `${hookPath}.backup-${Date.now()}`;
         fs.copyFileSync(hookPath, backupPath);
-        console.log(`📦 Backed up existing hook to: ${path.basename(backupPath)}`);
+        console.log(fmt.info(`Backed up existing hook to: ${path.basename(backupPath)}`));
     }
     const hookContent = fs.readFileSync(getTemplatePath(templateName), "utf-8");
     fs.writeFileSync(hookPath, hookContent, "utf-8");
     fs.chmodSync(hookPath, 0o755);
-    console.log(`✓ Installed Rafter ${hookName} hook`);
+    console.log(fmt.success(`Installed Rafter ${hookName} hook`));
     console.log(`  Location: ${hookPath}`);
     console.log();
     if (hookName === "pre-push") {
         console.log("The hook will:");
-        console.log("  • Scan commits being pushed for secrets");
-        console.log("  • Block pushes if secrets are detected");
-        console.log("  • Can be bypassed with: git push --no-verify (not recommended)");
+        console.log("  - Scan commits being pushed for secrets");
+        console.log("  - Block pushes if secrets are detected");
+        console.log("  - Can be bypassed with: git push --no-verify (not recommended)");
     }
     else {
         console.log("The hook will:");
-        console.log("  • Scan staged files for secrets before each commit");
-        console.log("  • Block commits if secrets are detected");
-        console.log("  • Can be bypassed with: git commit --no-verify (not recommended)");
+        console.log("  - Scan staged files for secrets before each commit");
+        console.log("  - Block commits if secrets are detected");
+        console.log("  - Can be bypassed with: git commit --no-verify (not recommended)");
     }
     console.log();
 }
@@ -89,7 +90,7 @@ async function installLocalHook(hookName, templateName) {
 async function installGlobalHook(hookName, templateName) {
     const homeDir = os.homedir();
     if (!homeDir) {
-        console.error("❌ Error: Could not determine home directory");
+        console.error(fmt.error("Could not determine home directory"));
         process.exit(1);
     }
     const globalHooksDir = path.join(homeDir, ".rafter", "git-hooks");
@@ -102,7 +103,7 @@ async function installGlobalHook(hookName, templateName) {
     fs.chmodSync(hookPath, 0o755);
     try {
         execSync(`git config --global core.hooksPath "${globalHooksDir}"`, { stdio: "pipe" });
-        console.log(`✓ Installed Rafter ${hookName} hook globally`);
+        console.log(fmt.success(`Installed Rafter ${hookName} hook globally`));
         console.log(`  Location: ${hookPath}`);
         console.log(`  Git config: core.hooksPath = ${globalHooksDir}`);
         console.log();
@@ -116,7 +117,7 @@ async function installGlobalHook(hookName, templateName) {
         console.log();
     }
     catch (e) {
-        console.error("❌ Failed to configure global git hooks");
+        console.error(fmt.error("Failed to configure global git hooks"));
         console.error("   You may need to manually set: git config --global core.hooksPath ~/.rafter/git-hooks");
         process.exit(1);
     }

package/dist/commands/agent/instruction-block.js

@@ -0,0 +1,63 @@
+import fs from "fs";
+import path from "path";
+export const RAFTER_MARKER_START = "<!-- rafter:start -->";
+export const RAFTER_MARKER_END = "<!-- rafter:end -->";
+/** Rafter security context block for agent instruction files (CLAUDE.md, AGENTS.md, etc.) */
+export const RAFTER_INSTRUCTION_BLOCK = `${RAFTER_MARKER_START}
+## Security: Rafter
+
+This environment has Rafter available — the security toolkit built for AI workflows.
+
+**Local scanning** (always available, no API key needed):
+- \`rafter scan local .\` — scan for leaked credentials
+- \`rafter scan local --staged\` — scan staged changes only
+
+**Remote analysis** (requires RAFTER_API_KEY):
+- \`rafter run\` — deterministic SAST, secret detection, dependency checks
+- \`rafter run --mode plus\` — agentic deep-dive with additional analysis passes
+
+Consider scanning before pushing, shipping features, or merging PRs.
+If RAFTER_API_KEY is not set, local scanning still works — use what's available.
+
+**Project integration:**
+- \`rafter agent install-hook\` — pre-commit secret scanning
+- \`rafter ci init\` — add scanning to CI/CD pipeline
+- \`.rafter.yml\` — project-specific security policy
+
+**More:**
+- \`rafter agent audit-skill <path>\` — audit a skill before installing
+- \`rafter agent audit --last 5\` — recent security events
+- \`rafter brief commands\` — full CLI reference
+${RAFTER_MARKER_END}`;
+/**
+ * Write a Rafter instruction block into an instruction file.
+ * Uses marker comments for idempotent updates — existing rafter blocks are replaced,
+ * non-rafter content is preserved.
+ */
+export function injectInstructionFile(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const block = RAFTER_INSTRUCTION_BLOCK;
+    const startMarker = RAFTER_MARKER_START;
+    const endMarker = RAFTER_MARKER_END;
+    let content = "";
+    if (fs.existsSync(filePath)) {
+        content = fs.readFileSync(filePath, "utf-8");
+    }
+    // Replace existing block or append
+    const startIdx = content.indexOf(startMarker);
+    const endIdx = content.indexOf(endMarker);
+    if (startIdx !== -1 && endIdx !== -1) {
+        content = content.slice(0, startIdx) + block + content.slice(endIdx + endMarker.length);
+    }
+    else {
+        if (content.length > 0 && !content.endsWith("\n\n")) {
+            content += content.endsWith("\n") ? "\n" : "\n\n";
+        }
+        content += block + "\n";
+    }
+    fs.writeFileSync(filePath, content, "utf-8");
+    return true;
+}

package/dist/commands/agent/scan.js

@@ -47,6 +47,7 @@ export function createScanCommand() {
         .option("--engine <engine>", "Scan engine: gitleaks or patterns", "auto")
         .option("--baseline", "Filter findings present in the saved baseline")
         .option("--watch", "Watch for file changes and re-scan on change")
+        .option("--history", "Scan git history for secrets (requires gitleaks engine)")
         .action(async (scanPath, opts) => {
         // Validate flags before doing any work
         const validEngines = ["auto", "gitleaks", "patterns"];
@@ -103,7 +104,7 @@ export function createScanCommand() {
             if (!opts.quiet) {
                 console.error(`Scanning directory: ${resolvedPath} (${engine})`);
             }
-            results = await scanDirectory(resolvedPath, engine, scanCfg);
+            results = await scanDirectory(resolvedPath, engine, scanCfg, opts.history);
         }
         else {
             if (!opts.quiet) {
@@ -372,11 +373,11 @@ async function scanFile(filePath, engine, scanCfg) {
 /**
  * Scan a directory with selected engine
  */
-async function scanDirectory(dirPath, engine, scanCfg) {
+async function scanDirectory(dirPath, engine, scanCfg, history) {
     if (engine === "gitleaks") {
         try {
             const gitleaks = new GitleaksScanner();
-            return await gitleaks.scanDirectory(dirPath);
+            return await gitleaks.scanDirectory(dirPath, { useGit: history ?? false });
         }
         catch (e) {
             console.error(fmt.warning("Gitleaks scan failed, falling back to patterns"));

package/dist/commands/agent/verify.js

@@ -193,7 +193,7 @@ export function createVerifyCommand() {
             console.log(fmt.success(`${passed.length}/${results.length} core checks passed${warnNote}`));
         }
         else {
-            console.log(fmt.error(`${hardFailed.length} check${hardFailed.length > 1 ? "s" : ""} failed`));
+            console.log(fmt.error(`${passed.length}/${results.length} checks passed — ${hardFailed.length} failed`));
         }
         console.log();
         if (hardFailed.length > 0) {

package/dist/commands/backend/run.js

@@ -9,6 +9,7 @@ import { handleScanStatus } from "./scan-status.js";
  */
 export async function runRemoteScan(opts) {
     const key = resolveKey(opts.apiKey);
+    const ghToken = opts.githubToken || process.env.RAFTER_GITHUB_TOKEN;
     let repo, branch;
     try {
         ({ repo, branch } = detectRepo({ repo: opts.repo, branch: opts.branch, quiet: opts.quiet }));
@@ -22,10 +23,17 @@ export async function runRemoteScan(opts) {
         }
         process.exit(EXIT_GENERAL_ERROR);
     }
+    const body = {
+        repository_name: repo,
+        branch_name: branch,
+        scan_mode: opts.mode ?? "fast",
+    };
+    if (ghToken)
+        body.github_token = ghToken;
     if (!opts.quiet) {
         const spinner = ora("Submitting scan").start();
         try {
-            const { data } = await axios.post(`${API}/static/scan`, { repository_name: repo, branch_name: branch, scan_mode: opts.mode ?? "fast" }, { headers: { "x-api-key": key } });
+            const { data } = await axios.post(`${API}/static/scan`, body, { headers: { "x-api-key": key } });
             spinner.succeed(`Scan ID: ${data.scan_id}`);
             if (opts.skipInteractive)
                 return;
@@ -56,7 +64,7 @@ export async function runRemoteScan(opts) {
     }
     else {
         try {
-            const { data } = await axios.post(`${API}/static/scan`, { repository_name: repo, branch_name: branch, scan_mode: opts.mode ?? "fast" }, { headers: { "x-api-key": key } });
+            const { data } = await axios.post(`${API}/static/scan`, body, { headers: { "x-api-key": key } });
             if (opts.skipInteractive)
                 return;
             const exitCode = await handleScanStatus(data.scan_id, { "x-api-key": key }, opts.format ?? "md", opts.quiet);
@@ -90,12 +98,13 @@ function addRunOptions(cmd) {
         .option("-k, --api-key <key>", "API key or RAFTER_API_KEY env var")
         .option("-f, --format <format>", "json | md", "md")
         .option("-m, --mode <mode>", "scan mode: fast | plus", "fast")
+        .option("--github-token <token>", "GitHub PAT for private repos (or RAFTER_GITHUB_TOKEN env var)")
         .option("--skip-interactive", "do not wait for scan to complete")
         .option("--quiet", "suppress status messages");
 }
 export function createRunCommand() {
     return addRunOptions(new Command("run")
-        .description("Trigger a remote backend security scan")).action(async (opts) => {
+        .description("Trigger a remote security scan")).action(async (opts) => {
         await runRemoteScan(opts);
     });
 }