guardrails-ref 1.0.9 → 1.1.1

package/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Node: >=18](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org)
 
-CLI for [Agent Guardrails](https://github.com/9atar6/agent-guardrails) — init, add, remove, setup, validate, check, upgrade, and list GUARDRAIL.md files.
+CLI for [Agent Guardrails](https://github.com/9atar6/agent-guardrails) — init, add, remove, setup, validate, check, upgrade, list, and why GUARDRAIL.md files.
 
 ## Why?
 
@@ -16,7 +16,7 @@ AI coding agents (Cursor, Claude Code, etc.) don't remember across sessions. Gua
 npx guardrails-ref init
 ```
 
-Creates `.agents/guardrails/`, adds the `no-plaintext-secrets` example, and configures Cursor and Claude Code to read your guardrails. No global install needed.
+Creates `.agents/guardrails/`, adds the `no-plaintext-secrets` example, and configures Cursor, Claude Code, and VS Code Copilot to read your guardrails. No global install needed.
 
 > **Note:** IDEs don't yet recognize guardrails natively. The `setup` command adds a rule so the AI reads them. Once IDEs add support, this won't be needed.
 
@@ -24,19 +24,26 @@ Creates `.agents/guardrails/`, adds the `no-plaintext-secrets` example, and conf
 
 | Command | Description |
 |---------|-------------|
-| `npx guardrails-ref init [path]` | Create `.agents/guardrails/`, add no-plaintext-secrets, configure Cursor and Claude Code |
+| `npx guardrails-ref init [path]` | Create `.agents/guardrails/`, add no-plaintext-secrets, configure Cursor, Claude Code, and VS Code Copilot |
+| `npx guardrails-ref init --minimal [path]` | Create `.agents/guardrails/` only (no example, no setup) |
 | `npx guardrails-ref add <name> [name2 ...] [path]` | Add example guardrail(s) — pass multiple names to add several at once |
 | `npx guardrails-ref remove <name> [path]` | Remove a guardrail (name required) |
-| `npx guardrails-ref setup [path]` | Add the guardrail rule to Cursor rules and Claude instructions (use `--remove` to undo) |
+| `npx guardrails-ref setup [path]` | Add the guardrail rule to Cursor, Claude Code, and VS Code Copilot |
+| `npx guardrails-ref setup --remove [path]` | Remove the guardrail rule from IDE configs |
+| `npx guardrails-ref setup --ide <name> [path]` | Target IDE: `cursor`, `claude`, `copilot`, or `auto` (only configured IDEs) |
+| `npx guardrails-ref setup --dry-run [path]` | Show what would be added/removed without writing files |
+| `npx guardrails-ref setup --check [path]` | Show which IDEs are configured and whether they have the rule |
 | `npx guardrails-ref validate [path]` | Validate GUARDRAIL.md files (use `--json` for JSON, `--strict` to fail on warnings) |
 | `npx guardrails-ref check [path]` | Validate with minimal output (CI-friendly, use `--strict` to fail on warnings) |
 | `npx guardrails-ref upgrade [path]` | Update installed guardrails to latest templates (use `--dry-run` to preview, `--diff` to show changes) |
 | `npx guardrails-ref list [path]` | List discovered guardrails (use `--json` for JSON output) |
+| `npx guardrails-ref why <name>` | Show guardrail template content (e.g. `why no-destructive-commands`) |
 
 ## Supported IDEs
 
 - **Cursor** — via `.cursor/rules/` or `.cursorrules`
 - **Claude Code** — via `.claude/instructions.md`
+- **VS Code Copilot** — via `.github/copilot-instructions.md`
 
 ## CI/CD
 
@@ -54,12 +61,15 @@ Or with full output or JSON:
   run: npx guardrails-ref validate . --json
 ```
 
+**Note:** `list` exits with code 1 when no guardrails are found, so it can be used in scripts to check for guardrail presence.
+
 ## Examples
 
 ```bash
 npx guardrails-ref init
 npx guardrails-ref add no-destructive-commands no-hardcoded-urls
 npx guardrails-ref add no-new-deps-without-approval
+npx guardrails-ref why no-destructive-commands
 npx guardrails-ref validate .
 npx guardrails-ref list .
 ```
@@ -69,6 +79,9 @@ npx guardrails-ref list .
 | Name | What it prevents |
 |------|------------------|
 | `no-plaintext-secrets` | Logging or committing credentials |
+| `no-placeholder-credentials` | Fake or placeholder API keys instead of asking for real values |
+| `no-silent-error-handling` | Catching errors without surfacing them to the user |
+| `require-access-control` | Exposing sensitive data or admin actions without role checks |
 | `database-migrations` | Direct schema changes instead of migrations |
 | `no-destructive-commands` | rm -rf, DROP TABLE, TRUNCATE without approval |
 | `no-new-deps-without-approval` | New packages without approval |
@@ -77,15 +90,20 @@ npx guardrails-ref list .
 | `rate-limiting` | Runaway tool calls and API loops |
 | `no-console-in-production` | console.log in production code |
 | `require-tests` | Merging code without tests |
+| `prefer-existing-code` | Reimplementing when existing code or helpers exist |
 | `no-inline-styles` | Inline `style=` in HTML/JSX |
 | `no-raw-sql` | Raw SQL without parameterization |
 | `no-magic-numbers` | Unexplained numeric literals |
+| `no-modifying-git-history` | git push --force, destructive rebase without approval |
+| `no-deprecated-apis` | Suggesting deprecated or obsolete APIs |
+| `no-unsafe-env-assumptions` | Assuming env vars exist without validation |
+| `no-hardcoded-user-facing-strings` | Hardcoded labels, messages, errors in UI |
 
-Use `npx guardrails-ref add --list` to see all available guardrails.
+Use `npx guardrails-ref add --list` to see all available guardrails. Use `npx guardrails-ref why <name>` to show a guardrail's full content (from templates).
 
 ## Troubleshooting
 
-- **"Unknown guardrail"** — Run `npx guardrails-ref list .` to see available names
+- **"Unknown guardrail"** — Run `npx guardrails-ref add --list` to see available guardrail names
 - **Setup not working** — Try `npx guardrails-ref setup --remove` then `npx guardrails-ref setup` again
 
 ## Links

package/dist/cli.js

@@ -5,9 +5,10 @@ import { fileURLToPath } from "node:url";
 import { program } from "commander";
 import chalk from "chalk";
 import { validatePath, listGuardrails } from "./validate.js";
-import { runSetup, runSetupRemove } from "./setup.js";
+import { runSetup, runSetupRemove, runSetupCheck } from "./setup.js";
 import { runInit } from "./init.js";
 import { runAdd } from "./add.js";
+import { runWhy } from "./why.js";
 import { runRemove } from "./remove.js";
 import { runUpgrade } from "./upgrade.js";
 import { TEMPLATE_NAMES } from "./templates.js";
@@ -92,31 +93,33 @@ program
     .description("Validate GUARDRAIL.md files in a directory or a single file")
     .option("-j, --json", "Output as JSON")
     .option("-s, --strict", "Fail on warnings (CI mode)")
-    .action((path = ".", cmd) => {
-    const opts = cmd?.opts?.() ?? {};
-    runValidate(path, opts);
+    .action(function (path) {
+    const opts = this.opts();
+    runValidate(path ?? ".", opts);
 });
 program
     .command("check [path]")
     .description("Validate guardrails with minimal output (CI-friendly alias)")
     .option("-s, --strict", "Fail on warnings")
-    .action((path = ".", cmd) => {
-    const opts = cmd?.opts?.() ?? {};
-    runValidate(path, { ...opts, minimal: true });
+    .action(function (path) {
+    const opts = this.opts();
+    runValidate(path ?? ".", { ...opts, minimal: true });
 });
 program
     .command("init [path]")
     .description("Create .agents/guardrails/, add no-plaintext-secrets, and run setup (one command to get started)")
-    .action((path = ".") => {
-    runInit(path);
+    .option("-m, --minimal", "Create .agents/guardrails/ only, no example and no setup")
+    .action(function (path) {
+    const opts = this.opts();
+    runInit(path ?? ".", opts.minimal);
 });
 program
     .command("add [names...]")
     .description("Add example guardrail(s) by name — pass multiple to add several at once")
     .option("-l, --list", "List available guardrails to add")
     .option("-p, --path <path>", "Target directory", ".")
-    .action((names = [], cmd) => {
-    const opts = cmd?.opts?.() ?? {};
+    .action(function (names = []) {
+    const opts = this.opts();
     if (opts.list) {
         console.log("Available guardrails:");
         for (const n of TEMPLATE_NAMES) {
@@ -162,8 +165,8 @@ program
     .description("Update installed guardrails to latest template versions")
     .option("-n, --dry-run", "Show what would be updated without writing")
     .option("-d, --diff", "Show diff for each updated guardrail")
-    .action((path, cmd) => {
-    const opts = cmd?.opts?.() ?? {};
+    .action(function (path) {
+    const opts = this.opts();
     runUpgrade(path ?? ".", opts.dryRun, opts.diff);
 });
 program
@@ -175,27 +178,59 @@ program
 });
 program
     .command("setup [path]")
-    .description("Add the guardrail one-liner to Cursor rules and Claude instructions (required until IDEs support guardrails natively)")
-    .option("-r, --remove", "Remove the guardrail rule from Cursor and Claude config")
-    .action((path, cmd) => {
+    .description("Add the guardrail rule to Cursor, Claude Code, and VS Code Copilot (required until IDEs support guardrails natively)")
+    .option("-r, --remove", "Remove the guardrail rule from IDE configs")
+    .option("-i, --ide <name>", "Target IDE: cursor, claude, copilot, or auto (only configured IDEs)")
+    .option("-n, --dry-run", "Show what would be added/removed without writing files")
+    .option("-c, --check", "Show which IDEs are configured and whether they have the rule")
+    .action(function (path) {
     const p = path ?? ".";
-    const opts = cmd?.opts?.() ?? {};
-    const result = opts.remove ? runSetupRemove(p) : runSetup(p);
+    const opts = this.opts();
+    if (opts.check) {
+        const check = runSetupCheck(p);
+        const fmt = (name, r) => {
+            const status = !r.configured ? "not configured" : r.hasRule ? "has rule" : "no rule";
+            const color = !r.configured ? chalk.gray : r.hasRule ? chalk.green : chalk.yellow;
+            console.log(`  ${name.padEnd(12)} ${color(status)}`);
+        };
+        console.log("IDE setup status:");
+        fmt("Cursor", check.cursor);
+        fmt("Claude Code", check.claude);
+        fmt("VS Code Copilot", check.copilot);
+        return;
+    }
+    const ide = opts.ide;
+    if (ide && !["cursor", "claude", "copilot", "auto"].includes(ide)) {
+        console.error(chalk.red("Invalid --ide. Use: cursor, claude, copilot, or auto"));
+        process.exit(1);
+    }
+    const result = opts.remove
+        ? runSetupRemove(p, ide, opts.dryRun)
+        : runSetup(p, ide, opts.dryRun);
     console.log(result.message);
 });
+program
+    .command("why <name>")
+    .description("Show guardrail content (e.g. npx guardrails-ref why no-destructive-commands)")
+    .action((name) => {
+    const ok = runWhy(name);
+    process.exit(ok ? 0 : 1);
+});
 program
     .command("list [path]")
     .description("List discovered guardrails")
     .option("-j, --json", "Output as JSON")
-    .action((path = ".", cmd) => {
-    const opts = cmd?.opts?.() ?? {};
-    const guardrails = listGuardrails(path);
+    .action(function (path) {
+    const opts = this.opts();
+    const guardrails = listGuardrails(path ?? ".");
     if (opts.json) {
         console.log(JSON.stringify({ guardrails, total: guardrails.length }, null, 2));
+        process.exit(guardrails.length === 0 ? 1 : 0);
         return;
     }
     if (guardrails.length === 0) {
         console.log(chalk.yellow("No guardrails found"));
+        process.exit(1);
         return;
     }
     for (const g of guardrails) {

package/dist/init.d.ts

@@ -3,4 +3,4 @@ export interface InitResult {
     exampleCreated: boolean;
     setupDone: string;
 }
-export declare function runInit(projectPath?: string): InitResult;
+export declare function runInit(projectPath?: string, minimal?: boolean): InitResult;

package/dist/init.js

@@ -3,7 +3,7 @@ import { resolve } from "path";
 import chalk from "chalk";
 import { runSetup } from "./setup.js";
 import { TEMPLATES } from "./templates.js";
-export function runInit(projectPath = ".") {
+export function runInit(projectPath = ".", minimal = false) {
     const root = resolve(projectPath);
     const guardrailsDir = resolve(root, ".agents", "guardrails");
     const exampleDir = resolve(guardrailsDir, "no-plaintext-secrets");
@@ -13,6 +13,13 @@ export function runInit(projectPath = ".") {
         mkdirSync(guardrailsDir, { recursive: true });
         console.log(chalk.green("✓") + " Created .agents/guardrails/");
     }
+    if (minimal) {
+        return {
+            guardrailsDir,
+            exampleCreated: false,
+            setupDone: "",
+        };
+    }
     if (!existsSync(exampleFile)) {
         mkdirSync(exampleDir, { recursive: true });
         writeFileSync(exampleFile, TEMPLATES["no-plaintext-secrets"]);

package/dist/parse.js

@@ -1,6 +1,6 @@
 import matter from "gray-matter";
 import { readFileSync } from "fs";
-import { resolve } from "path";
+import { resolve, dirname, basename } from "path";
 const NAME_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const MAX_NAME_LENGTH = 64;
 const MAX_DESCRIPTION_LENGTH = 1024;
@@ -75,13 +75,12 @@ export function parseGuardrailFile(filePath) {
             warnings.push("triggers must be a list of strings");
         }
     }
-    // Check directory name matches (only when file is inside a directory)
-    const pathParts = filePath.split(/[/\\]/);
-    if (pathParts.length > 1) {
-        const dirName = pathParts.slice(-2)[0];
-        if (dirName && dirName !== "." && typeof name === "string" && name !== dirName) {
-            warnings.push(`name "${name}" does not match parent directory "${dirName}"`);
-        }
+    // Check directory name matches (only when file is GUARDRAIL.md inside a directory, not GUARDRAILS.md at root)
+    const parentDir = dirname(filePath);
+    const dirName = basename(parentDir);
+    const fileName = basename(filePath);
+    if (fileName === "GUARDRAIL.md" && dirName && dirName !== "." && typeof name === "string" && name !== dirName) {
+        warnings.push(`name "${name}" does not match parent directory "${dirName}"`);
     }
     if (errors.length > 0) {
         return {

package/dist/setup.d.ts

@@ -1,7 +1,27 @@
+export type IdeName = "cursor" | "claude" | "copilot";
 export interface SetupResult {
     cursor: boolean;
     claude: boolean;
+    copilot: boolean;
     message: string;
 }
-export declare function runSetup(projectPath?: string): SetupResult;
-export declare function runSetupRemove(projectPath?: string): SetupResult;
+export interface SetupCheckResult {
+    cursor: {
+        configured: boolean;
+        hasRule: boolean;
+    };
+    claude: {
+        configured: boolean;
+        hasRule: boolean;
+    };
+    copilot: {
+        configured: boolean;
+        hasRule: boolean;
+    };
+}
+/**
+ * Check which IDEs are configured and whether they have the guardrail rule.
+ */
+export declare function runSetupCheck(projectPath?: string): SetupCheckResult;
+export declare function runSetup(projectPath?: string, ideFilter?: IdeName | "all" | "auto", dryRun?: boolean): SetupResult;
+export declare function runSetupRemove(projectPath?: string, ideFilter?: IdeName | "all" | "auto", dryRun?: boolean): SetupResult;

package/dist/setup.js

@@ -3,6 +3,10 @@ import { resolve } from "path";
 import chalk from "chalk";
 const GUARDRAIL_RULE = "You MUST read and follow all constraints in .agents/guardrails/. Never violate a guardrail without explicit human approval.";
 const GUARDRAIL_RULE_MARKER = "You MUST read and follow all constraints in .agents/guardrails";
+/**
+ * Removes the guardrail rule from file content.
+ * When the resulting content is empty, the caller may delete the file (e.g. .cursorrules, .claude/instructions.md).
+ */
 function removeRuleFromContent(content) {
     const lines = content.split("\n").filter((line) => !line.includes(GUARDRAIL_RULE_MARKER));
     return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
@@ -10,11 +14,7 @@ function removeRuleFromContent(content) {
 function hasRule(content) {
     return content.includes(GUARDRAIL_RULE_MARKER);
 }
-export function runSetup(projectPath = ".") {
-    const root = resolve(projectPath);
-    let cursorDone = false;
-    let claudeDone = false;
-    // Cursor: .cursor/rules/agent-guardrails.md (preferred) or .cursorrules (legacy)
+function setupCursor(root) {
     const cursorRulesDir = resolve(root, ".cursor", "rules");
     const cursorRuleFile = resolve(cursorRulesDir, "agent-guardrails.md");
     const cursorRuleContent = `---
@@ -29,27 +29,27 @@ ${GUARDRAIL_RULE}
         const existing = readFileSync(cursorRuleFile, "utf-8");
         if (!hasRule(existing)) {
             writeFileSync(cursorRuleFile, cursorRuleContent);
-            cursorDone = true;
+            return true;
         }
     }
     else if (existsSync(cursorrulesPath)) {
-        // Legacy: append to .cursorrules
         const existing = readFileSync(cursorrulesPath, "utf-8");
         if (!hasRule(existing)) {
             const appended = existing.trimEnd() + "\n\n" + GUARDRAIL_RULE + "\n";
             writeFileSync(cursorrulesPath, appended);
-            cursorDone = true;
+            return true;
         }
     }
     else {
-        // Create .cursor/rules/agent-guardrails.md
         if (!existsSync(cursorRulesDir)) {
             mkdirSync(cursorRulesDir, { recursive: true });
         }
         writeFileSync(cursorRuleFile, cursorRuleContent);
-        cursorDone = true;
+        return true;
     }
-    // Claude Code: .claude/instructions.md
+    return false;
+}
+function setupClaude(root) {
     const claudeDir = resolve(root, ".claude");
     const claudeInstructions = resolve(claudeDir, "instructions.md");
     if (existsSync(claudeInstructions)) {
@@ -57,7 +57,7 @@ ${GUARDRAIL_RULE}
         if (!hasRule(existing)) {
             const appended = existing.trimEnd() + "\n\n" + GUARDRAIL_RULE + "\n";
             writeFileSync(claudeInstructions, appended);
-            claudeDone = true;
+            return true;
         }
     }
     else {
@@ -65,35 +65,39 @@ ${GUARDRAIL_RULE}
             mkdirSync(claudeDir, { recursive: true });
         }
         writeFileSync(claudeInstructions, GUARDRAIL_RULE + "\n");
-        claudeDone = true;
-    }
-    const messages = [];
-    if (cursorDone) {
-        messages.push(chalk.green("✓") + " Added guardrail rule for Cursor");
+        return true;
     }
-    if (claudeDone) {
-        messages.push(chalk.green("✓") + " Added guardrail rule for Claude Code");
+    return false;
+}
+function setupCopilot(root) {
+    const githubDir = resolve(root, ".github");
+    const copilotFile = resolve(githubDir, "copilot-instructions.md");
+    const ruleBlock = `\n\n${GUARDRAIL_RULE}\n`;
+    if (existsSync(copilotFile)) {
+        const existing = readFileSync(copilotFile, "utf-8");
+        if (!hasRule(existing)) {
+            const appended = existing.trimEnd() + ruleBlock;
+            writeFileSync(copilotFile, appended);
+            return true;
+        }
     }
-    if (messages.length === 0) {
-        messages.push(chalk.yellow("Guardrail rule already present in all config files."));
+    else {
+        if (!existsSync(githubDir)) {
+            mkdirSync(githubDir, { recursive: true });
+        }
+        writeFileSync(copilotFile, GUARDRAIL_RULE + "\n");
+        return true;
     }
-    return {
-        cursor: cursorDone,
-        claude: claudeDone,
-        message: messages.join("\n"),
-    };
+    return false;
 }
-export function runSetupRemove(projectPath = ".") {
-    const root = resolve(projectPath);
-    let cursorDone = false;
-    let claudeDone = false;
+function removeCursor(root) {
     const cursorRulesDir = resolve(root, ".cursor", "rules");
     const cursorRuleFile = resolve(cursorRulesDir, "agent-guardrails.md");
     const cursorrulesPath = resolve(root, ".cursorrules");
-    const claudeInstructions = resolve(root, ".claude", "instructions.md");
+    let done = false;
     if (existsSync(cursorRuleFile)) {
         rmSync(cursorRuleFile);
-        cursorDone = true;
+        done = true;
     }
     if (existsSync(cursorrulesPath)) {
         const existing = readFileSync(cursorrulesPath, "utf-8");
@@ -105,9 +109,13 @@ export function runSetupRemove(projectPath = ".") {
             else {
                 rmSync(cursorrulesPath);
             }
-            cursorDone = true;
+            done = true;
         }
     }
+    return done;
+}
+function removeClaude(root) {
+    const claudeInstructions = resolve(root, ".claude", "instructions.md");
     if (existsSync(claudeInstructions)) {
         const existing = readFileSync(claudeInstructions, "utf-8");
         if (hasRule(existing)) {
@@ -118,22 +126,219 @@ export function runSetupRemove(projectPath = ".") {
             else {
                 rmSync(claudeInstructions);
             }
-            claudeDone = true;
+            return true;
+        }
+    }
+    return false;
+}
+function removeCopilot(root) {
+    const copilotFile = resolve(root, ".github", "copilot-instructions.md");
+    if (existsSync(copilotFile)) {
+        const existing = readFileSync(copilotFile, "utf-8");
+        if (hasRule(existing)) {
+            const cleaned = removeRuleFromContent(existing);
+            if (cleaned) {
+                writeFileSync(copilotFile, cleaned + "\n");
+            }
+            else {
+                rmSync(copilotFile);
+            }
+            return true;
+        }
+    }
+    return false;
+}
+function checkCursor(root) {
+    const cursorRuleFile = resolve(root, ".cursor", "rules", "agent-guardrails.md");
+    const cursorrulesPath = resolve(root, ".cursorrules");
+    if (existsSync(cursorRuleFile)) {
+        const content = readFileSync(cursorRuleFile, "utf-8");
+        return { configured: true, hasRule: hasRule(content) };
+    }
+    if (existsSync(cursorrulesPath)) {
+        const content = readFileSync(cursorrulesPath, "utf-8");
+        return { configured: true, hasRule: hasRule(content) };
+    }
+    return { configured: false, hasRule: false };
+}
+function checkClaude(root) {
+    const claudeInstructions = resolve(root, ".claude", "instructions.md");
+    if (existsSync(claudeInstructions)) {
+        const content = readFileSync(claudeInstructions, "utf-8");
+        return { configured: true, hasRule: hasRule(content) };
+    }
+    return { configured: false, hasRule: false };
+}
+function checkCopilot(root) {
+    const copilotFile = resolve(root, ".github", "copilot-instructions.md");
+    if (existsSync(copilotFile)) {
+        const content = readFileSync(copilotFile, "utf-8");
+        return { configured: true, hasRule: hasRule(content) };
+    }
+    return { configured: false, hasRule: false };
+}
+/**
+ * Check which IDEs are configured and whether they have the guardrail rule.
+ */
+export function runSetupCheck(projectPath = ".") {
+    const root = resolve(projectPath);
+    return {
+        cursor: checkCursor(root),
+        claude: checkClaude(root),
+        copilot: checkCopilot(root),
+    };
+}
+function wouldSetupCursor(root) {
+    const cursorRuleFile = resolve(root, ".cursor", "rules", "agent-guardrails.md");
+    const cursorrulesPath = resolve(root, ".cursorrules");
+    if (existsSync(cursorRuleFile))
+        return !hasRule(readFileSync(cursorRuleFile, "utf-8"));
+    if (existsSync(cursorrulesPath))
+        return !hasRule(readFileSync(cursorrulesPath, "utf-8"));
+    return true;
+}
+function wouldSetupClaude(root) {
+    const claudeInstructions = resolve(root, ".claude", "instructions.md");
+    if (existsSync(claudeInstructions))
+        return !hasRule(readFileSync(claudeInstructions, "utf-8"));
+    return true;
+}
+function wouldSetupCopilot(root) {
+    const copilotFile = resolve(root, ".github", "copilot-instructions.md");
+    if (existsSync(copilotFile))
+        return !hasRule(readFileSync(copilotFile, "utf-8"));
+    return true;
+}
+function wouldRemoveCursor(root) {
+    const cursorRuleFile = resolve(root, ".cursor", "rules", "agent-guardrails.md");
+    const cursorrulesPath = resolve(root, ".cursorrules");
+    if (existsSync(cursorRuleFile))
+        return true;
+    if (existsSync(cursorrulesPath))
+        return hasRule(readFileSync(cursorrulesPath, "utf-8"));
+    return false;
+}
+function wouldRemoveClaude(root) {
+    const claudeInstructions = resolve(root, ".claude", "instructions.md");
+    return existsSync(claudeInstructions) && hasRule(readFileSync(claudeInstructions, "utf-8"));
+}
+function wouldRemoveCopilot(root) {
+    const copilotFile = resolve(root, ".github", "copilot-instructions.md");
+    return existsSync(copilotFile) && hasRule(readFileSync(copilotFile, "utf-8"));
+}
+export function runSetup(projectPath = ".", ideFilter, dryRun = false) {
+    const root = resolve(projectPath);
+    let ides;
+    if (ideFilter === "auto") {
+        const check = runSetupCheck(root);
+        ides = ["cursor", "claude", "copilot"].filter((ide) => check[ide].configured);
+    }
+    else if (ideFilter && ideFilter !== "all") {
+        ides = [ideFilter];
+    }
+    else {
+        ides = ["cursor", "claude", "copilot"];
+    }
+    let cursorDone = false;
+    let claudeDone = false;
+    let copilotDone = false;
+    if (dryRun) {
+        if (ides.includes("cursor"))
+            cursorDone = wouldSetupCursor(root);
+        if (ides.includes("claude"))
+            claudeDone = wouldSetupClaude(root);
+        if (ides.includes("copilot"))
+            copilotDone = wouldSetupCopilot(root);
+        const messages = [];
+        if (cursorDone)
+            messages.push(chalk.gray("[dry-run] Would add guardrail rule for Cursor"));
+        if (claudeDone)
+            messages.push(chalk.gray("[dry-run] Would add guardrail rule for Claude Code"));
+        if (copilotDone)
+            messages.push(chalk.gray("[dry-run] Would add guardrail rule for VS Code Copilot"));
+        if (messages.length === 0) {
+            messages.push(chalk.yellow("Guardrail rule already present in all target IDEs. Nothing to do."));
         }
+        return { cursor: cursorDone, claude: claudeDone, copilot: copilotDone, message: messages.join("\n") };
     }
+    if (ides.includes("cursor"))
+        cursorDone = setupCursor(root);
+    if (ides.includes("claude"))
+        claudeDone = setupClaude(root);
+    if (ides.includes("copilot"))
+        copilotDone = setupCopilot(root);
     const messages = [];
-    if (cursorDone) {
-        messages.push(chalk.green("✓") + " Removed guardrail rule from Cursor");
+    if (cursorDone)
+        messages.push(chalk.green("✓") + " Added guardrail rule for Cursor");
+    if (claudeDone)
+        messages.push(chalk.green("✓") + " Added guardrail rule for Claude Code");
+    if (copilotDone)
+        messages.push(chalk.green("✓") + " Added guardrail rule for VS Code Copilot");
+    if (messages.length === 0) {
+        messages.push(chalk.yellow("Guardrail rule already present in all configured IDEs."));
     }
-    if (claudeDone) {
-        messages.push(chalk.green("✓") + " Removed guardrail rule from Claude Code");
+    return {
+        cursor: cursorDone,
+        claude: claudeDone,
+        copilot: copilotDone,
+        message: messages.join("\n"),
+    };
+}
+export function runSetupRemove(projectPath = ".", ideFilter, dryRun = false) {
+    const root = resolve(projectPath);
+    let ides;
+    if (ideFilter === "auto") {
+        const check = runSetupCheck(root);
+        ides = ["cursor", "claude", "copilot"].filter((ide) => check[ide].hasRule);
+    }
+    else if (ideFilter && ideFilter !== "all") {
+        ides = [ideFilter];
+    }
+    else {
+        ides = ["cursor", "claude", "copilot"];
     }
+    let cursorDone = false;
+    let claudeDone = false;
+    let copilotDone = false;
+    if (dryRun) {
+        if (ides.includes("cursor"))
+            cursorDone = wouldRemoveCursor(root);
+        if (ides.includes("claude"))
+            claudeDone = wouldRemoveClaude(root);
+        if (ides.includes("copilot"))
+            copilotDone = wouldRemoveCopilot(root);
+        const messages = [];
+        if (cursorDone)
+            messages.push(chalk.gray("[dry-run] Would remove guardrail rule from Cursor"));
+        if (claudeDone)
+            messages.push(chalk.gray("[dry-run] Would remove guardrail rule from Claude Code"));
+        if (copilotDone)
+            messages.push(chalk.gray("[dry-run] Would remove guardrail rule from VS Code Copilot"));
+        if (messages.length === 0) {
+            messages.push(chalk.yellow("Guardrail rule not found in any config files. Nothing to do."));
+        }
+        return { cursor: cursorDone, claude: claudeDone, copilot: copilotDone, message: messages.join("\n") };
+    }
+    if (ides.includes("cursor"))
+        cursorDone = removeCursor(root);
+    if (ides.includes("claude"))
+        claudeDone = removeClaude(root);
+    if (ides.includes("copilot"))
+        copilotDone = removeCopilot(root);
+    const messages = [];
+    if (cursorDone)
+        messages.push(chalk.green("✓") + " Removed guardrail rule from Cursor");
+    if (claudeDone)
+        messages.push(chalk.green("✓") + " Removed guardrail rule from Claude Code");
+    if (copilotDone)
+        messages.push(chalk.green("✓") + " Removed guardrail rule from VS Code Copilot");
     if (messages.length === 0) {
         messages.push(chalk.yellow("Guardrail rule not found in any config files."));
     }
     return {
         cursor: cursorDone,
         claude: claudeDone,
+        copilot: copilotDone,
         message: messages.join("\n"),
     };
 }

package/dist/why.d.ts

@@ -0,0 +1 @@
+export declare function runWhy(name: string): boolean;

package/dist/why.js

@@ -0,0 +1,13 @@
+import chalk from "chalk";
+import { TEMPLATES, TEMPLATE_NAMES } from "./templates.js";
+export function runWhy(name) {
+    const normalized = name.toLowerCase().replace(/\s+/g, "-");
+    const content = TEMPLATES[normalized];
+    if (!content) {
+        console.error(chalk.red("Unknown guardrail:") + " " + name);
+        console.error(chalk.gray("Available: " + TEMPLATE_NAMES.join(", ")));
+        return false;
+    }
+    console.log(content);
+    return true;
+}

package/examples/README.md

@@ -1,10 +1,13 @@
 # Example Guardrails
 
-Reference guardrails you can add with `npx guardrails-ref add <name>`.
+Reference guardrails you can add with `npx guardrails-ref add <name>`. Use `npx guardrails-ref why <name>` to show a guardrail's full content.
 
 | Name | What it prevents |
 |------|------------------|
 | `no-plaintext-secrets` | Logging or committing API keys, passwords, tokens |
+| `no-placeholder-credentials` | Fake or placeholder API keys instead of asking for real values |
+| `no-silent-error-handling` | Catching errors without surfacing them to the user |
+| `require-access-control` | Exposing sensitive data or admin actions without role checks |
 | `database-migrations` | Direct schema changes instead of migrations |
 | `no-destructive-commands` | `rm -rf`, `DROP TABLE`, `TRUNCATE` without approval |
 | `no-new-deps-without-approval` | New packages without human confirmation |
@@ -13,8 +16,13 @@ Reference guardrails you can add with `npx guardrails-ref add <name>`.
 | `rate-limiting` | Runaway tool calls and API loops |
 | `no-console-in-production` | `console.log` in production code |
 | `require-tests` | Merging code without tests |
+| `prefer-existing-code` | Reimplementing when existing code or helpers exist |
 | `no-inline-styles` | Inline `style=` in HTML/JSX |
 | `no-raw-sql` | Raw SQL without parameterization |
 | `no-magic-numbers` | Unexplained numeric literals |
+| `no-modifying-git-history` | `git push --force`, destructive rebase without approval |
+| `no-deprecated-apis` | Suggesting deprecated or obsolete APIs |
+| `no-unsafe-env-assumptions` | Assuming env vars exist without validation |
+| `no-hardcoded-user-facing-strings` | Hardcoded labels, messages, errors in UI |
 
 Each example lives in its own directory with a `GUARDRAIL.md` file. See `pre-commit/README.md` for pre-commit, Husky, or npm script setup. See the [specification](../spec/specification.md) for the format.

package/examples/no-deprecated-apis/GUARDRAIL.md

@@ -0,0 +1,35 @@
+---
+name: no-deprecated-apis
+description: Never suggest deprecated or obsolete APIs. Check package docs and current best practices before recommending patterns. Apply when adding dependencies, using libraries, or implementing features.
+scope: project
+severity: warning
+triggers:
+  - "Adding dependencies"
+  - "Using library"
+  - "API usage"
+  - "Implementing feature"
+  - "Package documentation"
+  - "Deprecated"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Deprecated APIs
+
+## Trigger
+Adding dependencies, using libraries, implementing features, or recommending APIs or patterns.
+
+## Instruction
+- Never suggest deprecated or obsolete APIs; check the package's current documentation first
+- When a pattern might be deprecated: verify against the latest docs before recommending
+- Prefer current, maintained approaches over legacy patterns (e.g. fetch over XMLHttpRequest, modern Node APIs over legacy callbacks)
+- If the project uses a specific version: ensure recommendations match that version's API
+- When unsure about deprecation status: note the uncertainty and suggest verifying in docs
+
+## Reason
+Agents often suggest outdated patterns from training data. Deprecated APIs may be removed in future versions and can cause technical debt. Current docs are the source of truth.
+
+## Provenance
+Manual addition, agent-guardrails reference.

package/examples/no-hardcoded-urls/GUARDRAIL.md

@@ -30,3 +30,6 @@ Adding API calls, integrating external services, or referencing URLs (base URLs,
 
 ## Reason
 Hardcoded URLs break across environments (dev/staging/prod), leak internal endpoints, and block easy configuration. Environment-based config is standard practice.
+
+## Provenance
+Manual addition, agent-guardrails reference.

package/examples/no-hardcoded-user-facing-strings/GUARDRAIL.md

@@ -0,0 +1,35 @@
+---
+name: no-hardcoded-user-facing-strings
+description: Never hardcode user-facing text (labels, messages, errors) in components or views. Use i18n keys, translation files, or shared constants. Apply when adding UI text, error messages, or form labels.
+scope: project
+severity: warning
+triggers:
+  - "Adding UI text"
+  - "Error messages"
+  - "Form labels"
+  - "User-facing strings"
+  - "Button text"
+  - "Placeholders"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Hardcoded User-Facing Strings
+
+## Trigger
+Adding user-facing text: labels, buttons, error messages, placeholders, tooltips, or any string displayed to the user in the UI.
+
+## Instruction
+- Never hardcode user-facing strings directly in components or views
+- Use i18n/translation keys (e.g. t('errors.network'), i18n.t('submit')) when the project has i18n
+- If no i18n: use shared constants or a strings module (e.g. STRINGS.ERROR_NETWORK) for reuse and consistency
+- For error messages: centralize in a shared location so they can be updated and translated
+- Exception: very small projects or prototypes may use inline strings; prefer externalizing as the project grows
+
+## Reason
+Hardcoded strings scatter copy across the codebase, block localization, and make consistent messaging harder. Centralized strings enable i18n and easier content updates.
+
+## Provenance
+Manual addition, agent-guardrails reference.

package/examples/no-inline-styles/GUARDRAIL.md

@@ -24,7 +24,9 @@ Adding styles to HTML, JSX, or component markup (e.g. React, Vue, Svelte).
 - Never add inline `style={{ ... }}` or `style="..."` attributes
 - Use CSS classes, CSS modules, Tailwind, or design system tokens instead
 - For dynamic values: use CSS variables or data attributes with stylesheets
-- Inline styles bypass design systems, hurt maintainability, and complicate theming
 
 ## Reason
-Inline styles scatter styling logic, prevent reuse, and make design consistency harder. Centralized styles (CSS, design tokens) enable theming and maintainability.
+Inline styles scatter styling logic, prevent reuse, and make design consistency harder. They bypass design systems, hurt maintainability, and complicate theming. Centralized styles (CSS, design tokens) enable theming and maintainability.
+
+## Provenance
+Manual addition, agent-guardrails reference.

package/examples/no-magic-numbers/GUARDRAIL.md

@@ -29,3 +29,6 @@ Adding numeric literals for timeouts, limits, buffer sizes, retry counts, thresh
 
 ## Reason
 Magic numbers make code hard to understand and change. Named constants document intent and centralize configuration.
+
+## Provenance
+Manual addition, agent-guardrails reference.

package/examples/no-modifying-git-history/GUARDRAIL.md

@@ -0,0 +1,36 @@
+---
+name: no-modifying-git-history
+description: Never run git push --force, destructive rebase, or history-rewriting commands without explicit human approval. Apply when suggesting git commands that modify shared history.
+scope: project
+severity: critical
+triggers:
+  - "git push"
+  - "git rebase"
+  - "Force push"
+  - "Rewriting history"
+  - "git reset"
+  - "Amending commits"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Modifying Git History
+
+## Trigger
+Suggesting or running git commands that modify history: force push, rebase that rewrites commits, reset, or amending pushed commits.
+
+## Instruction
+- Never run `git push --force`, `git push -f`, or `git push --force-with-lease` without explicit human approval
+- Never run `git rebase` on branches that may have been pushed or shared without approval
+- Never run `git reset --hard` to undo commits that others may have pulled
+- When the user asks to "fix" history or "undo" pushed commits: explain the impact and wait for confirmation
+- For shared branches (main, develop): always warn that force push can overwrite others' work
+- Prefer `git revert` over history-rewriting when undoing commits on shared branches
+
+## Reason
+Agents have suggested force push and rebase that overwrote shared history, causing lost work and broken clones. History-rewriting on shared branches requires explicit human confirmation.
+
+## Provenance
+Manual addition, common failure mode in autonomous coding agents.

package/examples/no-placeholder-credentials/GUARDRAIL.md

@@ -0,0 +1,36 @@
+---
+name: no-placeholder-credentials
+description: Never use fake or placeholder API keys, env vars, or credentials. Ask for real values instead of inventing them. Apply when configuring APIs, integrations, or environment variables.
+scope: project
+severity: critical
+triggers:
+  - "API integration"
+  - "Environment variables"
+  - "API key"
+  - "Configuration"
+  - "Credentials"
+  - "Placeholder"
+  - ".env"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Placeholder Credentials
+
+## Trigger
+Configuring API integrations, environment variables, credentials, or any code that requires API keys, tokens, or secrets.
+
+## Instruction
+- Never use fake, placeholder, or invented credentials (e.g. `sk_test_placeholder`, `your-api-key-here`, `xxx`)
+- Never assume env vars exist without validation; ask the user to provide or verify values
+- When a real value is required: stop and ask the user to provide it, or add it to .env
+- Document required env vars in .env.example with placeholders for format only (e.g. `STRIPE_KEY=sk_test_...`), not for actual use
+- For local development: use real test keys when available (e.g. Stripe test mode, sandbox APIs), or explicitly ask the user
+
+## Reason
+Agents hallucinate placeholder values that appear to work but fail in production. Users assume the agent configured correctly when it did not. Always ask for real values when they are required.
+
+## Provenance
+Manual addition, common failure mode in autonomous coding agents (DAPLab).

package/examples/no-raw-sql/GUARDRAIL.md

@@ -30,3 +30,6 @@ Writing database queries, SQL statements, or any code that executes SQL against
 
 ## Reason
 Raw SQL with string concatenation leads to SQL injection. Parameterized queries prevent injection and are required for security.
+
+## Provenance
+Manual addition, SQL injection prevention.

package/examples/no-silent-error-handling/GUARDRAIL.md

@@ -0,0 +1,36 @@
+---
+name: no-silent-error-handling
+description: Never catch errors without surfacing them to the user. Avoid hiding failures in console or generic messages. Apply when adding try/catch, error handling, or API error responses.
+scope: project
+severity: critical
+triggers:
+  - "Error handling"
+  - "try/catch"
+  - "Catching exceptions"
+  - "API errors"
+  - "Failure handling"
+  - "User feedback"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Silent Error Handling
+
+## Trigger
+Adding error handling, try/catch blocks, API error responses, or any code that catches or handles failures.
+
+## Instruction
+- Never catch errors without surfacing them to the user or logging them appropriately
+- Avoid empty catch blocks or catch blocks that only log to console without user-visible feedback
+- For user-facing flows: show clear error messages, not generic "Something went wrong" or "Generating…"
+- For APIs: return meaningful error responses (status codes, error payloads) instead of swallowing failures
+- When retrying: surface the failure if retries are exhausted
+- Prefer rethrowing or propagating errors when you cannot handle them meaningfully
+
+## Reason
+AI agents often suppress errors to "keep going," which hides real failures from users. Silent failures lead to incorrect assumptions, lost data, and debugging nightmares. Users must know when something failed.
+
+## Provenance
+Manual addition, common failure mode in autonomous coding agents (DAPLab).

package/examples/no-sudo-commands/GUARDRAIL.md

@@ -32,3 +32,6 @@ Suggesting or running shell commands that require elevated privileges (sudo, su,
 
 ## Reason
 Agents have run sudo commands that overwrote system configs or installed conflicting packages. Elevated privileges require explicit human confirmation.
+
+## Provenance
+Manual addition, common failure mode in autonomous coding agents.

package/examples/no-unsafe-env-assumptions/GUARDRAIL.md

@@ -0,0 +1,35 @@
+---
+name: no-unsafe-env-assumptions
+description: Never assume environment variables exist without validation. Validate required env vars at startup and fail fast with clear errors. Apply when using process.env, os.environ, or config that depends on env.
+scope: project
+severity: critical
+triggers:
+  - "Environment variables"
+  - "process.env"
+  - "os.environ"
+  - "Configuration"
+  - "Startup"
+  - "Config loading"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Unsafe Env Assumptions
+
+## Trigger
+Using environment variables, loading configuration from env, or any code that reads `process.env`, `os.environ`, or similar at runtime.
+
+## Instruction
+- Never assume required environment variables exist; validate at startup or first use
+- For required vars: fail fast with a clear error message (e.g. "Missing required env: API_KEY. Add it to .env or set it before starting.")
+- Use a config validation step (e.g. check all required vars before the app starts) instead of failing later with cryptic "undefined" errors
+- Document required env vars in .env.example or README
+- For optional vars: provide sensible defaults or handle absence explicitly
+
+## Reason
+Code that assumes env vars exist fails at runtime with unclear errors (e.g. "Cannot read property of undefined"). Validating at startup surfaces configuration problems immediately with actionable messages.
+
+## Provenance
+Manual addition, complements no-placeholder-credentials (don't invent values; validate when using).

package/examples/prefer-existing-code/GUARDRAIL.md

@@ -0,0 +1,36 @@
+---
+name: prefer-existing-code
+description: Prefer existing code and shared helpers over reimplementing. Search the codebase before adding new logic. Apply when adding features, refactoring, or implementing functionality.
+scope: project
+severity: warning
+triggers:
+  - "Adding features"
+  - "Implementing"
+  - "Refactoring"
+  - "New function"
+  - "Helper"
+  - "Utility"
+  - "Duplicate"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# Prefer Existing Code
+
+## Trigger
+Adding features, implementing functionality, refactoring, or writing new helpers and utilities.
+
+## Instruction
+- Before implementing: search the codebase for existing functions, utilities, or patterns that already do what you need
+- Prefer reusing existing code over copy-pasting or reimplementing
+- When adding shared logic: extract to a common module or helper instead of duplicating
+- If similar code exists elsewhere: refactor to use a shared implementation
+- When the user asks for something that may already exist: check first and suggest the existing solution if applicable
+
+## Reason
+Agents often reimplement logic that already exists, leading to duplication, inconsistency, and maintenance burden. Reusing existing code reduces bugs and keeps the codebase coherent.
+
+## Provenance
+Manual addition, common failure mode in autonomous coding agents (DAPLab).

package/examples/require-access-control/GUARDRAIL.md

@@ -0,0 +1,37 @@
+---
+name: require-access-control
+description: When handling sensitive data or admin actions, enforce role or permission checks. Never assume the current user has access. Apply when adding auth, admin features, or user-specific data.
+scope: project
+severity: critical
+triggers:
+  - "Admin features"
+  - "User data"
+  - "Sensitive data"
+  - "Authorization"
+  - "Permissions"
+  - "Role check"
+  - "Private data"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# Require Access Control
+
+## Trigger
+Adding admin features, handling user-specific or sensitive data, implementing authorization, or any code that differentiates between user roles or permissions.
+
+## Instruction
+- Never assume the current user has access to sensitive data or admin actions
+- Add explicit role or permission checks before exposing or modifying sensitive data
+- For admin-only actions: verify the user has admin role or equivalent permission
+- For user-specific data: verify the requester is the owner or has explicit access
+- When adding new endpoints or UI: consider who should access them and add checks accordingly
+- Avoid hardcoding "admin" or "user" assumptions; use the project's auth/permission system
+
+## Reason
+Agents sometimes add features without access checks, exposing admin actions or private data to regular users. Access control must be explicit and enforced.
+
+## Provenance
+Manual addition, security best practice.

package/examples/require-tests/GUARDRAIL.md

@@ -29,3 +29,6 @@ Adding features, fixing bugs, modifying production code paths, or refactoring ex
 
 ## Reason
 Untested code leads to regressions and makes refactoring risky. Tests document expected behavior and catch breakage before production.
+
+## Provenance
+Manual addition, agent-guardrails reference.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "guardrails-ref",
-  "version": "1.0.9",
-  "description": "Validate and manage Agent Guardrails (GUARDRAIL.md) — init, add, remove, setup, validate, check, upgrade, list",
+  "version": "1.1.1",
+  "description": "Validate and manage Agent Guardrails (GUARDRAIL.md) — init, add, remove, setup, validate, check, upgrade, list, why",
   "type": "module",
   "main": "dist/validate.js",
   "bin": {
@@ -21,7 +21,9 @@
     "guardrails",
     "ai",
     "cursor",
-    "claude"
+    "claude",
+    "copilot",
+    "vscode"
   ],
   "license": "MIT",
   "repository": {