@intellectronica/ruler 0.3.41 → 0.3.43

package/README.md

@@ -18,7 +18,7 @@
       </p>
     </td>
     <td style="vertical-align: top; width:33%;">
-      <img src="img/ruler-short.gif" alt="Ruler demo" style="width:300px; height:auto; display:block;" />
+      <img src="https://raw.githubusercontent.com/intellectronica/ruler/main/img/ruler-short.gif" alt="Ruler demo" style="width:300px; height:auto; display:block;" />
     </td>
   </tr>
 </table>
@@ -59,7 +59,7 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 | AGENTS.md              | `AGENTS.md`                                    | (pseudo-agent ensuring root `AGENTS.md` exists)  | -                         | -                            |
 | GitHub Copilot         | `AGENTS.md`                                    | `.vscode/mcp.json`                               | `.claude/skills/`         | `.github/agents/`            |
 | Claude Code            | `CLAUDE.md`                                    | `.mcp.json`                                      | `.claude/skills/`         | `.claude/agents/`            |
-| OpenAI Codex CLI       | `AGENTS.md`                                    | `.codex/config.toml`                             | `.codex/skills/`          | `.codex/agents/` (`.toml`)   |
+| OpenAI Codex CLI       | `AGENTS.md`                                    | `.codex/config.toml`                             | `.agents/skills/`         | `.codex/agents/` (`.toml`)   |
 | Pi Coding Agent        | `AGENTS.md`                                    | -                                                | `.pi/skills/`             | -                            |
 | Jules                  | `AGENTS.md`                                    | -                                                | -                         | -                            |
 | Cursor                 | `AGENTS.md`                                    | `.cursor/mcp.json`                               | `.cursor/skills/`         | `.cursor/agents/`            |
@@ -80,7 +80,7 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 | Goose                  | `.goosehints`                                  | -                                                | `.agents/skills/`         | -                            |
 | Qwen Code              | `AGENTS.md`                                    | `.qwen/settings.json`                            | -                         | -                            |
 | RooCode                | `AGENTS.md`                                    | `.roo/mcp.json`                                  | `.roo/skills/`            | -                            |
-| Zed                    | `AGENTS.md`                                    | `.zed/settings.json` (project root, never $HOME) | -                         | -                            |
+| Zed                    | `AGENTS.md`                                    | `.zed/settings.json` (project root, never $HOME) | `.agents/skills/`         | -                            |
 | Trae AI                | `.trae/rules/project_rules.md`                 | -                                                | -                         | -                            |
 | Warp                   | `WARP.md`                                      | -                                                | -                         | -                            |
 | Kiro                   | `.kiro/steering/ruler_kiro_instructions.md`    | `.kiro/settings/mcp.json`                        | -                         | -                            |
