@intellectronica/ruler 0.3.0 → 0.3.2

package/README.md

@@ -38,12 +38,14 @@ Managing instructions across multiple AI coding tools becomes complex as your te
 - **Duplicated effort** maintaining multiple config files
 - **Context drift** as project requirements evolve
 - **Onboarding friction** for new AI tools
+- **Complex project structures** requiring context-specific instructions for different components
 
-Ruler solves this by providing a **single source of truth** for all your AI agent instructions, automatically distributing them to the right configuration files.
+Ruler solves this by providing a **single source of truth** for all your AI agent instructions, automatically distributing them to the right configuration files. With support for **nested rule loading**, Ruler can handle complex project structures with context-specific instructions for different components.
 
 ## Core Features
 
 - **Centralised Rule Management**: Store all AI instructions in a dedicated `.ruler/` directory using Markdown files
+- **Nested Rule Loading**: Support complex project structures with multiple `.ruler/` directories for context-specific instructions
 - **Automatic Distribution**: Ruler applies these rules to configuration files of supported AI agents
 - **Targeted Agent Configuration**: Fine-tune which agents are affected and their specific output paths via `ruler.toml`
 - **MCP Server Propagation**: Manage and distribute Model Context Protocol (MCP) server settings
@@ -52,30 +54,30 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 
 ## Supported AI Agents
 
-| Agent            | Rules File(s)                                    | MCP Configuration / Notes                           |
-| ---------------- | ------------------------------------------------ | --------------------------------------------------- |
-| AGENTS.md        | `AGENTS.md`                                      | (pseudo-agent ensuring root `AGENTS.md` exists)   |
-| GitHub Copilot   | `.github/copilot-instructions.md`                | `.vscode/mcp.json`                                  |
-| Claude Code      | `CLAUDE.md`                                      | `.mcp.json`                                         |
-| OpenAI Codex CLI | `AGENTS.md`                                      | `.codex/config.toml`                                |
-| Jules            | `AGENTS.md`                                      | -                                                   |
-| Cursor           | `.cursor/rules/ruler_cursor_instructions.mdc`    | `.cursor/mcp.json`                                  |
-| Windsurf         | `.windsurf/rules/ruler_windsurf_instructions.md` | -                                                   |
-| Cline            | `.clinerules`                                    | -                                                   |
-| Amp              | `AGENTS.md`                                      | -                                                   |
-| Aider            | `AGENTS.md`, `.aider.conf.yml`                   | `.mcp.json`                                         |
-| Firebase Studio  | `.idx/airules.md`                                | -                                                   |
-| Open Hands       | `.openhands/microagents/repo.md`                 | `.openhands/config.toml`  |
-| Gemini CLI       | `AGENTS.md`                                      | `.gemini/settings.json`                             |
-| Junie            | `.junie/guidelines.md`                           | -                                                   |
-| AugmentCode      | `.augment/rules/ruler_augment_instructions.md`   | `.vscode/settings.json`                             |
-| Kilo Code        | `.kilocode/rules/ruler_kilocode_instructions.md` | `.kilocode/mcp.json`                                |
-| opencode         | `AGENTS.md`                                      | `opencode.json`  |
-| Goose            | `.goosehints`                                    | -                                                   |
-| Qwen Code        | `AGENTS.md`                                      | `.qwen/settings.json`                               |
-| Zed              | `AGENTS.md`                                      | `.zed/settings.json` (project root, never $HOME)    |
-| Warp             | `WARP.md`                                        | -                                                   |
-| Kiro             | `.kiro/steering/ruler_kiro_instructions.md`      | -                                                   |
+| Agent            | Rules File(s)                                    | MCP Configuration / Notes                        |
+| ---------------- | ------------------------------------------------ | ------------------------------------------------ |
+| AGENTS.md        | `AGENTS.md`                                      | (pseudo-agent ensuring root `AGENTS.md` exists)  |
+| GitHub Copilot   | `.github/copilot-instructions.md`                | `.vscode/mcp.json`                               |
+| Claude Code      | `CLAUDE.md`                                      | `.mcp.json`                                      |
+| OpenAI Codex CLI | `AGENTS.md`                                      | `.codex/config.toml`                             |
+| Jules            | `AGENTS.md`                                      | -                                                |
+| Cursor           | `.cursor/rules/ruler_cursor_instructions.mdc`    | `.cursor/mcp.json`                               |
+| Windsurf         | `.windsurf/rules/ruler_windsurf_instructions.md` | -                                                |
+| Cline            | `.clinerules`                                    | -                                                |
+| Amp              | `AGENTS.md`                                      | -                                                |
+| Aider            | `AGENTS.md`, `.aider.conf.yml`                   | `.mcp.json`                                      |
+| Firebase Studio  | `.idx/airules.md`                                | -                                                |
+| Open Hands       | `.openhands/microagents/repo.md`                 | `.openhands/config.toml`                         |
+| Gemini CLI       | `AGENTS.md`                                      | `.gemini/settings.json`                          |
+| Junie            | `.junie/guidelines.md`                           | -                                                |
+| AugmentCode      | `.augment/rules/ruler_augment_instructions.md`   | `.vscode/settings.json`                          |
+| Kilo Code        | `.kilocode/rules/ruler_kilocode_instructions.md` | `.kilocode/mcp.json`                             |
+| opencode         | `AGENTS.md`                                      | `opencode.json`                                  |
+| Goose            | `.goosehints`                                    | -                                                |
+| Qwen Code        | `AGENTS.md`                                      | `.qwen/settings.json`                            |
+| Zed              | `AGENTS.md`                                      | `.zed/settings.json` (project root, never $HOME) |
+| Warp             | `WARP.md`                                        | -                                                |
+| Kiro             | `.kiro/steering/ruler_kiro_instructions.md`      | -                                                |
 
 ## Getting Started
 
@@ -133,6 +135,39 @@ This is your central hub for all AI agent instructions:
 
 This ordering lets you keep a short, high-impact root `AGENTS.md` (e.g. executive project summary) while housing detailed guidance inside `.ruler/`.
 
+### Nested Rule Loading
+
+Ruler now supports **nested rule loading** with the `--nested` flag, enabling context-specific instructions for different parts of your project:
+
+```
+project/
+├── .ruler/           # Global project rules
+│   ├── AGENTS.md
+│   └── coding_style.md
+├── src/
+│   └── .ruler/       # Component-specific rules
+│       └── api_guidelines.md
+├── tests/
+│   └── .ruler/       # Test-specific rules
+│       └── testing_conventions.md
+└── docs/
+    └── .ruler/       # Documentation rules
+        └── writing_style.md
+```
+
+**How it works:**
+
+- Discover all `.ruler/` directories in the project hierarchy
+- Load and concatenate rules from each directory in order
+- Enable with: `ruler apply --nested`
+
+**Perfect for:**
+
+- Monorepos with multiple services
+- Projects with distinct components (frontend/backend)
+- Teams needing different instructions for different areas
+- Complex codebases with varying standards
+
 ### Best Practices for Rule Files
 
 **Granularity**: Break down complex instructions into focused `.md` files:
