claude-dev-env 2.14.1 → 2.15.0

package/bin/AGENTS.md

@@ -1,20 +1,22 @@
 # bin
 
-The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into the managed root (`~/.claude/` by default; `CLAUDE_CONFIG_DIR` or `--target` selects another), merges hook entries into that root's `settings.json`, installs Git hooks, and writes `~/.mypy.ini` under the process home.
+The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into the managed root (`~/.claude/` by default; `CLAUDE_CONFIG_DIR` or `--target` selects another), merges hook entries into that root's `settings.json`, installs Git hooks, writes `~/.mypy.ini` under the process home, and copies Codex exec-policy files into `~/.codex/rules` (`CODEX_HOME/rules` when that variable is set), and generates Cursor `.mdc` files into `~/.cursor/rules` from the installed Claude rules.
 
 ## Files
 
 | File | Purpose |
 |---|---|
 | `install.mjs` | Main installer: builds a read-only plan via `install-plan.mjs`, then runs mutations inside `install-transaction.mjs` recovery (copy content directories, merge hooks, install skills, prune, git hooks, mypy.ini); routes `CLAUDE_HOME`, the manifest path, and `~/.mypy.ini` through `resolve-install-root.mjs`; resolves single or multi-profile targets before mutation and writes one ownership manifest per target |
-| `resolve-install-root.mjs` | Pure install-root resolver: precedence `--target` > `CLAUDE_CONFIG_DIR` > `~/.claude`, separator-boundary containment, and the declared external allowlist for `~/.mypy.ini` |
+| `resolve-install-root.mjs` | Pure install-root resolver: precedence `--target` > `CLAUDE_CONFIG_DIR` > `~/.claude`, separator-boundary containment, and the declared external allowlist for `~/.mypy.ini` plus files under the Codex rules directory and the Cursor home |
 | `select-install-targets.mjs` | Pure target selection for main-default, explicit `--target`, and `--profile`/`--profiles`; rejects ambiguous or duplicate targets; builds per-target manifest records with `targetIdentity` and `managedRoot` |
 | `install-plan.mjs` | Read-only install and uninstall plans: install preflight (managed root, source conflicts, Python, settings when hooks install) and uninstall preflight (settings JSON before removal, removable vs skipped manifest records), freezes plans E2/F execute |
 | `install-transaction.mjs` | Install, update, and uninstall transaction journal: captures prior settings, manifest, managed files, and `core.hooksPath`, restores them on failure, and supports fault injection phases for recovery tests |
 | `install.transaction.test.mjs` | Unit and sandbox installer tests for snapshot/restore and fault phases (`after_file_staging`, `after_settings_write`, `after_git_config`, `after_manifest_write`) |
 | `install.uninstall-transaction.test.mjs` | Uninstall plan preflight and recovery: malformed/non-object settings fail before removal, each fault phase restores files/settings/manifest/`core.hooksPath`, retry succeeds, selected-root containment |
 | `install.profile-root.test.mjs` | Contract tests for the install-root resolver: precedence, containment boundary, external allowlist, and the install.mjs import smoke check |
-| `install-constants.mjs` | The named values `install.mjs` reads: `SKIPPED_SOURCE_ENTRY_NAMES` and `SKIPPED_SOURCE_FILE_EXTENSIONS` for the build artifacts the source walk leaves behind, `RUN_BACKUP_DIRECTORY_NAME_PATTERN` for the timestamp shape a run backup directory carries, `MANAGED_SKILLS_DIRECTORY_NAME` and `MANAGED_HOOKS_DIRECTORY_NAME` for the directory name each of those trees carries in a package source and under `~/.claude` — read by the copy loops, the hooks.json reads, the git-hook shims, the mypy configuration, and the prunes alike — `SETTINGS_FILE_NAME` for the settings file the merge, the retired-hook prune, and the uninstall purge share, and `MYPY_INI_FILE_NAME` for the home-directory file `install_mypy_ini.mjs` writes (also imported by `resolve-install-root.mjs`) |
+| `install.codex-rules.test.mjs` | Tests that Codex exec-policy files copy to `~/.codex/rules`, honor `CODEX_HOME`, skip `--only journal`, and uninstall without touching `default.rules` |
+| `install.cursor-rules.test.mjs` | Tests that Cursor `.mdc` files generate into `~/.cursor/rules` from Claude rules, skip `--only journal`, and leave a local extra `.mdc` in place |
+| `install-constants.mjs` | The named values `install.mjs` reads: `SKIPPED_SOURCE_ENTRY_NAMES` and `SKIPPED_SOURCE_FILE_EXTENSIONS` for the build artifacts the source walk leaves behind, `RUN_BACKUP_DIRECTORY_NAME_PATTERN` for the timestamp shape a run backup directory carries, `MANAGED_SKILLS_DIRECTORY_NAME` and `MANAGED_HOOKS_DIRECTORY_NAME` for the directory name each of those trees carries in a package source and under `~/.claude` — read by the copy loops, the hooks.json reads, the git-hook shims, the mypy configuration, and the prunes alike — `SETTINGS_FILE_NAME` for the settings file the merge, the retired-hook prune, and the uninstall purge share, and `MYPY_INI_FILE_NAME` for the home-directory file `install_mypy_ini.mjs` writes, plus the Codex home and rules directory names `resolve-install-root.mjs` uses |
 | `ever-shipped-skills.mjs` | Static `EVER_SHIPPED_SKILL_NAMES` set of every top-level skill directory name the package has shipped; the installer subtracts the current skill set from it to prune retired skills left under `~/.claude/skills` |
 | `expand_home_directory_tokens.mjs` | Expands residual `$HOME` / `${HOME}` / `~/` tokens in settings.json hook and statusLine commands to absolute home paths at install time (literal-safe for homes that contain `$`) |
 | `git_hooks_installer.mjs` | Installs or updates the `pre-commit`, `pre-push`, and `post-commit` Git hooks in the user's git config; writes hook scripts that delegate to the installed Python hooks |
@@ -78,7 +80,7 @@ A run that moves nothing sweeps nothing, so every recovery point the user holds
 
 `--uninstall` builds a read-only uninstall plan, captures a recovery snapshot, then removes each file the plan lists.
 
-Settings JSON is validated before any removal. A malformed or non-object `settings.json` fails closed with the managed files still on disk. Each manifest record passes a containment guard: the path resolves under `~/.claude`, or it names the `~/.mypy.ini` the install writes in the home directory. Every other record is skipped with a warning and counted. Skipping keeps one malformed record — hand-edited, or written by an installer that ran against a different home — from stranding the user with a half-removed install. The purge removes every legitimate record, clears the manifest, and reports the skipped count.
+Settings JSON is validated before any removal. A malformed or non-object `settings.json` fails closed with the managed files still on disk. Each manifest record passes a containment guard: the path resolves under `~/.claude`, or it names the `~/.mypy.ini` the install writes in the home directory, or it sits under the Codex rules directory. Every other record is skipped with a warning and counted. Skipping keeps one malformed record — hand-edited, or written by an installer that ran against a different home — from stranding the user with a half-removed install. The purge removes every legitimate record, clears the manifest, and reports the skipped count.
 
 The uninstall runs inside the same snapshot/restore journal as install: prior settings, manifest, managed files, and `core.hooksPath` restore when a later phase fails, so a retry starts from a complete ownership record. The journal is discarded only after a successful commit.
 

package/bin/install-constants.mjs

