@intellectronica/ruler 0.3.40 → 0.3.42

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>
@@ -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: enabled).             |
-| `--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
@@ -592,6 +597,7 @@ Skills are specialized knowledge packages that extend AI agent capabilities with
   - **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/`
@@ -658,7 +664,7 @@ When skills support is enabled and gitignore integration is active, Ruler automa
 - `.codex/skills/` (for OpenAI Codex CLI)
 - `.opencode/skills/` (for OpenCode)
 - `.pi/skills/` (for Pi Coding Agent)
-- `.agents/skills/` (for Goose and Amp)
+- `.agents/skills/` (for Goose, Amp, and Zed)
 - `.agent/skills/` (for Antigravity)
 - `.factory/skills/` (for Factory Droid)
 - `.vibe/skills/` (for Mistral Vibe)
@@ -719,7 +725,7 @@ ruler apply
 #    - OpenAI Codex CLI: .codex/skills/my-skill/
 #    - OpenCode: .opencode/skills/my-skill/
 #    - Pi Coding Agent: .pi/skills/my-skill/
-#    - Goose & Amp: .agents/skills/my-skill/
+#    - Goose, Amp & Zed: .agents/skills/my-skill/
 #    - Antigravity: .agent/skills/my-skill/
 #    - Factory Droid: .factory/skills/my-skill/
 #    - Mistral Vibe: .vibe/skills/my-skill/
@@ -740,18 +746,18 @@ Ruler can distribute named, delegatable **subagents** from a single source of tr
 
 For agents with a native subagent primitive, Ruler writes one file per subagent into the target directory:
 
-| Agent             | Target location                | Format |
-| ----------------- | ------------------------------ | ------ |
-| Claude Code       | `.claude/agents/<name>.md`     | Markdown + YAML frontmatter |
-| Cursor            | `.cursor/agents/<name>.md`     | Markdown + YAML frontmatter |
-| OpenAI Codex CLI  | `.codex/agents/<name>.toml`    | TOML (one self-contained file per agent) |
-| GitHub Copilot    | `.github/agents/<name>.md`     | Markdown + YAML frontmatter |
+| Agent            | Target location                      | Format                                   |
+| ---------------- | ------------------------------------ | ---------------------------------------- |
+| Claude Code      | `.claude/agents/<relative-path>.md`  | Markdown + YAML frontmatter              |
+| Cursor           | `.cursor/agents/<relative-path>.md`  | Markdown + YAML frontmatter              |
+| OpenAI Codex CLI | `.codex/agents/<relative-path>.toml` | TOML (one self-contained file per agent) |
+| GitHub Copilot   | `.github/agents/<relative-path>.md`  | Markdown + YAML frontmatter              |
 
 Other agents (Windsurf, RooCode, Aider, Gemini CLI, …) do not yet have a comparable native subagent primitive and are skipped with a warning. Subagent propagation will be added when those agents ship a comparable file format.
 
 ### Source Format
 