@@ -224,32 +224,32 @@ project/
 ruler apply [options]
 ```
 
-The `apply` command looks for `.ruler/` in the current directory tree, reading the first match. If no such directory is found, it will look for a global configuration in `$XDG_CONFIG_HOME/ruler`.
+The `apply` command searches upward from `--project-root` (default: current directory) for the nearest `.ruler/` directory. If no local `.ruler/` directory is found, it falls back to `$XDG_CONFIG_HOME/ruler`.
 
 ### Options
 
-| Option                         | Description                                                            |
-| ------------------------------ | ---------------------------------------------------------------------- |
-| `--project-root <path>`        | Project root path (default: current directory).                        |
-| `--agents <agent1,agent2,...>` | Comma-separated agent names to target (see supported list below).      |
-| `--config <path>`              | Custom `ruler.toml` path.                                              |
-| `--mcp` / `--with-mcp`         | Enable applying MCP server configurations (default: true).             |
-| `--no-mcp`                     | Disable applying MCP server configurations.                            |
-| `--mcp-overwrite`              | Overwrite native MCP config instead of merging.                        |
-| `--gitignore`                  | Enable automatic .gitignore updates (default: true).                   |
-| `--no-gitignore`               | Disable automatic .gitignore updates.                                  |
-| `--gitignore-local`            | Write managed ignore entries to `.git/info/exclude` instead.           |
-| `--nested`                     | Enable nested rule loading (default: inherit from config or disabled). |
-| `--no-nested`                  | Disable nested rule loading even if `nested = true` in config.         |
-| `--backup`                     | Enable creation of `.bak` backup files (default: enabled).             |
-| `--no-backup`                  | Disable creation of `.bak` backup files.                               |
-| `--skills`                     | Enable skills support (experimental, default: enabled).                |
-| `--no-skills`                  | Disable skills support.                                                |
-| `--subagents`                  | Enable subagents support (experimental, default: disabled).            |
-| `--no-subagents`               | Disable subagents support.                                             |
-| `--dry-run`                    | Preview changes without writing files.                                 |
-| `--local-only`                 | Skip `$XDG_CONFIG_HOME` when looking for configuration.                |
-| `--verbose` / `-v`             | Display detailed output during execution.                              |
+| Option                         | Description                                                               |
+| ------------------------------ | ------------------------------------------------------------------------- |
+| `--project-root <path>`        | Project root path (default: current directory).                           |
+| `--agents <agent1,agent2,...>` | Comma-separated agent names to target (see supported list below).         |
+| `--config <path>`              | Custom `ruler.toml` path.                                                 |
+| `--mcp` / `--with-mcp`         | Enable applying MCP server configurations (default: true).                |
+| `--no-mcp`                     | Disable applying MCP server configurations.                               |
+| `--mcp-overwrite`              | Overwrite native MCP config instead of merging.                           |
+| `--gitignore`                  | Enable automatic .gitignore updates (default: true).                      |
+| `--no-gitignore`               | Disable automatic .gitignore updates.                                     |
+| `--gitignore-local`            | Write managed ignore entries to `.git/info/exclude` instead.              |
+| `--nested`                     | Enable nested rule loading (default: inherit from config or disabled).    |
+| `--no-nested`                  | Disable nested rule loading even if `nested = true` in config.            |
+| `--backup`                     | Enable creation of `.bak` backup files (default: from config or enabled). |
+| `--no-backup`                  | Disable creation of `.bak` backup files.                                  |
+| `--skills`                     | Enable skills support (experimental, default: enabled).                   |
+| `--no-skills`                  | Disable skills support.                                                   |
+| `--subagents`                  | Enable subagents support (experimental, default: disabled).               |
+| `--no-subagents`               | Disable subagents support.                                                |
+| `--dry-run`                    | Preview changes without writing files.                                    |
+| `--local-only`                 | Skip `$XDG_CONFIG_HOME` when looking for configuration.                   |
+| `--verbose` / `-v`             | Display detailed output during execution.                                 |
 
 ### Common Examples
 
@@ -412,6 +412,11 @@ enabled = true
 # Write managed entries to .git/info/exclude instead of .gitignore (default: false)
 local = false
 
+# --- Backup Configuration ---
+[backup]
+# Enable/disable creation of .bak backup files (default: true)
+enabled = true
+
 # --- Agent-Specific Configurations ---
 [agents.copilot]
 enabled = true
@@ -509,6 +514,20 @@ Authorization = "Bearer your-token"
 "X-API-Version" = "v1"
 ```
 
+Agent-specific MCP servers can be defined under `[agents.<agent>.mcp_servers.<name>]`.
+They are applied only to that agent and override global servers with the same name:
+
+```toml
+[agents.cursor.mcp_servers.slack]
+url = "https://mcp.slack.com/mcp"
+auth = { CLIENT_ID = "CURSOR_ID" }
+
+[agents.claude.mcp_servers.slack]
+type = "http"
+url = "https://mcp.slack.com/mcp"
+oauth = { clientId = "CLAUDE_ID", callbackPort = 3118 }
+```
+
 ### Legacy `.ruler/mcp.json` (Deprecated)
 
 For backward compatibility, you can still use the JSON format; a warning is issued encouraging migration to TOML. The file is no longer created during `ruler init`.
@@ -587,11 +606,12 @@ Skills are specialized knowledge packages that extend AI agent capabilities with
   - **Claude Code**: `.claude/skills/`
   - **GitHub Copilot**: `.claude/skills/` (shared with Claude Code)
   - **Kilo Code**: `.claude/skills/` (shared with Claude Code)
-  - **OpenAI Codex CLI**: `.codex/skills/`
+  - **OpenAI Codex CLI**: `.agents/skills/` (shared with Goose, Amp, and Zed)
   - **OpenCode**: `.opencode/skills/`
   - **Pi Coding Agent**: `.pi/skills/`
   - **Goose**: `.agents/skills/`
   - **Amp**: `.agents/skills/` (shared with Goose)