@@ -85,3 +85,54 @@ export const SETTINGS_FILE_NAME = 'settings.json';
  * removes the file the install created.
  */
 export const MYPY_INI_FILE_NAME = '.mypy.ini';
+
+/**
+ * Environment variable Codex uses for its config home. When unset, Codex reads
+ * `~/.codex`. The installer copies shipped exec-policy files into
+ * `<that home>/rules`.
+ */
+export const CODEX_HOME_ENVIRONMENT_VARIABLE = 'CODEX_HOME';
+
+/**
+ * Directory name Codex uses under the user home when `CODEX_HOME` is unset.
+ */
+export const DEFAULT_CODEX_DIRECTORY_NAME = '.codex';
+
+/**
+ * Directory name under the Codex home that holds `*.rules` exec-policy files.
+ * Codex loads every file in that directory; see `load_exec_policy` in Codex.
+ */
+export const CODEX_RULES_DIRECTORY_NAME = 'rules';
+
+/**
+ * Package subdirectory that holds the shipped Codex exec-policy files. The
+ * installer copies this tree into the Codex rules directory, not into
+ * `~/.claude/`.
+ */
+export const CODEX_RULES_PACKAGE_DIRECTORY_NAME = 'codex-rules';
+
+/**
+ * Shipped exec-policy file name. A distinct name keeps a local `default.rules`
+ * file in place.
+ */
+export const CODEX_RULES_SHIPPED_FILE_NAME = 'claude-dev-env.rules';
+
+/**
+ * Directory name Cursor uses under the user home for editor config.
+ */
+export const DEFAULT_CURSOR_DIRECTORY_NAME = '.cursor';
+
+/**
+ * Directory name under the Cursor home that holds generated `.mdc` rule files.
+ */
+export const CURSOR_RULES_DIRECTORY_NAME = 'rules';
+
+/**
+ * Installed script that writes Cursor `.mdc` files from Claude rules.
+ */
+export const CURSOR_SYNC_SCRIPT_FILE_NAME = 'sync_to_cursor.py';
+
+/**
+ * Windows Python launcher command the installer may bake into hook settings.
+ */
+export const WINDOWS_PYTHON_LAUNCHER_COMMAND = 'py -3';

package/bin/install.codex-rules.test.mjs

@@ -0,0 +1,173 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import {
+    mkdtempSync,
+    mkdirSync,
+    writeFileSync,
+    readFileSync,
+    existsSync,
+    rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+    resolveInstallRoot,
+    isAllowedInstallDestination,
+} from './resolve-install-root.mjs';
+import {
+    CODEX_HOME_ENVIRONMENT_VARIABLE,
+    CODEX_RULES_DIRECTORY_NAME,
+    CODEX_RULES_PACKAGE_DIRECTORY_NAME,
+    CODEX_RULES_SHIPPED_FILE_NAME,
+    DEFAULT_CODEX_DIRECTORY_NAME,
+} from './install-constants.mjs';
+import { CONTENT_DIRECTORIES, INSTALL_GROUPS } from './install.mjs';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+const SHIPPED_RULES_SOURCE_PATH = join(
+    PACKAGE_DIRECTORY,
+    CODEX_RULES_PACKAGE_DIRECTORY_NAME,
+    CODEX_RULES_SHIPPED_FILE_NAME,
+);
+
+function runInstaller(homeDirectory, extraArguments) {
+    return execFileSync('node', [INSTALLER_PATH, ...extraArguments], {
+        cwd: PACKAGE_DIRECTORY,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            [CODEX_HOME_ENVIRONMENT_VARIABLE]: join(homeDirectory, DEFAULT_CODEX_DIRECTORY_NAME),
+        },
+    });
+}
+
+test('CONTENT_DIRECTORIES omits codex-rules because that tree installs to the Codex home', () => {
+    assert.equal(CONTENT_DIRECTORIES.includes(CODEX_RULES_PACKAGE_DIRECTORY_NAME), false);
+});
+
+test('the core group installs Codex exec-policy files', () => {
+    assert.equal(INSTALL_GROUPS.core.includeCodexRules, true);
+});
+
+test('resolveInstallRoot names ~/.codex/rules and allows files under it', () => {
+    const homeDirectory = join(tmpdir(), 'cdev-codex-rules-home');
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment: {},
+        explicitTarget: null,
+    });
+    const expectedDirectory = join(homeDirectory, DEFAULT_CODEX_DIRECTORY_NAME, CODEX_RULES_DIRECTORY_NAME);
+    assert.equal(resolution.codexRulesInstallDirectory, expectedDirectory);
+    assert.equal(
+        isAllowedInstallDestination(join(expectedDirectory, CODEX_RULES_SHIPPED_FILE_NAME), resolution),
+        true,
+    );
+    assert.equal(
+        isAllowedInstallDestination(join(homeDirectory, '.ssh', 'id_rsa'), resolution),
+        false,
+    );
+});
+
+test('CODEX_HOME relocates the Codex rules destination', () => {
+    const homeDirectory = join(tmpdir(), 'cdev-codex-home-default');
+    const relocatedHome = join(tmpdir(), 'cdev-codex-home-relocated');
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment: { [CODEX_HOME_ENVIRONMENT_VARIABLE]: relocatedHome },
+        explicitTarget: null,
+    });
+    assert.equal(
+        resolution.codexRulesInstallDirectory,
+        join(relocatedHome, CODEX_RULES_DIRECTORY_NAME),
+    );
+});
+
+test('a full install copies shipped Codex rules and leaves a local default.rules in place', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-codex-install-'));
+    try {
+        const userRulesPath = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+            'default.rules',
+        );
+        mkdirSync(dirname(userRulesPath), { recursive: true });
+        writeFileSync(userRulesPath, 'prefix_rule(pattern=["echo", "hi"], decision="allow")\n');
+
+        runInstaller(homeDirectory, []);
+
+        const installedRulesPath = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+            CODEX_RULES_SHIPPED_FILE_NAME,
+        );
+        assert.equal(existsSync(installedRulesPath), true);
+        assert.equal(
+            readFileSync(installedRulesPath, 'utf8'),
+            readFileSync(SHIPPED_RULES_SOURCE_PATH, 'utf8'),
+        );
+        assert.equal(
+            readFileSync(userRulesPath, 'utf8'),
+            'prefix_rule(pattern=["echo", "hi"], decision="allow")\n',
+        );
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full install Codex rules file contains no personal home path', () => {
+    const shippedText = readFileSync(SHIPPED_RULES_SOURCE_PATH, 'utf8');
+    assert.equal(shippedText.includes('Users\\jon'), false);
+    assert.equal(shippedText.includes('Users/jon'), false);
+    assert.equal(shippedText.includes('JonEcho'), false);
+});
+
+test('--only journal skips Codex rules; --only core copies them', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-codex-groups-'));
+    try {
+        const installedRulesPath = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+            CODEX_RULES_SHIPPED_FILE_NAME,
+        );
+        runInstaller(homeDirectory, ['--only', 'journal']);
+        assert.equal(existsSync(installedRulesPath), false);
+
+        runInstaller(homeDirectory, ['--only', 'core']);
+        assert.equal(existsSync(installedRulesPath), true);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('uninstall removes the shipped Codex rules file and leaves default.rules', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-codex-uninstall-'));
+    try {
+        const rulesDirectory = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+        );
+        const userRulesPath = join(rulesDirectory, 'default.rules');
+        mkdirSync(rulesDirectory, { recursive: true });
+        writeFileSync(userRulesPath, 'keep-me\n');
+
+        runInstaller(homeDirectory, []);
+        runInstaller(homeDirectory, ['--uninstall']);
+
+        const installedRulesPath = join(rulesDirectory, CODEX_RULES_SHIPPED_FILE_NAME);
+        assert.equal(existsSync(installedRulesPath), false);
+        assert.equal(readFileSync(userRulesPath, 'utf8'), 'keep-me\n');
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});

