@rafter-security/cli 0.7.3 → 0.7.6

package/dist/commands/agent/audit-skill.js

@@ -145,7 +145,7 @@ function displayQuickScan(scan, skillName) {
     else {
         console.log(fmt.warning(`Secrets: ${scan.secrets} found`));
         console.log("   → API keys, tokens, or credentials detected");
-        console.log("   → Run: rafter scan local <path> for details");
+        console.log("   → Run: rafter secrets <path> for details");
     }
     // URLs
     if (scan.urls.length === 0) {

package/dist/commands/agent/components.js

@@ -104,6 +104,12 @@ function claudeCodeHooks() {
             const post = { type: "command", command: "rafter hook posttool" };
             settings.hooks.PreToolUse = filterOutRafter(settings.hooks.PreToolUse, (e) => hookEntryMatchesRafter(e, "rafter hook pretool"));
             settings.hooks.PostToolUse = filterOutRafter(settings.hooks.PostToolUse, (e) => hookEntryMatchesRafter(e, "rafter hook posttool"));
+            // Strip legacy SessionStart entry from <=0.7.4 installs.
+            if (Array.isArray(settings.hooks.SessionStart)) {
+                settings.hooks.SessionStart = filterOutRafter(settings.hooks.SessionStart, (e) => hookEntryMatchesRafter(e, "rafter hook session-start"));
+                if (settings.hooks.SessionStart.length === 0)
+                    delete settings.hooks.SessionStart;
+            }
             settings.hooks.PreToolUse.push({ matcher: "Bash", hooks: [pre] }, { matcher: "Write|Edit", hooks: [pre] });
             settings.hooks.PostToolUse.push({ matcher: ".*", hooks: [post] });
             writeJson(settingsPath, settings);
@@ -118,6 +124,11 @@ function claudeCodeHooks() {
             if (settings.hooks?.PostToolUse) {
                 settings.hooks.PostToolUse = filterOutRafter(settings.hooks.PostToolUse, (e) => hookEntryMatchesRafter(e, "rafter hook posttool"));
             }
+            if (Array.isArray(settings.hooks?.SessionStart)) {
+                settings.hooks.SessionStart = filterOutRafter(settings.hooks.SessionStart, (e) => hookEntryMatchesRafter(e, "rafter hook session-start"));
+                if (settings.hooks.SessionStart.length === 0)
+                    delete settings.hooks.SessionStart;
+            }
             writeJson(settingsPath, settings);
         },
     };
@@ -266,6 +277,52 @@ function codexHooks() {
         },
     };
 }
+/**
+ * Project-scope Claude Code MCP config (<cwd>/.mcp.json). Unlike other
+ * claude-code components which touch ~/.claude, this one writes at the
+ * project root — Claude Code auto-loads it on startup and exposes
+ * `mcp__rafter__*` tools to the agent.
+ */
+function claudeCodeMcp() {
+    const home = os.homedir();
+    const mcpPath = path.join(process.cwd(), ".mcp.json");
+    return {
+        id: "claude-code.mcp",
+        platform: "claude-code",
+        kind: "mcp",
+        description: "Claude Code project-scope MCP server (<project>/.mcp.json)",
+        detectDir: path.join(home, ".claude"),
+        path: mcpPath,
+        isInstalled: () => {
+            if (!fs.existsSync(mcpPath))
+                return false;
+            const cfg = readJson(mcpPath);
+            return !!cfg.mcpServers?.rafter;
+        },
+        install: () => {
+            const cfg = fs.existsSync(mcpPath) ? readJson(mcpPath) : {};
+            cfg.mcpServers ?? (cfg.mcpServers = {});
+            cfg.mcpServers.rafter = { ...RAFTER_MCP_ENTRY };
+            writeJson(mcpPath, cfg);
+        },
+        uninstall: () => {
+            if (!fs.existsSync(mcpPath))
+                return;
+            const cfg = readJson(mcpPath);
+            if (!removeKey(cfg.mcpServers, "rafter"))
+                return;
+            if (cfg.mcpServers && Object.keys(cfg.mcpServers).length === 0) {
+                delete cfg.mcpServers;
+            }
+            if (Object.keys(cfg).length === 0) {
+                fs.unlinkSync(mcpPath);
+            }
+            else {
+                writeJson(mcpPath, cfg);
+            }
+        },
+    };
+}
 function cursorHooks() {
     const home = os.homedir();
     const hooksPath = path.join(home, ".cursor", "hooks.json");
@@ -728,6 +785,7 @@ export function getComponentRegistry() {
             claudeCodeHooks(),
             claudeCodeInstructions(),
             claudeCodeSkills(),
+            claudeCodeMcp(),
             codexHooks(),
             codexSkills(),
             cursorHooks(),

package/dist/commands/agent/exec.js

@@ -29,7 +29,7 @@ export function createExecCommand() {
             if (scanResult.secretsFound) {
                 console.error(`\n${fmt.warning("Secrets detected in staged files!")}\n`);
                 console.error(`Found ${scanResult.count} secret(s) in ${scanResult.files} file(s)`);
-                console.error(`\nRun 'rafter scan local' for details.\n`);
+                console.error(`\nRun 'rafter secrets' for details.\n`);
                 interceptor.logEvaluation(evaluation, "blocked");
                 process.exit(1);
             }

package/dist/commands/agent/init.js

@@ -127,6 +127,15 @@ function installClaudeCodeHooks(root) {
         const hooks = entry.hooks || [];
         return !hooks.some((h) => h.command === "rafter hook posttool");
     });
+    // Strip legacy SessionStart entry left over from <=0.7.4 installs.
+    if (Array.isArray(settings.hooks.SessionStart)) {
+        settings.hooks.SessionStart = settings.hooks.SessionStart.filter((entry) => {
+            const hooks = entry.hooks || [];
+            return !hooks.some((h) => h.command === "rafter hook session-start");
+        });
+        if (settings.hooks.SessionStart.length === 0)
+            delete settings.hooks.SessionStart;
+    }
     // Add Rafter hooks
     settings.hooks.PreToolUse.push({ matcher: "Bash", hooks: [preHook] }, { matcher: "Write|Edit", hooks: [preHook] });
     settings.hooks.PostToolUse.push({ matcher: ".*", hooks: [postHook] });
@@ -303,6 +312,28 @@ const RAFTER_MCP_ENTRY = {
     command: "rafter",
     args: ["mcp", "serve"],
 };
+/**
+ * Install MCP server config for Claude Code (<root>/.mcp.json).
+ * Project-scope MCP config that Claude Code auto-loads on startup.
+ */
+function installClaudeCodeMcp(root) {
+    const mcpPath = path.join(root, ".mcp.json");
+    let config = {};
+    if (fs.existsSync(mcpPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(mcpPath, "utf-8"));
+        }
+        catch {
+            console.log(fmt.warning("Existing .mcp.json was unreadable, creating new one"));
+        }
+    }
+    if (!config.mcpServers)
+        config.mcpServers = {};
+    config.mcpServers.rafter = { ...RAFTER_MCP_ENTRY };
+    fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2), "utf-8");
+    console.log(fmt.success(`Installed Rafter MCP server to ${mcpPath}`));
+    return true;
+}
 /**
  * Install MCP server config for Gemini CLI (~/.gemini/settings.json)
  */