+  - **Zed**: `.agents/skills/` (shared with Goose)
   - **Antigravity**: `.agent/skills/`
   - **Factory Droid**: `.factory/skills/`
   - **Mistral Vibe**: `.vibe/skills/`
@@ -655,10 +675,9 @@ If you run Ruler for agents that do not support native skills, Ruler logs a warn
 When skills support is enabled and gitignore integration is active, Ruler automatically adds:
 
 - `.claude/skills/` (for Claude Code, GitHub Copilot, and Kilo Code)
-- `.codex/skills/` (for OpenAI Codex CLI)
+- `.agents/skills/` (for OpenAI Codex CLI, Goose, Amp, and Zed)
 - `.opencode/skills/` (for OpenCode)
 - `.pi/skills/` (for Pi Coding Agent)
-- `.agents/skills/` (for Goose and Amp)
 - `.agent/skills/` (for Antigravity)
 - `.factory/skills/` (for Factory Droid)
 - `.vibe/skills/` (for Mistral Vibe)
@@ -672,7 +691,7 @@ to your `.gitignore` file within the managed Ruler block.
 
 ### Requirements
 
-- **For agents with native skills support** (Claude Code, GitHub Copilot, Kilo Code, OpenAI Codex CLI, OpenCode, Pi Coding Agent, Goose, Amp, Antigravity, Factory Droid, Mistral Vibe, Roo Code, Gemini CLI, Junie, Cursor, Windsurf): No additional requirements.
+- **For agents with native skills support** (Claude Code, GitHub Copilot, Kilo Code, OpenAI Codex CLI, OpenCode, Pi Coding Agent, Goose, Amp, Zed, Antigravity, Factory Droid, Mistral Vibe, Roo Code, Gemini CLI, Junie, Cursor, Windsurf): No additional requirements.
 
 ### Validation
 
@@ -716,10 +735,10 @@ ruler apply
 
 # 3. Skills are now available to compatible agents:
 #    - Claude Code, GitHub Copilot & Kilo Code: .claude/skills/my-skill/
-#    - OpenAI Codex CLI: .codex/skills/my-skill/
+#    - OpenAI Codex CLI: .agents/skills/my-skill/ (shared with Goose, Amp & Zed)
 #    - OpenCode: .opencode/skills/my-skill/
 #    - Pi Coding Agent: .pi/skills/my-skill/
-#    - Goose & Amp: .agents/skills/my-skill/
+#    - Goose, Amp, Zed & OpenAI Codex CLI: .agents/skills/my-skill/
 #    - Antigravity: .agent/skills/my-skill/
 #    - Factory Droid: .factory/skills/my-skill/
 #    - Mistral Vibe: .vibe/skills/my-skill/
@@ -909,6 +928,12 @@ dist/
 - **Configuration**: `[gitignore].enabled` and `[gitignore].local` in `ruler.toml`
 - **Default**: enabled
 
+### Backup Control
+
+- **CLI flags**: `--backup`, `--no-backup`
+- **Configuration**: `[backup].enabled` in `ruler.toml`
+- **Default**: enabled
+
 ## Practical Usage Scenarios
 
 ### Scenario 1: Getting Started Quickly