@@ -176,18 +211,18 @@ The `apply` command looks for `.ruler/` in the current directory tree, reading t
 
 ### Options
 
-| Option                         | Description                                                                                                                                                |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                   |
+| Option                         | Description                                                                                                                                                                     |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                                        |
 | `--agents <agent1,agent2,...>` | Comma-separated list of agent names to target (agentsmd, amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, augmentcode, kilocode, warp) |
-| `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                           |
-| `--mcp` / `--with-mcp`         | Enable applying MCP server configurations (default: true)                                                                                                  |
-| `--no-mcp`                     | Disable applying MCP server configurations                                                                                                                 |
-| `--mcp-overwrite`              | Overwrite native MCP config entirely instead of merging                                                                                                    |
-| `--gitignore`                  | Enable automatic .gitignore updates (default: true)                                                                                                        |
-| `--no-gitignore`               | Disable automatic .gitignore updates                                                                                                                       |
-| `--local-only`                 | Do not look for configuration in `$XDG_CONFIG_HOME`                                                                                                        |
-| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                   |
+| `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                                                |
+| `--mcp` / `--with-mcp`         | Enable applying MCP server configurations (default: true)                                                                                                                       |
+| `--no-mcp`                     | Disable applying MCP server configurations                                                                                                                                      |
+| `--mcp-overwrite`              | Overwrite native MCP config entirely instead of merging                                                                                                                         |
+| `--gitignore`                  | Enable automatic .gitignore updates (default: true)                                                                                                                             |
+| `--no-gitignore`               | Disable automatic .gitignore updates                                                                                                                                            |
+| `--local-only`                 | Do not look for configuration in `$XDG_CONFIG_HOME`                                                                                                                             |
+| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                                        |
 
 ### Common Examples
 
@@ -254,15 +289,15 @@ ruler revert [options]
 
 ### Options
 
-| Option                         | Description                                                                                                                                             |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                |
+| Option                         | Description                                                                                                                                                                  |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                                     |
 | `--agents <agent1,agent2,...>` | Comma-separated list of agent names to revert (agentsmd, amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode, warp) |
-| `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                        |
-| `--keep-backups`               | Keep backup files (.bak) after restoration (default: false)                                                                                             |
-| `--dry-run`                    | Preview changes without actually reverting files                                                                                                        |
-| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                |
-| `--local-only`                 | Only search for local .ruler directories, ignore global config                                                                                          |
+| `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                                             |
+| `--keep-backups`               | Keep backup files (.bak) after restoration (default: false)                                                                                                                  |
+| `--dry-run`                    | Preview changes without actually reverting files                                                                                                                             |
+| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                                     |
+| `--local-only`                 | Only search for local .ruler directories, ignore global config                                                                                                               |
 
 ### Common Examples
 
@@ -322,7 +357,7 @@ command = "npx"
 args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
 
 [mcp_servers.git]
-command = "npx" 
+command = "npx"
 args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
 
 [mcp_servers.remote_api]
@@ -456,6 +491,7 @@ For backward compatibility, you can still use the JSON format; a warning is issu
 ### Configuration Precedence
 
 When both TOML and JSON configurations are present:
+
 1. **TOML servers take precedence** over JSON servers with the same name
 2. **Servers are merged** from both sources (unless using overwrite strategy)
 3. **Deprecation warning** is shown encouraging migration to TOML (warning shown once per run)
@@ -463,6 +499,7 @@ When both TOML and JSON configurations are present:
 ### Server Types
 
 **Local/stdio servers** require a `command` field:
+
 ```toml
 [mcp_servers.local_server]
 command = "node"
@@ -474,7 +511,7 @@ DEBUG = "1"
 
 **Remote servers** require a `url` field (headers optional; bearer Authorization token auto-extracted for OpenHands when possible):
 ```toml
-[mcp_servers.remote_server]  
+[mcp_servers.remote_server]
 url = "https://api.example.com"
 
 [mcp_servers.remote_server.headers]
@@ -486,6 +523,7 @@ Ruler uses this configuration with the `merge` (default) or `overwrite` strategy
 **Home Directory Safety:** Ruler never writes MCP configuration files outside your project root. Any historical references to user home directories (e.g. `~/.codeium/windsurf/mcp_config.json` or `~/.zed/settings.json`) have been removed; only project-local paths are targeted.
 
 **Note for OpenAI Codex CLI:** To apply the local Codex CLI MCP configuration, set the `CODEX_HOME` environment variable to your project’s `.codex` directory:
+
 ```bash
 export CODEX_HOME="$(pwd)/.codex"
 ```
