guardrails-ref 1.0.3 → 1.0.4

package/README.md

@@ -17,8 +17,8 @@ No global install needed. Or: `npm install -g guardrails-ref`
 | `npx guardrails-ref init [path]` | Create `.agents/guardrails/`, add no-plaintext-secrets, configure Cursor and Claude Code |
 | `npx guardrails-ref add <name> [path]` | Add an example guardrail (e.g. no-destructive-commands, database-migrations) |
 | `npx guardrails-ref remove <name> [path]` | Remove a guardrail from .agents/guardrails/ |
-| `npx guardrails-ref setup [path]` | Add the guardrail rule to Cursor rules and Claude instructions |
-| `npx guardrails-ref validate [path]` | Validate GUARDRAIL.md files (use `--json` for JSON output) |
+| `npx guardrails-ref setup [path]` | Add the guardrail rule to Cursor rules and Claude instructions (use `--remove` to undo) |
+| `npx guardrails-ref validate [path]` | Validate GUARDRAIL.md files (use `--json` for JSON, `--strict` to fail on warnings) |
 | `npx guardrails-ref list [path]` | List discovered guardrails (use `--json` for JSON output) |
 
 ## Examples
@@ -37,6 +37,8 @@ npx guardrails-ref list .
 - `database-migrations` — Always use migration files
 - `no-destructive-commands` — No rm -rf, DROP, TRUNCATE without approval
 - `no-new-deps-without-approval` — No new packages without approval
+- `no-hardcoded-urls` — No hardcoded API URLs, base URLs, endpoints
+- `no-sudo-commands` — No sudo/su/root commands without approval
 - `rate-limiting` — Limit tool calls and API loops
 - `no-console-in-production` — No console.log in production code
 

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { program } from "commander";
 import chalk from "chalk";
 import { validatePath, listGuardrails } from "./validate.js";
-import { runSetup } from "./setup.js";
+import { runSetup, runSetupRemove } from "./setup.js";
 import { runInit } from "./init.js";
 import { runAdd } from "./add.js";
 import { runRemove } from "./remove.js";
@@ -14,8 +14,10 @@ program
     .command("validate [path]")
     .description("Validate GUARDRAIL.md files in a directory or a single file")
     .option("-j, --json", "Output as JSON")
-    .action((path = ".", options) => {
+    .option("-s, --strict", "Fail on warnings (CI mode)")
+    .action((path = ".", options = {}) => {
     const result = validatePath(path);
+    const hasWarnings = result.results.some((r) => r.warnings.length > 0);
     if (options.json) {
         const json = {
             valid: result.valid,
@@ -29,7 +31,8 @@ program
             })),
         };
         console.log(JSON.stringify(json, null, 2));
-        process.exit(result.invalid > 0 ? 1 : 0);
+        const exitCode = result.invalid > 0 || (options.strict && hasWarnings) ? 1 : 0;
+        process.exit(exitCode);
         return;
     }
     let hasErrors = false;
@@ -59,7 +62,8 @@ program
         console.log();
         console.log(`Valid: ${result.valid}/${result.total}  Invalid: ${result.invalid}/${result.total}`);
     }
-    process.exit(hasErrors ? 1 : 0);
+    const strictFail = options.strict && hasWarnings;
+    process.exit(hasErrors || strictFail ? 1 : 0);
 });
 program
     .command("init [path]")
@@ -69,7 +73,7 @@ program
 });
 program
     .command("add <name> [path]")