@@ -926,7 +951,81 @@ ruler init
 ruler apply
 ```
 
-### Scenario 2: Complex Projects with Nested Rules
+### Scenario 2: Working with worktrees
+
+When using the default `git add worktree` command (which is also run by agents apps such as Claude code or Codex through the interface), the gitignored files are not copied over. You will need to ask your agent to run `ruler apply` at the start of every session.
+
+As an alternative you can commit your default agents files to source control.
+
+```toml
+# .ruler/ruler.toml
+default_agents = ["claude", "codex"]
+
+[gitignore]
+enabled = false
+```
+
+```ignore
+# Do not ignore AGENTS.md and CLAUDE.md
+/.claude/*
+!/.claude/skills/
+/.codex/*
+!/.codex/skills/
+/.cursor
+/AGENTS.md.bak
+/CLAUDE.md.bak
+```
+
+To avoid having other contributors commit instructions outside of .ruler you can setup a github action to check there is no diff when running `ruler apply` in CI.
+
+```yml
+# .github/workflows/ruler-check/yml
+
+# Verifies the committed agent files (AGENTS.md, CLAUDE.md, skills) match the .ruler/ source.
+# They are committed so a fresh clone/worktree has guidance immediately; this guards against drift.
+name: Ruler guidance in sync
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - 'build/**'
+
+permissions:
+  contents: read
+
+env:
+  CI_NODE_VERSION: 24.15.0
+
+jobs:
+  ruler-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v5
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: 'pnpm'
+
+      - name: Verify committed agent files match .ruler/
+        run: |
+          pnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp
+          DRIFT="$(git status --porcelain -- AGENTS.md CLAUDE.md .claude/skills .codex/skills)"
+          if [ -n "$DRIFT" ]; then
+            echo "::error::Committed agent files are out of sync with .ruler/. Run 'pnpm dlx @intellectronica/ruler apply --no-gitignore --no-mcp' and commit the result."
+            echo "$DRIFT"
+            git --no-pager diff -- AGENTS.md CLAUDE.md .claude/skills .codex/skills
+            exit 1
+          fi
+          echo "Agent files are in sync with .ruler/."
+```
+
+### Scenario 3: Complex Projects with Nested Rules
 
 For large projects with multiple components or services, enable nested rule loading so each directory keeps its own rules and MCP bundle:
 
@@ -958,13 +1057,13 @@ This creates context-specific instructions for different parts of your project w
 > [!NOTE]
 > The CLI prints "Nested mode is experimental and may change in future releases." the first time nested processing runs. Expect refinements in future versions.
 
-### Scenario 3: Team Standardization
+### Scenario 4: Team Standardization
 
 1. Create `.ruler/coding_standards.md`, `.ruler/api_usage.md`
 2. Commit the `.ruler` directory to your repository
 3. Team members pull changes and run `ruler apply` to update their local AI agent configurations
 
-### Scenario 4: Project-Specific Context for AI
+### Scenario 5: Project-Specific Context for AI
 
 1. Detail your project's architecture in `.ruler/project_overview.md`
 2. Describe primary data structures in `.ruler/data_models.md`
@@ -1079,7 +1178,7 @@ A: Simply rename `.ruler/instructions.md` to `.ruler/AGENTS.md` (recommended). I
 A: Local stdio servers become `stdio_servers`. Remote URLs containing `/sse` are classified as `sse_servers`; others become `shttp_servers`. Bearer tokens in an `Authorization` header are extracted into `api_key` where possible.
 
 **Q: Where is Zed configuration written now?**
-A: Ruler writes a `settings.json` in the project root (not the user home dir) and transforms MCP server definitions to Zed's `context_servers` format including `source: "custom"`.
+A: Ruler writes `.zed/settings.json` inside the project root (not the user home dir) and transforms MCP server definitions to Zed's `context_servers` format including `source: "custom"`.
 
 **Q: What changed about MCP initialization?**
 A: `ruler init` now only adds example MCP server sections to `ruler.toml` instead of creating `.ruler/mcp.json`. The JSON file is still consumed if present, but TOML servers win on name conflicts.

package/dist/agents/AbstractAgent.d.ts

@@ -0,0 +1,53 @@
+import { IAgent, IAgentConfig } from './IAgent';
+/**
+ * Abstract base class for agents that write to a single configuration file.
+ * Implements common logic for applying ruler configuration.
+ */
+export declare abstract class AbstractAgent implements IAgent {
+    /**
+     * Returns the lowercase identifier of the agent.
+     */
+    abstract getIdentifier(): string;
+    /**
+     * Returns the display name of the agent.
+     */
+    abstract getName(): string;
+    /**
+     * Returns the default output path for this agent given the project root.
+     */
+    abstract getDefaultOutputPath(projectRoot: string): string;
+    /**
+     * Applies the concatenated ruler rules to the agent's configuration.
+     * This implementation handles the common pattern of:
+     * 1. Determining the output path
+     * 2. Ensuring the parent directory exists
+     * 3. Backing up the existing file
+     * 4. Writing the new content
+     */
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, _rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
+    /**
+     * Returns the specific key to be used for the server object in MCP JSON.
+     * Defaults to 'mcpServers' if not overridden.
+     */
+    getMcpServerKey(): string;
+    /**
+     * Returns whether this agent supports MCP STDIO servers.
+     * Defaults to false if not overridden.
+     */
+    supportsMcpStdio(): boolean;
+    /**
+     * Returns whether this agent supports MCP remote servers.
+     * Defaults to false if not overridden.
+     */
+    supportsMcpRemote(): boolean;
+    /**
+     * Returns whether this agent supports MCP server timeout configuration.
+     * Defaults to false if not overridden.
+     */
+    supportsMcpTimeout(): boolean;
+    /**
+     * Returns whether this agent has native skills support.
+     * Defaults to false if not overridden.
+     */
+    supportsNativeSkills(): boolean;
+}

