@intellectronica/ruler 0.1.1 → 0.1.3

package/README.md

@@ -1,3 +1,7 @@
+> **Experimental Research Preview**
+> - Please test this version with caution in your own setup
+> - File issues at https://github.com/intellectronica/ruler/issues
+
 # Ruler
 
 A CLI tool to manage custom rules and configs across different AI coding agents.
@@ -35,7 +39,14 @@ Create a `.ruler/` directory at your project root and add Markdown files definin
 Run the apply command:
 
 ```bash
-ruler apply [--project-root <path>] [--agents <agent1,agent2,...>]
+ruler apply [--project-root <path>] [--agents <agent1,agent2,...>] [--config <path>] [--gitignore] [--no-gitignore]
+```
+
+
+Run the init command to scaffold a basic `.ruler/` setup:
+
+```bash
+ruler init [--project-root <path>]
 ```
 
 Use `--agents` to specify a comma-separated list of agent names (case-insensitive substrings) to limit which agents the rules are applied to.
@@ -52,6 +63,141 @@ The command will read all `.md` files under `.ruler/`, concatenate their content
 | Cline                  | `.clinerules`                                               |
 | Aider                  | `ruler_aider_instructions.md` <br>and updates `.aider.conf.yml` |
 
+## Configuration
+
+Ruler uses a TOML configuration file located at `.ruler/ruler.toml` by default. You can override its location with the `--config <path>` option in the `apply` command.
+
+### Configuration structure
+
+```toml
+# Run only these agents by default (omit to use all agents)
+# default_agents = ["GitHub Copilot", "Claude Code", "Aider"]
+
+[agents.Copilot]
+enabled = true
+output_path = ".github/copilot-instructions.md"
+
+[agents.Claude]
+enabled = true
+# output_path = "CLAUDE.md"
+
+[agents.Aider]
+enabled = false
+# output_path_instructions = "ruler_aider_instructions.md"
+# output_path_config = ".aider.conf.yml"
+```
+
+- `default_agents`: array of agent names (case-insensitive substrings) to run by default.
+- `[agents.<AgentName>]`: per-agent settings:
+  - `enabled` (boolean): enable or disable this agent.
+  - `output_path` (string): custom path for agents that produce a single file.
+  - `output_path_instructions`/`output_path_config`: custom paths for Aider's instruction and config files.
+
+### Precedence
+
+1. CLI `--agents` option (substring filters)
+2. Config file `default_agents` and `[agents]` overrides
+3. Built-in defaults (all agents enabled, standard output paths)
+
+## MCP servers
+
+Ruler can propagate a project-level `.ruler/mcp.json` file to native MCP configurations of supported agents, merging (or overwriting) each agent’s existing MCP server settings.
+
+### `.ruler/mcp.json`
+
+Place your MCP servers config in a file at `.ruler/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com"
+    }
+  }
+}
+```
+
+### CLI flags
+
+| Flag              | Effect                                                       |
+|-------------------|--------------------------------------------------------------|
+| `--with-mcp`      | Enable writing MCP configs for all agents (default)          |
+| `--no-mcp`        | Disable writing MCP configs                                 |
+| `--mcp-overwrite` | Overwrite native MCP configs instead of merging              |
+
+### Configuration (`ruler.toml`)
+
+Configure default behavior in your `ruler.toml`:
+
+```toml
+[mcp]
+enabled = true
+merge_strategy = "merge"  # or "overwrite"
+
+[agents.Cursor.mcp]
+enabled = false
+merge_strategy = "overwrite"
+```
+
+## .gitignore Integration
+
+Ruler automatically adds generated agent configuration files to your project's `.gitignore` file to prevent them from being committed to version control. This ensures that the AI agent configuration files remain local to each developer's environment.
+
+### Behavior
+
+When `ruler apply` runs, it will:
+- Create or update a `.gitignore` file in your project root
+- Add all generated file paths to a managed block marked with `# START Ruler Generated Files` and `# END Ruler Generated Files`
+- Preserve any existing `.gitignore` content outside the managed block
+- Sort paths alphabetically within the Ruler block
+- Use relative POSIX-style paths (forward slashes)
+
+### CLI flags
+
+| Flag              | Effect                                                       |
+|-------------------|--------------------------------------------------------------|
+| `--gitignore`     | Enable automatic .gitignore updates (default)               |
+| `--no-gitignore`  | Disable automatic .gitignore updates                        |
+
+### Configuration (`ruler.toml`)
+
+Configure the default behavior in your `ruler.toml`:
+
+```toml
+[gitignore]
+enabled = true  # or false to disable by default
+```
+
+### Precedence
+
+The configuration precedence for .gitignore updates is:
+
+1. CLI flags (`--gitignore` or `--no-gitignore`)
+2. Configuration file `[gitignore].enabled` setting
+3. Default behavior (enabled)
+
+### Example
+
+After running `ruler apply`, your `.gitignore` might look like:
+
+```gitignore
+node_modules/
+*.log
+
+# START Ruler Generated Files
+.aider.conf.yml
+.clinerules
+.cursor/rules/ruler_cursor_instructions.md
+.github/copilot-instructions.md
+.windsurf/rules/ruler_windsurf_instructions.md
+AGENTS.md
+CLAUDE.md
+ruler_aider_instructions.md
+# END Ruler Generated Files
+
+dist/
+```
+
 ## Development
 
 Clone the repository and install dependencies:
@@ -82,13 +228,6 @@ End-to-end tests (run build before tests):
 npm run build && npm test
 ```
 
-### Roadmap
-- [ ] Support for MCP servers config
-- [ ] Support for transforming and rewriting the rules using AI
-- [ ] Support "harmonisation" (reading existing rules of specific agents and combining them with the master config)
-- [ ] Support for additional agents
-- [ ] Support for agent-specific features (for example: apply rules in copilot)
-
 ## Contributing
 
 Contributions are welcome! Please open issues or pull requests on GitHub.

package/dist/agents/AiderAgent.js

@@ -45,11 +45,13 @@ class AiderAgent {
     getName() {
         return 'Aider';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot) {
-        const mdFile = path.join(projectRoot, 'ruler_aider_instructions.md');
-        await (0, FileSystemUtils_1.backupFile)(mdFile);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(mdFile, concatenatedRules);
-        const cfgPath = path.join(projectRoot, '.aider.conf.yml');
+    async applyRulerConfig(concatenatedRules, projectRoot, agentConfig) {
+        const mdPath = agentConfig?.outputPathInstructions ??
+            this.getDefaultOutputPath(projectRoot).instructions;
+        await (0, FileSystemUtils_1.backupFile)(mdPath);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(mdPath, concatenatedRules);
+        const cfgPath = agentConfig?.outputPathConfig ??
+            this.getDefaultOutputPath(projectRoot).config;
         let doc = {};
         try {
             await fs.access(cfgPath);
@@ -63,11 +65,18 @@ class AiderAgent {
         if (!Array.isArray(doc.read)) {
             doc.read = [];
         }
-        if (!doc.read.includes('ruler_aider_instructions.md')) {
-            doc.read.push('ruler_aider_instructions.md');
+        const name = path.basename(mdPath);
+        if (!doc.read.includes(name)) {
+            doc.read.push(name);
         }
         const yamlStr = yaml.dump(doc);
         await (0, FileSystemUtils_1.writeGeneratedFile)(cfgPath, yamlStr);
     }
+    getDefaultOutputPath(projectRoot) {
+        return {
+            instructions: path.join(projectRoot, 'ruler_aider_instructions.md'),
+            config: path.join(projectRoot, '.aider.conf.yml'),
+        };
+    }
 }
 exports.AiderAgent = AiderAgent;

package/dist/agents/ClaudeAgent.js

@@ -43,10 +43,13 @@ class ClaudeAgent {
     getName() {
         return 'Claude Code';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot) {
-        const target = path.join(projectRoot, 'CLAUDE.md');
-        await (0, FileSystemUtils_1.backupFile)(target);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(target, concatenatedRules);
+    async applyRulerConfig(concatenatedRules, projectRoot, agentConfig) {
+        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        await (0, FileSystemUtils_1.backupFile)(output);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(output, concatenatedRules);
+    }
+    getDefaultOutputPath(projectRoot) {
+        return path.join(projectRoot, 'CLAUDE.md');
     }
 }
 exports.ClaudeAgent = ClaudeAgent;

package/dist/agents/ClineAgent.js

@@ -43,10 +43,13 @@ class ClineAgent {
     getName() {
         return 'Cline';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot) {
-        const target = path.join(projectRoot, '.clinerules');
-        await (0, FileSystemUtils_1.backupFile)(target);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(target, concatenatedRules);
+    async applyRulerConfig(concatenatedRules, projectRoot, agentConfig) {
+        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        await (0, FileSystemUtils_1.backupFile)(output);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(output, concatenatedRules);
+    }
+    getDefaultOutputPath(projectRoot) {
+        return path.join(projectRoot, '.clinerules');
     }
 }
 exports.ClineAgent = ClineAgent;

package/dist/agents/CodexCliAgent.js

@@ -43,10 +43,13 @@ class CodexCliAgent {
     getName() {
         return 'OpenAI Codex CLI';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot) {
-        const target = path.join(projectRoot, 'AGENTS.md');
-        await (0, FileSystemUtils_1.backupFile)(target);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(target, concatenatedRules);
+    async applyRulerConfig(concatenatedRules, projectRoot, agentConfig) {
+        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        await (0, FileSystemUtils_1.backupFile)(output);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(output, concatenatedRules);
+    }
+    getDefaultOutputPath(projectRoot) {
+        return path.join(projectRoot, 'AGENTS.md');
     }
 }
 exports.CodexCliAgent = CodexCliAgent;

package/dist/agents/CopilotAgent.js

@@ -43,12 +43,14 @@ class CopilotAgent {
     getName() {
         return 'GitHub Copilot';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot) {
-        const targetDir = path.join(projectRoot, '.github');
-        await (0, FileSystemUtils_1.ensureDirExists)(targetDir);
-        const target = path.join(targetDir, 'copilot-instructions.md');
-        await (0, FileSystemUtils_1.backupFile)(target);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(target, concatenatedRules);
+    async applyRulerConfig(concatenatedRules, projectRoot, agentConfig) {
+        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(output));
+        await (0, FileSystemUtils_1.backupFile)(output);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(output, concatenatedRules);
+    }
+    getDefaultOutputPath(projectRoot) {
+        return path.join(projectRoot, '.github', 'copilot-instructions.md');
     }
 }
 exports.CopilotAgent = CopilotAgent;

package/dist/agents/CursorAgent.js

@@ -43,12 +43,14 @@ class CursorAgent {
     getName() {
         return 'Cursor';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot) {
-        const targetDir = path.join(projectRoot, '.cursor', 'rules');
-        await (0, FileSystemUtils_1.ensureDirExists)(targetDir);
-        const target = path.join(targetDir, 'ruler_cursor_instructions.md');
-        await (0, FileSystemUtils_1.backupFile)(target);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(target, concatenatedRules);
+    async applyRulerConfig(concatenatedRules, projectRoot, agentConfig) {
+        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(output));
+        await (0, FileSystemUtils_1.backupFile)(output);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(output, concatenatedRules);
+    }
+    getDefaultOutputPath(projectRoot) {
+        return path.join(projectRoot, '.cursor', 'rules', 'ruler_cursor_instructions.md');
     }
 }
 exports.CursorAgent = CursorAgent;

package/dist/agents/WindsurfAgent.js

@@ -43,12 +43,14 @@ class WindsurfAgent {
     getName() {
         return 'Windsurf';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot) {
-        const targetDir = path.join(projectRoot, '.windsurf', 'rules');
-        await (0, FileSystemUtils_1.ensureDirExists)(targetDir);
-        const target = path.join(targetDir, 'ruler_windsurf_instructions.md');
-        await (0, FileSystemUtils_1.backupFile)(target);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(target, concatenatedRules);
+    async applyRulerConfig(concatenatedRules, projectRoot, agentConfig) {
+        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(output));
+        await (0, FileSystemUtils_1.backupFile)(output);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(output, concatenatedRules);
+    }
+    getDefaultOutputPath(projectRoot) {
+        return path.join(projectRoot, '.windsurf', 'rules', 'ruler_windsurf_instructions.md');
     }
 }
 exports.WindsurfAgent = WindsurfAgent;

package/dist/cli/commands.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -7,6 +40,8 @@ exports.run = run;
 const yargs_1 = __importDefault(require("yargs"));
 const helpers_1 = require("yargs/helpers");
 const lib_1 = require("../lib");
+const path = __importStar(require("path"));
+const fs_1 = require("fs");
 /**
  * Sets up and parses CLI commands.
  */
@@ -24,13 +59,46 @@ function run() {
             type: 'string',
             description: 'Comma-separated list of agent names to include (e.g. "copilot,claude")',
         });
+        y.option('config', {
+            type: 'string',
+            description: 'Path to TOML configuration file',
+        });
+        y.option('mcp', {
+            type: 'boolean',
+            description: 'Enable or disable applying MCP server config',
+            default: true,
+        });
+        y.alias('mcp', 'with-mcp');
+        y.option('mcp-overwrite', {
+            type: 'boolean',
+            description: 'Replace (not merge) the native MCP config(s)',
+            default: false,
+        });
+        y.option('gitignore', {
+            type: 'boolean',
+            description: 'Enable/disable automatic .gitignore updates (default: enabled)',
+        });
     }, async (argv) => {
         const projectRoot = argv['project-root'];
         const agents = argv.agents
             ? argv.agents.split(',').map((a) => a.trim())
             : undefined;
+        const configPath = argv.config;
+        const mcpEnabled = argv.mcp;
+        const mcpStrategy = argv['mcp-overwrite']
+            ? 'overwrite'
+            : undefined;
+        // Determine gitignore preference: CLI > TOML > Default (enabled)
+        // yargs handles --no-gitignore by setting gitignore to false
+        let gitignorePreference;
+        if (argv.gitignore !== undefined) {
+            gitignorePreference = argv.gitignore;
+        }
+        else {
+            gitignorePreference = undefined; // Let TOML/default decide
+        }
         try {
-            await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents);
+            await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference);
             console.log('Ruler apply completed successfully.');
         }
         catch (err) {
@@ -38,6 +106,104 @@ function run() {
             console.error('Error applying ruler configurations:', message);
             process.exit(1);
         }
+    })
+        .command('init', 'Scaffold a .ruler directory with default files', (y) => {
+        y.option('project-root', {
+            type: 'string',
+            description: 'Project root directory',
+            default: process.cwd(),
+        });
+    }, async (argv) => {
+        const projectRoot = argv['project-root'];
+        const rulerDir = path.join(projectRoot, '.ruler');
+        await fs_1.promises.mkdir(rulerDir, { recursive: true });
+        const instructionsPath = path.join(rulerDir, 'instructions.md');
+        const tomlPath = path.join(rulerDir, 'ruler.toml');
+        const exists = async (p) => {
+            try {
+                await fs_1.promises.access(p);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const DEFAULT_INSTRUCTIONS = `# Ruler Instructions
+
+These are your centralised AI agent instructions.
+Add your coding guidelines, style guides, and other project-specific context here.
+
+Ruler will concatenate all .md files in this directory (and its subdirectories)
+and apply them to your configured AI coding agents.
+`;
+        const DEFAULT_TOML = `# Ruler Configuration File
+# See https://ai.intellectronica.net/ruler for documentation.
+
+# To specify which agents are active by default when --agents is not used,
+# uncomment and populate the following line. If omitted, all agents are active.
+# default_agents = ["Copilot", "Claude"]
+
+# --- Agent Specific Configurations ---
+# You can enable/disable agents and override their default output paths here.
+
+# [agents.GitHubCopilot]
+# enabled = true
+# output_path = ".github/copilot-instructions.md"
+
+# [agents.ClaudeCode]
+# enabled = true
+# output_path = "CLAUDE.md"
+
+# [agents.OpenAICodexCLI]
+# enabled = true
+# output_path = "AGENTS.md"
+
+# [agents.Cursor]
+# enabled = true
+# output_path = ".cursor/rules/ruler_cursor_instructions.md"
+
+# [agents.Windsurf]
+# enabled = true
+# output_path = ".windsurf/rules/ruler_windsurf_instructions.md"
+
+# [agents.Cline]
+# enabled = true
+# output_path = ".clinerules"
+
+# [agents.Aider]
+# enabled = true
+# output_path_instructions = "ruler_aider_instructions.md"
+# output_path_config = ".aider.conf.yml"
+`;
+        if (!(await exists(instructionsPath))) {
+            await fs_1.promises.writeFile(instructionsPath, DEFAULT_INSTRUCTIONS);
+            console.log(`[ruler] Created ${instructionsPath}`);
+        }
+        else {
+            console.log(`[ruler] instructions.md already exists, skipping`);
+        }
+        if (!(await exists(tomlPath))) {
+            await fs_1.promises.writeFile(tomlPath, DEFAULT_TOML);
+            console.log(`[ruler] Created ${tomlPath}`);
+        }
+        else {
+            console.log(`[ruler] ruler.toml already exists, skipping`);
+        }
+        const mcpPath = path.join(rulerDir, 'mcp.json');
+        const DEFAULT_MCP_JSON = `{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com"
+    }
+  }
+}`;
+        if (!(await exists(mcpPath))) {
+            await fs_1.promises.writeFile(mcpPath, DEFAULT_MCP_JSON);
+            console.log(`[ruler] Created ${mcpPath}`);
+        }
+        else {
+            console.log(`[ruler] mcp.json already exists, skipping`);
+        }
     })
         .demandCommand(1, 'You need to specify a command')
         .help()

package/dist/core/ConfigLoader.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const toml_1 = __importDefault(require("toml"));
+/**
+ * Loads and parses the ruler TOML configuration file, applying defaults.
+ * If the file is missing or invalid, returns empty/default config.
+ */
+async function loadConfig(options) {
+    const { projectRoot, configPath, cliAgents } = options;
+    const configFile = configPath
+        ? path.resolve(configPath)
+        : path.join(projectRoot, '.ruler', 'ruler.toml');
+    let raw = {};
+    try {
+        const text = await fs_1.promises.readFile(configFile, 'utf8');
+        raw = text.trim() ? toml_1.default.parse(text) : {};
+    }
+    catch (err) {
+        if (err instanceof Error && err.code !== 'ENOENT') {
+            console.warn(`[ruler] Warning: could not read config file at ${configFile}: ${err.message}`);
+        }
+        raw = {};
+    }
+    const defaultAgents = Array.isArray(raw.default_agents)
+        ? raw.default_agents.map((a) => String(a))
+        : undefined;
+    const agentsSection = raw.agents && typeof raw.agents === 'object' && !Array.isArray(raw.agents)
+        ? raw.agents
+        : {};
+    const agentConfigs = {};
+    for (const [name, section] of Object.entries(agentsSection)) {
+        if (section && typeof section === 'object') {
+            const sectionObj = section;
+            const cfg = {};
+            if (typeof sectionObj.enabled === 'boolean') {
+                cfg.enabled = sectionObj.enabled;
+            }
+            if (typeof sectionObj.output_path === 'string') {
+                cfg.outputPath = path.resolve(projectRoot, sectionObj.output_path);
+            }
+            if (typeof sectionObj.output_path_instructions === 'string') {
+                cfg.outputPathInstructions = path.resolve(projectRoot, sectionObj.output_path_instructions);
+            }
+            if (typeof sectionObj.output_path_config === 'string') {
+                cfg.outputPathConfig = path.resolve(projectRoot, sectionObj.output_path_config);
+            }
+            if (sectionObj.mcp && typeof sectionObj.mcp === 'object') {
+                const m = sectionObj.mcp;
+                const mcpCfg = {};
+                if (typeof m.enabled === 'boolean') {
+                    mcpCfg.enabled = m.enabled;
+                }
+                if (typeof m.merge_strategy === 'string') {
+                    const ms = m.merge_strategy;
+                    if (ms === 'merge' || ms === 'overwrite') {
+                        mcpCfg.strategy = ms;
+                    }
+                }
+                cfg.mcp = mcpCfg;
+            }
+            agentConfigs[name] = cfg;
+        }
+    }
+    const rawMcpSection = raw.mcp && typeof raw.mcp === 'object' && !Array.isArray(raw.mcp)
+        ? raw.mcp
+        : {};
+    const globalMcpConfig = {};
+    if (typeof rawMcpSection.enabled === 'boolean') {
+        globalMcpConfig.enabled = rawMcpSection.enabled;
+    }
+    if (typeof rawMcpSection.merge_strategy === 'string') {
+        const strat = rawMcpSection.merge_strategy;
+        if (strat === 'merge' || strat === 'overwrite') {
+            globalMcpConfig.strategy = strat;
+        }
+    }
+    const rawGitignoreSection = raw.gitignore &&
+        typeof raw.gitignore === 'object' &&
+        !Array.isArray(raw.gitignore)
+        ? raw.gitignore
+        : {};
+    const gitignoreConfig = {};
+    if (typeof rawGitignoreSection.enabled === 'boolean') {
+        gitignoreConfig.enabled = rawGitignoreSection.enabled;
+    }
+    return {
+        defaultAgents,
+        agentConfigs,
+        cliAgents,
+        mcp: globalMcpConfig,
+        gitignore: gitignoreConfig,
+    };
+}

package/dist/core/GitignoreUtils.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateGitignore = updateGitignore;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const RULER_START_MARKER = '# START Ruler Generated Files';
+const RULER_END_MARKER = '# END Ruler Generated Files';
+/**
+ * Updates the .gitignore file in the project root with paths in a managed Ruler block.
+ * Creates the file if it doesn't exist, and creates or updates the Ruler-managed block.
+ *
+ * @param projectRoot The project root directory (where .gitignore should be located)
+ * @param paths Array of file paths to add to .gitignore (can be absolute or relative)
+ */
+async function updateGitignore(projectRoot, paths) {
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    // Read existing .gitignore or start with empty content
+    let existingContent = '';
+    try {
+        existingContent = await fs_1.promises.readFile(gitignorePath, 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+    // Convert paths to relative POSIX format
+    const relativePaths = paths.map((p) => {
+        const relative = path.isAbsolute(p) ? path.relative(projectRoot, p) : p;
+        return relative.replace(/\\/g, '/'); // Convert to POSIX format
+    });
+    // Get all existing paths from .gitignore (excluding Ruler block)
+    const existingPaths = getExistingPathsExcludingRulerBlock(existingContent);
+    // Filter out paths that already exist outside the Ruler block
+    const newPaths = relativePaths.filter((p) => !existingPaths.includes(p));
+    // The Ruler block should contain only the new paths (replacement behavior)
+    const allRulerPaths = [...new Set(newPaths)].sort();
+    // Create new content
+    const newContent = updateGitignoreContent(existingContent, allRulerPaths);
+    // Write the updated content
+    await fs_1.promises.writeFile(gitignorePath, newContent);
+}
+/**
+ * Gets all paths from .gitignore content excluding those in the Ruler block.
+ */
+function getExistingPathsExcludingRulerBlock(content) {
+    const lines = content.split('\n');
+    const paths = [];
+    let inRulerBlock = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === RULER_START_MARKER) {
+            inRulerBlock = true;
+            continue;
+        }
+        if (trimmed === RULER_END_MARKER) {
+            inRulerBlock = false;
+            continue;
+        }
+        if (!inRulerBlock && trimmed && !trimmed.startsWith('#')) {
+            paths.push(trimmed);
+        }
+    }
+    return paths;
+}
+/**
+ * Updates the .gitignore content by replacing or adding the Ruler block.
+ */
+function updateGitignoreContent(existingContent, rulerPaths) {
+    const lines = existingContent.split('\n');
+    const newLines = [];
+    let inFirstRulerBlock = false;
+    let hasRulerBlock = false;
+    let processedFirstBlock = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === RULER_START_MARKER && !processedFirstBlock) {
+            inFirstRulerBlock = true;
+            hasRulerBlock = true;
+            newLines.push(line);
+            // Add the new Ruler paths
+            rulerPaths.forEach((p) => newLines.push(p));
+            continue;
+        }
+        if (trimmed === RULER_END_MARKER && inFirstRulerBlock) {
+            inFirstRulerBlock = false;
+            processedFirstBlock = true;
+            newLines.push(line);
+            continue;
+        }
+        if (!inFirstRulerBlock) {
+            newLines.push(line);
+        }
+        // Skip lines that are in the first Ruler block (they get replaced)
+    }
+    // If no Ruler block exists, add one at the end
+    if (!hasRulerBlock) {
+        // Add blank line if content exists and doesn't end with blank line
+        if (existingContent.trim() && !existingContent.endsWith('\n\n')) {
+            newLines.push('');
+        }
+        newLines.push(RULER_START_MARKER);
+        rulerPaths.forEach((p) => newLines.push(p));
+        newLines.push(RULER_END_MARKER);
+    }
+    // Ensure file ends with a newline
+    let result = newLines.join('\n');
+    if (!result.endsWith('\n')) {
+        result += '\n';
+    }
+    return result;
+}

package/dist/lib.js

@@ -35,8 +35,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyAllAgentConfigs = applyAllAgentConfigs;
 const path = __importStar(require("path"));
-const FileSystemUtils_1 = require("./core/FileSystemUtils");
+const fs_1 = require("fs");
+const FileSystemUtils = __importStar(require("./core/FileSystemUtils"));
 const RuleProcessor_1 = require("./core/RuleProcessor");
+const ConfigLoader_1 = require("./core/ConfigLoader");
+const GitignoreUtils_1 = require("./core/GitignoreUtils");
 const CopilotAgent_1 = require("./agents/CopilotAgent");
 const ClaudeAgent_1 = require("./agents/ClaudeAgent");
 const CodexCliAgent_1 = require("./agents/CodexCliAgent");
@@ -44,6 +47,43 @@ const CursorAgent_1 = require("./agents/CursorAgent");
 const WindsurfAgent_1 = require("./agents/WindsurfAgent");
 const ClineAgent_1 = require("./agents/ClineAgent");
 const AiderAgent_1 = require("./agents/AiderAgent");
+const merge_1 = require("./mcp/merge");
+const validate_1 = require("./mcp/validate");
+const mcp_1 = require("./paths/mcp");
+/**
+ * Gets all output paths for an agent, taking into account any config overrides.
+ */
+function getAgentOutputPaths(agent, projectRoot, agentConfig) {
+    const paths = [];
+    const defaults = agent.getDefaultOutputPath(projectRoot);
+    if (typeof defaults === 'string') {
+        // Single output path (most agents)
+        const actualPath = agentConfig?.outputPath ?? defaults;
+        paths.push(actualPath);
+    }
+    else {
+        // Multiple output paths (e.g., AiderAgent)
+        const defaultPaths = defaults;
+        // Handle instructions path
+        if ('instructions' in defaultPaths) {
+            const instructionsPath = agentConfig?.outputPathInstructions ?? defaultPaths.instructions;
+            paths.push(instructionsPath);
+        }
+        // Handle config path
+        if ('config' in defaultPaths) {
+            const configPath = agentConfig?.outputPathConfig ?? defaultPaths.config;
+            paths.push(configPath);
+        }
+        // Handle any other paths in the default paths record
+        for (const [key, defaultPath] of Object.entries(defaultPaths)) {
+            if (key !== 'instructions' && key !== 'config') {
+                // For unknown path types, use the default since we don't have specific config overrides
+                paths.push(defaultPath);
+            }
+        }
+    }
+    return paths;
+}
 const agents = [
     new CopilotAgent_1.CopilotAgent(),
     new ClaudeAgent_1.ClaudeAgent(),
@@ -62,21 +102,106 @@ const agents = [
  * @param projectRoot Root directory of the project
  * @param includedAgents Optional list of agent name filters (case-insensitive substrings)
  */
-async function applyAllAgentConfigs(projectRoot, includedAgents) {
-    const rulerDir = await (0, FileSystemUtils_1.findRulerDir)(projectRoot);
+async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cliMcpEnabled = true, cliMcpStrategy, cliGitignoreEnabled) {
+    // Load configuration (default_agents, per-agent overrides, CLI filters)
+    const config = await (0, ConfigLoader_1.loadConfig)({
+        projectRoot,
+        cliAgents: includedAgents,
+        configPath,
+    });
+    // Normalize per-agent config keys to actual agent names (substring match)
+    const rawConfigs = config.agentConfigs;
+    const mappedConfigs = {};
+    for (const [key, cfg] of Object.entries(rawConfigs)) {
+        const lowerKey = key.toLowerCase();
+        for (const agent of agents) {
+            if (agent.getName().toLowerCase().includes(lowerKey)) {
+                mappedConfigs[agent.getName()] = cfg;
+            }
+        }
+    }
+    config.agentConfigs = mappedConfigs;
+    const rulerDir = await FileSystemUtils.findRulerDir(projectRoot);
     if (!rulerDir) {
         throw new Error(`.ruler directory not found from ${projectRoot}`);
     }
-    await (0, FileSystemUtils_1.ensureDirExists)(path.join(rulerDir, 'generated'));
-    const files = await (0, FileSystemUtils_1.readMarkdownFiles)(rulerDir);
+    await FileSystemUtils.ensureDirExists(path.join(rulerDir, 'generated'));
+    const files = await FileSystemUtils.readMarkdownFiles(rulerDir);
     const concatenated = (0, RuleProcessor_1.concatenateRules)(files);
+    const mcpFile = path.join(rulerDir, 'mcp.json');
+    let rulerMcpJson = null;
+    try {
+        const raw = await fs_1.promises.readFile(mcpFile, 'utf8');
+        rulerMcpJson = JSON.parse(raw);
+        (0, validate_1.validateMcp)(rulerMcpJson);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+    // Determine which agents to run:
+    // CLI --agents > config.default_agents > per-agent.enabled flags > default all
     let selected = agents;
-    if (includedAgents && includedAgents.length > 0) {
-        const filters = includedAgents.map((n) => n.toLowerCase());
+    if (config.cliAgents && config.cliAgents.length > 0) {
+        const filters = config.cliAgents.map((n) => n.toLowerCase());
         selected = agents.filter((agent) => filters.some((f) => agent.getName().toLowerCase().includes(f)));
     }
+    else if (config.defaultAgents && config.defaultAgents.length > 0) {
+        const defaults = config.defaultAgents.map((n) => n.toLowerCase());
+        selected = agents.filter((agent) => {
+            const key = agent.getName();
+            const override = config.agentConfigs[key]?.enabled;
+            if (override !== undefined) {
+                return override;
+            }
+            return defaults.includes(key.toLowerCase());
+        });
+    }
+    else {
+        selected = agents.filter((agent) => config.agentConfigs[agent.getName()]?.enabled !== false);
+    }
+    // Collect all generated file paths for .gitignore
+    const generatedPaths = [];
     for (const agent of selected) {
         console.log(`[ruler] Applying rules for ${agent.getName()}...`);
-        await agent.applyRulerConfig(concatenated, projectRoot);
+        const agentConfig = config.agentConfigs[agent.getName()];
+        await agent.applyRulerConfig(concatenated, projectRoot, agentConfig);
+        // Collect output paths for .gitignore
+        const outputPaths = getAgentOutputPaths(agent, projectRoot, agentConfig);
+        generatedPaths.push(...outputPaths);
+        const dest = await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
+        const enabled = cliMcpEnabled &&
+            (agentConfig?.mcp?.enabled ?? config.mcp?.enabled ?? true);
+        if (dest && rulerMcpJson != null && enabled) {
+            const strategy = cliMcpStrategy ??
+                agentConfig?.mcp?.strategy ??
+                config.mcp?.strategy ??
+                'merge';
+            const existing = await (0, mcp_1.readNativeMcp)(dest);
+            const merged = (0, merge_1.mergeMcp)(existing, rulerMcpJson, strategy);
+            await (0, mcp_1.writeNativeMcp)(dest, merged);
+        }
+    }
+    // Handle .gitignore updates
+    // Configuration precedence: CLI > TOML > Default (enabled)
+    let gitignoreEnabled;
+    if (cliGitignoreEnabled !== undefined) {
+        gitignoreEnabled = cliGitignoreEnabled;
+    }
+    else if (config.gitignore?.enabled !== undefined) {
+        gitignoreEnabled = config.gitignore.enabled;
+    }
+    else {
+        gitignoreEnabled = true; // Default enabled
+    }
+    if (gitignoreEnabled && generatedPaths.length > 0) {
+        // Filter out .bak files as specified in requirements
+        const pathsToIgnore = generatedPaths.filter((p) => !p.endsWith('.bak'));
+        const uniquePaths = [...new Set(pathsToIgnore)];
+        if (uniquePaths.length > 0) {
+            await (0, GitignoreUtils_1.updateGitignore)(projectRoot, uniquePaths);
+            console.log(`[ruler] Updated .gitignore with ${uniquePaths.length} unique path(s) in the Ruler block.`);
+        }
     }
 }

package/dist/mcp/merge.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeMcp = mergeMcp;
+/**
+ * Merge native and incoming MCP server configurations according to strategy.
+ * @param base Existing native MCP config object.
+ * @param incoming Ruler MCP config object.
+ * @param strategy Merge strategy: 'merge' to union servers, 'overwrite' to replace.
+ * @returns Merged MCP config object.
+ */
+function mergeMcp(base, incoming, strategy) {
+    if (strategy === 'overwrite') {
+        return incoming;
+    }
+    const baseServers = base.mcpServers || {};
+    const incomingServers = incoming.mcpServers || {};
+    return {
+        ...base,
+        mcpServers: { ...baseServers, ...incomingServers },
+    };
+}

package/dist/mcp/validate.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateMcp = validateMcp;
+/**
+ * Validate the structure of the Ruler MCP JSON config.
+ * Minimal validation: ensure 'mcpServers' property exists and is an object.
+ * @param data Parsed JSON object from .ruler/mcp.json.
+ * @throws Error if validation fails.
+ */
+function validateMcp(data) {
+    if (!data ||
+        typeof data !== 'object' ||
+        !('mcpServers' in data) ||
+        typeof data.mcpServers !== 'object') {
+        throw new Error('[ruler] Invalid .ruler/mcp.json: must contain an object property "mcpServers"');
+    }
+}

package/dist/paths/mcp.js

@@ -0,0 +1,100 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNativeMcpPath = getNativeMcpPath;
+exports.readNativeMcp = readNativeMcp;
+exports.writeNativeMcp = writeNativeMcp;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const fs_1 = require("fs");
+/** Determine the native MCP config path for a given agent. */
+async function getNativeMcpPath(adapterName, projectRoot) {
+    const home = os.homedir();
+    const candidates = [];
+    switch (adapterName) {
+        case 'GitHub Copilot':
+            candidates.push(path.join(projectRoot, '.vscode', 'mcp.json'));
+            break;
+        case 'Visual Studio':
+            candidates.push(path.join(projectRoot, '.mcp.json'));
+            candidates.push(path.join(projectRoot, '.vs', 'mcp.json'));
+            break;
+        case 'Cursor':
+            candidates.push(path.join(projectRoot, '.cursor', 'mcp.json'));
+            candidates.push(path.join(home, '.cursor', 'mcp.json'));
+            break;
+        case 'Windsurf':
+            candidates.push(path.join(home, '.codeium', 'windsurf', 'mcp_config.json'));
+            break;
+        case 'Claude Code':
+            candidates.push(path.join(projectRoot, 'claude_desktop_config.json'));
+            break;
+        case 'OpenAI Codex CLI':
+            candidates.push(path.join(home, '.codex', 'config.json'));
+            break;
+        case 'Aider':
+            candidates.push(path.join(projectRoot, '.mcp.json'));
+            break;
+        default:
+            return null;
+    }
+    for (const p of candidates) {
+        try {
+            await fs_1.promises.access(p);
+            return p;
+        }
+        catch {
+            // continue
+        }
+    }
+    // default to first candidate if none exist
+    return candidates.length > 0 ? candidates[0] : null;
+}
+/** Read native MCP config from disk, or return empty object if missing/invalid. */
+async function readNativeMcp(filePath) {
+    try {
+        const text = await fs_1.promises.readFile(filePath, 'utf8');
+        return JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+}
+/** Write native MCP config to disk, creating parent directories as needed. */
+async function writeNativeMcp(filePath, data) {
+    await fs_1.promises.mkdir(path.dirname(filePath), { recursive: true });
+    const text = JSON.stringify(data, null, 2) + '\n';
+    await fs_1.promises.writeFile(filePath, text, 'utf8');
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intellectronica/ruler",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Ruler — apply the same rules to all coding agents",
   "main": "dist/lib.js",
   "scripts": {
@@ -57,6 +57,7 @@
   },
   "dependencies": {
     "js-yaml": "^4.1.0",
+    "toml": "^3.0.0",
     "yargs": "^17.7.2"
   }
 }