@@ -463,6 +494,52 @@ async function installClaudeCodeSkills(root) {
 function installCodexSkills(root) {
     installSkillsTo(path.join(root, ".agents", "skills"));
 }
+function installGeminiSkills(root) {
+    installSkillsTo(path.join(root, ".agents", "skills"));
+}
+/**
+ * Register installed skills with Gemini CLI via `gemini skills link <abs-path>`.
+ *
+ * Requires gemini CLI >= 0.35 (the version that added `gemini skills`).
+ * Missing CLI, missing subcommand, and per-skill registration failures are
+ * non-fatal: we warn and continue so the on-disk install still succeeds.
+ */
+function registerGeminiSkills(skillsDir) {
+    // Probe for the `gemini` binary. Absence is expected on CI / fresh machines.
+    try {
+        execSync("gemini --version", { stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+    }
+    catch {
+        console.log(fmt.warning("gemini CLI not found on PATH — skipping skill registration. " +
+            "Skills are installed to disk; re-run after installing gemini ≥ 0.35."));
+        return;
+    }
+    // Probe `gemini skills` subcommand (added in 0.35).
+    try {
+        execSync("gemini skills --help", { stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+    }
+    catch {
+        console.log(fmt.warning("gemini CLI does not support `skills` subcommand (needs ≥ 0.35). " +
+            "Skipping registration — skills are still installed to disk."));
+        return;
+    }
+    for (const skill of AGENT_SKILLS) {
+        const absPath = path.resolve(skillsDir, skill.name);
+        if (!fs.existsSync(absPath))
+            continue;
+        try {
+            execSync(`gemini skills link ${JSON.stringify(absPath)}`, {
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: 10000,
+            });
+            console.log(fmt.success(`Registered ${skill.name} with Gemini CLI`));
+        }
+        catch (e) {
+            const msg = (e?.stderr?.toString?.() || e?.message || "").trim();
+            console.log(fmt.warning(`Failed to register ${skill.name} with Gemini CLI: ${msg.split("\n")[0] || "unknown error"}`));
+        }
+    }
+}
 async function askYesNo(question, defaultYes = true) {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
     const suffix = defaultYes ? "[Y/n]" : "[y/N]";
@@ -717,6 +794,17 @@ export function createInitCommand() {
             try {
                 await installClaudeCodeSkills(root);
                 installClaudeCodeHooks(root);
+                if (scope === "project") {
+                    const components = (manager.get("agent.components") ?? {});
+                    if (components["claude-code.mcp"]?.enabled === false) {
+                        console.log(fmt.info("Skipped .mcp.json (claude-code.mcp disabled; re-enable with `rafter agent enable claude-code.mcp`)"));
+                    }
+                    else {
+                        installClaudeCodeMcp(root);
+                        components["claude-code.mcp"] = { enabled: true, updatedAt: new Date().toISOString() };
+                        manager.set("agent.components", components);
+                    }
+                }
                 if (scope === "user")
                     manager.set("agent.environments.claudeCode.enabled", true);
                 claudeCodeOk = true;
@@ -739,11 +827,13 @@ export function createInitCommand() {
                 console.error(fmt.error(`Failed to install Codex CLI integration: ${e}`));
             }
         }
-        // Install Gemini CLI MCP + hooks if opted in
+        // Install Gemini CLI MCP + skills + hooks if opted in
         let geminiOk = false;
         if ((hasGemini || (opts.local && wantGemini)) && wantGemini) {
             try {
                 geminiOk = installGeminiMcp(root);
+                installGeminiSkills(root);
+                registerGeminiSkills(path.join(root, ".agents", "skills"));
                 installGeminiHooks(root);
                 if (geminiOk && scope === "user")
                     manager.set("agent.environments.gemini.enabled", true);
@@ -873,7 +963,7 @@ export function createInitCommand() {
             console.log("No agent environments detected. Install an agent tool and re-run with --with-<tool>.");
         }
         console.log();
-        console.log("  - Run: rafter scan local . (test secret scanning)");
+        console.log("  - Run: rafter secrets . (test secret scanning)");
         console.log("  - Configure: rafter agent config show");
         console.log();
         // Warn if a different rafter version shadows this one on PATH

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

@@ -4,30 +4,29 @@ 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
+## Security: Rafter (required review gate)
 
-This environment has Rafter available — the security toolkit built for AI workflows.
+Rafter is this project's security review gate. A security-relevant task is
+**not complete** until a rafter skill (or \`rafter run\`) has reviewed it.
+Don't mark done, don't hand off, don't open a PR without that pass.
 
-**Local scanning** (always available, no API key needed):
-- \`rafter scan local .\` — scan for leaked credentials
-- \`rafter scan local --staged\` — scan staged changes only
+**Stop and invoke before continuing:**
 
-**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
+- Designing auth, payments, credentials, tokens, sessions, file upload,
+  user data, or data deletion → **\`rafter-secure-design\`** (before writing code).
+- Diff touches user input, SQL, shell, auth, credentials, file paths, or
+  serialization → **\`rafter-code-review\`** + \`rafter run\` (before declaring done).
+- About to install or forward a third-party SKILL.md, MCP manifest, Cursor
+  rule, or agent config → **\`rafter-skill-review\`** (before copying anywhere).
+- Security-adjacent but the angle isn't clear → **\`rafter\`** (the router skill,
+  powerful toolkit to help you write more secure code).
 
-Consider scanning before pushing, shipping features, or merging PRs.
-If RAFTER_API_KEY is not set, local scanning still works — use what's available.
+**CLI:**
 
-**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 run\` — remote SAST + SCA + secrets (real code analysis, needs \`RAFTER_API_KEY\`)
+- \`rafter secrets .\` — local secrets only (offline; NOT a code-security scan)
+- \`rafter run --mode plus\` — everything in default (\`--mode fast\`) plus
+  powerful agentic deep-dives (needs \`RAFTER_API_KEY\`)
 ${RAFTER_MARKER_END}`;
 /**
  * Write a Rafter instruction block into an instruction file.

package/dist/commands/agent/scan.js

@@ -67,7 +67,7 @@ export function createScanCommand() {
         const isAgentScan = argv.includes("agent") && argv.includes("scan") &&
             argv.indexOf("agent") < argv.indexOf("scan");
         if (isAgentScan) {
-            process.stderr.write("Warning: rafter agent scan is deprecated and will be removed in a future major version. Use rafter scan local instead.\n");
+            process.stderr.write("Warning: rafter agent scan is deprecated and will be removed in a future major version. Use rafter secrets instead.\n");
         }
         // Load policy-merged config for excludePaths/customPatterns
         const manager = new ConfigManager();
@@ -115,6 +115,17 @@ export function createScanCommand() {
         outputScanResults(applyBaseline(results, baselineEntries), opts);
     });
 }
+/**
+ * `rafter secrets` — top-level alias for the secret scanner. Same engine
+ * and flags as `rafter scan local`; the name makes the scope (secrets only,
+ * not full code analysis) explicit to agents and humans.
+ */
+export function createSecretsCommand() {
+    const cmd = createScanCommand();
+    cmd.name("secrets");
+    cmd.description("Scan files/directories for hardcoded secrets (regex + gitleaks). Secrets only — not a code analysis. For full SAST/SCA, use 'rafter run'.");
+    return cmd;
+}
 /**
  * Emit SARIF 2.1.0 JSON for GitHub/GitLab security tab integration
  */

package/dist/commands/brief.js

@@ -210,7 +210,7 @@ This installs:
 ## Manual Setup (if automated init isn't available)
 
 1. Run \`rafter brief scanning\` and save the command reference
-2. Before commits, run: \`rafter scan local .\`
+2. Before commits, run: \`rafter secrets .\`
 3. For remote analysis: \`rafter run\``,
     codex: `# Rafter Setup — Codex CLI
 
@@ -424,7 +424,7 @@ rafter brief commands    # know what commands are available
 
 ## Key Commands to Know
 
-- \`rafter scan local .\` — scan for secrets locally (no API key needed)
+- \`rafter secrets .\` — scan for hardcoded 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

package/dist/commands/ci/init.js

@@ -100,7 +100,7 @@ jobs:
         run: npm install -g @rafter-security/cli
 
       - name: Scan for secrets
-        run: rafter scan local . --quiet
+        run: rafter secrets . --quiet
 `;
     if (withBackend) {
         yaml += `
@@ -131,7 +131,7 @@ secret-scan:
   image: node:20
   script:
     - npm install -g @rafter-security/cli
-    - rafter scan local . --quiet
+    - rafter secrets . --quiet
   rules:
     - if: $CI_PIPELINE_SOURCE == "push"
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
@@ -169,7 +169,7 @@ jobs:
           command: npm install -g @rafter-security/cli
       - run:
           name: Scan for secrets
-          command: rafter scan local . --quiet
+          command: rafter secrets . --quiet
 `;
     if (withBackend) {
         yaml += `

package/dist/commands/hook/pretool.js

@@ -142,7 +142,7 @@ function evaluateBash(command) {
             audit.logSecretDetected("staged files", `${scanResult.count} secret(s)`, "blocked");
             return {
                 decision: "deny",
-                reason: `${scanResult.count} secret(s) detected in ${scanResult.files} staged file(s). Run 'rafter scan local --staged' for details.`,
+                reason: `${scanResult.count} secret(s) detected in ${scanResult.files} staged file(s). Run 'rafter secrets --staged' for details.`,
             };
         }
     }

package/dist/commands/report.js

@@ -25,7 +25,7 @@ export function createReportCommand() {
         }
         else {
             console.error("Error: No input provided. Pipe scan results or provide a file path.\n" +
-                "  Example: rafter scan local --json . | rafter report -o report.html\n" +
+                "  Example: rafter secrets --json . | rafter report -o report.html\n" +
                 "  Example: rafter report scan-results.json -o report.html");
             process.exit(2);
             return;

package/dist/commands/scan/index.js

@@ -3,16 +3,17 @@
  *
  * Default (no subcommand): remote scan (same as `rafter run`)
  * rafter scan remote:       explicit alias for remote scan
- * rafter scan local [path]: local secret scanner (was `rafter agent scan`)
+ * rafter scan local [path]: hidden back-compat alias for `rafter secrets`
+ *                           (was `rafter agent scan` before 0.7.4).
  */
 import { Command } from "commander";
 import { runRemoteScan } from "../backend/run.js";
 import { createScanCommand as createLocalScanCommand } from "../agent/scan.js";
 export function createScanGroupCommand() {
-    // "local" subcommand — reuses agent/scan.ts logic, renamed
+    // "local" subcommand — back-compat alias for `rafter secrets`. Hidden from help.
     const localCmd = createLocalScanCommand();
     localCmd.name("local");
-    localCmd.description("Scan files or directories for secrets (local)");
+    localCmd.description("(deprecated alias for 'rafter secrets')");
     // "remote" subcommand — same handler as `rafter run`
     const remoteCmd = new Command("remote")
         .description("Trigger a remote backend security scan (explicit alias for 'rafter run')")
@@ -29,7 +30,7 @@ export function createScanGroupCommand() {
     });
     // Root scan group — default action is remote scan
     const scanGroup = new Command("scan")
-        .description("Scan for security issues. Default: remote scan. Use 'scan local' for local secret scanning.")
+        .description("Trigger a remote security scan (requires RAFTER_API_KEY).")
         .enablePositionalOptions()
         .option("-r, --repo <repo>", "org/repo (default: current)")
         .option("-b, --branch <branch>", "branch (default: current else main)")
@@ -39,7 +40,7 @@ export function createScanGroupCommand() {
         .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");
-    scanGroup.addCommand(localCmd);
+    scanGroup.addCommand(localCmd, { hidden: true });
     scanGroup.addCommand(remoteCmd);
     // When invoked with no subcommand, run remote scan
     scanGroup.action(async (opts) => {

package/dist/index.js

@@ -5,6 +5,7 @@ import { createRunCommand } from "./commands/backend/run.js";
 import { createGetCommand } from "./commands/backend/get.js";
 import { createUsageCommand } from "./commands/backend/usage.js";
 import { createScanGroupCommand } from "./commands/scan/index.js";
+import { createSecretsCommand } from "./commands/agent/scan.js";
 import { createAgentCommand } from "./commands/agent/index.js";
 import { createSkillCommand } from "./commands/skill/index.js";
 import { createCiCommand } from "./commands/ci/index.js";
@@ -40,6 +41,8 @@ program.addCommand(createGetCommand());
 program.addCommand(createUsageCommand());
 // Scan command group (default: remote scan; subcommands: local, remote)
 program.addCommand(createScanGroupCommand());
+// Secrets — top-level alias for local secret scanning (explicit-scope name)
+program.addCommand(createSecretsCommand());
 // Agent commands
 program.addCommand(createAgentCommand());
 // Skill commands (install / uninstall / list rafter-authored skills)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafter-security/cli",
-  "version": "0.7.3",
+  "version": "0.7.6",
   "type": "module",
   "bin": {
     "rafter": "./dist/index.js"

package/resources/pre-commit-hook.sh

@@ -27,7 +27,7 @@ fi
 echo "🔍 Rafter: Scanning staged files for secrets..."
 
 # Scan staged files
-rafter scan local --staged --quiet
+rafter secrets --staged --quiet
 
 EXIT_CODE=$?
 

package/resources/pre-push-hook.sh

@@ -38,7 +38,7 @@ while read local_ref local_sha remote_ref remote_sha; do
 
     echo "🔍 Rafter: Scanning commits being pushed ($local_ref)..."
 
-    rafter scan local --diff "$ref_arg" --quiet
+    rafter secrets --diff "$ref_arg" --quiet
     EXIT_CODE=$?
 
     if [ $EXIT_CODE -ne 0 ]; then
@@ -49,7 +49,7 @@ done
 if [ $FOUND_SECRETS -ne 0 ]; then
     echo -e "${RED}❌ Push blocked: Secrets detected in commits being pushed${NC}"
     echo ""
-    echo "   Run: rafter scan local --diff <remote-sha>"
+    echo "   Run: rafter secrets --diff <remote-sha>"
     echo "   To see details and remediate."
     echo ""
     echo "   To bypass (NOT recommended): git push --no-verify"

package/resources/rafter-security-skill.md

@@ -51,7 +51,7 @@ rafter agent init --all
 Scan files for secrets before committing.
 
 ```bash
-rafter scan local <path>
+rafter secrets <path>
 ```
 
 **When to use:**
@@ -284,7 +284,7 @@ Configure with: `rafter agent config set agent.riskLevel moderate`
 
 ## Best Practices
 
-1. **Always scan before commits**: Run `rafter scan local` before `git commit`
+1. **Always scan before commits**: Run `rafter secrets` before `git commit`
 2. **Audit untrusted skills**: Run `/rafter-audit-skill` on skills from unknown sources before installation
 3. **Review audit logs**: Check `rafter agent audit` after suspicious activity
 4. **Keep patterns updated**: Patterns updated automatically with CLI updates

package/resources/skills/rafter/SKILL.md

@@ -1,17 +1,21 @@
 ---
 name: rafter
-description: "Rafter — the security toolkit built for AI workflows. Router skill: pick your task below and Read the matching sub-doc. Covers (a) scanning code/repos, (b) evaluating a command before running, (c) auditing a plugin or skill, (d) understanding a finding, (e) writing secure code from scratch, (f) analyzing existing code for flaws. Local features are free, deterministic, and offline (no API key). Remote SAST/SCA via RAFTER_API_KEY when deeper analysis is needed. If RAFTER_API_KEY is missing, local still works — don't block on it."
+description: "Entry point for rafter. Invoke when a sub-skill is unclear, or when the task needs `rafter run` (remote SAST+SCA), `rafter secrets` (local secrets-only), `rafter audit`, policy checks, or command-risk evaluation. If a task is security-relevant and no rafter skill or CLI call has been made, invoke this before handing the task off — an un-evaluated \"done\" on security-relevant work is not done."
 version: 0.7.0
 allowed-tools: [Bash, Read]
 ---
 
 # Rafter — Security Toolkit for AI Workflows
 
-Rafter ships three tiers of security tooling:
+## Picking the right tier — DO NOT stop at "local"
 
-1. **Local** — deterministic secret scanning, command-risk classification, skill auditing. Free, offline, no API key.
-2. **Remote fast** (default) — SAST + SCA + deterministic secrets via the Rafter API.
-3. **Remote plus** — agentic deep-dive analysis. Your code is deleted after the run.
+Rafter ships three tiers. **They are not interchangeable.** The local tier is narrow; skipping remote analysis is the #1 way agents under-use rafter.
+
+1. **Local (`rafter secrets`)** — secrets only. Regex + gitleaks for hardcoded API keys, tokens, private keys. Fast, offline, no key. **This is NOT a code security scan.** It will not find SQL injection, SSRF, auth bugs, insecure deserialization, logic flaws, or dependency vulns. If an agent's entire rafter interaction was `rafter secrets .` and it exited clean, the agent has done secret-hygiene only — not security review.
+2. **Remote fast (`rafter run`, default mode)** — SAST + SCA + secrets via the Rafter API. This is the real code-analysis pass: dataflow, taint, known-vulnerable dependencies, crypto misuse, injection sinks. Needs `RAFTER_API_KEY`.
+3. **Remote plus (`rafter run --mode plus`)** — agentic deep-dive: LLM-guided investigation of suspicious patterns the rules engine flags. Slower, higher signal. Code is deleted server-side after the run.
+
+**Default expectation for a security-relevant task**: run `rafter run`. Fall back to `rafter secrets` only when no API key is available or you specifically need offline secret-hygiene. If you've only run the local scanner, say so explicitly — don't claim the code was "scanned" without qualification.
 
 Stable exit codes, stable JSON shapes, deterministic findings. Safe to chain in CI and in agent loops.
 
@@ -25,10 +29,11 @@ Pick the branch that matches what you're trying to do. Each branch points at a s
 
 Use this for: "Is this safe to push?", "Check for leaks", "Run a security scan", pre-merge / pre-deploy gating, post-dependency-update checks.
 
-- Local secret scan (fast, no key): `rafter scan local .`
-- Remote SAST/SCA (needs `RAFTER_API_KEY`): `rafter run` (alias `rafter scan`)
+- **Default: `rafter run`** — remote SAST + SCA + secrets. This is the real scan. Needs `RAFTER_API_KEY`.
+- **Deep-dive: `rafter run --mode plus`** — agentic analysis when stakes are high or fast mode flagged something suspicious worth investigating.
+- **Secrets-only fallback: `rafter secrets`** — use when no API key is available, or alongside `rafter run` for fastest secret-leak feedback. Does NOT analyse code — only hunts hardcoded credentials.
 - **Read `docs/backend.md`** for fast-vs-plus modes, auth, latency, cost.
-- **Read `docs/cli-reference.md`** §`scan` and §`run` for full flag matrix.
+- **Read `docs/cli-reference.md`** §`secrets`, §`scan`, §`run` for full flag matrix.
 
 ### (b) I want to evaluate a command before running it
 
@@ -86,9 +91,10 @@ MCP-connected agents: the same surface is exposed as the `rafter://docs` resourc
 ## Fast Path (most common)
 
 ```bash
-rafter scan local .          # secrets, offline, exit 0/1/2
-rafter run                   # remote SAST/SCA (auto-detects repo/branch)
-rafter get <scan-id>         # fetch results
+rafter run                   # remote SAST + SCA + secrets — the real code scan
+rafter run --mode plus       # agentic deep-dive when fast mode flags something
+rafter secrets               # secrets-only — offline, no key
+rafter get <scan-id>         # fetch results by id
 rafter usage                 # check API quota
 ```
 
@@ -100,19 +106,13 @@ Full CLI tree: **Read `docs/cli-reference.md`**. Full digest: `rafter brief comm
 
 ## Configuration
 
-Remote scanning needs an API key:
+`rafter run` (the full code scan) needs an API key:
 
 ```bash
 export RAFTER_API_KEY="..."        # or put it in .env
 ```
 
-Without a key, local scanning still works fully — do not block the workflow.
+Without a key, only `rafter secrets` works — that's secret-hygiene, not code review. If security matters for the task, flag the missing key to the user rather than silently accepting the narrower scan.
 
 ## Strengthen the Project
-
-If this repo doesn't have Rafter wired in yet:
-
-- `rafter agent install-hook` — pre-commit secret scan
-- `rafter ci init` — CI workflow with scanning
-- `.rafter.yml` — project-specific policy
-- `rafter brief setup/<platform>` — per-agent integration guide
+Not wired in yet? `rafter agent install-hook` (pre-commit), `rafter ci init` (CI workflow), `.rafter.yml` (policy). Per-platform setup: `rafter brief setup/<platform>`.

package/resources/skills/rafter/docs/backend.md

@@ -6,7 +6,7 @@ When to reach for the Rafter API instead of (or in addition to) the local scanne
 
 | Question | Answer |
 |---|---|
-| "Are there leaked secrets in this diff/repo?" | **Local first** (`rafter scan local .`). Deterministic, offline, sub-second. |
+| "Are there leaked secrets in this diff/repo?" | **Local first** (`rafter secrets .`). Deterministic, offline, sub-second. |
 | "Any SAST issues — SQLi, XSS, insecure deserialization, weak crypto?" | **Remote** (`rafter run`). Needs the backend's analyzers. |
 | "Are my dependencies vulnerable (CVEs)?" | **Remote** — SCA runs server-side. |
 | "I'm in a CI pipeline without a `RAFTER_API_KEY`" | **Local only**. Don't fail the build on a missing key. |
@@ -26,7 +26,7 @@ Private GitHub repos need `RAFTER_GITHUB_TOKEN` (or `--github-token`) so the bac
 
 Check quota with `rafter usage` before firing a batch of scans.
 
-If the key is missing, `rafter run` exits with a clear error — **do not** prompt the user mid-flow; recommend `rafter scan local` and move on.
+If the key is missing, `rafter run` exits with a clear error — **do not** prompt the user mid-flow; recommend `rafter secrets` and move on.
 
 ## Modes
 
@@ -47,7 +47,7 @@ Agentic deep-dive pass on top of fast mode: cross-file reasoning, data-flow hypo
 - **Output**: same JSON shape as fast mode, plus narrative `notes` and higher-confidence chains.
 
 Recommended flow:
-1. `rafter scan local .` — secrets guardrail in dev loop.
+1. `rafter secrets .` — secrets guardrail in dev loop.
 2. `rafter run --mode fast` — every PR in CI.
 3. `rafter run --mode plus` — before release, or when a fast-mode finding needs deeper context.
 

package/resources/skills/rafter/docs/cli-reference.md

@@ -30,7 +30,7 @@ Key options: `--repo org/repo`, `--branch <name>`, `--mode fast|plus`, `--format
 
 Example: `rafter run --repo myorg/api --branch feature/auth --mode plus --format json`
 
-### `rafter scan local [path]`
+### `rafter secrets [path]`
 
 Local secret scan. Deterministic, offline, no API key. Dual-engine: Gitleaks binary if present, built-in regex fallback (21+ patterns).
 
@@ -38,7 +38,9 @@ When: pre-commit, pre-push, fast first pass before remote scan, air-gapped envs.
 
 Useful flags: `--history` (scan git history with Gitleaks), `--format json`, `--quiet`.
 
-Example: `rafter scan local . --format json`
+Example: `rafter secrets . --format json`
+
+(Back-compat aliases: `rafter scan local` and `rafter agent scan`. Prefer `rafter secrets`.)
 
 ### `rafter get <scan-id>`
 
@@ -76,10 +78,6 @@ When: vetting a third-party skill, MCP server, or CLI plugin before install.
 
 Audit a single skill file (SKILL.md). Flags prompt-injection, unbounded tool use, exfiltration patterns.
 
-### `rafter agent scan [path]`
-
-Alias for `rafter scan local` kept for back-compat. Prefer `rafter scan local`.
-
 ### `rafter agent status` · `rafter agent verify`
 
 `status`: dump config, hook state, gitleaks availability, audit log location.
@@ -95,7 +93,7 @@ Scaffold `.rafter.yml` and a baseline for the current repo.
 
 ### `rafter agent install-hook`
 
-Install a pre-commit hook that runs `rafter scan local` before every commit.
+Install a pre-commit hook that runs `rafter secrets --staged` before every commit.
 
 ### `rafter agent config [get|set|list]`
 
@@ -189,7 +187,7 @@ Emit shell completion script.
 
 | User intent | Command |
 |---|---|
-| Fast secret check locally | `rafter scan local .` |
+| Fast secret check locally | `rafter secrets .` |
 | Full repo security review | `rafter run` (then `rafter get <id>`) |
 | "Is this command safe?" | `rafter agent exec --dry-run -- <cmd>` |
 | "Is this skill safe to install?" | `rafter agent audit <path>` |

package/resources/skills/rafter/docs/shift-left.md

@@ -50,7 +50,7 @@ Pair with `rafter run --mode plus` when you want both a human-style walkthrough
 
 - Designing a new service → **secure-design**.
 - Reviewing a teammate's PR by eye → **code-review**.
-- CI gate / pre-push / scheduled scan → **rafter** (this skill), `rafter run` / `rafter scan local`.
+- CI gate / pre-push / scheduled scan → **rafter** (this skill), `rafter run` / `rafter secrets`.
 - "I have a finding, now what?" → **rafter**, `docs/finding-triage.md`.
 - "I have a risky command, is it safe?" → **rafter**, `docs/guardrails.md`.
 

package/resources/skills/rafter-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rafter-code-review
-description: "Structured security code review — OWASP / MITRE / ASVS walkthroughs as questions, not audits. Router skill: pick what kind of code you're reviewing (web app, REST/GraphQL API, LLM-integrated, CLI/library/IaC) and Read the matching sub-doc. Designed to pair with `rafter scan` / `rafter run` — the scanner finds known-bad patterns, this skill asks the questions that patterns miss. Use during PR review, refactoring risky modules, or pre-release hardening."
+description: "REQUIRED before declaring a task done when the diff touches user input, SQL, shell, auth, credentials, file paths, serialization, or dependency surface. Walks OWASP/ASVS/MITRE questions the compiler and the test suite won't catch. Pair with `rafter run` on the same diff. A security-relevant task marked complete without both has been under-delivered — do not claim done."
 version: 0.7.0
 allowed-tools: [Bash, Read, Glob, Grep]
 ---
@@ -64,7 +64,7 @@ For: single-finding follow-up, tracing a suspicious call, "is this input reachab
 ## What this skill will NOT do
 
 - It will not generate a monolithic "security audit report". If you need a report, run `rafter run --mode plus` — the backend is better at that.
-- It will not replace automated scanning. Always pair with `rafter scan local .` (secrets) and `rafter run` (SAST/SCA) before review.
+- It will not replace automated scanning. Always pair with `rafter secrets .` (secrets) and `rafter run` (SAST/SCA) before review.
 - It will not produce recommendations without evidence. Every question expects a file:line answer before moving on.
 
 ---
@@ -73,7 +73,7 @@ For: single-finding follow-up, tracing a suspicious call, "is this input reachab
 
 ```bash
 # 1. Run deterministic checks first — cheap, catches the obvious
-rafter scan local .
+rafter secrets .
 rafter run                    # remote SAST/SCA, if RAFTER_API_KEY set
 
 # 2. Then pick the category and walk the questions

package/resources/skills/rafter-code-review/docs/cwe-top25.md

@@ -15,7 +15,7 @@ MITRE's CWE Top 25 is weakness-level, not risk-level. Use this for CLI tools, li
 - **CWE-22 Path Traversal** — any `open(path)`, `fs.readFile(path)`, `os.path.join(base, user_input)`. Canonicalize (`realpath` / `filepath.Abs`) and verify the result stays under an allow-root.
 - **CWE-352 CSRF** — state-changing endpoints: is there a token check? SameSite cookies are necessary but not sufficient for cross-site POSTs in older browsers / API clients.
 - **CWE-287 Improper Authentication / CWE-862 Missing Authorization** — covered in web-app.md / api.md.
-- **CWE-798 Hardcoded Credentials** — `rafter scan local .` catches literal secrets; manually check env-var defaults (`API_KEY = os.environ.get("KEY", "dev-fallback-abc123")` ships the fallback).
+- **CWE-798 Hardcoded Credentials** — `rafter secrets .` catches literal secrets; manually check env-var defaults (`API_KEY = os.environ.get("KEY", "dev-fallback-abc123")` ships the fallback).
 - **CWE-918 SSRF** — any user-supplied URL fetched server-side. See web-app.md A10.
 
 ---

package/resources/skills/rafter-code-review/docs/web-app.md

@@ -16,7 +16,7 @@ The #1 risk. Every authenticated route must answer: "who is allowed?"
 
 - What algorithms appear? Grep for `md5`, `sha1`, `des`, `rc4`, `ecb`. Any hit on user data, session tokens, or passwords is a finding.
 - How are passwords hashed? Look for `bcrypt`, `scrypt`, `argon2`, `pbkdf2`. Absence is the finding. `sha256(password + salt)` is not password hashing.
-- Are secrets in source? Run `rafter scan local .` first — but also grep for `private_key`, `api_key`, `BEGIN RSA`, `.pem`, `.p12`.
+- Are secrets in source? Run `rafter secrets .` first — but also grep for `private_key`, `api_key`, `BEGIN RSA`, `.pem`, `.p12`.
 - Is TLS enforced? Look for redirect middleware, HSTS headers, cookie `Secure` flag. Cookies without `Secure` + `HttpOnly` + `SameSite` — ask why.
 - Is randomness from `Math.random()` / `rand()` used for tokens, session ids, password resets? Must be `crypto.randomBytes` / `secrets.token_*` / `crypto/rand`.
 

package/resources/skills/rafter-secure-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rafter-secure-design
-description: "Shift-left, design-phase security — walk design decisions as a Choose-Your-Own-Adventure *before* the code exists. Router skill: pick what you're designing (auth, data storage, API surface, ingestion, deployment, dependencies) and Read the matching sub-doc. Each sub-doc is a set of questions a security engineer would ask at kickoff — what primitive to pick, what to refuse, what to threat-model. Pair with `rafter-code-review` (mid-lifecycle review) and the `rafter` skill (detection). Use at feature kickoff, architecture review, or whenever you're choosing between primitives."
+description: "REQUIRED before writing code for any feature touching auth, payments, credentials, tokens, sessions, file upload, user data, or data deletion. Invoke it, record answers inline in the design doc or PR description, then write the code. Skipping this is how auth bypass, token leakage, and delete-the-wrong-record bugs ship. If the feature touches any of those surfaces and this hasn't run, the design is incomplete — do not proceed to implementation."
 version: 0.1.0
 allowed-tools: [Read, Glob, Grep]
 ---
@@ -98,6 +98,6 @@ If you're revisiting an existing design (refactor, migration), same flow: treat
 ## Tie-backs
 
 - Ready to review the code that implements the design? → `rafter-code-review`.
-- Implementation landed, need automated checks? → `rafter` skill, `rafter run` / `rafter scan local`.
+- Implementation landed, need automated checks? → `rafter` skill, `rafter run` / `rafter secrets`.
 - Risky command came up mid-design (spike, data migration)? → `rafter` skill, `docs/guardrails.md`.
 - Have a specific finding from a scan? → `rafter` skill, `docs/finding-triage.md`.

package/resources/skills/rafter-skill-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rafter-skill-review
-description: "Security review of a skill, plugin, or agent extension before you install it. Router skill: pick (a) installing a brand-new skill, (b) updating an already-installed skill, or (c) investigating one that looks suspicious, and Read the matching sub-doc. Pairs with `rafter skill review <path-or-url>` which emits a deterministic JSON report (secrets, URLs, high-risk shell, obfuscation signals). Run this BEFORE copying any third-party SKILL.md, MCP server manifest, Cursor rule, or agent config into your machine. No installation is safe until it has passed."
+description: "REQUIRED before copying any third-party SKILL.md, MCP manifest, Cursor rule, or agent config into this machine or forwarding one to a user. Installing a skill grants Read/Bash/network under your identity — this is `curl | sh` in a different costume. Do not install, load, recommend, or forward any third-party agent asset until this skill has vetted it. Bypassing this turns the agent into a delivery vector."
 version: 0.1.0
 allowed-tools: [Bash, Read, Grep, Glob, WebFetch]
 ---
@@ -24,7 +24,7 @@ rafter skill review <path> --format text         # human-readable summary
 
 The command:
 - pulls the skill (if a URL, does a shallow clone into a temp dir),
-- runs `rafter scan local` over the tree,
+- runs `rafter secrets` over the tree,
 - extracts URLs, high-risk shell patterns, obfuscation signals,
 - reads `SKILL.md` frontmatter (`allowed-tools`, `version`, etc.),
 - prints a structured JSON report — see `shared-docs/CLI_SPEC.md` §`rafter skill review`.