-Author each subagent as `.ruler/agents/<name>.md`:
+Author each subagent as `.ruler/agents/<name>.md` (nested folders are supported and preserved in outputs):
 
 ```markdown
 ---
@@ -772,19 +778,19 @@ a structured verdict.
 
 **Required frontmatter fields:**
 
-| Field         | Type   | Notes                                                 |
-| ------------- | ------ | ----------------------------------------------------- |
+| Field         | Type   | Notes                                                                      |
+| ------------- | ------ | -------------------------------------------------------------------------- |
 | `name`        | string | Must match the filename stem (`code-reviewer.md` → `name: code-reviewer`). |
-| `description` | string | When the parent agent should delegate to this subagent. |
+| `description` | string | When the parent agent should delegate to this subagent.                    |
 
 **Optional frontmatter fields:**
 
-| Field           | Type             | Used by                                          | Default behavior                              |
-| --------------- | ---------------- | ------------------------------------------------ | --------------------------------------------- |
-| `tools`         | string[]         | Claude (verbatim), Copilot (mapped to aliases)   | Cursor / Codex ignore; omitted if absent.     |
-| `model`         | string           | All four targets                                 | Cursor defaults to `inherit`; others omit.    |
-| `readonly`      | boolean          | Cursor (verbatim), Codex (`sandbox_mode`), Copilot (`disable-model-invocation`) | Defaults to `false` for Cursor; omitted otherwise. |
-| `is_background` | boolean          | Cursor only                                      | Defaults to `false` for Cursor.               |
+| Field           | Type     | Used by                                                                         | Default behavior                                   |
+| --------------- | -------- | ------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `tools`         | string[] | Claude (verbatim), Copilot (mapped to aliases)                                  | Cursor / Codex ignore; omitted if absent.          |
+| `model`         | string   | All four targets                                                                | Cursor defaults to `inherit`; others omit.         |
+| `readonly`      | boolean  | Cursor (verbatim), Codex (`sandbox_mode`), Copilot (`disable-model-invocation`) | Defaults to `false` for Cursor; omitted otherwise. |
+| `is_background` | boolean  | Cursor only                                                                     | Defaults to `false` for Cursor.                    |
 
 For GitHub Copilot, source `tools` (Claude vocabulary: `Read`, `Grep`, `Bash`, …) are translated to Copilot's aliases (`read`, `search`, `execute`, …). Tools that do not have a Copilot equivalent are dropped silently on a normal apply; pass `--verbose` (or use `--dry-run` to preview) to see which tools were dropped.
 
@@ -801,6 +807,7 @@ ruler apply --subagents   # enable subagent propagation for one run
 [agents]
 enabled = true
 # include_in_rules = true  # also append .ruler/agents/*.md into top-level CLAUDE.md / AGENTS.md (default: false)
+# cleanup_orphaned = true   # allow ruler to delete stale native subagent dirs (default: false)
 ```
 
 > **Note:** the previous release used `[subagents]` for these keys. `[subagents]` is still honored as a fallback with a deprecation warning, and will be removed in a future release. Please migrate to `[agents]`.
@@ -837,7 +844,7 @@ Use `--no-gitignore` to opt out.
 
 ### Cleanup
 
-Subagent propagation does **not** currently have explicit `ruler revert` support. To remove generated subagent directories, set `[agents] enabled = false` (or pass `--no-subagents`) and run `ruler apply` once. Cleanup will run for all four targets even if no source `.ruler/agents/` directory exists.
+Subagent propagation does **not** currently have explicit `ruler revert` support. By default, `ruler apply` is non-destructive and leaves existing native subagent directories untouched when subagents are disabled or missing. To allow automatic cleanup of stale generated directories, set `[agents] cleanup_orphaned = true`, then disable subagents (`[agents] enabled = false` or `--no-subagents`) and run `ruler apply`.
 
 ### Example Workflow
 
@@ -870,7 +877,7 @@ ruler apply
 
 ### Limitations
 
-- **No explicit revert command.** Cleanup happens via `[agents] enabled = false` on a subsequent `apply`.
+- **No explicit revert command.** Optional cleanup is available via `[agents] cleanup_orphaned = true` and a subsequent `apply`.
 - **Atomic replace, not merge.** Ruler regenerates each agent's subagent directory from the source on every apply. Manual edits to generated files will be overwritten.
 - **No support yet for agents without a native subagent primitive.** Windsurf, RooCode, Aider, Gemini CLI, and others are skipped with a warning. Propagation will be added when those agents ship a comparable file format.
 
@@ -908,6 +915,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
@@ -1078,7 +1091,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/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/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

@@ -82,7 +82,9 @@ 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);
         }

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/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/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/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): Promise<void>;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+}

package/dist/agents/CrushAgent.js