@@ -545,7 +583,26 @@ ruler init
 ruler apply
 ```
 
-### Scenario 2: Team Standardization
+### Scenario 2: Complex Projects with Nested Rules
+
+For large projects with multiple components or services, use nested rule loading:
+
+```bash
+# Set up nested .ruler directories
+mkdir -p src/.ruler tests/.ruler docs/.ruler
+
+# Add component-specific instructions
+echo "# API Design Guidelines" > src/.ruler/api_rules.md
+echo "# Testing Best Practices" > tests/.ruler/test_rules.md
+echo "# Documentation Standards" > docs/.ruler/docs_rules.md
+
+# Apply with nested loading
+ruler apply --nested --verbose
+```
+
+This creates context-specific instructions for different parts of your project while maintaining global rules in the root `.ruler/` directory.
+
+### Scenario 3: Team Standardization
 
 1. Create `.ruler/coding_standards.md`, `.ruler/api_usage.md`
 2. Commit the `.ruler` directory to your repository
@@ -647,6 +704,9 @@ This shows:
 **Q: Can I use different rules for different agents?**
 A: Currently, all agents receive the same concatenated rules. For agent-specific instructions, include sections in your rule files like "## GitHub Copilot Specific" or "## Aider Configuration".
 
+**Q: How do I set up different instructions for different parts of my project?**
+A: Use the `--nested` flag with `ruler apply --nested`. This enables Ruler to discover and load rules from multiple `.ruler/` directories throughout your project hierarchy. Place component-specific instructions in `src/.ruler/`, test-specific rules in `tests/.ruler/`, etc., while keeping global rules in the root `.ruler/` directory.
+
 **Q: How do I temporarily disable Ruler for an agent?**
 A: Set `enabled = false` in `ruler.toml` under `[agents.agentname]`, or use `--agents` flag to specify only the agents you want.
 

package/dist/agents/AbstractAgent.js

@@ -50,11 +50,13 @@ class AbstractAgent {
      * 4. Writing the new content
      */
     async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
-    agentConfig) {
+    agentConfig, backup = true) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
         const absolutePath = path.resolve(projectRoot, output);
         await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
-        await (0, FileSystemUtils_1.backupFile)(absolutePath);
+        if (backup) {
+            await (0, FileSystemUtils_1.backupFile)(absolutePath);
+        }
         await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules);
     }
     /**

package/dist/agents/AgentsMdAgent.js

@@ -54,10 +54,12 @@ class AgentsMdAgent extends AbstractAgent_1.AbstractAgent {
         return path.join(projectRoot, 'AGENTS.md');
     }
     async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
-    agentConfig) {
+    agentConfig, backup = true) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
         const absolutePath = path.resolve(projectRoot, output);
         await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
+        // Add marker comment to the content to identify it as generated
+        const contentWithMarker = `<!-- Generated by Ruler -->\n${concatenatedRules}`;
         // Read existing content if present and skip write if identical
         let existing = null;
         try {
@@ -66,13 +68,15 @@ class AgentsMdAgent extends AbstractAgent_1.AbstractAgent {
         catch {
             existing = null;
         }
-        if (existing !== null && existing === concatenatedRules) {
+        if (existing !== null && existing === contentWithMarker) {
             // No change; skip backup/write for idempotency
             return;
         }
-        // Backup (only if file existed) then write new content
-        await (0, FileSystemUtils_1.backupFile)(absolutePath);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules);
+        // Backup (only if file existed and backup is enabled) then write new content
+        if (backup) {
+            await (0, FileSystemUtils_1.backupFile)(absolutePath);
+        }
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, contentWithMarker);
     }
     getMcpServerKey() {
         // No MCP configuration for this pseudo-agent

package/dist/agents/AiderAgent.js

@@ -52,21 +52,23 @@ class AiderAgent {
     getName() {
         return 'Aider';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig) {
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig, backup = true) {
         // First perform idempotent AGENTS.md write via composed AgentsMdAgent
         await this.agentsMdAgent.applyRulerConfig(concatenatedRules, projectRoot, null, {
             // Preserve explicit outputPath precedence semantics if provided.
             outputPath: agentConfig?.outputPath ||
                 agentConfig?.outputPathInstructions ||
                 undefined,
-        });
+        }, backup);
         // Now handle .aider.conf.yml configuration
         const cfgPath = agentConfig?.outputPathConfig ??
             this.getDefaultOutputPath(projectRoot).config;
         let doc = {};
         try {
             await fs.access(cfgPath);
-            await (0, FileSystemUtils_1.backupFile)(cfgPath);
+            if (backup) {
+                await (0, FileSystemUtils_1.backupFile)(cfgPath);
+            }
             const raw = await fs.readFile(cfgPath, 'utf8');
             doc = (yaml.load(raw) || {});
         }

package/dist/agents/AugmentCodeAgent.js

@@ -48,9 +48,11 @@ class AugmentCodeAgent {
         return 'AugmentCode';
     }
     async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
-    agentConfig) {
+    agentConfig, backup = true) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
-        await (0, FileSystemUtils_1.backupFile)(output);
+        if (backup) {
+            await (0, FileSystemUtils_1.backupFile)(output);
+        }
         await (0, FileSystemUtils_1.writeGeneratedFile)(output, concatenatedRules);
         // AugmentCode does not support MCP servers
         // MCP configuration is ignored for this agent

package/dist/agents/CursorAgent.js

@@ -48,7 +48,7 @@ class CursorAgent extends AbstractAgent_1.AbstractAgent {
         return 'Cursor';
     }
     async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
-    agentConfig) {
+    agentConfig, backup = true) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
         const absolutePath = path.resolve(projectRoot, output);
         // Cursor expects a YAML front-matter block with an `alwaysApply` flag.
@@ -56,7 +56,9 @@ class CursorAgent extends AbstractAgent_1.AbstractAgent {
         const frontMatter = ['---', 'alwaysApply: true', '---', ''].join('\n');
         const content = `${frontMatter}${concatenatedRules.trimStart()}`;
         await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
-        await (0, FileSystemUtils_1.backupFile)(absolutePath);
+        if (backup) {
+            await (0, FileSystemUtils_1.backupFile)(absolutePath);
+        }
         await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, content);
     }
     getDefaultOutputPath(projectRoot) {

package/dist/agents/WindsurfAgent.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WindsurfAgent = void 0;
 const path = __importStar(require("path"));
 const AbstractAgent_1 = require("./AbstractAgent");
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
 /**
  * Windsurf agent adapter.
  */
@@ -46,6 +47,19 @@ class WindsurfAgent extends AbstractAgent_1.AbstractAgent {
     getName() {
         return 'Windsurf';
     }
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
+    agentConfig, backup = true) {
+        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        const absolutePath = path.resolve(projectRoot, output);
+        // Windsurf expects a YAML front-matter block with a `trigger` flag.
+        const frontMatter = ['---', 'trigger: always_on', '---', ''].join('\n');
+        const content = `${frontMatter}${concatenatedRules.trimStart()}`;
+        await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
+        if (backup) {
+            await (0, FileSystemUtils_1.backupFile)(absolutePath);
+        }
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, content);
+    }
     getDefaultOutputPath(projectRoot) {
         return path.join(projectRoot, '.windsurf', 'rules', 'ruler_windsurf_instructions.md');
     }

package/dist/cli/commands.js

@@ -59,6 +59,16 @@ function run() {
             type: 'boolean',
             description: 'Only search for local .ruler directories, ignore global config',
             default: false,
+        })
+            .option('nested', {
+            type: 'boolean',
+            description: 'Enable nested rule loading from nested .ruler directories (default: disabled)',
+            default: false,
+        })
+            .option('backup', {
+            type: 'boolean',
+            description: 'Enable/disable creation of .bak backup files (default: enabled)',
+            default: true,
         });
     }, handlers_1.applyHandler)
         .command('init', 'Scaffold a .ruler directory with default files', (y) => {

package/dist/cli/handlers.js

@@ -58,6 +58,8 @@ async function applyHandler(argv) {
     const verbose = argv.verbose;
     const dryRun = argv['dry-run'];
     const localOnly = argv['local-only'];
+    const nested = argv.nested;
+    const backup = argv.backup;
     // Determine gitignore preference: CLI > TOML > Default (enabled)
     // yargs handles --no-gitignore by setting gitignore to false
     let gitignorePreference;
@@ -68,7 +70,7 @@ async function applyHandler(argv) {
         gitignorePreference = undefined; // Let TOML/default decide
     }
     try {
-        await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly);
+        await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly, nested, backup);
         console.log('Ruler apply completed successfully.');
     }
     catch (err) {
@@ -106,6 +108,10 @@ async function initHandler(argv) {
 # uncomment and populate the following line. If omitted, all agents are active.
 # default_agents = ["copilot", "claude"]
 
+# Enable nested rule loading from nested .ruler directories
+# When enabled, ruler will search for and process .ruler directories throughout the project hierarchy
+# nested = false
+
 # --- Agent Specific Configurations ---
 # You can enable/disable agents and override their default output paths here.
 # Use lowercase agent identifiers: amp, copilot, claude, codex, cursor, windsurf, cline, aider, kilocode

package/dist/core/ConfigLoader.js

@@ -69,6 +69,7 @@ const rulerConfigSchema = zod_1.z.object({
         enabled: zod_1.z.boolean().optional(),
     })
         .optional(),
+    nested: zod_1.z.boolean().optional(),
 });
 /**
  * Loads and parses the ruler TOML configuration file, applying defaults.
@@ -174,11 +175,13 @@ async function loadConfig(options) {
     if (typeof rawGitignoreSection.enabled === 'boolean') {
         gitignoreConfig.enabled = rawGitignoreSection.enabled;
     }
+    const nested = typeof raw.nested === 'boolean' ? raw.nested : false;
     return {
         defaultAgents,
         agentConfigs,
         cliAgents,
         mcp: globalMcpConfig,
         gitignore: gitignoreConfig,
+        nested,
     };
 }

package/dist/core/FileSystemUtils.js

@@ -38,6 +38,8 @@ exports.readMarkdownFiles = readMarkdownFiles;
 exports.writeGeneratedFile = writeGeneratedFile;
 exports.backupFile = backupFile;
 exports.ensureDirExists = ensureDirExists;
+exports.findGlobalRulerDir = findGlobalRulerDir;
+exports.findAllRulerDirs = findAllRulerDirs;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
@@ -147,8 +149,19 @@ async function readMarkdownFiles(rulerDir) {
             const stat = await fs_1.promises.stat(rootAgentsPath);
             if (stat.isFile()) {
                 const content = await fs_1.promises.readFile(rootAgentsPath, 'utf8');
-                // Prepend so it has highest precedence
-                ordered = [{ path: rootAgentsPath, content }, ...ordered];
+                // Check if this is a generated file and we have other .ruler files
+                const isGenerated = content.startsWith('<!-- Generated by Ruler -->');
+                const hasRulerFiles = others.length > 0 || primaryFile !== null;
+                // Additional check: if AGENTS.md contains ruler source comments and we have ruler files,
+                // it's likely a corrupted generated file that should be skipped
+                const containsRulerSources = content.includes('<!-- Source: .ruler/') ||
+                    content.includes('<!-- Source: ruler/');
+                const isProbablyGenerated = isGenerated || (containsRulerSources && hasRulerFiles);
+                // Skip generated AGENTS.md if we have other files in .ruler
+                if (!isProbablyGenerated || !hasRulerFiles) {
+                    // Prepend so it has highest precedence
+                    ordered = [{ path: rootAgentsPath, content }, ...ordered];
+                }
             }
         }
     }
@@ -182,3 +195,62 @@ async function backupFile(filePath) {
 async function ensureDirExists(dirPath) {
     await fs_1.promises.mkdir(dirPath, { recursive: true });
 }
+/**
+ * Finds the global ruler configuration directory at XDG_CONFIG_HOME/ruler.
+ * Returns the path if it exists, null otherwise.
+ */
+async function findGlobalRulerDir() {
+    const globalConfigDir = path.join(getXdgConfigDir(), 'ruler');
+    try {
+        const stat = await fs_1.promises.stat(globalConfigDir);
+        if (stat.isDirectory()) {
+            return globalConfigDir;
+        }
+    }
+    catch {
+        // ignore if global config doesn't exist
+    }
+    return null;
+}
+/**
+ * Searches the entire directory tree from startPath to find all .ruler directories.
+ * Returns an array of .ruler directory paths from most specific to least specific.
+ */
+async function findAllRulerDirs(startPath) {
+    const rulerDirs = [];
+    // Search the entire directory tree downwards from startPath
+    async function findRulerDirs(dir) {
+        try {
+            const entries = await fs_1.promises.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    if (entry.name === '.ruler') {
+                        rulerDirs.push(fullPath);
+                    }
+                    else {
+                        // Recursively search subdirectories (but skip hidden directories like .git)
+                        if (!entry.name.startsWith('.')) {
+                            await findRulerDirs(fullPath);
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // ignore errors when reading directories
+        }
+    }
+    // Start searching from the startPath
+    await findRulerDirs(startPath);
+    // Sort by depth (most specific first) - deeper paths come first
+    rulerDirs.sort((a, b) => {
+        const depthA = a.split(path.sep).length;
+        const depthB = b.split(path.sep).length;
+        if (depthA !== depthB) {
+            return depthB - depthA; // Deeper paths first
+        }
+        return a.localeCompare(b); // Alphabetical for same depth
+    });
+    return rulerDirs;
+}

package/dist/core/UnifiedConfigLoader.js

@@ -79,11 +79,18 @@ async function loadUnifiedConfig(options) {
         Array.isArray(tomlRaw.default_agents)) {
         defaultAgents = tomlRaw.default_agents.map((a) => String(a));
     }
+    let nested = false;
+    if (tomlRaw &&
+        typeof tomlRaw === 'object' &&
+        typeof tomlRaw.nested === 'boolean') {
+        nested = tomlRaw.nested;
+    }
     const toml = {
         raw: tomlRaw,
         schemaVersion: 1,
         agents: {},
         defaultAgents,
+        nested,
     };
     // Collect rule markdown files
     let ruleFiles = [];

package/dist/core/apply-engine.js

@@ -33,8 +33,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadRulerConfiguration = loadRulerConfiguration;
+exports.loadNestedConfigurations = loadNestedConfigurations;
+exports.loadSingleConfiguration = loadSingleConfiguration;
 exports.selectAgentsToRun = selectAgentsToRun;
+exports.processHierarchicalConfigurations = processHierarchicalConfigurations;
+exports.processSingleConfiguration = processSingleConfiguration;
 exports.applyConfigurationsToAgents = applyConfigurationsToAgents;
 exports.updateGitignore = updateGitignore;
 const path = __importStar(require("path"));
@@ -49,27 +52,99 @@ const propagateOpenCodeMcp_1 = require("../mcp/propagateOpenCodeMcp");
 const agent_utils_1 = require("../agents/agent-utils");
 const capabilities_1 = require("../mcp/capabilities");
 const constants_1 = require("../constants");
+async function loadNestedConfigurations(projectRoot, configPath, localOnly) {
+    const { dirs: rulerDirs } = await findRulerDirectories(projectRoot, localOnly, true);
+    const rootConfig = await (0, ConfigLoader_1.loadConfig)({
+        projectRoot,
+        configPath,
+    });
+    const results = [];
+    const rulerDirConfigs = await processIndependentRulerDirs(rulerDirs);
+    for (const { rulerDir, files } of rulerDirConfigs) {
+        results.push(await createHierarchicalConfiguration(rulerDir, files, rootConfig));
+    }
+    return results;
+}
 /**
- * Loads all necessary configurations for ruler operation.
- * @param projectRoot Root directory of the project
- * @param configPath Optional custom config path
- * @param localOnly Whether to search only locally for .ruler directory
- * @returns Promise resolving to the loaded configuration
+ * Processes each .ruler directory independently, returning configuration for each.
+ * Each .ruler directory gets its own rules (not merged with others).
  */
-async function loadRulerConfiguration(projectRoot, configPath, localOnly) {
-    // Find the .ruler directory
-    const rulerDir = await FileSystemUtils.findRulerDir(projectRoot, !localOnly);
-    if (!rulerDir) {
-        throw (0, constants_1.createRulerError)(`.ruler directory not found`, `Searched from: ${projectRoot}`);
+async function processIndependentRulerDirs(rulerDirs) {
+    const results = [];
+    // Process each .ruler directory independently
+    for (const rulerDir of rulerDirs) {
+        const files = await FileSystemUtils.readMarkdownFiles(rulerDir);
+        results.push({ rulerDir, files });
     }
+    return results;
+}
+async function createHierarchicalConfiguration(rulerDir, files, rootConfig) {
+    await warnAboutLegacyMcpJson(rulerDir);
+    const concatenatedRules = (0, RuleProcessor_1.concatenateRules)(files, path.dirname(rulerDir));
+    return {
+        rulerDir,
+        config: rootConfig,
+        concatenatedRules,
+        rulerMcpJson: null, // No nested MCP support - each level uses root config only
+    };
+}
+/**
+ * Finds ruler directories based on the specified mode.
+ */
+async function findRulerDirectories(projectRoot, localOnly, hierarchical) {
+    if (hierarchical) {
+        const dirs = await FileSystemUtils.findAllRulerDirs(projectRoot);
+        const allDirs = [...dirs];
+        // Add global config if not local-only
+        if (!localOnly) {
+            const globalDir = await FileSystemUtils.findGlobalRulerDir();
+            if (globalDir) {
+                allDirs.push(globalDir);
+            }
+        }
+        if (allDirs.length === 0) {
+            throw (0, constants_1.createRulerError)(`.ruler directory not found`, `Searched from: ${projectRoot}`);
+        }
+        return { dirs: allDirs, primaryDir: allDirs[0] };
+    }
+    else {
+        const dir = await FileSystemUtils.findRulerDir(projectRoot, !localOnly);
+        if (!dir) {
+            throw (0, constants_1.createRulerError)(`.ruler directory not found`, `Searched from: ${projectRoot}`);
+        }
+        return { dirs: [dir], primaryDir: dir };
+    }
+}
+/**
+ * Warns about legacy mcp.json files if they exist.
+ */
+async function warnAboutLegacyMcpJson(rulerDir) {
+    try {
+        const legacyMcpPath = path.join(rulerDir, 'mcp.json');
+        await (await Promise.resolve().then(() => __importStar(require('fs/promises')))).access(legacyMcpPath);
+        console.warn('[ruler] Warning: Using legacy .ruler/mcp.json. Please migrate to ruler.toml. This fallback will be removed in a future release.');
+    }
+    catch {
+        // ignore
+    }
+}
+/**
+ * Loads configuration for single-directory mode (existing behavior).
+ */
+async function loadSingleConfiguration(projectRoot, configPath, localOnly) {
+    // Find the single ruler directory
+    const { dirs: rulerDirs, primaryDir } = await findRulerDirectories(projectRoot, localOnly, false);
+    // Warn about legacy mcp.json
+    await warnAboutLegacyMcpJson(primaryDir);
     // Load the ruler.toml configuration
     const config = await (0, ConfigLoader_1.loadConfig)({
         projectRoot,
         configPath,
     });
-    // Read and concatenate the markdown rule files
-    const files = await FileSystemUtils.readMarkdownFiles(rulerDir);
-    const concatenatedRules = (0, RuleProcessor_1.concatenateRules)(files, path.dirname(rulerDir));
+    // Read rule files
+    const files = await FileSystemUtils.readMarkdownFiles(rulerDirs[0]);
+    // Concatenate rules
+    const concatenatedRules = (0, RuleProcessor_1.concatenateRules)(files, path.dirname(primaryDir));
     // Load unified config to get merged MCP configuration
     const { loadUnifiedConfig } = await Promise.resolve().then(() => __importStar(require('./UnifiedConfigLoader')));
     const unifiedConfig = await loadUnifiedConfig({ projectRoot, configPath });
@@ -133,7 +208,43 @@ function selectAgentsToRun(allAgents, config) {
     return selected;
 }
 /**
- * Applies configurations to the selected agents.
+ * Processes hierarchical configurations by applying rules to each .ruler directory independently.
+ * Each directory gets its own set of rules and generates its own agent files.
+ * @param agents Array of agents to process
+ * @param configurations Array of hierarchical configurations for each .ruler directory
+ * @param verbose Whether to enable verbose logging
+ * @param dryRun Whether to perform a dry run
+ * @param cliMcpEnabled Whether MCP is enabled via CLI
+ * @param cliMcpStrategy MCP strategy from CLI
+ * @returns Promise resolving to array of generated file paths
+ */
+async function processHierarchicalConfigurations(agents, configurations, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup = true) {
+    const allGeneratedPaths = [];
+    for (const config of configurations) {
+        console.log(`[ruler] Processing .ruler directory: ${config.rulerDir}`);
+        const rulerRoot = path.dirname(config.rulerDir);
+        const paths = await applyConfigurationsToAgents(agents, config.concatenatedRules, config.rulerMcpJson, config.config, rulerRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
+        allGeneratedPaths.push(...paths);
+    }
+    return allGeneratedPaths;
+}
+/**
+ * Processes a single configuration by applying rules to all selected agents.
+ * All rules are concatenated and applied to generate agent files in the project root.
+ * @param agents Array of agents to process
+ * @param configuration Single ruler configuration with concatenated rules
+ * @param projectRoot Root directory of the project
+ * @param verbose Whether to enable verbose logging
+ * @param dryRun Whether to perform a dry run
+ * @param cliMcpEnabled Whether MCP is enabled via CLI
+ * @param cliMcpStrategy MCP strategy from CLI
+ * @returns Promise resolving to array of generated file paths
+ */
+async function processSingleConfiguration(agents, configuration, projectRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup = true) {
+    return await applyConfigurationsToAgents(agents, configuration.concatenatedRules, configuration.rulerMcpJson, configuration.config, projectRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
+}
+/**
+ * Applies configurations to the selected agents (internal function).
  * @param agents Array of agents to process
  * @param concatenatedRules Concatenated rule content
  * @param rulerMcpJson MCP configuration JSON
@@ -143,7 +254,7 @@ function selectAgentsToRun(allAgents, config) {
  * @param dryRun Whether to perform a dry run
  * @returns Promise resolving to array of generated file paths
  */
-async function applyConfigurationsToAgents(agents, concatenatedRules, rulerMcpJson, config, projectRoot, verbose, dryRun, cliMcpEnabled = true, cliMcpStrategy) {
+async function applyConfigurationsToAgents(agents, concatenatedRules, rulerMcpJson, config, projectRoot, verbose, dryRun, cliMcpEnabled = true, cliMcpStrategy, backup = true) {
     const generatedPaths = [];
     let agentsMdWritten = false;
     for (const agent of agents) {
@@ -155,9 +266,11 @@ async function applyConfigurationsToAgents(agents, concatenatedRules, rulerMcpJs
         const outputPaths = (0, agent_utils_1.getAgentOutputPaths)(agent, projectRoot, agentConfig);
         (0, constants_1.logVerbose)(`Agent ${agent.getName()} output paths: ${outputPaths.join(', ')}`, verbose);
         generatedPaths.push(...outputPaths);
-        // Also add the backup file paths to the gitignore list
-        const backupPaths = outputPaths.map((p) => `${p}.bak`);
-        generatedPaths.push(...backupPaths);
+        // Only add the backup file paths to the gitignore list if backups are enabled
+        if (backup) {
+            const backupPaths = outputPaths.map((p) => `${p}.bak`);
+            generatedPaths.push(...backupPaths);
+        }
         if (dryRun) {
             (0, constants_1.logVerbose)(`DRY RUN: Would write rules to: ${outputPaths.join(', ')}`, verbose);
         }
@@ -188,80 +301,89 @@ async function applyConfigurationsToAgents(agents, concatenatedRules, rulerMcpJs
                 };
             }
             if (!skipApplyForThisAgent) {
-                await agent.applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, finalAgentConfig);
+                await agent.applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, finalAgentConfig, backup);
             }
         }
         // Handle MCP configuration
-        await handleMcpConfiguration(agent, agentConfig, config, rulerMcpJson, projectRoot, generatedPaths, verbose, dryRun, cliMcpEnabled, cliMcpStrategy);
+        await handleMcpConfiguration(agent, agentConfig, config, rulerMcpJson, projectRoot, generatedPaths, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
     }
     return generatedPaths;
 }
-/**
- * Handles MCP configuration for a specific agent.
- */
-async function handleMcpConfiguration(agent, agentConfig, config, rulerMcpJson, projectRoot, generatedPaths, verbose, dryRun, cliMcpEnabled = true, cliMcpStrategy) {
-    // Check if agent supports MCP at all
+async function handleMcpConfiguration(agent, agentConfig, config, rulerMcpJson, projectRoot, generatedPaths, verbose, dryRun, cliMcpEnabled = true, cliMcpStrategy, backup = true) {
     if (!(0, capabilities_1.agentSupportsMcp)(agent)) {
         (0, constants_1.logVerbose)(`Agent ${agent.getName()} does not support MCP - skipping MCP configuration`, verbose);
         return;
     }
     const dest = await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
     const mcpEnabledForAgent = cliMcpEnabled && (agentConfig?.mcp?.enabled ?? config.mcp?.enabled ?? true);
-    if (dest && mcpEnabledForAgent && rulerMcpJson) {
-        // Filter MCP configuration based on agent capabilities
-        const filteredMcpJson = (0, capabilities_1.filterMcpConfigForAgent)(rulerMcpJson, agent);
-        if (!filteredMcpJson) {
-            (0, constants_1.logVerbose)(`No compatible MCP servers found for ${agent.getName()} - skipping MCP configuration`, verbose);
-            return;
-        }
-        // Include MCP config file in .gitignore only if it's within the project directory
-        if (dest.startsWith(projectRoot)) {
-            const relativeDest = path.relative(projectRoot, dest);
-            generatedPaths.push(relativeDest);
-            // Also add the backup for the MCP file
+    if (!dest || !mcpEnabledForAgent || !rulerMcpJson) {
+        return;
+    }
+    const filteredMcpJson = (0, capabilities_1.filterMcpConfigForAgent)(rulerMcpJson, agent);
+    if (!filteredMcpJson) {
+        (0, constants_1.logVerbose)(`No compatible MCP servers found for ${agent.getName()} - skipping MCP configuration`, verbose);
+        return;
+    }
+    await updateGitignoreForMcpFile(dest, projectRoot, generatedPaths, backup);
+    await applyMcpConfiguration(agent, filteredMcpJson, dest, agentConfig, config, projectRoot, cliMcpStrategy, dryRun, verbose, backup);
+}
+async function updateGitignoreForMcpFile(dest, projectRoot, generatedPaths, backup = true) {
+    if (dest.startsWith(projectRoot)) {
+        const relativeDest = path.relative(projectRoot, dest);
+        generatedPaths.push(relativeDest);
+        if (backup) {
             generatedPaths.push(`${relativeDest}.bak`);
         }
-        // Prevent writing MCP configs outside the project root (e.g., legacy home-directory targets)
-        if (!dest.startsWith(projectRoot)) {
-            (0, constants_1.logVerbose)(`Skipping MCP config for ${agent.getName()} because target path is outside project: ${dest}`, verbose);
-            return;
-        }
-        if (agent.getIdentifier() === 'openhands') {
-            // *** Special handling for Open Hands ***
-            if (dryRun) {
-                (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config by updating TOML file: ${dest}`, verbose);
-            }
-            else {
-                await (0, propagateOpenHandsMcp_1.propagateMcpToOpenHands)(filteredMcpJson, dest);
-            }
-        }
-        else if (agent.getIdentifier() === 'opencode') {
-            // *** Special handling for OpenCode ***
-            if (dryRun) {
-                (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config by updating OpenCode config file: ${dest}`, verbose);
-            }
-            else {
-                await (0, propagateOpenCodeMcp_1.propagateMcpToOpenCode)(filteredMcpJson, dest);
-            }
-        }
-        else {
-            // Standard MCP handling using capabilities
-            const strategy = cliMcpStrategy ??
-                agentConfig?.mcp?.strategy ??
-                config.mcp?.strategy ??
-                'merge';
-            // Determine the correct server key for the agent
-            const serverKey = agent.getMcpServerKey?.() || 'mcpServers';
-            (0, constants_1.logVerbose)(`Applying filtered MCP config for ${agent.getName()} with strategy: ${strategy} and key: ${serverKey}`, verbose);
-            if (dryRun) {
-                (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config to: ${dest}`, verbose);
-            }
-            else {
-                const existing = await (0, mcp_1.readNativeMcp)(dest);
-                const merged = (0, merge_1.mergeMcp)(existing, filteredMcpJson, strategy, serverKey);
-                await (0, mcp_1.writeNativeMcp)(dest, merged);
-            }
+    }
+}
+async function applyMcpConfiguration(agent, filteredMcpJson, dest, agentConfig, config, projectRoot, cliMcpStrategy, dryRun, verbose, backup = true) {
+    // Prevent writing MCP configs outside the project root (e.g., legacy home-directory targets)
+    if (!dest.startsWith(projectRoot)) {
+        (0, constants_1.logVerbose)(`Skipping MCP config for ${agent.getName()} because target path is outside project: ${dest}`, verbose);
+        return;
+    }
+    if (agent.getIdentifier() === 'openhands') {
+        return await applyOpenHandsMcpConfiguration(filteredMcpJson, dest, dryRun, verbose, backup);
+    }
+    if (agent.getIdentifier() === 'opencode') {
+        return await applyOpenCodeMcpConfiguration(filteredMcpJson, dest, dryRun, verbose, backup);
+    }
+    return await applyStandardMcpConfiguration(agent, filteredMcpJson, dest, agentConfig, config, cliMcpStrategy, dryRun, verbose, backup);
+}
+async function applyOpenHandsMcpConfiguration(filteredMcpJson, dest, dryRun, verbose, backup = true) {
+    if (dryRun) {
+        (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config by updating TOML file: ${dest}`, verbose);
+    }
+    else {
+        await (0, propagateOpenHandsMcp_1.propagateMcpToOpenHands)(filteredMcpJson, dest, backup);
+    }
+}
+async function applyOpenCodeMcpConfiguration(filteredMcpJson, dest, dryRun, verbose, backup = true) {
+    if (dryRun) {
+        (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config by updating OpenCode config file: ${dest}`, verbose);
+    }
+    else {
+        await (0, propagateOpenCodeMcp_1.propagateMcpToOpenCode)(filteredMcpJson, dest, backup);
+    }
+}
+async function applyStandardMcpConfiguration(agent, filteredMcpJson, dest, agentConfig, config, cliMcpStrategy, dryRun, verbose, backup = true) {
+    const strategy = cliMcpStrategy ??
+        agentConfig?.mcp?.strategy ??
+        config.mcp?.strategy ??
+        'merge';
+    const serverKey = agent.getMcpServerKey?.() ?? 'mcpServers';
+    (0, constants_1.logVerbose)(`Applying filtered MCP config for ${agent.getName()} with strategy: ${strategy} and key: ${serverKey}`, verbose);
+    if (dryRun) {
+        (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config to: ${dest}`, verbose);
+    }
+    else {
+        if (backup) {
+            const { backupFile } = await Promise.resolve().then(() => __importStar(require('../core/FileSystemUtils')));
+            await backupFile(dest);
         }
+        const existing = await (0, mcp_1.readNativeMcp)(dest);
+        const merged = (0, merge_1.mergeMcp)(existing, filteredMcpJson, strategy, serverKey);
+        await (0, mcp_1.writeNativeMcp)(dest, merged);
     }
 }
 /**
@@ -272,7 +394,7 @@ async function handleMcpConfiguration(agent, agentConfig, config, rulerMcpJson,
  * @param cliGitignoreEnabled CLI gitignore setting
  * @param dryRun Whether to perform a dry run
  */
-async function updateGitignore(projectRoot, generatedPaths, config, cliGitignoreEnabled, dryRun) {
+async function updateGitignore(projectRoot, generatedPaths, config, cliGitignoreEnabled, dryRun, backup = true) {
     // Configuration precedence: CLI > TOML > Default (enabled)
     let gitignoreEnabled;
     if (cliGitignoreEnabled !== undefined) {
@@ -286,8 +408,10 @@ async function updateGitignore(projectRoot, generatedPaths, config, cliGitignore
     }
     if (gitignoreEnabled && generatedPaths.length > 0) {
         const uniquePaths = [...new Set(generatedPaths)];
-        // Add wildcard pattern for backup files
-        uniquePaths.push('*.bak');
+        // Add wildcard pattern for backup files only if backup is enabled
+        if (backup) {
+            uniquePaths.push('*.bak');
+        }
         if (uniquePaths.length > 0) {
             const prefix = (0, constants_1.actionPrefix)(dryRun);
             if (dryRun) {

package/dist/lib.js

@@ -17,24 +17,51 @@ const agents = agents_1.allAgents;
  * @param projectRoot Root directory of the project
  * @param includedAgents Optional list of agent name filters (case-insensitive substrings)
  */
-async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cliMcpEnabled = true, cliMcpStrategy, cliGitignoreEnabled, verbose = false, dryRun = false, localOnly = false) {
+async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cliMcpEnabled = true, cliMcpStrategy, cliGitignoreEnabled, verbose = false, dryRun = false, localOnly = false, nested = false, backup = true) {
     // Load configuration and rules
     (0, constants_1.logVerbose)(`Loading configuration from project root: ${projectRoot}`, verbose);
     if (configPath) {
         (0, constants_1.logVerbose)(`Using custom config path: ${configPath}`, verbose);
     }
-    const rulerConfiguration = await (0, apply_engine_1.loadRulerConfiguration)(projectRoot, configPath, localOnly);
-    // Add CLI agents to the configuration
-    rulerConfiguration.config.cliAgents = includedAgents;
-    (0, constants_1.logVerbose)(`Loaded configuration with ${Object.keys(rulerConfiguration.config.agentConfigs).length} agent configs`, verbose);
-    (0, constants_1.logVerbose)(`Found .ruler directory with ${rulerConfiguration.concatenatedRules.length} characters of rules`, verbose);
+    let selectedAgents;
+    let generatedPaths;
+    let loadedConfig;
+    if (nested) {
+        const hierarchicalConfigs = await (0, apply_engine_1.loadNestedConfigurations)(projectRoot, configPath, localOnly);
+        if (hierarchicalConfigs.length === 0) {
+            throw new Error('No .ruler directories found');
+        }
+        // Use the root config for agent selection (all levels share the same agent settings)
+        const rootConfig = hierarchicalConfigs[0].config;
+        loadedConfig = rootConfig;
+        rootConfig.cliAgents = includedAgents;
+        (0, constants_1.logVerbose)(`Loaded ${hierarchicalConfigs.length} .ruler directory configurations`, verbose);
+        (0, constants_1.logVerbose)(`Root configuration has ${Object.keys(rootConfig.agentConfigs).length} agent configs`, verbose);
+        normalizeAgentConfigs(rootConfig, agents);
+        selectedAgents = (0, apply_engine_1.selectAgentsToRun)(agents, rootConfig);
+        (0, constants_1.logVerbose)(`Selected ${selectedAgents.length} agents: ${selectedAgents.map((a) => a.getName()).join(', ')}`, verbose);
+        generatedPaths = await (0, apply_engine_1.processHierarchicalConfigurations)(selectedAgents, hierarchicalConfigs, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
+    }
+    else {
+        const singleConfig = await (0, apply_engine_1.loadSingleConfiguration)(projectRoot, configPath, localOnly);
+        loadedConfig = singleConfig.config;
+        singleConfig.config.cliAgents = includedAgents;
+        (0, constants_1.logVerbose)(`Loaded configuration with ${Object.keys(singleConfig.config.agentConfigs).length} agent configs`, verbose);
+        (0, constants_1.logVerbose)(`Found .ruler directory with ${singleConfig.concatenatedRules.length} characters of rules`, verbose);
+        normalizeAgentConfigs(singleConfig.config, agents);
+        selectedAgents = (0, apply_engine_1.selectAgentsToRun)(agents, singleConfig.config);
+        (0, constants_1.logVerbose)(`Selected ${selectedAgents.length} agents: ${selectedAgents.map((a) => a.getName()).join(', ')}`, verbose);
+        generatedPaths = await (0, apply_engine_1.processSingleConfiguration)(selectedAgents, singleConfig, projectRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
+    }
+    await (0, apply_engine_1.updateGitignore)(projectRoot, generatedPaths, loadedConfig, cliGitignoreEnabled, dryRun, backup);
+}
+/**
+ * Normalizes per-agent config keys to agent identifiers for consistent lookup.
+ * Maps both exact identifier matches and substring matches with agent names.
+ * @param config The configuration object to normalize
+ * @param agents Array of available agents
+ */
+function normalizeAgentConfigs(config, agents) {
     // Normalize per-agent config keys to agent identifiers (exact match or substring match)
-    rulerConfiguration.config.agentConfigs = (0, config_utils_1.mapRawAgentConfigs)(rulerConfiguration.config.agentConfigs, agents);
-    // Select agents to run
-    const selectedAgents = (0, apply_engine_1.selectAgentsToRun)(agents, rulerConfiguration.config);
-    (0, constants_1.logVerbose)(`Selected ${selectedAgents.length} agents: ${selectedAgents.map((a) => a.getName()).join(', ')}`, verbose);
-    // Apply configurations to agents
-    const generatedPaths = await (0, apply_engine_1.applyConfigurationsToAgents)(selectedAgents, rulerConfiguration.concatenatedRules, rulerConfiguration.rulerMcpJson, rulerConfiguration.config, projectRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy);
-    // Update .gitignore
-    await (0, apply_engine_1.updateGitignore)(projectRoot, generatedPaths, rulerConfiguration.config, cliGitignoreEnabled, dryRun);
+    config.agentConfigs = (0, config_utils_1.mapRawAgentConfigs)(config.agentConfigs, agents);
 }

package/dist/mcp/propagateOpenCodeMcp.js

@@ -85,7 +85,7 @@ function transformToOpenCodeFormat(rulerMcp) {
         mcp: openCodeServers,
     };
 }
-async function propagateMcpToOpenCode(rulerMcpData, openCodeConfigPath) {
+async function propagateMcpToOpenCode(rulerMcpData, openCodeConfigPath, backup = true) {
     const rulerMcp = rulerMcpData || {};
     // Read existing OpenCode config if it exists
     let existingConfig = {};
@@ -108,5 +108,9 @@ async function propagateMcpToOpenCode(rulerMcpData, openCodeConfigPath) {
         },
     };
     await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(openCodeConfigPath));
+    if (backup) {
+        const { backupFile } = await Promise.resolve().then(() => __importStar(require('../core/FileSystemUtils')));
+        await backupFile(openCodeConfigPath);
+    }
     await fs.writeFile(openCodeConfigPath, JSON.stringify(finalConfig, null, 2) + '\n');
 }

package/dist/mcp/propagateOpenHandsMcp.js

@@ -90,7 +90,7 @@ function normalizeRemoteServerArray(entries) {
     // All entries are strings, keep as is
     return entries;
 }
-async function propagateMcpToOpenHands(rulerMcpData, openHandsConfigPath) {
+async function propagateMcpToOpenHands(rulerMcpData, openHandsConfigPath, backup = true) {
     const rulerMcp = rulerMcpData || {};
     // Always use the legacy Ruler MCP config format as input (top-level "mcpServers" key)
     const rulerServers = rulerMcp.mcpServers || {};
@@ -162,5 +162,9 @@ async function propagateMcpToOpenHands(rulerMcpData, openHandsConfigPath) {
     config.mcp.sse_servers = normalizeRemoteServerArray(Array.from(existingSseServers.values()));
     config.mcp.shttp_servers = normalizeRemoteServerArray(Array.from(existingShttpServers.values()));
     await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(openHandsConfigPath));
+    if (backup) {
+        const { backupFile } = await Promise.resolve().then(() => __importStar(require('../core/FileSystemUtils')));
+        await backupFile(openHandsConfigPath);
+    }
     await fs.writeFile(openHandsConfigPath, (0, toml_1.stringify)(config));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intellectronica/ruler",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Ruler — apply the same rules to all coding agents",
   "main": "dist/lib.js",
   "scripts": {