package/dist/agents/AbstractAgent.js

@@ -52,11 +52,12 @@ class AbstractAgent {
     async applyRulerConfig(concatenatedRules, projectRoot, _rulerMcpJson, agentConfig, backup = true) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
         const absolutePath = path.resolve(projectRoot, output);
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(absolutePath, projectRoot, 'Refusing to write generated file outside project');
         await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
         if (backup) {
-            await (0, FileSystemUtils_1.backupFile)(absolutePath);
+            await (0, FileSystemUtils_1.backupFile)(absolutePath, projectRoot);
         }
-        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules, projectRoot);
     }
     /**
      * Returns the specific key to be used for the server object in MCP JSON.

package/dist/agents/AgentsMdAgent.d.ts

@@ -0,0 +1,14 @@
+import { AbstractAgent } from './AbstractAgent';
+import { IAgentConfig } from './IAgent';
+/**
+ * Pseudo-agent that ensures the concatenated rules are written to root-level `AGENTS.md`.
+ * Does not participate in MCP propagation. Idempotent: only writes (and creates a backup)
+ * when content differs from existing file.
+ */
+export declare class AgentsMdAgent extends AbstractAgent {
+    getIdentifier(): string;
+    getName(): string;
+    getDefaultOutputPath(projectRoot: string): string;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, _rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
+    getMcpServerKey(): string;
+}

package/dist/agents/AgentsMdAgent.js