@@ -82,11 +82,14 @@ class CrushAgent {
     }
     async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig) {
         const outputPaths = this.getDefaultOutputPath(projectRoot);
-        const instructionsPath = agentConfig?.outputPathInstructions ?? outputPaths['instructions'];
+        const instructionsPath = agentConfig?.outputPath ??
+            agentConfig?.outputPathInstructions ??
+            outputPaths['instructions'];
         const mcpPath = agentConfig?.outputPathConfig ?? outputPaths['mcp'];
         await fs.writeFile(instructionsPath, concatenatedRules);
         // Always transform from mcpServers ({ mcpServers: ... }) to { mcp: ... } for Crush
         let finalMcpConfig = { mcp: {} };
+        const strategy = agentConfig?.mcp?.strategy ?? 'merge';
         try {
             const existingMcpConfig = JSON.parse(await fs.readFile(mcpPath, 'utf-8'));
             if (existingMcpConfig && typeof existingMcpConfig === 'object') {
@@ -94,7 +97,7 @@ class CrushAgent {
                 finalMcpConfig = {
                     ...existingMcpConfig,
                     mcp: {
-                        ...(existingMcpConfig.mcp || {}),
+                        ...(strategy === 'merge' ? existingMcpConfig.mcp || {} : {}),
                         ...transformedServers,
                     },
                 };

package/dist/agents/CursorAgent.d.ts

@@ -0,0 +1,17 @@
+import { IAgentConfig } from './IAgent';
+import { AgentsMdAgent } from './AgentsMdAgent';
+/**
+ * Cursor agent adapter.
+ * Leverages the standardized AGENTS.md approach supported natively by Cursor.
+ * See: https://docs.cursor.com/en/cli/using
+ */
+export declare class CursorAgent extends AgentsMdAgent {
+    getIdentifier(): string;
+    getName(): 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/FactoryDroidAgent.d.ts

@@ -0,0 +1,13 @@
+import { AgentsMdAgent } from './AgentsMdAgent';
+/**
+ * Factory Droid agent adapter.
+ * Uses the root-level AGENTS.md for instructions.
+ */
+export declare class FactoryDroidAgent extends AgentsMdAgent {
+    getIdentifier(): string;
+    getName(): string;
+    getMcpServerKey(): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+    supportsNativeSkills(): boolean;
+}

package/dist/agents/FirebaseAgent.d.ts

@@ -0,0 +1,11 @@
+import { AbstractAgent } from './AbstractAgent';
+/**
+ * Firebase Studio agent adapter.
+ */
+export declare class FirebaseAgent extends AbstractAgent {
+    getIdentifier(): string;
+    getName(): string;
+    getDefaultOutputPath(projectRoot: string): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+}

package/dist/agents/FirebenderAgent.d.ts

@@ -0,0 +1,36 @@
+import { IAgent, IAgentConfig } from './IAgent';
+/**
+ * Firebender agent adapter.
+ */
+export declare class FirebenderAgent implements IAgent {
+    /**
+     * Type guard function to safely check if an object is a FirebenderRule.
+     */
+    private isFirebenderRule;
+    getIdentifier(): string;
+    getName(): string;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
+    private resolveOutputPath;
+    private loadExistingConfig;
+    private createRulesFromConcatenatedRules;
+    private createRuleObjectsFromFilePaths;
+    private createRulesFromPlainText;
+    private removeDuplicateRules;
+    private saveConfig;
+    /**
+     * Handle MCP server configuration for Firebender.
+     * Merges or overwrites MCP servers in the firebender.json configuration based on strategy.
+     */
+    private handleMcpConfiguration;
+    getDefaultOutputPath(projectRoot: string): Record<string, string>;
+    getMcpServerKey(): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+    /**
+     * Extracts file paths from concatenated rules by parsing HTML source comments.
+     * @param concatenatedRules The concatenated rules string with HTML comments
+     * @param projectRoot The project root directory
+     * @returns Array of file paths relative to project root
+     */
+    private extractFilePathsFromRules;
+}

package/dist/agents/GeminiCliAgent.d.ts

@@ -0,0 +1,11 @@
+import { IAgentConfig } from './IAgent';
+import { AgentsMdAgent } from './AgentsMdAgent';
+export declare class GeminiCliAgent extends AgentsMdAgent {
+    getIdentifier(): string;
+    getName(): 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;
+}

package/dist/agents/GeminiCliAgent.js

@@ -44,11 +44,11 @@ class GeminiCliAgent extends AgentsMdAgent_1.AgentsMdAgent {
     getName() {
         return 'Gemini CLI';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig) {
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig, backup = true) {
         // First, perform idempotent write of AGENTS.md via base class
         await super.applyRulerConfig(concatenatedRules, projectRoot, null, {
             outputPath: agentConfig?.outputPath,
-        });
+        }, backup);
         // Prepare .gemini/settings.json with contextFileName and MCP configuration
         const settingsPath = path.join(projectRoot, '.gemini', 'settings.json');
         let existingSettings = {};

package/dist/agents/GooseAgent.d.ts

@@ -0,0 +1,12 @@
+import { AbstractAgent } from './AbstractAgent';
+/**
+ * Goose agent adapter for Block's Goose AI assistant.
+ * Propagates rules to .goosehints file.
+ */
+export declare class GooseAgent extends AbstractAgent {
+    getIdentifier(): string;
+    getName(): string;
+    getDefaultOutputPath(projectRoot: string): string;
+    getMcpServerKey(): string;
+    supportsNativeSkills(): boolean;
+}