-    .description("Add an example guardrail by name (e.g. no-destructive-commands, no-new-deps-without-approval)")
+    .description("Add an example guardrail by name (e.g. no-destructive-commands, no-hardcoded-urls, no-sudo-commands)")
     .action((name, path = ".") => {
     const ok = runAdd(name, path);
     process.exit(ok ? 0 : 1);
@@ -84,8 +88,11 @@ program
 program
     .command("setup [path]")
     .description("Add the guardrail one-liner to Cursor rules and Claude instructions (required until IDEs support guardrails natively)")
-    .action((path = ".") => {
-    const result = runSetup(path);
+    .option("-r, --remove", "Remove the guardrail rule from Cursor and Claude config")
+    .action((path, cmd) => {
+    const p = path ?? ".";
+    const opts = cmd?.opts?.() ?? {};
+    const result = opts.remove ? runSetupRemove(p) : runSetup(p);
     console.log(result.message);
 });
 program

package/dist/setup.d.ts

@@ -4,3 +4,4 @@ export interface SetupResult {
     message: string;
 }
 export declare function runSetup(projectPath?: string): SetupResult;
+export declare function runSetupRemove(projectPath?: string): SetupResult;

package/dist/setup.js

@@ -1,8 +1,12 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
 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 = "read and follow all constraints in .agents/guardrails";
+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();
+}
 function hasRule(content) {
     return content.includes(GUARDRAIL_RULE_MARKER);
 }
@@ -79,3 +83,57 @@ ${GUARDRAIL_RULE}
         message: messages.join("\n"),
     };
 }
+export function runSetupRemove(projectPath = ".") {
+    const root = resolve(projectPath);
+    let cursorDone = false;
+    let claudeDone = false;
+    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");
+    if (existsSync(cursorRuleFile)) {
+        rmSync(cursorRuleFile);
+        cursorDone = true;
+    }
+    if (existsSync(cursorrulesPath)) {
+        const existing = readFileSync(cursorrulesPath, "utf-8");
+        if (hasRule(existing)) {
+            const cleaned = removeRuleFromContent(existing);
+            if (cleaned) {
+                writeFileSync(cursorrulesPath, cleaned + "\n");
+            }
+            else {
+                rmSync(cursorrulesPath);
+            }
+            cursorDone = true;
+        }
+    }
+    if (existsSync(claudeInstructions)) {
+        const existing = readFileSync(claudeInstructions, "utf-8");
+        if (hasRule(existing)) {
+            const cleaned = removeRuleFromContent(existing);
+            if (cleaned) {
+                writeFileSync(claudeInstructions, cleaned + "\n");
+            }
+            else {
+                rmSync(claudeInstructions);
+            }
+            claudeDone = true;
+        }
+    }
+    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 (messages.length === 0) {
+        messages.push(chalk.yellow("Guardrail rule not found in any config files."));
+    }
+    return {
+        cursor: cursorDone,
+        claude: claudeDone,
+        message: messages.join("\n"),
+    };
+}

package/dist/templates.d.ts

@@ -1,5 +1,2 @@
-/**
- * Bundled example guardrails. Used by init and add commands.
- */
 export declare const TEMPLATES: Record<string, string>;
 export declare const TEMPLATE_NAMES: string[];

package/dist/templates.js

@@ -1,7 +1,15 @@
 /**
- * Bundled example guardrails. Used by init and add commands.
+ * Load templates from examples/ at runtime. Falls back to bundled templates
+ * when examples directory is not available (e.g. edge cases).
+ * Single source of truth: agent-guardrails/examples/
  */
-export const TEMPLATES = {
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "node:url";
+import { parseGuardrailFile } from "./parse.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Bundled fallback when examples/ is not available */
+const BUNDLED = {
     "no-plaintext-secrets": `---
 name: no-plaintext-secrets
 description: Never log, commit, or expose API keys, passwords, or tokens. Use environment variables or secrets managers. Apply when adding logging, implementing auth, or integrating third-party APIs.
@@ -32,168 +40,49 @@ Implementing authentication endpoints, adding logging, integrating third-party A
 
 ## Reason
 API keys were exposed in git during a 2025 security audit. Plaintext credentials in logs led to emergency key rotation.
-`,
-    "database-migrations": `---
-name: database-migrations
-description: Always use migration files for schema changes. Never modify production schema directly. Apply when modifying database schema, adding tables, or changing columns.
-scope: project
-severity: critical
-triggers:
-  - "Modifying database schema"
-  - "Adding or changing tables"
-  - "Database migrations"
-  - "Prisma schema"
-  - "SQL migrations"
-license: MIT
-metadata:
-  author: agent-guardrails
-  version: "1.0"
----
-
-# Database Migrations
-
-## Trigger
-Modifying database schema, adding tables, changing columns, or optimizing queries that affect schema.
-
-## Instruction
-- Always create a migration file (e.g. \`prisma migrate dev\`, \`rails db:migrate\`, or equivalent)
-- Never modify production schema directly without a migration
-- Test migrations in staging before applying to production
-- Require explicit human approval before running migrations in production
-
-## Reason
-Direct schema changes caused 4-hour downtime and data inconsistencies. Migrations provide rollback capability and audit trail.
-`,
-    "no-destructive-commands": `---
-name: no-destructive-commands
-description: Never run destructive shell commands or SQL without explicit human approval. Apply when deleting files, dropping tables, truncating data, or modifying production.
-scope: project
-severity: critical
-triggers:
-  - "Deleting files"
-  - "Cleaning up"
-  - "Dropping tables"
-  - "Truncating data"
-  - "Database cleanup"
-  - "rm -rf"
-  - "DROP TABLE"
-  - "TRUNCATE"
-license: MIT
-metadata:
-  author: agent-guardrails
-  version: "1.0"
----
-
-# No Destructive Commands
-
-## Trigger
-Running shell commands that delete files, database commands that drop or truncate data, or any operation that irreversibly removes content.
-
-## Instruction
-- Never run \`rm -rf\`, \`rm -r\`, or recursive deletes without explicit human approval
-- Never run \`DROP TABLE\`, \`DROP DATABASE\`, \`TRUNCATE\`, or \`DELETE\` without a WHERE clause on production data without explicit approval
-- For cleanup tasks: propose the command, explain the impact, and wait for confirmation before executing
-- Prefer moving to trash or using \`--dry-run\` when available
-- If the user asks to "delete everything" or "clean slate": stop and confirm scope before proceeding
-
-## Reason
-Agents have run \`rm -rf\` on wrong directories and \`DROP TABLE\` in production. Destructive operations must never execute without explicit human confirmation.
-`,
-    "no-new-deps-without-approval": `---
-name: no-new-deps-without-approval
-description: Do not add new npm, pip, or other package dependencies without explicit human approval. Apply when installing packages, adding imports, or suggesting new libraries.
-scope: project
-severity: warning
-triggers:
-  - "Installing packages"
-  - "Adding dependencies"
-  - "npm install"
-  - "pip install"
-  - "New library"
-  - "Use package X"
-license: MIT
-metadata:
-  author: agent-guardrails
-  version: "1.0"
----
-
-# No New Dependencies Without Approval
-
-## Trigger
-Adding a new package to package.json, requirements.txt, pyproject.toml, Cargo.toml, or any dependency manifest.
-
-## Instruction
-- Before running \`npm install <pkg>\`, \`pip install <pkg>\`, or equivalent: list the package and why it's needed, then ask for approval
-- Prefer using existing project dependencies over adding new ones
-- If a built-in or stdlib solution exists, use it instead of a new dependency
-- When suggesting a new dependency: include package name, purpose, and alternative (e.g. "or we could use the built-in X")
-- Never add dependencies "to fix" a problem without confirming the user wants new packages in the project
-
-## Reason
-Uncontrolled dependency growth leads to security risk, bundle bloat, and maintenance burden. Teams want to review what gets added to their lockfile.
-`,
-    "rate-limiting": `---
-name: rate-limiting
-description: Limit tool calls and API requests to prevent runaway loops. Max 50 tool calls per session, max 10 per iteration. Stop after 3 consecutive errors.
-scope: session
-severity: warning
-triggers:
-  - "Debugging API integrations"
-  - "Stripe or payment API calls"
-  - "External API calls in loops"
-  - "Context window approaching capacity"
-license: MIT
-metadata:
-  author: agent-guardrails
-  version: "1.0"
----
-
-# Rate Limiting
-
-## Trigger
-Debugging API integrations, making repeated external API calls, or when context exceeds 80% capacity or 10+ consecutive errors.
-
-## Instruction
-- Max 50 tool calls per session
-- Max 10 tool calls per iteration
-- Stop after 3 consecutive errors and request context rotation
-- For payment APIs (Stripe, etc.): always use test mode when debugging
-- When context exceeds 80% capacity: re-inject GUARDRAILS.md + summary + objective, then reset context
-
-## Reason
-Agent debugging Stripe entered an infinite loop of test calls, resulting in 2000+ requests in 30 minutes, $200 API costs, and account suspension.
-`,
-    "no-console-in-production": `---
-name: no-console-in-production
-description: Never add console.log, console.debug, or console.info in production code. Use a proper logging library. Apply when adding debugging, logging, or trace statements.
-scope: project
-severity: warning
-triggers:
-  - "Adding logging"
-  - "Debugging"
-  - "console.log"
-  - "console.debug"
-  - "Trace statements"
-license: MIT
-metadata:
-  author: agent-guardrails
-  version: "1.0"
----
-
-# No Console in Production
-
-## Trigger
-Adding logging, debugging statements, or trace output to application code that ships to production.
-
-## Instruction
-- Never add \`console.log\`, \`console.debug\`, or \`console.info\` in production code paths
-- Use a structured logging library (e.g. pino, winston, log4j) with log levels
-- For temporary debugging: use \`console.warn\` or \`console.error\` and add a TODO to remove before merge
-- Strip or gate console calls in production builds when a logger is not available
-- Prefer environment-based log levels (e.g. DEBUG=true) over hardcoded console statements
-
-## Reason
-console.log in production leaks sensitive data, clutters logs, and impacts performance. Structured loggers support levels, formatting, and safe redaction.
 `,
 };
+function loadTemplatesFromDir(examplesDir) {
+    const templates = {};
+    if (!existsSync(examplesDir))
+        return templates;
+    const entries = readdirSync(examplesDir, { withFileTypes: true });
+    for (const ent of entries) {
+        if (!ent.isDirectory())
+            continue;
+        const file = join(examplesDir, ent.name, "GUARDRAIL.md");
+        if (!existsSync(file))
+            continue;
+        try {
+            const result = parseGuardrailFile(file);
+            if (result.success && result.guardrail) {
+                const key = ent.name.toLowerCase().replace(/\s+/g, "-");
+                const content = readFileSync(file, "utf-8");
+                templates[key] = content;
+            }
+            else if (result.errors.length > 0) {
+                console.warn(`guardrails-ref: skipped ${file}: ${result.errors.join("; ")}`);
+            }
+        }
+        catch (err) {
+            console.warn(`guardrails-ref: skipped ${file}: ${err.message}`);
+        }
+    }
+    return templates;
+}
+function getTemplates() {
+    // Try: 1) guardrails-ref/examples (published pkg), 2) ../examples (repo root when developing)
+    const candidates = [
+        join(__dirname, "..", "examples"),
+        join(__dirname, "..", "..", "examples"),
+    ];
+    for (const examplesDir of candidates) {
+        const fromDisk = loadTemplatesFromDir(examplesDir);
+        if (Object.keys(fromDisk).length > 0) {
+            return fromDisk;
+        }
+    }
+    return BUNDLED;
+}
+export const TEMPLATES = getTemplates();
 export const TEMPLATE_NAMES = Object.keys(TEMPLATES);

package/examples/database-migrations/GUARDRAIL.md

@@ -0,0 +1,33 @@
+---
+name: database-migrations
+description: Always use migration files for schema changes. Never modify production schema directly. Apply when modifying database schema, adding tables, or changing columns.
+scope: project
+severity: critical
+triggers:
+  - "Modifying database schema"
+  - "Adding or changing tables"
+  - "Database migrations"
+  - "Prisma schema"
+  - "SQL migrations"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# Database Migrations
+
+## Trigger
+Modifying database schema, adding tables, changing columns, or optimizing queries that affect schema.
+
+## Instruction
+- Always create a migration file (e.g. `prisma migrate dev`, `rails db:migrate`, or equivalent)
+- Never modify production schema directly without a migration
+- Test migrations in staging before applying to production
+- Require explicit human approval before running migrations in production
+
+## Reason
+Direct schema changes caused 4-hour downtime and data inconsistencies. Migrations provide rollback capability and audit trail.
+
+## Provenance
+Manual addition, based on guardrails.md case study.

package/examples/no-console-in-production/GUARDRAIL.md

@@ -0,0 +1,34 @@
+---
+name: no-console-in-production
+description: Never add console.log, console.debug, or console.info in production code. Use a proper logging library. Apply when adding debugging, logging, or trace statements.
+scope: project
+severity: warning
+triggers:
+  - "Adding logging"
+  - "Debugging"
+  - "console.log"
+  - "console.debug"
+  - "Trace statements"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Console in Production
+
+## Trigger
+Adding logging, debugging statements, or trace output to application code that ships to production.
+
+## Instruction
+- Never add `console.log`, `console.debug`, or `console.info` in production code paths
+- Use a structured logging library (e.g. pino, winston, log4j) with log levels
+- For temporary debugging: use `console.warn` or `console.error` and add a TODO to remove before merge
+- Strip or gate console calls in production builds when a logger is not available
+- Prefer environment-based log levels (e.g. DEBUG=true) over hardcoded console statements
+
+## Reason
+console.log in production leaks sensitive data, clutters logs, and impacts performance. Structured loggers support levels, formatting, and safe redaction.
+
+## Provenance
+Manual addition, common code quality concern for production applications.

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

@@ -0,0 +1,37 @@
+---
+name: no-destructive-commands
+description: Never run destructive shell commands or SQL without explicit human approval. Apply when deleting files, dropping tables, truncating data, or modifying production.
+scope: project
+severity: critical
+triggers:
+  - "Deleting files"
+  - "Cleaning up"
+  - "Dropping tables"
+  - "Truncating data"
+  - "Database cleanup"
+  - "rm -rf"
+  - "DROP TABLE"
+  - "TRUNCATE"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Destructive Commands
+
+## Trigger
+Running shell commands that delete files, database commands that drop or truncate data, or any operation that irreversibly removes content.
+
+## Instruction
+- Never run `rm -rf`, `rm -r`, or recursive deletes without explicit human approval
+- Never run `DROP TABLE`, `DROP DATABASE`, `TRUNCATE`, or `DELETE` without a WHERE clause on production data without explicit approval
+- For cleanup tasks: propose the command, explain the impact, and wait for confirmation before executing
+- Prefer moving to trash or using `--dry-run` when available
+- If the user asks to "delete everything" or "clean slate": stop and confirm scope before proceeding
+
+## Reason
+Agents have run `rm -rf` on wrong directories and `DROP TABLE` in production. Destructive operations must never execute without explicit human confirmation.
+
+## Provenance
+Manual addition, common failure mode in autonomous coding agents.

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

@@ -0,0 +1,32 @@
+---
+name: no-hardcoded-urls
+description: Never hardcode API URLs, base URLs, or endpoints. Use environment variables or config. Apply when adding API calls, integrations, or external service URLs.
+scope: project
+severity: warning
+triggers:
+  - "API integration"
+  - "Adding API calls"
+  - "Base URL"
+  - "Endpoint"
+  - "http://"
+  - "https://"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Hardcoded URLs
+
+## Trigger
+Adding API calls, integrating external services, or referencing URLs (base URLs, endpoints, webhook URLs) in code.
+
+## Instruction
+- Never hardcode API base URLs, endpoints, or webhook URLs in source code
+- Use environment variables (e.g. `API_BASE_URL`, `WEBHOOK_URL`) or config files
+- Document required env vars in README or .env.example
+- For tests: use localhost, mock servers, or env-based URLs
+- Prefer relative paths for same-origin requests when applicable
+
+## Reason
+Hardcoded URLs break across environments (dev/staging/prod), leak internal endpoints, and block easy configuration. Environment-based config is standard practice.

package/examples/no-new-deps-without-approval/GUARDRAIL.md

@@ -0,0 +1,35 @@
+---
+name: no-new-deps-without-approval
+description: Do not add new npm, pip, or other package dependencies without explicit human approval. Apply when installing packages, adding imports, or suggesting new libraries.
+scope: project
+severity: warning
+triggers:
+  - "Installing packages"
+  - "Adding dependencies"
+  - "npm install"
+  - "pip install"
+  - "New library"
+  - "Use package X"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No New Dependencies Without Approval
+
+## Trigger
+Adding a new package to package.json, requirements.txt, pyproject.toml, Cargo.toml, or any dependency manifest.
+
+## Instruction
+- Before running `npm install <pkg>`, `pip install <pkg>`, or equivalent: list the package and why it's needed, then ask for approval
+- Prefer using existing project dependencies over adding new ones
+- If a built-in or stdlib solution exists, use it instead of a new dependency
+- When suggesting a new dependency: include package name, purpose, and alternative (e.g. "or we could use the built-in X")
+- Never add dependencies "to fix" a problem without confirming the user wants new packages in the project
+
+## Reason
+Uncontrolled dependency growth leads to security risk, bundle bloat, and maintenance burden. Teams want to review what gets added to their lockfile.
+
+## Provenance
+Manual addition, common team preference for dependency hygiene.

package/examples/no-plaintext-secrets/GUARDRAIL.md

@@ -0,0 +1,33 @@
+---
+name: no-plaintext-secrets
+description: Never log, commit, or expose API keys, passwords, or tokens. Use environment variables or secrets managers. Apply when adding logging, implementing auth, or integrating third-party APIs.
+scope: project
+severity: critical
+triggers:
+  - "Adding logging"
+  - "Implementing authentication"
+  - "API integration"
+  - "Handling credentials"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Plaintext Secrets
+
+## Trigger
+Implementing authentication endpoints, adding logging, integrating third-party APIs, or handling any user credentials or API keys.
+
+## Instruction
+- Never store, log, or commit plaintext credentials (API keys, passwords, tokens, sessions)
+- Always use environment variables or secrets managers (e.g. 1Password, Vault)
+- Use bcrypt with 12 salt rounds for password hashing
+- Always require HTTPS for authentication endpoints
+- Use a `redactSensitive()` helper when logging objects that may contain secrets
+
+## Reason
+API keys were exposed in git during a 2025 security audit. Plaintext credentials in logs led to emergency key rotation.
+
+## Provenance
+Manual addition, based on guardrails.md case study.

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

@@ -0,0 +1,34 @@
+---
+name: no-sudo-commands
+description: Never run sudo, su, or root-elevated commands without explicit human approval. Apply when suggesting shell commands that modify system files or require elevated privileges.
+scope: project
+severity: critical
+triggers:
+  - "Installing system packages"
+  - "apt install"
+  - "yum install"
+  - "brew install"
+  - "Modifying system files"
+  - "sudo"
+  - "su "
+  - "root"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# No Sudo Commands
+
+## Trigger
+Suggesting or running shell commands that require elevated privileges (sudo, su, root) or that modify system-wide files.
+
+## Instruction
+- Never run `sudo`, `su`, or root-elevated commands without explicit human approval
+- For package installation: prefer user-space tools (nvm, pyenv, user-local npm) over system-wide installs
+- If system packages are needed: propose the command, explain the impact, and wait for confirmation
+- Never modify /etc, /usr (outside user installs), or other system directories without approval
+- When the user asks to "install" something: clarify scope (project vs system) before suggesting commands
+
+## Reason
+Agents have run sudo commands that overwrote system configs or installed conflicting packages. Elevated privileges require explicit human confirmation.

package/examples/rate-limiting/GUARDRAIL.md

@@ -0,0 +1,33 @@
+---
+name: rate-limiting
+description: Limit tool calls and API requests to prevent runaway loops. Max 50 tool calls per session, max 10 per iteration. Stop after 3 consecutive errors.
+scope: session
+severity: warning
+triggers:
+  - "Debugging API integrations"
+  - "Stripe or payment API calls"
+  - "External API calls in loops"
+  - "Context window approaching capacity"
+license: MIT
+metadata:
+  author: agent-guardrails
+  version: "1.0"
+---
+
+# Rate Limiting
+
+## Trigger
+Debugging API integrations, making repeated external API calls, or when context exceeds 80% capacity or 10+ consecutive errors.
+
+## Instruction
+- Max 50 tool calls per session
+- Max 10 tool calls per iteration
+- Stop after 3 consecutive errors and request context rotation
+- For payment APIs (Stripe, etc.): always use test mode when debugging
+- When context exceeds 80% capacity: re-inject GUARDRAILS.md + summary + objective, then reset context
+
+## Reason
+Agent debugging Stripe entered an infinite loop of test calls, resulting in 2000+ requests in 30 minutes, $200 API costs, and account suspension.
+
+## Provenance
+Manual addition, based on guardrails.md case study.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardrails-ref",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Validate and manage Agent Guardrails (GUARDRAIL.md) — init, add, remove, setup, validate, list",
   "type": "module",
   "main": "dist/validate.js",
@@ -8,7 +8,7 @@
     "guardrails-ref": "dist/cli.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/copy-examples.js && tsc",
     "test": "npm run build && node --test test/*.test.js",
     "validate": "node dist/cli.js validate",
     "list": "node dist/cli.js list",
@@ -42,6 +42,7 @@
     "node": ">=18"
   },
   "files": [
-    "dist"
+    "dist",
+    "examples"
   ]
 }