@@ -56,6 +56,7 @@ class AgentsMdAgent extends AbstractAgent_1.AbstractAgent {
     async applyRulerConfig(concatenatedRules, projectRoot, _rulerMcpJson, agentConfig, backup = true) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
         const absolutePath = path.resolve(projectRoot, output);
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(absolutePath, projectRoot, 'Refusing to write generated file outside project');
         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}`;
@@ -73,9 +74,9 @@ class AgentsMdAgent extends AbstractAgent_1.AbstractAgent {
         }
         // 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.backupFile)(absolutePath, projectRoot);
         }
-        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, contentWithMarker);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, contentWithMarker, projectRoot);
     }
     getMcpServerKey() {
         // No MCP configuration for this pseudo-agent

package/dist/agents/AiderAgent.d.ts

@@ -0,0 +1,14 @@
+import { IAgent, IAgentConfig } from './IAgent';
+/**
+ * Aider agent adapter that uses AGENTS.md for instructions and .aider.conf.yml for configuration.
+ */
+export declare class AiderAgent implements IAgent {
+    private agentsMdAgent;
+    getIdentifier(): string;
+    getName(): string;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
+    getDefaultOutputPath(projectRoot: string): Record<string, string>;
+    getMcpServerKey(): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+}

package/dist/agents/AiderAgent.js

@@ -67,7 +67,7 @@ class AiderAgent {
         try {
             await fs.access(cfgPath);
             if (backup) {
-                await (0, FileSystemUtils_1.backupFile)(cfgPath);
+                await (0, FileSystemUtils_1.backupFile)(cfgPath, projectRoot);
             }
             const raw = await fs.readFile(cfgPath, 'utf8');
             doc = (yaml.load(raw) || {});
@@ -82,21 +82,24 @@ class AiderAgent {
         const agentsPath = agentConfig?.outputPath ||
             agentConfig?.outputPathInstructions ||
             this.getDefaultOutputPath(projectRoot).instructions;
-        const name = path.basename(agentsPath);
+        const name = path
+            .relative(projectRoot, path.resolve(projectRoot, agentsPath))
+            .replace(/\\/g, '/');
         if (!doc.read.includes(name)) {
             doc.read.push(name);
         }
         const yamlStr = yaml.dump(doc);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(cfgPath, yamlStr);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(cfgPath, yamlStr, projectRoot);
     }
     getDefaultOutputPath(projectRoot) {
         return {
             instructions: path.join(projectRoot, 'AGENTS.md'),
             config: path.join(projectRoot, '.aider.conf.yml'),
+            mcp: path.join(projectRoot, '.mcp.json'),
         };
     }
     getMcpServerKey() {
-        return this.agentsMdAgent.getMcpServerKey();
+        return 'mcpServers';
     }
     supportsMcpStdio() {
         return true;

package/dist/agents/AmazonQCliAgent.d.ts

@@ -0,0 +1,13 @@
+import { IAgent, IAgentConfig } from './IAgent';
+/**
+ * Amazon Q CLI agent adapter.
+ */
+export declare class AmazonQCliAgent implements IAgent {
+    getIdentifier(): string;
+    getName(): string;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
+    getDefaultOutputPath(projectRoot: string): Record<string, string>;
+    getMcpServerKey(): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+}

package/dist/agents/AmazonQCliAgent.js

@@ -54,16 +54,18 @@ class AmazonQCliAgent {
             agentConfig?.outputPathInstructions ||
             outputPaths['instructions']);
         // Write rules file to .amazonq/rules/
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(rulesPath, projectRoot, 'Refusing to write generated file outside project');
         await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(rulesPath));
         if (backup) {
-            await (0, FileSystemUtils_1.backupFile)(rulesPath);
+            await (0, FileSystemUtils_1.backupFile)(rulesPath, projectRoot);
         }
-        await (0, FileSystemUtils_1.writeGeneratedFile)(rulesPath, concatenatedRules);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(rulesPath, concatenatedRules, projectRoot);
         // Handle MCP configuration if enabled and provided
         const mcpEnabled = agentConfig?.mcp?.enabled ?? true;
         if (mcpEnabled && rulerMcpJson) {
             const mcpPath = path.resolve(projectRoot, agentConfig?.outputPathConfig ?? outputPaths['mcp']);
             const mcpStrategy = agentConfig?.mcp?.strategy ?? 'merge';
+            await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(mcpPath, projectRoot, 'Refusing to write generated file outside project');
             await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(mcpPath));
             let existingMcpConfig = {};
             try {
@@ -79,9 +81,9 @@ class AmazonQCliAgent {
             // Merge the MCP configurations using the standard merge function
             const mergedConfig = (0, merge_1.mergeMcp)(existingMcpConfig, rulerMcpJson, mcpStrategy, 'mcpServers');
             if (backup) {
-                await (0, FileSystemUtils_1.backupFile)(mcpPath);
+                await (0, FileSystemUtils_1.backupFile)(mcpPath, projectRoot);
             }
-            await (0, FileSystemUtils_1.writeGeneratedFile)(mcpPath, JSON.stringify(mergedConfig, null, 2));
+            await (0, FileSystemUtils_1.writeGeneratedFile)(mcpPath, JSON.stringify(mergedConfig, null, 2), projectRoot);
         }
     }
     getDefaultOutputPath(projectRoot) {

package/dist/agents/AmpAgent.d.ts

@@ -0,0 +1,6 @@
+import { AgentsMdAgent } from './AgentsMdAgent';
+export declare class AmpAgent extends AgentsMdAgent {
+    getIdentifier(): string;
+    getName(): string;
+    supportsNativeSkills(): boolean;
+}

package/dist/agents/AntigravityAgent.d.ts

@@ -0,0 +1,10 @@
+import { AbstractAgent } from './AbstractAgent';
+/**
+ * Antigravity agent adapter.
+ */
+export declare class AntigravityAgent extends AbstractAgent {
+    getIdentifier(): string;
+    getName(): string;
+    getDefaultOutputPath(projectRoot: string): string;
+    supportsNativeSkills(): boolean;
+}

package/dist/agents/AugmentCodeAgent.d.ts

@@ -0,0 +1,13 @@
+import { IAgent, IAgentConfig } from './IAgent';
+/**
+ * AugmentCode agent adapter.
+ * Generates ruler_augment_instructions.md configuration file and updates VSCode settings.json with MCP server configuration.
+ */
+export declare class AugmentCodeAgent implements IAgent {
+    getIdentifier(): string;
+    getName(): string;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, _rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
+    getDefaultOutputPath(projectRoot: string): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+}

package/dist/agents/AugmentCodeAgent.js

@@ -49,10 +49,11 @@ class AugmentCodeAgent {
     }
     async applyRulerConfig(concatenatedRules, projectRoot, _rulerMcpJson, agentConfig, backup = true) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        const absolutePath = path.resolve(projectRoot, output);
         if (backup) {
-            await (0, FileSystemUtils_1.backupFile)(output);
+            await (0, FileSystemUtils_1.backupFile)(absolutePath, projectRoot);
         }
-        await (0, FileSystemUtils_1.writeGeneratedFile)(output, concatenatedRules);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules, projectRoot);
         // AugmentCode does not support MCP servers
         // MCP configuration is ignored for this agent
     }

package/dist/agents/ClaudeAgent.d.ts

@@ -0,0 +1,13 @@
+import { AbstractAgent } from './AbstractAgent';
+/**
+ * Claude Code agent adapter.
+ */
+export declare class ClaudeAgent extends AbstractAgent {
+    getIdentifier(): string;
+    getName(): string;
+    getDefaultOutputPath(projectRoot: string): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+    supportsNativeSkills(): boolean;
+    supportsNativeSubagents(): boolean;
+}

package/dist/agents/ClineAgent.d.ts

@@ -0,0 +1,9 @@
+import { AbstractAgent } from './AbstractAgent';
+/**
+ * Cline agent adapter.
+ */
+export declare class ClineAgent extends AbstractAgent {
+    getIdentifier(): string;
+    getName(): string;
+    getDefaultOutputPath(projectRoot: string): string;
+}

package/dist/agents/CodexCliAgent.d.ts

@@ -0,0 +1,31 @@
+import { IAgent, IAgentConfig } from './IAgent';
+/**
+ * MCP server definition for Codex CLI (stdio uses command, remote uses url).
+ */
+interface McpServer {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    [key: string]: any;
+}
+interface RulerMcp {
+    mcpServers?: Record<string, McpServer>;
+}
+/**
+ * OpenAI Codex CLI agent adapter.
+ */
+export declare class CodexCliAgent implements IAgent {
+    private agentsMdAgent;
+    getIdentifier(): string;
+    getName(): string;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: RulerMcp | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
+    getDefaultOutputPath(projectRoot: string): Record<string, string>;
+    getMcpServerKey(): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+    supportsNativeSkills(): boolean;
+    supportsNativeSubagents(): boolean;
+}
+export {};

package/dist/agents/CodexCliAgent.js

@@ -128,7 +128,7 @@ class CodexCliAgent {
             const finalConfig = { ...updatedConfig };
             // @iarna/toml should handle the formatting properly
             const tomlContent = (0, toml_1.stringify)(finalConfig);
-            await (0, FileSystemUtils_1.writeGeneratedFile)(configPath, tomlContent);
+            await (0, FileSystemUtils_1.writeGeneratedFile)(configPath, tomlContent, projectRoot);
         }
     }
     getDefaultOutputPath(projectRoot) {

package/dist/agents/CopilotAgent.d.ts

@@ -0,0 +1,20 @@
+import { IAgent, IAgentConfig } from './IAgent';
+/**
+ * GitHub Copilot agent adapter.
+ * Writes to AGENTS.md for both web-based GitHub Copilot and VS Code extension.
+ */
+export declare class CopilotAgent implements IAgent {
+    private agentsMdAgent;
+    getIdentifier(): string;
+    getName(): string;
+    /**
+     * Returns the default output path for AGENTS.md.
+     */
+    getDefaultOutputPath(projectRoot: string): string;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
+    getMcpServerKey(): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+    supportsNativeSkills(): boolean;
+    supportsNativeSubagents(): boolean;
+}

package/dist/agents/CrushAgent.d.ts

@@ -0,0 +1,14 @@
+import { IAgent, IAgentConfig } from './IAgent';
+export declare class CrushAgent implements IAgent {
+    getIdentifier(): string;
+    getName(): string;
+    getDefaultOutputPath(projectRoot: string): Record<string, string>;
+    /**
+     * Transform MCP server types for Crush compatibility.
+     * Crush expects "http" for HTTP servers and "sse" for SSE servers, not "remote".
+     */
+    private transformMcpServersForCrush;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+}