package/bin/install.cursor-rules.test.mjs

@@ -0,0 +1,103 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import {
+    resolveInstallRoot,
+    isAllowedInstallDestination,
+} from './resolve-install-root.mjs';
+import {
+    DEFAULT_CURSOR_DIRECTORY_NAME,
+    CURSOR_RULES_DIRECTORY_NAME,
+} from './install-constants.mjs';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+
+function runInstaller(homeDirectory, extraArguments) {
+    return execFileSync('node', [INSTALLER_PATH, ...extraArguments], {
+        cwd: PACKAGE_DIRECTORY,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+        },
+    });
+}
+
+test('resolveInstallRoot names ~/.cursor/rules and allows generated mdc files under it', () => {
+    const homeDirectory = join(tmpdir(), 'cdev-cursor-rules-home');
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment: {},
+        explicitTarget: null,
+    });
+    const expectedDirectory = join(
+        homeDirectory,
+        DEFAULT_CURSOR_DIRECTORY_NAME,
+        CURSOR_RULES_DIRECTORY_NAME,
+    );
+    assert.equal(resolution.cursorRulesInstallDirectory, expectedDirectory);
+    assert.equal(
+        isAllowedInstallDestination(join(expectedDirectory, 'plain-language.mdc'), resolution),
+        true,
+    );
+    assert.equal(
+        isAllowedInstallDestination(join(homeDirectory, '.ssh', 'id_rsa'), resolution),
+        false,
+    );
+});
+
+test('a full install writes stem-named Cursor rules and leaves a local extra mdc in place', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-cursor-install-'));
+    try {
+        const extraRulePath = join(
+            homeDirectory,
+            DEFAULT_CURSOR_DIRECTORY_NAME,
+            CURSOR_RULES_DIRECTORY_NAME,
+            'user-local.mdc',
+        );
+        mkdirSync(dirname(extraRulePath), { recursive: true });
+        writeFileSync(extraRulePath, 'keep-me\n');
+
+        runInstaller(homeDirectory, []);
+
+        const generatedPath = join(
+            homeDirectory,
+            DEFAULT_CURSOR_DIRECTORY_NAME,
+            CURSOR_RULES_DIRECTORY_NAME,
+            'plain-language.mdc',
+        );
+        assert.equal(existsSync(generatedPath), true);
+        const generatedText = readFileSync(generatedPath, 'utf8');
+        assert.equal(generatedText.includes('alwaysApply: true'), true);
+        assert.equal(readFileSync(extraRulePath, 'utf8'), 'keep-me\n');
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('--only journal skips Cursor rule generation; --only core writes them', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-cursor-groups-'));
+    try {
+        const generatedPath = join(
+            homeDirectory,
+            DEFAULT_CURSOR_DIRECTORY_NAME,
+            CURSOR_RULES_DIRECTORY_NAME,
+            'plain-language.mdc',
+        );
+        runInstaller(homeDirectory, ['--only', 'journal']);
+        assert.equal(existsSync(generatedPath), false);
+
+        runInstaller(homeDirectory, ['--only', 'core']);
+        assert.equal(existsSync(generatedPath), true);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});

package/bin/install.mjs

@@ -22,10 +22,14 @@ import {
     MANAGED_SKILLS_DIRECTORY_NAME,
     MANAGED_HOOKS_DIRECTORY_NAME,
     SETTINGS_FILE_NAME,
+    CODEX_RULES_PACKAGE_DIRECTORY_NAME,
+    CURSOR_SYNC_SCRIPT_FILE_NAME,
+    WINDOWS_PYTHON_LAUNCHER_COMMAND,
 } from './install-constants.mjs';
 import {
     resolveInstallRoot,
     parseExplicitTargetFromArgv,
+    isAllowedInstallDestination,
 } from './resolve-install-root.mjs';
 import {
     parseInstallTargetSelectionFromArgv,
@@ -211,7 +215,7 @@ function discoverDependencyGroups() {
             readFileSync(join(dependencyRoot, 'package.json'), 'utf8')
         );
         const groupName = dependencyPackageJson.claudeDevEnv?.groupName
-            || dependencyName.replace(/^@[^/]+\//, '');
+            || dependencyName.replace(new RegExp('^@[^/]+/'), '');
         const group = {
             description: dependencyPackageJson.description || dependencyName,
             packageRoot: dependencyRoot,
@@ -257,6 +261,7 @@ export const INSTALL_GROUPS = {
         skills: CORE_SKILLS,
         includeDirectories: CORE_INCLUDE_DIRECTORIES,
         includeAllHooks: true,
+        includeCodexRules: true,
     },
     journal: {
         description: 'Session logging and memory',
@@ -302,6 +307,75 @@ export function isWindowsStorePythonStub(executablePath) {
     return /[\\/]windowsapps[\\/]/i.test(executablePath);
 }
 
+/**
+ * Split a stored Python command into an executable and prefix arguments.
+ *
+ * Args:
+ *   pythonCommand: The command the installer detected (`py -3`, `python3`, or a path).
+ *
+ * Returns:
+ *   `{ file, prefixArguments }` for `execFileSync`.
+ */
+export function pythonFileAndPrefixArguments(pythonCommand) {
+    if (pythonCommand === WINDOWS_PYTHON_LAUNCHER_COMMAND) {
+        return { file: 'py', prefixArguments: ['-3'] };
+    }
+    const unquoted = pythonCommand.replace(/^"(.*)"$/, '$1');
+    return { file: unquoted, prefixArguments: [] };
+}
+
+/**
+ * Read generated Cursor paths from the sync manifest under a Cursor home.
+ *
+ * Args:
+ *   cursorRoot: Absolute `.cursor` directory.
+ *
+ * Returns:
+ *   Absolute paths the installer may record, including the sync manifest.
+ */
+export function collectManagedCursorSyncPaths(cursorRoot) {
+    const manifestPath = join(cursorRoot, '.sync-manifest.json');
+    if (!existsSync(manifestPath)) return [];
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const generatedPaths = [manifestPath];
+    const allEntries = { ...(parsed.entries || {}), ...(parsed.docs_entries || {}) };
+    for (const eachRelativePath of Object.keys(allEntries)) {
+        generatedPaths.push(join(cursorRoot, eachRelativePath));
+    }
+    return generatedPaths;
+}
+
+/**
+ * Run the installed Cursor rule generator against Claude and Cursor roots.
+ *
+ * Args:
+ *   pythonCommand: Interpreter command from install preflight.
+ *   scriptPath: Absolute `sync_to_cursor.py` path.
+ *   claudeRoot: Managed Claude root that holds `rules/` and `docs/`.
+ *   cursorRoot: Cursor home that receives `rules/*.mdc`.
+ *
+ * Returns:
+ *   void
+ */
+export function runCursorRuleSync(pythonCommand, scriptPath, claudeRoot, cursorRoot) {
+    mkdirSync(cursorRoot, { recursive: true });
+    const { file, prefixArguments } = pythonFileAndPrefixArguments(pythonCommand);
+    execFileSync(
+        file,
+        [
+            ...prefixArguments,
+            scriptPath,
+            '--force',
+            '--quiet',
+            '--claude-root',
+            claudeRoot,
+            '--cursor-root',
+            cursorRoot,
+        ],
+        { stdio: 'inherit' },
+    );
+}
+
 /**
  * Formats an absolute interpreter path as a settings.json hook command prefix:
  * forward-slash separators, double-quoted when the path contains a space so the
@@ -629,8 +703,7 @@ function isManagedPath(candidatePath, managedHomeDirectory = CLAUDE_HOME) {
  * @returns {boolean} True when the installer itself writes the path.
  */
 function isRemovableManifestRecord(candidatePath) {
-    if (isManagedPath(candidatePath)) return true;
-    return comparisonKeyForPath(candidatePath) === comparisonKeyForPath(MYPY_INI_INSTALL_PATH);
+    return isAllowedInstallDestination(candidatePath, INSTALL_ROOT_RESOLUTION);
 }
 
 /**
@@ -650,6 +723,10 @@ function owningManagedRoot(installedFilePath) {
         const managedRoot = join(CLAUDE_HOME, directoryName);
         if (isInsideDirectory(resolvedPath, managedRoot)) return managedRoot;
     }
+    const codexRulesDirectory = INSTALL_ROOT_RESOLUTION.codexRulesInstallDirectory;
+    if (isInsideDirectory(resolvedPath, codexRulesDirectory)) return codexRulesDirectory;
+    const cursorInstallDirectory = INSTALL_ROOT_RESOLUTION.cursorInstallDirectory;
+    if (isInsideDirectory(resolvedPath, cursorInstallDirectory)) return cursorInstallDirectory;
     return null;
 }
 
@@ -1856,7 +1933,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             `${PACKAGE_NAME}: --update — removing prior managed files under ${CLAUDE_HOME}, then reinstalling from the package.\n`,
         );
         purgeManagedInstallation({
-            requireManifest: false,
+            isManifestRequired: false,
             throwIfFault,
         });
     } else if (isUpdateRefresh) {
@@ -1940,6 +2017,30 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             }
         }
     }
+    const shouldInstallCodexRules = !selectedGroups
+        || activeGroups.some((eachGroup) => eachGroup.includeCodexRules);
+    if (shouldInstallCodexRules) {
+        const sourceDirectory = join(PACKAGE_ROOT, CODEX_RULES_PACKAGE_DIRECTORY_NAME);
+        if (existsSync(sourceDirectory)) {
+            const destinationDirectory = INSTALL_ROOT_RESOLUTION.codexRulesInstallDirectory;
+            const stats = copyTree(sourceDirectory, destinationDirectory);
+            summary.codexRules = stats;
+            allInstalledFiles.push(...stats.paths);
+        }
+    }
+    const shouldInstallCursorRules = !selectedGroups
+        || activeGroups.some((eachGroup) => (eachGroup.includeDirectories || []).includes('rules'));
+    if (shouldInstallCursorRules) {
+        const scriptPath = join(CLAUDE_HOME, 'scripts', CURSOR_SYNC_SCRIPT_FILE_NAME);
+        if (!existsSync(scriptPath)) {
+            throw new Error(`cursor rule sync script missing: ${scriptPath}`);
+        }
+        const cursorRoot = dirname(INSTALL_ROOT_RESOLUTION.cursorRulesInstallDirectory);
+        runCursorRuleSync(pythonCommand, scriptPath, CLAUDE_HOME, cursorRoot);
+        const generatedCursorPaths = collectManagedCursorSyncPaths(cursorRoot);
+        allInstalledFiles.push(...generatedCursorPaths);
+        summary.cursorRules = { created: generatedCursorPaths.length, updated: 0, paths: generatedCursorPaths };
+    }
     let skillsCreated = 0;
     let skillsUpdated = 0;
     const skillPaths = [];
@@ -2136,6 +2237,14 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             console.log(`  ${directory}: ${created + updated} files (${created} new, ${updated} updated)`);
         }
     }
+    if (summary.codexRules) {
+        const { created, updated } = summary.codexRules;
+        console.log(`  ${CODEX_RULES_PACKAGE_DIRECTORY_NAME}: ${created + updated} files (${created} new, ${updated} updated)`);
+    }
+    if (summary.cursorRules) {
+        const { created } = summary.cursorRules;
+        console.log(`  cursor-rules: ${created} generated files`);
+    }
     if (summary.skills) {
         const { created, updated, pruned } = summary.skills;
         const staleClause = pruned > 0 ? `, ${pruned} stale moved aside` : '';
@@ -2222,14 +2331,14 @@ function removeRecordedFile(filePath) {
 /**
  * Build the uninstall plan for this managed root.
  *
- * @param {boolean} requireManifest
+ * @param {boolean} isManifestRequired
  * @returns {ReturnType<typeof buildUninstallPlan>}
  */
-function resolveUninstallPlan(requireManifest) {
+function resolveUninstallPlan(isManifestRequired) {
     return buildUninstallPlan({
         managedRoot: CLAUDE_HOME,
         manifestFilePath: MANIFEST_FILE,
-        requireManifest,
+        requireManifest: isManifestRequired,
         isRemovableRecord: isRemovableManifestRecord,
     });
 }
@@ -2266,20 +2375,20 @@ function executeUninstallPlan(plan, helpers = {}) {
     }
     if (plan.skippedFiles.length > 0) {
         console.warn(
-            `  ${plan.skippedFiles.length} manifest record(s) skipped — each names a path outside ${CLAUDE_HOME} and outside ${MYPY_INI_INSTALL_PATH}`,
+            `  ${plan.skippedFiles.length} manifest record(s) skipped — each names a path outside ${CLAUDE_HOME}, outside ${MYPY_INI_INSTALL_PATH}, outside ${INSTALL_ROOT_RESOLUTION.codexRulesInstallDirectory}, and outside ${INSTALL_ROOT_RESOLUTION.cursorInstallDirectory}`,
         );
     }
     throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
 
     if (existsSync(plan.settingsPath)) {
         const settings = JSON.parse(readFileSync(plan.settingsPath, 'utf8'));
-        let settingsChanged = false;
+        let didSettingsChange = false;
         if (settings.hooks) {
             const managedHookRelativePaths = managedHookScriptRelativePathsFromSourceRoots(
                 managedPackageSourceRoots(),
             );
             pruneManagedHooksFromSettings(settings, managedHookRelativePaths);
-            settingsChanged = true;
+            didSettingsChange = true;
             console.log('  Hook entries removed from settings.json');
         }
         const managedDenyFromPlan = plan.managedPermissionDenyEntries.length > 0
@@ -2288,13 +2397,13 @@ function executeUninstallPlan(plan, helpers = {}) {
         if (managedDenyFromPlan.length > 0) {
             const pruneOutcome = pruneManagedPermissionsFromSettings(settings, managedDenyFromPlan);
             if (pruneOutcome.removedCount > 0) {
-                settingsChanged = true;
+                didSettingsChange = true;
                 console.log(
                     `  Permission entries removed from settings.json: ${pruneOutcome.removedCount} managed deny(s)`,
                 );
             }
         }
-        if (settingsChanged) {
+        if (didSettingsChange) {
             writeFileSync(plan.settingsPath, JSON.stringify(settings, null, 4) + '\n');
         }
     }
@@ -2327,13 +2436,13 @@ function executeUninstallPlan(plan, helpers = {}) {
  * without nesting a second journal.
  *
  * @param {{
- *   requireManifest: boolean,
+ *   isManifestRequired: boolean,
  *   throwIfFault?: (phase: string) => void,
  * }} options
  * @returns {number|void} 0 when no manifest exists and none is required.
  */
-function purgeManagedInstallation({ requireManifest, throwIfFault }) {
-    const plan = resolveUninstallPlan(requireManifest);
+function purgeManagedInstallation({ isManifestRequired, throwIfFault }) {
+    const plan = resolveUninstallPlan(isManifestRequired);
     if (plan.isNoOp) {
         return 0;
     }
@@ -2433,6 +2542,8 @@ Examples:
 
 Install location: ~/.claude/ by default; CLAUDE_CONFIG_DIR or --target selects another managed root.
 Named profiles resolve under LLM_SETTINGS_PROFILES_ROOT or ~/.claude-profiles/<directoryName>.
+Codex exec-policy files copy into ~/.codex/rules, or CODEX_HOME/rules when CODEX_HOME is set.
+Cursor rule files generate into ~/.cursor/rules as stem-named mdc files, one per Claude rule.
 
 Root precedence: --target > CLAUDE_CONFIG_DIR > ~/.claude
 Profile selection (--profile/--profiles) is mutually exclusive with --target.
@@ -2564,7 +2675,7 @@ function runInstallForAllTargets(allTargets, childArgv) {
  * @returns {number | null}
  */
 function spawnInstallChild(target, childArgv) {
-    const result = spawnSync(
+    const childProcess = spawnSync(
         process.execPath,
         [
             fileURLToPath(import.meta.url),
@@ -2579,11 +2690,11 @@ function spawnInstallChild(target, childArgv) {
             env: process.env,
         },
     );
-    if (result.error) {
-        console.error(`ERROR: failed to spawn install child: ${result.error.message}`);
+    if (childProcess.error) {
+        console.error(`ERROR: failed to spawn install child: ${childProcess.error.message}`);
         return 1;
     }
-    return result.status === null ? 1 : result.status;
+    return childProcess.status === null ? 1 : childProcess.status;
 }
 
 if (invokedAsEntryPoint(import.meta.url, process.argv[1])) {

package/bin/install.profile-root.test.mjs

@@ -8,6 +8,7 @@ import { join, resolve } from 'node:path';
 import { mkdtempSync, rmSync, mkdirSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { CODEX_RULES_SHIPPED_FILE_NAME } from './install-constants.mjs';
 import {
     resolveInstallRoot,
     isPathWithinManagedRoot,
@@ -90,6 +91,13 @@ test('declared external mypy.ini is allowed; unrelated external paths are not',
         isAllowedInstallDestination(join(resolution.managedRoot, 'hooks', 'x.py'), resolution),
         true,
     );
+    assert.equal(
+        isAllowedInstallDestination(
+            join(resolution.codexRulesInstallDirectory, CODEX_RULES_SHIPPED_FILE_NAME),
+            resolution,
+        ),
+        true,
+    );
 });
 
 test('parseExplicitTargetFromArgv reads --target and --target=', () => {

package/bin/install.prune.test.mjs

@@ -238,6 +238,7 @@ function resolveInstallerInvocation(homeDirectory, options) {
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+        CODEX_HOME: join(homeDirectory, '.codex'),
     };
     if (dependencyResolvable) {
         childEnvironment.NODE_PATH = ensureDependencyStub(homeDirectory);
@@ -1227,7 +1228,7 @@ test('an uninstall removes the home-directory .mypy.ini the install wrote and sk
         assert.equal(
             existsSync(mypyIniPath),
             false,
-            'the uninstall removes the one file the install writes outside ~/.claude',
+            'the uninstall removes the mypy configuration the install writes outside ~/.claude',
         );
         assert.equal(
             installerOutput.includes(`skipping ${mypyIniPath}`),

package/bin/install.transaction.test.mjs

@@ -242,6 +242,7 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+        CODEX_HOME: join(homeDirectory, '.codex'),
     };
     if (options.faultPhase) {
         childEnvironment[INSTALL_FAULT_ENV] = options.faultPhase;

package/bin/install.uninstall-transaction.test.mjs

@@ -74,6 +74,7 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+        CODEX_HOME: join(homeDirectory, '.codex'),
     };
     if (options.faultPhase) {
         childEnvironment[INSTALL_FAULT_ENV] = options.faultPhase;

package/bin/resolve-install-root.mjs

@@ -11,7 +11,14 @@
 
 import { homedir } from 'node:os';
 import { join, normalize, resolve, sep } from 'node:path';
-import { MYPY_INI_FILE_NAME } from './install-constants.mjs';
+import {
+    MYPY_INI_FILE_NAME,
+    CODEX_HOME_ENVIRONMENT_VARIABLE,
+    DEFAULT_CODEX_DIRECTORY_NAME,
+    CODEX_RULES_DIRECTORY_NAME,
+    DEFAULT_CURSOR_DIRECTORY_NAME,
+    CURSOR_RULES_DIRECTORY_NAME,
+} from './install-constants.mjs';
 
 export const CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CONFIG_DIR';
 export const DEFAULT_CLAUDE_DIRECTORY_NAME = '.claude';
@@ -33,6 +40,10 @@ export const MANIFEST_FILE_NAME = '.claude-dev-env-manifest.json';
  *   manifestFilePath: string,
  *   mypyIniInstallPath: string,
  *   allDeclaredExternalPaths: string[],
+ *   allDeclaredExternalDirectories: string[],
+ *   codexRulesInstallDirectory: string,
+ *   cursorInstallDirectory: string,
+ *   cursorRulesInstallDirectory: string,
  * }} InstallRootResolution
  */
 
@@ -69,6 +80,18 @@ export function resolveInstallRoot(options = {}) {
     }
 
     const mypyIniInstallPath = resolve(join(homeDirectory, MYPY_INI_FILE_NAME));
+    const codexHomeDirectory = normalizeOptionalPath(
+        environment[CODEX_HOME_ENVIRONMENT_VARIABLE],
+    ) ?? resolve(join(homeDirectory, DEFAULT_CODEX_DIRECTORY_NAME));
+    const codexRulesInstallDirectory = resolve(
+        join(codexHomeDirectory, CODEX_RULES_DIRECTORY_NAME),
+    );
+    const cursorInstallDirectory = resolve(
+        join(homeDirectory, DEFAULT_CURSOR_DIRECTORY_NAME),
+    );
+    const cursorRulesInstallDirectory = resolve(
+        join(cursorInstallDirectory, CURSOR_RULES_DIRECTORY_NAME),
+    );
     return {
         managedRoot,
         source,
@@ -76,6 +99,10 @@ export function resolveInstallRoot(options = {}) {
         manifestFilePath: join(managedRoot, MANIFEST_FILE_NAME),
         mypyIniInstallPath,
         allDeclaredExternalPaths: [mypyIniInstallPath],
+        allDeclaredExternalDirectories: [codexRulesInstallDirectory, cursorInstallDirectory],
+        codexRulesInstallDirectory,
+        cursorInstallDirectory,
+        cursorRulesInstallDirectory,
     };
 }
 
@@ -103,8 +130,9 @@ export function isPathWithinManagedRoot(candidatePath, managedRoot) {
 }
 
 /**
- * True when a write destination is allowed: inside the managed root or on
- * the declared external allowlist (today: ~/.mypy.ini under the home dir).
+ * True when a write destination is allowed: inside the managed root, the
+ * home-directory `.mypy.ini`, a file under the Codex rules directory, or a file
+ * under the Cursor rules directory.
  *
  * @param {string} candidatePath
  * @param {InstallRootResolution} resolution
@@ -115,8 +143,13 @@ export function isAllowedInstallDestination(candidatePath, resolution) {
         return true;
     }
     const normalizedCandidate = normalizePathForComparison(candidatePath);
-    return resolution.allDeclaredExternalPaths.some(
+    if (resolution.allDeclaredExternalPaths.some(
         (eachExternalPath) => normalizePathForComparison(eachExternalPath) === normalizedCandidate,
+    )) {
+        return true;
+    }
+    return (resolution.allDeclaredExternalDirectories ?? []).some(
+        (eachExternalDirectory) => isPathWithinManagedRoot(candidatePath, eachExternalDirectory),
     );
 }
 
@@ -130,18 +163,18 @@ export function parseExplicitTargetFromArgv(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         if (token === '--target') {
-            const value = argv[index + 1];
-            if (!value || value.startsWith('--')) {
+            const targetPath = argv[index + 1];
+            if (!targetPath || targetPath.startsWith('--')) {
                 throw new Error('--target requires a path argument');
             }
-            return value;
+            return targetPath;
         }
         if (token.startsWith('--target=')) {
-            const value = token.slice('--target='.length);
-            if (!value) {
+            const targetPath = token.slice('--target='.length);
+            if (!targetPath) {
                 throw new Error('--target requires a path argument');
             }
-            return value;
+            return targetPath;
         }
     }
     return null;

package/codex-rules/claude-dev-env.rules

@@ -0,0 +1,12 @@
+# Shared Codex exec-policy prefix rules shipped by claude-dev-env.
+# Codex loads every *.rules file under $CODEX_HOME/rules (default ~/.codex/rules).
+# This file is named claude-dev-env.rules so a local default.rules stays in place.
+# Patterns use relative repo paths only. Personal home paths stay out of this file.
+
+prefix_rule(pattern=["gemini", "--version"], decision="allow")
+prefix_rule(pattern=["git", "status", "--short", "--branch"], decision="allow")
+prefix_rule(pattern=["git", "status", "--short"], decision="allow")
+prefix_rule(pattern=["git", "diff", "--", "packages/claude-dev-env/_shared/pr-loop/scripts/code_rules_gate_parts", "packages/claude-dev-env/_shared/pr-loop/scripts/tests/test_code_rules_gate.py"], decision="allow")
+prefix_rule(pattern=["Get-Content", "-LiteralPath", "packages/claude-dev-env/_shared/pr-loop/scripts/code_rules_gate_parts/tests/_repo_test_helpers.py"], decision="allow")
+prefix_rule(pattern=["rg", "-n", "-i", "--glob", "!**/__pycache__/**", "verified_commit_gate|verifier_verdict_minter|verdict_directory_write_blocker|verify-skip|code-verifier.*commit|commit.*code-verifier", "packages/claude-dev-env"], decision="allow")
+prefix_rule(pattern=["python", "-m", "pytest", "-q", "packages/claude-dev-env/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py", "packages/claude-dev-env/hooks/blocking/test_bash_pre_tool_use_dispatcher.py", "packages/claude-dev-env/hooks/blocking/test_pre_tool_use_dispatcher.py", "packages/claude-dev-env/hooks/blocking/test_verdict_directory_write_blocker.py"], decision="allow")

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.14.1",
+    "version": "2.15.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -26,6 +26,7 @@
         "installable-surfaces.manifest.json",
         "_shared/",
         "audit-rubrics/",
+        "codex-rules/",
         "AGENTS.md",
         "CLAUDE.md",
         "!**/__pycache__/**",

package/scripts/sync_to_cursor/AGENTS.md

@@ -6,12 +6,12 @@ Python package that syncs Claude rules and docs to Cursor `.mdc` files. Entry po
 
 | File | Purpose |
 |---|---|
-| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest |
-| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format |
+| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest; `--claude-root` and `--cursor-root` select explicit layouts |
+| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format; maps remaining `rules/*.md` files to `<stem>.mdc` |
 | `canonical_docs.py` | Checks and syncs canonical documentation files (`CODE_RULES.md`, `TEST_QUALITY.md`) to the Cursor rules directory |
 | `paths.py` | Resolves the Claude and Cursor layout paths; respects the `LLM_SETTINGS_ROOT` env var for non-home layouts |
 | `hashing.py` | SHA-256 helpers that detect whether source files changed since the last sync run |
-| `config.py` | Package-level constants: `GENERATOR_VERSION`, `CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES` |
+| `config/` | Package-level constants: `GENERATOR_VERSION`, `ALL_CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES`, skipped inventory filenames, markdown suffix |
 | `__init__.py` | Empty package marker |
 
 ## Layout resolution

package/scripts/sync_to_cursor/canonical_docs.py

@@ -3,7 +3,7 @@
 import shutil
 from pathlib import Path
 
-from sync_to_cursor.config import CANONICAL_DOC_FILES
+from sync_to_cursor.config import ALL_CANONICAL_DOC_FILES
 from sync_to_cursor.hashing import sha256_bytes
 
 
@@ -17,19 +17,19 @@ def sync_canonical_docs(
     if not dry_run:
         docs_out.mkdir(parents=True, exist_ok=True)
     new_docs: dict = {}
-    for name in CANONICAL_DOC_FILES:
-        src = claude / "docs" / name
-        dst = docs_out / name
+    for each_name in ALL_CANONICAL_DOC_FILES:
+        src = claude / "docs" / each_name
+        dst = docs_out / each_name
         if not src.is_file():
             if dst.is_file():
                 if not dry_run:
                     dst.unlink()
                 if not quiet:
-                    print(f"WARN     docs/{name} (source removed — deleted stale copy at {dst})")
+                    print(f"WARN     docs/{each_name} (source removed — deleted stale copy at {dst})")
             elif not quiet:
-                print(f"WARN     docs/{name} (missing source: {src})")
+                print(f"WARN     docs/{each_name} (missing source: {src})")
             continue
-        key = f"docs/{name}"
+        key = f"docs/{each_name}"
         src_hash = sha256_bytes(src.read_bytes())
         if dry_run:
             if dst.is_file():
@@ -44,10 +44,10 @@ def sync_canonical_docs(
 
 
 def check_canonical_docs(claude: Path, cursor: Path, docs_entries: dict) -> bool:
-    for name in CANONICAL_DOC_FILES:
-        key = f"docs/{name}"
-        src = claude / "docs" / name
-        dst = cursor / "docs" / name
+    for each_name in ALL_CANONICAL_DOC_FILES:
+        key = f"docs/{each_name}"
+        src = claude / "docs" / each_name
+        dst = cursor / "docs" / each_name
         if not src.is_file():
             if key in docs_entries:
                 return False

package/scripts/sync_to_cursor/config/__init__.py

@@ -0,0 +1,8 @@
+"""Shared configuration for the sync-to-cursor package."""
+
+GENERATOR_VERSION: str = "1.3.0"
+ALL_CANONICAL_DOC_FILES: tuple[str, ...] = ("CODE_RULES.md", "TEST_QUALITY.md")
+MAX_RULE_BODY_LINES: int = 50
+ALL_SKIPPED_RULE_FILE_NAMES: frozenset[str] = frozenset({"CLAUDE.md", "AGENTS.md"})
+MARKDOWN_SUFFIX: str = ".md"
+CLAUDE_RULES_DIRECTORY_NAME: str = "rules"

package/scripts/sync_to_cursor/engine.py

@@ -140,15 +140,40 @@ def _sync_rules(
     return summary, new_entries
 
 
+def _layout_from_args(args: argparse.Namespace) -> tuple[Path, Path, Path, Path]:
+    """Resolve Claude and Cursor roots from flags or the default layout.
+
+    Args:
+        args: Parsed CLI arguments.
+
+    Returns:
+        Claude root, Cursor root, rules output directory, and manifest path.
+
+    Raises:
+        SystemExit: When only one of `--claude-root` / `--cursor-root` is set.
+    """
+    claude_root = args.claude_root
+    cursor_root = args.cursor_root
+    if (claude_root is None) != (cursor_root is None):
+        raise SystemExit("both --claude-root and --cursor-root are required")
+    if claude_root is None:
+        return llm_layout_paths()
+    claude = Path(claude_root).expanduser().resolve()
+    cursor = Path(cursor_root).expanduser().resolve()
+    return claude, cursor, cursor / "rules", cursor / ".sync-manifest.json"
+
+
 def run(argv: list[str] | None = None) -> int:
     argument_parser = argparse.ArgumentParser(description="Sync Claude rules to Cursor .mdc files")
     argument_parser.add_argument("--force", action="store_true", help="Regenerate all outputs")
     argument_parser.add_argument("--dry-run", action="store_true", help="Print actions only")
     argument_parser.add_argument("--check", action="store_true", help="Exit 1 if anything stale")
     argument_parser.add_argument("--quiet", action="store_true", help="Minimal output when up to date")
+    argument_parser.add_argument("--claude-root", help="Claude layout root holding rules/ and docs/")
+    argument_parser.add_argument("--cursor-root", help="Cursor layout root receiving rules/ and docs/")
     args = argument_parser.parse_args(argv)
 
-    claude, cursor, out_dir, manifest_path = llm_layout_paths()
+    claude, cursor, out_dir, manifest_path = _layout_from_args(args)
     mappings = build_mappings(claude)
     old_manifest = _load_manifest(manifest_path)
     entries_meta: dict = old_manifest.get("entries", {})

package/scripts/sync_to_cursor/rules.py

@@ -7,7 +7,12 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal
 
-from sync_to_cursor.config import MAX_RULE_BODY_LINES
+from sync_to_cursor.config import (
+    ALL_SKIPPED_RULE_FILE_NAMES,
+    CLAUDE_RULES_DIRECTORY_NAME,
+    MARKDOWN_SUFFIX,
+    MAX_RULE_BODY_LINES,
+)
 
 
 def _parse_h2_sections(markdown: str) -> dict[str, str]:
@@ -412,6 +417,61 @@ def _path_scoped_mappings(rules_directory: Path, docs_directory: Path) -> tuple[
     )
 
 
+def _description_from_rule_file(rule_file: Path, fallback_key: str) -> str:
+    """Return the first markdown heading, or the rule key with spaces.
+
+    Args:
+        rule_file: Claude rule markdown to read.
+        fallback_key: Stem used when the file has no heading.
+
+    Returns:
+        A one-line Cursor `description` value.
+    """
+    for each_line in rule_file.read_text(encoding="utf-8").splitlines():
+        stripped = each_line.strip()
+        if stripped.startswith("# "):
+            return stripped[2:].strip()
+    return fallback_key.replace("-", " ")
+
+
+def _discovered_mappings(
+    rules_directory: Path, all_covered_source_names: set[str]
+) -> tuple[RuleMapping, ...]:
+    """Map remaining `*.md` rule files to `<stem>.mdc` Cursor rules.
+
+    Args:
+        rules_directory: Claude `rules/` directory.
+        all_covered_source_names: Rule filenames already claimed by curated mappings.
+
+    Returns:
+        One mapping per remaining markdown rule, sorted by filename.
+    """
+    if not rules_directory.is_dir():
+        return ()
+    all_discovered: list[RuleMapping] = []
+    for each_rule_file in sorted(rules_directory.glob("*.md")):
+        if each_rule_file.name in ALL_SKIPPED_RULE_FILE_NAMES:
+            continue
+        if each_rule_file.name in all_covered_source_names:
+            continue
+        key = each_rule_file.stem
+        paths_glob = _read_paths_glob(each_rule_file)
+        has_paths = paths_glob is not None
+        all_discovered.append(
+            RuleMapping(
+                key,
+                (each_rule_file,),
+                f"{key}.mdc",
+                not has_paths,
+                paths_glob,
+                _description_from_rule_file(each_rule_file, key),
+                "verbatim",
+                strip_leading_frontmatter=has_paths,
+            )
+        )
+    return tuple(all_discovered)
+
+
 def build_mappings(claude: Path) -> tuple[RuleMapping, ...]:
     """Resolve every rule into a concrete Cursor mapping against a Claude layout.
 
@@ -420,14 +480,25 @@ def build_mappings(claude: Path) -> tuple[RuleMapping, ...]:
 
     Returns:
         One RuleMapping per rule, each path-scoped rule carrying a glob derived
-        from its source rule's `paths:` frontmatter.
+        from its source rule's `paths:` frontmatter. Curated mappings come first,
+        then one generated mapping per remaining `rules/*.md` file.
     """
     rules_directory = claude / "rules"
     docs_directory = claude / "docs"
-    all_mappings = (
+    all_curated = (
         *_always_apply_mappings(rules_directory, docs_directory),
         *_path_scoped_mappings(rules_directory, docs_directory),
     )
-    mapping_by_key = {each_mapping.key: each_mapping for each_mapping in all_mappings}
+    mapping_by_key = {each_mapping.key: each_mapping for each_mapping in all_curated}
     assert set(mapping_by_key) == set(_merged_mapping_key_order)
-    return tuple(mapping_by_key[each_key] for each_key in _merged_mapping_key_order)
+    ordered_curated = tuple(mapping_by_key[each_key] for each_key in _merged_mapping_key_order)
+    all_covered_source_names = {
+        each_source.name
+        for each_mapping in ordered_curated
+        for each_source in each_mapping.sources
+        if each_source.suffix == MARKDOWN_SUFFIX
+        and each_source.parent.name == CLAUDE_RULES_DIRECTORY_NAME
+    }
+    return ordered_curated + _discovered_mappings(
+        rules_directory, all_covered_source_names
+    )

package/scripts/tests/AGENTS.md

@@ -10,6 +10,8 @@ pytest suite for the Python scripts and Pester suite for the PowerShell scripts
 | `test_setup_project_paths_config.py` | Configuration constants used by `setup_project_paths.py` |
 | `test_sweep_empty_dirs.py` | `sweep_empty_dirs.py` — age check, one-shot mode, and continuous-watch behavior |
 | `test_sync_to_cursor.py` | `sync_to_cursor/` package — mapping, hashing, manifest, and path resolution |
+| `test_rules.py` | Discovered Claude `rules/*.md` mappings to stem-named Cursor `.mdc` files |
+| `test_engine.py` | `sync_to_cursor` engine `--claude-root` / `--cursor-root` layout flags |
 | `test_grok_worker_constants.py` | `grok_worker_constants.py` — the accepted batch worker-key set stays in step with the worker key constants, and the unknown-key message names both its placeholders |
 
 ## PowerShell test files

package/scripts/tests/test_engine.py

@@ -0,0 +1,102 @@
+"""Tests for sync_to_cursor engine CLI roots."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from sync_to_cursor.engine import run as run_sync_to_cursor
+
+_CODE_STANDARDS_SECTION_ORDER = (
+    "COMMENT PRESERVATION",
+    "CORE PRINCIPLES",
+    "⚡ HOOK-ENFORCED RULES",
+    "3. REUSE CONSTANTS / 4. CONFIG LOCATIONS",
+    "5. NO ABBREVIATIONS",
+    "6. COMPLETE TYPE HINTS",
+    "9. SELF-CONTAINED COMPONENTS",
+)
+_TEST_QUALITY_SECTION_ORDER = (
+    "Delete Useless Tests",
+    "Test Dependencies MUST FAIL",
+    "Core Testing Principles",
+    "React Testing Patterns",
+    "Test File Organization",
+)
+
+
+def _write_minimal_curated_rules(rules_directory: Path) -> None:
+    rules_directory.mkdir(parents=True, exist_ok=True)
+    (rules_directory / "code-standards.md").write_text(
+        "# Code standards stub\n", encoding="utf-8"
+    )
+    (rules_directory / "tasklings-preferences.md").write_text(
+        '---\npaths:\n  - "Y:/x/**"\n---\n\n# Tasklings\n',
+        encoding="utf-8",
+    )
+    (rules_directory / "bdd.md").write_text("# BDD\n", encoding="utf-8")
+    (rules_directory / "testing.md").write_text(
+        '---\npaths:\n  - "**/test_*.py"\n---\n\n# Testing\n',
+        encoding="utf-8",
+    )
+    (rules_directory / "research-mode.md").write_text("# RM\n", encoding="utf-8")
+    (rules_directory / "conservative-action.md").write_text("# CA\n", encoding="utf-8")
+    (rules_directory / "explore-thoroughly.md").write_text("# ET\n", encoding="utf-8")
+
+
+def _write_minimal_docs(docs_directory: Path) -> None:
+    docs_directory.mkdir(parents=True, exist_ok=True)
+    (docs_directory / "CODE_RULES.md").write_text(
+        "\n\n".join(f"## {title}\n\nalpha" for title in _CODE_STANDARDS_SECTION_ORDER)
+        + "\n",
+        encoding="utf-8",
+    )
+    (docs_directory / "TEST_QUALITY.md").write_text(
+        "\n\n".join(f"## {title}\n\nbeta" for title in _TEST_QUALITY_SECTION_ORDER)
+        + "\n",
+        encoding="utf-8",
+    )
+
+
+def test_explicit_roots_write_stem_named_mdc(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    claude = tmp_path / "claude-home"
+    cursor = tmp_path / "cursor-home"
+    _write_minimal_curated_rules(claude / "rules")
+    _write_minimal_docs(claude / "docs")
+    (claude / "rules" / "plain-language.md").write_text(
+        "# Plain language\n\nUse short sentences.\n",
+        encoding="utf-8",
+    )
+    (claude / "rules" / "CLAUDE.md").write_text("# Inventory\n", encoding="utf-8")
+    monkeypatch.delenv("LLM_SETTINGS_ROOT", raising=False)
+    assert cursor.exists() is False
+    assert (
+        run_sync_to_cursor(
+            [
+                "--force",
+                "--claude-root",
+                str(claude),
+                "--cursor-root",
+                str(cursor),
+            ]
+        )
+        == 0
+    )
+    generated = (cursor / "rules" / "plain-language.mdc").read_text(encoding="utf-8")
+    assert 'description: "Plain language"' in generated
+    assert "alwaysApply: true" in generated
+    assert "Use short sentences." in generated
+    assert not (cursor / "rules" / "CLAUDE.mdc").is_file()
+
+
+def test_explicit_roots_require_both_flags(tmp_path: Path) -> None:
+    with pytest.raises(SystemExit):
+        run_sync_to_cursor(["--force", "--claude-root", str(tmp_path)])

package/scripts/tests/test_rules.py

@@ -0,0 +1,79 @@
+"""Tests for discovered Claude-to-Cursor rule mappings."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from sync_to_cursor.rules import build_mappings
+
+_PACKAGE_ROOT = _SCRIPTS_DIR.parent
+_SKIPPED_RULE_FILE_NAMES = frozenset({"CLAUDE.md", "AGENTS.md"})
+
+
+def _write_minimal_curated_rules(rules_directory: Path) -> None:
+    rules_directory.mkdir(parents=True, exist_ok=True)
+    (rules_directory / "code-standards.md").write_text(
+        "# Code standards stub\n", encoding="utf-8"
+    )
+    (rules_directory / "tasklings-preferences.md").write_text(
+        '---\npaths:\n  - "Y:/x/**"\n---\n\n# Tasklings\n',
+        encoding="utf-8",
+    )
+    (rules_directory / "bdd.md").write_text("# BDD\n", encoding="utf-8")
+    (rules_directory / "testing.md").write_text(
+        '---\npaths:\n  - "**/test_*.py"\n---\n\n# Testing\n',
+        encoding="utf-8",
+    )
+    (rules_directory / "research-mode.md").write_text("# RM\n", encoding="utf-8")
+    (rules_directory / "conservative-action.md").write_text("# CA\n", encoding="utf-8")
+    (rules_directory / "explore-thoroughly.md").write_text("# ET\n", encoding="utf-8")
+
+
+def test_build_mappings_emits_stem_mdc_for_remaining_claude_rules(
+    tmp_path: Path,
+) -> None:
+    claude = tmp_path / ".claude"
+    _write_minimal_curated_rules(claude / "rules")
+    (claude / "docs").mkdir(parents=True, exist_ok=True)
+    (claude / "rules" / "plain-language.md").write_text(
+        "# Plain language\n\nBe brief.\n",
+        encoding="utf-8",
+    )
+    (claude / "rules" / "CLAUDE.md").write_text(
+        "# Package inventory\n", encoding="utf-8"
+    )
+    (claude / "rules" / "AGENTS.md").write_text("# Agent inventory\n", encoding="utf-8")
+    mappings = build_mappings(claude)
+    output_by_key = {each_mapping.key: each_mapping for each_mapping in mappings}
+    discovered = output_by_key["plain-language"]
+    assert discovered.output_name == "plain-language.mdc"
+    assert discovered.always_apply is True
+    assert discovered.description == "Plain language"
+    assert "CLAUDE.md" not in {
+        each_source.name
+        for each_mapping in mappings
+        for each_source in each_mapping.sources
+    }
+    assert "AGENTS.md" not in {
+        each_source.name
+        for each_mapping in mappings
+        for each_source in each_mapping.sources
+    }
+
+
+def test_every_shipped_claude_rule_maps_to_an_mdc() -> None:
+    mappings = build_mappings(_PACKAGE_ROOT)
+    output_name_by_rule_file = {}
+    for each_mapping in mappings:
+        for each_source in each_mapping.sources:
+            if each_source.parent.name == "rules" and each_source.suffix == ".md":
+                output_name_by_rule_file[each_source.name] = each_mapping.output_name
+    for each_rule_file in sorted((_PACKAGE_ROOT / "rules").glob("*.md")):
+        if each_rule_file.name in _SKIPPED_RULE_FILE_NAMES:
+            continue
+        assert each_rule_file.name in output_name_by_rule_file, each_rule_file.name

package/scripts/sync_to_cursor/config.py

@@ -1,5 +0,0 @@
-"""Shared configuration for the sync-to-cursor package."""
-
-GENERATOR_VERSION: str = "1.2.3"
-CANONICAL_DOC_FILES: tuple[str, ...] = ("CODE_RULES.md", "TEST_QUALITY.md")
-MAX_RULE_BODY_LINES: int = 50