rulesync 16.18.0 → 16.20.0

package/dist/cli/index.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_import = require("../import-BQpUs1JO.cjs");
+const require_import = require("../import-BlhbArzI.cjs");
 let commander = require("commander");
 let zod_mini = require("zod/mini");
 let node_fs_promises = require("node:fs/promises");
@@ -9,6 +9,7 @@ let node_readline_promises = require("node:readline/promises");
 let jsonc_parser = require("jsonc-parser");
 let node_os = require("node:os");
 node_os = require_import.__toESM(node_os, 1);
+let node_util = require("node:util");
 let js_yaml = require("js-yaml");
 let node_fs = require("node:fs");
 node_fs = require_import.__toESM(node_fs, 1);
@@ -16,7 +17,6 @@ let node_crypto = require("node:crypto");
 node_crypto = require_import.__toESM(node_crypto, 1);
 let es_toolkit_promise = require("es-toolkit/promise");
 let node_child_process = require("node:child_process");
-let node_util = require("node:util");
 let _octokit_request_error = require("@octokit/request-error");
 let _octokit_rest = require("@octokit/rest");
 let node_zlib = require("node:zlib");
@@ -1165,7 +1165,7 @@ async function walkDirectory(dir, outputRoot, depth = 0, ctx = {
 }, logger) {
 	if (depth > MAX_WALK_DEPTH) throw new GitClientError(`Directory tree exceeds max depth of ${MAX_WALK_DEPTH}: "${dir}". Aborting to prevent resource exhaustion.`);
 	const results = [];
-	for (const name of await require_import.listDirectoryFiles(dir)) {
+	for (const name of await require_import.listDirectoryEntryNames(dir)) {
 		if (name === ".git") continue;
 		const fullPath = (0, node_path.join)(dir, name);
 		if (await require_import.isSymlink(fullPath)) {
@@ -2158,16 +2158,54 @@ function getSourceFilters(sourceEntry) {
 		rules: sourceEntry.rules
 	};
 }
+/**
+* The name, within the rules tree, of the subdirectory holding the fetched copy
+* of remote rules. Taken as the last segment of the feature subdirectory rather
+* than by subtracting one path from another, so no separator spelling is
+* involved on either side.
+*
+* Split on the native separator, the one the constant was joined with and the one
+* the path it is compared against is split on. The posix reading would leave the
+* whole `rules\\.curated` on Windows, where it matches no segment at all.
+*/
+const CURATED_RULES_SUBDIR_NAME = (0, node_path.basename)(require_import.CURATED_RULES_FEATURE_SUBDIR);
+/**
+* The names of the rules the project holds itself, which take precedence over
+* the rules a source offers under the same name.
+*
+* Walked rather than globbed: globby reads a backslash as a path separator and
+* rewrites it in the paths it returns, so a rule file named `back\\slash.md`
+* would be recorded as the rule `back/slash`, a name no rule on disk has. No
+* remote rule can be named that either — `isValidRuleName` rejects a separator
+* — so nothing is skipped over it today; the set simply has to say what the
+* project holds, since that is the whole question it answers.
+*
+* The `.md` test is case-sensitive to match the glob that loads the rules, so a
+* name can only land in this set if a rule of that name really loads. A
+* `NOTES.MD` counted here but not loaded there would shadow the remote `NOTES`
+* and leave the project with neither. The walk is de-duplicated by file
+* identity for the same reason: it reports every name it passes, while the
+* loader's glob keeps one name per file, so a rule shared inside the tree
+* through a symbolic link would otherwise be counted under an alias the loader
+* never uses -- shadowing the remote rule of that name while loading nothing
+* under it.
+*
+* The curated subtree is named rather than left to the walk's hidden-entry
+* rule, which happens to cover it today only because the name starts with a
+* dot. Reading a fetched rule as a local one is not a small mistake: it would
+* take precedence over its own source and never be refreshed again. Its own
+* first segment is compared, not a prefix of the path, so a rule really named
+* `.curated-notes/x.md` is left alone. The split is on the native separator
+* alone: the walk joins with it, and a backslash inside a name -- the very
+* thing the walk exists to preserve -- must not divide a segment in two.
+*/
 async function getLocalRuleNames(projectRoot) {
 	const rulesDir = (0, node_path.join)(projectRoot, require_import.RULESYNC_RULES_RELATIVE_DIR_PATH);
-	const files = await require_import.findFilesByGlobs((0, node_path.join)(rulesDir, "**", "*.md"));
-	const localNames = /* @__PURE__ */ new Set();
-	for (const file of files) {
-		const relativePath = (0, node_path.relative)(rulesDir, file);
-		if (relativePath.startsWith(`.curated${node_path.sep}`)) continue;
-		localNames.add(relativePath.replace(/\.md$/i, ""));
-	}
-	return localNames;
+	const relativePaths = await require_import.listFilePathsRecursively(rulesDir, {
+		nameFilter: (name) => name.endsWith(".md"),
+		deduplicateByFileIdentity: true
+	});
+	return new Set(relativePaths.filter((relativePath) => relativePath.split(node_path.sep)[0] !== CURATED_RULES_SUBDIR_NAME).map((relativePath) => relativePath.replace(/\.md$/, "")));
 }
 async function getInstalledSourceSkillNames({ sources, projectRoot, logger }) {
 	const lock = await readLockFile({
@@ -4163,11 +4201,11 @@ const DOCS_CONTENT = {
 	"guide/separate-input-root": "# Separate Input Root\n\nThe `--input-roots <paths...>` flag lets you point `rulesync generate` at one or more rulesync source directories other than the current working directory. This decouples where your rule definitions live from where the generated tool configuration files are written.\n\nEach entry in `--input-roots` is a **rulesync source tree** — the directory that directly contains `rules/`, `skills/`, `mcp.jsonc`, and the other rulesync source files. The path you pass is read exactly as given: `--input-roots ~/.aiglobal/.rulesync` reads rules from `~/.aiglobal/.rulesync/rules/`, skills from `~/.aiglobal/.rulesync/skills/`, and so on.\n\nWhen you pass more than one entry, Rulesync reads all of them and merges the result. The typical reason to do this is to layer a personal or per-machine override tree on top of a shared team tree — see [Combining multiple source trees](#combining-multiple-source-trees) below.\n\n> **Currently supported on `generate` only.** At present, `--input-roots`/`--input-root` are wired into the `rulesync generate` command only. Other commands (`import`, `convert`, `gitignore`, `install`, `fetch`, `init`) still read `.rulesync/` from the current working directory. To use the same source directory with those commands, `cd` into the source-tree's parent directory first.\n\n## Primary use case: centralized rules across all repos\n\nA common workflow is to keep a single set of AI rules in a shared source tree (e.g. `~/.aiglobal/.rulesync/`) and apply them to every project without switching directories:\n\n```bash\n# In any project directory — rules are read from ~/.aiglobal/.rulesync/\nrulesync generate --input-roots ~/.aiglobal/.rulesync --targets \"*\" --features rules\n```\n\nWithout `--input-roots`, you would have to `cd ~/.aiglobal && rulesync generate` and then `cd -` back, and the output files would land in `~/.aiglobal` instead of the current project.\n\n## Step-by-step setup\n\n1. Create and initialize a shared rules directory:\n\n   ```bash\n   mkdir -p ~/.aiglobal\n   cd ~/.aiglobal\n   rulesync init\n   ```\n\n2. Edit your shared rules (`~/.aiglobal/.rulesync/rules/overview.md`, etc.) to your preferences.\n\n3. From any project, generate configurations using the shared rules:\n\n   ```bash\n   # In your project directory\n   rulesync generate --input-roots ~/.aiglobal/.rulesync --targets claudecode --features rules\n   ```\n\n## Combining multiple source trees\n\nThe most common reason to pass more than one entry to `--input-roots` is **per-developer local overrides**: check a shared `.rulesync/` tree into version control and let each developer keep an optional untracked `.rulesync.local/` tree next to it for their own tweaks.\n\n`rulesync gitignore` adds `.rulesync.local/` to the generated ignore list, so an overlay tree with that\nconventional name stays untracked without any extra setup. Any other name is not recognized, so if you\ncall your overlay something else (for example `.rulesync.dev/`), add it to `.gitignore` yourself — an\noverlay tree can hold personal MCP credentials and permission settings that must not be committed.\n\n```bash\nrulesync generate --input-roots ./.rulesync ./.rulesync.local --targets \"*\" --features rules,mcp\n```\n\nWith this invocation, Rulesync reads both trees and merges them: files that only exist in `./.rulesync` are used as-is, and any file `./.rulesync.local` also provides replaces the shared version. For example, if a developer creates `./.rulesync.local/rules/coding-style.md`, it replaces `./.rulesync/rules/coding-style.md` only on that developer's machine.\n\nThe same mechanism works for other layouts — for example, a globally shared base plus a per-repo overlay:\n\n```bash\nrulesync generate --input-roots ~/.aiglobal/.rulesync ./.rulesync --targets \"*\" --features rules,mcp\n```\n\n### Merge rules per feature\n\nThe general rule is: later entries win. Each feature refines that rule slightly:\n\n- **Rules, commands, subagents, checks, skills** — merged file-by-file (case-insensitive). Files present only in an earlier tree are kept; a file that also exists in a later tree replaces the earlier version. A skill directory is replaced as a single unit (all of its companion files together). Differently cased names that collapse to the same identity produce a warning instead of being dropped silently; the comparison also normalizes Unicode (NFC), so the composed and decomposed spellings of an accented name — one file on macOS — are treated as the same entry.\n- **MCP** — merged one level into the JSON: the top-level `mcpServers` map and each `<toolname>.mcpServers` map are merged by server name (later wins per key). An individual server config is replaced as a whole; patching just its `args` or `env` is not supported.\n- **Hooks, permissions, ignore** — the last tree that provides the file wins the whole file. There is no line-level merge. When more than one tree provides the file, Rulesync warns which tree won and which ones it replaced, so the dropped content is easy to trace — these files decide what an agent may read and run, so a silent whole-file replacement would be easy to miss.\n\nRoot order is the primary precedence rule. Within a single source tree, a rule or skill outside `.curated/` takes precedence over a same-named curated artifact. That comparison is case-insensitive for the same reason the cross-root merge is — the two names are one file on macOS and Windows — so a curated `shared.md` is skipped even when the local file is spelled `Shared.md`. A case-only match is reported as a warning, because on a case-sensitive filesystem the two are genuinely distinct files. After that per-tree choice is made, a later input root replaces an earlier root's effective artifact even when the later artifact is curated.\n\nThe first source tree is the required base and must exist, though it may be empty. Later source trees are optional overlays: a missing overlay contributes nothing, and `--watch` starts reading it if the directory is created while Rulesync is running. This lets teams commit `inputRoots: [\"./.rulesync\", \"./.rulesync.local\"]` without requiring every developer to create `.rulesync.local/`. An existing overlay may also supply just one feature — for example, only `mcp.jsonc`.\n\n## Setting input roots in `rulesync.jsonc`\n\nYou can set the same value in `rulesync.jsonc` (or `rulesync.local.jsonc`) instead of passing it on the command line:\n\n```jsonc\n{\n  \"inputRoots\": [\"./.rulesync\", \"./.rulesync.local\"],\n}\n```\n\n## Deprecated `--input-root` (singular)\n\nAn older, singular `--input-root` / `inputRoot` option is still accepted for backward compatibility, but new configurations should use the plural form. If you pass it, Rulesync treats the value as the **parent** of a default `.rulesync/` directory:\n\n```bash\n# These two commands are equivalent:\nrulesync generate --input-root ~/.aiglobal\nrulesync generate --input-roots ~/.aiglobal/.rulesync\n```\n\nThe singular and plural flags cannot be combined in the same CLI invocation, and they cannot both be set in the same config file. If one config file uses the singular form and another uses the plural form, the plural form wins.\n\n## Comparison with `--global`\n\nThese two flags serve different but complementary purposes:\n\n|              | `--input-roots`                                                                  | `--global`                                                             |\n| ------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |\n| **Changes**  | Source location (which rulesync source tree(s) files are read from)              | Output location (writes to user-scope config paths, e.g. `~/.claude/`) |\n| **Use when** | Your rule definitions live in a non-CWD directory, or you overlay multiple trees | You want the output to go to the tool's global (user-scope) config     |\n\nThey can be combined. For example, to read rules from `~/.aiglobal/.rulesync` and write them to Claude Code's global settings:\n\n```bash\nrulesync generate --input-roots ~/.aiglobal/.rulesync --global --targets claudecode --features rules\n```\n\n> **`--input-roots` does not enable `--global`.** When any input root is explicitly provided, Rulesync reads source files from those trees, but output scope still follows the CLI flags: use `--global` for user-scope output, and omit it for project-scope output. A `\"global\": true` setting in the `rulesync.jsonc` under an explicit input root is **not** applied unless you also pass `--global`, and Rulesync will emit a warning when dropping it so the override is visible.\n\n## Symlinks and trust\n\nRulesync follows symbolic links during file discovery. A symlink inside a source tree that points outside it will be followed transparently, and the resolved file content will be copied into the generated output. This is intentional: it lets you centralize shared skills or rules in one place and reference them via symlinks from multiple project directories without duplication.\n\nThe trust boundary is the source tree you point Rulesync at. `--input-roots` entries are `resolve()`-ed to absolute paths before use, but there is no `realpath`-based boundary check on individual symlinks inside them. Only run Rulesync against trees you control. The narrowing is inside skill directories, whose companion files include hidden entries: a hidden entry that a link resolves to outside the skill directory is not carried and is named in a warning, and the entries a skill never carries — credential stores, build trees, `.git` — are refused by the path they resolve to, so renaming a link does not smuggle them in, as is a link resolving into a system pseudo-filesystem (`/proc`, `/sys`, `/dev`). Directory symlink cycles are handled safely — glob-based discovery results are deduplicated by the real file they resolve to, so a cycle does not produce duplicated output, while a skill directory is walked directly and keeps every entry that walk reaches. See the [File Formats § Symlinks](../reference/file-formats.md#symlinks) note for the behavior that applies across all features.\n",
 	"guide/simulated-features": "# Simulated Commands, Subagents and Skills\n\nSimulated commands, subagents and skills allow you to generate simulated features for cursor, codexcli and etc. This is useful for shortening your prompts.\n\n1. Prepare `.rulesync/commands/*.md`, `.rulesync/subagents/*.md` and `.rulesync/skills/*/SKILL.md` for your purposes.\n2. Generate simulated commands, subagents and skills for specific tools that are included in cursor, codexcli and etc.\n\n   ```bash\n   rulesync generate \\\n     --targets copilot,cursor,codexcli \\\n     --features commands,subagents,skills \\\n     --simulate-commands \\\n     --simulate-subagents \\\n     --simulate-skills\n   ```\n\n3. Use simulated commands, subagents and skills in your prompts.\n   - Prompt examples:\n\n     ```txt\n     # Execute simulated commands. By the way, `s/` stands for `simulate/`.\n     s/your-command\n\n     # Execute simulated subagents\n     Call your-subagent to achieve something.\n\n     # Use simulated skills\n     Use the skill your-skill to achieve something.\n     ```\n",
 	"guide/why-rulesync": "# Why Rulesync?\n\n## Single Source of Truth\n\nAuthor rules once, generate everywhere. Rulesync turns a unified ruleset into tool-native formats so teams stop duplicating instructions across multiple AI assistants.\n\n## Tool Freedom Without Friction\n\nLet developers pick the assistant that fits their flow—Copilot, Cursor, Cline, Claude Code, and more—without rewriting team standards.\n\n## Clean, Auditable Outputs\n\nRulesync emits plain configuration files you can commit, review, and ship. If you ever uninstall Rulesync, your generated files keep working.\n\n## Fast Onboarding & Consistency\n\nNew team members get the same conventions, context, and guardrails immediately, keeping code style and quality consistent across tools.\n\n## Multi-Tool & Modular Workflows\n\nCompose rules, MCP configs, commands, and subagents for different tools or scopes (project vs. global) without fragmenting your workflow.\n\n## Ready for What's Next\n\nAI tool ecosystems evolve quickly. Rulesync helps you add, switch, or retire tools while keeping your rules intact.\n",
-	"reference/cli-commands": "# CLI Commands\n\n## Quick Commands\n\n```bash\n# Initialize new project (recommended: organized rules structure)\nrulesync init\n\n# Import existing configurations (to .rulesync/rules/ by default)\nrulesync import --targets claudecode --features rules,mcp,commands,subagents,skills,permissions\n\n# Import components from an existing plugin directory\nrulesync import --targets claudecode-plugin --features skills,hooks --output-root ./plugins/review-tools\n\n# Convert configurations from one tool to other tools (skips .rulesync/)\nrulesync convert --from cursor --to copilot,claudecode\nrulesync convert --from cursor --to copilot,claudecode --features rules,mcp\n\n# Fetch configurations from a Git repository\nrulesync fetch owner/repo\nrulesync fetch owner/repo@v1.0.0 --features rules,commands\nrulesync fetch https://github.com/owner/repo --conflict skip\n\n# Generate all features for all tools (new preferred syntax)\nrulesync generate --targets \"*\" --features \"*\"\n\n# Generate specific features for specific tools\nrulesync generate --targets copilot,cursor,cline --features rules,mcp\nrulesync generate --targets claudecode --features rules,subagents\n\n# Generate components inside an existing plugin directory\nrulesync generate --targets antigravity-plugin --features rules,mcp,subagents,skills,hooks --output-roots ./plugins/review-tools\n\n# Generate only rules (no MCP, permissions, commands, or subagents)\nrulesync generate --targets \"*\" --features rules\n\n# Generate simulated commands and subagents\nrulesync generate --targets copilot,cursor,codexcli --features commands,subagents --simulate-commands --simulate-subagents\n\n# Dry run: show changes without writing files\nrulesync generate --dry-run --targets claudecode --features rules\n\n# Check if files are up to date (for CI/CD pipelines)\nrulesync generate --check --targets \"*\" --features \"*\"\n\n# Generate from a shared source tree (without cd-ing into it)\nrulesync generate --input-roots ~/.aiglobal/.rulesync --targets \"*\" --features rules\n\n# Install rules and skills from declarative sources in rulesync.jsonc\nrulesync install\n\n# Add a source to rulesync.jsonc, update the lockfile, and install it\nrulesync add anthropics/skills --skills skill-creator\n\n# Add a rule source without selecting skills\nrulesync add acme/ai-standards --rules testing-guidelines\n\n# Force re-resolve all source refs (ignore lockfile)\nrulesync install --update\n\n# Fail if lockfile is missing or out of sync (for CI); fetch missing artifacts using locked refs\nrulesync install --frozen\n\n# Install then generate (typical workflow)\nrulesync install && rulesync generate\n\n# Add generated files to .gitignore\nrulesync gitignore\n\n# Add only specific tool entries to .gitignore\nrulesync gitignore --targets claudecode,copilot\n\n# Add only specific feature entries to .gitignore\nrulesync gitignore --targets copilot --features rules,commands\n\n# Diagnose the configuration files for common problems (read-only)\nrulesync doctor\n\n# Diagnose and fail CI on warnings too\nrulesync doctor --strict\n\n# Print GitHub release notes for a repository (latest 10 by default)\nrulesync release-notes dyoshikawa/rulesync\n\n# Print the most recent 5 releases\nrulesync release-notes dyoshikawa/rulesync --latest 5\n\n# Update rulesync to the latest version (single-binary installs)\nrulesync update\n\n# Check for updates without installing\nrulesync update --check\n\n# Force update even if already at latest version\nrulesync update --force\n```\n\n> **Deprecated feature:** `ignore` remains available to existing projects throughout Rulesync 14.x, but new projects should use `permissions`. Any removal will be decided separately and will not occur before a future major release.\n\n## Generate Command\n\nThe `generate` command reads source files from one or more rulesync source trees (default: `<cwd>/.rulesync`; configurable via `--input-roots`) and writes AI tool configuration files to the output directories.\n\n### Options\n\n| Option                      | Description                                                                                                                                                                                                                                                                                                                                                                               | Default               |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |\n| `--targets, -t <tools>`     | Comma-separated list of tools (e.g. `claudecode,copilot` or `*`)                                                                                                                                                                                                                                                                                                                          | From `rulesync.jsonc` |\n| `--features, -f <features>` | Comma-separated list of features (rules, commands, subagents, skills, mcp, hooks, permissions, checks; deprecated: ignore)                                                                                                                                                                                                                                                                | From `rulesync.jsonc` |\n| `--input-roots <paths...>`  | Ordered list of rulesync source-tree directories (e.g. `.rulesync`, `.rulesync.local`). Each entry is a source tree itself — no `.rulesync/` join is applied. The first root is required; later roots are optional overlays and may be absent. Later entries override earlier ones for the same relative source path (currently `generate` only). Cannot be combined with `--input-root`. | `<cwd>/.rulesync`     |\n| `--input-root <path>`       | **Deprecated.** Path to the PARENT directory of a `.rulesync/` source tree; kept for backward compatibility and expands internally to `--input-roots <path>/.rulesync`. Prefer `--input-roots`. Cannot be combined with it.                                                                                                                                                               | CWD                   |\n| `--dry-run`                 | Show what would change without writing files                                                                                                                                                                                                                                                                                                                                              | `false`               |\n| `--check`                   | Like `--dry-run` but exits with code 1 if files are not up to date                                                                                                                                                                                                                                                                                                                        | `false`               |\n| `--global`                  | Generate for global (user-scope) configuration files                                                                                                                                                                                                                                                                                                                                      | `false`               |\n| `--simulate-commands`       | Generate simulated commands for tools that do not support them natively                                                                                                                                                                                                                                                                                                                   | `false`               |\n| `--simulate-subagents`      | Generate simulated subagents for tools that do not support them natively                                                                                                                                                                                                                                                                                                                  | `false`               |\n| `--simulate-skills`         | Generate simulated skills for tools that do not support them natively                                                                                                                                                                                                                                                                                                                     | `false`               |\n| `--delete`                  | Delete existing generated files before writing                                                                                                                                                                                                                                                                                                                                            | From `rulesync.jsonc` |\n| `--watch, -w`               | Keep running and regenerate whenever rulesync source files change                                                                                                                                                                                                                                                                                                                         | `false`               |\n\n> **Note on `--delete` and shared output directories:** Several targets write\n> into one directory on purpose — `.agents/agents/`, `.agents/skills/`, and the\n> rest of the cross-vendor roots. The orphan sweep runs only after every target\n> and every feature in the run has written, and it skips any path the run itself\n> produced, so one target never deletes a sibling's freshly written file and an\n> already-synchronized tree stays a no-op under `--check`. What is swept is\n> unchanged: a file in a generated directory that no `.rulesync/` source\n> produces.\n>\n> Takt's skills are the one target swept by file name rather than by directory\n> (its rules, commands, and subagents are swept normally). They are flat files\n> sharing a single `.takt/facets/knowledge/` root rather than each getting a\n> directory of its own, so what the sweep removes there is a `.md` file directly\n> under that root which no `.rulesync/skills/` source produces. The root itself\n> and anything nested inside it are left alone. See [Takt](../tools/takt.md).\n\n> **Note on unreadable sources:** This applies to the single-file features —\n> `mcp`, `hooks`, `permissions`, and `ignore` — each of which is generated from\n> one `.rulesync/` file. When that file exists but cannot be read — malformed\n> JSON/JSONC, or content the schema rejects — the problem is reported as an\n> error, the feature produces no output, and `generate` exits non-zero, naming\n> the affected features. Every other feature in the run still executes first, so\n> one bad file does not hide the rest of the errors. Because that feature's\n> output could not be regenerated, `--delete` also skips its orphan sweep,\n> leaving the previously generated files in place rather than deleting\n> configuration the run was unable to rewrite. Under `--watch` the failure is\n> reported and the watcher keeps running, so saving a corrected source\n> regenerates as usual.\n>\n> A source file that is simply absent is not an error: that feature just has\n> nothing to generate, and the run succeeds — it is still logged, but it does\n> not fail the run. Only genuine absence counts; a path that cannot even be\n> checked (a permission error, a symlink loop, a symlink whose target is gone)\n> is treated as unreadable, not as missing.\n>\n> The directory-based features handle an unparseable source file differently,\n> and not uniformly. `subagents` and `checks` report it as a warning and skip\n> that file, because their directories hold free-form Markdown that users also\n> keep notes and READMEs in; the rest of the directory still generates and the\n> run succeeds. `rules`, `commands`, and `skills` do not: an invalid frontmatter\n> there aborts `generate` with that error and a non-zero exit, without the\n> per-feature isolation described above.\n>\n> A source entry that exists but cannot be _read_ is never treated as deleted\n> for any of them, warn-and-skip features included: a `.rulesync/` file or\n> directory whose symbolic link no longer resolves, or an input root that\n> cannot be resolved, stops the run rather than letting `--delete` sweep away\n> what it was supposed to generate.\n\n### Examples\n\n```bash\n# Generate all features for all configured tools\nrulesync generate\n\n# Generate rules for all tools\nrulesync generate --targets \"*\" --features rules\n\n# Generate from a shared source tree without cd-ing into it\nrulesync generate --input-roots ~/.aiglobal/.rulesync --targets \"*\" --features rules\n\n# Dry run: preview changes without writing\nrulesync generate --dry-run --targets claudecode --features rules\n\n# CI check: fail if generated files are not up to date\nrulesync generate --check --targets \"*\" --features \"*\"\n\n# Watch mode: regenerate on every change to the sources\nrulesync generate --watch\n```\n\n### Watch mode\n\n`generate --watch` runs one generation immediately and then keeps running, regenerating whenever the rulesync sources change. It is meant for iterating on rules, commands, subagents or skills without re-running the command by hand.\n\n- **What is watched**: the `.rulesync/` source tree (recursively) plus the configuration files next to it (`rulesync.jsonc` and `rulesync.local.jsonc`, or the file passed to `--config`). Generated output is never watched, so a regeneration cannot re-trigger the watcher.\n- **Debouncing**: bursts of file-system events (editor save storms, `git checkout` switching many files) are coalesced into a single regeneration after a short quiet period. Changes that arrive while a generation is running trigger exactly one follow-up run.\n- **Errors keep the watcher alive**: a failing generation (e.g. invalid frontmatter saved mid-edit) is reported and watching continues; the process does not exit.\n- **Configuration changes**: editing the configuration file triggers a regeneration, and the new values apply to it because the configuration is re-resolved on every run. The **set of watched paths is fixed at startup**, so changing `inputRoot`/`inputRoots` (or the location of the configuration file itself) requires restarting the command. A warning is printed whenever the configuration file changes as a reminder.\n- **Incompatible flags**: `--watch` cannot be combined with `--check`, `--dry-run` or `--json`. The first two are one-shot verification modes and `--json` emits a single result document when the command exits, which never happens while watching.\n- **Stopping**: `Ctrl+C` (`SIGINT`) or `SIGTERM` closes the watchers and exits normally.\n\n### Tool home overrides win over the output root in global scope\n\nTwo tools read their profile location from an environment variable: Hermes Agent (`HERMES_HOME`) and Kimi Code (`KIMI_CODE_HOME`). When one of them is set, `generate --global` and `convert --global` write that tool's output under it, **overriding both `outputRoots` and an explicit `--output-roots`** for that target. See [Supported Tools](./supported-tools.md) for what each profile root contains. This is deliberate — the variable names where the tool itself looks, so honoring the flag instead would produce files the tool never reads. Every other target still uses the configured output root.\n\nThe override must be a usable directory: an empty value is ignored (the default profile location applies), and a value that is the filesystem root or an unnormalized path is rejected with an error naming the variable.\n\n### Shared config files are never created empty\n\nSome outputs are files Rulesync merges into rather than owns, because the tool (or you) keeps unrelated settings there: `.amp/settings.json(c)`, `.antigravity/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, `.codex/config.toml`, `.copilot/settings.json`, `.devin/config.json`, `.factory/settings.json`, `.github/copilot/settings.json`, `.grok/config.toml`, `.vibe/config.toml`, `.vscode/settings.json`, `.zcode/config.json`, `.zcode/cli/config.json`, `.zed/settings.json`, `kilo.json(c)`, `opencode.json(c)`, and `reasonix.toml`. These are deliberately **not** added to `.gitignore` by `rulesync gitignore`, so that settings you hand-author in them stay version-controlled.\n\nBecause they stay committable, `generate` will not **create** one of them just to hold an empty payload: if Rulesync has nothing to contribute (e.g. no permissions map to that tool), the file is left absent instead of being written as `{}`. A file that already exists is always rewritten as usual, so nothing you authored is dropped. Every other generated file is written even when empty, since for a file Rulesync owns its existence is part of the output.\n\n## Gitignore Command\n\nThe `gitignore` command adds generated AI tool configuration files to `.gitignore`. By default, it emits entries only for the tools listed in the `targets` of your `rulesync.jsonc` (controlled by the `gitignoreTargetsOnly` option, which defaults to `true`). Set `gitignoreTargetsOnly` to `false` to emit entries for all supported tools instead. You can also filter the output per-invocation with `--targets` / `--features`, which take precedence over the config.\n\nYou can route entries to `.gitattributes` instead by setting `gitignoreDestination` to `\"gitattributes\"` at root, tool, or tool × feature level. More specific settings take precedence.\n\n> **No `rulesync.jsonc` in the project?** Entries for all supported tools are emitted. `gitignoreTargetsOnly` is only applied when a config file exists, so users without a config still get useful `.gitignore` coverage.\n\n> **`agentsmd` entries are always included.** Even when `gitignoreTargetsOnly` is `true` and `agentsmd` is not listed in `targets`, entries for `AGENTS.md` (and related paths) are appended automatically. Because `AGENTS.md` is a de facto standard file read by many AI tools regardless of the target set, its gitignore entries are emitted unconditionally to prevent accidental commits of generated rule files. To opt out of this behavior, pass an explicit `--targets` option that omits `agentsmd`.\n\n### Options\n\n| Option                      | Description                                                                                                  | Default                                         |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |\n| `--targets, -t <tools>`     | Comma-separated list of tools to include (e.g., `claudecode,copilot` or `*` for all)                         | Derived from `targets` / `gitignoreTargetsOnly` |\n| `--features, -f <features>` | Comma-separated list of features to include (rules, commands, subagents, skills, ignore, mcp, hooks, checks) | `*` (all)                                       |\n\n### Examples\n\n```bash\n# Add all entries (default)\nrulesync gitignore\n\n# Add entries for Claude Code only\nrulesync gitignore --targets claudecode\n\n# Add entries for multiple tools\nrulesync gitignore --targets claudecode,copilot,cursor\n\n# Add only rules and commands entries for Copilot\nrulesync gitignore --targets copilot --features rules,commands\n```\n\n### Behavior\n\n- **Common entries** (e.g., `.rulesync/rules/.curated/`, `.rulesync/skills/.curated/`, `rulesync.local.jsonc`) are always included regardless of filters.\n- **General entries** (e.g., memories, settings) are always included when their target is selected.\n- When re-running, all previously generated rulesync entries are removed before writing the new filtered set.\n\n## Add Command\n\nThe `add` command can scaffold one Rulesync feature file or append one declarative source to `rulesync.jsonc`.\n\n### Feature scaffolding\n\nUse a feature keyword to create a valid, editable starter file:\n\n```bash\n# Named Markdown features\nrulesync add rule --name overview\nrulesync add command --name review-pr.md\nrulesync add subagent --name planner\nrulesync add skill --name project-context\nrulesync add check --name security\n\n# Singleton features\nrulesync add mcp\nrulesync add hooks\nrulesync add permissions\n\n# Deprecated compatibility scaffold; prefer permissions\nrulesync add ignore\n```\n\nNamed features accept a name with or without the `.md` suffix. Skills use the directory layout `.rulesync/skills/<name>/SKILL.md`; the other named features create `<name>.md` in their canonical Rulesync directory. Names cannot contain path separators.\n\nWhen the target file exists, interactive execution asks before replacing it. Declining leaves the file unchanged. JSON, silent, and non-interactive execution fail safely; pass `--force` to overwrite explicitly. Singleton scaffolds recognize supported JSONC and legacy variants and replace the effective existing file instead of creating a shadowed canonical file.\n\nFeature keywords are reserved when no source-specific option is present. To add a source whose identifier is also a feature keyword, provide a source option that makes the intent explicit, such as `rulesync add skill --transport npm`.\n\n### Declarative sources\n\nFor any other source identifier, `add` appends one source to `rulesync.jsonc` and immediately runs the declarative source resolver. It preserves JSONC comments, installs selected rules into `.rulesync/rules/.curated/`, installs selected skills into `.rulesync/skills/.curated/`, and updates `rulesync.lock` or `rulesync-npm.lock.json`.\n\n```bash\n# GitHub source (default transport)\nrulesync add anthropics/skills --skills skill-creator\n\n# Rules only; direct .md files are selected from rules/\nrulesync add acme/ai-standards --rules testing-guidelines,typescript-conventions\n\n# Rules and skills from separate paths in one source\nrulesync add acme/ai-assets --rules \"*\" --rules-path exports/rules --skills review-pr --path exports/skills\n\n# Any Git remote through the git CLI\nrulesync add https://example.com/team/skills.git --transport git --ref main --path skills\n\n# npm-compatible registry\nrulesync add @acme/skill-package --transport npm --registry https://registry.npmjs.org\n```\n\nThe selected configuration file must already exist. Run `rulesync init` first, or pass `--config <path>`. Adding a source whose normalized source identity is already present fails instead of silently creating duplicate lockfile entries; edit the existing entry when changing its options.\n\nThe operation fetches only the source being added; existing declarations are not re-fetched. Existing sources must already be locked and installed, otherwise run `rulesync install` first. The operation is transactional: if the new source fails to install, Rulesync restores the manifest, source lockfiles, curated rules, and curated skills to their pre-command state.\n\n| Option                | Description                                                                                       |\n| --------------------- | ------------------------------------------------------------------------------------------------- |\n| `--name <name>`       | Name for a rule, command, subagent, skill, or check scaffold                                      |\n| `--force`             | Replace an existing scaffold file without prompting                                               |\n| `--skills <skills>`   | Comma-separated skill names. `*` selects all skills.                                              |\n| `--rules <rules>`     | Comma-separated rule names. Names may omit `.md`; `*` selects direct `.md` files under rulesPath. |\n| `--transport <type>`  | `github` (default), `git`, or experimental `npm`                                                  |\n| `--ref <ref>`         | Git ref, npm version, or npm dist-tag                                                             |\n| `--path <path>`       | Skills path within the source; defaults to `skills`                                               |\n| `--rules-path <path>` | Rules path within the source; defaults to `rules`                                                 |\n| `--registry <url>`    | npm-compatible registry URL                                                                       |\n| `--token-env <name>`  | Environment variable containing the npm registry token                                            |\n| `--token <token>`     | GitHub token for private repositories                                                             |\n| `--config <path>`     | Configuration file to edit (default: `rulesync.jsonc`)                                            |\n\nWhen neither `--skills` nor `--rules` is provided, all skills are installed for backward compatibility. Providing only `--rules` installs no skills.\n\n## Fetch Command\n\nThe `fetch` command allows you to fetch configuration files directly from a Git repository (GitHub/GitLab).\n\n> [!NOTE]\n> This feature is in development and may change in future releases.\n\n**Note:** The fetch command searches for feature directories (`rules/`, `commands/`, `skills/`, `subagents/`, etc.) directly at the specified path, without requiring a `.rulesync/` directory structure. This allows fetching from external repositories like `vercel-labs/agent-skills` or `anthropics/skills`.\n\n### Source Formats\n\n```bash\n# Full URL format\nrulesync fetch https://github.com/owner/repo\nrulesync fetch https://github.com/owner/repo/tree/branch\nrulesync fetch https://github.com/owner/repo/tree/branch/path/to/subdir\nrulesync fetch https://gitlab.com/owner/repo  # GitLab (planned)\n\n# Prefix format\nrulesync fetch github:owner/repo\nrulesync fetch gitlab:owner/repo              # GitLab (planned)\n\n# Shorthand format (defaults to GitHub)\nrulesync fetch owner/repo\nrulesync fetch owner/repo@ref        # Specify branch/tag/commit\nrulesync fetch owner/repo:path       # Specify subdirectory\nrulesync fetch owner/repo@ref:path   # Both ref and path\n```\n\n### Options\n\n| Option                  | Description                                                                                                                                                           | Default                          |\n| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |\n| `--target, -t <target>` | Target format to interpret files as (e.g., 'rulesync', 'claudecode')                                                                                                  | `rulesync`                       |\n| `--features <features>` | Comma-separated features to fetch (rules, commands, subagents, skills, ignore, mcp, hooks, permissions, checks)                                                       | `skills`                         |\n| `--output <dir>`        | Output directory relative to project root                                                                                                                             | `.rulesync`                      |\n| `--conflict <strategy>` | Conflict resolution: `overwrite` or `skip`                                                                                                                            | `overwrite`                      |\n| `--no-prune`            | Keep local files inside a fetched skill directory that the remote skill no longer has                                                                                 | Pruning is on                    |\n| `--ref <ref>`           | Git ref (branch/tag/commit) to fetch from                                                                                                                             | Default branch                   |\n| `--path <path>`         | Subdirectory in the repository                                                                                                                                        | `.` (root)                       |\n| `--skills <skills>`     | Comma-separated skill names to fetch (requires the skills feature)                                                                                                    | All skills                       |\n| `--interactive, -i`     | Interactively select skills to fetch via a checkbox prompt; nothing is selected initially, press `<a>` to select/deselect all (requires the skills feature and a TTY) | Disabled                         |\n| `--token <token>`       | Git provider token for private repositories                                                                                                                           | `GITHUB_TOKEN` or `GH_TOKEN` env |\n\n### Pruning Fetched Skill Directories\n\nA skill is a directory (`skills/<name>/SKILL.md` plus its supporting files), not a single file. When the upstream skill drops or renames a file, an additive fetch would leave the old local copy in place, and the directory would become a mixture of the current upstream files and orphaned leftovers. Agents read whatever is in the directory, so a stale reference or an outdated script keeps steering them long after upstream removed it.\n\n**The remote skill is therefore the source of truth: by default, `fetch` deletes files inside the skill directories it fetched that the remote does not have.** Every deletion is listed in the summary, so the destructive part of the command is never silent:\n\n```text\nFetched from anthropics/skills@main:\n  ✓ skills/pdf/SKILL.md (overwritten)\n  ✗ skills/pdf/reference.md (deleted - no longer in the remote skill)\n\nSummary: 1 overwritten, 1 deleted\n```\n\nRulesync also warns separately whenever a run deleted anything, so the one part of the command that cannot be undone is not left to be spotted among the rest of the summary.\n\n> [!WARNING]\n> Pruning removes **any** file in a fetched skill directory that the remote does not have — including one you added yourself. That is what \"mirror the remote\" means. Keep your own material outside the skill directories you fetch, or pass `--no-prune`.\n>\n> This applies to whatever `--output` points at. `--output .` makes the fetched skill directories your project's own `skills/`, so a fetch there prunes the skills you maintain by hand. Fetch into the default `.rulesync/` unless you really mean to mirror a remote repository into your project root.\n\nThe scope is deliberately narrow:\n\n- Only the `skills/<name>/` directories fetched in **this** run are pruned. A skill left out by `--skills` or `--interactive` is untouched.\n- Other features (`rules/`, `commands/`, `subagents/`, …) are never pruned — the issue only exists for directory-based skills.\n- Directories the remote skill no longer has are removed as well, and are listed in the summary under their own name with a trailing slash.\n- Symbolic links are unlinked, never followed: a link inside a skill directory can only ever lose the link itself, never whatever it points at. A skill directory that is **itself** a symbolic link is not pruned at all, since deleting through it would reach outside the output directory; Rulesync warns and leaves it alone.\n- A local file that the filesystem holds as the same file as one just fetched — a second name for it on a case-insensitive or Unicode-normalizing filesystem, or a hard link — is kept, even though the remote list does not carry that name. The same applies to a symbolic link that resolves to a file or directory this run wrote: it is kept rather than unlinked, since the fetch may have written through it.\n- A skill directory Rulesync cannot read or delete from — a permission it does not hold, a disk that gave out — stops that skill's prune where it failed rather than the whole fetch. Rulesync warns, still lists whatever it had already deleted, and moves on to the next skill.\n- Nothing more than 15 directories below the skill directory is pruned. That is a limit on the local walk, deep enough that a fetched tree stays well inside it; Rulesync warns and leaves anything deeper alone.\n- A skill directory whose name ends in a dot or a space, or whose name has the `NAME~1` shape of a Windows short name, is not pruned. Some systems resolve such a name to a different directory, so the directory that name reads as may not be the directory it opens.\n- A skill directory whose name differs from another in `skills/` — one that was already there, or one this same fetch just wrote — only in ways some filesystems ignore — its case, or whether an accented letter is written composed or decomposed — is not pruned either, for the same reason: macOS and Windows resolve `skills/PDF` to an existing `skills/pdf`, and macOS resolves a decomposed name to the composed directory of the same name, so pruning it would judge the local skill's own files stale.\n- A skill whose remote listing came back incomplete — GitHub caps a directory listing at 1,000 entries, and entries such as symlinks and submodules cannot be fetched — is not pruned either. Rulesync warns instead, because a local file that upstream still ships cannot be told apart from one it dropped.\n- `--conflict skip` disables pruning. That flag says to leave existing local files alone, and it also means the local copies are not this run's output, so they cannot be judged against the remote list.\n- `--target <tool>` never prunes, because that conversion path does not fetch skills at all.\n\nPass `--no-prune` to get the old purely additive behavior.\n\n#### Remote Paths Containing a Backslash or a Colon\n\nA backslash is an ordinary character in a filename on Linux and macOS, and a directory separator on Windows. A colon is ordinary too here, and on Windows it separates a file from one of its alternate data streams, so `skills/pdf::$INDEX_ALLOCATION` is another way of writing `skills/pdf` rather than a directory of its own. A remote file whose path contains either character therefore names one file on some systems and something else on others, so `fetch` skips it and warns rather than picking an interpretation. The rest of the fetch continues normally.\n\nBecause the skipped file is still part of the remote skill, the skill directory it came from is not pruned in that run either — a local copy of a file the remote still ships would otherwise be indistinguishable from one it dropped.\n\n#### Skill Names That Look Alike\n\nA repository can publish two skill directories whose names a terminal draws the same way — `skill` spelled with a Cyrillic `ѕ`, or the fullwidth `ｓｋｉｌｌ` beside the plain one. Each is still a separate entry with its own name, so a selection writes exactly the directories that were checked; the risk is only that the two entries cannot be told apart by sight.\n\nThe interactive prompt therefore prefixes such an entry with `[!]` and the reason, ahead of the name itself:\n\n```text\n? Select skills to fetch (press <a> to select/deselect all)\n ◯ pdf\n ◯ [!] another entry differs from it only by lookalike letters — skill\n ◯ [!] another entry differs from it only by lookalike letters; mi… — ѕkill\n```\n\nThe mark comes first so that a name — which the remote repository chooses — cannot be spelled to look like a mark of its own, or reorder one away. A label wider than one line is shortened with an ellipsis for the same reason; the budget is measured in terminal columns, so a name of ideographic spaces cannot buy extra width by being few characters. The name is measured first and the reasons take the room that is left, which is why the second label above is cut: a cut takes the reasons from the tail, and the mark and the start of the first reason always survive. Two entries whose labels read alike are numbered — `(1) `, `(2) `, in front for the same reason the mark is — so they stay distinct. That covers labels shortened into the same text, and equally `git` beside `ɡit`, where both rows carry the same note and the names are one shape: the numbers do not say which row is which, but they do say there are two of them, and the value behind a label is untouched, so a shortened entry still selects the skill it names. A name that itself begins the way a marked row does is given a mark of its own saying so — judged by the shape it is drawn in rather than the characters it is spelled with, so `(l)` and a `[ǃ]` written with U+01C3 LATIN LETTER RETROFLEX CLICK are marked alongside the plain `(1)` and `[!]`.\n\nAn entry is marked for any of four reasons:\n\n- **Another entry has the same display form.** Names are compared with their hidden characters removed, normalized (NFKC), their whitespace collapsed, and lowercased, so `Skill`, `skill`, `skill ` and the fullwidth `ｓｋｉｌｌ` all collide.\n- **Another entry differs from it only by lookalike letters.** Two names that read the same once each character is replaced by the Latin letter it is drawn as — `copy` beside the same word spelled entirely in Cyrillic. A name does not have to leave the Latin alphabet to qualify: `c0py` with a zero, `ruIes` with a capital I for the l, `Ⅰist` with the Roman numeral one, and `git` with the script `ɡ` or the dotless `ı` are all marked against the plain spelling. The separator counts too, since nearly every skill name is kebab-case and a name that swaps only its hyphen for U+2010 HYPHEN — drawn identically, belonging to no script, and left alone by the compatibility normalization — would otherwise pass every check as plain ASCII. Neither name mixes scripts on its own, so this pair is visible only by comparing the two.\n- **The name reads as Latin letters but is written in another script.** Every letter of it is drawn as a Latin one without being Latin, which is the whole-script confusable of UTS #39: `copy` spelled with four Cyrillic letters is marked even when no Latin `copy` is on the list. This check uses the narrower list of letters that are drawn as a _lowercase_ Latin letter while being lowercase themselves, so an ordinary Russian or Greek word — `текст`, `κατα` — is not marked: its letters are ones whose capitals resemble Latin capitals, which is not the same thing. Cherokee, Coptic, Lisu, Osage, Deseret and Tifinagh are taken whole instead of letter by letter — a name written in nothing but one of them is marked — since those alphabets are drawn in Latin letter shapes throughout. Canadian Aboriginal Syllabics and Vai are not: their letters are shapes of their own, so a name in either reads as nothing Latin, and only a mixture with Latin is marked.\n- **The name mixes scripts.** A single name built from scripts that share letter shapes, such as `good` with a Cyrillic `о`. The alphabets treated as lookalikes are Latin, Cyrillic, Greek, Armenian, Cherokee, Coptic, Lisu, Canadian Aboriginal Syllabics, Osage, Deseret, Vai and Tifinagh, which are among the ones UTS #39 records as confusable with each other. Japanese, Korean and Chinese names mix scripts by nature and routinely carry Latin, so those combinations are not marked, and neither is Latin beside a script that shares no shapes with it.\n\nA `fetch` that shows no prompt — a plain one, or one selecting with `--skills` — prints the same reasons as a warning listing the names they apply to, so a scripted run is told what an interactive one would have been shown. The names are judged against everything the repository publishes, as the prompt judges them, and listed for what the run actually writes: `--skills c0py` is told that the name reads like another entry even though the `copy` that makes it so was never fetched.\n\nThe mark is display-only: it never removes a skill from the list. It is also not a complete answer — the table of lookalike letters holds the common pairs rather than every one, and a name written entirely in a script the table does not map is compared against nothing — so treat it as a hint to look closer, not as a guarantee that unmarked entries are distinct.\n\nNames that cannot be shown honestly at all are a separate case: a skill directory whose name carries a control character, one that draws as nothing — a zero-width space, a Hangul filler, a braille blank — or one that draws as nothing but blank space or combining marks with no letter to sit on is dropped rather than marked, with a warning naming it in stripped form. That drop applies to every `fetch`, including a plain one with neither `--skills` nor `--interactive`, because such a directory on disk cannot be told from the plain name it imitates in any line Rulesync prints.\n\nA zero-width joiner or a variation selector is dropped only where it hides something. It is kept beside the scripts that are written with one — the Arabic family, the Indic scripts, Mongolian — and beside the pictographs an emoji sequence is built from; anywhere else it can be nothing but padding, so `pdf` with a joiner in it is dropped, and so is `設定` with one between its two characters. Standing where its own script puts it — a Persian or Indic name written with a zero-width non-joiner, an emoji name built from a chain of joiners — it is left alone and the name is fetched normally. A joiner is held to both of its neighbors, since it exists to bind two characters: a name that merely ends in one is a second directory drawn exactly like the name beside it, and is dropped. A variation selector is held only to the character before it, which is the one whose form it selects, so an emoji name may end in one.\n\n#### Remote Paths in Rulesync's Output\n\nPath names come from the remote repository, so every one that Rulesync prints — the fetch summary, warnings, and debug lines — has its control characters stripped first. A crafted path cannot forge or erase the lines around it, which is what makes the record of what was written and deleted worth reading.\n\nThe `--json` output is the exception: it carries each path exactly as the repository spells it, because a machine consumer needs the real name to act on it. Anything that renders a value out of that JSON into a terminal has to strip it itself.\n\n### Examples\n\n```bash\n# Fetch skills from external repositories\nrulesync fetch vercel-labs/agent-skills\nrulesync fetch anthropics/skills\n\n# Fetch only specific skills by name\nrulesync fetch anthropics/skills --skills pdf,docx\n\n# Interactively select which skills to fetch (checkbox prompt)\n# Nothing is checked when the prompt opens: press <space> to select the\n# highlighted skill, <a> to select/deselect all, <i> to invert, and <enter> to confirm.\nrulesync fetch anthropics/skills --interactive\n\n# Interactively select skills with some pre-checked\nrulesync fetch anthropics/skills --interactive --skills pdf\n\n# Fetch all features from a public repository\nrulesync fetch dyoshikawa/rulesync --path .rulesync --features \"*\"\n\n# Fetch only rules and commands from a specific tag\nrulesync fetch owner/repo@v1.0.0 --features rules,commands\n\n# Fetch from a private repository (uses GITHUB_TOKEN env var)\nexport GITHUB_TOKEN=ghp_xxxx\nrulesync fetch owner/private-repo\n\n# Or use GitHub CLI to get the token\nGITHUB_TOKEN=$(gh auth token) rulesync fetch owner/private-repo\n\n# Preserve existing files (skip conflicts)\nrulesync fetch owner/repo --conflict skip\n\n# Keep local files a fetched skill no longer has upstream\nrulesync fetch anthropics/skills --no-prune\n\n# Fetch from a monorepo subdirectory\nrulesync fetch owner/repo:packages/my-package\n```\n\n## Convert Command\n\nThe `convert` command converts configuration files from one AI tool directly to one or more destination tools **without creating `.rulesync/` files on disk**. The intermediate rulesync representation is kept in memory only.\n\nThis is useful when you want to translate a one-shot tool-to-tool conversion (e.g., \"I have Cursor rules, give me Claude Code and Copilot equivalents\") without adopting rulesync's managed source-of-truth workflow.\n\n### Options\n\n| Option                      | Description                                                                                                               | Default   |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------- |\n| `--from <tool>`             | Source tool to convert from (single tool, e.g., `cursor`, `claudecode`)                                                   | Required  |\n| `--to <tools>`              | Comma-separated list of destination tools (e.g., `copilot,claudecode`)                                                    | Required  |\n| `--features, -f <features>` | Comma-separated list of features to convert (rules, commands, subagents, skills, ignore, mcp, hooks, permissions, checks) | `*` (all) |\n| `--verbose, -V`             | Verbose output                                                                                                            | `false`   |\n| `--silent, -s`              | Suppress all output                                                                                                       | `false`   |\n| `--global, -g`              | Convert for global (user scope) configuration files                                                                       | `false`   |\n| `--dry-run`                 | Show changes without writing files                                                                                        | `false`   |\n\n### Examples\n\n```bash\n# Convert Cursor rules to Copilot and Claude Code\nrulesync convert --from cursor --to copilot,claudecode --features rules\n\n# Convert all features Cursor and Copilot both support\nrulesync convert --from cursor --to copilot\n\n# Convert MCP configuration from Claude Code to Cursor\nrulesync convert --from claudecode --to cursor --features mcp\n\n# Dry run to preview the conversion\nrulesync convert --from cursor --to copilot,claudecode --dry-run\n```\n\n### Behavior\n\n- The intermediate rulesync files produced during conversion are **never** written to disk. Only destination tool files are written.\n- Features that exist for the source tool but are not supported by a given destination tool are skipped with a warning.\n- When `--features` is omitted, the command attempts every feature the source tool supports.\n- Passing the source tool inside `--to` is rejected, because converting a tool onto itself is lossy.\n- With `--dry-run`, no destination files are written; the command prints a summary prefixed with `[DRY RUN]` listing what would have been converted.\n\n## Doctor Command\n\nThe `doctor` command runs read-only diagnostics against the configuration files (`rulesync.jsonc` and `rulesync.local.jsonc`) and reports problems grouped by severity (`error` / `warning` / `info`). It never writes files, which makes it a safe first step when generation does not behave as expected, and a cheap CI guard.\n\nIt is especially useful for catching **silently ignored configuration**: the config schema is non-strict, so a misspelled key such as `\"target\"` instead of `\"targets\"` is normally swallowed without any error. `doctor` reports every unknown key with a \"did you mean\" suggestion.\n\n### Checks\n\n- JSONC parse errors, reported with line and column.\n- Unknown or misspelled top-level keys, with a \"did you mean\" suggestion.\n- Unknown tool targets and features (array and object forms), with the nearest valid name suggested.\n- Deprecated features (`ignore`, superseded by `permissions`).\n- Object-form `targets` combined with `features` — including the case where the conflict only appears after merging `rulesync.jsonc` with `rulesync.local.jsonc`.\n- Conflicting target pairs (e.g. `claudecode` + `claudecode-legacy`).\n- `$schema` presence and whether it points at the current config schema URL.\n- Structural schema violations on any other key (wrong types, malformed `sources` entries).\n- `sources[].tokenEnv` naming an environment variable that is not set.\n- `inputRoot` or the first `inputRoots` entry pointing at a directory that does not exist. Later `inputRoots` entries are optional overlays and may be absent.\n- `inputRoot` or an `inputRoots` entry set to an empty string, which makes `generate` fail with `outputRoot cannot be an empty string` before it resolves any source tree.\n- Duplicate entries in `inputRoots` (warning; duplicates are ignored at generate time).\n\n### Options\n\n| Option                | Description                       | Default          |\n| --------------------- | --------------------------------- | ---------------- |\n| `--config, -c <path>` | Path to configuration file        | `rulesync.jsonc` |\n| `--strict`            | Treat warnings as errors (exit 1) | `false`          |\n| `--verbose, -V`       | Verbose output                    | `false`          |\n| `--silent, -s`        | Suppress all output               | `false`          |\n\n### Examples\n\n```bash\n# Diagnose the project configuration\nrulesync doctor\n\n# Fail CI on warnings too\nrulesync doctor --strict\n\n# Machine-readable output for editors and CI\nrulesync --json doctor\n\n# Diagnose a configuration file at a custom location\nrulesync doctor --config ./configs/rulesync.jsonc\n```\n\n### Behavior\n\n- Exits with code `1` when any `error`-severity diagnostic is present (or any `warning` with `--strict`), and `0` otherwise.\n- With the global `--json` flag, diagnostics and a severity summary are emitted as structured JSON: in `data` on success (exit 0), and in `error.details` of the standard error document (code `DOCTOR_FAILED`) on failure.\n- A missing configuration file is reported as `info` only — rulesync runs fine with built-in defaults.\n\n## Docs Command\n\nThe `docs` command prints the bundled Rulesync documentation to standard output, so both humans and coding agents can retrieve it directly in the terminal without browsing the repository or website. The documentation is embedded in the CLI at build time, so it works in installed npm distributions and compiled binaries alike.\n\nDocument identifiers follow the `docs/` hierarchy without the `docs/` prefix or the `.md` extension (both are accepted and stripped when supplied). Identifiers that try to escape the bundled tree — absolute paths, drive letters, `..` segments — are rejected.\n\n### Usage\n\n```bash\n# List every available document identifier\nrulesync docs\n\n# Print a document (top-level or nested)\nrulesync docs faq\nrulesync docs guide/configuration\n\n# Ranked full-text search across the bundled documentation\nrulesync docs --search \"global mode\"\n```\n\n### Search\n\n`--search <text>` builds an in-memory BM25+ index (via MiniSearch) over document paths, titles, headings, and body content, with stronger boosts for titles and headings. Up to 10 results are printed, one per line, as `<document> — <matching context>`. Matching is exact-term; no prefix or fuzzy expansion is applied.\n\n### Behavior\n\n- `rulesync docs` with no argument lists all document identifiers, one per line, sorted.\n- A missing document, an invalid identifier, an empty search text, a search with no matches, or combining a document argument with `--search` each exit with code 1 and an explanatory error.\n- Document output is printed verbatim, so it can be piped to other tools.\n- The global `--json` flag is not supported (the command's output is raw Markdown, not a JSON document) and exits with code 1.\n\n## Release Notes Command\n\nThe `release-notes` command prints GitHub release notes for any repository, so you can review what changed in an upstream AI coding tool — or in Rulesync itself — without leaving the terminal. Releases are fetched through the GitHub Releases API and rendered as Markdown on standard output, newest first.\n\nThe repository is given as `owner/repo` or a full `https://github.com/owner/repo` URL. Unlike `fetch`, ref (`@`) and path (`:`) suffixes are rejected — use `--tag` to select a single release. Only GitHub is supported; other Git providers have no equivalent Releases API.\n\n### Usage\n\n```bash\n# Latest 10 releases (default)\nrulesync release-notes dyoshikawa/rulesync\n\n# Most recent N releases\nrulesync release-notes dyoshikawa/rulesync --latest 5\n\n# Releases published within a date range (either end may be omitted)\nrulesync release-notes dyoshikawa/rulesync --since 2026-01-01 --until 2026-06-30\n\n# A single release by tag name\nrulesync release-notes dyoshikawa/rulesync --tag v16.11.0\n\n# Every release between two tags, inclusive\nrulesync release-notes dyoshikawa/rulesync --from v16.0.0 --to v16.11.0\n\n# Include prereleases\nrulesync release-notes dyoshikawa/rulesync --include-prereleases\n\n# Machine-readable output\nrulesync --json release-notes dyoshikawa/rulesync --latest 3\n```\n\n### Filtering\n\nThe four filtering modes — `--latest`, `--since`/`--until`, `--tag`, and `--from`/`--to` — are mutually exclusive; combining them exits with code 1. With no filter, the latest 10 releases are printed.\n\n| Option                              | Description                                                                                                                                                                                                                      |\n| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--latest <count>`                  | Print the most recent `<count>` releases. Must be a positive integer.                                                                                                                                                            |\n| `--since <date>` / `--until <date>` | Print releases published within the range, both ends inclusive. Either end may be omitted for an open-ended range. Dates are parsed as ISO 8601, e.g. `2026-01-31`; a bare date given to `--until` covers that whole day in UTC. |\n| `--tag <tag>`                       | Print a single release by tag name. Named `--tag` rather than `--version` because `--version` is the global flag that prints the Rulesync version.                                                                               |\n| `--from <tag>` / `--to <tag>`       | Print every release between two tags, inclusive. Both are required.                                                                                                                                                              |\n| `--include-prereleases`             | Include prereleases in the output.                                                                                                                                                                                               |\n| `--token <token>`                   | GitHub token for private repositories or higher rate limits.                                                                                                                                                                     |\n\nTag ranges are resolved by position in the repository's release history, not by parsing semver, so non-semver tag names work and the order of `--from` and `--to` does not matter. A tag that does not appear in the history exits with code 1.\n\n### Authentication\n\nRequests are unauthenticated by default, which is enough for public repositories but subject to GitHub's stricter anonymous rate limit. Set `GITHUB_TOKEN` or `GH_TOKEN` (or pass `--token`) for private repositories and higher limits:\n\n```bash\nGITHUB_TOKEN=$(gh auth token) rulesync release-notes owner/private-repo\n```\n\n### Behavior\n\n- Draft releases are never printed: they are unpublished and only visible to accounts with write access.\n- Prereleases are excluded unless `--include-prereleases` is given, matching how GitHub itself resolves the \"latest\" release. `--tag` is the exception — an explicitly named tag is printed regardless of its prerelease status.\n- A repository with no matching releases prints a warning and exits with code `0`.\n- Range queries walk at most 10 API pages (1,000 releases); tags older than that are reported as not found.\n- Date ranges scan the whole walked history rather than stopping at the first out-of-range release, because the API orders releases by creation date and a release published from a long-lived branch can appear out of publication order.\n- Default output is Markdown on standard output, so it can be piped to other tools. With the global `--json` flag, the releases are emitted as structured `data` instead and no Markdown is printed; failures use the standard error document with code `RELEASE_NOTES_FAILED`.\n",
+	"reference/cli-commands": "# CLI Commands\n\n## Quick Commands\n\n```bash\n# Initialize new project (recommended: organized rules structure)\nrulesync init\n\n# Import existing configurations (to .rulesync/rules/ by default)\nrulesync import --targets claudecode --features rules,mcp,commands,subagents,skills,permissions\n\n# Import components from an existing plugin directory\nrulesync import --targets claudecode-plugin --features skills,hooks --output-root ./plugins/review-tools\n\n# Convert configurations from one tool to other tools (skips .rulesync/)\nrulesync convert --from cursor --to copilot,claudecode\nrulesync convert --from cursor --to copilot,claudecode --features rules,mcp\n\n# Fetch configurations from a Git repository\nrulesync fetch owner/repo\nrulesync fetch owner/repo@v1.0.0 --features rules,commands\nrulesync fetch https://github.com/owner/repo --conflict skip\n\n# Generate all features for all tools (new preferred syntax)\nrulesync generate --targets \"*\" --features \"*\"\n\n# Generate specific features for specific tools\nrulesync generate --targets copilot,cursor,cline --features rules,mcp\nrulesync generate --targets claudecode --features rules,subagents\n\n# Generate components inside an existing plugin directory\nrulesync generate --targets antigravity-plugin --features rules,mcp,subagents,skills,hooks --output-roots ./plugins/review-tools\n\n# Generate only rules (no MCP, permissions, commands, or subagents)\nrulesync generate --targets \"*\" --features rules\n\n# Generate simulated commands and subagents\nrulesync generate --targets copilot,cursor,codexcli --features commands,subagents --simulate-commands --simulate-subagents\n\n# Dry run: show changes without writing files\nrulesync generate --dry-run --targets claudecode --features rules\n\n# Check if files are up to date (for CI/CD pipelines)\nrulesync generate --check --targets \"*\" --features \"*\"\n\n# Generate from a shared source tree (without cd-ing into it)\nrulesync generate --input-roots ~/.aiglobal/.rulesync --targets \"*\" --features rules\n\n# Install rules and skills from declarative sources in rulesync.jsonc\nrulesync install\n\n# Add a source to rulesync.jsonc, update the lockfile, and install it\nrulesync add anthropics/skills --skills skill-creator\n\n# Add a rule source without selecting skills\nrulesync add acme/ai-standards --rules testing-guidelines\n\n# Force re-resolve all source refs (ignore lockfile)\nrulesync install --update\n\n# Fail if lockfile is missing or out of sync (for CI); fetch missing artifacts using locked refs\nrulesync install --frozen\n\n# Install then generate (typical workflow)\nrulesync install && rulesync generate\n\n# Add generated files to .gitignore\nrulesync gitignore\n\n# Add only specific tool entries to .gitignore\nrulesync gitignore --targets claudecode,copilot\n\n# Add only specific feature entries to .gitignore\nrulesync gitignore --targets copilot --features rules,commands\n\n# Diagnose the configuration files for common problems (read-only)\nrulesync doctor\n\n# Diagnose and fail CI on warnings too\nrulesync doctor --strict\n\n# Print GitHub release notes for a repository (latest 10 by default)\nrulesync release-notes dyoshikawa/rulesync\n\n# Print the most recent 5 releases\nrulesync release-notes dyoshikawa/rulesync --latest 5\n\n# Update rulesync to the latest version (single-binary installs)\nrulesync update\n\n# Check for updates without installing\nrulesync update --check\n\n# Force update even if already at latest version\nrulesync update --force\n```\n\n> **Deprecated feature:** `ignore` remains available to existing projects throughout Rulesync 14.x, but new projects should use `permissions`. Any removal will be decided separately and will not occur before a future major release.\n\n## JSON Output\n\nThe global `--json` flag makes a command print a single result document and nothing else. Because that document is the whole of the output, warnings that would otherwise go to standard error are carried inside it, as a top-level `warnings` array of strings:\n\n```json\n{\n  \"success\": true,\n  \"timestamp\": \"2025-01-01T00:00:00.000Z\",\n  \"command\": \"import\",\n  \"version\": \"x.y.z\",\n  \"warnings\": [\".factory/settings.local.json is a machine-local overrides file …\"],\n  \"data\": { \"…\": \"…\" }\n}\n```\n\nThe key is omitted when nothing warned, and `--silent` suppresses warnings there as it does on the console. `warnings` sits beside `data` rather than inside it so a command's own captured keys can never collide with it, and it is reported on the failure document too, where a diagnostic about the input is often what explains the failure.\n\nAt most 100 warnings are reported, each truncated to 1,000 characters and 8,000 characters in total; a run that exceeds any of those limits says so in a final entry rather than growing the document without bound.\n\nBecause that budget is finite, the array carries the diagnostics a run has no other way to report — not a restatement of what `data` already holds. A command that lists something under a captured key writes the list there and warns only about what the list does not say.\n\n## Generate Command\n\nThe `generate` command reads source files from one or more rulesync source trees (default: `<cwd>/.rulesync`; configurable via `--input-roots`) and writes AI tool configuration files to the output directories.\n\n### Options\n\n| Option                      | Description                                                                                                                                                                                                                                                                                                                                                                               | Default               |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |\n| `--targets, -t <tools>`     | Comma-separated list of tools (e.g. `claudecode,copilot` or `*`)                                                                                                                                                                                                                                                                                                                          | From `rulesync.jsonc` |\n| `--features, -f <features>` | Comma-separated list of features (rules, commands, subagents, skills, mcp, hooks, permissions, checks; deprecated: ignore)                                                                                                                                                                                                                                                                | From `rulesync.jsonc` |\n| `--input-roots <paths...>`  | Ordered list of rulesync source-tree directories (e.g. `.rulesync`, `.rulesync.local`). Each entry is a source tree itself — no `.rulesync/` join is applied. The first root is required; later roots are optional overlays and may be absent. Later entries override earlier ones for the same relative source path (currently `generate` only). Cannot be combined with `--input-root`. | `<cwd>/.rulesync`     |\n| `--input-root <path>`       | **Deprecated.** Path to the PARENT directory of a `.rulesync/` source tree; kept for backward compatibility and expands internally to `--input-roots <path>/.rulesync`. Prefer `--input-roots`. Cannot be combined with it.                                                                                                                                                               | CWD                   |\n| `--dry-run`                 | Show what would change without writing files                                                                                                                                                                                                                                                                                                                                              | `false`               |\n| `--check`                   | Like `--dry-run` but exits with code 1 if files are not up to date                                                                                                                                                                                                                                                                                                                        | `false`               |\n| `--global`                  | Generate for global (user-scope) configuration files                                                                                                                                                                                                                                                                                                                                      | `false`               |\n| `--simulate-commands`       | Generate simulated commands for tools that do not support them natively                                                                                                                                                                                                                                                                                                                   | `false`               |\n| `--simulate-subagents`      | Generate simulated subagents for tools that do not support them natively                                                                                                                                                                                                                                                                                                                  | `false`               |\n| `--simulate-skills`         | Generate simulated skills for tools that do not support them natively                                                                                                                                                                                                                                                                                                                     | `false`               |\n| `--delete`                  | Delete existing generated files before writing                                                                                                                                                                                                                                                                                                                                            | From `rulesync.jsonc` |\n| `--watch, -w`               | Keep running and regenerate whenever rulesync source files change                                                                                                                                                                                                                                                                                                                         | `false`               |\n\n> **Note on `--delete` and shared output directories:** Several targets write\n> into one directory on purpose — `.agents/agents/`, `.agents/skills/`, and the\n> rest of the cross-vendor roots. The orphan sweep runs only after every target\n> and every feature in the run has written, and it skips any path the run itself\n> produced, so one target never deletes a sibling's freshly written file and an\n> already-synchronized tree stays a no-op under `--check`. What is swept is\n> unchanged: a file in a generated directory that no `.rulesync/` source\n> produces.\n>\n> Takt's skills are the one target swept by file name rather than by directory\n> (its rules, commands, and subagents are swept normally). They are flat files\n> sharing a single `.takt/facets/knowledge/` root rather than each getting a\n> directory of its own, so what the sweep removes there is a `.md` file directly\n> under that root which no `.rulesync/skills/` source produces. The root itself\n> and anything nested inside it are left alone. See [Takt](../tools/takt.md).\n\n> **Note on unreadable sources:** This applies to the single-file features —\n> `mcp`, `hooks`, `permissions`, and `ignore` — each of which is generated from\n> one `.rulesync/` file. When that file exists but cannot be read — malformed\n> JSON/JSONC, or content the schema rejects — the problem is reported as an\n> error, the feature produces no output, and `generate` exits non-zero, naming\n> the affected features. Every other feature in the run still executes first, so\n> one bad file does not hide the rest of the errors. Because that feature's\n> output could not be regenerated, `--delete` also skips its orphan sweep,\n> leaving the previously generated files in place rather than deleting\n> configuration the run was unable to rewrite. Under `--watch` the failure is\n> reported and the watcher keeps running, so saving a corrected source\n> regenerates as usual.\n>\n> A source file that is simply absent is not an error: that feature just has\n> nothing to generate, and the run succeeds — it is still logged, but it does\n> not fail the run. Only genuine absence counts; a path that cannot even be\n> checked (a permission error, a symlink loop, a symlink whose target is gone)\n> is treated as unreadable, not as missing.\n>\n> The directory-based features handle an unparseable source file differently,\n> and not uniformly. `subagents` and `checks` report it as a warning and skip\n> that file, because their directories hold free-form Markdown that users also\n> keep notes and READMEs in; the rest of the directory still generates and the\n> run succeeds. `rules`, `commands`, and `skills` do not: an invalid frontmatter\n> there aborts `generate` with that error and a non-zero exit, without the\n> per-feature isolation described above.\n>\n> A source entry that exists but cannot be _read_ is never treated as deleted\n> for any of them, warn-and-skip features included: a `.rulesync/` file or\n> directory whose symbolic link no longer resolves, or an input root that\n> cannot be resolved, stops the run rather than letting `--delete` sweep away\n> what it was supposed to generate.\n\n### Examples\n\n```bash\n# Generate all features for all configured tools\nrulesync generate\n\n# Generate rules for all tools\nrulesync generate --targets \"*\" --features rules\n\n# Generate from a shared source tree without cd-ing into it\nrulesync generate --input-roots ~/.aiglobal/.rulesync --targets \"*\" --features rules\n\n# Dry run: preview changes without writing\nrulesync generate --dry-run --targets claudecode --features rules\n\n# CI check: fail if generated files are not up to date\nrulesync generate --check --targets \"*\" --features \"*\"\n\n# Watch mode: regenerate on every change to the sources\nrulesync generate --watch\n```\n\n### Watch mode\n\n`generate --watch` runs one generation immediately and then keeps running, regenerating whenever the rulesync sources change. It is meant for iterating on rules, commands, subagents or skills without re-running the command by hand.\n\n- **What is watched**: the `.rulesync/` source tree (recursively) plus the configuration files next to it (`rulesync.jsonc` and `rulesync.local.jsonc`, or the file passed to `--config`). Generated output is never watched, so a regeneration cannot re-trigger the watcher.\n- **Debouncing**: bursts of file-system events (editor save storms, `git checkout` switching many files) are coalesced into a single regeneration after a short quiet period. Changes that arrive while a generation is running trigger exactly one follow-up run.\n- **Errors keep the watcher alive**: a failing generation (e.g. invalid frontmatter saved mid-edit) is reported and watching continues; the process does not exit.\n- **Configuration changes**: editing the configuration file triggers a regeneration, and the new values apply to it because the configuration is re-resolved on every run. The **set of watched paths is fixed at startup**, so changing `inputRoot`/`inputRoots` (or the location of the configuration file itself) requires restarting the command. A warning is printed whenever the configuration file changes as a reminder.\n- **Incompatible flags**: `--watch` cannot be combined with `--check`, `--dry-run` or `--json`. The first two are one-shot verification modes and `--json` emits a single result document when the command exits, which never happens while watching.\n- **Stopping**: `Ctrl+C` (`SIGINT`) or `SIGTERM` closes the watchers and exits normally.\n\n### Tool home overrides win over the output root in global scope\n\nTwo tools read their profile location from an environment variable: Hermes Agent (`HERMES_HOME`) and Kimi Code (`KIMI_CODE_HOME`). When one of them is set, `generate --global` and `convert --global` write that tool's output under it, **overriding both `outputRoots` and an explicit `--output-roots`** for that target. See [Supported Tools](./supported-tools.md) for what each profile root contains. This is deliberate — the variable names where the tool itself looks, so honoring the flag instead would produce files the tool never reads. Every other target still uses the configured output root.\n\nThe override must be a usable directory: an empty value is ignored (the default profile location applies), and a value that is the filesystem root or an unnormalized path is rejected with an error naming the variable.\n\n### Shared config files are never created empty\n\nSome outputs are files Rulesync merges into rather than owns, because the tool (or you) keeps unrelated settings there: `.amp/settings.json(c)`, `.antigravity/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, `.codex/config.toml`, `.copilot/settings.json`, `.devin/config.json`, `.factory/settings.json`, `.github/copilot/settings.json`, `.grok/config.toml`, `.vibe/config.toml`, `.vscode/settings.json`, `.zcode/config.json`, `.zcode/cli/config.json`, `.zed/settings.json`, `kilo.json(c)`, `opencode.json(c)`, and `reasonix.toml`. These are deliberately **not** added to `.gitignore` by `rulesync gitignore`, so that settings you hand-author in them stay version-controlled.\n\nBecause they stay committable, `generate` will not **create** one of them just to hold an empty payload: if Rulesync has nothing to contribute (e.g. no permissions map to that tool), the file is left absent instead of being written as `{}`. A file that already exists is always rewritten as usual, so nothing you authored is dropped. Every other generated file is written even when empty, since for a file Rulesync owns its existence is part of the output.\n\n### Comments in shared JSONC files are preserved\n\nSeveral of those shared files are JSONC rather than JSON, because the tools themselves put comments in them — VS Code's own \"MCP: Add Server\" scaffold opens `.vscode/mcp.json` with a comment line. `.vscode/settings.json`, `.vscode/mcp.json`, `.amp/settings.json`, `opencode.json(c)` and `kilo.json(c)` (with their global counterparts) are therefore written back as **edits to the existing text**: only the spans whose values actually changed are rewritten, so the comments, blank lines, and key order everywhere else in the file survive a regenerate, and a `generate` that computes the same content it wrote last time leaves the file byte-identical. A key that Rulesync drops takes its own line with it, but a comment on the line above it stays, because Rulesync cannot tell whether that note described the key or the file around it. A note written after a key on the same line belongs to that key: it is removed with the key, and it stays put when Rulesync adds a new key after it. New keys are appended at the end of the object that holds them, and the region the insert touches is re-indented to the file's own indentation — so an object written on a single line is expanded to one key per line when Rulesync adds to it.\n\nRulesync falls back to rewriting the whole document when there is nothing to preserve, nothing to edit against, or no way to edit safely: an empty file; a file that does not parse, a byte-order mark included (for `.vscode/settings.json`, `.vscode/mcp.json` and `.amp/settings.json` an unparsable file stops the command instead, rather than have Rulesync overwrite settings it could not read); a file whose root is not an object; a file using `__proto__`, `constructor` or `prototype` as a key (those keys are dropped from every document Rulesync parses, so they are removed rather than left behind); a file that states the same key twice, where an edit would land on the copy the tool itself ignores; a file so large, with so much of it changing, that editing it key by key would take longer than a rewrite is worth, whether the size is the file Rulesync starts from or the document it is taking (a machine-generated file with thousands of entries, all of them replaced, or a small file handed thousands of new ones); a file whose changed keys write more than about 200 KB of new text between them, indentation included, which costs more to re-indent than to write out; and a file the editor itself refuses, which it reports as an error rather than a result. Files in the other formats — JSON, YAML, TOML — are re-serialized as before, so comments in `.codex/config.toml` or `reasonix.toml` are still not retained.\n\n## Gitignore Command\n\nThe `gitignore` command adds generated AI tool configuration files to `.gitignore`. By default, it emits entries only for the tools listed in the `targets` of your `rulesync.jsonc` (controlled by the `gitignoreTargetsOnly` option, which defaults to `true`). Set `gitignoreTargetsOnly` to `false` to emit entries for all supported tools instead. You can also filter the output per-invocation with `--targets` / `--features`, which take precedence over the config.\n\nYou can route entries to `.gitattributes` instead by setting `gitignoreDestination` to `\"gitattributes\"` at root, tool, or tool × feature level. More specific settings take precedence.\n\n> **No `rulesync.jsonc` in the project?** Entries for all supported tools are emitted. `gitignoreTargetsOnly` is only applied when a config file exists, so users without a config still get useful `.gitignore` coverage.\n\n> **`agentsmd` entries are always included.** Even when `gitignoreTargetsOnly` is `true` and `agentsmd` is not listed in `targets`, entries for `AGENTS.md` (and related paths) are appended automatically. Because `AGENTS.md` is a de facto standard file read by many AI tools regardless of the target set, its gitignore entries are emitted unconditionally to prevent accidental commits of generated rule files. To opt out of this behavior, pass an explicit `--targets` option that omits `agentsmd`.\n\n### Options\n\n| Option                      | Description                                                                                                  | Default                                         |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |\n| `--targets, -t <tools>`     | Comma-separated list of tools to include (e.g., `claudecode,copilot` or `*` for all)                         | Derived from `targets` / `gitignoreTargetsOnly` |\n| `--features, -f <features>` | Comma-separated list of features to include (rules, commands, subagents, skills, ignore, mcp, hooks, checks) | `*` (all)                                       |\n\n### Examples\n\n```bash\n# Add all entries (default)\nrulesync gitignore\n\n# Add entries for Claude Code only\nrulesync gitignore --targets claudecode\n\n# Add entries for multiple tools\nrulesync gitignore --targets claudecode,copilot,cursor\n\n# Add only rules and commands entries for Copilot\nrulesync gitignore --targets copilot --features rules,commands\n```\n\n### Behavior\n\n- **Common entries** (e.g., `.rulesync/rules/.curated/`, `.rulesync/skills/.curated/`, `rulesync.local.jsonc`) are always included regardless of filters.\n- **General entries** (e.g., memories, settings) are always included when their target is selected.\n- When re-running, all previously generated rulesync entries are removed before writing the new filtered set.\n\n## Add Command\n\nThe `add` command can scaffold one Rulesync feature file or append one declarative source to `rulesync.jsonc`.\n\n### Feature scaffolding\n\nUse a feature keyword to create a valid, editable starter file:\n\n```bash\n# Named Markdown features\nrulesync add rule --name overview\nrulesync add command --name review-pr.md\nrulesync add subagent --name planner\nrulesync add skill --name project-context\nrulesync add check --name security\n\n# Singleton features\nrulesync add mcp\nrulesync add hooks\nrulesync add permissions\n\n# Deprecated compatibility scaffold; prefer permissions\nrulesync add ignore\n```\n\nNamed features accept a name with or without the `.md` suffix. Skills use the directory layout `.rulesync/skills/<name>/SKILL.md`; the other named features create `<name>.md` in their canonical Rulesync directory. Names cannot contain path separators.\n\nWhen the target file exists, interactive execution asks before replacing it. Declining leaves the file unchanged. JSON, silent, and non-interactive execution fail safely; pass `--force` to overwrite explicitly. Singleton scaffolds recognize supported JSONC and legacy variants and replace the effective existing file instead of creating a shadowed canonical file.\n\nFeature keywords are reserved when no source-specific option is present. To add a source whose identifier is also a feature keyword, provide a source option that makes the intent explicit, such as `rulesync add skill --transport npm`.\n\n### Declarative sources\n\nFor any other source identifier, `add` appends one source to `rulesync.jsonc` and immediately runs the declarative source resolver. It preserves JSONC comments, installs selected rules into `.rulesync/rules/.curated/`, installs selected skills into `.rulesync/skills/.curated/`, and updates `rulesync.lock` or `rulesync-npm.lock.json`.\n\n```bash\n# GitHub source (default transport)\nrulesync add anthropics/skills --skills skill-creator\n\n# Rules only; direct .md files are selected from rules/\nrulesync add acme/ai-standards --rules testing-guidelines,typescript-conventions\n\n# Rules and skills from separate paths in one source\nrulesync add acme/ai-assets --rules \"*\" --rules-path exports/rules --skills review-pr --path exports/skills\n\n# Any Git remote through the git CLI\nrulesync add https://example.com/team/skills.git --transport git --ref main --path skills\n\n# npm-compatible registry\nrulesync add @acme/skill-package --transport npm --registry https://registry.npmjs.org\n```\n\nThe selected configuration file must already exist. Run `rulesync init` first, or pass `--config <path>`. Adding a source whose normalized source identity is already present fails instead of silently creating duplicate lockfile entries; edit the existing entry when changing its options.\n\nThe operation fetches only the source being added; existing declarations are not re-fetched. Existing sources must already be locked and installed, otherwise run `rulesync install` first. The operation is transactional: if the new source fails to install, Rulesync restores the manifest, source lockfiles, curated rules, and curated skills to their pre-command state.\n\n| Option                | Description                                                                                       |\n| --------------------- | ------------------------------------------------------------------------------------------------- |\n| `--name <name>`       | Name for a rule, command, subagent, skill, or check scaffold                                      |\n| `--force`             | Replace an existing scaffold file without prompting                                               |\n| `--skills <skills>`   | Comma-separated skill names. `*` selects all skills.                                              |\n| `--rules <rules>`     | Comma-separated rule names. Names may omit `.md`; `*` selects direct `.md` files under rulesPath. |\n| `--transport <type>`  | `github` (default), `git`, or experimental `npm`                                                  |\n| `--ref <ref>`         | Git ref, npm version, or npm dist-tag                                                             |\n| `--path <path>`       | Skills path within the source; defaults to `skills`                                               |\n| `--rules-path <path>` | Rules path within the source; defaults to `rules`                                                 |\n| `--registry <url>`    | npm-compatible registry URL                                                                       |\n| `--token-env <name>`  | Environment variable containing the npm registry token                                            |\n| `--token <token>`     | GitHub token for private repositories                                                             |\n| `--config <path>`     | Configuration file to edit (default: `rulesync.jsonc`)                                            |\n\nWhen neither `--skills` nor `--rules` is provided, all skills are installed for backward compatibility. Providing only `--rules` installs no skills.\n\n## Fetch Command\n\nThe `fetch` command allows you to fetch configuration files directly from a Git repository (GitHub/GitLab).\n\n> [!NOTE]\n> This feature is in development and may change in future releases.\n\n**Note:** The fetch command searches for feature directories (`rules/`, `commands/`, `skills/`, `subagents/`, etc.) directly at the specified path, without requiring a `.rulesync/` directory structure. This allows fetching from external repositories like `vercel-labs/agent-skills` or `anthropics/skills`.\n\n### Source Formats\n\n```bash\n# Full URL format\nrulesync fetch https://github.com/owner/repo\nrulesync fetch https://github.com/owner/repo/tree/branch\nrulesync fetch https://github.com/owner/repo/tree/branch/path/to/subdir\nrulesync fetch https://gitlab.com/owner/repo  # GitLab (planned)\n\n# Prefix format\nrulesync fetch github:owner/repo\nrulesync fetch gitlab:owner/repo              # GitLab (planned)\n\n# Shorthand format (defaults to GitHub)\nrulesync fetch owner/repo\nrulesync fetch owner/repo@ref        # Specify branch/tag/commit\nrulesync fetch owner/repo:path       # Specify subdirectory\nrulesync fetch owner/repo@ref:path   # Both ref and path\n```\n\n### Options\n\n| Option                  | Description                                                                                                                                                           | Default                          |\n| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |\n| `--target, -t <target>` | Target format to interpret files as (e.g., 'rulesync', 'claudecode')                                                                                                  | `rulesync`                       |\n| `--features <features>` | Comma-separated features to fetch (rules, commands, subagents, skills, ignore, mcp, hooks, permissions, checks)                                                       | `skills`                         |\n| `--output <dir>`        | Output directory relative to project root                                                                                                                             | `.rulesync`                      |\n| `--conflict <strategy>` | Conflict resolution: `overwrite` or `skip`                                                                                                                            | `overwrite`                      |\n| `--no-prune`            | Keep local files inside a fetched skill directory that the remote skill no longer has                                                                                 | Pruning is on                    |\n| `--ref <ref>`           | Git ref (branch/tag/commit) to fetch from                                                                                                                             | Default branch                   |\n| `--path <path>`         | Subdirectory in the repository                                                                                                                                        | `.` (root)                       |\n| `--skills <skills>`     | Comma-separated skill names to fetch (requires the skills feature)                                                                                                    | All skills                       |\n| `--interactive, -i`     | Interactively select skills to fetch via a checkbox prompt; nothing is selected initially, press `<a>` to select/deselect all (requires the skills feature and a TTY) | Disabled                         |\n| `--token <token>`       | Git provider token for private repositories                                                                                                                           | `GITHUB_TOKEN` or `GH_TOKEN` env |\n\n### Pruning Fetched Skill Directories\n\nA skill is a directory (`skills/<name>/SKILL.md` plus its supporting files), not a single file. When the upstream skill drops or renames a file, an additive fetch would leave the old local copy in place, and the directory would become a mixture of the current upstream files and orphaned leftovers. Agents read whatever is in the directory, so a stale reference or an outdated script keeps steering them long after upstream removed it.\n\n**The remote skill is therefore the source of truth: by default, `fetch` deletes files inside the skill directories it fetched that the remote does not have.** Every deletion is listed in the summary, so the destructive part of the command is never silent:\n\n```text\nFetched from anthropics/skills@main:\n  ✓ skills/pdf/SKILL.md (overwritten)\n  ✗ skills/pdf/reference.md (deleted - no longer in the remote skill)\n\nSummary: 1 overwritten, 1 deleted\n```\n\nRulesync also warns separately whenever a run deleted anything, so the one part of the command that cannot be undone is not left to be spotted among the rest of the summary.\n\n> [!WARNING]\n> Pruning removes **any** file in a fetched skill directory that the remote does not have — including one you added yourself. That is what \"mirror the remote\" means. Keep your own material outside the skill directories you fetch, or pass `--no-prune`.\n>\n> This applies to whatever `--output` points at. `--output .` makes the fetched skill directories your project's own `skills/`, so a fetch there prunes the skills you maintain by hand. Fetch into the default `.rulesync/` unless you really mean to mirror a remote repository into your project root.\n\nThe scope is deliberately narrow:\n\n- Only the `skills/<name>/` directories fetched in **this** run are pruned. A skill left out by `--skills` or `--interactive` is untouched.\n- Other features (`rules/`, `commands/`, `subagents/`, …) are never pruned — the issue only exists for directory-based skills.\n- Directories the remote skill no longer has are removed as well, and are listed in the summary under their own name with a trailing slash.\n- Symbolic links are unlinked, never followed: a link inside a skill directory can only ever lose the link itself, never whatever it points at. A skill directory that is **itself** a symbolic link is not pruned at all, since deleting through it would reach outside the output directory; Rulesync warns and leaves it alone.\n- A local file that the filesystem holds as the same file as one just fetched — a second name for it on a case-insensitive or Unicode-normalizing filesystem, or a hard link — is kept, even though the remote list does not carry that name. The same applies to a symbolic link that resolves to a file or directory this run wrote: it is kept rather than unlinked, since the fetch may have written through it.\n- A skill directory Rulesync cannot read or delete from — a permission it does not hold, a disk that gave out — stops that skill's prune where it failed rather than the whole fetch. Rulesync warns, still lists whatever it had already deleted, and moves on to the next skill.\n- Nothing more than 15 directories below the skill directory is pruned. That is a limit on the local walk, deep enough that a fetched tree stays well inside it; Rulesync warns and leaves anything deeper alone.\n- A skill directory whose name ends in a dot or a space, or whose name has the `NAME~1` shape of a Windows short name, is not pruned. Some systems resolve such a name to a different directory, so the directory that name reads as may not be the directory it opens.\n- A skill directory whose name differs from another in `skills/` — one that was already there, or one this same fetch just wrote — only in ways some filesystems ignore — its case, or whether an accented letter is written composed or decomposed — is not pruned either, for the same reason: macOS and Windows resolve `skills/PDF` to an existing `skills/pdf`, and macOS resolves a decomposed name to the composed directory of the same name, so pruning it would judge the local skill's own files stale.\n- A skill whose remote listing came back incomplete — GitHub caps a directory listing at 1,000 entries, and entries such as symlinks and submodules cannot be fetched — is not pruned either. Rulesync warns instead, because a local file that upstream still ships cannot be told apart from one it dropped.\n- `--conflict skip` disables pruning. That flag says to leave existing local files alone, and it also means the local copies are not this run's output, so they cannot be judged against the remote list.\n- `--target <tool>` never prunes, because that conversion path does not fetch skills at all.\n\nPass `--no-prune` to get the old purely additive behavior.\n\n#### Remote Paths Containing a Backslash or a Colon\n\nA backslash is an ordinary character in a filename on Linux and macOS, and a directory separator on Windows. A colon is ordinary too here, and on Windows it separates a file from one of its alternate data streams, so `skills/pdf::$INDEX_ALLOCATION` is another way of writing `skills/pdf` rather than a directory of its own. A remote file whose path contains either character therefore names one file on some systems and something else on others, so `fetch` skips it and warns rather than picking an interpretation. The rest of the fetch continues normally.\n\nBecause the skipped file is still part of the remote skill, the skill directory it came from is not pruned in that run either — a local copy of a file the remote still ships would otherwise be indistinguishable from one it dropped.\n\n#### Skill Names That Look Alike\n\nA repository can publish two skill directories whose names a terminal draws the same way — `skill` spelled with a Cyrillic `ѕ`, or the fullwidth `ｓｋｉｌｌ` beside the plain one. Each is still a separate entry with its own name, so a selection writes exactly the directories that were checked; the risk is only that an entry cannot be told apart by sight from what it appears to be — another entry, a skill you already have, or the plainer, shorter name its own row reads as.\n\nThe interactive prompt therefore prefixes such an entry with `[!]` and the reason, ahead of the name itself:\n\n```text\n? Select skills to fetch (press <a> to select/deselect all)\n ◯ pdf\n ◯ [!] another entry differs from it only by lookalike letters — skill\n ◯ [!] another entry differs from it only by lookalike letters; mi… — ѕkill\n```\n\nThe mark comes first so that a name — which the remote repository chooses — cannot be spelled to look like a mark of its own, or reorder one away. A label wider than one line is shortened with an ellipsis for the same reason; the budget is measured in terminal columns, so a name of ideographic spaces cannot buy extra width by being few characters, and it is taken from the terminal the prompt is drawn in — the window's own width, less the five columns the pointer and the checkbox can take between them, and never more than 72 — so a pane split in half shortens the labels along with it. A terminal that does not say how wide it is counts as 80 columns, the width the prompt falls back to when it wraps the rows, and no terminal shortens a label below 16: past that a row would be an ellipsis and little else, and rows that cannot be told apart at all are worse than a row that wraps. The name is measured first and the reasons take the room that is left, which is why the second label above is cut: a cut takes the reasons from the tail, and the mark and the start of the first reason always survive. Two entries whose labels read alike are numbered — `(1) `, `(2) `, in front for the same reason the mark is — so they stay distinct. That covers labels shortened into the same text, and equally `git` beside `ɡit`, where both rows carry the same note and the names are one shape: the numbers do not say which row is which, but they do say there are two of them, and the value behind a label is untouched, so a shortened entry still selects the skill it names. A name that itself begins the way a marked row does is given a mark of its own saying so — judged by the shape it is drawn in rather than the characters it is spelled with, so `(l)` and a `[ǃ]` written with U+01C3 LATIN LETTER RETROFLEX CLICK are marked alongside the plain `(1)` and `[!]`.\n\nAn entry is marked for any of five reasons:\n\n- **Another entry has the same display form.** Names are compared with their hidden characters removed, normalized (NFKC), their whitespace collapsed, and lowercased, so `Skill`, `skill`, `skill ` and the fullwidth `ｓｋｉｌｌ` all collide.\n- **Another entry differs from it only by lookalike letters.** Two names that read the same once each character is replaced by the Latin letter it is drawn as — `copy` beside the same word spelled entirely in Cyrillic. A name does not have to leave the Latin alphabet to qualify: `c0py` with a zero, `ruIes` with a capital I for the l, `Ⅰist` with the Roman numeral one, and `git` with the script `ɡ` or the dotless `ı` are all marked against the plain spelling. Two letters drawn as one count as well — `forrnat` for `format`, `revievv` for `review` — which no table of single characters can see. `cl` for `d` is left out of that short list on purpose: it opens too many ordinary words, and folding it would report `clone` against a `done` you happen to have. The separator counts too, since nearly every skill name is kebab-case and a name that swaps only its hyphen for U+2010 HYPHEN — drawn identically, belonging to no script, and left alone by the compatibility normalization — would otherwise pass every check as plain ASCII. Neither name mixes scripts on its own, so this pair is visible only by comparing the two.\n- **The name carries more whitespace than the row shows.** A run of whitespace is drawn as one gap however long it is, and whitespace at either end of a name is drawn as nothing at all, so `pdf ` and `pdf  reader` reach past what can be seen of them. Both halves of a pair like `pdf` and `pdf ` are already marked as sharing a display form; this reason is what marks the padded name when it is alone on the list. A single blank inside a name that is merely not the plain space — a no-break space, an ideographic space — is not marked here: it is drawn, and the plain name it imitates is reported as the pair it makes under the first reason above, so an ordinary `設定 ガイド` written with the ideographic space is left alone. At either end it is marked like any other blank, since there the question is not which character was chosen but that the name reaches past where it appears to end.\n- **The name reads as Latin letters but is written in another script.** Every letter of it is drawn as a Latin one without being Latin, which is the whole-script confusable of UTS #39: `copy` spelled with four Cyrillic letters is marked even when no Latin `copy` is on the list. This check uses the narrower list of letters that are drawn as a _lowercase_ Latin letter while being lowercase themselves, so an ordinary Russian or Greek word — `текст`, `κατα` — is not marked: its letters are ones whose capitals resemble Latin capitals, which is not the same thing. Cherokee, Coptic, Lisu, Osage, Deseret and Tifinagh are taken whole instead of letter by letter — a name written in nothing but one of them is marked — since those alphabets are drawn in Latin letter shapes throughout. Canadian Aboriginal Syllabics and Vai are not: their letters are shapes of their own, so a name in either reads as nothing Latin, and only a mixture with Latin is marked.\n- **The name mixes scripts.** A single name built from scripts that share letter shapes, such as `good` with a Cyrillic `о`. The alphabets treated as lookalikes are Latin, Cyrillic, Greek, Armenian, Cherokee, Coptic, Lisu, Canadian Aboriginal Syllabics, Osage, Deseret, Vai and Tifinagh, which are among the ones UTS #39 records as confusable with each other. Japanese, Korean and Chinese names mix scripts by nature and routinely carry Latin, so those combinations are not marked, and neither is Latin beside a script that shares no shapes with it.\n\nThe first two reasons are asked of the skills already in the output directory as well as of the other entries, and say `a local skill` in place of `another entry` when that is where the twin is. Without that comparison a repository publishing only the imitation — `dep1oy` against a `deploy` you have had for months — is a single plain-ASCII name in one script with nothing on the list to compare it against, and every check stays quiet. A local skill that names the directory an entry would be written into is the skill that entry would refresh rather than one imitating it, so it is not a collision and is not marked; a second fetch of the same repository is therefore as quiet as the first. Where the two spellings differ only in case, or only in how the name is composed in Unicode, whether they name one directory is the filesystem's answer rather than the listing's — macOS and Windows resolve `skills/PDF` to an existing `skills/pdf`, Linux does not — so Rulesync asks it, and marks the pair only where they really are two directories — and only where the two also read alike, so that a local skill a _second_ entry imitates keeps its place in the comparison while the first entry refreshes it. A fullwidth `ｐｄｆ` is a second directory everywhere and is always marked. Where both another entry and a local skill collide with a name, the entry is the one named, since that is the pair you can compare on screen.\n\nA `fetch` that shows no prompt — a plain one, or one selecting with `--skills` — prints the same reasons as a warning listing the names they apply to, so a scripted run is told what an interactive one would have been shown. The names are judged against everything the repository publishes and everything already in the output directory, as the prompt judges them, and listed for what the run actually writes: `--skills c0py` is told that the name reads like another entry even though the `copy` that makes it so was never fetched.\n\nThe mark is display-only: it never removes a skill from the list. It is also not a complete answer — the table of lookalike letters holds the common pairs rather than every one, and a name written entirely in a script the table does not map is compared against nothing — so treat it as a hint to look closer, not as a guarantee that unmarked entries are distinct.\n\nNames that cannot be shown honestly at all are a separate case: a skill directory whose name carries a control character, one that draws as nothing — a zero-width space, a Hangul filler, a braille blank — or one that draws as nothing but blank space or combining marks with no letter to sit on is dropped rather than marked, with a warning naming it in stripped form. That drop applies to every `fetch`, including a plain one with neither `--skills` nor `--interactive`, because such a directory on disk cannot be told from the plain name it imitates in any line Rulesync prints.\n\nA zero-width joiner or a variation selector is dropped only where it hides something. It is kept beside the scripts that are written with one — the Arabic family, the Indic scripts, Mongolian — and beside the pictographs an emoji sequence is built from; anywhere else it can be nothing but padding, so `pdf` with a joiner in it is dropped, and so is `設定` with one between its two characters. Standing where its own script puts it — a Persian or Indic name written with a zero-width non-joiner, an emoji name built from a chain of joiners — it is left alone and the name is fetched normally. A joiner is held to both of its neighbors, since it exists to bind two characters: a name that merely ends in one is a second directory drawn exactly like the name beside it, and is dropped. A variation selector is held only to the character before it, which is the one whose form it selects, so an emoji name may end in one. The keycap sequences — `1️⃣`, `#️⃣`, `*️⃣`, spelled as UTS #51 spells them: one of `0`–`9`, `#` or `*`, then U+FE0F, then U+20E3 — are matched whole, since what they are built on is a digit or an ASCII sign rather than a pictograph. Only the whole sequence is kept: a digit followed by a variation selector with no enclosing keycap behind it is padding still, and is dropped still.\n\n#### Remote Paths in Rulesync's Output\n\nPath names come from the remote repository, so every one that Rulesync prints — the fetch summary, warnings, and debug lines — has its control characters stripped first. A crafted path cannot forge or erase the lines around it, which is what makes the record of what was written and deleted worth reading.\n\nThe `--json` output is the exception: it carries each path exactly as the repository spells it, because a machine consumer needs the real name to act on it. Anything that renders a value out of that JSON into a terminal has to strip it itself.\n\n### Examples\n\n```bash\n# Fetch skills from external repositories\nrulesync fetch vercel-labs/agent-skills\nrulesync fetch anthropics/skills\n\n# Fetch only specific skills by name\nrulesync fetch anthropics/skills --skills pdf,docx\n\n# Interactively select which skills to fetch (checkbox prompt)\n# Nothing is checked when the prompt opens: press <space> to select the\n# highlighted skill, <a> to select/deselect all, <i> to invert, and <enter> to confirm.\nrulesync fetch anthropics/skills --interactive\n\n# Interactively select skills with some pre-checked\nrulesync fetch anthropics/skills --interactive --skills pdf\n\n# Fetch all features from a public repository\nrulesync fetch dyoshikawa/rulesync --path .rulesync --features \"*\"\n\n# Fetch only rules and commands from a specific tag\nrulesync fetch owner/repo@v1.0.0 --features rules,commands\n\n# Fetch from a private repository (uses GITHUB_TOKEN env var)\nexport GITHUB_TOKEN=ghp_xxxx\nrulesync fetch owner/private-repo\n\n# Or use GitHub CLI to get the token\nGITHUB_TOKEN=$(gh auth token) rulesync fetch owner/private-repo\n\n# Preserve existing files (skip conflicts)\nrulesync fetch owner/repo --conflict skip\n\n# Keep local files a fetched skill no longer has upstream\nrulesync fetch anthropics/skills --no-prune\n\n# Fetch from a monorepo subdirectory\nrulesync fetch owner/repo:packages/my-package\n```\n\n## Convert Command\n\nThe `convert` command converts configuration files from one AI tool directly to one or more destination tools **without creating `.rulesync/` files on disk**. The intermediate rulesync representation is kept in memory only.\n\nThis is useful when you want to translate a one-shot tool-to-tool conversion (e.g., \"I have Cursor rules, give me Claude Code and Copilot equivalents\") without adopting rulesync's managed source-of-truth workflow.\n\n### Options\n\n| Option                      | Description                                                                                                               | Default   |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------- |\n| `--from <tool>`             | Source tool to convert from (single tool, e.g., `cursor`, `claudecode`)                                                   | Required  |\n| `--to <tools>`              | Comma-separated list of destination tools (e.g., `copilot,claudecode`)                                                    | Required  |\n| `--features, -f <features>` | Comma-separated list of features to convert (rules, commands, subagents, skills, ignore, mcp, hooks, permissions, checks) | `*` (all) |\n| `--verbose, -V`             | Verbose output                                                                                                            | `false`   |\n| `--silent, -s`              | Suppress all output                                                                                                       | `false`   |\n| `--global, -g`              | Convert for global (user scope) configuration files                                                                       | `false`   |\n| `--dry-run`                 | Show changes without writing files                                                                                        | `false`   |\n\n### Examples\n\n```bash\n# Convert Cursor rules to Copilot and Claude Code\nrulesync convert --from cursor --to copilot,claudecode --features rules\n\n# Convert all features Cursor and Copilot both support\nrulesync convert --from cursor --to copilot\n\n# Convert MCP configuration from Claude Code to Cursor\nrulesync convert --from claudecode --to cursor --features mcp\n\n# Dry run to preview the conversion\nrulesync convert --from cursor --to copilot,claudecode --dry-run\n```\n\n### Behavior\n\n- The intermediate rulesync files produced during conversion are **never** written to disk. Only destination tool files are written.\n- Features that exist for the source tool but are not supported by a given destination tool are skipped with a warning.\n- When `--features` is omitted, the command attempts every feature the source tool supports.\n- Passing the source tool inside `--to` is rejected, because converting a tool onto itself is lossy.\n- With `--dry-run`, no destination files are written; the command prints a summary prefixed with `[DRY RUN]` listing what would have been converted.\n\n## Doctor Command\n\nThe `doctor` command runs read-only diagnostics against the configuration files (`rulesync.jsonc` and `rulesync.local.jsonc`) and reports problems grouped by severity (`error` / `warning` / `info`). It never writes files, which makes it a safe first step when generation does not behave as expected, and a cheap CI guard.\n\nIt is especially useful for catching **silently ignored configuration**: the config schema is non-strict, so a misspelled key such as `\"target\"` instead of `\"targets\"` is normally swallowed without any error. `doctor` reports every unknown key with a \"did you mean\" suggestion.\n\n### Checks\n\n- JSONC parse errors, reported with line and column.\n- Unknown or misspelled top-level keys, with a \"did you mean\" suggestion.\n- Unknown tool targets and features (array and object forms), with the nearest valid name suggested.\n- Deprecated features (`ignore`, superseded by `permissions`).\n- Object-form `targets` combined with `features` — including the case where the conflict only appears after merging `rulesync.jsonc` with `rulesync.local.jsonc`.\n- Conflicting target pairs (e.g. `claudecode` + `claudecode-legacy`).\n- `$schema` presence and whether it points at the current config schema URL.\n- Structural schema violations on any other key (wrong types, malformed `sources` entries).\n- `sources[].tokenEnv` naming an environment variable that is not set.\n- `inputRoot` or the first `inputRoots` entry pointing at a directory that does not exist. Later `inputRoots` entries are optional overlays and may be absent.\n- `inputRoot` or an `inputRoots` entry set to an empty string, which makes `generate` fail with `outputRoot cannot be an empty string` before it resolves any source tree.\n- Duplicate entries in `inputRoots` (warning; duplicates are ignored at generate time).\n\n### Options\n\n| Option                | Description                       | Default          |\n| --------------------- | --------------------------------- | ---------------- |\n| `--config, -c <path>` | Path to configuration file        | `rulesync.jsonc` |\n| `--strict`            | Treat warnings as errors (exit 1) | `false`          |\n| `--verbose, -V`       | Verbose output                    | `false`          |\n| `--silent, -s`        | Suppress all output               | `false`          |\n\n### Examples\n\n```bash\n# Diagnose the project configuration\nrulesync doctor\n\n# Fail CI on warnings too\nrulesync doctor --strict\n\n# Machine-readable output for editors and CI\nrulesync --json doctor\n\n# Diagnose a configuration file at a custom location\nrulesync doctor --config ./configs/rulesync.jsonc\n```\n\n### Behavior\n\n- Exits with code `1` when any `error`-severity diagnostic is present (or any `warning` with `--strict`), and `0` otherwise.\n- With the global `--json` flag, diagnostics and a severity summary are emitted as structured JSON: in `data` on success (exit 0), and in `error.details` of the standard error document (code `DOCTOR_FAILED`) on failure.\n- A missing configuration file is reported as `info` only — rulesync runs fine with built-in defaults.\n\n## Docs Command\n\nThe `docs` command prints the bundled Rulesync documentation to standard output, so both humans and coding agents can retrieve it directly in the terminal without browsing the repository or website. The documentation is embedded in the CLI at build time, so it works in installed npm distributions and compiled binaries alike.\n\nDocument identifiers follow the `docs/` hierarchy without the `docs/` prefix or the `.md` extension (both are accepted and stripped when supplied). Identifiers that try to escape the bundled tree — absolute paths, drive letters, `..` segments — are rejected.\n\n### Usage\n\n```bash\n# List every available document identifier\nrulesync docs\n\n# Print a document (top-level or nested)\nrulesync docs faq\nrulesync docs guide/configuration\n\n# Ranked full-text search across the bundled documentation\nrulesync docs --search \"global mode\"\n```\n\n### Search\n\n`--search <text>` builds an in-memory BM25+ index (via MiniSearch) over document paths, titles, headings, and body content, with stronger boosts for titles and headings. Up to 10 results are printed, one per line, as `<document> — <matching context>`. Matching is exact-term; no prefix or fuzzy expansion is applied.\n\n### Behavior\n\n- `rulesync docs` with no argument lists all document identifiers, one per line, sorted.\n- A missing document, an invalid identifier, an empty search text, a search with no matches, or combining a document argument with `--search` each exit with code 1 and an explanatory error.\n- Document output is printed verbatim, so it can be piped to other tools.\n- The global `--json` flag is not supported (the command's output is raw Markdown, not a JSON document) and exits with code 1.\n\n## Release Notes Command\n\nThe `release-notes` command prints GitHub release notes for any repository, so you can review what changed in an upstream AI coding tool — or in Rulesync itself — without leaving the terminal. Releases are fetched through the GitHub Releases API and rendered as Markdown on standard output, newest first.\n\nThe repository is given as `owner/repo` or a full `https://github.com/owner/repo` URL. Unlike `fetch`, ref (`@`) and path (`:`) suffixes are rejected — use `--tag` to select a single release. Only GitHub is supported; other Git providers have no equivalent Releases API.\n\n### Usage\n\n```bash\n# Latest 10 releases (default)\nrulesync release-notes dyoshikawa/rulesync\n\n# Most recent N releases\nrulesync release-notes dyoshikawa/rulesync --latest 5\n\n# Releases published within a date range (either end may be omitted)\nrulesync release-notes dyoshikawa/rulesync --since 2026-01-01 --until 2026-06-30\n\n# A single release by tag name\nrulesync release-notes dyoshikawa/rulesync --tag v16.11.0\n\n# Every release between two tags, inclusive\nrulesync release-notes dyoshikawa/rulesync --from v16.0.0 --to v16.11.0\n\n# Include prereleases\nrulesync release-notes dyoshikawa/rulesync --include-prereleases\n\n# Machine-readable output\nrulesync --json release-notes dyoshikawa/rulesync --latest 3\n```\n\n### Filtering\n\nThe four filtering modes — `--latest`, `--since`/`--until`, `--tag`, and `--from`/`--to` — are mutually exclusive; combining them exits with code 1. With no filter, the latest 10 releases are printed.\n\n| Option                              | Description                                                                                                                                                                                                                      |\n| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--latest <count>`                  | Print the most recent `<count>` releases. Must be a positive integer.                                                                                                                                                            |\n| `--since <date>` / `--until <date>` | Print releases published within the range, both ends inclusive. Either end may be omitted for an open-ended range. Dates are parsed as ISO 8601, e.g. `2026-01-31`; a bare date given to `--until` covers that whole day in UTC. |\n| `--tag <tag>`                       | Print a single release by tag name. Named `--tag` rather than `--version` because `--version` is the global flag that prints the Rulesync version.                                                                               |\n| `--from <tag>` / `--to <tag>`       | Print every release between two tags, inclusive. Both are required.                                                                                                                                                              |\n| `--include-prereleases`             | Include prereleases in the output.                                                                                                                                                                                               |\n| `--token <token>`                   | GitHub token for private repositories or higher rate limits.                                                                                                                                                                     |\n\nTag ranges are resolved by position in the repository's release history, not by parsing semver, so non-semver tag names work and the order of `--from` and `--to` does not matter. A tag that does not appear in the history exits with code 1.\n\n### Authentication\n\nRequests are unauthenticated by default, which is enough for public repositories but subject to GitHub's stricter anonymous rate limit. Set `GITHUB_TOKEN` or `GH_TOKEN` (or pass `--token`) for private repositories and higher limits:\n\n```bash\nGITHUB_TOKEN=$(gh auth token) rulesync release-notes owner/private-repo\n```\n\n### Behavior\n\n- Draft releases are never printed: they are unpublished and only visible to accounts with write access.\n- Prereleases are excluded unless `--include-prereleases` is given, matching how GitHub itself resolves the \"latest\" release. `--tag` is the exception — an explicitly named tag is printed regardless of its prerelease status.\n- A repository with no matching releases prints a warning and exits with code `0`.\n- Range queries walk at most 10 API pages (1,000 releases); tags older than that are reported as not found.\n- Date ranges scan the whole walked history rather than stopping at the first out-of-range release, because the API orders releases by creation date and a release published from a long-lived branch can appear out of publication order.\n- Default output is Markdown on standard output, so it can be piped to other tools. With the global `--json` flag, the releases are emitted as structured `data` instead and no Markdown is printed; failures use the standard error document with code `RELEASE_NOTES_FAILED`.\n",
 	"reference/command-syntax": "# Command Syntax\n\nSlash commands authored under `.rulesync/commands/*.md` use a **universal syntax** that mirrors Claude Code's command placeholders. When rulesync generates a tool-specific command file, it rewrites these placeholders into the syntax that the target tool understands. The reverse rewrite happens on import, so a rulesync ↔ tool round-trip preserves the original universal form.\n\n## Universal placeholders\n\n| Placeholder  | Meaning                                                                  |\n| ------------ | ------------------------------------------------------------------------ |\n| `$ARGUMENTS` | The full argument string the user supplied when invoking the command.    |\n| `` !`cmd` `` | Inline shell expansion. The agent runs `cmd` and substitutes its output. |\n\nThese are written exactly as Claude Code accepts them, so writing a rulesync command body is the same as writing a Claude Code command body.\n\n## Per-tool translation\n\nThe table below shows how each placeholder is translated for the supported tools. \"pass-through\" means the placeholder is emitted verbatim because the target tool already understands the universal form.\n\n| Tool              | `$ARGUMENTS`           | `` !`cmd` ``                |\n| ----------------- | ---------------------- | --------------------------- |\n| Claude Code       | pass-through           | pass-through                |\n| Codex CLI[^codex] | pass-through (literal) | pass-through (literal)      |\n| Pi                | pass-through           | pass-through (literal)[^pi] |\n| Other tools[^1]   | pass-through (literal) | pass-through (literal)      |\n\n[^1]: Tools not listed do not have a documented translation; their command body is emitted as-is.\n\n[^codex]: Codex CLI prompt files are forwarded to the LLM verbatim; the placeholders are passed to the model as literal text rather than being substituted by the engine.\n\n[^pi]: Pi natively expands `$ARGUMENTS` (along with `$1`, `$2`, `$@`), so `$ARGUMENTS` is a real pass-through there. rulesync still emits `` !`cmd` `` verbatim for Pi, but does not assume Pi expands inline shell snippets — treat that placeholder as literal text on Pi's side.\n\nThe translation also runs in reverse when you import an existing tool command file via `rulesync import`, so a tool-native placeholder is rewritten back to the universal form in the generated `.rulesync/commands/*.md`.\n\n## Example\n\nGiven the following rulesync command:\n\n```md\n---\ntargets: [\"claudecode\"]\ndescription: \"Summarize git diff\"\n---\n\nSummarize the diff:\n!`git diff`\n\nFocus on $ARGUMENTS.\n```\n\nrulesync generates `.claude/commands/summarize.md`, passing the placeholders through verbatim because Claude Code already understands the universal form.\n\n## Notes\n\n- If you author a command with explicit tool-specific syntax (e.g. you write a tool-native placeholder directly in a rulesync command body), rulesync does **not** re-translate the already-tool-native form. Stick to the universal placeholders to keep commands portable across tools.\n- The translation is purely textual and is applied to the entire body. It does not skip fenced or inline code blocks, so ` ```js\\n$ARGUMENTS\\n``` ` in a rulesync body will still be rewritten when generating tool output. There is **no escape syntax** for the universal placeholders — backslashes are not consumed by the regex, so `\\$ARGUMENTS` is rewritten alongside the placeholder rather than producing a literal `$ARGUMENTS`.\n- The shell expansion regex matches a single backtick-delimited segment without embedded backticks or newlines (`` !`...` ``). Multi-line shell snippets are not supported, and a backtick inside the command body is not allowed.\n",
-	"reference/file-formats": "# File Formats\n\n## Symlinks\n\nRulesync follows symbolic links when it discovers source files, whether you use a plain `.rulesync/` directory or separate `--input-roots`. Glob-based discovery (rules, commands, subagents, skills) follows symlinked files and directories; single fixed-path files such as `.rulesyncignore`, `.rulesync/mcp.jsonc`, and `.rulesync/permissions.jsonc` are likewise resolved transparently by the OS when read. A symlink inside the input tree that points elsewhere is followed transparently, and the resolved file content is copied into the generated output. This is intentional: it lets you centralize shared skills or rules in one place and reference them via symlinks without duplication (see [issue #1707](https://github.com/dyoshikawa/rulesync/issues/1707)).\n\nThe trust boundary is the directory you point Rulesync at. There is **no** `realpath`-based containment check on individual symlinks, so a link may resolve to a target outside the input root — enforcing containment would break the shared-file use case above. Only run Rulesync against trees you control. Directory symlink **cycles** are handled safely: glob-based results are deduplicated by the real file they resolve to, so a cycle does not produce duplicated output, and two names for one file (a `docs/reference.md` link pointing at a top-level `reference.md`, say) yield a single entry. Skill directories are not discovered by globs at all — they are walked directly, and that walk keeps every entry it reaches, so a supporting file remains available under each name the skill gives it. Note that the remote-fetch path (`rulesync fetch` from a Git repository) is a separate, hardened code path that never **follows** a symlink. A symlink in the remote repository is skipped rather than downloaded, so untrusted remote content never has its links resolved. Locally, the stale-file prune described in [CLI Commands](./cli-commands.md#pruning-fetched-skill-directories) removes a stale link itself without reading through it, and refuses to prune a skill directory that is a symlink at all, so a shared skill you linked in stays untouched.\n\nThree exceptions narrow this within skill directories. First, the entries a skill directory never carries (listed in the supporting-file note below) are excluded by the name they really resolve to, not just the name they have inside the skill — a link called `vendor` pointing at `~/.aws` is refused exactly as a directory called `.aws` is. Second, a link whose real path lands in a system pseudo-filesystem (`/proc`, `/sys`, `/dev`) is refused: `/proc/self/environ` looks like an ordinary file but reads back the environment of the running process. Third, a skill directory's companion files include hidden (dot-prefixed) entries, so an ordinary-looking link to a home directory would otherwise pull in every dotfile beneath it: a hidden entry whose real path resolves outside the skill directory is **not** carried, and the skipped paths are named in a warning. Copy such a file into the directory if the skill really needs it.\n\nWhat decides that third rule is the name inside the skill directory, not the path the link resolves through: a named file keeps the behavior above even when its target sits under a dot-directory such as `~/.dotfiles/skills/`, because somebody chose that name. Reaching outside the directory is reported either way — carried or not — since the content is about to be copied into every enabled tool root.\n\nOne discovery pass is deliberately excluded from the follow-symlinks rule: the scan for nested `AGENTS.md` files (see the `agentsmd` note below). Unlike every other glob above, it walks the whole project rather than a rulesync-owned directory, so a symlink committed to a repository you cloned could otherwise pull a file from outside the project into version-controlled `.rulesync/`. That scan does not follow symlinks.\n\n## `rulesync/rules/*.md`\n\nExample:\n\n```md\n---\nroot: true # true for root-level rules, false for details such as `.agents/memories/*.md`\nlocalRoot: false # (optional, default: false) true for project-specific local rules. Claude Code: CLAUDE.local.md; Rovodev (Rovo Dev CLI), Roo Code, Zoo Code and Devin: AGENTS.local.md; Qwen Code: .qwen/QWEN.local.md; Others: append to root file. See the localRoot note below for import behavior\ntargets: [\"*\"] # * = all, or specific tools\ndescription: \"Rulesync project overview and development guidelines for unified AI rules management CLI tool\"\nglobs: [\"**/*\"] # file patterns to match (e.g., [\"*.md\", \"*.txt\"])\nagentsmd: # agentsmd and codexcli specific parameters\n  # Support for using nested AGENTS.md files for subprojects in a large monorepo.\n  # This option is available only if root is false.\n  # If subprojectPath is provided, the file is located in `${subprojectPath}/AGENTS.md`.\n  # If subprojectPath is not provided and root is false, the file is located in `.agents/memories/*.md`.\n  subprojectPath: \"path/to/subproject\"\ncursor: # cursor specific parameters\n  alwaysApply: true\n  description: \"Rulesync project overview and development guidelines for unified AI rules management CLI tool\"\n  globs: [\"*\"]\ncopilot: # copilot specific parameters (non-root `*.instructions.md` files only)\n  name: \"TypeScript Style\" # (optional) display name shown in the VS Code UI; defaults to the file name\n  excludeAgent: \"code-review\" # (optional) \"code-review\" or \"cloud-agent\": skip this file for that agent\n  # Any other frontmatter key found in a hand-written `*.instructions.md` is imported into this\n  # section and written back out, so a field Rulesync does not model is not lost on regeneration.\n  # `description` and `applyTo` are the exception: they have canonical homes (`description` and\n  # `globs`), so a value written for them in this section is overwritten by the canonical one.\nantigravity: # antigravity specific parameters\n  trigger: \"always_on\" # always_on, glob, manual, or model_decision\n  globs: [\"**/*\"] # (optional) file patterns to match when trigger is \"glob\"\n  description: \"When to apply this rule\" # (optional) used with \"model_decision\" trigger\ndevin: # devin (Devin Desktop, formerly Windsurf) specific parameters\n  trigger: \"always_on\" # always_on, glob, manual, or model_decision\n  globs: [\"**/*\"] # (optional) file patterns to match when trigger is \"glob\"\n  description: \"When to apply this rule\" # (optional) used with \"model_decision\" trigger\naugmentcode: # augmentcode specific parameters\n  type: \"always_apply\" # always_apply, manual, or agent_requested\n  description: \"When to apply this rule\" # (optional) used with \"agent_requested\" type\nkiro: # kiro specific parameters (steering inclusion)\n  inclusion: \"fileMatch\" # always, fileMatch, manual, or auto\n  fileMatchPattern: [\"src/components/**/*.tsx\"] # (optional) glob string or array of globs, used when inclusion is \"fileMatch\"\n  name: \"api-design\" # (optional) required when inclusion is \"auto\"; the steering entry key\n  description: \"REST API design patterns. Use when creating or modifying API endpoints.\" # (optional) required when inclusion is \"auto\"; Kiro auto-includes the file when a request matches this\ntakt: # takt specific parameters (optional; emitted under .takt/facets/policies/ — frontmatter is dropped on emit)\n  name: \"renamed-stem\" # (optional) override the emitted filename stem (no path separators or \"..\")\n  extends: \"base\" # (optional) emit a leading `{extends:<parent>}` facet-inheritance directive (Takt 0.39.0+)\n  facet: \"output-contracts\" # (optional) \"policies\" (default) or \"output-contracts\": redirect this rule to Takt's output-structure/report-template facet\n---\n\n# Rulesync Project Overview\n\nThis is Rulesync, a Node.js CLI tool that automatically generates configuration files for various AI development tools from unified AI rule files. The project enables teams to maintain consistent AI coding assistant rules across multiple tools.\n\n...\n```\n\nMultiple files can set `root: true` for the same target in project and global modes. Rulesync renders each file through the target adapter, then combines compatible root or plain-Markdown single-file outputs in deterministic source-discovery order with one blank line between fragments. Local rules are ordered lexicographically by source file path and composed before non-overridden `.curated/` rules, which are also ordered lexicographically; filename prefixes such as `10-` and `20-` control composition order within each set. Targets that map source rules to distinct native paths keep those files separate. Explicitly supported plain-Markdown modular rules that normalize to the same output path are combined; a fragment whose generated output carries its own frontmatter block (such as Amp's `globs:` gate) is never composed and stays a separate file instead. Unsafe collisions involving a source `root: true` rule fail. Other exact or case-insensitive modular collisions remain separate and produce a warning that the last write wins wherever the filesystem treats their paths as the same.\n\n> **localRoot import note:** For the tools that emit a separate personal local file (Claude Code and its legacy layout: `CLAUDE.local.md`; Rovodev, Roo Code, Zoo Code and Devin: `AGENTS.local.md`; Qwen Code: `.qwen/QWEN.local.md`), `rulesync import` also reads that file back as a `localRoot: true` rule under `.rulesync/rules/`, keeping the tool-side basename. The imported rule's `targets` is scoped to the tool it was imported from, not `\"*\"` — a wildcard would spread the personal content into other tools' committed root files on the next generate (tools without a separate local file append `localRoot` bodies to their root file), and importing from several tools would otherwise produce conflicting wildcard `localRoot` rules. Widen `targets` by hand if you do want the content shared. The same scoping applies to `rulesync convert`: converting to a different tool drops the source tool's personal local file rather than folding it into the destination's root file. The derived `.gitignore` covers the imported copy via `.rulesync/rules/*.local.md`; run `rulesync gitignore` after a first import if the project's `.gitignore` has not been generated yet, so the personal content stays untracked. Project scope only, like `localRoot` generation itself.\n\n> **AGENTS.md standard note (`agentsmd`):** Nested `AGENTS.md` files are the standard's only scoping mechanism — agents read the nearest file in the directory tree, so the closest one wins. Rulesync writes them from `agentsmd.subprojectPath` and, on **import**, discovers them by scanning the project for `**/AGENTS.md`. Hidden directories (other tools' generated output, including rulesync's own) are skipped at any depth, as are `node_modules/` and `__pycache__/`. Build, vendoring and scratch directories (`vendor/`, `third_party/`, `dist/`, `build/`, `out/`, `target/`, `coverage/`, `tmp/`, `temp/`, `venv/`) are skipped **at the project root only**, because a top-level `build/` is a build directory while `packages/build/` is a real subproject. Beyond those names, the scan honors your `.gitignore`: a file git does not track is not your project's source, and copying a vendored dependency's rule file into version-controlled `.rulesync/rules/` would hand third-party instructions to every tool — including the ones that concatenate non-root rules into a single always-loaded file. (Ignore rules come from the `.gitignore` files at and below the output root — a parent repository's rules are not consulted, so running against a subdirectory only sees that subdirectory's own. The test is applied to the _directories_ above each file, not the file itself, so the `**/AGENTS.md` entry that `rulesync gitignore` writes for its own output does not disable the scan; the flip side is that ignoring one individual `AGENTS.md` no longer keeps it out of the import.) Symbolic links are not followed, so a link committed to a repository cannot pull a file from outside the project into version-controlled `.rulesync/`. The scan is import-only: a nested file rulesync did not write is never removed by `--delete`. That means deleting the rulesync rule stops the reference from being listed in the root `AGENTS.md`, but leaves the subproject file itself on disk — where agents still read it, since the nearest file wins. Remove it by hand. Each discovered file is imported to `.rulesync/rules/<directory-with-hyphens>.md` (e.g. `packages/api/AGENTS.md` → `packages-api.md`) carrying `agentsmd.subprojectPath`, so the next generate puts it back where it came from. A subproject that would claim the reserved `overview.md` name gets an `-agents` suffix instead, so the root rule is never overwritten; any other pair of sources deriving the same name is reported at import time, since only the last one survives. Import always rewrites `.rulesync/rules/`, so a subproject whose derived name matches a rule file you wrote by hand replaces it — pick distinct names, or keep hand-written rules out of the derived namespace. See <https://agents.md/>.\n\n> **Kiro note:** Kiro reads steering files from `.kiro/steering/*.md` and uses an `inclusion` frontmatter block to decide when each is loaded (`always`, `fileMatch` with a `fileMatchPattern`, `manual`, or `auto` — which auto-includes the file when a request matches its companion `description`, keyed by `name`). Rulesync derives this for non-root steering files: an explicit `kiro.inclusion` block round-trips as-is (carrying `name`/`description` through for `auto`); otherwise specific (non-wildcard) `globs` map to `inclusion: fileMatch` (a single glob is written as a string and multiple as a YAML array, both of which Kiro accepts), so the rule applies only to matching files instead of always; otherwise the file stays always-on and is written without a frontmatter block (Kiro's no-frontmatter default). The root overview index is always written plain so Kiro always loads it. A rule carrying the shared directory-scoping carrier `agentsmd.subprojectPath` is written to `<dir>/AGENTS.md` **instead of** `.kiro/steering/`: Kiro CLI 2.18.0 and IDE 1.0.309 load `AGENTS.md` as steering context from anywhere in the workspace tree, so a directory-scoped rule reaches only the subtree it applies to rather than being flattened into an always-loaded steering file. A nested file is written plain (no `inclusion` block — that frontmatter belongs to `.kiro/steering/*.md`), and imports back as a `kiro`-targeted rule named after its directory (`services/api` → `services-api-kiro.md`). Like every other nested scan, discovery is **import-only**: the matches are hand-authored files outside a rulesync-owned directory, so `generate --delete` never sweeps them. Nesting is project scope only — under `~/.kiro/steering/` there is no workspace tree to scope against, so `subprojectPath` is ignored there. In **global** mode (`--global`), steering is written to `~/.kiro/steering/` with the root rule as `~/.kiro/steering/product.md` (Kiro does not read `~/AGENTS.md`, so the project-scope root `AGENTS.md` is not used at the home level), and global MCP is written to `~/.kiro/settings/mcp.json`.\n\n> **Grok CLI note:** Grok Build writes the root rule to the auto-loaded `AGENTS.md` (project) / `~/.grok/AGENTS.md` (global, via `--global`), and non-root rules to `.grok/rules/*.md` (project) / `~/.grok/rules/*.md` (global). Grok scans that directory flat and in name order, alongside the AGENTS.md family — earlier Rulesync versions folded every topic rule into the single root file, which matched Grok 0.2.54 but not the current release, so regenerate to split them back out. Non-root files carry no frontmatter. Because this is a directory Grok defines rather than one Rulesync invented, a project may already have hand-written files there: Rulesync owns it from now on, so `--delete` removes anything in it — `~/.grok/rules/` included, in global mode — that `.rulesync/rules/` does not produce. Move those files into `.rulesync/rules/` first.\n\n> **Kilo Code note:** Kilo writes the root rule to the auto-loaded `AGENTS.md` and non-root rules to `.kilo/rules/*.md`. Because Kilo v7 does not auto-load files under `.kilo/rules/`, Rulesync also registers each generated non-root rule file in the `instructions` array of the shared `kilo.jsonc` (the root `AGENTS.md` is auto-loaded and is therefore not registered). This merge is non-destructive: existing keys such as `mcp`, `tools`, and `permission` are preserved. Within the `instructions` list rulesync owns the entries under `.kilo/rules/` — that subset is rebuilt from the current generate, so deleting a rule also drops its registration — while entries outside it pass through verbatim; the result is deduped and sorted.\n\n> In global mode (`--global`), Kilo's own layout is asymmetric: the root rule goes to `~/.config/kilo/AGENTS.md`, while non-root rules go to `~/.kilo/rules/*.md` — the same `.kilo`-relative path the skills adapter uses in both scopes. Global rules need no `instructions` registration, because Kilo auto-discovers every `~/.kilo/rules/*.md` on config load; writing the files is enough, and no global `kilo.jsonc` is touched by the rules feature.\n\n> **Kimi Code note:** Kimi Code reads `.kimi-code/AGENTS.md` at project scope and `~/.kimi-code/AGENTS.md` at user scope. When `KIMI_CODE_HOME` is set, Rulesync follows Kimi and resolves every global Kimi-specific file (`AGENTS.md`, `mcp.json`, `config.toml`, `skills/`, and `agents/`) under that custom data root; the shared `~/.agents/skills/` and `~/.agents/agents/` discovery roots remain under the user's real home directory. Because Kimi has no dedicated directory for topic-based instruction files, Rulesync folds every non-root rule body into that single file. See the [Kimi Code agents and instruction-files docs](https://moonshotai.github.io/kimi-code/en/customization/agents.html) and [environment-variable docs](https://moonshotai.github.io/kimi-code/en/configuration/env-vars.html).\n\n> **OpenCode note:** OpenCode writes the root rule to the auto-loaded `AGENTS.md` and non-root rules to `.opencode/memories/*.md`. Because OpenCode auto-loads only the root `AGENTS.md` plus files explicitly listed in the `instructions` array of `opencode.json` (it does not auto-discover a rules directory), Rulesync also registers each generated non-root rule file in the `instructions` array of the shared `opencode.json`/`opencode.jsonc` (the root `AGENTS.md` is auto-loaded and is therefore not registered). The same applies in **global** mode (via `--global`): OpenCode reads `instructions` from the global `~/.config/opencode/opencode.json` too, so global non-root rules are written to `~/.config/opencode/memories/*.md` and registered there (entries relative to the config file's directory, e.g. `memories/style.md`) instead of being dropped. This merge is non-destructive: existing keys such as `mcp`, `tools`, and `permission` are preserved. Within the `instructions` list rulesync owns the entries under its managed rules directory (`.opencode/memories/`, or `memories/` in the global config) — that subset is rebuilt from the current generate, so deleting a rule also drops its registration — while entries outside it pass through verbatim; the result is deduped and sorted.\n\n> **Qwen Code note:** Qwen Code writes the root rule to the auto-loaded `QWEN.md` (project) / `~/.qwen/QWEN.md` (global, via `--global`) as plain Markdown, and non-root rules to its path-based context-rule directory `.qwen/rules/` (project) / `~/.qwen/rules/` (global). Each non-root rule is a Markdown file with optional YAML frontmatter: Rulesync maps `globs` ⇄ Qwen's `paths` (a picomatch glob array) and `description` ⇄ `description`. A rule **with** specific `paths` is _conditional_ — Qwen lazily injects it only when the model touches a matching file — while a rule **without** `paths` (empty or wildcard `**/*`/`*` globs) is a _baseline_ rule loaded at session start and is written as plain Markdown with no frontmatter block. The `.qwen/rules/` directory supersedes the legacy `.qwen/memories/` import surface, so each rule is emitted to exactly one location; the root `QWEN.md` is unchanged. A `localRoot: true` rule is emitted to `.qwen/QWEN.local.md` (project scope only) — Qwen Code v0.16.2's personal project context file, loaded after the shared `QWEN.md` so it can override team instructions; the file is covered by the derived `.gitignore` since Qwen Code does not gitignore it for you. See the [Qwen Code memory/context docs](https://github.com/QwenLM/qwen-code).\n\n> **Cline note:** Cline writes the root rule to the auto-loaded `AGENTS.md` (project) as plain Markdown, and non-root rules to its flat `.clinerules/` directory. Each non-root rule is a Markdown file with optional YAML frontmatter for conditional activation: Rulesync maps `globs` ⇄ Cline's `paths` (a glob array; the rule loads only when a matching file is in context) and `description` ⇄ `description`. A rule with **specific** `globs` emits `paths`; a rule with **universal** globs (`**/*` or `*`) emits `alwaysApply: true` (always load); a rule **without** globs is written as plain Markdown with no frontmatter block (always active). In global mode (via `--global`), the root rule is written to the cross-tool `~/.agents/AGENTS.md` (Cline CLI v3.0.15+) as plain Markdown, and non-root rules go to `~/Documents/Cline/Rules/*.md` — the global modular-rules directory both the VS Code extension and the SDK/CLI read — with the same conditional-frontmatter conversion project rules get. See the [Cline rules docs](https://docs.cline.bot/customization/cline-rules).\n\n> **Warp note (rules):** Warp reads project rules from the root `AGENTS.md` (or the back-compat `WARP.md`) and does not scan a modular rules directory, so non-root rule bodies are folded into the single root `./AGENTS.md`. In global mode (via `--global`), the root rule is written to the cross-tool `~/.agents/AGENTS.md` — Warp's third rule source alongside project and Warp Drive rules, also used from remote hosts in SSH sessions — with the same folding. Other targets (e.g. Cline) own the same global path; as with the shared project-root `AGENTS.md`, each target regenerates the file per its own semantics. See the [Warp rules docs](https://docs.warp.dev/agent-platform/capabilities/rules/) and [file locations](https://docs.warp.dev/terminal/settings/file-locations/).\n\n> **Pi note:** Pi writes the root rule to the auto-loaded `AGENTS.md` (project) / `~/.pi/agent/AGENTS.md` (global, via `--global`) as plain Markdown, and folds non-root rules into that single file (Pi has no modular rules directory). Pi additionally loads two system-prompt instruction files. `.pi/APPEND_SYSTEM.md` (project) / `~/.pi/agent/APPEND_SYSTEM.md` (global) **appends** to the default system prompt, and Rulesync emits it from any rule that opts in via a `pi.systemPrompt: append` frontmatter block — those rule bodies are routed to `APPEND_SYSTEM.md` instead of `AGENTS.md`, multiple opted-in rules concatenate in source order, and the file is managed by generate/import/delete like the root file (note: if you hand-authored `.pi/APPEND_SYSTEM.md` before this feature existed, `generate --delete` for the `pi` target now treats it as a managed path and removes it unless a rule opts in — import it first to convert it into a canonical rule). The opt-in is ignored on the `root: true` rule, which always stays on `AGENTS.md` (routing the root away would leave the context file without a merge target). `.pi/SYSTEM.md` (project) / `~/.pi/agent/SYSTEM.md` (global) **replaces** the default system prompt entirely — which silently disables Pi's built-in tool instructions — so Rulesync deliberately never emits it and leaves it to be authored by hand. Example:\n>\n> ```yaml\n> ---\n> targets: [\"pi\"]\n> description: \"House style for the system prompt\"\n> pi:\n>   systemPrompt: append # routes this rule's body to .pi/APPEND_SYSTEM.md / ~/.pi/agent/APPEND_SYSTEM.md\n> ---\n> ```\n>\n> Pi tries `AGENTS.override.md` before `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md` and `CLAUDE.MD` in every directory it scans (including the global `~/.pi/agent/` one), loading it **instead of** the others from that directory. Set `pi.contextFile: override` on the **`root: true`** rule to emit the root context file under that name — useful when another target owns the shared `AGENTS.md`, or when a `CLAUDE.md` sits next to it and Pi should deterministically prefer Rulesync's output. Because Pi folds every rule body into the root context file, one opted-in root rule decides for the whole Pi output: the flag is applied to every other Pi rule (root ones included), and setting it _only_ on a non-root rule is ignored with a warning — emitting both files would hide everything left in `AGENTS.md`. `AGENTS.override.md` is Pi-exclusive, so it is imported and deleted like the root file, and toggling the flag off cleans it up. The project-root `AGENTS.md` is never deleted on Pi's behalf, with or without the flag: `agentsmd`, `codexcli`, `warp` and others write that same path, so the `pi` target leaves a stale one behind rather than removing another target's output (the global `~/.pi/agent/AGENTS.md` is Pi-exclusive and is still cleaned up). Example:\n>\n> ```yaml\n> ---\n> root: true\n> targets: [\"pi\"]\n> pi:\n>   contextFile: override # emits AGENTS.override.md instead of AGENTS.md\n> ---\n> ```\n>\n> See the [Pi usage docs](https://pi.dev/docs/latest/usage) and the [context-file discovery in the Pi source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/resource-loader.ts).\n\n> **Devin note:** The root rule is emitted to the project-root `AGENTS.md` — the file [Devin CLI / Devin Local actually reads](https://docs.devin.ai/cli/extensibility/rules) (its rules page does not list `.devin/rules/` among its sources) — as plain markdown, while non-root rules keep going to `.devin/rules/*.md`, the Devin Desktop Cascade directory whose `trigger` activation modes (`always_on`, `glob`, `manual`, `model_decision`) are driven by the `devin` frontmatter block. Global mode mirrors that layout: the root rule is a plain `~/.config/devin/AGENTS.md`, and non-root rules are emitted one file per rule into `~/.devin/rules/*.md` with the same `trigger`/`globs` frontmatter. Note the directory split — the per-rule global directory is the home `~/.devin/`, not the `~/.config/devin/` tree the global root and Devin's other global surfaces use; that is what the rules page documents (`~/.devin/rules/*.md`, `~/.devin/global_rules.md`).\n\n> **Amp note:** Amp gates an @-mentioned guidance file on `globs:` YAML frontmatter — the file is loaded only after Amp has read a file matching one of the globs, and **without** the frontmatter it is always loaded. Rulesync therefore emits each non-root rule's `globs` as that frontmatter on the generated `.agents/memories/*.md` file (in addition to the advisory `applyTo` value in the root file's TOON table, which Amp does not enforce), and restores it into the canonical `globs` on import. Amp implicitly prefixes each glob with `**/` unless it starts with `./` or `../`, so canonical globs pass through verbatim. See [Globs in AGENTS.md](https://ampcode.com/news/globs-in-AGENTS.md).\n\n> **Junie note:** Junie CLI resolves project guidelines in order — `.junie/AGENTS.md` → root `AGENTS.md` combined with `.junie/playbook.md` and every `.junie/rules/*.md` → the legacy `.junie/guidelines.md` / `.junie/guidelines/`. The multi-file branch is unreachable whenever `.junie/AGENTS.md` exists, because that file \"is used exclusively and no other guidelines files are combined with it\". Rulesync therefore writes the root rule to `.junie/AGENTS.md` (project) / `~/.junie/AGENTS.md` (global, via `--global`) and folds non-root rules into that single file — lossless, since Junie loads it in full. Emitting `.junie/rules/*.md` beside it would produce files Junie never reads, and moving the root output to the project-root `AGENTS.md` would change every existing output path and collide with the `agentsmd` target, so the fold stays. The multi-file branch **is** read on import, but only while `.junie/AGENTS.md` is absent — exactly when Junie itself reads it. Hand-authored `.junie/rules/*.md` (that directory itself, not a tree below it) and `.junie/playbook.md` are then imported as non-root rules. They are import-only read roots — Rulesync never generates them, never deletes them as orphans, and never adds them to `.gitignore` — so the `generate` that follows folds their content into `.junie/AGENTS.md` and leaves the originals untouched. Later imports skip them with a single warning naming up to ten skipped files (the rest are folded into an `and N more` count): re-reading rules the root file already contains would fold the same content in again on every import/generate cycle. Only `.junie/AGENTS.md` closes that gate — the legacy `.junie/guidelines.md` does not, since Junie ranks it _below_ the multi-file branch and Rulesync never writes it, so nothing has been folded into it. In that legacy layout both branches are imported at once, so a `.junie/rules/overview.md` and the legacy root claim the same `.rulesync/rules/overview.md`; the root file wins, and the usual collision warning names the file that lost. Delete them once you have checked the fold, since Junie stops reading them the moment `.junie/AGENTS.md` exists. In that pre-`.junie/AGENTS.md` layout Junie's root file is the project-root `AGENTS.md`, which belongs to the `agentsmd` target. `rulesync import` takes one target at a time, so run `rulesync import --targets agentsmd` before `rulesync import --targets junie` if you want a root rule as well: a `junie`-only import of that layout yields non-root rules alone, and the next `generate` writes `.junie/AGENTS.md` — at which point Junie stops reading the project-root `AGENTS.md` whose content was never imported. The legacy `.junie/guidelines.md` is still accepted as an import fallback. Earlier Rulesync versions emitted non-root rules to `.junie/memories/*.md`, which is not a documented Junie read path; those files are no longer generated (stale outputs stay gitignored but are not cleaned up automatically). See the [Junie guidelines docs](https://junie.jetbrains.com/docs/guidelines-and-memory.html) and the [Junie IDE plugin docs](https://junie.jetbrains.com/docs/junie-ide-plugin.html) — the IDE plugin page is where the exclusivity sentence quoted above appears.\n\n> **Reasonix note:** Reasonix auto-injects a hierarchical instruction document, reading its vendor-specific `REASONIX.md` (alongside the cross-tool `AGENTS.md`/`CLAUDE.md`) by walking user-home → ancestors → project root/local. Rulesync writes the vendor `REASONIX.md` at the project root (project) / `~/.reasonix/REASONIX.md` (global, via `--global`) and folds non-root rules into that single file, since Reasonix has no modular rules directory. Directory-scoped rules are the exception: Context Engine v2 (v1.18.0) also walks from the workspace root to the target path loading per-directory instruction files (“Deeper directories beat broader directories”), so a non-root rule carrying `agentsmd.subprojectPath` is emitted as a nested `<subprojectPath>/REASONIX.md` (project scope only) instead of being folded — its paragraphs load only under that path rather than being carried on every turn. On **import**, nested `REASONIX.md` files are discovered by the same project scan the AGENTS.md standard uses (same dependency/build-directory exclusions; import-only, never removed by `--delete`) and land in `.rulesync/rules/<directory-with-hyphens>-reasonix.md` with `targets: [\"reasonix\"]` and the `subprojectPath` carried, so the next generate puts them back. The `-reasonix` suffix and the reasonix-only targeting keep them from clobbering the AGENTS.md standard's derived names or surprising other tools with new nested files; note that a rule targeting both `agentsmd` and `reasonix` with a `subprojectPath` produces a nested `AGENTS.md` **and** a nested `REASONIX.md` in the same directory, both of which Reasonix loads — scope such rules to one target. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md) and [Context Engine v2 docs](https://github.com/esengine/DeepSeek-Reasonix/blob/v1.18.0/docs/SESSION_MEMORY_RETRIEVAL.md).\n\n> **Vibe Code note:** Vibe reads the project-root `AGENTS.md` (project) / `~/.vibe/AGENTS.md` (global, via `--global`) and folds non-root rules into that single file, since it has no modular rules directory. Directory-scoped rules are the exception: Vibe's harness manager walks the directories between the workspace root and the file being read and loads every `AGENTS.md` it finds along the way (`find_subdirectory_agents_md`), injecting the result into the `read_file` tool's output since v2.19.1 — so a non-root rule carrying `agentsmd.subprojectPath` is emitted as a nested `<subprojectPath>/AGENTS.md` (project scope only) instead of being folded. On **import**, nested files are discovered by the same project scan the AGENTS.md standard uses (same dependency/build-directory exclusions; import-only, never removed by `--delete`). Unlike the Reasonix note above, the imported rule is **not** suffixed or target-scoped: Vibe's nested file is literally the AGENTS.md standard's own per-directory file at the same path, so it lands in `.rulesync/rules/<directory-with-hyphens>.md` with `targets: [\"*\"]` — importing the same file through `agentsmd` and `vibe` therefore yields one rulesync rule, not two copies that would fold duplicated content back into the same `AGENTS.md`. Because the emitted file is the plain per-directory `AGENTS.md`, a rule scoped with `targets: [\"vibe\"]` is still picked up by every other AGENTS.md reader working in that directory — Vibe's nested surface is the shared standard's file, so target-scoping it is structurally impossible. See [mistral-vibe](https://github.com/mistralai/mistral-vibe) (`vibe/core/config/harness_files/_harness_manager.py`).\n\n> **Meta Muse Code note:** Muse Code walks up from the working directory to the `.git` boundary and loads one instruction file per directory level, preferring `AGENTS.md` over `CLAUDE.md` when both exist. The `musecode` target writes the root rule to the shared project-root `AGENTS.md` (the same file `agentsmd`, `codexcli` and others write) and folds non-root rules into it, since Muse Code has no modular rules directory. Muse Code has user/global rules, but their path is not documented, so the `musecode` rules target is project-scope only. See the [Muse Code configuration docs](https://dev.meta.ai/docs/muse-code/configuration.md).\n\n> **ZCode note:** ZCode (Z.ai's agentic development environment for the GLM family) reads exactly two instruction files — the user-global `~/.zcode/AGENTS.md` and the workspace `AGENTS.md` at the project root — and appends them in that order. Its docs are explicit that it \"does not merge multiple `AGENTS.md` files across directory levels\" and \"does not scan child directories\", so there is no nested rules surface to emit: rulesync writes the project-root `AGENTS.md` (project) / `~/.zcode/AGENTS.md` (global, via `--global`) and folds non-root rules into that single file. `CLAUDE.md` is deliberately not written for `zcode`: ZCode reads it only once, during onboarding, as a migration source. See the [ZCode AGENTS.md docs](https://zcode.z.ai/en/docs/agents).\n\n## `.rulesync/hooks.jsonc`\n\n`.rulesync/hooks.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/hooks.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nHermes Agent accepts native snake-case events under `hermesagent.hooks`: `pre_tool_call`, `post_tool_call`, `transform_terminal_output`, `transform_tool_result`, `transform_llm_output`, `pre_llm_call`, `post_llm_call`, `on_stream_start`, `on_stream_delta`, `on_stream_end`, `on_interim_message`, `pre_verify`, `pre_api_request`, `post_api_request`, `api_request_error`, `on_session_start`, `on_session_end`, `on_session_finalize`, `on_session_reset`, `on_skill_lifecycle`, `subagent_start`, `subagent_stop`, `pre_gateway_dispatch`, `pre_approval_request`, `post_approval_response`, `pre_transcription`, `kanban_task_claimed`, `kanban_task_completed`, `kanban_task_blocked`, `on_kanban_worker_spawned`, `on_kanban_worker_exited`, `on_kanban_worker_stale_claim`, `on_kanban_task_updated`, `on_kanban_dispatch_tick`, `gateway_platform_event`, and `pre_command`. That is 36 of the 37 `VALID_HOOKS` entries at v0.20.2: `transform_api_error_classification` is subtracted by `SHELL_UNSUPPORTED_HOOKS`, because a shell hook cannot return its directive and Hermes refuses the registration — authoring it still emits the entry, with a warning saying it will never run. Rulesync maps shared canonical events first, applies canonical keys from `hermesagent.hooks` next, then applies exact native keys last. An exact native key therefore wins when both forms resolve to the same Hermes event. Native-only events remain under `hermesagent.hooks` on import instead of leaking into other targets. Rulesync owns the event keys inside the `hooks:` mapping of `config.yaml`, but not the mapping itself: Hermes v0.20.0 nests the [outbound webhook registry](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks) under the same key as `hooks.outbound`, so any key there that is not a Hermes hook event is carried over from the existing file untouched. Rulesync neither authors nor imports `outbound`, since it is a list of webhook targets rather than a hook event; it only makes sure a regenerate leaves it alone. An event key Rulesync did write, including one under an undocumented event name supplied through `hermesagent.hooks`, is still retracted when it disappears from the source.\n\nHooks run scripts at lifecycle events (e.g. session start, before tool use). Events use **canonical camelCase** in this file, and Rulesync translates them per tool: Cursor uses them as-is; Claude Code, Factory Droid, Codex CLI, Qwen Code, and Goose get PascalCase (with a few tool-specific name mappings) in their settings files; OpenCode and Kilo hooks are emitted as JavaScript plugins (`.opencode/plugins/rulesync-hooks.js`, `.kilo/plugins/rulesync-hooks.js`) — both share one event surface apart from `notification` (see below), in which `preToolUse`/`postToolUse` become named `tool.execute.before`/`tool.execute.after` hooks, `preCompact` becomes the named `experimental.session.compacting` hook and `beforeSubmitPrompt` the named `chat.message` hook (both receive `(input, output)` and expose nothing to match on, so a `matcher` on either is dropped), `beforeShellExecution`/`afterShellExecution` also land in those named `tool.execute.*` hooks with an implicit `input.tool === \"bash\"` gate — OpenCode has no shell-execution lifecycle event (`command.executed`, which earlier Rulesync versions mapped `afterShellExecution` to, is a _slash-command_ event, so the hook never fired on shell commands; regenerate to fix), and matchers on the shell events are dropped with a warning since the named hooks expose no command text, and the rest are `event.type` dispatches — `sessionStart` → `session.created`, `stop` → `session.idle`, `afterFileEdit` → `file.edited`, `permissionRequest` → `permission.asked`, `permissionDenied` → `permission.replied` (which fires for every reply, so the generated handler is gated on `event.properties.reply === \"reject\"`), `notification` → `tui.toast.show` (**OpenCode only** — Kilo's plugin docs document no TUI events, so `notification` is not part of its surface; note too that OpenCode's toast channel is broader than the canonical event, since every `info`/`success`/`warning`/`error` toast fires the hook rather than only the ones asking for your attention, and most toasts originate in the TUI client, so a headless `opencode run` rarely fires it at all), `postCompact` → `session.compacted`, `afterError` → `session.error`, `fileChanged` → `file.watcher.updated`; Amp hooks are emitted as a TypeScript plugin (`.amp/plugins/rulesync-hooks.ts`, or `~/.config/amp/plugins/rulesync-hooks.ts` in global mode) using `session.start`, `tool.call`, `tool.result`, `agent.start`, and `agent.end`; Pi Coding Agent hooks are emitted as a Rulesync-owned TypeScript extension (`.pi/extensions/rulesync-hooks.ts`, or `~/.pi/agent/extensions/rulesync-hooks.ts` in global mode) that subscribes to Pi's snake_case extension events (`sessionStart` → `session_start`, `stop` → `agent_end`, `preToolUse` → `tool_call` with the matcher tested as a regex against the tool name, `preCompact` → `session_before_compact`, `postCompact` → `session_compact`, `postModelInvocation` → `message_end` gated on assistant messages so it runs once per finalized model response, `beforeSubmitPrompt` → `input`) — `tool_call` is Pi's only tool gate, so a `preToolUse` command that exits non-zero denies the call with `{ block: true, reason }` (the reason is the command's stderr, falling back to its stdout and then to its exit code, with terminal escape sequences, control and C1 characters, and format characters such as bidirectional overrides and zero-width joiners stripped, carriage returns folded into newlines so the text cannot overwrite an already printed line, the sanitized result capped at 2000 characters (and only the first 128000 characters of the command's output scanned at all) — sanitizing first so a reason that opens with a progress banner is still reported by its content — and a generic `Hook command failed.` used when nothing survives), and `input` is its prompt-submission gate, so a `beforeSubmitPrompt` command that exits non-zero cancels the prompt with `{ action: \"handled\" }` — that result carries no reason field, so the same text is reported through `ctx.ui.notify`, falling back to stderr in print (`-p`) and JSON modes where that channel is a no-op; three limits are worth knowing before relying on the prompt gate: Pi checks extension slash commands before the `input` event, so input consumed as a `/cmd` never reaches the gate, messages another extension injects via `sendUserMessage` (`event.source === \"extension\"`) are deliberately passed through because the canonical event covers prompts the user submits, and the hook command receives no prompt text (Pi's `input` event exposes it, but the generated handler runs the command with no stdin or arguments, unlike Claude Code's `UserPromptSubmit`), so the gate can only decide from ambient state; a `matcher` on `beforeSubmitPrompt` is dropped, since `input` exposes no tool name to test it against; every other event, `postToolUse`/`tool_result` included, observes only and cannot block or mutate Pi events; a denied call deliberately leaves Pi's `terminate` flag unset so control returns to the model instead of ending the turn; Copilot and Copilot CLI map event names to their own camelCase (e.g. `beforeSubmitPrompt` → `userPromptSubmitted`, `stop` → `agentStop`, `afterError` → `errorOccurred`) and write the command into the `bash`/`powershell` field named by the canonical `shell` selector, or into the portable `command` field when none is set — Copilot CLI additionally covers a wider event set and supports `prompt` and `http` hook types beyond `command`; deepagents-cli gets the Hooks v2 PascalCase `HookEvent` names (e.g. `SessionStart`, `PostToolUseFailure`) in a `{ \"hooks\": { \"<Event>\": [{ \"matcher\": …, \"hooks\": [{ \"type\": \"command\", … }] }] } }` document — this requires deepagents-code 0.1.52+, the release where Hooks v2 became generally available (the legacy flat list is removed upstream on 2026-09-01; Rulesync still imports the legacy format but no longer writes it); `kiro-cli` and `kiro-ide` emit hooks into the standalone `.kiro/hooks/rulesync.json` with PascalCase triggers, while the deprecated `kiro` alias still writes them into `.kiro/agents/default.json` using the older event names (`agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop`); Qwen Code emits PascalCase events into the `hooks` key of `.qwen/settings.json` (its supported event set differs from Gemini CLI's).\n\nExample:\n\n```json\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"sessionStart\": [{ \"type\": \"command\", \"command\": \".rulesync/hooks/session-start.sh\" }],\n    \"preToolUse\": [{ \"matcher\": \"Bash\", \"command\": \".rulesync/hooks/confirm.sh\" }],\n    \"postToolUse\": [{ \"matcher\": \"Write|Edit\", \"command\": \".rulesync/hooks/format.sh\" }],\n    \"stop\": [{ \"command\": \".rulesync/hooks/audit.sh\" }]\n  },\n  \"cursor\": {\n    \"hooks\": {\n      \"afterFileEdit\": [{ \"command\": \".cursor/hooks/format.sh\" }]\n    }\n  },\n  \"claudecode\": {\n    \"hooks\": {\n      \"notification\": [\n        {\n          \"matcher\": \"permission_prompt\",\n          \"command\": \"$CLAUDE_PROJECT_DIR/.claude/hooks/notify.sh\"\n        }\n      ]\n    }\n  },\n  \"opencode\": {\n    \"hooks\": {\n      \"afterShellExecution\": [{ \"command\": \".rulesync/hooks/post-shell.sh\" }]\n    }\n  },\n  \"copilot\": {\n    \"hooks\": {\n      \"afterError\": [{ \"command\": \".rulesync/hooks/report-error.sh\" }]\n    }\n  }\n}\n```\n\n**Top-level keys:**\n\n- `version`: Schema version (currently `1`).\n- `hooks`: Map of canonical event names to an array of hook entries. These are dispatched to every tool that supports the given event.\n- `amp.hooks`, `cursor.hooks`, `claudecode.hooks`, `opencode.hooks`, `kilo.hooks`, `copilot.hooks`, `copilotcli.hooks`, `factorydroid.hooks`, `codexcli.hooks`, `goose.hooks`, `deepagents.hooks`, `kiro.hooks`, `qwencode.hooks`, `grokcli.hooks`: Tool-specific **override keys**. Entries under these keys are emitted only for the corresponding tool, so tool-only events (e.g. `afterFileEdit` for Cursor/OpenCode/Kilo, `worktreeCreate` for Claude Code, `afterError` for Copilot/Copilot CLI, `PostFileSave`/`PreTaskExec` for Kiro) can coexist with shared ones without leaking to other tools. `copilotcli.hooks` falls back to `copilot.hooks`, which in turn falls back to the shared `hooks` block.\n\n**Hook entry keys:**\n\n- `command` (required): Shell command to execute when the event fires.\n- `type` (optional): One of `\"command\"` (default), `\"prompt\"`, `\"http\"`, `\"agent\"`, `\"mcp_tool\"`, or `\"function\"` — the union of the hook types accepted across supported tools. Each tool supports a subset (most support only `command`); hooks with a type a tool does not support are skipped for that tool with a warning. See notes below.\n- `matcher` (optional): Regex used by tools that scope hooks to specific tool names (e.g. `preToolUse`, `postToolUse`, `notification`). Ignored by events that do not take a matcher (e.g. `sessionStart`, `worktreeCreate`, `worktreeRemove`).\n- `timeout` (optional): Per-hook timeout in seconds, forwarded to tools that support it.\n- `cacheTtl` (optional): Number of seconds to cache a successful hook result. Forwarded to the deprecated `kiro` alias's agent-config format as `cache_ttl_seconds`; `0` disables caching and Kiro never caches `AgentSpawn` hooks.\n- `failClosed` (optional): Boolean. When `true`, a hook failure (crash, timeout, invalid JSON) blocks the action instead of allowing it through. Passed through to Cursor's `.cursor/hooks.json`, to JetBrains Junie's `~/.junie/config.json` (as Junie's equivalently-named `blockOnError` flag), and to Hermes Agent's `~/.hermes/config.yaml` (as `fail_closed`). Hermes only honours it on `pre_tool_call`, its one blocking-capable event, so a `failClosed` set on any other canonical event is dropped with a warning.\n- `commandRegex` (optional): Regex applied to the shell command string, narrowing an `Execute` matcher group further (e.g. `\"^git \"`). Forwarded to Factory Droid, which skips invalid regex values. Like `matcher`, it belongs to the whole matcher group, so every hook sharing that matcher receives it.\n- `async` (optional): Boolean. When `true`, the hook command runs in the background without blocking. Forwarded to Qwen Code (`.qwen/settings.json`), JetBrains Junie (`~/.junie/config.json`, same field name), Claude Code and Codex CLI (`.codex/hooks.json`, same field name — Codex runs up to eight background hooks concurrently per session and queues the rest).\n- `env` (optional, `command` hooks): a map of extra environment variables merged into the hook process's environment. Forwarded to Qwen Code (`.qwen/settings.json`), Copilot CLI, and Grok CLI (`.grok/hooks/rulesync.json`, upstream `HookConfig.env`, merged into the spawned command's `extra_env`). Documented on command hooks only, so it is neither emitted on a hook of another type nor imported from one (a value found there is dropped with a warning). For Grok CLI, an entry whose key is empty or contains `=`, or whose key or value contains a newline, carriage return or NUL, is refused in both directions — the tool rebuilds each entry into a `KEY=VALUE` string, so such a key would name a different variable than it appears to.\n- `shell` (optional): Either `\"bash\"` or `\"powershell\"` — the only two interpreter values any tool accepts. Forwarded to Qwen Code, Claude Code, Copilot and Copilot CLI command hooks; for the two Copilot targets it names the `bash`/`powershell` field the command is written into, and leaving it unset selects their portable `command` field. Like `args`, `async` and `asyncRewake`, it is documented on command hooks only, so it is neither emitted on a hook of another type nor imported from one (a value found there is dropped with a warning).\n- `url` / `headers` / `allowedEnvVars` (optional, `http` hooks): the POST target URL, request headers (values support `$VAR` interpolation), and the env-var allowlist for that interpolation. Forwarded to Claude Code and Qwen Code http hooks.\n- `server` / `tool` / `input` (optional, `mcp_tool` hooks): the configured MCP server name, the tool to call on it, and the (arbitrary JSON) arguments, whose string values support `${path}` substitution from the hook input. Forwarded to Claude Code mcp_tool hooks.\n- `model` (optional, `prompt` / `agent` hooks): the model used for evaluation (defaults to a fast model). Forwarded to Claude Code prompt/agent hooks and to Qwen Code prompt hooks.\n- `args` (optional, `command` hooks): an argument list. When present — an empty list counts, and is the form the Claude Code docs use — the tool spawns `command` directly as an executable with these arguments. There is no shell, so Rulesync writes the project-directory prefix as the braced placeholder `${CLAUDE_PROJECT_DIR}/…` that Claude Code substitutes itself, rather than the quoted shell form. Forwarded to Claude Code and AugmentCode. Only `command` is prefixed; entries of `args` are passed through exactly as written.\n- `asyncRewake` (optional): boolean. Like `async`, but wakes Claude when the hook exits with code 2. Forwarded to Claude Code command hooks.\n- `once` (optional): boolean. Run the hook once per session, then remove it. Forwarded to Claude Code (honored in skill frontmatter; accepted but ignored in settings files) and Qwen Code http hooks.\n- `continueOnBlock` (optional): boolean. Feed a blocking hook's rejection reason back to the model and continue the turn instead of ending it. Forwarded to Claude Code.\n- `commandWindows` (optional): a Windows-only override for `command`, so one hook set can be cross-platform. Forwarded to Codex CLI command hooks (`.codex/hooks.json`), which is the only tool that accepts it.\n- `additionalContextLimit` (optional): a non-negative integer. The token threshold above which the tool writes the hook's additional context to a file and passes that path instead of the text itself (upstream default 2500). Forwarded to Codex CLI command hooks (`.codex/hooks.json`), which is the only tool that accepts it.\n- `statusMessage` (optional): the progress text shown while the hook runs. Forwarded to Qwen Code (command and http hooks) and to Codex CLI command hooks.\n- `enabled` (optional): boolean, default `true`. Whether the hook is active. Forwarded to Kiro's standalone hooks file (`.kiro/hooks/rulesync.json`, written by the `kiro-cli` and `kiro-ide` targets), the only place with a per-hook on-disk enable flag Rulesync writes; an imported `enabled: false` round-trips, so a deliberately disabled hook is not silently switched back on by the next generate. Every other target has no way to express it, so the hook is emitted there as an ordinary **active** hook and a warning is logged at generate time — to turn a hook off everywhere, remove it rather than setting `enabled: false`. (Antigravity has an `enabled` flag of its own, but on the named hook group rather than the individual definition, so it is not driven by this field.)\n- `if` (optional): a single permission rule (same syntax as `settings.json` permission rules, e.g. `\"Bash(rm *)\"`) that filters a hook by tool arguments in addition to the tool name. Forwarded to Claude Code, where it is evaluated only on tool events (`preToolUse`, `postToolUse`, `postToolUseFailure`, `permissionRequest`, `permissionDenied`); it round-trips as an opaque string.\n\nA field a tool documents on `command` hooks only (`args`, `env`, `shell`, `async`, `asyncRewake`) is dropped with a warning in both directions when it appears on a hook of another type — on generate for a value authored in `.rulesync/hooks.*`, and on import for one found in an existing tool config. Import additionally checks each value against the constraint the canonical field declares (e.g. `shell` must be `\"bash\"` or `\"powershell\"`, `additionalContextLimit` must be a non-negative integer, and no string field may carry a newline, carriage return or NUL); a value that fails is skipped with a warning naming the constraint, rather than imported into a file the next generate would refuse to read. When the offending value is a `command`, `prompt` or `matcher`, the whole hook is skipped instead of just that field, since a hook without its command runs nothing and a hook without its matcher fires on everything.\n\nTop-level `hooks` keys must be canonical event names; unknown event names are rejected at parse time. Tool-specific override blocks (e.g. `kiro.hooks`) additionally accept tool-native event keys, which pass through verbatim.\n\nEvents present in the shared `hooks` block but unsupported by a given tool are skipped for that tool (a warning is logged at generate time). The canonical `notification` event maps to deepagents-cli's Hooks v2 `Notification` event, whose matcher selects the notification kind (e.g. `agent_needs_input`); canonical `contextOffload` is skipped for deepagents-cli, since its legacy `context.offload` event has no Hooks v2 counterpart.\n\n### Hook event × tool matrix\n\n<!-- HOOK_EVENTS_MATRIX:BEGIN -->\n\n| Event                  | Amp | Claude Code | Claude Code plugin | Codex CLI | GitHub Copilot | GitHub Copilot CLI | Goose | Hermes Agent | Grok CLI | Cursor | deepagents-cli | Factory Droid | OpenCode | Cline | Kilo Code | Kimi Code | Vibe Code | Qwen Code | Reasonix | Kiro ⚠️ | Kiro CLI | Kiro IDE | Google Antigravity IDE | Google Antigravity CLI | Google Antigravity plugin | JetBrains Junie | AugmentCode | Devin Desktop | Pi Coding Agent |\n| ---------------------- | :-: | :---------: | :----------------: | :-------: | :------------: | :----------------: | :---: | :----------: | :------: | :----: | :------------: | :-----------: | :------: | :---: | :-------: | :-------: | :-------: | :-------: | :------: | :-----: | :------: | :------: | :--------------------: | :--------------------: | :-----------------------: | :-------------: | :---------: | :-----------: | :-------------: |\n| `sessionStart`         | ✅  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      ✅      |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |  ✅   |    ✅     |    ✅     |     —     |    ✅     |    ✅    |   ✅    |    ✅    |    ✅    |           —            |           —            |             —             |       ✅        |     ✅      |      ✅       |       ✅        |\n| `sessionEnd`           |  —  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      ✅      |    ✅    |   ✅   |       ✅       |      ✅       |    —     |  ✅   |     —     |    ✅     |     —     |    ✅     |    ✅    |   ✅    |    —     |    —     |           —            |           —            |             —             |       ✅        |     ✅      |      ✅       |       ✅        |\n| `preToolUse`           | ✅  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      ✅      |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |  ✅   |    ✅     |    ✅     |    ✅     |    ✅     |    ✅    |   ✅    |    ✅    |    ✅    |           ✅           |           ✅           |            ✅             |       ✅        |     ✅      |      ✅       |       ✅        |\n| `postToolUse`          | ✅  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      ✅      |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |  ✅   |    ✅     |    ✅     |    ✅     |    ✅     |    ✅    |   ✅    |    ✅    |    ✅    |           ✅           |           ✅           |            ✅             |        —        |     ✅      |      ✅       |       ✅        |\n| `preModelInvocation`   |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      ✅      |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           ✅           |           ✅           |            ✅             |        —        |      —      |       —       |       ✅        |\n| `postModelInvocation`  |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      ✅      |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    ✅    |    —    |    —     |    —     |           ✅           |           ✅           |            ✅             |        —        |      —      |       —       |       ✅        |\n| `beforeSubmitPrompt`   | ✅  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      —       |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |  ✅   |    ✅     |    ✅     |     —     |    ✅     |    ✅    |   ✅    |    ✅    |    ✅    |           —            |           —            |             —             |       ✅        |     ✅      |      ✅       |       ✅        |\n| `stop`                 | ✅  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      —       |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |   —   |    ✅     |    ✅     |    ✅     |    ✅     |    ✅    |   ✅    |    ✅    |    ✅    |           ✅           |           ✅           |            ✅             |       ✅        |     ✅      |      ✅       |       ✅        |\n| `subagentStop`         |  —  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |   —   |      ✅      |    ✅    |   ✅   |       ✅       |      ✅       |    —     |   —   |     —     |    ✅     |     —     |    ✅     |    ✅    |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `preCompact`           |  —  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |   —   |      —       |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |  ✅   |    ✅     |    ✅     |     —     |    ✅     |    ✅    |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |       ✅        |\n| `postCompact`          |  —  |     ✅      |         ✅         |    ✅     |       —        |         —          |   —   |      —       |    ✅    |   —    |       —        |       —       |    ✅    |   —   |    ✅     |    ✅     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |      ✅       |       ✅        |\n| `postToolUseFailure`   |  —  |     ✅      |         ✅         |     —     |       ✅       |         ✅         |  ✅   |      —       |    ✅    |   ✅   |       ✅       |       —       |    —     |   —   |     —     |    ✅     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `subagentStart`        |  —  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |   —   |      ✅      |    ✅    |   ✅   |       ✅       |       —       |    —     |   —   |     —     |    ✅     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `beforeShellExecution` |  —  |      —      |         —          |     —     |       —        |         —          |  ✅   |      —       |    —     |   ✅   |       —        |       —       |    ✅    |   —   |    ✅     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterShellExecution`  |  —  |      —      |         —          |     —     |       —        |         —          |  ✅   |      —       |    —     |   ✅   |       —        |       —       |    ✅    |   —   |    ✅     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `beforeMCPExecution`   |  —  |      —      |         —          |     —     |       —        |         ✅         |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterMCPExecution`    |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `beforeReadFile`       |  —  |      —      |         —          |     —     |       —        |         —          |  ✅   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterFileEdit`        |  —  |      —      |         —          |     —     |       —        |         —          |  ✅   |      —       |    —     |   ✅   |       —        |       —       |    ✅    |   —   |    ✅     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterAgentResponse`   |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterAgentThought`    |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `beforeTabFileRead`    |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterTabFileEdit`     |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `permissionRequest`    |  —  |     ✅      |         ✅         |    ✅     |       —        |         ✅         |   —   |      —       |    —     |   —    |       ✅       |       —       |    ✅    |   —   |    ✅     |    ✅     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |       ✅        |      —      |      ✅       |        —        |\n| `notification`         |  —  |     ✅      |         ✅         |     —     |       —        |         ✅         |   —   |      —       |    ✅    |   —    |       ✅       |      ✅       |    ✅    |  ✅   |     —     |    ✅     |     —     |    ✅     |    ✅    |    —    |    —     |    —     |           —            |           —            |             —             |        —        |     ✅      |       —       |        —        |\n| `setup`                |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterError`           |  —  |      —      |         —          |     —     |       ✅       |         ✅         |   —   |      —       |    —     |   —    |       —        |       —       |    ✅    |  ✅   |    ✅     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `worktreeCreate`       |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `worktreeRemove`       |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `workspaceOpen`        |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `messageDisplay`       |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `todoCreated`          |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `todoCompleted`        |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `stopFailure`          |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    ✅    |   —    |       —        |       —       |    —     |   —   |     —     |    ✅     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |       ✅        |      —      |       —       |        —        |\n| `stopCancelled`        |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    ✅    |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `instructionsLoaded`   |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `userPromptExpansion`  |  —  |     ✅      |         ✅         |     —     |       ✅       |         ✅         |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `postToolBatch`        |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `permissionDenied`     |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    ✅    |   —    |       —        |       —       |    ✅    |   —   |    ✅     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `taskCreated`          |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `taskCompleted`        |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |  ✅   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `teammateIdle`         |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `configChange`         |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `cwdChanged`           |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `fileChanged`          |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    ✅    |   —   |    ✅     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `directoryAdded`       |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `elicitation`          |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `elicitationResult`    |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `sessionDelete`        |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n\n<!-- HOOK_EVENTS_MATRIX:END -->\n\n> **Note:** `beforeSubmitPrompt`, `stop`, `worktreeCreate`, `worktreeRemove`, `messageDisplay`, `postToolBatch`, `taskCreated`, `taskCompleted`, `teammateIdle`, and `cwdChanged` are the Claude Code events the [matcher table](https://code.claude.com/docs/en/hooks) lists as not supporting the `matcher` field (they fire on every occurrence). A matcher authored on one of them is dropped with a warning rather than written into `settings.json` to be ignored. `directoryAdded` is **not** one of them: the matcher table documents it as filtering on how the directory was added (`slash_command`, `register_repo_root`), so a matcher written on it is emitted as-is.\n\n> **Note:** Rulesync implements OpenCode hooks as a plugin at `.opencode/plugins/rulesync-hooks.js` and Kilo hooks as a plugin at `.kilo/plugins/rulesync-hooks.js`, so importing from OpenCode/Kilo to rulesync is not supported. Both only support command-type hooks (not prompt-type).\n\n> **Note:** Rulesync implements Amp hooks as a generated TypeScript plugin at `.amp/plugins/rulesync-hooks.ts` (project) or `~/.config/amp/plugins/rulesync-hooks.ts` (global), so importing arbitrary Amp plugin code is not supported. Amp supports command hooks for `sessionStart` → `session.start`, `preToolUse` → `tool.call`, `postToolUse` → `tool.result`, `beforeSubmitPrompt` → `agent.start`, and `stop` → `agent.end`. Tool-event matchers are regular expressions against the Amp tool name; definitions with a matcher on any lifecycle event are skipped with a warning. A failing `preToolUse` command rejects the tool call and lets the agent continue; other mapped events observe the command result.\n\n> **Amp command syntax:** Amp executes plugin commands with [Bun Shell](https://bun.com/docs/runtime/shell), whose syntax differs slightly from POSIX shells. Use `$VAR` for environment expansion (`${VAR}` remains literal) and `$(command)` for command substitution (backticks remain literal). Rulesync passes the authored command through unchanged so quoting and escaped operators retain their Bun Shell meaning.\n\n> **Note:** GitHub Copilot's format uses separate `powershell` and `bash` fields for hooks, plus a portable `command` field that upstream copies into both when neither is present. Rulesync picks between them with the canonical `shell` selector, and writes the portable `command` field when a hook does not set one. Earlier versions chose the field from the platform Rulesync happened to run on; regenerate to get a machine-independent file.\n\n> **Note:** Hook file paths per tool:\n>\n> - **Copilot (cloud agent / VS Code)** — project: `<project>/.github/hooks/copilot-hooks.json`; global: `~/.copilot/hooks/copilot-ide-hooks.json`. Command hooks carry `bash`/`powershell` with optional `timeoutSec`, plus the canonical `env` map and a pass-through `cwd`. On import, `timeout` is honored as an alias for `timeoutSec` when `timeoutSec` is absent. Which command field is written is chosen by the canonical `shell` selector; without it the portable `command` field is written, which upstream copies to both. It is deliberately **not** chosen from the platform Rulesync runs on: the cloud agent runs hooks in a **Linux sandbox** where only `bash` and `command` are honored, so a `powershell` entry generated on a Windows machine would simply never run. It also keeps the output identical everywhere, which matters because the cloud agent reads this file from the repository. For the same reason, an imported entry carrying both fields resolves to `bash` (with a warning) on every platform. VS Code and the coding agent both document `~/.copilot/hooks` as the user scope and load every `*.json` in that folder; the Copilot CLI's global file already occupies `copilot-hooks.json` there, so the VS Code target uses a distinct filename and the two never overwrite each other. Note the flip side of \"every `*.json` is loaded\": generating **both** `copilot` and `copilotcli` in global mode leaves two files in that one folder, and a reader of the folder runs the hooks from both — so a command present in your canonical config fires twice per event. Generate only one of the two globally unless you want that.\n> - **Copilot CLI** — project: `<project>/.github/hooks/copilotcli-hooks.json`; global: `~/.copilot/hooks/copilot-hooks.json`. The Copilot CLI docs let you choose any filename inside `.github/hooks/`, so Rulesync uses the CLI-specific name to avoid colliding with the cloud-agent file when both targets are enabled. The global path is a Rulesync convention; the official Copilot CLI documentation does not currently enumerate a global hooks location, so this placement may change if the spec later mandates an alternate layout. Copilot CLI uses a **wider event surface** than the shared cloud-agent set (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `agentStop` ← `stop`, `subagentStart`, `subagentStop`, `errorOccurred` ← `afterError`, `preCompact`, `permissionRequest`, `notification`, `userPromptTransformed` ← `userPromptExpansion`, `preMcpToolCall` ← `beforeMCPExecution`) and supports three hook types: **`command`** (`bash`/`powershell` with optional `timeoutSec`, plus pass-through `cwd`/`env`; on import the portable `command` field is read as the cross-platform fallback when neither shell field is present, and `timeout` is honored as an alias for `timeoutSec` when `timeoutSec` is absent. On generate the canonical `shell` selector chooses `bash` or `powershell`; without it the portable `command` field is written, so the generated file does not depend on the machine Rulesync ran on. An imported entry carrying both shell fields resolves to `bash` (with a warning) on every platform, so importing the same file yields the same canonical config everywhere), **`prompt`** (a `prompt` string — Copilot CLI only honors prompt hooks on `sessionStart`, so prompt hooks on other events are dropped), and **`http`** (`url`/`headers`/`allowedEnvVars` with optional `timeoutSec`). An entry's optional `matcher` field is emitted and round-tripped on the six events the hooks reference documents as matcher-aware — `preToolUse` and `postToolUse` (regex on the tool name), `permissionRequest` (tool name), `notification` (notification type), `preCompact` (the trigger, `manual` or `auto`) and `subagentStart` (agent name); on any other event a matcher is dropped with a warning because the CLI does not honor it there. See the [hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference).\n> - **Antigravity IDE / Antigravity CLI** — project: `<project>/.agents/hooks.json`; global: `~/.gemini/config/hooks.json`. Both targets share the same dedicated `hooks.json` (a Claude-Code-style matcher map nested under a generated `rulesync` hook name), so enabling both writes the same file.\n> - **Devin Desktop (formerly Windsurf)** — project: `<project>/.windsurf/hooks.json`; global: `~/.codeium/windsurf/hooks.json`. The Cascade Hooks file location is unchanged by the Devin Desktop rebrand.\n> - **Factory Droid** — project: `<project>/.factory/hooks.json`; global: `~/.factory/hooks.json`. A standalone `hooks.json` is keyed **directly by event name** (`{\"PreToolUse\": [...]}`); the `hooks` wrapper Droid documents belongs to `settings.json` only, so Rulesync writes the bare event map. The file is Rulesync-owned and rewritten wholesale, which also repairs a `hooks.json` an earlier version left in the wrapped shape — Droid found no known event key at the top level of that file, so none of those hooks ever fired; regenerate to fix. Import accepts both shapes: the top level when it names an event, and the `hooks` key otherwise, which is also how the legacy `.factory/settings.json` read-time fallback is understood. Import falls back in order: `.factory/hooks.json`, then the `.factory/settings.json` `hooks` key (with `.factory/settings.local.json` overlaid, since Droid reads the pair as one) when those settings actually carry a `hooks` key — an unrelated `settings.local.json` therefore does not shadow the next step — then the pre-1.0 `.factory/hooks/hooks.json` — last because Droid renames that file to `hooks.migrated.json` once it has migrated it, so a copy still sitting there is the least likely to be live. Only `.factory/hooks.json` is ever written. As with permissions below, a hook that came from the machine-local file is imported into `.rulesync/hooks.json` like any other, so the next `generate` writes it into the committed hooks files of every targeted tool — and a hook carries a command someone else's machine would then run. Drop a personal hook from `.rulesync/hooks.json` after importing if it should stay personal. Whatever the local file contributed is named in a warning while importing, so a personal value is visible before it is committed; a key that governs what the tool may run — a sandbox tier, an autonomy ceiling, the hooks it executes — is called out on its own, since publishing one machine's relaxed value makes it the team's.\n> - **AugmentCode** — project: `<project>/.augment/settings.json`; global: `~/.augment/settings.json`. Hooks are merged under the top-level `hooks` key of the shared settings file (which also holds `toolPermissions`).\n> - **Kimi Code** — global only: `~/.kimi-code/config.toml`. Hooks are merged into the shared `[[hooks]]` array without replacing unrelated model, provider, or permission settings.\n> - **Vibe Code** — project: `<project>/.vibe/hooks.toml`; global: `~/.vibe/hooks.toml`. Stable since v2.21.0, which removed the `enable_experimental_hooks` flag: declaring a hook is enough, so Rulesync writes nothing into `.vibe/config.toml` for hooks.\n\n> **Note:** Because each AI tool evolves its own hook surface at its own pace, the matrix above reflects the events Rulesync currently translates. When a tool ships a new event that Rulesync does not yet support, the most reliable path is to open an issue — the matrix is the intended baseline to compare against.\n\n> **Note:** Kiro has two hook formats, and the target you pick decides which one you get. The **`kiro-cli`** and **`kiro-ide`** targets write the standalone `{ \"version\": \"v1\", \"hooks\": [ … ] }` file that both products read today — `.kiro/hooks/rulesync.json` in project scope and `~/.kiro/hooks/rulesync.json` in user scope — with one array entry per hook carrying `name`, `trigger`, an optional `matcher`, an `action` (`{ \"type\": \"command\", \"command\": … }` for a canonical `command` hook, `{ \"type\": \"agent\", \"prompt\": … }` for a `prompt` hook), an optional `timeout` in seconds, and `enabled`. Triggers are PascalCase (`sessionStart` ⇄ `SessionStart`, `stop` ⇄ `Stop`, …); triggers with no canonical event, such as `PostFileSave` or `PreTaskExec`, are reachable through the **shared `kiro.hooks` override block** and pass through verbatim. Both targets write the same filename, so they read that one block rather than per-target `kiro-cli.hooks` / `kiro-ide.hooks` blocks — otherwise a divergent override would make the file's content depend on which target was generated last. Generating either or both targets therefore always yields the same file. A block authored under `kiro-cli.hooks` or `kiro-ide.hooks` is read by nothing and reported with a warning; move it to `kiro.hooks` (the same key the deprecated `kiro` alias, and the Kiro MCP and permissions wiring, already use). A second filename would not help either, since Kiro runs every `*.json` in the directory and both products read the same one. The deprecated `kiro` alias reads the same block but writes a different format, so the two writers each keep to their own vocabulary: a standalone-only trigger (`PostFileSave`, `PreTaskExec`, …) in `kiro.hooks` is dropped from the alias's `.kiro/agents/default.json` output with a warning, and an agent-config spelling (`agentSpawn`, `fileEdited`, …) is translated to its v1 equivalent (`SessionStart`, `PostFileSave`) for the standalone targets rather than written as a trigger Kiro does not define. Keys neither writer recognizes still pass through unchanged.\n>\n> The deprecated **`kiro`** alias still writes the older embedded format: `.kiro/agents/default.json` under the `hooks` field, merged with any existing agent configuration (tools, allowedTools, etc.). There, both `sessionEnd` and `stop` map to Kiro's `stop` event, only `command`-type hooks are supported (`prompt`-type hooks are silently skipped), per-hook timeouts are `timeout_ms` (milliseconds), and `cache_ttl_seconds` maps to the canonical `cacheTtl` field in both directions. Kiro's [hooks migration guide](https://kiro.dev/docs/cli/v3/hooks-migration/) states this format \"does not work in 3.0\", so prefer `kiro-cli`.\n>\n> If you generated `kiro-cli` hooks with an earlier Rulesync version, the `hooks` block it left in `.kiro/agents/default.json` is not removed for you — that file is shared with the permissions and subagents features, so Rulesync never deletes it. On Kiro CLI 2.x, which reads both formats, leaving it in place means every hook fires twice; delete the block by hand (or run Kiro's own agent migration) after regenerating. For the same reason, `rulesync import --targets kiro-cli --features hooks` now reads only the standalone file: to pull hooks out of an existing agent config, import with `--targets kiro`. Two event-surface differences come with the switch as well: Kiro's standalone triggers have no `SessionEnd`, so a canonical `sessionEnd` hook is dropped with a warning — use `stop` instead — and `cacheTtl` has no counterpart outside the agent-config format.\n\n> **Note:** Antigravity (IDE and CLI) writes a dedicated `hooks.json` keyed by a **named hook** whose value holds the event map, e.g. `{ \"rulesync\": { \"PreToolUse\": [ { \"matcher\": \"...\", \"hooks\": [...] } ], \"Stop\": [ { \"hooks\": [...] } ] } }`. Rulesync emits a single generated hook under the stable name `rulesync`. It supports five lifecycle events — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `preModelInvocation` ⇄ `PreInvocation`, `postModelInvocation` ⇄ `PostInvocation`, and `stop` ⇄ `Stop` — where `PreInvocation`/`PostInvocation`/`Stop` are matcher-less handler lists. On import, both the named-hook wrapper and a legacy flat top-level event map are accepted, and the optional per-hook `enabled` flag is ignored.\n\n> **Note:** Devin Desktop (formerly Windsurf) Cascade Hooks (GA) are written to a dedicated `hooks.json` whose top-level `hooks` key maps each Cascade event name to a **flat array** of hook objects (no `matcher`, no `type`, no inner `hooks` wrapper, and no `timeout`). Each object carries `command` and/or `powershell`, plus optional `show_output` and `working_directory`. Rulesync splits the generic tool lifecycle into Devin's file/command/MCP-specific events, so the canonical events map bijectively: `beforeReadFile` ⇄ `pre_read_code`, `beforeTabFileRead` ⇄ `post_read_code`, `afterTabFileEdit` ⇄ `pre_write_code`, `afterFileEdit` ⇄ `post_write_code`, `beforeShellExecution` ⇄ `pre_run_command`, `afterShellExecution` ⇄ `post_run_command`, `beforeMCPExecution` ⇄ `pre_mcp_tool_use`, `afterMCPExecution` ⇄ `post_mcp_tool_use`, `beforeSubmitPrompt` ⇄ `pre_user_prompt`, `afterAgentResponse` ⇄ `post_cascade_response`, `beforeAgentResponse` ⇄ `post_cascade_response_with_transcript`, and `worktreeCreate` ⇄ `post_setup_worktree`. Canonical events with no Devin equivalent (e.g. `sessionStart`, `stop`) are dropped with a logged warning. The Cascade Hooks file location (`.windsurf/hooks.json` / `~/.codeium/windsurf/hooks.json`) is retained from the Windsurf era and is unaffected by the rebrand.\n\n> **Note:** AugmentCode (Auggie CLI) hooks are merged under the top-level `hooks` key of the shared `.augment/settings.json` (project) / `~/.augment/settings.json` (global), mirroring Claude Code's per-event matcher arrays (`{ \"EventName\": [ { \"matcher\": \"...\", \"hooks\": [ { \"type\": \"command\", \"command\": \"...\", \"timeout\": ... } ] } ] }`). The `hooks` block is merged in place so it coexists with the `toolPermissions` block from the permissions feature. Seven lifecycle events are supported — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `stop` ⇄ `Stop`, `notification` ⇄ `Notification`, and `beforeSubmitPrompt` ⇄ `PromptSubmit` (added in Auggie 0.27.0). The `matcher` field (a case-sensitive regex, default `.*`, with `mcp:*` support) applies only to the tool events `PreToolUse`/`PostToolUse`; any matcher on the session events (including `Notification` and `PromptSubmit`) is dropped with a logged warning. Two Auggie-specific fields round-trip as well: a command hook's `args` (extra argv the runner appends, authored as `args` on the canonical hook) and the matcher group's `metadata` (`includeConversationData` / `includeMCPMetadata` / `includeUserContext`, which select what the runner puts in the JSON payload the script receives). `metadata` belongs to the group upstream, so it is authored on any hook of the group and re-applied to every hook of that group on import. Both matter because the `hooks` key is owned in the shared settings file: a value not written here is erased from a hand-written `settings.json` on the next generate. Commands are emitted verbatim — Auggie exposes `AUGMENT_PROJECT_DIR` as a runtime environment variable, not as an inline command substitution, so no directory prefix is added. Only `command`-type hooks are supported. On **import** (project scope), Rulesync also reads the layered overrides file `<workspace>/.augment/settings.local.json` — a gitignored, machine-specific file that Auggie merges on top of `settings.json` — and combines it over the base settings before importing, following Auggie's documented layering (simple values take the local override, `mcpServers`/`plugins` replace wholesale, and other objects/lists — including the `hooks` events — are combined across tiers), so personal hook overrides are picked up without dropping base events. This overlay is **import-only and project-only**: Rulesync never writes `settings.local.json`, AugmentCode documents no global `~/.augment/settings.local.json`, so the overlay is skipped in global mode. Whatever the local file contributed is named in a warning while importing, so a personal value is visible before it is committed; a key that governs what the tool may run — a sandbox tier, an autonomy ceiling, the hooks it executes — is called out on its own, since publishing one machine's relaxed value makes it the team's.\n\n> **Note:** Vibe Code (mistral-vibe) hooks are written to a dedicated `.vibe/hooks.toml` (project) / `~/.vibe/hooks.toml` (global) as a flat `[[hooks]]` TOML array. Each entry carries its own event `type`, a `command`, and optional `name`, `timeout` (seconds, default 60), and `description`. Tool-hook entries (`pre_tool` / `post_tool`) additionally carry a tool-name `match` (an fnmatch glob like `bash`/`mcp_*` or a `re:`-prefixed regex, case-insensitive — the canonical `matcher` field; `*` means \"any tool\") and an optional `strict` flag; `post_agent` carries neither. Three events are supported — `preToolUse` ⇄ `pre_tool`, `postToolUse` ⇄ `post_tool`, and `stop` ⇄ `post_agent` (fires after every assistant turn that ends without pending tool calls). Only `command`-type hooks are emitted. Vibe v2.21.0 graduated hooks from experimental: it renamed all three types (`before_tool` → `pre_tool`, `after_tool` → `post_tool`, `post_agent_turn` → `post_agent`) and removed the `enable_experimental_hooks` flag, so declaring a hook is enough and Rulesync no longer writes an auxiliary `.vibe/config.toml`. `HookType` is a strict enum upstream, so an entry using an old name is rejected outright. Import still reads the three old spellings, so a `hooks.toml` left behind from before the rename is repaired into the current names rather than being lost.\n\n> **Cline note (hooks):** Cline's file-based hooks are executables, not a config file: it resolves one script per lifecycle event from `<project>/.clinerules/hooks/` (project) or `~/Documents/Cline/Hooks/` (global, via `--global`), named exactly after the event — the extensionless name on Unix, `<Event>.ps1` on Windows. Rulesync emits a wrapper script per configured event in **both** spellings (the POSIX one with mode `0755`, since Cline spawns the file itself), plus a `rulesync-hooks.json` manifest listing the scripts it owns. The wrapper feeds the event payload it receives on stdin to each configured command in order and answers on stdout with `{\"cancel\": …, \"contextModification\": \"\", \"errorMessage\": …}`: a command exiting `2` cancels the task, any other non-zero exit is surfaced through `errorMessage` without cancelling. Nine canonical events map onto Cline's fixed script names — `sessionStart` → `TaskStart`, `sessionEnd` → `SessionShutdown`, `beforeSubmitPrompt` → `UserPromptSubmit`, `preToolUse` → `PreToolUse`, `postToolUse` → `PostToolUse`, `preCompact` → `PreCompact`, `notification` → `Notification`, `taskCompleted` → `TaskComplete`, `afterError` → `TaskError`. That set is the union of the two runtimes reading the same directory: the VS Code extension's `VALID_HOOK_TYPES` and the SDK/CLI's `HookConfigFileName`, which drops `Notification` but adds `TaskError` and `SessionShutdown`. A script named for an event the running runtime does not know is simply never spawned. That applies to unknown _names_ only: for an event it does know, the SDK/CLI runtime spawns **both** spellings, because it lists hook files per path rather than per event. Each generated script therefore opens with a guard that stands down on the platform the other one owns — the `.ps1` is a no-op off Windows, and the extensionless script is a no-op on Windows. Both are needed: off Windows the runtime runs the `.ps1` through `pwsh`, and on Windows it infers the extensionless file's interpreter from its `#!/bin/bash` shebang and normalizes it to a bare `bash`, so with Git Bash on `PATH` the two spellings **both execute your commands** — a genuine double fire. (The Unix side was noise rather than duplication: the `.ps1` body shells out through `cmd /c`, which Unix does not have, so it failed on every fire instead.) The PowerShell guard tests that `$IsWindows` is both defined and false, since it does not exist at all in the Windows PowerShell 5.1 that `powershell -File` starts; the POSIX guard matches `$OSTYPE`/`uname` against the `msys`/`cygwin`/`mingw` family. Cline's `TaskResume` and `TaskCancel` have no canonical counterpart and are left unmapped; only `command`-type hooks are supported, and `matcher` is ignored because the wrapper is a plain shell script with no payload parser. Each command is passed to `bash -c` as a single quoted argument, so its own quotes and operators cannot break the wrapper; a command that is not valid shell syntax is reported through `errorMessage` instead of cancelling (an unparseable command would otherwise exit `2`). Note that the same command string runs under `bash` on Unix and `cmd /c` on Windows, so shell-specific syntax is not portable across the two generated spellings. Three caveats on ownership: the hooks directory is also where you hand-author your own hooks and the filenames are fixed by Cline, so every generated script carries a `rulesync-owned: cline-hooks` marker line and a script **without** that marker is never overwritten (that event is then not managed by Rulesync, and generate warns about it); a script whose event you remove is rewritten as a no-op rather than deleted, while dropping the `cline` target with `--delete` removes the marked scripts outright; and `rulesync gitignore` lists the generated script names explicitly rather than the whole directory, so a hand-authored hook sharing one of those names needs a negation in your own `.gitignore` if you want to commit it. Generated scripts cannot be imported back into canonical hooks, so this target is generate-only. Cline's in-process hook surface (`AgentHooks` from `@cline/core`) is a separate mechanism that Rulesync does not target. See [`VALID_HOOK_TYPES`](https://github.com/cline/cline/blob/main/apps/vscode/src/core/hooks/utils.ts) and [`HookConfigFileName`](https://github.com/cline/cline/blob/main/sdk/packages/core/src/hooks/hook-file-config.ts) in the Cline source.\n\n> **Note:** Goose hooks follow the Open Plugins spec: Rulesync writes a plugin directory `hooks/hooks.json` that Goose auto-discovers at startup. Locations are `<project>/.agents/plugins/rulesync/hooks/hooks.json` (project) and `~/.agents/plugins/rulesync/hooks/hooks.json` (global). The JSON shape matches Claude Code's (`{ \"hooks\": { \"EventName\": [ { \"matcher\": \"...\", \"hooks\": [ { \"type\": \"command\", \"command\": \"...\" } ] } ] } }`). Eleven lifecycle events are supported — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `stop` ⇄ `Stop`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `beforeReadFile` ⇄ `BeforeReadFile`, `afterFileEdit` ⇄ `AfterFileEdit`, `beforeShellExecution` ⇄ `BeforeShellExecution`, and `afterShellExecution` ⇄ `AfterShellExecution` — matching Goose's `HookEvent` enum exactly (it has no `SubagentStart`/`SubagentStop`). The `matcher` regex is preserved, commands are emitted verbatim (Goose exposes `PLUGIN_ROOT` as a runtime environment variable), and only `command`-type hooks are supported. One exception applies to the matcher: Goose compiles it with `Regex::new` and **silently drops the whole rule** when compilation fails, and the canonical catch-all `\"*\"` is not a valid regex, so it is emitted as _no_ matcher (which Goose treats as match-all) instead of verbatim.\n\n> **Note:** Qwen Code hooks are written under the top-level `hooks` key of `.qwen/settings.json` (project) / `~/.qwen/settings.json` (global), using Claude-style PascalCase per-matcher arrays (`{ \"EventName\": [ { \"matcher\": \"...\", \"sequential\": false, \"hooks\": [ { \"type\": \"command\", \"command\": \"...\", \"timeout\": ... } ] } ] }`). Qwen's supported event set **differs from Gemini CLI's**, so rulesync defines a Qwen-specific mapping. Twenty-two lifecycle events are supported — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `postToolBatch` ⇄ `PostToolBatch`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `userPromptExpansion` ⇄ `UserPromptExpansion`, `stop` ⇄ `Stop`, `stopFailure` ⇄ `StopFailure`, `subagentStart` ⇄ `SubagentStart`, `subagentStop` ⇄ `SubagentStop`, `preCompact` ⇄ `PreCompact`, `postCompact` ⇄ `PostCompact`, `permissionRequest` ⇄ `PermissionRequest`, `permissionDenied` ⇄ `PermissionDenied`, `notification` ⇄ `Notification`, `instructionsLoaded` ⇄ `InstructionsLoaded`, `todoCreated` ⇄ `TodoCreated`, `todoCompleted` ⇄ `TodoCompleted`, `messageDisplay` ⇄ `MessageDisplay` (fires repeatedly as the reply streams; added in Qwen Code v0.19.10), and `sessionDelete` ⇄ `SessionDelete` (fires after an explicitly selected session is deleted, via the interactive `/delete` command or the ACP `deleteSession` request; matcher-less, added in Qwen Code v0.21.3). Commands are emitted verbatim (no `$GEMINI_PROJECT_DIR` rewriting). Qwen's four hook types are supported: `command`, `prompt` (which carries the required `prompt` body — with `$ARGUMENTS` interpolation — and an optional `model` override, both round-tripped; a prompt hook without a `prompt` is warned about at generate time since Qwen Code loads it and fails it at runtime), `http` (which carries a `url` and POSTs JSON to it; the type and URL round-trip), and `function`. Per-hook fields added in [Qwen Code PR #2827](https://github.com/QwenLM/qwen-code/pull/2827) round-trip as well: command hooks carry `async` (run in the background), `env` (extra subprocess environment variables), and `shell` (`bash`/`powershell`); http hooks carry `headers` (with `${VAR}` interpolation), `allowedEnvVars` (the env-var allowlist), and `once` (single execution per event per session); `statusMessage` (progress text) applies to both. Command-only fields are emitted only on command hooks and http-only fields only on http hooks. The group-level `sequential` flag (parallel by default) and the top-level `disableAllHooks` switch are both round-tripped, and other top-level keys in `settings.json` are preserved. See the [Qwen Code hooks docs](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/hooks.md).\n\n> **Note:** Reasonix hooks are written to a dedicated `.reasonix/settings.json` (project) / `~/.reasonix/settings.json` (global) — a Claude-Code-style but standalone JSON file, separate from the `[permissions]`/`[[plugins]]` TOML config. Unlike Claude Code, each event key maps directly to a **flat array** of hook objects (no `matcher`/`hooks` wrapper): `{ \"EventName\": [ { \"match\": \"...\", \"command\": \"...\", \"description\": \"...\", \"timeout\": ... } ] }`. All ten of Reasonix's documented events are mapped — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `stop` ⇄ `Stop`, `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `subagentStop` ⇄ `SubagentStop`, `postModelInvocation` ⇄ `PostLLMCall`, `notification` ⇄ `Notification`, and `preCompact` ⇄ `PreCompact`. `match` (Reasonix's matcher field name) is honored only on `PreToolUse`/`PostToolUse`; a matcher on any other event is dropped with a warning. The canonical `timeout` field is documented in seconds, while Reasonix's `timeout` is milliseconds, so rulesync converts (`× 1000` on generate, `÷ 1000` on import). Only `command`-type hooks are supported. The `settings.json` file is not documented as holding anything besides hooks today, but rulesync merges non-destructively and never deletes it, in case a future Reasonix version adds other keys. See the [Reasonix Hooks guide](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/DESKTOP_HOOKS.zh-CN.md).\n\n> **Note:** Grok CLI (xAI Grok Build) hooks are written to a dedicated, standalone `rulesync.json` that Grok auto-discovers from `.grok/hooks/*.json` (project) / `~/.grok/hooks/*.json` (global). The JSON shape is Claude-Code-compatible: each event nests under the top-level `hooks` key as a per-matcher array (`{ \"hooks\": { \"EventName\": [ { \"matcher\": \"...\", \"hooks\": [ { \"type\": \"command\", \"command\": \"...\", \"timeout\": ... } ] } ] } }`). All fifteen documented events map 1:1 onto canonical arms — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `permissionDenied` ⇄ `PermissionDenied`, `stop` ⇄ `Stop`, `stopFailure` ⇄ `StopFailure`, `stopCancelled` ⇄ `StopCancelled`, `notification` ⇄ `Notification`, `subagentStart` ⇄ `SubagentStart`, `subagentStop` ⇄ `SubagentStop`, `preCompact` ⇄ `PreCompact`, and `postCompact` ⇄ `PostCompact`. `StopCancelled` runs **instead of** `Stop` when a turn ends without completing — a user interrupt, a declined permission prompt, the `--max-turns` limit, or a no-progress bail-out — so a `stop` hook alone does not cover interrupted turns; it is observation-only and cannot block. A `matcher` (a regex) is honored on every event except `Stop` and `UserPromptSubmit`, which always fire; a matcher on either of those two is dropped with a warning. What the regex tests depends on the event: the tool name on `PreToolUse` / `PostToolUse` / `PostToolUseFailure` / `PermissionDenied`, the notification type on `Notification` (e.g. `idle_prompt`), the subagent type on `SubagentStart` / `SubagentStop` (e.g. `explore`), the start source on `SessionStart`, the end reason on `SessionEnd`, the compaction trigger (`manual` or `auto`) on `PreCompact` / `PostCompact`, the error type on `StopFailure` (`rate_limit`, `authentication_failed`, …), and the cancellation reason on `StopCancelled` (`user_interrupt`, `permission_rejected`, `permission_cancelled`, `max_turns`, `no_progress`, or `unknown`). Earlier Rulesync versions inferred a much narrower set from Claude Code compatibility and dropped the other matchers, so a hook authored that way fired on everything; regenerate to get them back. Commands are emitted verbatim (Grok documents no project-directory variable). See the [Grok hooks docs](https://docs.x.ai/build/features/hooks). Both handler types Grok defines round-trip: a `command` hook runs a command, and an `http` hook POSTs the payload to its `url`. A command hook's `env` map (upstream `HookConfig.env`, merged into the spawned command's `extra_env`) round-trips as well. Note that a `.rulesync/hooks.*` obtained with `rulesync fetch` can therefore point a Grok hook at any URL — read it before generating.\n\n> **Note:** Kimi Code hooks are global-only and written as flat `[[hooks]]` entries in `~/.kimi-code/config.toml`, with `event`, `command`, and optional `matcher`/`timeout`. Rulesync maps fourteen canonical lifecycle events to Kimi's PascalCase names: `sessionStart`, `sessionEnd`, `beforeSubmitPrompt`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `permissionRequest`, `stop`, `stopFailure`, `notification`, `subagentStart`, `subagentStop`, `preCompact`, and `postCompact`. Kimi's native `PermissionResult`, `Interrupt`, `TurnStarted`, `UserPromptQueued`, `TaskStarted`, and `SessionHeartbeat` events have no canonical equivalents, but they can be written and preserved through the `kimi-code.hooks` override under their native names. (`TaskStarted` is deliberately not folded into the canonical `taskCreated`: it fires when a background task starts and matches on task kind, while `taskCreated` models Claude Code's blocking, matcher-less `TaskCreated` fired during task creation.) Only `command` hooks are emitted. A matcher is dropped with a warning on `Stop`, `SessionHeartbeat`, and `Interrupt`, the three events whose Event Reference row documents the matcher as an empty string. Kimi treats `matcher` as a regular expression tested against the event target, so on these events it is tested against `\"\"` and any non-trivial matcher never matches — such a hook silently never ran. Dropping the matcher is therefore a behavior change for existing configs: the hook now fires, which is what authoring it meant. Every other event matches a real value (`UserPromptSubmit` the submitted prompt text, `PermissionRequest` and `PermissionResult` the tool name, `PreCompact` the trigger, and so on), so matchers there are kept. Kimi normally runs these user-level hooks with each current session project as the working directory, which would let an unrelated repository substitute a relative script or influence commands such as `npm test`. Rulesync therefore wraps every generated command so it first changes to the trusted absolute directory containing the source `.rulesync/hooks.jsonc`; relative paths and project-aware commands consistently resolve against that source rather than whichever repository Kimi later opens. Kimi requires `timeout` to be an integer from 1 to 600 seconds; invalid canonical values are omitted with a warning so Kimi can still load the config. The shared TOML file is merged in place and never deleted. See the [Kimi Code hooks docs](https://moonshotai.github.io/kimi-code/en/customization/hooks.html).\n\n## `.github/mcp.json` and `.copilot/mcp-config.json`\n\nExample:\n\n```json\n{\n  \"mcpServers\": {\n    \"serena\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/oraios/serena\", \"serena\", \"start-mcp-server\"]\n    },\n    \"github\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:3000/mcp\"\n    },\n    \"local-dev\": {\n      \"type\": \"local\",\n      \"command\": \"node\",\n      \"args\": [\"scripts/start-local-mcp.js\"]\n    }\n  }\n}\n```\n\nThis file is used by the GitHub Copilot CLI for MCP server configuration. Rulesync manages it by converting from the unified `.rulesync/mcp.jsonc` format. Both scopes use the same `{ \"mcpServers\": {...} }` shape but write to different paths:\n\n- **Project mode:** `.github/mcp.json` (relative to project root) — the Copilot CLI auto-loads MCP servers from this workspace config file ([changelog v1.0.61, 2026-06-09](https://github.com/github/copilot-cli)).\n- **Global mode:** `~/.copilot/mcp-config.json` (relative to home directory) — the personal/global MCP configuration.\n\n> **Migration note:** earlier Rulesync versions wrote the **project-mode** Copilot CLI MCP config to `.copilot/mcp-config.json` (the same path used for global mode). Project mode now writes the dedicated workspace file `.github/mcp.json` instead, so a previously generated project-scope `.copilot/mcp-config.json` is no longer managed and can be removed by hand.\n\nRulesync preserves explicit `type` values for `http`, `sse`, and `local` servers. For command-based servers that omit a transport type, Rulesync emits the mandatory `\"type\": \"stdio\"` field required by the Copilot CLI. `streamable-http` is written as `http`, the transport it names, and the canonical `httpUrl` alias is normalized to the `url` Copilot CLI reads. A server the Copilot CLI config cannot express is skipped with a warning rather than failing the run: one that declares no transport at all (the shape a Kilo `{\"enabled\": …}` toggle imports as, which switches off a server some other config layer defines — every entry here defines a server), one that names a remote transport but no `url`/`httpUrl`, one that names a local transport but no `command`, and a `ws` server, since Copilot CLI has no WebSocket transport.\n\nThe canonical per-server `enabledTools` is written as Copilot CLI's own [`tools` allowlist](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) — `[\"*\"]` (the default) exposes every tool, a list exposes only those names — and imports back as `enabledTools`. A server that already carries a native `tools` value keeps it, and a colliding `enabledTools` is dropped with a warning. `disabledTools` has no counterpart upstream (expressing it would need the server's full tool list), so it is not emitted.\n\n## `rulesync/commands/*.md`\n\nExample:\n\n```md\n---\ndescription: \"Review a pull request\" # command description\ntargets: [\"*\"] # * = all, or specific tools\ncopilot: # copilot specific parameters (optional)\n  description: \"Review a pull request\"\n  agent: \"agent\" # (optional) VS Code prompt-file agent: \"ask\", \"agent\", \"plan\", or a custom agent name (replaces the deprecated \"mode\")\nantigravity: # antigravity specific parameters\n  trigger: \"/review\" # Specific trigger for workflow (renames file to review.md)\n  turbo: true # (Optional, default: true) Append // turbo for auto-execution\ntakt: # takt specific parameters (optional; emitted under .takt/facets/instructions/)\n  name: \"renamed-stem\" # (optional) override the emitted filename stem (no path separators or \"..\")\n  extends: \"base\" # (optional) emit a leading `{extends:<parent>}` facet-inheritance directive (Takt 0.39.0+)\npi: # pi coding agent specific parameters (optional)\n  argument-hint: \"[message]\" # Hint shown in Pi's command palette\ncodexcli: # Codex CLI custom-prompt specific parameters (optional)\n  argument-hint: \"[message]\" # Hint shown for the custom prompt's arguments\nroo: # Roo Code specific parameters (optional)\n  mode: \"architect\" # (optional) mode slug to switch to before running the command body (e.g. \"code\", \"architect\")\n---\n\ntarget_pr = $ARGUMENTS\n\nIf target_pr is not provided, use the PR of the current branch.\n\nExecute the following in parallel:\n\n...\n```\n\nThe command body itself uses a Claude Code-compatible **universal syntax** (e.g. `$ARGUMENTS`, `` !`cmd` ``). When a target tool expects a different placeholder syntax, rulesync translates it automatically on generation and reverses the translation on import. See [Command Syntax](./command-syntax.md) for the full mapping.\n\n> **Codex CLI deprecation note:** Codex CLI's own docs now state \"Custom prompts are deprecated. Use skills for reusable instructions\" (see [Custom Prompts](https://developers.openai.com/codex/custom-prompts)). Rulesync's `codexcli` commands still generate the global-only `~/.codex/prompts/*.md` custom-prompt files described above — they remain functional and no removal date has been announced, so this behavior is unchanged for now. For new reusable instructions, prefer rulesync's `codexcli` skills support (see `.rulesync/skills/*/SKILL.md` below) instead.\n\n> **Warp note:** Warp documents skills as its custom slash-command surface — any skill is invocable as `/{skill-name}` with `$ARGUMENTS` / `$ARGUMENTS[N]` / `$N` argument substitution — so rulesync emits each command onto the native skills surface as `.warp/skills/<name>/SKILL.md` (project) / `~/.warp/skills/<name>/SKILL.md` (global, via `--global`), with `name`/`description` frontmatter derived from the command file. Warp's `.warp/workflows/` YAML files are parameterized shell-command templates, not agent prompts, and are deliberately not used. Commands import and `--delete` are no-ops for `warp` because the skills feature owns the `.warp/skills/` tree (importing it as commands would double-import every skill) — mirrors the Devin note below. Keep command and skill names distinct for this target, since a command and a skill sharing a name write the same `SKILL.md` path. See the [Warp skills docs](https://docs.warp.dev/agent-platform/capabilities/skills/).\n\n> **Devin note:** Devin's extensibility docs no longer document a standalone workflows/commands component — reusable prompts invoked as slash commands are [Skills](https://docs.devin.ai/cli/extensibility/skills/overview) (`/name`). Rulesync therefore emits each command onto the native skills surface as `.devin/skills/<name>/SKILL.md` (project) / `~/.config/devin/skills/<name>/SKILL.md` (global, via `--global`), with `name`/`description` frontmatter derived from the command file. The legacy Windsurf/Cascade-era `.devin/workflows/` and `~/.codeium/windsurf/global_workflows/` locations are no longer emitted (stale outputs there stay gitignored but are not cleaned up automatically). Commands import and `--delete` are no-ops for `devin` because the skills feature owns the `.devin/skills/` tree (importing it as commands would double-import every skill). Note that a command and a skill sharing the same name write the same `SKILL.md` path, so keep command and skill names distinct for this target.\n\n> **Agent Skills standard note (`agentsskills`):** Rulesync accepts the legacy rulesync spellings on input but always **emits** the shapes the [specification](https://agentskills.io/specification) requires: `allowed-tools` becomes a space-separated scalar (a YAML list is joined), `compatibility` becomes a string (an object is flattened to `key: value` pairs), and `metadata` values are stringified so the block stays a string→string map. Generation also checks the normative constraints and warns — without failing the run — when `name` is empty, longer than 64 characters, contains anything but lowercase letters, digits and single hyphens, or does not match its parent directory name; when `description` is empty or longer than 1024 characters; when `compatibility` exceeds 500 characters; or when an `allowed-tools` list entry contains whitespace, which the space-separated form cannot represent. These are warnings rather than errors because a conformant client only _skips_ such a skill, and because import stays lenient as the [client-implementation guide](https://agentskills.io/client-implementation/adding-skills-support) advises. **Import** reports the same empty-`description` violation, for the one reason it matters on that side too: a conformant client would skip the skill, so a user who is never told has no reason to fix it. Rulesync converts rather than loads, so the skill is imported all the same — dropping the directory would lose content that is still repairable. `hermesagent` reads the same shape and reports it identically. A value that normalizes to the empty string (`compatibility: {}`, `allowed-tools: []`) is dropped rather than written, since the spec requires `compatibility` to be 1–500 characters when present. On **import**, `allowed-tools` is normalized back to the canonical rulesync list, so a generate → import round trip leaves `.rulesync/skills/**` in the shape it started in (the `compatibility` and `metadata` coercions are one-way, because the legacy object/number forms have no conformant equivalent). `hermesagent` reads the same `agentsskills` block and applies the same normalization in both directions, so one rulesync source never produces two different on-disk spellings — except for `metadata`, which stays structured there because Hermes reads `metadata.hermes.*` as YAML. A `hermesagent:` override still wins over the shared block (as for every tool-specific section), so a list or mapping written there is emitted as-is and reported as a spec violation rather than rewritten. Validate the result with the spec's own [`skills-ref validate`](https://github.com/agentskills/agentskills/tree/main/skills-ref). Import leniency is root-based as well as tool-based: any tool scanning an Agent Skills interop root (project `.agents/skills/`, global `~/.agents/skills/`, or Amp's `~/.config/agents/skills/`) skips-and-warns on a skill (directory-form or flat-file) that fails to load there — the cross-vendor directory is where foreign-authored, potentially non-conformant skills live — while each tool's own native root (e.g. Rovo Dev's `.rovodev/skills/`) stays fail-fast.\n\n> **Malformed frontmatter note:** a `SKILL.md` whose YAML fails to parse is retried once with its top-level unquoted values quoted, which recovers the case the Agent Skills [client-implementation guide](https://agentskills.io/client-implementation/adding-skills-support) names — `description: Use this skill when: the user asks about PDFs`, where the second colon ends the scalar. The retry rewrites only top-level `key: value` lines whose value contains a colon followed by whitespace, so a URL (`homepage: https://example.com`) and anything already quoted, a flow collection or a block scalar are left alone. An inline comment is cut off before the value is examined, so `allowed-tools: Read # TODO: add Bash later` is neither rewritten nor turned into a value that grants what the comment had disabled; a file the retry cannot fix still fails with the error it actually has. Recovery is reported with a warning: fix the file itself, since other tools read it with their own parsers.\n\n> **Replit note:** Replit's skills page states conformance to the [Agent Skills specification](https://agentskills.io/specification), so `replit.allowed-tools` accepts either the spec's space-separated string or a canonical rulesync list and is always **emitted** as the string; `replit.compatibility` likewise accepts the spec's string alongside the legacy object form. On import, `allowed-tools` is normalized back to the list, mirroring `deepagents` — so keep list entries free of whitespace, since the space-separated form cannot represent an entry such as `Bash(git commit:*)` and a client would read it back as two. An object `compatibility` is emitted unchanged rather than flattened: unlike the join, that conversion would be one-way, so the legacy form stays as-is and is simply not spec-conformant on disk.\n\n> **Junie skills note:** Junie treats `description` as **optional** in a skill's `SKILL.md` — \"If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content as the description.\" Rulesync's canonical frontmatter requires one, so on **import** a missing `description` is filled in the same way, from the first body paragraph (wrapped lines joined into a single line, since it becomes a YAML scalar); a `SKILL.md` Junie loads fine therefore no longer aborts the import. **Markdown headings are skipped**, matching upstream's \"If the body is also empty or contains only headings, the skill will fail to load\" — so a body opening with `# Skill Name` yields the prose beneath it, not the title. That matters beyond the import: an imported description is written back out explicitly on the next generate, so importing the title would replace Junie's own correct fallback with it, for every tool. A fenced code block is **not** special-cased — it is ordinary content, so a body whose first non-heading paragraph is a fence yields the fence text, which is a good reason to author a `description` explicitly. When nothing remains (an empty or headings-only body), Junie could not load the skill either, so Rulesync skips **that one skill** with a warning and keeps importing the rest. Generation always writes an explicit `description`, which Junie's own docs recommend. Junie also loads skills from the shared Agent Skills root — `<projectRoot>/.agents/skills/` and `~/.agents/skills/` — so Rulesync registers it as an import fallback at either scope; it is import-only (the `agentsskills` target owns writing there) and is never removed by Junie-target orphan deletion. When the same skill name exists in both roots, the Junie-specific `.junie/skills/` root takes precedence — Junie's own docs are silent on that ordering, so this matches how Rulesync already resolves the shared root for `kimi-code`. Names are compared case-insensitively there too, so `.agents/skills/My-Skill` does not shadow `.junie/skills/my-skill`; see the cross-root duplicate note under [`.rulesync/skills/*/SKILL.md`](#rulesyncskillsskillmd). Junie's third skill source — the custom folders added with `--skill-location` or the `skill-locations` key of its `config.json` — is out of scope for the `junie` target: Rulesync neither reads nor writes those paths, so a skill kept only there stays invisible to `rulesync import`. See the [agent skills docs](https://junie.jetbrains.com/docs/agent-skills.html).\n\n> **Vibe skills note:** Vibe discovers skills under `.vibe/skills/` (project) and `~/.vibe/skills/` (global), plus the shared `.agents/skills/` root at **both** scopes — Vibe's `user_skills_dirs` returns `~/.vibe/skills` and `~/.agents/skills` alike. Rulesync registers the shared root as an import fallback at either scope; it is import-only and is never removed by Vibe-target orphan deletion. When the same skill name exists in both roots the Vibe-specific root takes precedence, compared case-insensitively; see the cross-root duplicate note under [`.rulesync/skills/*/SKILL.md`](#rulesyncskillsskillmd).\n\n> **Pi skills note:** Pi implements the [Agent Skills specification](https://agentskills.io/specification), so `pi.allowed-tools` accepts either the spec's space-delimited string or a canonical rulesync list and is always **emitted** as the string; `pi.compatibility` likewise accepts the spec's string alongside the legacy object form. Importing a spec-conformant `SKILL.md` used to fail outright. On import, `allowed-tools` is normalized back to the list, mirroring `deepagents`; keep list entries free of whitespace, since the space-delimited form cannot represent an entry such as `Bash(git commit:*)`. An `allowed-tools` value that normalizes to the empty string (an empty list) is dropped rather than written. An object `compatibility` is emitted unchanged rather than flattened, because that conversion would be one-way.\n\n> **Hermes Agent note:** Commands are global-only and remain distinct from skills. Rulesync writes JSON command specs to `~/.hermes/rulesync/commands/<name>.json`, installs the `rulesync-commands` plugin under `~/.hermes/plugins/`, and enables it in `~/.hermes/config.yaml`. The plugin registers each spec with Hermes's [`ctx.register_command()` plugin API](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins/) and dispatches the prompt through `delegate_task`; invocation arguments are appended to the prompt. `.rulesync/skills/<name>/SKILL.md` still generates a full [Hermes Agent Skill](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/) under `~/.hermes/skills/<name>/SKILL.md`, which Hermes also exposes as a dynamic slash command. Rulesync rejects command/skill names that would collide in Hermes's slash-command namespace, and rejects nested command paths that flatten to the same name. Generate commands with `rulesync generate --targets hermesagent --features commands --global`.\n>\n> Releases before this native plugin transport emitted Hermes commands as `~/.hermes/skills/<name>/SKILL.md`. Rulesync cannot distinguish those files from real user-authored skills safely, so remove an obsolete legacy file manually after confirming that `.rulesync/skills/<name>/SKILL.md` does not own it.\n\n> **Qwen Code note:** Custom commands are emitted as **Markdown** files (not TOML — TOML is deprecated upstream) under `.qwen/commands/` (project) and `~/.qwen/commands/` (global, via `--global`). The file is an optional YAML frontmatter block followed by the prompt body; besides `description`, Qwen Code's command loader reads `when_to_use` (invocation guidance), `argument-hint` (completion hint), and `disable-model-invocation`, all typed and round-tripped. Subdirectory namespacing is supported: `.qwen/commands/git/commit.md` becomes the `/git:commit` command. Any extra fields are preserved on round-trip under the `qwencode:` block.\n\n> **OpenCode import note:** OpenCode lets commands live both as Markdown files under `.opencode/commands/*.md` **and** inline in `opencode.json`/`opencode.jsonc` under the top-level `command` key. On import, rulesync reads both: each inline entry's `template` becomes the command body and its `description`/`agent`/`model`/`subtask` fields become frontmatter. A Markdown file takes precedence over an inline entry with the same name.\n\n> **AugmentCode note:** Commands are written to `.augment/commands/<name>.md` (project) / `~/.augment/commands/<name>.md` (global, via `--global`). Subdirectories are namespaces — `.augment/commands/git/commit.md` is `/git:commit` — so nested rulesync commands keep their nesting rather than being flattened to a basename. If you generated AugmentCode commands with an earlier Rulesync, the flattened files it wrote are still on disk under their old names; `--delete` removes them. Auggie also discovers commands under the cross-tool `.agents/commands/` root, so **import** reads that root too and treats a command found there as if it lived under `.augment/commands/` — the command's name is its path under whichever root it came from. Generation stays on `.augment/commands/`, and `.agents/commands/` is never written to or swept for orphans, since the files there may belong to another tool — Rulesync itself writes that root for the `agentsmd` target, so a command already imported from `.augment/commands/` is not imported again from there under a flattened name. Auggie's other shared root, `.claude/commands/`, is deliberately not read: it is Claude Code's own output, which Rulesync already imports as that target. Importing from a shared root is announced, because the result is a Rulesync command written for every target on the next generate. See the [custom commands docs](https://docs.augmentcode.com/cli/custom-commands).\n\n> **Reasonix note:** Custom slash commands are Markdown files under `.reasonix/commands/` (project) / `~/.reasonix/commands/` (global, via `--global`) — directly analogous to Claude Code's `.claude/commands/`, since Reasonix explicitly mirrors Claude Code's conventions. Frontmatter supports `description` and `argument-hint`, and the body uses the same `$ARGUMENTS` / `$1`…`$N` placeholder syntax. Subdirectory namespacing is supported (`git/commit.md` → `/git:commit`). Any extra fields are preserved on round-trip under the `reasonix:` block. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md#slash-commands).\n\n> **Grok CLI note:** Custom slash commands are Markdown files under `.grok/commands/` (project) / `~/.grok/commands/` (global, via `--global`), read by the same Claude-Code-compatible frontmatter parser Grok uses for skills. Rulesync emits `description` plus, from the `grokcli:` block, `argument-hint`, `user-invocable` (default true) and `disable-model-invocation` (default false) — the same invocation-control pair Grok skills honor. Two upstream constraints are worth knowing. Grok's command scan is **flat and non-recursive**, so subdirectory namespacing is not supported: a nested `git/commit.md` is flattened onto `commit.md`, and two nested commands with the same basename collide (rulesync warns and the last one wins). And Grok collects skills before commands, letting **skills win name collisions** — a `.grok/skills/<name>/` shadows `.grok/commands/<name>.md`, so avoid giving a rulesync skill and a rulesync command the same name when targeting Grok. Any extra frontmatter keys are preserved on round-trip under the `grokcli:` block. See the [skills, plugins and marketplaces docs](https://docs.x.ai/build/features/skills-plugins-marketplaces).\n\n> **Rovo Dev CLI note:** Rovo Dev's \"saved prompts\" are a file-based custom-command surface made of a `prompts.yml` manifest plus per-prompt Markdown content files, invoked via `/prompts [title] [extra]`. Rulesync writes the content (no frontmatter) to `.rovodev/prompts/<name>.md` (project) / `~/.rovodev/prompts/<name>.md` (global, via `--global`), and rebuilds the sibling `.rovodev/prompts.yml` / `~/.rovodev/prompts.yml` manifest with one `{ name, description, content_file }` entry per prompt, `content_file` pointing at `prompts/<name>.md` (resolved relative to `prompts.yml`, matching Rovo Dev's own resolution order). The `prompts` array is fully replaced from the current rulesync commands on each generate (mirrors the Rovodev MCP adapter fully replacing `mcpServers`); any other top-level key in an existing manifest is preserved, and the manifest is never deleted. See the [saved prompts](https://support.atlassian.com/rovo/docs/save-and-reuse-a-prompt-in-rovo-dev-cli/) and [CLI commands](https://support.atlassian.com/rovo/docs/rovo-dev-cli-commands/) docs.\n\n> **ZCode note:** Custom commands are Markdown files under `.zcode/commands/` (project) / `~/.zcode/commands/` (global, via `--global`), invoked from the input box with `/`. Only the global path is spelled out in ZCode's docs, which describe the workspace scope as \"workspace-level commands live in the project directory\"; the `.zcode/commands/` project path is rulesync's inference from that sentence and from the layout ZCode uses for its other workspace assets, not a documented path. The file name is the command's identifier, and the frontmatter carries the `description` shown in the command picker plus an `argument-hint`. ZCode's command scan is flat, so subdirectory namespacing is not modeled. Any extra frontmatter fields are preserved on round-trip under the `zcode:` block. See the [ZCode commands docs](https://zcode.z.ai/en/docs/commands).\n\n## `rulesync/subagents/*.md`\n\nExample:\n\n```md\n---\nname: planner # subagent name\ntargets: [\"*\"] # * = all, or specific tools\ndescription: >- # subagent description\n  This is the general-purpose planner. The user asks the agent to plan to\n  suggest a specification, implement a new feature, refactor the codebase, or\n  fix a bug. This agent can be called by the user explicitly only.\nclaudecode: # for claudecode-specific parameters\n  model: inherit # opus, sonnet, haiku, fable, a full model id, or inherit (default)\n  tools: [\"Read\", \"Write\"] # (optional) allowed tools (string or list)\n  disallowedTools: [\"Bash\"] # (optional) tools to remove (string or list)\n  permissionMode: default # (optional) default | acceptEdits | bypassPermissions | plan\n  maxTurns: 20 # (optional) maximum agentic turns\n  skills: [\"skill-creator\"] # (optional) Agent Skills to utilize (string or list)\n  color: cyan # (optional) UI color (e.g. red, blue, green, cyan, ...)\n  memory: project # (optional) user | project | local\n  effort: high # (optional) low | medium | high | xhigh | max\n  isolation: worktree # (optional) run the subagent in an isolated git worktree\n  background: false # (optional) run the subagent in the background\n  initialPrompt: \"Start by reading the spec.\" # (optional) seed prompt for the subagent\n  mcpServers: {} # (optional) MCP server config (passed through verbatim)\n  hooks: {} # (optional) hook config (passed through verbatim)\ncopilot: # for GitHub Copilot specific parameters\n  tools:\n    # Listed tools are emitted verbatim; omit `tools` entirely to grant the agent\n    # all tools. `agent/runSubagent` is opt-in — add it explicitly only when this\n    # subagent needs to orchestrate other subagents.\n    - web/fetch\n    - agent/runSubagent\nopencode: # for OpenCode-specific parameters\n  mode: subagent # (optional, defaults to \"subagent\") OpenCode agent mode\n  model: anthropic/claude-sonnet-4-20250514\n  temperature: 0.1\n  tools:\n    write: false\n    edit: false\n    bash: false\n  permission:\n    bash:\n      \"git diff\": allow\nkilo: # for Kilo-specific parameters\n  mode: all # (optional, defaults to \"all\") use \"subagent\" for hidden/subagent-only agents\ncursor: # for Cursor-specific parameters (generated to .cursor/agents/*.md)\n  model: inherit # (optional, defaults to \"inherit\") model id, or \"inherit\" to use the parent's model\n  readonly: false # (optional, defaults to false) restrict the subagent to read-only tools\n  is_background: false # (optional, defaults to false) run the subagent as a background agent\njunie: # for JetBrains Junie CLI specific parameters (generated to .junie/agents/*.md; also imported from .agents/*.md)\n  tools: [\"Read\", \"Grep\", \"Edit\"] # allowed tools\n  disallowedTools: [\"Bash\", \"WebSearch\"] # disallowed tools\n  mcpServers: [\"github\"] # MCP servers the subagent may use\n  model: sonnet # model id\n  permissionMode: acceptEdits # (optional, defaults to \"default\") default | acceptEdits | dontAsk | bypassPermissions | plan\n  reasoningLevel: high # low | medium | high\n  maxTurns: 20 # max agentic turns\n  skills: [\"kotlin\", \"writerside\"] # Agent Skills to utilize\n  allowPromptArgument: true # whether the subagent accepts a prompt argument\ntakt: # takt specific parameters (optional; emitted under .takt/facets/personas/)\n  name: \"renamed-stem\" # (optional) override the emitted filename stem (no path separators or \"..\")\nroo: # for Roo Code specific parameters (optional; aggregated into the root .roomodes file)\n  slug: planner # (optional) custom mode slug (^[a-zA-Z0-9-]+$); defaults to the sanitized file name\n  whenToUse: \"When planning a task\" # (optional) guidance for automated mode selection\n  customInstructions: \"Be concise.\" # (optional) extra behavioral guidelines\n  roleDefinition: \"You are the planner.\" # (optional) overrides the body as the mode's roleDefinition\n  groups: # (optional, defaults to [\"read\", \"edit\", \"command\", \"mcp\"]) tool access\n    - read\n    - [\"edit\", { fileRegex: \"\\\\.md$\", description: \"Markdown files\" }]\n---\n\nYou are the planner for any tasks.\n\nBased on the user's instruction, create a plan while analyzing the related files. Then, report the plan in detail. You can output files to @tmp/ if needed.\n\nAttention, again, you are just the planner, so though you can read any files and run any commands for analysis, please don't write any code.\n```\n\n> **Antigravity note:** Antigravity custom agents (CLI v1.1.6+, shared by the IDE and the CLI) are emitted as Markdown + YAML frontmatter to `.agents/agents/<name>.md` (project) and `~/.gemini/config/agents/<name>.md` (global, via `--global`); the body after the frontmatter is the agent's system prompt. Both `antigravity-ide` and `antigravity-cli` read the same two locations, so enabling both writes the same file — the same way they already share `.agents/hooks.json`. Antigravity also accepts a directory form (`<name>/agent.md`); Rulesync emits and imports the flat file form only. `name` and `description` are **required** upstream, so a canonical subagent without a description gets a minimal generated fallback rather than a file Antigravity refuses to load. Because the two share that file, every Antigravity target reads the `antigravity-ide` and `antigravity-cli` blocks merged in a fixed order (the CLI block wins) — the same rule the MCP feature uses for the same shared-output reason — so generation order never changes the file's content; the `antigravity-plugin` block is layered on top for the plugin bundle only. Besides the shared `name`/`description`, those blocks accept these optional fields (all preserved on round-trip): `tools` (string list), `mainAgent` (boolean, default `true`), `subagent` (boolean, default `true`), `model` (`inherit` | `flash` | `pro`), `commandExecutionPolicy` (`off` | `auto` | `eager` | `sandbox`), `mcpServers`, `skills`, and `plugins`. `hidden` and `inheritMcp` appear in the v1.1.6 release notes but not in the documented frontmatter table, so they pass through verbatim with no behavior modeled around them; the schema is loose, so any extra keys survive the round-trip too. The `antigravity-plugin` target writes the same file format into a plugin bundle's `agents/` directory (project scope only). See the [Antigravity subagents docs](https://antigravity.google/docs/subagents) and the [plugin bundle layout](https://antigravity.google/docs/cli/plugins).\n\n> **`.agents/agents/` ownership note (`agentsmd`):** `.agents/agents/` is not an AGENTS.md convention — the AGENTS.md standard defines only `AGENTS.md` itself. It is the cross-vendor location AGENTS.md-era clients actually scan for agent definitions: both Antigravity targets generate into it, and Kimi Code reads it alongside its own agents directory. The **simulated** `agentsmd` subagent writer therefore emits there too, and because it has no frontmatter model of its own it emits exactly what the Antigravity targets emit — same merged `antigravity-ide` → `antigravity-cli` blocks, same serialization — so a simulated writer can never degrade the file a native target owns. Earlier Rulesync versions wrote these files to `.agents/subagents/`, a directory no documented client reads; they are no longer generated there (stale outputs stay gitignored but are not cleaned up automatically), so move or delete anything you hand-authored under the old path. Note that, unlike the shared root Kimi Code reads (which is import-only for that target), `.agents/agents/` is a **generated** path for `agentsmd` and the Antigravity targets, so `generate --delete` sweeps orphans there: a hand-authored agent in that directory that no `.rulesync/subagents/*.md` produces is removed. Import it first if you want to keep it. A subagent pinned to one writer of this directory (`targets: [\"antigravity-cli\"]`, say) survives a run that includes the other writers: `generate` claims every path the run writes, across all the targets it runs, and holds the orphan sweep back until the last of them has written, so no writer of a shared directory treats a sibling's output as a leftover. Narrowing `--targets` narrows that claim set, though — a later `generate --targets antigravity-ide --delete` knows nothing about the `antigravity-cli`-pinned file and sweeps it — so generate the writers of a shared directory together. Because the file is shared, an `agentsmd`-only generate still emits the Antigravity blocks (`tools`, `model`, `commandExecutionPolicy`, `mcpServers`, …) verbatim: writing a reduced file would be exactly the silent degradation this shared-path arrangement exists to prevent. That is a deliberate trade-off — a subagent pulled in from someone else's repository with `rulesync fetch` becomes a live, executable agent definition as soon as any target that writes this path runs, so review `.rulesync/subagents/*.md` after fetching, exactly as you would review any other fetched configuration before generating.\n\n> **Qwen Code note:** Subagents are emitted as Markdown + YAML frontmatter under `.qwen/agents/` (project) and `~/.qwen/agents/` (user/global, via `--global`); the body is the subagent's system prompt. Besides the shared `name`/`description`, the `qwencode:` block accepts these optional fields (all preserved on round-trip): `model`, `approvalMode` (`default` | `plan` | `auto-edit` | `yolo` | `bubble`), `tools` (allowlist), `disallowedTools` (denylist), `maxTurns`, `color`, `mcpServers` (per-agent MCP overrides — accepts both a record of server specs, matching Qwen's documented shape, and a plain array of server names), and `hooks` (per-agent hook registrations). See the [Qwen Code sub-agents docs](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/sub-agents.md).\n\n> **Kimi Code note:** Subagents are emitted as Markdown files under `.kimi-code/agents/` (project) and `~/.kimi-code/agents/` (global). The shared `name` and required `description` fields are written to YAML frontmatter; Kimi-specific `whenToUse`, `override`, `tools`, `disallowedTools`, and `subagents` fields can be authored under the `kimi-code:` block and round-trip unchanged. Kimi recursively scans both its Kimi-specific agents directory and the shared `.agents/agents/` directory, so Rulesync imports nested Markdown files from both locations and flattens them into `.rulesync/subagents/<name>.md` using the validated kebab-case agent name. The Kimi-specific root has precedence over `.agents/agents/`; if multiple source files resolve to the same logical agent name, the first one wins and Rulesync warns about the duplicate. The shared root is import-only and is never removed by Kimi-target orphan deletion. See the [Kimi Code custom-agents docs](https://moonshotai.github.io/kimi-code/en/customization/agents.html).\n\n> **Kiro CLI note:** Subagents are emitted as JSON agent configurations under `.kiro/agents/` (project) and `~/.kiro/agents/` (global). Kiro allows the JSON `name` field to be omitted, in which case the filename stem is the agent name; Rulesync accepts that form on import and writes the derived name into the Rulesync frontmatter. Imports through the `kiro-cli` target retain `targets: [\"kiro-cli\"]`, so they can be generated back to the same target without changing the target metadata.\n\n> **Cline note:** Cline file-based agents are emitted as YAML files (`<name>.yaml`) into `.cline/agents/` (project) and `~/.cline/agents/` (global, via `--global`). The file is a YAML frontmatter block followed by the system prompt body, matching Cline's agent config loader: `name` and `description` are **required** (Cline cli-v3.0.23+ refuses to load an agent whose `description` is missing or empty — a canonical subagent without one gets a minimal generated fallback rather than a file Cline cannot load), and the typed optional fields `tools`, `skills`, `providerId`, `modelId`, and `maxIterations` round-trip through the `cline:` section. Import reads `.yml` alongside `.yaml`, matching Cline's `isYamlFile()`.\n\n> **Devin note:** Devin Local custom subagent profiles are emitted as `AGENT.md` files in a **directory-per-agent** layout: `.devin/agents/<name>/AGENT.md` (project) and `~/.config/devin/agents/<name>/AGENT.md` (global, via `--global`). The directory name `<name>` is the profile id (derived from the rulesync subagent file name). The `AGENT.md` is a YAML frontmatter block followed by the subagent's system prompt. Besides the shared `name`/`description`, the `devin` subagent block accepts these optional fields (all preserved on round-trip): `model` (string, override the subagent LLM), `allowed-tools` (list of strings, restrict available tools), `permissions` (object with `allow`/`deny`/`ask` string lists, override tool permissions), and `max-nesting` (integer, enable nested subagent spawning up to the given depth). See the [Devin subagents docs](https://docs.devin.ai/cli/subagents).\n\n> **Reasonix note:** Reasonix native subagents are Skill profiles emitted as `SKILL.md` files in a **directory-per-agent** layout: `.reasonix/skills/<name>/SKILL.md` (project) and `~/.reasonix/skills/<name>/SKILL.md` (global, via `--global`). The directory name `<name>` is the profile id (derived from the rulesync subagent file name). A subagent is a Skill whose YAML frontmatter declares `invocation: manual` and `runAs: subagent` — Rulesync always injects both markers so the SKILL.md is recognized as a manually invoked subagent rather than an auto-discovered skill. Besides the shared `name`/`description`, the `reasonix` subagent block accepts these optional fields (all preserved on round-trip): `model` (string, subagent LLM), `effort` (string, reasoning effort), `allowed-tools` (list of strings, restrict available tools), and `color` (string, display color). The schema is loose, so any extra keys survive the round-trip. See the [Reasonix subagent profiles docs](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SUBAGENT_PROFILES.md).\n\n> **Roo / Zoo Code mode-specific rules note:** Both tools load `.roo/rules-{mode}/` (global `~/.roo/rules-{mode}/`) **instead of** the mode-agnostic `.roo/rules/` while that custom mode is active. Set a `roo:` frontmatter section with `mode: architect` on a rule to route it there; the section is shared by the `roo` and `zoocode` targets, which write the same `.roo/` tree. The slug must match `^[a-zA-Z0-9-]+$` (the alphabet the tools themselves accept) — anything else is ignored with a warning and the rule lands in `.roo/rules/`, rather than interpolating an arbitrary string into a directory name. The key is ignored on the `root: true` rule, which has no mode-specific counterpart. On import, a file under a mode directory comes back as `.rulesync/rules/{name}-{mode}.md` carrying `roo.mode`, suffixed so it cannot collide with a same-named generic rule (an already-suffixed name is left alone, so repeated generate/import cycles converge) and targeted at the importing tool alone, since a wildcard would make every other target emit a mode-scoped rule as an always-on one; mode-directory import is project scope only. Note that mode directories are **not swept by orphan deletion** — `generate --delete` only clears `.roo/rules/` — because a `rules-*` glob would also match mode rules you wrote by hand, so a file left behind by a removed rule has to be deleted yourself. Mode-specific _skills_ need no directory support: Zoo Code reads `modeSlugs` from a skill's own frontmatter at higher priority than the directory it sits in, so the existing `roo: modeSlugs` frontmatter already scopes a skill in `.roo/skills/` to a mode.\n\n> **Roo skills/commands note (final v3.54.0 state — Roo Code is EOL and its repository archived):** Commands are generated to `.roo/commands/` (project) and `~/.roo/commands/` (global, via `--global`; project wins on a name collision). Skill frontmatter beyond `name`/`description` — most usefully `modeSlugs: string[]` for mode targeting — is authored via the `roo:` section of `.rulesync/skills/*/SKILL.md` and lifted back into it on import, so it survives the round-trip. A localRoot rule is emitted as `AGENTS.local.md`, the personal, gitignored override file Roo loads alongside `AGENTS.md`.\n\n> **Zoo Code note:** Zoo Code ([Zoo-Code-Org/Zoo-Code](https://github.com/Zoo-Code-Org/Zoo-Code)) is the community continuation of the archived Roo Code, named by the Roo shutdown notice and continuing Roo's release numbering (v3.54.0 → v3.72.0 as of 2026-07-25). It still resolves `~/.roo` and the project `.roo/` layout — the `.zoo` renaming is confined to provider/auth code — so the `zoocode` target reuses the `roo` adapters' path model verbatim across rules (including `AGENTS.local.md` local-root handling), ignore (`.rooignore`), MCP (`.roo/mcp.json`), commands (`.roo/commands/`), skills (`.roo/skills/`, `roo:` frontmatter section), and subagents (the aggregated `.roomodes` file). Shared mode/skill fields keep riding the `roo:` frontmatter sections, so one rulesync source never produces two spellings; targeting both `roo` and `zoocode` writes the same files, so pick one target per project — and note the fail-open hazard the shared `.roomodes` creates: a `--targets roo` generate rewrites it **without** `allowedMcpServers`, so opening that workspace in Zoo Code makes every MCP server available to the mode. The post-fork divergence is carried by the `zoocode:` subagent section: `allowedMcpServers` (Zoo Code v3.60.0+), a per-mode MCP server allowlist (\"when omitted, all servers are available; when set, only the listed servers are injected\"), emitted into the mode and lifted back into `zoocode:` on import. See the [Zoo Code docs](https://docs.zoocode.dev/features/custom-modes).\n\n> **Vibe note:** Vibe agent profiles are emitted as TOML to `.vibe/agents/<name>.toml` (project) and `~/.vibe/agents/<name>.toml` (global, via `--global`). The subagent body is **not** written into the profile: Vibe's settable field is `system_prompt_id`, while `system_prompt` is a read-only property on its config schema and unknown TOML keys are ignored rather than rejected — so a profile carrying `system_prompt` loads fine and silently runs with the **default** system prompt. Rulesync therefore writes the body to `.vibe/prompts/<name>.md` and sets `system_prompt_id = \"<name>\"`, the same mechanism Vibe's own builtin profiles use (`EXPLORE` sets `\"system_prompt_id\": \"explore\"`). The two files are always written together, because `VibeConfigSchema._check_system_prompt` evaluates the id during validation and an unresolvable one makes `AgentRegistry._try_load` drop the agent with a warning. On import, `system_prompt_id` is resolved against `.vibe/prompts/` and becomes the canonical body; a legacy `system_prompt` is still read, and an id that resolves to nothing is preserved in the `vibe:` block so a hand-maintained prompt file keeps working. A subagent with an empty body writes no prompt file and leaves any `system_prompt_id` you authored alone. Note that `.vibe/prompts/` is not swept by orphan deletion — `generate --delete` only clears `.vibe/agents/` — so a prompt file left behind by a removed subagent has to be deleted by hand.\n\n> **Roo note (as of 2026-06-16):** Roo Code reads project custom modes from a single aggregated `.roomodes` file at the workspace root (YAML; JSON also accepted). Rulesync therefore collapses every Roo-targeted subagent into that file's `customModes` array — each subagent becomes one mode whose `slug` is derived from the file name (sanitized to `^[a-zA-Z0-9-]+$`), `name`/`description` come from the shared frontmatter, and `roleDefinition` is the subagent body. The optional `roo:` block supplies `groups` (defaults to `[\"read\", \"edit\", \"command\", \"mcp\"]`), `whenToUse`, `customInstructions`, an explicit `slug`, and a `roleDefinition` override. (Roo's previous `.roo/subagents/` output was inert — Roo Code never read it.) See the [Roo custom-modes docs](https://roocodeinc.github.io/Roo-Code/features/custom-modes).\n\n> **OpenCode import note:** OpenCode lets agents live both as Markdown files under `.opencode/agents/*.md` **and** inline in `opencode.json`/`opencode.jsonc` under the top-level `agent` key. On import, rulesync reads both: each inline entry's `prompt` becomes the subagent body (a `\"{file:./path}\"` reference is resolved relative to the config file's location, as OpenCode does), and the remaining fields (`description`/`mode`/`model`/`tools`/`permission`/...) become frontmatter under the `opencode:` block. A Markdown file takes precedence over an inline entry with the same name, compared case-insensitively — `.opencode/agents/planner.md` and an inline `Planner` are one `.rulesync/subagents/` file on macOS and Windows, so the inline copy is dropped with a warning rather than silently overwriting the file (two inline entries differing only in case resolve the same way, keeping the earlier one).\n\n> **Kilo note (as of 2026-05-13):** Kilo's documented default for user-defined agents is `mode: all`, which makes the agent available both as a top-level pick and as a subagent. Set `kilo.mode: subagent` to opt into hidden/subagent-only behavior.\n\nBesides `mode`, the `kilo` subagent block accepts these optional fields (all preserved on round-trip):\n\n| Field         | Type             | Notes                                                                                                                                                                                                                                                            |\n| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `displayName` | string           | Human-friendly name shown in pickers                                                                                                                                                                                                                             |\n| `model`       | string           | Model id                                                                                                                                                                                                                                                         |\n| `variant`     | string           | Model variant                                                                                                                                                                                                                                                    |\n| `temperature` | number           | Sampling temperature                                                                                                                                                                                                                                             |\n| `top_p`       | number           | Nucleus-sampling parameter                                                                                                                                                                                                                                       |\n| `permission`  | string \\| object | Permission profile name, or a per-tool `{ <tool>: { allow, deny, ask } }` object                                                                                                                                                                                 |\n| `prompt`      | string           | Inline system prompt                                                                                                                                                                                                                                             |\n| `color`       | string           | UI color                                                                                                                                                                                                                                                         |\n| `native`      | boolean          | Native (built-in) agent flag                                                                                                                                                                                                                                     |\n| `hidden`      | boolean          | Hide from top-level picker                                                                                                                                                                                                                                       |\n| `disable`     | boolean          | Disable the agent                                                                                                                                                                                                                                                |\n| `deprecated`  | boolean          | Mark as deprecated                                                                                                                                                                                                                                               |\n| `steps`       | positive integer | Maximum agentic iterations before a text-only response is forced (an explicit `null` is accepted and round-trips as-is, so a file that already carries one still imports; earlier Rulesync versions took a list of step objects here, which Kilo never accepted) |\n| `options`     | object           | Free-form key/value options                                                                                                                                                                                                                                      |\n\n> **Migration note (`steps`):** earlier Rulesync versions typed `steps` as a list of step objects, which Kilo never accepted — a subagent authored that way produced a file Kilo ignored. It is now the iteration count Kilo documents, so a `kilo` block (or a `.kilo/agents/*.md` file) still carrying the list form fails validation with the offending file named, and the run stops rather than writing a file that would not work. Replace the list with the number of iterations you want, or drop the field.\n\n> **Hermes Agent note:** Project generation writes subagent JSON specs under `.hermes/rulesync/subagents/` and installs `.hermes/plugins/rulesync-subagents/`. The plugin resolves specs relative to its own installation, so the same code works in project and global scope. For project scope, Rulesync also enables `rulesync-subagents` in `$HERMES_HOME/config.yaml`. Run Hermes from the trusted project root with `HERMES_ENABLE_PROJECT_PLUGINS=true`; Rulesync deliberately does not persist that global trust gate.\n\n## `.rulesync/checks/*.md`\n\nCode review checks are per-check instructions an agent runs during code review. Each check is a single Markdown file with YAML frontmatter (the source of the check identity is the file name — e.g. `.rulesync/checks/security.md` defines the `security` check).\n\nExample:\n\n```md\n---\ntargets: [\"*\"] # * = all, or specific tools\ndescription: Flags common security issues # (optional) short summary of the check\nseverity: high # (optional) low | medium | high | critical\ntools: [\"Read\", \"Grep\"] # (optional) tool names the check may use\n---\n\nReview the diff for injection vulnerabilities, hardcoded secrets, and unsafe\ndeserialization. Report each finding with a file and line reference.\n```\n\nAmp, AugmentCode, Cursor, Factory Droid, Hermes Agent, Rovo Dev CLI and Takt consume checks. Amp receives one Markdown file per check:\n\n- **Project scope:** `.agents/checks/<name>.md`\n- **Global scope** (`--global`): `~/.config/amp/checks/<name>.md`\n\nFor Cursor, checks are [Bugbot](https://cursor.com/docs/bugbot) code review instructions, and Bugbot reads one aggregated instruction file per directory rather than a file per check — so every check targeting Cursor collapses into the repository-root `.cursor/BUGBOT.md`. Each check becomes one section: an HTML-comment marker carrying the check name, an `## <name>` heading, and the check body as the instruction text (the `description` is used when the body is empty). Bugbot reads the file as free prose, so a check's `severity` and `tools` have no equivalent there — they are not written and do not come back on import, and neither is `description` whenever the check also has a body. Project scope only: Bugbot reads repository files and there is no user-level instruction file. Because Bugbot only sees the file when it is **committed**, the derived `.gitignore` deliberately does not ignore `.cursor/BUGBOT.md` (Rovo Dev's `.rovodev/.review-agent.md` and Factory Droid's `.factory/skills/review-guidelines/SKILL.md` get the same treatment) — commit the generated file for the reviewer to pick it up. Example output:\n\n```md\n<!-- rulesync:check:security -->\n\n## security\n\nReview the diff for injection vulnerabilities.\n```\n\nOn import the markers split the file back into one check per section, each with `targets: [\"*\"]` because Bugbot instructions are plain prose that applies anywhere. Content sitting ahead of the first marker — and a hand-written `BUGBOT.md` with no markers at all — is imported as a single `bugbot` check, so nothing in the file is dropped. A check body that contains a marker line of its own (a quoted rulesync doc fragment, say) is written as `<!-- rulesync:literal-check:… -->` and restored on import, so it cannot split the check it belongs to. Bugbot also merges nested `<dir>/.cursor/BUGBOT.md` files found while traversing upward from changed files, but rulesync check sources carry no directory-placement semantics, so only the root file is generated.\n\nGenerating checks for Cursor replaces `.cursor/BUGBOT.md`, so run `rulesync import --targets cursor --features checks` first if the repository already has a hand-written one — generation warns when it is about to replace instructions rulesync did not write. Deletion is guarded: a `BUGBOT.md` holding anything rulesync did not write — no marker at all, or hand-written text ahead of the first marker — is never removed, so dropping the last check that targets Cursor takes rulesync's own output with it and nothing else.\n\nFor Rovo Dev CLI, checks are [code-review custom instructions](https://support.atlassian.com/rovo/docs/set-custom-instructions-for-code-reviews/), and Rovo Dev reads one plain-Markdown file rather than a file per check — so every check targeting Rovo Dev collapses into `.rovodev/.review-agent.md` (note the leading dot in the file name). The file takes **no frontmatter**. Everything else works exactly as it does for Cursor Bugbot above, because the two surfaces are the same shape: one marked-up section per check, `severity`/`tools` dropped, `description` used only when the body is empty, markers splitting the file back on import (with a hand-written file importing as a single `review-agent` check), the same `<!-- rulesync:literal-check:… -->` escaping, the same replace-and-warn on generate, and the same deletion guard for a file holding anything rulesync did not write. Project scope only — these are per-repository review instructions and Rovo Dev documents no user-level equivalent, which is the opposite of the Rovo Dev permissions surface (global only).\n\nFor Factory Droid, checks are its [repository-specific review guidelines](https://docs.factory.ai/software-factory/code-review-ci). Factory's automated code review has no dedicated instruction file: it reads a skill named `review-guidelines` and injects it into every review run, so every check targeting Factory Droid collapses into `.factory/skills/review-guidelines/SKILL.md`. The file is plain Markdown with **no frontmatter**, matching Factory's documented example — and frontmatter would be self-defeating anyway, since anything ahead of the first marker counts as hand-written text. Everything else works exactly as it does for Cursor Bugbot above (one marked-up section per check, `severity`/`tools` dropped, the same escaping, the same deletion guard), with a hand-written file importing as a single `review-guidelines` check (its YAML frontmatter, if it has any, is skill metadata rather than review prose and is dropped on the way in). Project scope only: the reviewer runs against a repository and reads the file out of it, so there is no user-level equivalent to write. Because the output lives inside the `.factory/skills/` tree the `skills` feature also writes, the derived `.gitignore` ignores that tree as `**/.factory/skills/**` and re-includes this one file — git cannot un-ignore a path inside an ignored directory, so the directory pattern has to be the broader one. Re-run `rulesync gitignore` after upgrading: an earlier rulesync wrote the directory itself as `**/.factory/skills/`, and git never descends into an ignored directory, so that one line left in place would keep the re-include from working and the reviewer would never see the generated file. The command takes the old spelling out for you, wherever in the file it sits. A `review-guidelines` skill you authored yourself collides with the generated file. Generation does not replace it: a file holding anything ahead of the first generated marker is left exactly as it is, no Factory Droid checks are written at all for that run, and a warning names the file — the path has a single owner rather than a merge rule, and a file here may be an ordinary skill written for Droid's skill loader rather than review prose, so rulesync does not rewrite it (this is stricter than Cursor Bugbot's replace-and-warn, whose path only the reviewer reads). Import it with `rulesync import --targets factorydroid --features checks` and then delete the file: importing copies the text into `.rulesync/checks/` but leaves the file itself alone, so generation stays blocked until it is gone, and the next generate writes the path back from `.rulesync/checks/`. Delete it outright if you no longer want it, or rename the directory if what it holds is an ordinary skill rather than review guidelines. The `skills` feature leaves this path alone in every direction, whatever the file holds: a project-scoped `review-guidelines` skill is never imported as a skill, never swept as an orphan skill directory by `generate --delete`, and never generated into `.factory/skills/review-guidelines/` in the first place — a rulesync skill of that name is skipped for Factory Droid with a warning, so rename it if you want it generated. Global scope is unaffected, since checks has no user-level output: `~/.factory/skills/review-guidelines/` is an ordinary skill. Deleting the file when the last check targeting Factory Droid goes away is still guarded: it is removed only when it holds nothing but generated sections. Note that this file is **committed**, unlike the rest of `.factory/skills/`: Factory's reviewer reads it out of the checked-out repository, so whatever it contains is injected into every review run — review it as you would any other committed instruction file, in particular when it came from `rulesync fetch`.\n\nFor AugmentCode, checks are [Augment Code Review guidelines](https://docs.augmentcode.com/codereview/review-guidelines), which live in one YAML file at `.augment/code_review_guidelines.yaml` rather than in a file per check. Augment groups rules into named **areas**, each with a `description`, the `globs` it applies to, and a list of `rules` — every rule an `id` / `description` / `severity` triple, all of them required. Rulesync maps one check onto one rule: the body becomes the rule's `description` (the check's `description` is used when the body is empty, and the file stem when neither is set), and the rule lands in an area of its own, keyed by the check's file stem. An `augmentcode` frontmatter block moves it: `area` groups several checks under one key, with `areaDescription` and `globs` taken from the first check to name that area (`globs` defaults to `[\"**\"]`, matching Augment's own example; an authored empty list is kept as written, since an area matching nothing is a narrower statement than the catch-all, not an absent value), and `id` overrides the rule id. An authored `area` is used verbatim — Augment's own documented example keys an area `memory_safety`, and rewriting the underscores would leave the original area behind while a second one appeared beside it. Only the file-stem default is slugified, since that has to become a legal key from an arbitrary file name. Rule ids are kept distinct because Augment reports findings by id: two same-named checks in different subdirectories become `security` and `security-2`, and a generated id also steps aside for one a preserved hand-written area already uses. Example:\n\n```md\n---\ntargets: [\"augmentcode\"]\nseverity: high\naugmentcode:\n  area: databases\n  areaDescription: \"Data and Database related rules\"\n  globs: [\"db/**\"]\n  id: \"no_pii_in_bigquery\"\n---\n\nNever store PII data in BigQuery tables.\n```\n\n**Severity is lossy in one direction.** Augment's scale is `high` / `medium` / `low` with no band above `high`, so canonical `critical` is written as `high` and imports back as `high` — the canonical value is not recoverable from Augment's file alone. A check with no `severity` emits `medium`, since the field cannot be omitted: `high` would push every unannotated check past the ones deliberately marked `medium`, and `low` would bury them.\n\nGeneration **merges** rather than replaces, because Augment's documentation tells users to hand-write this file. Only the areas the current check set claims are rewritten — and a claimed area is replaced as a whole, so a field you hand-added inside one Rulesync regenerates does not survive. Every other area, the `file_paths_to_ignore` list, and any key Augment adds later are left untouched. `file_paths_to_ignore` is recognized and preserved but never authored or imported — the canonical check model has no ignore surface, and adding one is a separate question. The cost of merging is that rulesync cannot tell its own leftovers from a hand-written area: renaming a check strands the area under the old key, and when checks remain but none target AugmentCode the existing areas are left in place with a warning rather than guessed at. For the same reason the file is never deleted once it exists — unlike the Markdown surfaces, YAML carries no marker saying which text is rulesync's, since a rewrite drops comments and an unknown top-level key risks Augment's own parser.\n\nOn import, each rule becomes its own check (an area of three rules is three checks, not one), carrying the area key, description and globs back in its `augmentcode` block so the next generate regroups them exactly where they were. A rule missing `id` or `description` is left in the YAML rather than imported, and a rule id repeated across two areas is suffixed so the second check does not overwrite the first. Project scope only — the reviewer reads the file from the committed repository, and Augment documents no user-level equivalent.\n\nFor Hermes Agent, Rulesync writes project-local JSON specs under `.hermes/plugins/rulesync-checks/checks/` and a `rulesync-checks` plugin beside them. Its one-shot [`pre_verify` hook](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/#pre-verify) fires only for coding turns with changed paths and `attempt == 0`, then asks Hermes to run all configured checks before finishing. `tools` is preserved as advisory guidance because Hermes does not enforce an Amp-style per-check tool allowlist. Run Hermes with the project plugin explicitly trusted for that invocation:\n\n```sh\nHERMES_ENABLE_PROJECT_PLUGINS=1 hermes\n```\n\nRulesync adds `rulesync-checks` to `plugins.enabled` in `$HERMES_HOME/config.yaml` but deliberately leaves `$HERMES_HOME/.env` unchanged, preserving Hermes's global trust boundary. Existing plugin configuration is preserved; an explicit `plugins.disabled` conflict fails generation.\n\nFor Takt, checks are **quality gates**, and they live in the `workflow_overrides` block of the shared `.takt/config.yaml` (project) / `~/.takt/config.yaml` (global) rather than in files of their own — so every check targeting Takt collapses into that one file. A check becomes one gate: by default a **string gate**, the body text, which Takt injects into the agent step prompt as a completion directive (the `description` is used when the body is empty, and the file stem when neither is set); with `command` in the check's `takt` frontmatter block, a **command gate** (`{type: command, name, command, cwd, timeout_ms}`), which Takt runs after the step and fails on a non-zero exit code. `name` defaults to the file stem so Takt's logs identify the gate. `name`, `cwd` and `timeout_ms` belong to a command gate, so they are ignored on a check that states no `command`. `steps` and `personas` in that block scope a gate to named workflow steps or personas (`workflow_overrides.steps.<step>.quality_gates`); an unscoped gate applies everywhere, and a gate naming both is written to both. `quality_gates_edit_only` is a property of the block as a whole, so one check setting it turns it on for all of them. It reaches only the unscoped gates — Takt runs a `steps`/`personas`-scoped gate whether or not the step may edit files — so the reach it narrows is the other checks' unscoped gates, which is warned about when there are any. Takt gates carry no severity or tool allowlist, so a check's `severity` and `tools` are not written and do not come back on import. Takt merges quality gates additively and dedupes them (project over global over the workflow YAML's own gates). Example:\n\n```md\n---\ntargets: [\"takt\"]\ntakt:\n  command: ./.takt/quality-gates/check.sh # omit for a string gate\n  timeout_ms: 300000\n  steps: [\"review\"] # (optional) scope to named workflow steps\n  personas: [\"coder\"] # (optional) scope to named personas\n---\n```\n\nA command gate's `command` is run by Takt with no further gating — Takt's default-deny `workflow_command_gates.custom_scripts` policy applies to gates declared in workflow YAML, not to these — so read the frontmatter of any check you obtain with `rulesync fetch` before generating. The body of a check that carries a `command` is not used. `workflow_overrides` is owned by the checks feature: it is rewritten from `.rulesync/checks/` on every generate, so a gate deleted there disappears from `config.yaml` too, while every other key of the file is preserved and the file is never deleted. When checks remain but none of them target Takt — every one names other tools — the block is retracted with a warning, whether an earlier generate or a hand edit put it there; that is what owning the key means, so author gates as checks rather than in `config.yaml`. A project with no `config.yaml` does not get one. Emptying `.rulesync/checks/` altogether is different: the feature has no source to generate from, so nothing runs and the gates already in `config.yaml` stay. Delete the block by hand in that case — a command gate left behind keeps running after every step. On import, each gate becomes its own check file, named from the gate text or the command gate's `name`. A string gate is prose that applies anywhere, so it imports with `targets: [\"*\"]` like an Amp check; a command gate imports as `targets: [\"takt\"]`, since its body is empty and would generate an empty check for every other tool. A gate scoped to both a step and a persona becomes two checks, and a command gate carrying a field of the wrong type is left in `config.yaml` rather than imported. The default-deny `workflow_command_gates.custom_scripts` policy is **not** written here — Takt validates it against gates declared in workflow YAML, not against these, and it is authorable through the `takt` block of `.rulesync/permissions.*`, which owns the security policies. See the [Takt workflows docs](https://github.com/nrslib/takt/blob/main/docs/workflows.md).\n\nThe emitted Amp frontmatter is derived from the source as follows:\n\n| Amp field          | Source                                                   |\n| ------------------ | -------------------------------------------------------- |\n| `name`             | the source file basename without `.md` (required by Amp) |\n| `description`      | `description`                                            |\n| `severity-default` | `severity`                                               |\n| `tools`            | `tools`                                                  |\n\nThe frontmatter schema is loose, so extra Amp-specific keys survive a generate/import round-trip (except keys that collide with a rulesync tool-target name such as `cursor` — those are treated as tool-scoped sections and are not re-emitted). A tool-scoped section (e.g. `amp: { \"severity-default\": \"critical\" }`) overrides the canonical values for that tool — the tool-specific value takes precedence, and the section itself is not emitted (except `name`, which always comes from the file name). On import, `severity-default` maps back to the generic `severity` field, and the `name` field is dropped because it is re-derived from the file name on the next generate.\n\n> **v1 limitation:** Amp also discovers subtree-scoped checks (e.g. `api/.agents/checks/`), but rulesync sources carry no directory-placement semantics, so those subtree-scoped checks are not generated. See the [Amp manual](https://ampcode.com/manual).\n\n## `.rulesync/skills/*/SKILL.md`\n\nExample:\n\n```md\n---\nname: example-skill # skill name\ndescription: >- # skill description\n  A sample skill that demonstrates the skill format\ntargets: [\"*\"] # * = all, or specific tools\n# (optional) shared default for tools that support the flag — claudecode, copilot,\n# copilotcli, cursor, zed, pi, qwencode, grokcli, and factorydroid. Any of those\n# tool sections can override it by setting their own `disable-model-invocation`\n# value below. devin also reads this root value (true maps onto a user-only\n# `triggers` list); it has no section key of the same name, but devin.triggers\n# overrides it.\ndisable-model-invocation: true\n# (optional) shared default for tools that support the flag — claudecode, copilot,\n# copilotcli, cursor, qwencode, vibe, grokcli, and factorydroid. Any of those tool\n# sections can override it by setting their own `user-invocable` value below.\n# devin also reads this root value (false maps onto a model-only `triggers`\n# list); it has no section key of the same name, but devin.triggers overrides it.\nuser-invocable: false\nclaudecode: # for claudecode-specific parameters\n  model: sonnet # opus, sonnet, haiku, or any string\n  when_to_use: When the user asks to review a PR # (optional) extra trigger context appended to description\n  allowed-tools: # (optional) tools usable without asking; accepts a string or a list\n    - \"Bash\"\n    - \"Read\"\n    - \"Write\"\n    - \"Grep\"\n  disallowed-tools: # (optional) removes these tools while the skill is active (string or list)\n    - \"WebFetch\"\n  effort: high # (optional) effort while active: low | medium | high | xhigh | max\n  argument-hint: \"[pr-number]\" # (optional) autocomplete hint for expected arguments\n  arguments: # (optional) named positional arguments for $name substitution (string or list)\n    - \"pr_number\"\n  context: fork # (optional) set to \"fork\" to run the skill in a forked subagent context\n  agent: code-reviewer # (optional) subagent type to use when context: fork\n  background: false # (optional, context: fork only) wait for the forked subagent in the invoking turn instead of backgrounding it (default true)\n  shell: bash # (optional) shell for ! command blocks: bash (default) or powershell\n  hooks: # (optional) hooks scoped to the skill's lifecycle (free-form per the Claude Code docs)\n    PreToolUse:\n      - matcher: \"Bash\"\n  disable-model-invocation: true # (optional) disable model invocation for this skill\n  user-invocable: false # (optional) hide from the / menu while keeping model access\n  scheduled-task: true # (optional) emit to .claude/scheduled-tasks/<name>/SKILL.md instead of .claude/skills/<name>/SKILL.md\n  # paths (optional) limits auto-activation to matching globs. Accepts a\n  # comma-separated string, e.g. paths: \"src/**/*.ts,test/**/*.ts\", or a list:\n  paths:\n    - \"src/**/*.ts\"\n    - \"test/**/*.ts\"\n  # Claude Code accepts the three Agent Skills standard fields below but acts on\n  # none of them; they matter for claude.ai skill uploads, the Skills API, and\n  # packaging with package_skill.py.\n  license: Apache-2.0 # (optional) license covering the skill\n  compatibility: Requires Node.js 22 or later # (optional) environment requirements, up to 500 characters\n  metadata: # (optional) free-form map for your own tooling; a non-map value is dropped by Claude Code\n    catalog: internal\ncodexcli: # for codexcli-specific parameters\n  short-description: A brief user-facing description\n  # The following sections are emitted to the agents/openai.yaml sidecar next to SKILL.md.\n  # See https://developers.openai.com/codex/skills.md\n  interface: # (optional) UI metadata\n    display_name: Example Skill\n    short_description: A brief user-facing description\n    default_prompt: Do the thing\n  policy: # (optional) invocation policy\n    allow_implicit_invocation: false # only invoke explicitly via $skill\n  dependencies: # (optional) tool dependencies\n    tools:\n      - type: mcp\n        value: example\n        description: Example MCP tool\npi: # for Pi Coding Agent-specific parameters (optional; Agent Skills standard)\n  # Authored either as a canonical list or as the spec's space-delimited string;\n  # emitted to SKILL.md as the string, and imported back as the list.\n  allowed-tools:\n    - \"Bash\"\n    - \"Read\"\n  disable-model-invocation: true # (optional) disable model invocation for this skill\n  license: MIT # (optional)\n  compatibility: \"Requires git and jq\" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n  metadata: # (optional) free-form metadata\n    author: rulesync\nreplit: # for Replit Agent-specific parameters (optional; Agent Skills standard)\n  # Authored either as a canonical list or as the spec's space-separated string;\n  # emitted to SKILL.md as the string, and imported back as the list.\n  allowed-tools:\n    - \"Bash\"\n    - \"Read\"\n  license: MIT # (optional)\n  compatibility: \"Requires git and docker\" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n  metadata: # (optional) free-form metadata\n    author: rulesync\ndeepagents: # for deepagents-cli (dcode)-specific parameters (optional; Agent Skills standard)\n  # Authored as a canonical list; emitted to SKILL.md as a space-delimited string\n  # (e.g. \"Bash Read\") because dcode rejects a YAML list at runtime.\n  allowed-tools:\n    - \"Bash\"\n    - \"Read\"\n  license: MIT # (optional)\n  compatibility: # (optional) free-form compatibility metadata\n    deepagents-version: \">=0.1.0\"\n  metadata: # (optional) free-form metadata\n    author: rulesync\nopencode: # for OpenCode-specific parameters (optional)\n  license: MIT # (optional)\n  compatibility: # (optional) free-form compatibility metadata\n    opencode-version: \">=1.16.0\"\n  metadata: # (optional) free-form metadata\n    author: rulesync\n  allowed-tools: # (optional) Anthropic-spec passthrough; OpenCode ignores unknown fields\n    - \"Bash\"\n    - \"Read\"\nkilo: # for Kilo Code-specific parameters (optional)\n  license: MIT # (optional)\n  compatibility: # (optional) free-form compatibility metadata\n    kilo-version: \">=7.0.0\"\n  metadata: # (optional) free-form metadata\n    author: rulesync\n  allowed-tools: # (optional) backward-compat passthrough; not part of Kilo's official SKILL.md frontmatter\n    - \"Bash\"\n    - \"Read\"\nkiro: # for Kiro-specific parameters (optional; project .kiro/skills/, global ~/.kiro/skills/)\n  license: MIT # (optional)\n  compatibility: \"Requires network access\" # (optional) free-form string (an object is also accepted for back-compat)\n  metadata: # (optional) free-form metadata\n    author: rulesync\n  # Any other frontmatter key found in a hand-written SKILL.md is imported into this section and\n  # written back out, so a field Rulesync does not model is not lost on regeneration. `name` and\n  # `description` are the exception: they have canonical homes at the top level.\nkimi-code: # for Kimi Code-specific parameters (optional; project/global .kimi-code/skills/)\n  type: inline # (optional) prompt, inline, or flow\n  whenToUse: \"When reviewing pull requests\" # (optional) model invocation hint\n  disableModelInvocation: false # (optional) prevent automatic model invocation\n  arguments: [\"pull_request\"] # (optional) named arguments, also accepts a whitespace-separated string\nagentsskills: # for the Agent Skills standard target (optional; supports project + global ~/.agents/skills/)\n  license: MIT # (optional)\n  compatibility: \"Requires Python 3.14+ and uv\" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n  metadata: # (optional) free-form metadata (spec-recommended place for skill versioning)\n    version: \"1.0.0\"\n  allowed-tools: \"shell\" # (optional, experimental) space-separated string or list\namp: # for Amp-specific parameters (optional; project .agents/skills/, global ~/.config/agents/skills/)\n  # Amp reads the open Agent Skills standard and documents no frontmatter field beyond\n  # `name`/`description`, so this section exists only to carry keys a hand-written SKILL.md adds:\n  # they are imported into it and written back to the top level of the generated file instead of\n  # being erased on regeneration. `name` and `description` are the exception — they have canonical\n  # homes at the top level and a section value of either is ignored.\ncopilot: # for GitHub Copilot-specific parameters (optional; project .github/skills/, global ~/.copilot/skills/)\n  license: MIT # (optional)\n  allowed-tools: \"shell\" # (optional) tools pre-approved without per-use confirmation\n  argument-hint: \"[message]\" # (optional) hint shown for the skill's expected arguments\n  user-invocable: true # (optional, default true) whether users can run it with /SKILL-NAME\n  disable-model-invocation: false # (optional, default false) stop the agent from invoking it on its own\n  context: fork # (optional, experimental) run the skill in a forked session (VS Code 1.118+)\n  # Any other frontmatter key found in a hand-written SKILL.md is imported into this section and\n  # written back out, so a field Rulesync does not model is not lost on regeneration. `name` and\n  # `description` are the exception: they have canonical homes at the top level. Like the modeled\n  # fields below, such a key rides one section only, so the shared-path caveat that follows applies\n  # to it too.\n  # `copilot` and `copilotcli` write the same SKILL.md path at both scopes, so with both targets\n  # enabled the one generated last wins — and that is the order the targets are listed in, so which\n  # section decides the file is not fixed. Set the value in both sections (or, for the two invocation\n  # gates, in the shared top-level fields) whenever you generate for both. `context` has no\n  # `copilotcli` counterpart, so it survives only when `copilot` is generated last.\ncopilotcli: # for GitHub Copilot CLI-specific parameters (optional; project .github/skills/, global ~/.copilot/skills/)\n  license: MIT # (optional)\n  allowed-tools: \"shell\" # (optional) tools pre-approved without per-use confirmation\n  argument-hint: \"[message]\" # (optional) hint shown for the skill's expected arguments\n  user-invocable: true # (optional, default true) whether users can run it with /SKILL-NAME\n  disable-model-invocation: false # (optional, default false) stop the agent from invoking it on its own\n  # As in the `copilot` section, any other frontmatter key found in a hand-written SKILL.md is\n  # imported here and written back out.\nrovodev: # for Rovo Dev CLI-specific parameters (optional; Agent Skills standard)\n  allowed-tools: \"grep bash\" # (optional) space-separated string (a YAML list is also accepted)\n  license: MIT # (optional)\n  compatibility: \"Requires Python 3.14+ and uv\" # (optional) free-form string (object form also accepted)\n  metadata: # (optional) free-form metadata\n    author: rulesync\nzed: # for Zed-specific parameters (optional)\n  disable-model-invocation: true # (optional) prevent the model from auto-invoking this skill\ncursor: # for Cursor-specific parameters (optional)\n  paths: # (optional) glob patterns (string or list) scoping the skill to matching files\n    - \"src/**/*.ts\"\n  disable-model-invocation: true # (optional) only include the skill when invoked via /skill-name\n  user-invocable: false # (optional) hide from / autocomplete and typed /skill-name, keep model access\n  metadata: # (optional) free-form metadata\n    author: rulesync\nfactorydroid: # for Factory Droid-specific parameters (optional)\n  disable-model-invocation: true # (optional) prevent the model from auto-invoking this skill\n  user-invocable: false # (optional) hide from the slash-command menu, keep model access\n  enabled: false # (optional, default true) keep the skill on disk but stop Droid loading it\n  allowed-tools: \"Read Execute\" # (optional) tools the skill is designed to use (string or list)\n  # Droid documents the four packaging fields below without a type and never validates\n  # them, so rulesync carries whatever value they hold through in both directions.\n  license: MIT # (optional) license metadata for shared skills\n  compatibility: droid # (optional) compatibility metadata for catalogs, plugins, or team tooling\n  metadata: # (optional) structured metadata for your own tooling\n    owner: platform-team\n  version: \"1.0.0\" # (optional) version string for shared or packaged skills — quote it, since\n  # an unquoted 1.0 is a YAML number and is emitted back as `version: 1`\n  # `name` and `description` are the exception: the top-level values always win over a\n  # value of the same key inside this section.\n  # As in the `kiro` section, any other frontmatter key found in a hand-written SKILL.md is\n  # imported here and written back out.\ntakt: # takt specific parameters (optional; emitted under .takt/facets/knowledge/ — frontmatter is dropped on emit)\n  name: \"renamed-stem\" # (optional) override the emitted filename stem (no path separators or \"..\")\n  extends: \"base\" # (optional) emit a leading `{extends:<parent>}` facet-inheritance directive (Takt 0.39.0+)\ndevin: # for Devin-specific parameters (optional; project .devin/skills/, global ~/.config/devin/skills/)\n  argument-hint: \"[environment]\" # (optional) hint shown after the slash-command name\n  model: \"fast\" # (optional) model override while the skill runs\n  subagent: true # (optional) run the skill in a subagent (string or boolean per Devin's docs)\n  agent: \"deployer\" # (optional) named agent profile to run the skill with\n  allowed-tools: # (optional) tools available while the skill runs (string or list)\n    - \"Bash(git status:*)\"\n  permissions: {} # (optional) auto-approval rules applied while the skill runs (load-bearing since Devin CLI v3000.1.23)\n  triggers: [\"user\"] # (optional) invocation gating; omitted = user + model. The shared disable-model-invocation / user-invocable flags map onto this when unset.\nqwencode: # for Qwen Code-specific parameters (optional; project .qwen/skills/, global ~/.qwen/skills/)\n  priority: 10 # (optional) higher values appear earlier in /skills listings\n  paths: # (optional) glob patterns gating model discovery to matching files (a scalar is coerced to the array Qwen Code requires)\n    - \"src/**/*.ts\"\n  user-invocable: false # (optional) hide from slash-command invocation, keep model access\n  disable-model-invocation: true # (optional) hide from the model but allow direct user invocation\n  allowedTools: # (optional) permissions.allow-syntax rules auto-approved while the skill is active\n    - \"Shell(git status:*)\"\n  model: \"fast\" # (optional) model override while the skill runs (model id, fast, authType:modelId, inherit)\n  hooks: {} # (optional) session-scoped hooks registered while the skill runs (settings.json shape)\n  when_to_use: \"Use when deploying\" # (optional) invocation guidance surfaced in the SkillTool description\n  argument-hint: \"[environment]\" # (optional) hint shown after the slash-command name in completion\ngrokcli: # for Grok CLI-specific parameters (optional)\n  user-invocable: false # (optional) hide from the skill tool, keep model access\n  disable-model-invocation: true # (optional) block auto-invocation, keep the slash command\nvibe: # for Vibe Code-specific parameters (optional)\n  user-invocable: false # (optional) hide from slash-command invocation, keep model access\n  allowed-tools: \"Bash Read\" # (optional) space-delimited or list of allowed tool names\n---\n\nThis is the skill body content.\n\nYou can provide instructions, context, or any information that helps the AI agent understand and execute this skill effectively.\n\nThe skill can include:\n\n- Step-by-step instructions\n- Code examples\n- Best practices\n- Any relevant context\n\nSkills are directory-based and can include additional files alongside SKILL.md.\n\nWhen `claudecode.scheduled-task: true` is set, that skill is emitted only as a Claude Code scheduled task and is not emitted to other tools even if `targets` contains `\"*\"`.\n```\n\n> **Supporting-file note:** every file beside `SKILL.md` in a skill directory is copied **byte for byte**, to whichever tool root the skill is generated into. Most of them are user assets — images, archives, fixtures whose CRLF line endings or missing trailing newline are deliberate — so unlike `SKILL.md`, whose body and frontmatter Rulesync composes, they get no UTF-8 round-trip, no line-ending normalization and no trailing newline appended. Change detection compares them byte for byte too, so a supporting file written by an older Rulesync (which normalized text files) or edited in place by a formatter is rewritten from the source on the next generate. The one exception is a supporting file Rulesync composes itself rather than carries through — Codex CLI's `agents/openai.yaml` — which is compared by parsed content so that re-indenting it does not report a change on every generate. Dot-prefixed entries count as supporting files too — the specification says a skill directory \"may contain any files and directories beyond the required `SKILL.md`\", and a hidden `.env.example` or `.config/` is content the skill needs. Some entries are never carried, whether they are reached by their own name or through a symbolic link that renames them:\n>\n> - `.git`, `.hg` and `.svn` — a nested repository, whose tracked files are copied but whose history is not. Rulesync warns when it skips a top-level `.git`.\n> - `.DS_Store` — the macOS Finder's index.\n> - Credential stores and credential-shaped files: anything under `.ssh/`, `.aws/` or `.gnupg/`, plus `.npmrc`, `.netrc`, `.git-credentials`, `.pgpass`, `.pypirc`, `.htpasswd`, `.dockercfg`, `.envrc`, `.docker/config.json`, `.kube/config`, `.config/gh/hosts.yml`, `.config/gcloud/credentials.db`, `.gem/credentials`, `gcloud/application_default_credentials.json`, `.codex/auth.json` and `.gemini/oauth_creds.json`. A credential name counts wherever it appears in the path, not only as the last segment: `.env/production` and `.netrc/machine` hold what the files of those names hold, so a directory given a credential file's name is refused with everything under it. Carrying a secret would copy it into every enabled tool root, multiplying the places it can be committed from. A link that leaves the skill directory to reach a `.config/`, `.local/`, `.azure/`, `.m2/`, `.terraform.d/`, `.docker/`, `.kube/` or `Keychains/` tree is refused entirely — those are the per-application directories of a home directory, where naming each credential file is a list always one release behind — while a `.config/` the skill ships itself is carried as ordinary content. The exemption is for a sibling: a link that goes no higher than the skill directory's own parent, so a global skill under `~/.config/agents/skills/` still shares `../_shared` there while the same skill reaching `~/.config/gcloud/` is refused like any other; a tool home such as `~/.claude/` is deliberately not on the list, because that is where the global skills this feature exists to share are kept.\n> - `.env` and every `.env.<suffix>` spelling except the template ones — the last piece of the name decides, so `.env.example`, `.env.sample`, `.env.template`, `.env.dist`, `.env.defaults` and compound spellings such as `.env.local.example` are carried, being the case this support exists for, while `.env.local` and `.env.production` hold real values.\n> - Build, cache and virtual-environment trees: `.cache`, `.venv`, `.tox`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, `.gradle`, `.next`, `.nuxt`, `.turbo`, `.parcel-cache`, `.nyc_output` and `.terraform`. These are regenerated from the skill's own sources, and copying a `.venv` into every enabled tool root would multiply thousands of files that are not skill content.\n>\n> Names are compared case-insensitively, so `.SSH/` is excluded on the platforms that treat it as `.ssh/`, and trailing dots and spaces are trimmed first, because Windows drops them when the file lands (`.env ` becomes `.env` there). Leaving out a credential-shaped entry is reported in a warning, and so is an entry whose own name says nothing about it — a link named `assets` pointing into a `.cache/` tree; the ordinary exclusions, where the name in the skill directory is the excluded one — `.DS_Store`, build and cache trees — stay quiet.\n>\n> A skill directory is also walked within bounds, because a symbolic link in it may point anywhere: at most **12 directories deep**, at most **10,000 files**, at most **10,000 directories**, at most **200,000 entries looked at**, and at most **100MB** in total per directory, and each real directory is visited once so that a link pointing back at an ancestor collapses instead of multiplying the walk. Because only one route to a directory is walked, the route is chosen rather than left to the walk order: everything reachable without crossing a symbolic link first, then everything one link away, and so on — so a file keeps the path its `SKILL.md` refers to. When a route that the hidden-entry rule below then refuses is the one that reached a tree, the directory is walked once more with the hidden routes left out, so a tree that a fully named path also reaches is still carried under that name. Reaching any of those limits leaves files out, so it is always reported in a warning rather than silently truncating the skill; so is an entry that cannot be read at all. A route that passes through `/proc`, `/sys` or `/dev` is refused at every hop rather than only at its destination: `/proc/<pid>/fd/N` and `exe` resolve to whatever a running process holds open, so a check of the destination alone would carry another program's private key as though it were an ordinary file. Each hop's parent directory is resolved as well, since a link named `fds` pointing at `/proc/self/fd` leaves no `/proc` in the path `fds/3` to check; the hops a chain costs count against the entry limit above, so a directory of long chains cannot buy more work than a directory of files.\n\n> **`.agents/skills/` ownership note:** `.agents/skills/` is not an AGENTS.md convention — the AGENTS.md standard defines only `AGENTS.md` itself. It is the [Agent Skills](https://agentskills.io/specification) project location, which the native `agentsskills` target writes. Several targets write there — `agentsskills`, `agentsmd`, `aiassistant`, `codexcli`, `amp`, `zed`, `replit` and both Antigravity targets — because they all implement the same convention. Each native target writes its own documented frontmatter, so enabling more than one and reordering `--targets` can change which optional keys end up in the file; that is inherent to several tools sharing one path and is not specific to any of them.\n\n> The **simulated** `agentsmd` writer is the exception that is fixed: it has no frontmatter model of its own (the AGENTS.md standard defines no skills at all), so it used to overwrite the native output with a bare `name`/`description` pair and silently drop `license`, `compatibility`, `metadata` and `allowed-tools`. It now emits exactly what `agentsskills` emits, so a simulated writer can never degrade the file a native target owns.\n\n> **Cross-root duplicate note:** Several targets discover skills in more than one root — a shared Agent Skills root beside the tool-specific one (`junie`, `vibe`, `kimi-code`, `rovodev`, `augmentcode`), nested `.claude/skills/` directories (`claudecode`), or roots the tool's own config points at (`opencode`). The roots are scanned in precedence order and the first one to claim a skill name keeps it; the multi-root subagent targets follow the same rule, and for targets whose native format aggregates many subagents into one file (Roo's `.roomodes`) the same de-duplication is applied to the paths the entries fan out to. The comparison is **case-insensitive** (and Unicode normalizing), because every imported skill is written back into a single `.rulesync/skills/` tree, where `.junie/skills/my-skill` and `.agents/skills/My-Skill` are one directory on macOS and Windows — comparing the names exactly would let both through, and the shared copy, written last, would overwrite the tool-specific one, inverting the precedence the roots were ordered by. A collision that differs only in case is reported with a warning naming the ignored copy; an exact repeat stays quiet, being the ordinary overlay. Kimi Code is the exception on both counts: it identifies a skill or subagent by its frontmatter `name` folded to lower case, so two spellings are already one name upstream and the duplicate is resolved silently. **Trade-off:** the rule applies on every platform, so on a case-sensitive filesystem — where the two really are separate skills — `rulesync import` and `rulesync convert` drop the lower-precedence one instead of importing it under its own name. Rename one of them if you need both — and if the dropped copy lives in a shared `.agents/skills/` root, import `agentsskills` in the same run, so the skill still reaches `.rulesync/` and a later `agentsskills` generate does not prune it as an orphan. Slash commands are not covered by this rule yet: `augmentcode` reads both `.augment/commands/` and the shared `.agents/commands/`, but their names are still compared exactly, so `deploy.md` and `Deploy.md` are both imported and collide in `.rulesync/commands/` on a case-insensitive filesystem ([issue #2741](https://github.com/dyoshikawa/rulesync/issues/2741)).\n\n> **Claude Code nested skills note:** Claude Code v2.1.178+ also loads skills from **nested** `.claude/skills/` directories below the working directory (a skill in `apps/web/.claude/skills/` becomes available when working on files there, and a name clash with a root skill keeps both under a directory-qualified name like `apps/web:deploy`). `rulesync import --targets claudecode --features skills` discovers those nested directories (import-only, lenient, same dependency/build-directory exclusions as the nested `AGENTS.md` scan; symlinks not followed) so an existing nested skill is no longer invisible. On a name clash the root skill wins the import — rulesync's flat skill namespace cannot express the qualified variant. Because generation stays targeted at the project-root `.claude/skills/`, a nested skill's location-based scoping would otherwise be lost, so the import derives it: a skill found in `apps/web/.claude/skills/` gets `claudecode.paths: [\"apps/web/**\"]` written for it. Glob metacharacters in the directory names are escaped, so a Next.js-style `app/[slug]/.claude/skills/` still derives a literal match. A `paths` value the skill already declares is kept as-is — Claude Code does not document whether a nested skill's `paths` resolves against the project root or its own directory, so rulesync does not rewrite the author's glob, which means a declared value narrower than the subtree (`src/**`) is re-anchored at the project root once the skill moves there; write it subtree-qualified (`apps/web/src/**`) if that matters. Root-discovered skills get nothing added, and the derived value lands in the `claudecode:` block only — other targets with their own `paths` field (`cursor:`, `qwencode:`) are untouched. To scope a skill's _activation_ to a subtree yourself, write the `paths` frontmatter, or run a separate generate with `--output-roots <subdir>` for physical co-location.\n\n> **Note:** `claudecode.disallowed-tools` (a space/comma-separated string or a YAML list) removes the listed tools from the model while the skill is active. The same field is available on Claude Code slash commands. Both round-trip through the `claudecode` frontmatter section.\n\n> **Note:** Codex CLI reads UI metadata, invocation policy, and tool dependencies from an `agents/openai.yaml` sidecar next to `SKILL.md` (Codex's `SKILL.md` frontmatter only carries `name` and `description`). When `codexcli.interface`, `codexcli.policy`, or `codexcli.dependencies` is present, Rulesync emits `.agents/skills/<name>/agents/openai.yaml` and reads it back on import. If the sidecar is emitted and `interface.short_description` is absent, the legacy `codexcli.short-description` is routed there. See the [Codex skills docs](https://developers.openai.com/codex/skills.md).\n\n> **Takt-driven Codex note:** Rulesync's `codexcli` skills land in `.agents/skills/` (project) and `~/.agents/skills/` (global), but a Takt workflow driving Codex does **not** inherit repository or user skills from there by default — upstream's wording is \"TAKT workflows do not inherit repository or user Codex Skills by default\" — so skills you generated will not reach a Takt-driven Codex run unless you turn inheritance on. (`takt exec` is the documented exception: each scope defaults to inheritance when it is not explicitly configured.) The setting is `provider_options.codex.skills.repo` for the project tree and `.user` for the global one, added in Takt 0.53.0. **Where it goes depends on your Takt version.** Up to 0.55.x, and on any later version whenever `runtime.yaml` is inactive (a file carrying only `version: 1` counts as inactive and leaves the legacy resolution in place), it belongs in `provider_options` in `.takt/config.yaml` — which is also where a `takt` block in `.rulesync/permissions.*` writes it. From 0.56.0, `runtime.yaml` owns provider configuration, and while it is active **any** legacy provider setting in `config.yaml` — `provider_options` included — stops Takt with `Mixed provider configuration detected` before it runs an agent. Takt generates `~/.takt/runtime.yaml` active on first launch in a fresh environment, so a new install is in runtime mode by default; there, set the flag in `runtime.yaml` under the `options` of a profile whose provider is Codex, and keep `provider_options` out of `config.yaml`. Mind the shape when you move it: a profile's `options` is a **flat bag applying to that profile's own provider**, so the `codex` segment is dropped — `options: { skills: { repo: true } }`, not `options: { codex: { skills: { repo: true } } }`. The nested spelling is not a schema error; it is simply never read, so inheritance stays off while the config looks right. Takt 0.57.0 adds a workflow-side alternative to writing `provider_options` inline: a workflow, step, or parallel sub-step can declare `capabilities: enable-skills`, a bundled preset covering the Codex repo and user skills. Takt 0.55.0 made the same default change for Claude providers (`provider_options.claude.skills.enabled`, plus `--disable-slash-commands` on CLI-backed ones), so Rulesync-generated Claude Code skills and slash commands are off in Takt-driven sessions unless re-enabled the same way. See the [Takt configuration docs](https://github.com/nrslib/takt/blob/main/docs/configuration.md) and [CHANGELOG](https://github.com/nrslib/takt/blob/main/CHANGELOG.md).\n\n> **Reasonix note:** Reasonix discovers Anthropic-style directory-layout skills (`<name>/SKILL.md`) under `.reasonix/skills/` (project) / `~/.reasonix/skills/` (global, via `--global`). Rulesync emits the portable `name`/`description` frontmatter (Reasonix supports additional optional keys, but only that pair is modeled); the schema is loose, so any extra keys on an imported `SKILL.md` survive the round-trip. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md).\n\n> **Meta Muse Code note:** Muse Code discovers Agent Skills (`<skill-id>/SKILL.md`) under `.agents/skills/` (project) and under `$XDG_CONFIG_HOME/muse/skills` plus `~/.agents/skills` (user). Rulesync emits the shared `.agents/skills/` directory in project mode and only the XDG-default `~/.config/muse/skills` in global mode (via `--global`), so a skill is written exactly once. Muse Code's compatibility scans of repo-local `.codex/skills` and `.claude/skills` belong to other tools and are not emitted for `musecode`. Only the portable `name`/`description` frontmatter pair is modeled; the schema is loose, so extra keys on an imported `SKILL.md` survive the round-trip. See the [Muse Code extending docs](https://dev.meta.ai/docs/muse-code/extending.md).\n\n> **Hermes Agent note:** Hermes skills are global-only under `~/.hermes/skills/<name>/SKILL.md`. Standard Agent Skills fields (`license`, `compatibility`, and `allowed-tools`) round-trip through `agentsskills` and are normalized to the Agent Skills spec shapes described above (so `allowed-tools` is written and imported the same way as for `agentsskills`); Hermes-native fields such as `version`, `author`, `platforms`, `environments`, `required_environment_variables`, `required_credential_files`, and `metadata.hermes` round-trip through `hermesagent`. Canonical `name` and `description` always own those two frontmatter keys.\n\n> **Kimi Code note:** Kimi Code discovers skills under `.kimi-code/skills/` (project) and `~/.kimi-code/skills/` (global), plus the shared `.agents/skills/` root at either scope. Rulesync generates the recommended directory layout (`<name>/SKILL.md`) and imports both that layout and flat `<name>.md` skills; for flat files, a missing `name` comes from the filename and a missing `description` falls back to the first non-empty body line (up to 240 characters), matching Kimi. Imported skills are written to `.rulesync/skills/<logical-name>/SKILL.md`, using the normalized logical frontmatter name rather than the source directory or filename. Duplicate precedence follows Kimi's case-insensitive logical frontmatter `name`: the Kimi-specific root takes precedence over `.agents/skills/`, and a directory skill takes precedence over a same-named flat file within one root. Shared roots are import-only and are never removed by Kimi-target orphan deletion. Besides `name`/`description`, Rulesync maps Kimi's `type`, `whenToUse`, `disableModelInvocation`, and `arguments` frontmatter through the `kimi-code:` block and preserves supporting files beside directory-layout `SKILL.md`. The shared top-level `disable-model-invocation` value supplies the Kimi flag unless the tool-specific block overrides it. See the [Kimi Code Agent Skills docs](https://moonshotai.github.io/kimi-code/en/customization/skills.html).\n\n> **ZCode note:** ZCode discovers Anthropic-style directory-layout skills (`<name>/SKILL.md`) and invokes them with `$`. The documented location is the user one, `~/.zcode/skills/`; the workspace scope its import dialog offers is taken to be served from the project's own `.zcode/skills/`, so rulesync writes `.zcode/skills/<name>/SKILL.md` in project mode and `~/.zcode/skills/<name>/SKILL.md` with `--global`. That project path is inferred from the import dialog and from ZCode's other workspace assets, not documented. Only the portable `name`/`description` pair is modeled; the schema is loose, so an imported `SKILL.md` carrying extra keys still parses, but — as with every other skill target — only that pair is carried into the canonical skill. ZCode rejects a `description` longer than 1024 characters and truncates a body past 100KB when it loads the skill; rulesync does not enforce either limit, since the canonical skill is shared with every other target. See the [ZCode skills docs](https://zcode.z.ai/en/docs/skill).\n\n## `.rulesync/mcp.jsonc`\n\n`.rulesync/mcp.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/mcp.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nExample:\n\n```json\n{\n  \"mcpServers\": {\n    \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json\",\n    \"serena\": {\n      \"description\": \"Code analysis and semantic search MCP server\",\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/oraios/serena\",\n        \"serena\",\n        \"start-mcp-server\",\n        \"--context\",\n        \"ide-assistant\",\n        \"--enable-web-dashboard\",\n        \"false\",\n        \"--project\",\n        \".\"\n      ],\n      \"env\": {}\n    },\n    \"context7\": {\n      \"description\": \"Library documentation search server\",\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@upstash/context7-mcp\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### Tool-scoped server blocks (`{toolname}.mcpServers`)\n\nServers under the shared `mcpServers` key are emitted to every targeted tool. To scope a server to a single tool, add a tool-scoped `{toolname}` block alongside it — mirroring `{toolname}.hooks` in `.rulesync/hooks.jsonc` and `{toolname}.permission` in `.rulesync/permissions.jsonc`:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"shared-server\": { \"type\": \"stdio\", \"command\": \"echo\" },\n  },\n  \"claudecode\": {\n    \"mcpServers\": {\n      // Added only to Claude Code's MCP config.\n      \"claude-only-server\": { \"type\": \"http\", \"url\": \"https://example.com/mcp\" },\n      // `null` removes a shared server for Claude Code only.\n      \"shared-server\": null,\n    },\n  },\n}\n```\n\n- A tool-scoped entry with the same name as a shared server **replaces it wholesale** for that tool (no field-level merge).\n- A tool-scoped entry set to `null` **removes** the shared server for that tool.\n- Any MCP-capable `--targets` name is accepted as a block key (`claudecode`, `cursor`, `codexcli`, ...). Targets that share one output file resolve identically so the shared file never depends on generation order: the deprecated `claudecode-legacy` target reads the `claudecode` block; the `kiro-cli` / `kiro-ide` targets read the `kiro` block (all three write the same `.kiro/settings/mcp.json`); and the `antigravity-ide` / `antigravity-cli` targets both apply both `antigravity-*` blocks in a fixed order (`antigravity-ide` first, then `antigravity-cli` — the CLI block wins per server) because they share their output file at both scopes (`.agents/mcp_config.json` in project mode, `~/.gemini/config/mcp_config.json` in global mode).\n\n> **Generation filter: per-server `enabled`.** Set `\"enabled\": false` on a server (in the shared map or a tool-scoped block) to keep the definition in the source file while emitting it to **no** tool config at all — a temporary off switch that does not lose the entry. Omitted means enabled, so existing configs keep generating everything; writing `\"enabled\": true` is opt-in clarity. This is distinct from the canonical `disabled`, which is a **pass-through** field the tools read (written as `disabled: true`, or translated to each tool's own spelling): `enabled: false` wins and drops the server entirely, while `disabled` only matters for servers still emitted. The field is rulesync-source-only and never reaches generated output — several tools (OpenCode, Kilo, Grok CLI, Goose) have a native `enabled` field with different semantics — and import never invents it: a tool's native enabled/disabled state keeps mapping to the canonical `disabled` (though a stray hand-written `enabled` in a passthrough-imported tool file does come back as the canonical filter). Two edges to know: a tool-scoped entry **replaces the shared entry wholesale**, so a same-named tool-scoped entry without `enabled: false` re-emits the server for that tool (per-tool re-enabling); and on merge-style shared configs (e.g. Hermes Agent's `config.yaml`), disabling a previously generated server stops writing it but does not remove the already-written entry — same as deleting the definition.\n\n> **Deprecated: per-server `targets`.** The older per-server `\"targets\": [\"tool\", ...]` array is still honored as a filter (a missing value or `[\"*\"]` means every tool), but it is deprecated and logs a warning at generate time. Migrate by moving the server into the matching `{toolname}.mcpServers` block(s).\n\n> **JetBrains AI Assistant note:** Rulesync writes the native `{ \"mcpServers\": { ... } }` configuration to `.ai/mcp/mcp.json` in project mode and `~/.ai/mcp/mcp.json` in global mode. Both scopes support STDIO and remote server entries using the shape documented in [JetBrains AI Assistant's MCP guide](https://www.jetbrains.com/help/ai-assistant/mcp.html).\n\n#### JSON Schema Support\n\nRulesync provides a JSON Schema for editor validation and autocompletion. Add the `$schema` property to your `.rulesync/mcp.jsonc`:\n\n```json\n{\n  \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json\",\n  \"mcpServers\": {}\n}\n```\n\n### Transport types (`type` / `transport`)\n\nThe `type` (and the equivalent `transport`) field accepts `local`, `stdio`, `sse`, `http`, `ws`, and `streamable-http`. `streamable-http` is the MCP specification's name for the HTTP transport and is accepted as an alias of `http`, so configurations copied from a server's documentation work unchanged. `ws` is the WebSocket transport (a persistent bidirectional connection) and accepts the same `url`/`headers`/`headersHelper`/`timeout` fields as `http`. Tools that do not recognize a given transport keep it on round-trip but may ignore it at runtime.\n\n> **OpenCode skills note:** on import, Rulesync also reads the `skills.paths` array of `opencode.json` / `opencode.jsonc` (\"Additional paths to skill folders\") and scans each entry as an extra skill root, so skills a project keeps outside `.opencode/skills/` are no longer invisible to `rulesync import`. These roots are import-only — generation keeps writing to Rulesync's own managed root — and a skill of the same name found in a managed root still wins. Each entry is resolved against the directory the config was read from — the project root in project mode, `~/.config/opencode/` in global mode — which is what OpenCode itself does. An absolute path, or one that escapes that directory, is ignored, and a directory under a configured root that is not a skill is skipped with a warning rather than failing the run, since a configured root is arbitrary user territory. `skills.urls` is a remote-fetch surface and is out of scope for a file-based generator.\n\n> **Kilo Code note:** Kilo's MCP config uses its own native shape in `kilo.jsonc` (`type: \"local\" | \"remote\"`, `environment`, `enabled`, `command` as an array). Rulesync maps `stdio`/`local` ⇄ Kilo `local` and `http`/`sse` ⇄ Kilo `remote`; on import, Kilo `remote` is normalized to the canonical `http` transport (the deprecated `sse` is no longer emitted). The Kilo-specific `timeout` (local + remote, a positive integer in milliseconds) and `oauth` (remote only — either an OAuth-config object or `false` to disable auto-detection) fields are preserved on round-trip. The `kilo.jsonc` `skills` config key (`skills.paths` for extra skill locations and `skills.urls` for remote skill manifests) is likewise preserved when Rulesync writes the file. A bare `{\"enabled\": false}` entry — Kilo's way of switching off a server another config layer defines, such as the global config or a marketplace — round-trips as itself: it imports as a canonical server carrying only `disabled: true`/`disabled: false` and no transport, and a server in that shape is written back as `{\"enabled\": …}` rather than as a local server with an empty command it cannot start. The enabled state has to be stated outright in both directions: for a transport-less server that says nothing about `disabled`, a toggle already in `kilo.jsonc` is left exactly as it is, and if there is none the server is skipped with a warning — a toggle overrides the layer that defines the server, so writing `enabled: true` for it would switch back on what you turned off there. Kilo's per-tool `enabledTools`/`disabledTools` reach the generated file at all now — they used to be stripped before this adapter saw them, so a filter read out of `kilo.jsonc` was deleted from it on the next generate. A skipped server's filters are written to the `tools` map either way, since that map is keyed by server name and reaches servers `mcp` does not list; on import, a `tools` entry naming no listed server comes back as a server carrying nothing but the filters, so it survives the round-trip. A server with no transport — a toggle, or one of those filter-only entries — is imported into the tool-scoped `kilo.mcpServers` block rather than the shared `mcpServers` map, because an entry with no command and no url is a server the other tools' configs cannot start. All of this applies equally to OpenCode: its published schema carries the same bare-toggle union member, it round-trips a toggle as itself under the same explicit-state rule, its `tools` map works the same way, and its transport-less servers land in `opencode.mcpServers`. The entry must carry no field of a local or remote server (`type`, `command`, `url`, `headers`, `environment`, `cwd`, `timeout`, `oauth`); an entry that is malformed in some other way still fails loudly rather than being quietly read as a toggle and written back with its command, headers, or OAuth secrets gone, while an unrelated key Kilo adds later is accepted rather than failing the run (it is not carried across the round-trip, though — a toggle imports as its enabled state and nothing else). Since a toggle keeps nothing but its enabled state, a canonical server that declares no transport but still carries fields such as `args` or `env` is written as a toggle with those fields dropped and a warning naming them. A server that names a transport it cannot reach — a `type` with no `command`, an `http` with no `url` — is skipped with a warning instead, because `{\"type\": \"local\", \"command\": []}` is a server Kilo cannot start. An existing `kilo.jsonc` carrying that shape (earlier Rulesync versions wrote it) imports as a server with no transport rather than failing the run. The same applies to OpenCode, whose config uses the same shape. Rejecting it used to fail the whole `--targets kilo` run rather than the MCP feature alone, because `kilo.jsonc` is the file the rules feature writes too.\n\n> **Zed note:** Zed configures MCP servers under `context_servers` in its shared settings file (`.zed/settings.json` project, `~/.config/zed/settings.json` global — `%APPDATA%\\Zed\\settings.json` on Windows), whose value is an untagged shape with no `type` field: a stdio server is `{\"command\": <string>, \"args\", \"env\", \"timeout\"}`, a remote one `{\"url\", \"headers\", \"timeout\"}`, and an extension-provided one neither. Rulesync translates the canonical fields into those shapes instead of forwarding them verbatim (which used to hand Zed keys it silently ignores — most seriously `disabled: true`, which left the server **enabled**): `disabled: true` becomes `enabled: false` (and imports back as `disabled: true`), the `httpUrl` alias is normalized to `url`, an array `command` is flattened to Zed's single command string with the rest prepended to `args`, and canonical-only fields (`type`/`transport`, `alwaysAllow`, `trust`, `cwd`, `networkTimeout`, the Kiro lists) are dropped. Fields rulesync does not model — a remote server's `oauth` block, an extension server's `settings` — pass through untouched, so they are best authored in the tool-scoped `zed.mcpServers` block. A server Zed cannot start is skipped with a warning rather than written broken: an `sse` or `ws` server (Zed has neither transport), a remote server with no `url`, a local one with no `command`. A server with no transport at all is written as Zed's extension-provided variant, and on import such an entry lands in the tool-scoped `zed.mcpServers` block rather than the shared `mcpServers` map, since other tools cannot start it.\n\n> **Kimi Code note:** MCP servers are written to `.kimi-code/mcp.json` (project) and `~/.kimi-code/mcp.json` (global). Kimi Code supports stdio, HTTP, and SSE plus `env`, `cwd`, `headers`, `bearerTokenEnvVar`, `enabled`, `startupTimeoutMs`, `toolTimeoutMs`, `enabledTools`, and `disabledTools`; Rulesync preserves the canonical fields that Kimi accepts. Canonical `local` maps to stdio and `streamable-http` maps to HTTP. WebSocket servers are skipped with a warning because Kimi has no WebSocket transport. A `kimi-code` block may also carry `startupTimeoutMs` / `toolTimeoutMs`, which are **not** per-server: they become Kimi's `[mcp] startup_timeout_ms` / `tool_timeout_ms` defaults in the shared global `~/.kimi-code/config.toml`, applying to every MCP server including ones Rulesync did not write (a per-server value in `mcp.json` still wins). Global scope only, since `config.toml` has no project counterpart, and merged in place so the `hooks` and `permission` sections of the same file survive. The merge is per key: authoring only one of the two timeouts leaves a hand-written sibling alone, and dropping the override entirely leaves the section as it stands rather than deleting it — remove the keys from `config.toml` by hand if you want them gone. See the [Kimi Code MCP docs](https://moonshotai.github.io/kimi-code/en/customization/mcp.html) and [config-files reference](https://moonshotai.github.io/kimi-code/en/configuration/config-files.html#mcp).\n\n> **Hermes Agent note:** Hermes MCP servers live under `mcp_servers` in the shared `~/.hermes/config.yaml`. Rulesync preserves OAuth fields (`redirect_uri`, `redirect_host`, `redirect_port`, `client_id`, `client_secret`, and `scopes`) plus `idle_timeout_seconds`, `max_lifetime_seconds`, `ssl_verify` (`true`/`false` or a PEM CA-bundle path), `skip_preflight`, `keepalive_interval` (liveness ping cadence in seconds), `trust` (`full` or `untrusted`, where every write-capable tool call needs approval — copied verbatim, since Hermes reads any unrecognized value as `untrusted`), and the `sampling`, `elicitation`, and `identity_header` mappings (carried as opaque objects so new sub-keys keep working). A canonical `sse` server is written with Hermes's own `transport: sse` (v0.20.0) and imports back as `type: \"sse\"`; without it Hermes connects to a `url` server over Streamable HTTP, so the transport would silently change. Streamable HTTP is Hermes's default and stays implicit. On import, portable server fields remain in shared `mcpServers`; Hermes-only fields are isolated in the full `hermesagent.mcpServers.<name>` replacement block so they cannot leak to other targets.\n\n> **Devin note:** Since Devin v3000.3 (the Local 3.6 release), MCP servers live in a dedicated `mcpServers`-keyed file: `.devin/mcp_config.json` (project) and `~/.config/devin/mcp_config.json` (global, via `--global`). The file is MCP-only and rulesync-owned (rewritten whole, deletable), unlike the shared `.devin/config.json` that permissions and hooks keep patching in place. Rulesync no longer writes the legacy `config.json` `mcpServers` key — Devin auto-migrates it away on startup, so re-seeding it would fight the migration — but import still falls back to that key when no `mcp_config.json` exists, so pre-v3000.3 repos migrate cleanly. The gitignored personal override `.devin/mcp_config.local.json` is never read or written (it is covered by the derived `.gitignore`). See the [Devin MCP configuration docs](https://docs.devin.ai/cli/extensibility/mcp/configuration).\n\n> **Warp note:** Warp reads file-based MCP servers from `.warp/.mcp.json` (project) and `~/.warp/.mcp.json` (global). Warp spells the working directory `working_directory` (used for resolving relative paths), so the canonical `cwd` is translated to it on generate and back on import; a tool-native `working_directory` already on the server wins over `cwd`. See the [Warp MCP docs](https://docs.warp.dev/agent-platform/capabilities/mcp/).\n\n> **Takt note (partial / transport-allowlist only):** Takt does **not** have a project- or global-level registry of MCP server _definitions_. The concrete `mcp_servers` map (`command`/`args`/`env` or `type`/`url`/`headers`) is declared **per workflow step** inside individual workflow YAML files; there is no top-level `mcp_servers` key in `config.yaml`, and Takt's config loader hard-rejects unknown top-level keys (introduced with MCP support in [Takt v0.21.0](https://github.com/nrslib/takt/blob/main/CHANGELOG.md)). What `config.yaml` _does_ hold is the **default-deny transport allowlist** `workflow_mcp_servers: { stdio, sse, http }` — without it, workflow-defined MCP servers are refused regardless of how they are declared. So Rulesync emits **only** this allowlist into the shared `.takt/config.yaml` (project) / `~/.takt/config.yaml` (global), enabling exactly the transports your `.rulesync/mcp.jsonc` servers use (`local`/`stdio` ⇒ `stdio`; `sse` ⇒ `sse`; `http`/`streamable-http`/`ws` ⇒ `http`). The merge is in place — every other top-level key (`provider`, `provider_profiles`, …) is preserved and the file is never deleted. **Documented lossiness:** per-server names, commands, env, URLs, and headers are not representable in `config.yaml` and are intentionally **not** written; you still declare the concrete servers in your workflow YAML steps, and Rulesync only opens the transport gate that permits them. As a corollary, **import** cannot reconstruct server definitions from a transport allowlist and yields an empty `mcpServers` map. See the [Takt configuration docs](https://github.com/nrslib/takt/blob/main/docs/configuration.md).\n\n### MCP Tool Config (`enabledTools` / `disabledTools`)\n\nYou can control which individual tools from an MCP server are enabled or disabled using `enabledTools` and `disabledTools` arrays per server.\n\n```json\n{\n  \"mcpServers\": {\n    \"serena\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/oraios/serena\", \"serena\", \"start-mcp-server\"],\n      \"enabledTools\": [\"search_symbols\", \"find_references\"],\n      \"disabledTools\": [\"rename_symbol\"]\n    }\n  }\n}\n```\n\n- `enabledTools`: An array of tool names that should be explicitly enabled for this server.\n- `disabledTools`: An array of tool names that should be explicitly disabled for this server.\n\n> **Kiro note:** Kiro MCP servers are written under `mcpServers` in `.kiro/settings/mcp.json` (project) and `~/.kiro/settings/mcp.json` (global). Kiro supports `disabledTools` natively and Rulesync preserves it on generate and import. Kiro does not expose a corresponding per-server `enabledTools` allowlist, so that field is omitted for Kiro targets. The two Rulesync-only authoring keys are translated onto the field names Kiro actually reads: `kiroAutoApprove` becomes `autoApprove` (tools run without a confirmation prompt) and `kiroAutoBlock` becomes `disabledTools` (tools hidden from the agent). A server that already spells `autoApprove` or `disabledTools` natively keeps working — the two lists are merged rather than one overwriting the other. On import, `autoApprove` is lifted back into `kiroAutoApprove`; `disabledTools` stays as-is because it is already a canonical Rulesync field with the same meaning, so `kiroAutoBlock` has no import counterpart. That makes `kiroAutoBlock` a redundant spelling of `disabledTools`: a Kiro config imported after a generate comes back as canonical `disabledTools`, which then also reaches the other targets that support it. Prefer authoring `disabledTools` directly, which makes that scope explicit from the start.\n\n> **Roo Code / Zoo Code note:** Both targets write `.roo/mcp.json` through the same adapter, and their per-server MCP schema is **denylist-only**: `disabledTools` clears each named tool's `enabledForPrompt` (the tool stops being offered to the model), and there is no corresponding `enabledTools` allowlist, so that field is omitted for these targets. The server config is emitted verbatim, so `disabledTools` round-trips as itself. Earlier Rulesync versions stripped it before the adapter saw it, which meant a filter you had written into `.roo/mcp.json` by hand — or through Zoo Code's own tool toggles, which write the same key — was deleted on the next generate.\n\n> **deepagents note:** MCP servers are written to `.deepagents/.mcp.json` (project) / `~/.deepagents/.mcp.json` (global). Two translations apply, because dcode **drops an individual server it cannot validate** — the rest of the file still loads, so a mistake here is silent rather than loud. **Transports:** dcode accepts only `stdio`, `sse` and `http` (plus the aliases `streamable_http` / `streamable-http` → `http`), so canonical `local` is written as `stdio` and `streamable-http` as `http`; canonical `ws` has no counterpart and the server is skipped with a warning at generate time, where you can still see it. Whether the value lands under `type` or `transport` follows whichever key you authored — dcode reads the two interchangeably, and with neither set it infers `http` from a `url` and `stdio` otherwise. On import, both spellings of the `streamable_http` alias come back as canonical `http`. **Tool filters:** canonical `enabledTools` becomes `allowedTools` (dcode never reads `enabledTools`, and it ignores unknown keys silently, so forwarding the canonical name would be a no-op), while `disabledTools` carries its own name; each entry is a tool name or an `fnmatch` glob, and import lifts `allowedTools` back. Upstream rejects a server that sets **both** filters and rejects an **empty** list, and each case is resolved the way that does not hand the model more tools than your canonical config allows. Setting both is valid canonically — other targets apply the two lists independently — but has no form here, so the **server is skipped** with a warning rather than written without filters, which would leave it running with every tool including the denied ones. An empty `enabledTools` likewise **skips the server**, since an allowlist of nothing means no tools at all and dropping the key would publish all of them. An empty `disabledTools` is the one genuine no-op, so only that key is dropped (with a warning) and the server is still written. See the [MCP tools docs](https://docs.langchain.com/oss/deepagents/code/mcp-tools).\n\n> **Qwen Code note:** MCP servers are written to the `mcpServers` key of `.qwen/settings.json` (project) / `~/.qwen/settings.json` (global, via `--global`). Qwen supports stdio (`command`/`args`), SSE (`url`), and HTTP (`httpUrl`) transports. Rulesync maps the canonical per-server `enabledTools` ⇄ Qwen's `includeTools` (allowlist) and `disabledTools` ⇄ Qwen's `excludeTools` (denylist). Other top-level keys in `settings.json` are preserved on round-trip.\n\n> **Codex CLI server-name note:** Codex requires MCP server names matching `[a-zA-Z0-9_-]+`, so Rulesync auto-normalizes non-conforming names on generate (lowercase, runs of other characters become `_`, leading/trailing `_` trimmed) — e.g. `Postgres MCP - Production - Read Only` becomes `postgres_mcp_production_read_only`. If two names normalize to the same Codex name, the last processed server overwrites the earlier one (with a warning). A name with no representable characters at all (e.g. a fully Japanese name) falls back to a stable hash-derived name like `mcp_1a2b3c4d` instead of being dropped; rename the server in `.rulesync/mcp.jsonc` to pick a readable Codex name. This normalization is one-way: importing back from the generated `config.toml` yields the normalized name, not the original.\n\n> **Codex CLI key-translation note:** Codex's `[mcp_servers.<name>]` table reads its own field names, so the canonical fields are translated rather than forwarded. `headers` is written as `http_headers` (and imports back as `headers`), which Codex accepts only on a url-based server — on a stdio server it is a load error upstream, so the headers are dropped with a warning instead. The canonical millisecond timeouts become Codex's second-based ones: `timeout` ⇄ `tool_timeout_sec` (the default timeout for tool calls) and `networkTimeout` ⇄ `startup_timeout_sec` (initialize + list-tools), dividing by 1000 on generate and multiplying on import, so a sub-second remainder is emitted as a fraction. Codex also accepts `startup_timeout_ms`, which imports verbatim into `networkTimeout` unless the config sets `startup_timeout_sec` too — Codex prefers the seconds spelling when both are present, and so does Rulesync. The canonical `tools` array is **not** written: Codex declares `tools` as a table of per-tool approval settings (`tools.<tool>.approval_mode`), and an array where it expects a table is a hard deserialization error that takes the whole server entry down, so it is dropped with a warning — use `enabledTools` / `disabledTools`, which map onto Codex's `enabled_tools` / `disabled_tools`. For the same reason the approval table is never imported into the canonical model; it stays in `config.toml`, where the approval-preserving merge carries it across regenerates. Both timeouts must be non-negative: Codex builds a duration out of them and errors on a negative value, which fails the whole file, so such a value is dropped with a warning. Canonical fields Codex has no counterpart for (`type`/`transport` — Codex infers the transport from `command` versus `url` — plus `alwaysAllow`, `trust`, and the Kiro lists) are dropped silently; on import a server carrying a `url` and no `command` gets `type: \"http\"` restated, so a config read out of Codex still reaches the tools that branch on the transport. That restatement is one-way, like the server-name normalization: Codex's only remote transport is `streamable_http`, so a canonical `sse` (or `ws`, or `streamable-http`) server comes back from a round-trip as `http`. Fields Rulesync does not model, such as `env_http_headers` and `bearer_token_env_var`, pass through under their own names.\n\n### Codex-specific: pass shell env vars to MCP servers (`envVars`)\n\nCodex CLI supports a per-server array of shell env var names to inherit when launching the MCP server process. The source schema uses `envVars` (camelCase, matching the project convention used by sibling fields like `enabledTools`/`disabledTools`); the codex generator renames it to `env_vars` (snake_case) for codex's native `config.toml` format.\n\nThis is distinct from `env` (which is a literal `{name: value}` map) — `envVars` is a list of names whose **values come from the user's environment at runtime**. Both fields may coexist on the same server.\n\n```json\n{\n  \"mcpServers\": {\n    \"pal\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/BeehiveInnovations/pal-mcp-server.git\",\n        \"pal-mcp-server\"\n      ],\n      \"envVars\": [\"OPENAI_API_KEY\", \"OPENROUTER_API_KEY\", \"GEMINI_API_KEY\"]\n    }\n  }\n}\n```\n\nGenerated `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.pal]\ntype = \"stdio\"\ncommand = \"uvx\"\nargs = [\"--from\", \"git+https://github.com/BeehiveInnovations/pal-mcp-server.git\", \"pal-mcp-server\"]\nenv_vars = [\"OPENAI_API_KEY\", \"OPENROUTER_API_KEY\", \"GEMINI_API_KEY\"]\n```\n\nAn entry may also be an object naming the environment to read the variable from: `{ \"name\": \"REMOTE_TOKEN\", \"source\": \"remote\" }` reads it from the remote executor environment (and requires remote MCP stdio support), while a bare name and `\"source\": \"local\"` read from Codex's own environment. The object form is written to `config.toml` as an inline table, matching Codex's documented shape. Only `name` and `source` are accepted in that object — Codex rejects an unknown key there, and rejecting one server's entry would take the whole `config.toml` down with it, so Rulesync fails on the canonical file instead. For the same reason an entry that a `config.toml` already holds in some other shape is dropped with a warning on import rather than written into a `.rulesync/mcp.jsonc` the next generate would refuse.\n\n- Emitted only into the codex CLI output. Stripped from `RulesyncMcp.getMcpServers()` so it does not appear in other tools' generated configs (Claude Code, Kilo, OpenCode, Gemini CLI, Cursor, Cline, Junie, Factorydroid, Rovodev, etc.).\n- Use this for secrets and API keys you do not want literal-encoded into a committed `mcp.json`.\n- Precedence: codex CLI resolves these names from the user's runtime shell environment. If a name is also set in `env` (literal value), the codex CLI behavior is upstream-defined; see the [Codex configuration reference](https://developers.openai.com/codex/config-reference#mcp_serversid-env_vars) (last checked 2026-05-13) for the exact resolution rule.\n\n### Codex-specific: run a stdio server remotely (`experimentalEnvironment`)\n\nFor stdio servers, `experimentalEnvironment: \"remote\"` starts the server through a remote executor environment when one is available. It is written as `experimental_environment` in `config.toml`. Like `envVars`, it is stripped before every other tool's MCP config is written, so it cannot leak into a config that would not understand it — and for the same reason, a server config copied straight out of a `config.toml` may spell it `experimental_environment`, which is accepted and normalized on the way to Codex.\n\nSee the [Codex MCP reference](https://learn.chatgpt.com/docs/extend/mcp) for both fields.\n\n#### Codex-specific: OAuth client id (`oauth.clientId` → `client_id`)\n\nA server's `oauth` block is preserved in the canonical Claude Code shape (camelCase `clientId`), but Codex CLI reads the OAuth client id from snake_case `oauth.client_id`. Without it, `codex mcp login <server>` falls back to dynamic client registration and fails for providers that do not support it (e.g. Slack). The codex generator therefore **duplicates** `clientId` into a sibling `client_id`, keeping the camelCase key so tools that expect it keep working:\n\n```toml\n[mcp_servers.slack.oauth]\nclientId = \"1601185624273.8899143856786\"\nclient_id = \"1601185624273.8899143856786\"\ncallbackPort = 3118\n```\n\nOnly a string `clientId` is duplicated (a non-string value would not be a usable OAuth client id), and an explicit `client_id` already present in the source is left untouched. On import, `client_id` collapses back to the canonical `clientId` (and is dropped when both are present) so the round-trip stays stable.\n\n> **Grok CLI note:** MCP servers are written to a `[mcp_servers.<name>]` table in `.grok/config.toml` (project) / `~/.grok/config.toml` (global, via `--global`). The file is treated as shared Grok config: Rulesync only replaces the `mcp_servers` key and preserves every other table on round-trip, and it is never deleted. Unlike Codex CLI, Grok uses a literal `env` table (it does not support the `env_vars` runtime-passthrough list) and has no per-server tool allow/deny lists, so the only field rename is `disabled` (rulesync) ⇄ `enabled = false` (grok); an active server simply omits `enabled`. Servers with no environment variables are emitted without a dangling `[mcp_servers.<name>.env]` table (empty nested tables are stripped), and a server whose entire configuration would be empty is dropped with a warning.\n\n### Goose-specific: MCP servers as `extensions` (global) and open-plugin manifest (project)\n\nGoose configures MCP servers in two locations depending on scope:\n\n- **Global (`--global`):** MCP servers are written as **extensions** in the shared user config `~/.config/goose/config.yaml`. The schema is non-standard, so Rulesync maps canonical MCP fields to Goose's: `command` → `cmd` (an array `command` folds its tail into `args`), `env` → `envs`, `url`/`httpUrl` → `uri`, and `disabled: true` → `enabled: false`. The `type` is derived — `command` ⇒ `stdio`, a remote `url` ⇒ `streamable_http` (or `sse` when the canonical `type` is `sse`). Each extension also carries its own `name`. A canonical server with no `command` and no `url` is **skipped with a warning** rather than written as a `stdio` extension with no `cmd`, which Goose cannot start. Generation merges the `extensions:` block into the existing `config.yaml`, preserving other Goose settings (model, provider, ...), and the file is never deleted. The `extensions:` map itself is co-owned: Goose's own `builtin`/`platform`/`frontend`/`inline_python` extensions (`developer`, `memory`, ...) live there alongside MCP servers and are **carried over untouched**, as is any entry Rulesync cannot read as an MCP server, while every entry it positively identifies as one (`stdio`/`streamable_http`/`sse`) is Rulesync-owned, so a server deleted from `.rulesync/.mcp.json` is retracted with a warning naming it. Import mirrors this: a non-MCP extension type is skipped with a warning instead of being imported as a server (importing a `builtin` used to strip the type that makes it work). This location supports **both stdio and remote** (http/sse) servers.\n- **Project:** Goose v1.39.0+ discovers MCP extensions in **open plugins** at `<project>/.agents/plugins/<name>/.mcp.json` (and `~/.agents/plugins/<name>/.mcp.json` at user scope). Rulesync emits `.agents/plugins/rulesync/.mcp.json`, reusing the same `.agents/plugins/rulesync/` tree already used for Goose hooks. The manifest uses the **Claude-style** `{ \"mcpServers\": { \"<name>\": { \"command\", \"args\", \"env\", \"cwd\" } } }` shape. This manifest is **stdio-only** — it cannot express `url`/`headers`, so **remote (http/sse) servers are skipped with a warning** in project mode; sync them with `--global` to `~/.config/goose/config.yaml` instead. The `.mcp.json` manifest is owned by Rulesync and is deleted when no servers remain.\n\nSee the [Goose extensions docs](https://goose-docs.ai/docs/getting-started/using-extensions/) and [open-plugins MCP PR #9471](https://github.com/aaif-goose/goose/pull/9471).\n\n### Goose-specific: commands as recipes, subagents as custom agents\n\nGoose [recipes](https://goose-docs.ai/docs/guides/recipes/recipe-reference/) are reusable YAML workflow files. **Commands** map to top-level recipes at `.goose/recipes/<name>.yaml` (project) and `~/.config/goose/recipes/<name>.yaml` (global); the command body becomes the recipe `prompt`, `title` defaults to the file name and `description` to the rulesync `description` (falling back to `title`), `version` defaults to `1.0.0`, and any other recipe field round-trips through the rulesync `goose` section of a command.\n\nA recipe on disk is not invocable as `/name` on its own: Goose resolves slash commands from the `slash_commands` list in the user config (`~/.config/goose/config.yaml`), whose entries are `{ command, recipe_path }` pairs. In **global mode** Rulesync therefore registers every generated recipe there. `recipe_path` is written as an **absolute** path, because Goose resolves it with a bare `PathBuf::from(...)` on this code path (the tilde expansion used by `goose run --recipe` does not apply, so a `~/…` registration would never resolve), and the command name is lowercased, because Goose lowercases the typed command and compares it against the stored value verbatim. There is no project-level registration surface upstream, so project-scope recipes must still be run with `goose run --recipe`.\n\nThe list is co-owned: entries whose `recipe_path` points outside `~/.config/goose/recipes/` — and sub-recipes under `recipes/subagents/` — are carried over untouched, while **every** entry pointing directly into that directory is Rulesync-owned and recomputed on each `--global` generate. That retracts a deleted command's registration and drops the key once nothing is registered, but it also means a slash command you registered yourself (via Goose's own UI or `goose recipe`) for a recipe living in that directory is removed on the next generate — keep such recipes elsewhere, or author them in `.rulesync/commands/`. Command names must be unique, contain no spaces, and must not shadow a built-in command such as `/recipe`, `/compact`, or `/help`; Rulesync does not check the built-in names for you. See the [slash-command mapping in the Goose source](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/slash_commands/recipe_slash_command.rs).\n\n**Subagents** map to Goose's [custom agents](https://goose-docs.ai/docs/guides/context-engineering/custom-agents/) (v1.34.0+): Markdown files with `name` (required) / `description` / `model` frontmatter whose body is the agent instructions, invocable via `@name` or delegation. They are emitted to the goose-specific discovery dirs `.goose/agents/<name>.md` (project) and `~/.config/goose/agents/<name>.md` (global), so the output cannot collide with a future shared `.agents/agents/` target; `model` and unknown future fields round-trip through the rulesync `goose` subagent section. Earlier rulesync versions emitted subagents as sub-recipe YAML under `.goose/recipes/subagents/` — a location Goose's agent discovery never scans, so those files were inert; they are no longer generated (stale outputs stay gitignored but are not cleaned up automatically).\n\n### Vibe-specific: stdio `cwd` and MCP `[auth]` block\n\nVibe (mistral-vibe) MCP servers live in `[[mcp_servers]]` arrays of the shared `.vibe/config.toml`. In addition to the flat fields, Rulesync passes through the stdio `cwd` (working directory), a structured per-server `auth` block (Vibe v2.15.0+), and the four keys Vibe's `/mcp` panel writes back when you toggle a server or one of its tools — `prompt`, `sampling_enabled`, `disabled` and `disabled_tools`. Because `mcp_servers` is replaced as a whole array on each generate, a server Rulesync writes is seeded from the on-disk entry of the same name for exactly those keys, so a toggle you made in the TUI survives — unless your `.rulesync/mcp.json` states the value itself, which wins. `disabled_tools` is the canonical `disabledTools` under Vibe's spelling; `prompt` and `sampling_enabled` have no canonical equivalent and pass through as-is. The `auth` table is discriminated on `type`: `static` (`headers`, `api_key_env`, `api_key_header`, `api_key_format`) and `oauth` (`scopes`, `client_id` / `client_metadata_url`, `redirect_port`). Because Vibe rejects mixing legacy top-level static-auth keys with an explicit `[auth]` block, Rulesync suppresses the legacy keys (`headers`/`api_key_env`/`api_key_header`/`api_key_format`) whenever a server carries an `auth` block. Servers added outside Rulesync — through `vibe mcp add` (v2.23.0) or the `/mcp add` panel, both of which persist straight into this TOML — are preserved after the managed entries instead of being deleted by the array replace. The flip side: removing a server from `.rulesync/mcp.jsonc` no longer removes it from `config.toml`; delete it there too (or run `vibe mcp remove`). Deleting it from one scope may not be enough either: since v2.24.0 Vibe stacks the user and project layers and union-merges `mcp_servers` by name, so a server of the same name left in `~/.vibe/config.toml` still resolves after you remove it from the project file. See [mistral-vibe](https://github.com/mistralai/mistral-vibe) (`vibe/core/config/models.py`).\n\n> **GitHub Copilot (VS Code) MCP note:** the `copilot` target writes `.vscode/mcp.json`, which has three documented top-level sections: `servers`, `inputs` (secret prompts referenced as `${input:id}`) and `sandbox` (filesystem/network rules for sandboxed servers, added in VS Code v1.112). Rulesync owns and replaces only `servers`; the rest of the document — including any future top-level section — is read back and preserved on each generate. VS Code recommends committing this file, so dropping an `inputs` entry would leave `${input:…}` unresolvable and the affected servers would fail to start. If the existing file cannot be parsed, generate fails with an error rather than overwriting it. See the [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).\n\n> **Rovo Dev CLI MCP note:** Rovo Dev documents the per-server transport key as `transport` (`stdio` | `http` | `sse`), not the canonical `type`. Rulesync translates on the way out (`local` → `stdio`, `streamable-http` → `http`) and back on import; `ws` has no Rovo Dev equivalent, so those servers are skipped with a warning, and a `transport` value outside Rovo Dev's vocabulary is dropped on import rather than written into the canonical config, whose transport field is a strict enum. `disabled` is stripped from the servers that are written, since `mcp.json` is not where a Rovo Dev server is switched on and off — see the toggle handling below. `mcp.json` is written at both scopes: the global `~/.rovodev/mcp.json`, and in project mode the repo-committed `.rovodev/mcp.json` the Bitbucket Cloud Agentic Pipelines guide documents (pointed at via `mcp.mcpConfigPath`, which Rulesync now writes into the project `config.yml` for you: Rovo Dev's `mcpConfigPath` default points at the _global_ MCP file, so without the pointer the generated project `mcp.json` is never read. The pointer names one config instead of merging with the default, so it is written only when the project has a Rovo Dev server to run — one that targets `rovodev`, is not disabled, and names a `command`/`url` to start — since otherwise the project would trade the user's global servers for an empty file; writing it is logged, being the step that makes Rovo Dev start those servers. If the last such server is later removed or switched off, the pointer is not taken back out (Rulesync cannot tell its own past value from a user who typed the same string) but the now-empty result is reported with a warning. A `mcpConfigPath` already aimed somewhere else is left in place — it is the user's choice — and reported with a warning naming the file that stays unread. One value earns its own message in global scope: `~/.rovodev/mcp_config.json`, the default the settings reference documents, which Rovo Dev may therefore have written itself rather than the user choosing it. That is exactly the user this pointer exists for, so the warning says what to change and whether that file holds servers they would lose by changing it. The comparison recognizes the other spelling of the same home-directory file — an already-expanded absolute path — so a pointer that already names the generated file is not reported as unread, and a stale one still is. `$HOME/...` and `${HOME}/...` are deliberately not counted as correct: nothing in Atlassian's documentation says Rovo Dev expands environment variables in this setting, and a pointer that resolves literally reads no MCP servers at all, so that spelling gets a warning of its own asking for the `~` form instead. Global scope gets the same treatment, with the home-anchored value `~/.rovodev/mcp.json`, because Atlassian's own pages disagree about the default: the [settings reference](https://support.atlassian.com/rovo/docs/manage-rovo-dev-cli-settings/) documents `~/.rovodev/mcp_config.json`, while the [MCP guide](https://support.atlassian.com/rovo/docs/connect-to-an-mcp-server-in-rovo-dev-cli/) has servers registered in `~/.rovodev/mcp.json`. Under the first spelling the global file Rulesync writes is never read, so naming it explicitly is what makes the outcome the same either way; the value has to be home-anchored rather than repo-relative, since `~/.rovodev/config.yml` is read from whatever directory Rovo Dev runs in. That same disagreement is why the global pointer is **withheld** when `~/.rovodev/mcp_config.json` holds servers of its own — if the settings reference is the spelling in force, those are the servers Rovo Dev is running today, and naming `mcp.json` instead would stop them being read on every project on the machine. Rulesync does not write that file, so it could neither import them first nor put them back; it reports what it found and leaves the pointer for you to set once you have moved what you want to keep into `.rulesync/mcp.jsonc`. A `mcp_config.json` that cannot be parsed, cannot be read (a directory or a permission error at that path, which costs this one decision rather than aborting the run), or carries a shape Rulesync does not recognize all count the same way, since none of them can be shown to be empty; only an `mcpServers` map with no entries — or a literally empty `{}` — releases the pointer. Each of those reports also says what to do when the file turns out to hold nothing you need — set `mcp.mcpConfigPath` yourself, which Rulesync never overwrites, or change it if it is already set — so a file Rulesync cannot see inside is never a dead end. Writing the global pointer is a warning rather than a note, the project pointer changing one repository where this one changes Rovo Dev everywhere. The project file is not gitignored, since committing it is the point). A server the canonical config marks `disabled: true` is no longer dropped: its definition is written to `mcp.json` (minus the flag, which the file cannot express) and its name goes to `mcp.disabledMcpServers` in the sibling `config.yml` — the key Rovo Dev actually consults — where rulesync owns the toggle for the servers it manages while user keys (`allowedMcpServers`, ...) and disabled names for unmanaged servers survive. On import, names listed in `mcp.disabledMcpServers` come back as `disabled: true` on the matching servers; a `config.yml` that exists but cannot be parsed fails both directions closed (the import errors instead of silently re-enabling servers, and generate skips disabled definitions it cannot switch off). Since the project `mcp.json` is committed, prefer env-var references over literal credentials in server `env`/`headers`; note that rulesync owns the `mcpServers` map in that file, so servers hand-added there (rather than to `.rulesync/mcp.jsonc`) are replaced on the next generate. Rovo Dev's per-server `enable_instructions` — which opts the server's own initialization-response instructions into the agent's system prompt, and which Atlassian warns to \"only enable for MCP servers you trust, since the instructions become part of the agent's prompt and can influence its behavior\" — is authored as the Rulesync-only key `rovodevEnableInstructions` (Rovo Dev's own `enable_instructions` spelling is accepted too, so an entry copied out of Atlassian's docs works) and written out as `enable_instructions`; on import it is lifted back onto `rovodevEnableInstructions`. Only a literal `true` counts in either direction, since absent and `false` mean the same thing to Rovo Dev, and when both spellings are present on one entry the canonical key decides — so an explicit `rovodevEnableInstructions: false` overrides an `enable_instructions: true` left over from a copied example rather than losing to it. Every server that receives the flag is named in a warning on generate, since it is the one thing Rulesync writes that widens what steers the model. Like `musecodeMode`, the key is stripped from every other target's output — and here that matters more than tidiness: it decides whether a third-party server's text joins the model's prompt, so it must not reach a tool you were not writing about. See the [Rovo Dev MCP docs](https://support.atlassian.com/rovo/docs/connect-to-an-mcp-server-in-rovo-dev-cli/).\n\n> **Meta Muse Code MCP note:** Muse Code reads MCP servers only from the `mcp_servers` block of the **global** user settings file `~/.config/muse/settings.json` — no project-scoped MCP location is documented, so the `musecode` MCP target requires `--global`. Each server entry carries a `transport` discriminator: `stdio` servers get `command` (a single string), `args` and `env`, and remote servers become `transport: \"streamable_http\"` with `url`/`headers` (Muse Code's only documented remote transport). A server that states `sse` or `ws` — or carries a `ws://`/`wss://` URL with no stated type — is skipped with a warning rather than rewritten onto a transport it does not speak. A canonical `disabled: true` maps to Muse's `enabled: false` and back. The settings file must carry `\"schema_version\": 1` — Muse Code fails startup with `malformed settings file` without it — so Rulesync bootstraps the key when it creates the file and preserves an existing value; every other settings key is preserved on round-trip and the file is never deleted. There are no per-server tool allow/deny lists. Muse Code's per-server `mode` — `required` (its default) aborts the whole run when the server fails to start, `optional` skips it with a warning — is authored as the Rulesync-only key `musecodeMode` and written out as `mode`; on import a `mode` of `required` or `optional` is lifted back into `musecodeMode`, while any other value is dropped with a warning naming the server — keeping it would copy a Muse Code key into every _other_ target's generated config, since Rulesync's server schema is loose, and the next generate would drop it from the Muse Code side regardless. `musecodeMode` is stripped from every other target's output, so it is safe to leave on a shared server entry. See the [Muse Code extending docs](https://dev.meta.ai/docs/muse-code/extending.md) and [configuration docs](https://dev.meta.ai/docs/muse-code/configuration.md).\n\n> **Reasonix note:** MCP servers are written as `[[plugins]]` array-of-tables entries (Reasonix's MCP-compatible external plugins) in `reasonix.toml` (project) / `~/.reasonix/config.toml` (global, via `--global`). Each entry carries a `name` plus the standard transport fields: `type` selects the transport (`stdio` default — `command`/`args`/`env`; `http`, a.k.a. `streamable-http` — `url`/`headers`; `sse`, the legacy 2024-11-05 HTTP+SSE transport, written verbatim — Reasonix re-implemented it in v1.17.18, and collapsing it onto `http` pointed the client at Streamable HTTP so the server could not connect). The file is treated as shared Reasonix config: Rulesync only replaces the `plugins` key and preserves every other table (providers, ui, agent, …) on round-trip, and it is never deleted. Reasonix has no per-server tool allow/deny lists. The `trusted_read_only_tools` array (raw MCP tool names pre-seeded as trusted for planner/read-only use) is neither written nor imported: v1.17.18 retired it along with `default_tools_approval_mode`, `tools.<raw>.approval_mode` and `approvals_reviewer` — installing a server is the authorization decision now, and Reasonix ignores the key on load and strips it the next time it saves that entry. Importing it would put a Reasonix-only dead key into the canonical `mcpServers` that every MCP target writes out, so it would surface in `.mcp.json` and the rest. Note that Rulesync owns the `plugins` key, so the next generate drops the key from an older `reasonix.toml` as well; nothing is lost that Reasonix still reads. An MCP server whose transport Reasonix does not implement (`ws`, including a `ws://`/`wss://` URL that states no transport at all) is skipped with a warning rather than written as a `type` its loader rejects. Each entry also supports `startup_timeout_seconds` (a per-server cap on the background launch/authorization/`initialize`/`tools/list` sequence, overriding the global `mcp_startup_timeout_seconds`; `0` means defer to that global cap, and is preserved rather than dropped), `call_timeout_seconds` (a per-server MCP call timeout) and `tool_timeout_seconds` (a per-tool inline table keyed by raw MCP tool name). All three round-trip as passthrough fields on the canonical MCP server object rather than through a deep mapping. For the latter two there is no canonical counterpart at all; `startup_timeout_seconds` does have a near-equivalent in canonical `networkTimeout` (which Codex CLI deep-maps to its `startup_timeout_sec`), but canonical timeouts are milliseconds while Reasonix takes seconds, and Reasonix's meaningful `0` has no canonical spelling — so mapping it would either invent a value or lose one. Vibe's `startup_timeout_sec` passes through for the same reason. See the [Reasonix plugins guide](https://github.com/esengine/deepseek-reasonix/blob/main-v2/docs/GUIDE.md#plugins-mcp) and [SPEC.md](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md) (`[[plugins]]` schema).\n\n> **ZCode MCP note:** ZCode reads MCP servers from the `mcp.servers` block of its own JSON config: `<project>/.zcode/config.json` (project) and `~/.zcode/cli/config.json` (global, via `--global`). A stdio server carries `command`, `args` and `env`; a remote server carries `type` — `http` (what rulesync calls `streamable-http`) or `sse` — plus `url` and optional `headers`. ZCode's own page shows a JSON example for stdio servers only and describes remote ones through its UI (\"Service URL\" plus optional headers), so the remote JSON spelling used here is inferred from the configuration Z.ai documents for the other MCP clients it supports. A server with no stated transport and an `http(s)` URL is written as `type: \"http\"`, ZCode's default remote transport, while a `ws`/`wss` server is skipped with a warning rather than rewritten onto a transport ZCode does not implement. ZCode's per-server toggle is `enable`, which defaults to `true` when absent, so a canonical `disabled: true` is written as `enable: false` and lifted back on import. The file is shared ZCode config: rulesync only replaces the `mcp` key (preserving its non-`servers` siblings and every other top-level key such as `model`), never deletes the file, and fails closed rather than overwriting a `config.json` it cannot parse. ZCode's legacy `.agents/mcp.json` fallback — consulted only while the `.zcode` file of the same scope lists no server — is neither written nor imported, so a hand-maintained one is left alone. Because rulesync replaces the whole `servers` map, a server added to `config.json` by hand is dropped on the next `generate`; add it to `.rulesync/.mcp.json` instead. The project file is committable, so prefer `env` entries that reference environment variables over literal credentials. There are no per-server tool allow/deny lists. See the [ZCode MCP services docs](https://zcode.z.ai/en/docs/mcp-services).\n\n## `.rulesync/.aiignore` or `.rulesyncignore` (deprecated)\n\n> **Deprecation notice:** The `ignore` feature is deprecated in favor of the more expressive [`permissions` feature](#rulesync-permissions-jsonc). Existing ignore configurations, generation, import, conversion, and explicit `rulesync add ignore` scaffolding remain supported throughout Rulesync 14.x. Removal, if any, will be decided separately and will not occur before a future major release. `rulesync init` no longer enables or scaffolds ignore for new projects.\n\nRulesync continues to support a single legacy ignore list in either location:\n\n- `.rulesync/.aiignore` (preferred legacy location)\n- `.rulesyncignore` (older project-root location)\n\nRules and behavior:\n\n- You may use either location.\n- When both exist, Rulesync prefers `.rulesync/.aiignore` over `.rulesyncignore` when reading.\n- Explicitly running `rulesync add ignore` creates `.rulesync/.aiignore` when neither location exists.\n\nExample:\n\n```ignore\ntmp/\ncredentials/\n```\n\n### Migrating to permissions\n\nMove each ignore pattern into the `read` category of `.rulesync/permissions.jsonc` with the `deny` action:\n\n```jsonc\n{\n  \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json\",\n  \"permission\": {\n    \"read\": {\n      \"tmp/**\": \"deny\",\n      \"credentials/**\": \"deny\",\n    },\n  },\n}\n```\n\nThis is the closest replacement for preventing an agent from reading ignored paths — except for Zed, whose read-only tools are not permission-gated at all: there the replacement is `private_files`, which the ignore feature writes, so a `read` deny rule is dropped with a warning instead. If the old policy was also intended to prevent changes, repeat the patterns under `edit` and `write`. Target tools differ in the permission categories they can represent, so review the [Supported Tools and Features](./supported-tools.md) table and the tool-specific permission notes below before removing the old ignore feature from a multi-tool project.\n\n### Where ignore patterns are written per tool\n\nMost tools get a dedicated ignore file (for example `.cursorignore`,\n`.geminiignore`, `.clineignore`). Antigravity CLI is built on the same engine\nas Gemini CLI, so it reads the project-root `.geminiignore` file. Claude Code is the exception: it does not\nread a separate ignore file, so Rulesync writes the deny list into Claude\nCode's settings file as `permissions.deny` entries (`Read(<pattern>)`).\n\nReasonix has no ignore file either, so its deny list goes into the `[permissions]` table of the shared `reasonix.toml` (project) / `~/.reasonix/config.toml` (global, via `--global`) as `Read(<pattern>)` entries — the same Claude-Code-style rule syntax the permissions feature writes there. `deny` is used rather than `[sandbox].forbid_read` because deny rules take glob specifiers and are documented as \"a hard block in every mode\", while `forbid_read` takes absolute paths with no documented glob support. The file is shared with the MCP and permissions features: only `Read(...)` deny entries are replaced, every other table and deny entry is preserved, and the file is never deleted. When the permissions feature also manages the `Read` category its explicit rules win, and the overwrite is warned about. As with the MCP and permissions features, the file is re-serialized on write, so hand-written comments, blank lines, and key ordering in `reasonix.toml` are not preserved.\n\nKiro reads `.kiroignore` in project scope and `~/.kiro/settings/kiroignore` in user scope. The `kiro`, `kiro-cli`, and `kiro-ide` targets therefore support `--global` for the deprecated ignore feature, as do `reasonix` and `zed` (whose config files exist in both scopes), as well as `devin`; the remaining ignore targets are project-only.\n\nDevin writes the project file as `.devinignore` (reading the pre-rebrand `.codeiumignore` and `.windsurfignore` as import fallbacks, in that order — the docs list the three names side by side without defining a precedence, so the order is rulesync's own choice), and in global scope writes `~/.codeium/.codeiumignore`. Three things about that global path are worth knowing: it keeps the **legacy brand spelling** — the rename to `.devinignore` covered only the project file, so no `.devinignore` variant is written or read there, not even as a fallback; it is documented in the Devin **Desktop** docs tree rather than the Devin Local (CLI) one, which is why it sits outside `~/.config/devin` where the other global Devin paths live; and it is positioned as an **enterprise** feature for enforcing ignore rules across many repositories, not as a general per-user setting. See [the Devin ignore docs](https://docs.devin.ai/desktop/context-awareness/windsurf-ignore).\n\nZed has no ignore file: its deny list is the `private_files` array inside the shared settings file — `.zed/settings.json` in project scope and `~/.config/zed/settings.json` in global scope (`%APPDATA%\\Zed\\settings.json` on Windows). `private_files` is a worktree setting, and Zed layers default → user → project, so the key is honored in the user settings file too. The array is **owned wholesale by Rulesync**: it is replaced with the patterns from `.rulesync/.aiignore` on every generation, so a pattern deleted there is retracted from the file Rulesync writes instead of surviving forever. Note that this narrows what Rulesync's own layer contributes, not the effective set: Zed's shipped default and any other settings layer still add their own patterns (see below). When no patterns remain at all, the key is removed rather than written as `[]`. `private_files` is an `ExtendingVec`: each settings layer's value is appended to the one below it (`merge_from` calls `extend_from_slice`) instead of replacing it, and Zed ships a populated default (`**/.env*`, `**/*.pem`, …). Writing the key is therefore purely additive — an empty array would neither disable Zed's secret redaction nor mean anything at all — so omitting it is how Rulesync says it contributes nothing here. Every other key in the file — including the MCP `context_servers` and permissions `agent` blocks and unrelated editor settings — is preserved, and the file is never deleted.\n\nGoose retired `.gooseignore` upstream (\"removed some time ago in favour of other ignore things like gitignore etc\" — [goose#10343](https://github.com/aaif-goose/goose/issues/10343)), so rulesync no longer generates it; the replacement guidance is `.gitignore` plus tool permissions. Stale `.gooseignore` files from earlier versions stay gitignored but are not cleaned up automatically.\n\nCline's `.clineignore` is still emitted, but its own docs now title it \"deprecate soon\" and state it is not a security or access-control boundary — upstream's replacement direction is a Cline plugin enforcing via a `beforeTool` hook. Treat the matrix ✅ as a deprecated surface.\n\nHermes Agent uses a project-local `rulesync-ignore` plugin under `.hermes/plugins/`. It applies the canonical gitignore-style patterns through [`pre_tool_call`](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/#pre-tool-call) to `read_file`, `write_file`, and `patch` before execution, and filters ignored paths from `search_files` results through `transform_tool_result`. This is defense in depth around Hermes file tools; terminal commands and paths already present in conversation context are outside the plugin's enforcement surface. Hermes deliberately requires [explicit trust for project plugins](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins/), so run it from the trusted project root with that invocation opted in:\n\n```sh\nHERMES_ENABLE_PROJECT_PLUGINS=1 hermes\n```\n\nRulesync adds `rulesync-ignore` to `plugins.enabled` in `$HERMES_HOME/config.yaml` but deliberately leaves `$HERMES_HOME/.env` unchanged. Existing configuration is preserved, explicit `plugins.disabled` conflicts fail, and `--delete` retains the additive user-level activation.\n\nFor Cursor, Rulesync emits only `.cursorignore` — the file that **blocks access\nentirely** (semantic search, Tab, Agent, Inline Edit, and `@`-mentions). Cursor\nalso supports a second file, `.cursorindexingignore`, which excludes files from\n**indexing only** while keeping them accessible to the AI on demand. These two\nfiles mean _different_ things, and Rulesync's `ignore` feature models a single\ncanonical ignore list per tool with no per-pattern distinction between\n\"block access\" and \"exclude from indexing only\". Emitting the same patterns to\nboth files would be incorrect, so `.cursorindexingignore` is intentionally **not\ngenerated** (an intentional non-goal). Author it by hand if you need\nindexing-only excludes.\n\nBy default, Claude Code's deny list is written to the **shared**\n`.claude/settings.json` so that the policy can be committed and reviewed by\nthe team. This is intentional (see issue #1094), but it means that running\n`rulesync gitignore` will not add `.claude/settings.json` to `.gitignore` —\nthat file may also contain other shared Claude config you actively want to\ncommit.\n\nIf you would rather keep the deny list out of version control, opt into the\n**local** mode using the per-feature options object form:\n\n```jsonc\n// rulesync.jsonc\n{\n  \"targets\": [\"claudecode\"],\n  \"features\": {\n    \"claudecode\": {\n      \"ignore\": { \"fileMode\": \"local\" },\n    },\n  },\n}\n```\n\n| `fileMode`           | Output file                   | Tracked by git by default                             |\n| -------------------- | ----------------------------- | ----------------------------------------------------- |\n| `\"shared\"` (default) | `.claude/settings.json`       | Yes — meant to be committed and shared with the team. |\n| `\"local\"`            | `.claude/settings.local.json` | No — `rulesync gitignore` already excludes this file. |\n\n## `.rulesync/permissions.jsonc`\n\n`.rulesync/permissions.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/permissions.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nFor Hermes Agent imports, Rulesync treats a valid private `permissions.rulesync` block as provenance, then reconciles it with current native settings. `command_allowlist`, `approvals.deny`, and an enabled `security.website_blocklist` are authoritative for their mapped canonical rules, so hand edits replace stale generated values. A config with no private block still imports those native rules. Unmodeled `approvals`, `security`, `skills`, and `memory` settings remain under the `hermes` override; unrelated root settings such as `model` are not imported.\n\n`rulesync init` scaffolds a `codexcli` block with `approval_policy: \"on-request\"`, `approvals_reviewer: \"auto_review\"`, and `base_permission_profile: \":danger-full-access\"`. On generation, the profile value becomes Codex's top-level `default_permissions`.\n\nPermissions define which tool actions are allowed, require confirmation, or are denied. The canonical format uses **lowercase tool category names** and **glob patterns** mapped to permission actions.\n\n**Permission actions:**\n\n- `allow` -- Automatically permitted without user confirmation\n- `ask` -- Requires user confirmation before execution\n- `deny` -- Blocked from execution\n\n**Supported tool categories:** `bash`, `read`, `edit`, `write`, `webfetch`, `websearch`, `grep`, `glob`, `notebookedit`, `agent`, and MCP-specific tool names (e.g., `mcp__puppeteer__puppeteer_navigate`)\n\nExample:\n\n```json\n{\n  \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json\",\n  \"permission\": {\n    \"bash\": {\n      \"git *\": \"allow\",\n      \"npm run *\": \"allow\",\n      \"rm -rf *\": \"deny\",\n      \"*\": \"ask\"\n    },\n    \"edit\": {\n      \"src/**\": \"allow\"\n    },\n    \"read\": {\n      \".env\": \"deny\",\n      \"credentials/**\": \"deny\"\n    }\n  }\n}\n```\n\n**Rejected pattern keys.** Two kinds of pattern are refused when the source file is read, rather than being carried into generated configs:\n\n- A **blank pattern** (empty, or only whitespace). It is a prefix of every command and a substring of every path, so a tool that honors it grants or denies everything, while a tool that filters it — Roo Code keeps only entries passing `cmd.trim().length > 0` — ignores it entirely. Rather than let each target decide, Rulesync rejects it on the source file.\n- A pattern named `__proto__`, `constructor`, or `prototype`. Rulesync strips these from every source document it parses, because assigning them would reach the prototype chain instead of the object, so such an entry could never reach a generated file. Rulesync now names the offending path instead of dropping it in silence.\n\nImporting removes a blank pattern rather than reproducing it: keeping one would write a source file the very next `generate` refuses. This applies to the shared `permission` block and to tool-scoped `{toolname}.permission` blocks alike, since importing OpenCode or Kilo routes their tool-only categories into the tool-scoped block. Every removal is reported in a warning naming how many patterns were dropped from each block, because dropping one can widen what the imported configuration allows — a blanket blank pattern may have been the only entry denying anything.\n\nWhen removing a blank pattern leaves a category with no rules at all, the category itself is removed rather than left as an empty object. An empty category means \"Rulesync manages this category and it has no rules\", which makes the next `generate` delete the entries the tool's own config already had; removing the category leaves them alone.\n\n### Tool-scoped permission blocks (`{toolname}.permission`)\n\nThe shared `permission` block applies to every targeted tool. To scope rules to a single tool, add a tool-scoped `{toolname}` block with a `permission` record of the same shape — mirroring `{toolname}.hooks` in `.rulesync/hooks.jsonc` and `{toolname}.mcpServers` in `.rulesync/mcp.jsonc`:\n\n```jsonc\n{\n  \"permission\": {\n    \"bash\": { \"git *\": \"allow\", \"*\": \"ask\" },\n  },\n  \"claudecode\": {\n    \"permission\": {\n      // Replaces the shared `bash` category for Claude Code only.\n      \"bash\": { \"git *\": \"allow\", \"git push *\": \"deny\", \"*\": \"ask\" },\n    },\n  },\n}\n```\n\n- Categories are merged **per category**: a tool-scoped category replaces the shared category wholesale for that tool; shared categories it does not name still apply.\n- Any permissions-capable `--targets` name is accepted as a block key. `kiro-cli`/`kiro-ide` alias to the `kiro` key and `hermesagent` to `hermes` (matching the shared output file each writes).\n- OpenCode, Kilo, and Vibe keep their existing tool-native `permission` override semantics (bare action strings / tool-only categories / `sensitive_patterns` — see the tool-specific callouts below); their blocks are consumed by their translators instead of the central merge.\n\n#### JSON Schema Support\n\nRulesync provides a JSON Schema for editor validation and autocompletion. Add the `$schema` property to your `.rulesync/permissions.jsonc`:\n\n```json\n{\n  \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json\",\n  \"permission\": {}\n}\n```\n\nFor Claude Code, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in `.claude/settings.json` (project mode) or `~/.claude/settings.json` (global mode) using PascalCase tool names (e.g., `Bash(git *)`, `Edit(src/**)`, `Read(.env)`).\n\nClaude Code's file permission checks match only `Edit(path)` and `Read(path)` rules: a `Write(path)`, `NotebookEdit(path)` or `Glob(path)` rule \"is accepted but never matched by those checks, so Claude Code warns at startup for each allow, deny, or ask rule in one of these unmatched forms\" ([permissions docs](https://code.claude.com/docs/en/permissions), v2.1.210+). Rulesync therefore writes a canonical `write` or `notebookedit` rule that carries a pattern as `Edit(pattern)`, and a `glob` rule as `Read(pattern)`. A rule whose pattern is `*` is a tool-name rule with no path — it matches the tool everywhere and produces no warning — so it is still written as the bare `Write` / `NotebookEdit` / `Glob`. Entries an earlier Rulesync wrote in the warned form are replaced on the next generate, and so is a rewritten entry whose action changed, so flipping a rule from deny to allow never leaves the old deny behind to win. Rewriting a rule does **not** make Rulesync claim the `Edit` or `Read` namespace as a whole: a `Read(...)` deny the [ignore feature](#rulesyncignore) wrote, or an `Edit(...)` rule you added to `settings.json` by hand, is left alone unless the canonical config manages that category itself. Import stays tolerant of both forms, so an existing `settings.json` still round-trips; a rewritten rule comes back under `edit` or `read` rather than the category it was authored in, since that is the rule Claude Code actually applies. Note that this widens a `glob` **allow** rule: `Read(pattern)` permits reading the files' contents, not just listing their names — the docs prescribe the substitution, but author `glob` allow rules with that in mind. When two categories resolve to the same entry with different actions (`edit` allowing what `write` denies, say) both are written and Rulesync warns — Claude Code applies deny first, then ask, then allow.\n\n> **Claude Code-only override (`claudecode` key):** Claude Code's `permissions` object also carries non-list fields with no canonical permission category — notably `defaultMode` (the session-start permission mode: `default` | `acceptEdits` | `plan` | `bypassPermissions`) and `additionalDirectories` (extra working directories). Add a tool-scoped `claudecode` override key alongside the shared block to author them: the fields under `claudecode.permissions` are merged into the settings `permissions` object and emitted **only** for Claude Code, while the shared `permission` block continues to drive the managed `allow`/`ask`/`deny` arrays. The block is a verbatim passthrough (so other/future `permissions` fields such as the org locks `disableBypassPermissionsMode`/`disableAutoMode` can be set too), but any `allow`/`ask`/`deny` placed inside it is ignored — rulesync owns those arrays. On import, the non-list `permissions` fields round-trip back into the `claudecode` override. Note that these fields are merged **additively** into the existing `settings.json` (so hand-added settings survive): removing a field from the `claudecode` override does not delete a value already written to `settings.json` — clear it there by hand.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git *\": \"allow\" } },\n>   \"claudecode\": {\n>     \"permissions\": { \"defaultMode\": \"acceptEdits\", \"additionalDirectories\": [\"../shared\"] },\n>     \"sandbox\": { \"network\": { \"allowedDomains\": [\"example.com\"], \"strictAllowlist\": true } },\n>     \"editorMode\": \"vim\",\n>     \"env\": { \"MY_VAR\": \"1\" }\n>   }\n> }\n> ```\n>\n> The same override key also carries `sandbox`, the sibling top-level settings subtree governing the sandbox commands run in (`sandbox.network.*`, `sandbox.filesystem.*`, `sandbox.credentials`, `sandbox.allowAppleEvents`, ...). It has no canonical permission category either — it constrains _how_ a permitted command runs rather than which commands are permitted — so it is a verbatim passthrough on the same terms, merged into the top level of `settings.json` and round-tripped back on import — except for the three paths naming an executable, covered by the Trust caveat below, which are dropped in both directions. The merge is recursive, unlike the flat `permissions` fields above: `sandbox` subtrees carry restriction lists (`network.deniedDomains`, `filesystem.denyRead`), so setting one flag under `network` must not drop the denials beside it. A sibling key at any depth survives; a list you author replaces the existing list rather than being appended to. **Scope caveat:** Claude Code honors a subset of `sandbox.*` only from user settings, managed settings and the `--settings` flag — `filesystem.disabled`, `network.strictAllowlist`, `network.tlsTerminate`, `credentials.allowPlaintextInject`, `credentials.awsPairs`, `credentials.sigv4` and `allowAppleEvents` — and ignores them in a repository's `.claude/settings.json` / `.claude/settings.local.json`. Rulesync therefore skips those keys when generating project scope (warning once per key) and emits them only under `--global`, so it never _writes_ a project-scope sandbox policy that does nothing. The same restriction applies **per entry** inside `credentials.files` and `credentials.envVars`: an entry with `\"mode\": \"mask\"` is ignored in a repository's settings file, so Rulesync drops just those entries at project scope (warning once per list) while keeping the `deny` entries in the same list, which every scope does honor. Values already in the file are left untouched — both ones you hand-wrote and ones an earlier Rulesync version generated — because the two cannot be told apart and clobbering your file would be worse; so an inert key committed before this behavior existed stays there until you remove it by hand. Import stays scope-agnostic. See the [sandboxing docs](https://code.claude.com/docs/en/sandboxing).\n>\n> **Any other key is a top-level `settings.json` key.** Everything in the `claudecode` block other than `permission`, `permissions`, `sandbox` and `hooks` is written straight to the top level of `.claude/settings.json` and round-trips back on import, so a setting Claude Code adds needs no Rulesync release to become authorable — `editorMode`, `emojiCompletionEnabled`, `workflowSizeGuideline`, `keybindingFlavor`, `env`, `model`, `alwaysThinkingEnabled` and anything after them all work the same way. The merge is recursive, like `sandbox`, so setting one key under `env` keeps the variables already in the file. `hooks` is excluded because the [hooks feature](#rulesynchooksjsonc) owns it, `permission`/`permissions`/`sandbox` because they have their own handling above, and `$schema` because it is an editor pointer rather than a Claude Code setting. **Scope caveat:** the [settings reference](https://code.claude.com/docs/en/settings-reference) documents a scope per key, and Rulesync skips a key the file it is writing cannot honor (warning once per key): keys scoped `User or managed` / `User, local, or managed` (`spellcheck`, `autoMode`, `vimInsertModeRemaps`, `pluginConfigs`, `sshConfigs`, `syncClaudeAiSkills`, ...) are skipped at project scope and emitted only under `--global`, while keys scoped `Managed` (`allowManagedHooksOnly`, `requiredMinimumVersion`, `strictKnownMarketplaces`, ...) or `Global config` (`diffTool`, `autoConnectIde`, `teammateDefaultModel`, ...) are skipped in both scopes, because neither file Rulesync writes is the file that reads them — set those by hand in the managed settings file or `~/.claude.json`. The alternate spellings `additionalMarketplaces` and `allowedMarketplaces` are resolved to their canonical keys (`extraKnownMarketplaces` and `strictKnownMarketplaces`) before that check, so an alias is treated exactly as the key it spells. **Trust caveat:** a permissions file is shareable — `rulesync fetch` copies `.rulesync/permissions.jsonc` out of another repository — so a file whose name promises restrictions must not be able to hand Claude Code a command to run. Rulesync therefore refuses the keys whose value _is_ an executed command, in both scopes and in both directions: `apiKeyHelper`, `awsAuthRefresh`, `awsCredentialExport`, `fileSuggestion`, `gcpAuthRefresh`, `otelHeadersHelper`, `policyHelper`, `processWrapper`, `statusLine` and `subagentStatusLine` are never written (warning once per key) and are silently dropped on import — author commands in [`.rulesync/hooks.jsonc`](#rulesynchooksjsonc), where a reviewer expects them, or set these by hand in `settings.json`. The same line applies inside `sandbox`, which has its own merge branch: `sandbox.ripgrep`, `sandbox.bwrapPath` and `sandbox.socatPath` each name an executable Claude Code runs, so they are refused in both scopes and dropped on import too. The scope caveat reaches inside `sandbox` as well: `sandbox.filesystem.allowManagedReadPathsOnly` and `sandbox.network.allowManagedDomainsOnly` are scoped `Managed`, so they are skipped in both scopes for the same reason the `Managed` top-level keys are — set them in the managed settings file by hand. Keys that widen what Claude Code trusts rather than running something themselves are still written, but every one of them is named in a single summary warning per file — one line listing each setting and what it affects, rather than a run of near-identical lines: `env`, `disableAllHooks`, `disableSkillShellExecution` set to anything but `true` (which re-opens inline shell execution a user setting had turned off), `enableAllProjectMcpServers`, `enabledMcpjsonServers` and `allowedMcpServers`, `autoMode`, `skipAutoPermissionPrompt` and `skipDangerousModePermissionPrompt`, `enabledPlugins` and `extraKnownMarketplaces`, `agent` and `outputStyle` (which replace the prompt and tools every session starts with), `httpHookAllowedEnvVars` and `allowedHttpHookUrls` (which relax what an existing HTTP hook may send and where), `claudeMdExcludes` (which drops the CLAUDE.md files its patterns match), `crossSessionInbound` set to anything but `hold` or `refuse` (which lets messages from your other sessions reach Claude), `modelOverrides` (which decides the inference profile a call is routed to), `skipWebFetchPreflight` set to anything but `false` (which turns off the WebFetch domain safety check), `remoteControlAtStartup` set to anything but `false`, `prUrlTemplate` (which rewrites the PR links Claude Code renders), `companyAnnouncements`, `permissions.additionalDirectories`, a `permissions.defaultMode` of `bypassPermissions`, `acceptEdits` or `auto`, and the `sandbox` paths that loosen the sandbox rather than naming something to run — `enabled`, `autoAllowBashIfSandboxed`, `allowUnsandboxedCommands`, `excludedCommands`, `allowAppleEvents`, `enableWeakerNestedSandbox`, `enableWeakerNetworkIsolation`, `ignoreViolations`, `filesystem.allowRead`, `filesystem.allowWrite`, `network.allowedDomains`, `network.allowMachLookup`, `network.allowUnixSockets`, `network.allowAllUnixSockets`, `network.allowLocalBinding`, `network.httpProxyPort` and `network.socksProxyPort`. The `allow*` lists are in that set because Claude Code merges a list across settings scopes rather than replacing it, so a project file can only ever add to them; their `deny*` counterparts, which restrict, are not. These warnings fire only on the value that actually loosens the policy, so authoring the restrictive one (`allowUnsandboxedCommands: false`, an empty `excludedCommands`) stays quiet. Each condition names the value that stays quiet rather than the one that warns, so a value of the wrong type — a `skipWebFetchPreflight` of `1` rather than `true` — is reported rather than passed over. `allowUnsandboxedCommands` and `autoAllowBashIfSandboxed` both default to `true`, and an explicit `true` is reported even so: a project `.claude/settings.json` outranks the user file, so writing it there re-opens what a user's `false` closed. `remoteControlAtStartup` is the one key whose _scope_ depends on its value — Claude Code honors a `false` from a project file but ignores a `true`, so a `true` is skipped at project scope and emitted only under `--global`. They are also emitted after the scope filter, so a path the scope drops is reported as skipped rather than as written. Every one of these warnings exists for the same reason: a value that arrived with a fetched override should be visible rather than silent. (`env` is warned about rather than refused because it has too many ordinary uses to drop, even though a value such as `NODE_OPTIONS` or `PATH` does run code.) As with `sandbox`, the filter only applies to what Rulesync writes: a value already in the file is left untouched, and removing a key from the override block does not delete the value an earlier generate wrote — clear it in `settings.json` by hand.\n\nFor OpenCode, this generates the `permission` object in `opencode.json` / `opencode.jsonc` (project mode) or `.config/opencode/opencode.json` / `.config/opencode/opencode.jsonc` (global mode), preserving other existing OpenCode config fields. OpenCode's `webfetch`, `websearch`, `todowrite`, `question`, and `doom_loop` keys accept only a single action string, so Rulesync emits their canonical `{ \"*\": \"allow\" }` form as `\"allow\"`. If one of these categories contains pattern-specific rules, Rulesync collapses them to the most restrictive action (`deny` > `ask` > `allow`) and logs a warning because OpenCode cannot represent those patterns; a map without `*` includes an implicit `ask` fallback so a narrow allowlist never becomes blanket `allow`, while an empty map becomes `deny` instead of falling through to OpenCode's default allow behavior.\n\n> **OpenCode-only override (`opencode` key):** OpenCode exposes permission categories that other tools do not understand (e.g. `external_directory`). Placing these in the shared `permission` block would push meaningless entries into Claude Code, Codex, etc. To scope them to OpenCode, add a tool-scoped `opencode` override key alongside the shared block — mirroring the tool-scoped override keys used by [hooks](#hooks) (`opencode.hooks`) and rules frontmatter. Categories under `opencode.permission` are merged on top of the shared block **per category** (the override wins) and are emitted **only** into `opencode.json` / `opencode.jsonc`; every other tool ignores them. Values may use a bare action string (`\"deny\"`) or, for OpenCode keys that support fine-grained matching, a pattern map (`{ \"*\": \"ask\" }`).\n>\n> ```jsonc\n> {\n>   \"permission\": {\n>     \"bash\": { \"git *\": \"allow\", \"*\": \"ask\" },\n>   },\n>   // Emitted only into opencode.json's `permission`; never leaks to other tools.\n>   \"opencode\": {\n>     \"permission\": {\n>       \"external_directory\": \"deny\",\n>     },\n>   },\n> }\n> ```\n>\n> On **import**, any OpenCode category that is not a shared canonical rulesync category (`bash`, `read`, `edit`, `write`, `webfetch`, `websearch`, `grep`, `glob`, `notebookedit`, `agent`, the all-tools key `*`, or an `mcp__*` tool name) is routed into the `opencode` override rather than the shared block, so a subsequent `rulesync generate` does not leak it into other tools.\n>\n> You may also override a **shared** category for OpenCode specifically (e.g. put `webfetch` under `opencode.permission` to give OpenCode a different value than the shared block sends to other tools). On generate this works as expected, but note the override is not round-trip stable for shared categories: re-importing the generated `opencode.json` classifies a shared category back into the shared block, so prefer expressing OpenCode-only categories here and keeping cross-tool categories in the shared block.\n\nFor Hermes Agent, permissions are written into the shared `~/.hermes/config.yaml` (global only). Canonical rules map onto the structures Hermes's runtime actually enforces:\n\n- `allow` patterns (all categories) → `command_allowlist`.\n- `bash` `deny` patterns → `approvals.deny` — Hermes's hard denylist, evaluated **before** `--yolo` / `approvals.mode: off`.\n- `webfetch` `deny` patterns → `security.website_blocklist.domains`.\n- Every `ask` rule, and `deny` rules in categories other than `bash`/`webfetch`, have no native per-pattern Hermes primitive; they survive only for round-trip (Rulesync also stores the full canonical config under a private `permissions.rulesync` key so `.rulesync/permissions.jsonc` reconstructs losslessly).\n\n> **Hermes-only override (`hermes` key):** Hermes exposes approval/security controls with no canonical permission category — e.g. `approvals` (`mode`, `cron_mode`, `mcp_reload_confirm`, ...), `security` (`allow_private_urls`, ...), `skills.write_approval`, `memory.write_approval`. Add a tool-scoped `hermes` override key alongside the shared block to author them; its contents are **deep-merged** into `config.yaml` (so an `approvals.mode` here coexists with the `approvals.deny` derived from canonical deny rules) and are emitted **only** for Hermes. The block is a verbatim passthrough, so any current or future Hermes config key can be set without Rulesync modeling each one. Note that the deep merge replaces **arrays** wholesale, so setting `hermes.approvals.deny` or `hermes.security.website_blocklist.domains` overrides (does not append to) the list derived from the shared `permission` block — use it only when you intend to replace the canonical-derived deny list for Hermes. The top-level `permissions` key is reserved by Rulesync for the round-trip blob, so a `permissions` key inside the `hermes` override is ignored.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"rm -rf *\": \"deny\" } },\n>   \"hermes\": { \"approvals\": { \"mode\": \"smart\" }, \"security\": { \"allow_private_urls\": false } }\n> }\n> ```\n\nFor Codex CLI, this generates a `rulesync` named profile in `.codex/config.toml` under `[permissions.rulesync]` and sets `default_permissions = \"rulesync\"` (project/global depending on mode). It also generates `.codex/rules/rulesync.rules` from `permission.bash` entries using `prefix_rule(...)`. Current Rulesync-to-Codex mapping supports `bash`, `read`, `edit`/`write`, and `webfetch` categories:\n\n- `bash`: generates one `prefix_rule(...)` per command pattern in `.codex/rules/rulesync.rules` (`allow` → `allow`, `ask` → `prompt`, `deny` → `forbidden`)\n- `read`: `allow` → `read`, `ask`/`deny` → `deny` in `permissions.<profile>.filesystem`\n- `edit` / `write`: `allow` → `write`, `ask`/`deny` → `deny` in `permissions.<profile>.filesystem`\n- `webfetch`: `allow`/`deny` map to `permissions.<profile>.network.domains` (Codex does not support `ask` for domain rules); `network.enabled = true` is emitted only when at least one `allow` rule is present. Deny-only domain sets are emitted without `enabled`, which Codex treats as restricted (its default) while the deny entries still round-trip back into Rulesync rules. Codex rejects the global wildcard `*` in denied domains at config load time, so `webfetch: { \"*\": \"deny\" }` is skipped with a warning (unlisted domains are denied by Codex's allowlist-first policy anyway); `webfetch: { \"*\": \"allow\" }` is emitted as a regular `\"*\" = \"allow\"` domain entry, which Codex accepts for denylist-only setups ([openai/codex#15549](https://github.com/openai/codex/pull/15549)). On import, `deny` entries are always taken, while `allow` entries are imported only when `enabled = true` is explicit — Codex treats a missing `enabled` as restricted, so importing an allow entry from a disabled profile would activate a grant Codex never had. A Codex profile with `network.enabled = true` but no `domains` is imported as `webfetch: { \"*\": \"allow\" }`, which reflects Codex's default semantics where `enabled = true` grants sandbox-wide network access (under Codex's experimental `network_proxy` feature, `enabled = true` without an allowlist blocks requests instead, and the regenerated `\"*\" = \"allow\"` entry is the closest equivalent).\n\nRelative filesystem globs such as `src/**` or `**/*.tf` are emitted under `permissions.<profile>.filesystem.\":workspace_roots\"` instead of the top-level filesystem table, because Codex expects top-level filesystem keys to be absolute paths, `~/...`, or named roots. Rulesync also sets `glob_scan_max_depth = 8` when generated workspace-root rules contain unbounded `**` patterns.\n\nThe `:workspace_roots` table also receives a default `.git` carve-out: `\".git/**\" = \"write\"`. Codex's `:workspace` baseline keeps `.git` read-only inside workspace roots, which denies basic git workflows (commit/stage operations write to `.git/index`, `.git/objects`, refs, and logs; everyday commands such as `git remote add`, `git push -u`, and local-scope `git config` write to `.git/config`). The write rule reopens the whole subtree, including `.git/config` — an earlier `\".git/config\" = \"read\"` security guard (a writable `.git/config` lets a sandboxed process set keys like `core.fsmonitor` or `core.hooksPath` that execute code outside the sandbox) was dropped because it blocked those everyday commands while the protection it added was already partial (`.git/hooks/`, and `.git/modules/**` for submodules, remains writable so hook managers such as lefthook and simple-git-hooks keep working; a sandboxed process could still install a hook directly). Users who want stricter isolation can author a more specific rule (e.g. `read: { \".git/config\": \"allow\" }` or `read: { \".git/hooks/**\": \"allow\" }`) in the canonical permissions, which wins over the default (Codex resolves the more specific path with priority). Because `.git/**` is an unbounded `**` pattern, the carve-out also means `glob_scan_max_depth = 8` is effectively always emitted unless it is suppressed.\n\nThe carve-out is skipped in three cases: a user rule for the same pattern always wins per key; the `codexcli.git_write_rules` override set to `false` suppresses it entirely (only an explicit `false` does; the default is `true`); and it is not injected when `codexcli.base_permission_profile` is `\":read-only\"` (it would grant `.git` write access inside a sandbox the user explicitly chose to keep read-only) or when the canonical rules contain a direct `\":workspace_roots\"` pattern (a whole-tree access decision that the defaults must not override). Like `:minimal`, the default-valued carve-out is not imported into the Rulesync model on `rulesync import` — it is re-added on every generate — while customized `.git` values import normally. One limitation: the `git_write_rules` flag itself cannot be recovered from `config.toml`, so it does not round-trip through `rulesync import`; if you opted out with `false`, re-add the flag to the canonical permissions config after importing (and if you want the same `.git` rules while opted out, author them as canonical `read`/`write` rules rather than hand-writing them in `config.toml` — though note that import cannot tell a user-authored `\".git/**\" = \"write\"` from the default carve-out, so that exact pattern/value pair is still skipped on import and must be re-authored in the canonical config afterwards). Migration note: configs generated before the `\".git/config\" = \"read\"` default was removed still carry that entry, and `rulesync import` now treats it as a user-authored rule — it lands in the canonical config as `read: { \".git/config\": \"allow\" }` and, because Codex gives the more specific path priority, keeps `.git/config` read-only on every regenerate. If you want the current writable default instead, delete that rule from the canonical permissions after importing.\n\nThe generated `[permissions.rulesync]` profile always extends one of Codex's built-in permission profiles via `extends`. The baseline is chosen with the `codexcli.base_permission_profile` override key (`\":read-only\"` | `\":workspace\"` | `\":danger-full-access\"`) and defaults to `\":workspace\"` when unspecified. Codex's built-in `:workspace` baseline grants read access to the whole filesystem and write access to the entire workspace root plus `/tmp` and `$TMPDIR` (with carve-outs protecting `.git`, `.codex`, and `.agents`), while `:read-only` keeps command execution read-only; the generated `filesystem` entries then grant or deny access on top of the chosen baseline. Codex's third built-in profile, `:danger-full-access`, is rejected by `extends` at Codex config load time — so selecting it works differently: Rulesync emits `default_permissions = \":danger-full-access\"` directly and skips the managed `[permissions.rulesync]` profile entirely (with the sandbox removed there is nothing for filesystem/network rules to refine; canonical `read`/`edit`/`write`/`webfetch` rules are ignored for Codex CLI with a warning, and any stale managed profile from a previous generate is pruned while sibling hand-written profiles are preserved). On import, a profile's `extends` value round-trips back into `codexcli.base_permission_profile` when it names one of the two extendable built-ins, and a top-level `default_permissions = \":danger-full-access\"` round-trips the same way; a custom parent profile is skipped and replaced by the managed baseline on regeneration (with a warning).\n\nRulesync emits `\":minimal\" = \"read\"` in the generated filesystem table by default. This enables `include_platform_defaults()` ([FileSystemSpecialPath::Minimal](https://github.com/openai/codex/pull/13434)), which provides the platform/runtime read access needed for basic sandboxed command execution on macOS, Linux, and Windows. `:minimal` is the only special path treated as a fixed baseline: it is always present in the generated table and is never imported into Rulesync's own permission model, regardless of its value. A canonical rule for `:minimal` still overrides the emitted value on generate (e.g. a `write: { \":minimal\": \"allow\" }` rule emits `\":minimal\" = \"write\"` — see the [FAQ](../faq.md#codex-cli-denies-ssh-agent-access-temp-dir-writes-or-reading-its-own-config-with-a-generated-permissions-profile) for when that is needed), but because import always skips `:minimal`, such a customization does not round-trip: after `rulesync import`, re-author the rule or the next generate falls back to `\"read\"`. The other special paths `:root`, `:tmpdir`, and `:slash_tmp` are user-managed access rules that are imported into the Rulesync model and re-emitted from it like any ordinary filesystem entry (`:root = \"deny\"` becomes a read/edit deny, `:tmpdir = \"write\"` becomes an edit allow, and so on). Because they round-trip through `.rulesync/permissions.jsonc` rather than relying on an existing `.codex/config.toml`, a restrictive value such as `:root = \"deny\"` survives a fresh-clone `rulesync generate` with no pre-existing Codex config.\n\n`network.mode`, `network.unix_sockets`, and `description` have no equivalent in Rulesync's canonical permissions model and are not generated. If an existing `.codex/config.toml` already contains these fields on the `rulesync` profile, Rulesync preserves them on regeneration — as it does any other network key it does not model (e.g. `dangerously_allow_all_unix_sockets` or Codex's proxy keys), since network settings are user territory by design. `network.enabled` is only half-managed: Rulesync sets `enabled = true` itself when the canonical model contains an allow domain, but when a regeneration computes no `enabled` value, a user-authored `enabled` is preserved (with a warning) instead of being deleted — see the [FAQ](../faq.md#codex-cli-denies-ssh-agent-access-temp-dir-writes-or-reading-its-own-config-with-a-generated-permissions-profile) for the recommended user-managed entries. The preservation applies only when the existing profile carries no allow domain: an existing `enabled` next to allow domains is Rulesync's own managed output, so removing every webfetch allow rule from the canonical model removes `enabled` too (falling back to Codex's restricted default) instead of leaving an unscoped `enabled = true` behind. Note that `filesystem`, `network.domains`, and `extends` are always managed by Rulesync (`filesystem`/`network.domains` derived from `edit`/`write`/`webfetch` rules, `extends` from `codexcli.base_permission_profile`), so hand-authored values in those fields will be replaced on regeneration.\n\n> **Codex CLI-only override (`codexcli` key):** Codex CLI's permission surface is richer than the canonical allow/ask/deny model — its approval workflow, permission-profile baseline, and per-app tool gating have no canonical category. Add a tool-scoped `codexcli` override to author them: except for `base_permission_profile`, its fields are written verbatim as **top-level `.codex/config.toml` keys** (the override wins per key; existing sibling keys the user set directly are preserved, and table values are shallow-merged) while the shared `permission` block keeps driving the managed `[permissions.rulesync]` profile and `default_permissions`. Supported keys: `base_permission_profile` (`:read-only` | `:workspace` | `:danger-full-access`, default `:workspace` — not a top-level key; it becomes the managed profile's `extends` baseline, or with `:danger-full-access` the directly-selected `default_permissions` value, see above), `approval_policy` (`untrusted` | `on-request` (legacy alias `on-failure`) | `never`, or a `{ granular = { … } }` table kept verbatim; defaults to `on-request` when neither the override nor the existing config sets it), `apps` (per-app tool gating — `apps.<id>.tools.<tool>.approval_mode` / `.enabled`, `apps.<id>.default_tools_approval_mode`), `approvals_reviewer` (`user` | `auto_review` (legacy alias `guardian_subagent`), or a table; defaults to `auto_review` when neither the override nor the existing config sets it), `tui` (the `[tui]` table — e.g. `vim_mode_default = true` for the modal Vim composer added in Codex 0.129.0, and the `tui.keymap.*` bindings beside it; the shallow merge applies one level deep, so authoring `keymap` replaces the whole existing `[tui.keymap]` table rather than merging into it), and `git_write_rules` (boolean, default `true` — like `base_permission_profile` it is not a top-level key: it controls whether the managed profile's `:workspace_roots` table emits the default `.git` carve-out described above; only an explicit `false` suppresses it). **Deprecated:** `sandbox_mode` (`read-only` | `workspace-write` | `danger-full-access`) with the sibling `sandbox_workspace_write` table (`network_access`, `writable_roots`, …) belong to Codex's classic sandbox system, which permission profiles supersede — Codex prioritizes these legacy keys over permission profiles when both are present, so authoring them disables the generated `[permissions.rulesync]` profile; they are still accepted (with a warning) so existing configs round-trip, but use `base_permission_profile` and the shared `permission` block instead. On import, the top-level keys round-trip back into the `codexcli` override, and the managed profile's `extends` round-trips into `base_permission_profile`. It is a `looseObject`, so future top-level Codex config keys can be authored here (merged verbatim on generate; only the listed keys are re-extracted on import). Example: `{ \"permission\": { … }, \"codexcli\": { \"base_permission_profile\": \":workspace\", \"approval_policy\": \"on-request\", \"approvals_reviewer\": \"auto_review\" } }`. **Out of scope:** `mcp_servers.*` per-MCP gating is **not** authorable here — it is owned by the MCP feature (`codexcli-mcp.ts` writes the `mcp_servers` tables in the same `config.toml`), and `permissions` / `default_permissions` are owned by the canonical model; any such key placed in the override is skipped with a warning. See the [Codex configuration reference](https://developers.openai.com/codex/config-reference) and [permissions docs](https://developers.openai.com/codex/permissions).\n\nFor Kiro, this generates tool permission settings in `.kiro/agents/default.json` (project mode):\n\n- `bash` maps to `toolsSettings.shell.allowedCommands` / `toolsSettings.shell.deniedCommands`\n- `read` maps to `toolsSettings.read.allowedPaths` / `toolsSettings.read.deniedPaths`\n- `edit` / `write` map to `toolsSettings.write.allowedPaths` / `toolsSettings.write.deniedPaths`\n- `grep` maps to `toolsSettings.grep.allowedPaths` / `toolsSettings.grep.deniedPaths`\n- `glob` maps to `toolsSettings.glob.allowedPaths` / `toolsSettings.glob.deniedPaths` (both emitted only when a rule is present, so existing configs do not gain empty tables)\n- `webfetch` / `websearch` with pattern `*` map to `allowedTools` entries (`web_fetch` / `web_search`)\n- `ask` rules are skipped with a warning (Kiro config does not support explicit ask entries)\n\n> **Kiro-only override (`kiro` key):** Kiro's agent config exposes per-tool `toolsSettings` knobs with no canonical allow/ask/deny category. Author them through a tool-scoped `kiro` override under `toolsSettings`: the shell auto-trust flags `shell.autoAllowReadonly` / `shell.denyByDefault`, the `aws` built-in tool's `allowedServices` / `deniedServices` (+ `autoAllowReadonly`), and the `web_fetch` domain trust arrays `trusted` / `blocked` (regex host patterns; Kiro documents these for `web_fetch` only — `web_search` has no domain-trust surface). Example: `{ \"permission\": { … }, \"kiro\": { \"toolsSettings\": { \"shell\": { \"autoAllowReadonly\": true }, \"aws\": { \"allowedServices\": [\"s3\"], \"deniedServices\": [\"eks\"] }, \"web_fetch\": { \"trusted\": [\".*github\\\\.com.*\"] } } } }`. The override is **deep-merged per `toolsSettings` key** (the override wins at the leaf) so authoring `shell.autoAllowReadonly` keeps the canonical-generated `shell.allowedCommands`; the shared `permission` block keeps driving `shell.{allowed,denied}Commands`, `read`/`write`/`grep`/`glob` paths, and the `web_fetch`/`web_search` `allowedTools` toggles. Existing non-canonical `shell` flags are preserved across regenerate even without an override. On **import**, these Kiro-specific surfaces are lifted into the `kiro` override so they round-trip. It is a `looseObject` at every level, so future Kiro `toolsSettings` fields pass through verbatim. Kiro MCP `disabledTools` lives in the separate `.kiro/settings/mcp.json` file and is modeled by the MCP feature; MCP `autoApprove` remains outside this permissions translator. See the [Kiro built-in tools](https://kiro.dev/docs/cli/reference/built-in-tools/) and [configuration reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/) docs.\n\nFor Cursor CLI, this generates `permissions` entries in `.cursor/cli.json` (project mode) or `~/.cursor/cli-config.json` (global mode). Cursor CLI only supports `allow` and `deny` decisions, so `ask` rules are skipped with a warning. Tool categories are mapped to PascalCase Cursor tool names (`bash` → `Shell`, `read` → `Read`, `edit`/`write` → `Write`, `webfetch` → `WebFetch`, `mcp__*` → `Mcp`). Existing Cursor-specific entries that Rulesync does not manage (for example, MCP entries with extra fields) are preserved on round-trip. Note Cursor scopes the file asymmetrically — \"Only permissions can be configured at the project level. All other CLI settings must be set globally\" — so in project mode Rulesync contributes only the `permissions` key, and no longer stamps `version` or `editor.vimMode` there (both are written in global mode, where Cursor reads them). Content already in a project `cli.json` is passed through untouched either way, including a `version` an earlier Rulesync version stamped: Rulesync cannot tell a key it wrote from one you wrote, so it does not delete it.\n\n> **Cursor-only override (`cursor` key):** Cursor's `cli.json` carries scalar autonomy settings with no canonical permission category — `approvalMode` (`allowlist` | `auto-review` | `unrestricted`) and a `sandbox` object (`mode`/`networkAccess`). Add a tool-scoped `cursor` override to author them: its fields are merged into the top level of the config file while the shared `permission` block keeps driving the `permissions.allow`/`permissions.deny` arrays (the override cannot clobber that managed block). These settings are **global-only** upstream, so they are written only when generating with `--global`; in project scope they are skipped with a warning naming each one, rather than written into a `.cursor/cli.json` where Cursor would ignore them and the authored setting would silently never take effect. On import, `approvalMode` and `sandbox` round-trip back into the `cursor` override. It is a `looseObject`, so `sandbox`'s (currently undocumented) value set passes through verbatim and extra `cli.json` keys can be authored here (they are merged verbatim on generate); note that only `approvalMode` and `sandbox` are re-extracted on import.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git *\": \"allow\" } },\n>   \"cursor\": { \"approvalMode\": \"auto-review\" }\n> }\n> ```\n>\n> The separate Cursor **IDE** `permissions.json` (`mcpAllowlist`, `terminalAllowlist`, `autoRun.*`) is a different file and is not targeted by this translator.\n\nFor GitHub Copilot (`copilot`), this manages the three `chat.tools.*.autoApprove` maps in the workspace `.vscode/settings.json` (project mode only). VS Code has no standalone, environment-agnostic Copilot policy file, so project-level auto-approvals are configured through VS Code Copilot Chat's workspace settings. Three canonical categories have a clean, non-lossy mapping and are emitted: `bash` → `chat.tools.terminal.autoApprove` (command patterns), `edit` → `chat.tools.edits.autoApprove` (file globs) and `webfetch` → `chat.tools.urls.autoApprove` (URL patterns). In all three, `allow` → `true` (auto-approve) and `deny` → `false` (never auto-approve); an `ask` rule is represented by **omitting** the entry, so VS Code falls through to its default in-chat approval prompt. The canonical `read` category has no VS Code approval surface, and `write` is deliberately **not** folded into the edits map alongside `edit` — doing so would make the two indistinguishable on import — so neither is emitted. VS Code also accepts a `{ \"approveRequest\": …, \"approveResponse\": … }` object per URL pattern; that form has no canonical equivalent, so it is skipped on import, and because Rulesync owns the key outright it is replaced whenever the canonical config carries any `webfetch` rule. `.vscode/settings.json` is a general workspace file (JSONC), so Rulesync merges only those three keys non-destructively and never deletes the file; every unrelated setting is preserved. VS Code's user-scope `settings.json` lives at a platform-dependent path outside Rulesync's home-relative global model, so only project scope is supported. The all-or-nothing `chat.tools.global.autoApprove` boolean and the registry-allowlist `chat.mcp.access` setting are intentionally **not** mapped, since collapsing per-pattern rules into them would misrepresent what was configured. See the [VS Code agent approvals docs](https://code.visualstudio.com/docs/agents/approvals) and the [edit-approval docs](https://code.visualstudio.com/docs/copilot/chat/review-code-edits).\n\nFor Zoo Code (`zoocode`), this manages the two command lists `zoo-code.allowedCommands` and `zoo-code.deniedCommands` in the workspace `.vscode/settings.json` (project mode only). Zoo Code is a VS Code extension and has no policy file in its `.roo/` tree; these two settings are contributed without a `scope`, which in VS Code means they are settable per workspace, and `ClineProvider.mergeCommandLists()` unions the workspace values into the lists the auto-approval decision reads. Only the canonical `bash` category maps, since Zoo Code gates terminal commands and nothing else through these settings: `allow` → `allowedCommands`, `deny` → `deniedCommands`, and an `ask` rule is represented by **omitting** the pattern from both lists so Zoo Code falls through to its own approval prompt. Entries are matched as command **prefixes**, and Zoo Code resolves a command matching both lists by the **longer** prefix — auto-approval needs a strictly longer allowed match, and a denied match that is longer or equal auto-denies — so a pattern present in both lists imports as `deny`. Patterns are literal prefixes rather than globs: apart from a bare `*` (the one entry treated as a wildcard), a pattern such as `rm -rf *` is compared with `startsWith` and so never matches `rm -rf /`. Rulesync handles that mismatch by which way it fails. A glob- or regex-shaped **deny** fails open — the entry never matches, so the command stays auto-approved — so the literal prefix it pins down is **added alongside** it (`rm -rf *` also emits `rm -rf `, `/^curl /` also emits `curl `), which makes the deny take effect and denies at least everything the original named; the addition is reported at generate time so you can narrow it if it is wider than you meant. Your own pattern stays in the file, so importing the settings back does not quietly narrow the canonical rule and change what other targets generate from it. The added prefix comes back with it, though: importing from these targets leaves the derived entry in the canonical config alongside the pattern you wrote, and every other target then emits it too (`Bash(rm -rf *)` gains a `Bash(rm -rf )` beside it). It denies no more than the pattern it came from, so it is redundant rather than wrong — delete it from `.rulesync/permissions.jsonc` if you would rather not carry it. A deny that pins down no prefix at all is left as-is and reported as inert instead: `*.sh` would yield the empty prefix, which `startsWith` matches every command against, and an alternation such as `npm run (build|test)` names alternatives rather than a prefix — write one entry per alternative. A glob-shaped **allow** fails closed — it approves fewer commands than it looks like it does, and the rest reach the approval prompt — so it is passed through unchanged and only warned about. Only unambiguous matcher syntax counts here: `*`, grouping and alternation, a leading `^`, and **anchored** `/^…/` regex literals. Everything else is a literal prefix and is left strictly alone. That includes absolute command paths — `/bin/sh` and `/etc/init.d/x` have the shape of a regex literal but are commands, which is why the anchor is required — and shell syntax generally, since Zoo Code restores variables, brackets, braces and quoted strings verbatim before matching: `echo $HOME`, `[ -f x ]` and `mv a{,.bak}` really do match, and widening them would auto-deny far more than you wrote. Once the `bash` category is stated, Rulesync owns both keys, and the two empty cases differ because their contributed defaults do. An empty allow list is written as `[]`: Zoo Code reads the _effective_ setting value, and `allowedCommands` is contributed with the default `[\"git log\", \"git diff\", \"git show\"]`, so removing the key would silently re-grant those three auto-approvals. An empty deny list **retracts** its key instead: `deniedCommands` is contributed as `[]`, so nothing resurfaces, and because VS Code resolves array settings by scope precedence rather than by merging, writing `[]` per workspace would erase a deny list you hand-authored in your user-scope `settings.json`. A canonical config that states no `bash` category at all leaves both keys exactly as you wrote them. `.vscode/settings.json` is a general workspace file (JSONC) shared with the `copilot` target's `chat.tools.*.autoApprove` keys, so Rulesync merges only its own keys non-destructively and never deletes the file. VS Code's user-scope `settings.json` lives at a platform-dependent path outside Rulesync's home-relative global model, so only project scope is supported. The `zoo-code.*` namespace is Zoo-era (the v3.74.0 rebrand renamed it from `roo-cline.*`), so the `roo` target deliberately does not emit these keys and writes its own lineage's spelling instead — see the Roo Code paragraph below. See the [Zoo Code settings contributions](https://github.com/Zoo-Code-Org/Zoo-Code/blob/main/src/package.json).\n\nFor Roo Code (`roo`), this manages the same pair of command lists under the archived lineage's own spelling, `roo-cline.allowedCommands` and `roo-cline.deniedCommands`, in the workspace `.vscode/settings.json` (project mode only). The extension's package name is `roo-cline`, so that is the namespace its contributed settings live under; both keys are present in Roo Code's final release, v3.54.0, which is why they are in the `roo` target's scope rather than being a post-fork Zoo Code addition. The mapping is identical to Zoo Code's, and shares its implementation: only the canonical `bash` category maps, `allow` → `allowedCommands`, `deny` → `deniedCommands`, an `ask` rule is represented by omitting the pattern from both lists, once the category is stated an empty allow list is written as `[]` so the contributed `allowedCommands` default cannot resurface while an empty deny list retracts its key so a user-scope deny list survives, glob- or regex-shaped denies additionally emit the literal prefix they pin down (and are reported) while glob-shaped allows are passed through with a warning, and a canonical config stating no `bash` category leaves both keys untouched. Roo Code resolves a command matching both lists by the **longer** prefix — auto-approval needs a strictly longer allowed match, and a denied match that is longer or equal auto-denies — so a pattern present in both lists still imports as `deny`. Because `roo` and `zoocode` write different keys in the same file, enabling both targets leaves all four keys in `.vscode/settings.json` and neither adapter touches the other's pair; the general advice to pick one of the two targets per project still applies, since every other feature they share writes the same files. See the [Roo Code v3.54.0 settings contributions](https://github.com/RooCodeInc/Roo-Code/blob/v3.54.0/src/package.json).\n\nFor the GitHub Copilot CLI (`copilotcli`), this manages the two URL lists in the CLI's settings file: `.github/copilot/settings.json` (project mode, repository scope — the file [shipped in CLI v1.0.60](https://github.com/github/copilot-cli/blob/main/changelog.md)) and `~/.copilot/settings.json` (global mode, user scope). Only the canonical `webfetch` category maps: `allow` → `allowedUrls`, `deny` → `deniedUrls`, and an `ask` rule is represented by **omitting** the pattern, since the CLI prompts for any URL that is in neither list. No other category is emitted — the CLI's `permissions.allow`/`ask`/`deny` rule arrays are accepted only in MDM/enterprise managed settings, and interactive tool approvals are machine-written to `permissions-config.json`, so neither is authorable here. **Scope matters:** the repository-scope key table documents `deniedUrls` (union — a repository may add denials, never remove them) but **not** `allowedUrls`, so an allow rule is only enforceable at user scope; at project scope allow rules are dropped with a warning telling you to author them with `--global`, rather than being written to a key the CLI ignores (v1.0.79 additionally warns on startup about unknown top-level keys in the user `settings.json`, so Rulesync emits documented keys only there too). On import, a project-scope `allowedUrls` is likewise ignored so a dead entry does not become an enforced allow rule, and a pattern present in both lists imports as `deny`. `settings.json` also carries unrelated keys (`model`, `effortLevel`, `hooks`, `sandbox.*`, …), so Rulesync merges only the URL keys non-destructively and never deletes the file. See the [CLI config directory reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference).\n\nFor Kilo Code, this generates the `permission` object in `kilo.jsonc` (project mode) or `~/.config/kilo/kilo.jsonc` (global mode). The shape is identical to OpenCode's (Kilo is an OpenCode fork), so categories like `bash`, `read`, `edit`, `write`, `webfetch`, and `mcp` accept either a string catch-all (`\"allow\" | \"ask\" | \"deny\"`) or a `{ <pattern>: <action> }` map. Other top-level keys in `kilo.jsonc` are preserved on round-trip. **The `permission` object is merged per top-level tool key**: for each tool key present in the rulesync output, that key is replaced entirely from rulesync (rulesync owns its managed keys; manual edits inside a managed key will be overwritten on the next generation). Tool keys that exist in the existing `kilo.jsonc` but are NOT in the rulesync output are preserved verbatim so user-added Kilo-only categories survive regeneration. When a regenerate replaces a key whose existing value contained `deny` patterns that disappear from the new rulesync output, an aggregated `logger.warn` enumerates the dropped patterns (matching the project convention used by every other permissions translator). Edits to other top-level keys (e.g. `model`) are preserved. **Malformed `kilo.jsonc` aborts the run**: the `jsonc-parser` library would otherwise silently coerce a syntax error to `{}` and overwrite the corrupted file with an empty `permission`, dropping the user's existing `deny` rules. Rulesync now surfaces parse errors so the run aborts before any destructive write — matching the strict `JSON.parse` behavior used by every other permissions translator.\n\n> **Kilo-only override (`kilo` key):** Kilo's `permission` object carries tool-specific keys with no canonical permission category — OpenCode-inherited ones (`external_directory`, `doom_loop`, `lsp`, `question`, `todowrite`, `skill`, `task`, `list`) and Kilo-unique ones (`agent_manager`, `notebook_read`, `notebook_edit`, `notebook_execute`, `repo_clone`, `repo_overview`). Add a tool-scoped `kilo` override key alongside the shared block (mirroring the `opencode` override) to author these; entries under `kilo.permission` are merged on top of the shared block **per key** (the override wins) and are emitted **only** into `kilo.jsonc`. Each value may be a bare action string or a pattern map. On **import**, any Kilo key that is not a shared canonical category (`bash`, `read`, `edit`, `webfetch`, `websearch`, `grep`, `glob`, the all-tools key `*`, or an `mcp__*` tool name) is routed into the `kilo` override rather than the shared block, so a subsequent `rulesync generate` does not leak it into other tools.\n>\n> **Kilo-only override (`kilo.sandbox`):** the `sandbox` block Kilo runs commands in is a security surface orthogonal to per-tool allow/ask/deny, with no canonical category, so it is authored under the same tool-scoped `kilo` override: `enabled` (boolean), `network` (e.g. `\"deny\"`), `allowed_hosts` (a list of `host` / `host:port` destination exceptions) and `writable_paths`. It is shallow-merged into the top-level `sandbox` key of `kilo.jsonc` — the override's keys win, unrelated sibling keys you set directly are preserved — and the whole block round-trips back into `kilo.sandbox` on import. **Scope matters here.** Kilo honors `allowed_hosts` and `writable_paths` from the _global_ config only, and lets a project config merely tighten (`enabled: true`, `network: \"deny\"`); a project-level network denial even clears the global destination exceptions. Rulesync mirrors that rather than writing config Kilo would ignore: at project scope only `enabled` and `network` are emitted, and any other key is dropped with a warning telling you to author it with `--global`. See the [sandboxing docs](https://kilo.ai/docs/getting-started/settings/sandboxing).\n\n> **Name-mismatch traps.** Canonical category names do not always match Kilo's key names: Kilo folds **`write` into `edit`** (there is no `write` key), uses **`notebook_edit`** (not the canonical `notebookedit`) and **`task`/`agent_manager`** (not `agent`), and has **no `mcp` key** (MCP is addressed via `mcp__*` tool-name keys). Rulesync passes key names through verbatim, so author Kilo keys using Kilo's own names (e.g. put a `notebook_edit` rule under `kilo.permission`, not the canonical `notebookedit`). Kilo also treats a `null` action as a delete sentinel; Rulesync does not model `null` and only round-trips `allow`/`ask`/`deny`.\n\nFor AugmentCode CLI, this generates `toolPermissions` entries in `.augment/settings.json` (project mode) or `~/.augment/settings.json` (global mode). Each entry has `toolName`, an optional `shellInputRegex` (only for shell commands), and `permission.type` ∈ `\"allow\" | \"deny\" | \"ask-user\"`. Tool category mapping: `bash` → `launch-process`, `read` → `view`, `edit` → `str-replace-editor`, `write` → `save-file`, `webfetch` → `web-fetch`, `websearch` → `web-search`. Action mapping: rulesync `ask` → AugmentCode `ask-user`. For `bash` patterns other than `*`, the glob pattern is converted to a regex and emitted as `shellInputRegex`. The glob → regex conversion maps `*` to `.*`, `?` to `.`, escapes `\\^$.|+(){}[]`, and anchors at both ends; characters outside that set (notably `-`, `/`, `:`, `,`) are emitted verbatim, so Augment will match them literally. Generated entries are sorted **deny first, ask second, allow last**, with more specific patterns (those carrying `shellInputRegex`) before catch-alls — this is required because Augment's `toolPermissions` is evaluated **first-match-wins**. Existing `toolPermissions` entries whose `toolName` is NOT in the rulesync-managed set are preserved on round-trip; existing **`deny` entries for ANY managed `toolName`** (`launch-process`, `view`, `str-replace-editor`, `save-file`, `web-fetch`, `web-search`) are also preserved (fail-closed) so a user-added deny rule on any managed tool cannot be silently downgraded by regeneration. Existing managed-tool `allow` / `ask-user` entries are still replaced (rulesync owns the permissive surface for managed namespaces). **Non-bash categories do not have a documented per-input matcher in AugmentCode**, so Rulesync emits at most one catch-all entry per tool: if the rulesync category contains any `deny` rule, Rulesync emits a single `deny` entry for the entire tool (fail-closed) and warns; otherwise only `*`-pattern allow/ask rules are emitted and any non-`*` allow/ask patterns are dropped with a warning. Importing AugmentCode entries back into rulesync recovers `bash` patterns from `shellInputRegex` but the other categories always import as the catch-all `*` pattern. **The import direction also applies fail-closed precedence** when multiple existing entries collapse to the same `(canonical, \"*\")` key (e.g. `[{view: deny}, {view: allow}]`): the most restrictive action wins regardless of iteration order (precedence: `deny` > `ask` > `allow`), so a user-added deny in the source file is never silently dropped by import order. The `launch-process` (bash) path is unchanged because each entry has its own `shellInputRegex`-derived pattern with no `\"*\"` collapse. On **import** (project scope), Rulesync also reads the layered overrides file `<workspace>/.augment/settings.local.json` — a gitignored, machine-specific file that Auggie merges on top of `settings.json` — and combines it over the base settings before converting to the canonical model, following Auggie's documented layering (simple values take the local override, `mcpServers`/`plugins` replace wholesale, and other objects/lists — including `toolPermissions`, which Auggie concatenates local-first under first-match — are combined across tiers), so personal permission overrides are picked up without dropping a committed base `deny`. This overlay is **import-only and project-only**: Rulesync never writes `settings.local.json` (it stays a user-owned, gitignored file), and AugmentCode documents no global `~/.augment/settings.local.json`, so the overlay is skipped in global mode. Whatever the local file contributed is named in a warning while importing, so a personal value is visible before it is committed; a key that governs what the tool may run — a sandbox tier, an autonomy ceiling, the hooks it executes — is called out on its own, since publishing one machine's relaxed value makes it the team's. An unknown top-level key such as `recommendedMarketplaces` (added in Auggie CLI 0.20.0) is preserved verbatim through the generate round-trip via the `{...settings}` merge.\n\n> **AugmentCode-only override (`augmentcode` key):** AugmentCode's `toolPermissions[]` supports \"custom policy\" entries the canonical allow/ask/deny model cannot express — `permission.type` of `webhook-policy` / `script-policy` (delegating the decision to a `webhookUrl` / `script`) and an `eventType` of `tool-response` (a post-execution check rather than the default pre-execution `tool-call`). Author these through a tool-scoped `augmentcode` override with a `toolPermissions` array of verbatim entries: `{ \"permission\": { … }, \"augmentcode\": { \"toolPermissions\": [ { \"toolName\": \"github-api\", \"permission\": { \"type\": \"webhook-policy\", \"webhookUrl\": \"https://api.example.com/validate\" } }, { \"toolName\": \"view\", \"eventType\": \"tool-response\", \"permission\": { \"type\": \"allow\" } } ] } }`. Authored entries are **prepended** — ahead of the canonical-generated basic rules — so a webhook/script gate or tool-response check is never shadowed by a regenerated allow/deny/ask entry under first-match-wins. When the override authors `toolPermissions` it becomes the source of truth for the special entries (the existing file's specials are no longer separately preserved, avoiding a double-emit); without an override, any special entries already present in `settings.json` are preserved verbatim as before. On **import**, special entries are lifted verbatim into the `augmentcode` override (rather than being skipped with a warning) so they round-trip and become user-authorable; basic entries continue to drive the shared `permission` block. The entry objects stay a loose passthrough so `shellInputRegex`, `webhookUrl`, `script`, and future non-policy fields survive untouched, while the documented bounded fields are validated as enums: `permission.type` (`allow` | `deny` | `ask-user` | `webhook-policy` | `script-policy`) and `eventType` (`tool-call` | `tool-response`). Both project and global scope are supported.\n\nFor Factory Droid, this generates `commandAllowlist` / `commandDenylist` arrays in `.factory/settings.json` (project mode) or `~/.factory/settings.json` (global mode). Factory Droid only gates **shell commands** through these two lists, so only the rulesync `bash` category is translated: `allow` patterns become `commandAllowlist` entries (run without confirmation) and `deny` patterns become `commandDenylist` entries (always require confirmation; the denylist wins when a command is in both). Factory Droid has **no separate `ask` list** — any command not in the allowlist already prompts — so rulesync `ask` rules are dropped. Categories other than `bash` cannot be represented in the command allow/deny model and are skipped, with a `logger.warn` when a skipped category carries a `deny` rule (to surface the gap). rulesync owns the `commandAllowlist` / `commandDenylist` keys (they are replaced from the rulesync output), while every other key in `settings.json` (e.g. `hooks`) is preserved verbatim on round-trip — except the Factory-specific security keys covered by the `factorydroid` override below, which are lifted into that override on import. Importing reads the two lists back into the `bash` category, with `.factory/settings.local.json` overlaid on top of `settings.json` first — Droid layers the two, so importing without the overlay would read permissions it does not actually enforce. Rulesync never _writes_ `settings.local.json`; generation only ever writes `settings.json`. Note the consequence for a full round-trip: a value that came from the local file is imported into `.rulesync/permissions.jsonc` like any other, so the next `generate` writes it into the shared `settings.json`. If a personal override should stay personal, drop it from `.rulesync/permissions.jsonc` after importing. Whatever the local file contributed is named in a warning while importing, so a personal value is visible before it is committed; a key that governs what the tool may run — a sandbox tier, an autonomy ceiling, the hooks it executes — is called out on its own, since publishing one machine's relaxed value makes it the team's. Rulesync gitignores `.factory/settings.local.json` itself, matching Factory's guidance to keep it out of version control.\n\n> **Factory Droid-only override (`factorydroid` key):** Factory Droid has security controls that do not fit the per-command `allow`/`ask`/`deny` model — the hard-block `commandBlocklist` tier (commands that can **never** run, not even under full autonomy — distinct from an approvable `deny`), plus `networkPolicy` (`allowedIps`), `sandbox` (`enabled`/`mode`/`filesystem`/`network`), `mcpPolicy`, `enableDroidShield`, autonomy settings (`sessionDefaultSettings`, `maxAutonomyLevel`, `subagentAutonomyLevel`, `interactionMode`, and the per-tool `mcpAutonomyOverrides`), the plugin-bootstrap keys `extraKnownMarketplaces` / `enabledPlugins` (Droid auto-registers those marketplaces and installs those plugins on start — the upstream distribution path for the same artifacts rulesync generates), the `hooksDisabled` kill-switch, `disabledSkills` (an array of skill names to disable without deleting their files), and the organization controls `modelPolicy` and `missionPolicy`. Add a tool-scoped `factorydroid` override to author them: its keys are merged into `settings.json` (the override wins) while the shared `permission` block keeps driving `commandAllowlist`/`commandDenylist`. On **import**, these keys are lifted into the `factorydroid` override — so `commandBlocklist` now round-trips faithfully (its never-runs guarantee is preserved) rather than being collapsed onto an approvable `deny`.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git *\": \"allow\" } },\n>   \"factorydroid\": { \"commandBlocklist\": [\"curl *\"], \"sandbox\": { \"enabled\": true } }\n> }\n> ```\n\nFor Cline CLI, this generates `.cline/command-permissions.json` (project mode only). Cline reads this file via the `CLINE_COMMAND_PERMISSIONS` environment variable; you can wire it up with `export CLINE_COMMAND_PERMISSIONS=$(cat .cline/command-permissions.json)`. The schema is `{ \"allow\": [...], \"deny\": [...], \"allowRedirects\": false }`. Cline only supports shell commands and only `allow`/`deny`. Non-`bash` categories are dropped and rulesync `ask` rules for `bash` are **translated to `deny`** (fail-closed safety, since Cline lacks `ask` semantics); both translation notices are surfaced via a single aggregated `logger.warn` per generation (matching the project convention used by every other permissions translator) so the translation stays visible without tripping CI gates that treat error lines as failures. **The `allow` array is wholesale-replaced by rulesync** — user-added entries inside `allow` are not preserved on regenerate. **The `deny` array is additive** — user-added denies in the existing file are preserved on every generation alongside the rulesync-derived denies (fail-closed standard). The `allowRedirects` field (a single global boolean gating shell redirection operators `>`/`>>`/`<`) can be authored from rulesync via a tool-scoped **`cline` override** — add `\"cline\": { \"allowRedirects\": true }` alongside the shared `permission` block. Precedence: the `cline` override wins, otherwise the existing file value is preserved, otherwise it defaults to `false`. On import, a `true` value round-trips back into the `cline` override (the default `false` emits no override). Cline does not have a stable per-user file location for command permissions, so global mode is not supported. If a pattern ends up in **both** `allow` and `deny` (defensive check; not reachable from a single rulesync config), Rulesync emits a warning because Cline does not document a deterministic deny-priority.\n\nFor Zed, this generates the `agent.tool_permissions` object in `.zed/settings.json` (project mode) or `~/.config/zed/settings.json` (global mode — `%APPDATA%\\Zed\\settings.json` on Windows). Each canonical category becomes a key under `agent.tool_permissions.tools.<tool>` (tool-name mapping: `bash` → `terminal`, `edit` → `edit_file`, `write` → `write_file`, `webfetch` → `fetch`, `websearch` → `search_web`; unknown categories pass through unchanged). Per-tool MCP categories are translated: canonical `mcp__<server>__<tool>` becomes Zed's `mcp:<server>:<tool>`, and imports back into the canonical spelling, so a category authored once reaches Zed and the other targets alike (a key already written in Zed's spelling is emitted unchanged but still normalizes to the canonical form on import). Only the first separator is split, so a tool whose own name contains `__` survives the round-trip. Inside an MCP category only the catch-all `*` rule is emitted, as the tool's `default`; pattern-scoped rules are dropped with a warning, because Zed dispatches every MCP tool with a single empty input (\"MCP tools are gated only by tool id (no per-input pattern matching)\"), so a pattern would be matched against `\"\"` rather than against anything meaningful. A category that omits or wildcards either half — `mcp__<server>`, `mcp__<server>__*`, `mcp__*__<tool>` — is dropped with a warning too, since Zed looks the tool up by exact key on the full triple with no glob or prefix matching. Any canonical-spelled `mcp__<server>__<tool>` entry an earlier Rulesync version left in `settings.json` is swept on the next generate, whether or not the current config still names that category: it is not a Zed tool name, so it can only be Rulesync's own output, and leaving it would resurrect stale rules on the next import. Read-only categories are not written at all: Zed's [gated tool list](https://zed.dev/docs/ai/tool-permissions#supported-tools) does not include `read_file`, `grep`, `find_path` or `list_directory` — they are in Zed's own `EXCLUDED_TOOLS` and never consult the permission settings, so neither a per-tool entry nor the global `default` reaches them. Canonical `read`, `grep` and `glob` (and a category naming one of those Zed tools directly) are therefore **dropped**, with a warning when the category carried a `deny` or `ask` rule, rather than written as entries Zed ignores. Zed's read-denial surface is `private_files`, which the ignore feature writes from `.rulesync/.aiignore`. An inert entry an earlier Rulesync version wrote is left in place rather than deleted — Rulesync cannot tell it from one you wrote, and Zed ignores it either way — and it still imports back as the canonical category, so remove it by hand if you want it gone. The canonical `*` category is the exception: its catch-all `*` rule sets the top-level `agent.tool_permissions.default` — rung 6 of Zed's precedence ladder, and the mechanism Zed documents for MCP tools — rather than an inert `tools[\"*\"]` entry (`*` is not a Zed tool name; a stale `tools[\"*\"]` entry written by an earlier version is cleaned up when the canonical config carries a `*` category, and the `default` imports back as `*: { \"*\": <action> }`). Pattern-scoped rules in the `*` category have no Zed counterpart and are dropped with a warning. Within every other category, the catch-all `*` pattern sets the per-tool `default`, while specific patterns become `always_allow` / `always_deny` / `always_confirm` entries of the form `{ \"pattern\": <regex>, \"case_sensitive\": false }`. Action mapping: rulesync `ask` ⇄ Zed `confirm` (`allow`/`deny` are shared). Because Zed matches with regular expressions, patterns are emitted verbatim — author canonical patterns as regexes when targeting Zed. The settings file is shared with the MCP (`context_servers`) and ignore (`private_files`) features, so writes merge non-destructively: unrelated settings, a user-set `agent.tool_permissions.default` (when the canonical config has no `*` category), and any `tools.<tool>` entries NOT managed by rulesync are preserved on round-trip. The canonical model has no slot for per-pattern case sensitivity, so rulesync always emits `case_sensitive: false`; a hand-authored `case_sensitive: true` on a rulesync-managed tool is overwritten on the next generate.\n\n> **Zed-only override (`zed` key):** two Zed surfaces sit outside the canonical allow/ask/deny model and are authored verbatim through a tool-scoped `zed` override. `zed.sandbox_permissions` is written into `agent.sandbox_permissions`: Zed's OS-level agent sandbox, which since [Zed 1.14.2](https://zed.dev/releases/stable) (2026-08-05) is **on by default** for the `terminal` and `fetch` tools and by default forbids network access, writing outside the project directories, and writing to `.git`. Most real setups therefore need to relax one of `network_hosts` (exact hostnames or leading `*.` wildcards), `allow_all_hosts`, `write_paths`, `allow_fs_write_all` or `allow_unsandboxed` — none of which the canonical categories can express, since this is process containment rather than tool gating. `zed.profiles` is written into `agent.profiles`, Zed's tool-availability layer: a separate enforcement stage from `tool_permissions`, because a tool absent from the active profile cannot be used no matter what the permission rules allow (per-profile keys `name`, `tools`, `enable_all_context_servers`, `context_servers`, `default_model`). Example: `{ \"permission\": { … }, \"zed\": { \"sandbox_permissions\": { \"network_hosts\": [\"*.github.com\"], \"write_paths\": [\"/tmp\"] }, \"profiles\": { \"review\": { \"name\": \"Review\", \"tools\": { \"terminal\": false } } } } }`. Both blocks pass through untouched — Rulesync canonicalizes neither, and validates only the documented `profiles` keys (`sandbox_permissions` is unvalidated, since Zed adds to it release over release) — and each is **replaced wholesale** when the override supplies it, since Zed reads each as a single policy unit; omit the key and whatever is already in `settings.json` is left alone rather than deleted, so removing a block is a manual edit. On **import**, both are lifted back into the `zed` override so a hand-written sandbox policy or profile set round-trips — including approvals you did not write by hand, since Zed saves an always-allow you clicked in the sandbox prompt into `agent.sandbox_permissions` itself. Read the imported block before committing it: an ad-hoc `allow_unsandboxed` picked up from your own machine would otherwise be regenerated into the project file and shipped to everyone. The same wholesale replace works the other way too — regenerating from an authored override discards approvals Zed had recorded since. The `zed` block authors these two keys and nothing else: `agent.tool_permissions` belongs to the canonical `permission` block, and any other key — a misspelling, or a blunt instrument such as Zed's `agent.always_allow_tool_actions` — is ignored with a warning, so nothing reachable from the override can weaken a reviewed deny. Both scopes are written, like the sibling `agent.tool_permissions`: Zed layers user settings under project settings, and a project's `.zed/settings.json` is applied once the worktree is trusted. That trust prompt is the thing to watch when you clone a repository — a project-scoped `allow_unsandboxed` or `allow_all_hosts` is a real grant, not an inert one, so review a `.zed/settings.json` you did not write before trusting the worktree. See the [Zed sandboxing](https://zed.dev/docs/ai/sandboxing) and [agent profiles](https://zed.dev/docs/ai/agent-profiles) docs.\n\nFor Qwen Code, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in `.qwen/settings.json` (project mode) or `~/.qwen/settings.json` (global mode). The format mirrors Claude Code's: entries are `Bash(<pattern>)`, `Read(<pattern>)`, `Edit(<pattern>)`, `Write(<pattern>)`, `WebFetch(<pattern>)`, `WebSearch(<pattern>)`, `Grep(<pattern>)`, `Glob(<pattern>)`, `Agent(<pattern>)`, etc. Other top-level keys in `settings.json` are preserved on round-trip. Patterns may contain nested parentheses (e.g. `Bash(echo (a))`); Rulesync uses the **last** `)` as the closing delimiter when parsing, so inner parens round-trip. Malformed entries (missing closing paren, trailing characters) emit a warning; for **`deny`** they fall back to the catch-all pattern `*` (fail-closed: broadening a deny is the safer direction), but for **`allow` / `ask`** they are **dropped** rather than broadened — silently turning a narrow user rule into `*` would be a fail-open round-trip. Generation does not create the `.qwen/` directory until `writeAiFiles` runs, so dry-run is side-effect-free.\n\nFor Kimi Code, permissions are global-only and generate `[[permission.rules]]` entries in `~/.kimi-code/config.toml`. Canonical categories map to Kimi tool patterns (`bash` → `Bash`, `read` → `Read`, `write` → `Write`, `edit` → `Edit`, `grep` → `Grep`, `glob` → `Glob`, `websearch` → `WebSearch`, `webfetch` → `FetchURL`, `agent` → `Agent`, and `mcp__…` passes through as the MCP tool name); a `*` canonical pattern emits the bare tool name and a specific pattern emits `Tool(pattern)`. Actions map 1:1 to Kimi's `allow` / `ask` / `deny`, and generated rules use `scope = \"user\"`. Kimi evaluates rules first-match-wins, so Rulesync sorts canonical output fail-closed: all `deny` rules precede `ask`, all `ask` rules precede `allow`, and more-specific patterns precede broader patterns within each action. Kimi does not match MCP tool arguments; an argument-specific MCP `allow`/`ask` is skipped with a warning rather than broadened, while an argument-specific `deny` becomes a whole-tool deny with a warning. The optional `kimi-code.defaultPermissionMode` override writes Kimi's top-level `default_permission_mode` (`manual` / `yolo` / `auto`), while `kimi-code.rules` accepts native rules that canonical categories cannot express and emits them first in their authored order. On import, Rulesync preserves the complete ordered rule list under `kimi-code.rules`, including rules that could otherwise fit the shared permission model, so regeneration cannot change Kimi's first-match behavior. A `kimi-code.tools` override writes Kimi's `[tools] enabled` / `disabled` lists — a separate enforcement layer from `[[permission.rules]]`, since a rule prompts while these remove the tool from every agent in every session. Entries pass through verbatim because the section uses agent-file tool syntax (exact built-in names, `mcp__server__*` globs) rather than the canonical category/pattern shape. Note that Kimi registers `[tools]` in its v2 engine, so today it applies under `kimi web` and experimental `kimi -p` rather than the interactive TUI. Like the MCP defaults, the section merges per key: authoring only `enabled` leaves a hand-written `disabled` list alone, and dropping the override leaves the section as it stands. Values are carried through exactly as written, empty lists included — `enabled = []` is an allowlist admitting _nothing_, the strictest setting there is, while an absent `enabled` means no allowlist at all, so the two are never interchanged. The TOML file is shared with hooks, the MCP timeout defaults and other Kimi settings, so updates merge in place and never delete the file. See the [Kimi Code permission docs](https://moonshotai.github.io/kimi-code/en/configuration/config-files.html).\n\n> **Qwen-only override (`qwencode` key):** Qwen's `settings.json` exposes autonomy/sandbox controls with no canonical permission category — under `tools` (`approvalMode` = `plan`/`default`/`auto-edit`/`auto`/`yolo`, `autoAccept`, `sandbox`, `sandboxImage`, `disabled`, `visible` — the deferred-tool startup visibility list, union-merged by Qwen across scopes), `security` (`folderTrust`, plus the two guardrails on `type: \"http\"` hooks — `allowedHttpHookUrls`, the allowlist of URL patterns a hook may POST to, where an empty list means allow-all, and `allowPrivateNetworkHooks`, which relaxes the private-IP (SSRF) check), and `permissions.autoMode` (the Auto Mode classifier config: `hints.{allow,softDeny,hardDeny}`, `environment`, `classifyAllShell`). Add a tool-scoped `qwencode` override to author them: `qwencode.tools` and `qwencode.security` are shallow-merged into the matching `settings.json` group at the **top level of that group** (an unrelated sibling key such as `tools.core` is preserved, an override key wins, and a nested object the override supplies such as `security.folderTrust` replaces the existing one wholesale rather than being deep-merged), while `qwencode.autoMode` is emitted as `permissions.autoMode` (replacing the existing `autoMode` wholesale) and the shared `permission` block keeps driving the `permissions.allow`/`ask`/`deny` arrays. On import, the documented autonomy keys (`tools.{approvalMode,autoAccept,sandbox,sandboxImage,disabled,visible}`, `security.{folderTrust,allowedHttpHookUrls,allowPrivateNetworkHooks}`, and `permissions.autoMode`) round-trip back into the override; other `tools`/`security` keys are left in `settings.json` and not extracted. One scope caveat applies: Qwen Code honors `security.allowPrivateNetworkHooks` only in user/system settings and deliberately **ignores** a workspace value, so that a cloned repository cannot grant itself private-network access. Rulesync therefore skips that key with a warning when generating project-scoped `settings.json` (a value already written into the project file by hand is left untouched), and emits it only in global mode. Import lifts it in either scope, because the file being read carries no scope marker — so if you import a project `.qwen/settings.json` that came from a repository you cloned, review the key before regenerating with `--global`, since that promotes an inert workspace value into one Qwen Code actually enforces.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"*\": \"allow\" } },\n>   \"qwencode\": {\n>     \"tools\": { \"approvalMode\": \"auto-edit\" },\n>     \"security\": { \"folderTrust\": { \"enabled\": true } },\n>     \"autoMode\": { \"hints\": { \"allow\": [\"Running tests\"] }, \"classifyAllShell\": true }\n>   }\n> }\n> ```\n>\n> **Alias overlap:** Qwen's `Read` is a meta-tool that also covers grep/glob/list, so canonical `grep`/`glob` rules are emitted as their own `Grep(...)`/`Glob(...)` entries but overlap Qwen's `Read` category at runtime; and Qwen folds web search into `web_fetch`, so a canonical `websearch` rule (`WebSearch(...)`) may not correspond to a distinct Qwen tool. `tools.disabled` is a hard whole-tool disable (stronger than `deny`) and is only authorable via the override, not the canonical `deny`.\n\nFor Pi Coding Agent, this generates the `defaultTools` array in `.pi/settings.json` (project mode) or `~/.pi/agent/settings.json` (global mode). Pi exposes no allow/ask/deny rule surface, so **no canonical permission category maps onto it** — its one repository-syncable tool gate is `defaultTools`, the list of built-in tools enabled at startup (added in Pi v0.84.2). It is an enable-list rather than an allow/deny rule set, so it is authored through a `pi` override block in `.rulesync/permissions.jsonc` — e.g. `{ \"permission\": {}, \"pi\": { \"defaultTools\": [\"bash\", \"edit\", \"write\"] } }` — and round-trips back into it on import. An empty array is meaningful and emitted as written: upstream reads it as \"start with no built-in tools\" while keeping extension and SDK custom tools. **Scope semantics are the opposite of the union merge most targets use**: a project `defaultTools` array _replaces_ the global array rather than adding to it, so the two scopes are written independently and never combined. CLI flags outrank the setting (`--tools` is a strict allowlist over all tools, `--no-tools` disables everything, `--no-builtin-tools` drops the built-in defaults, `--exclude-tools` filters the result). `settings.json` is a hand-edited file holding many unrelated keys (`theme`, `defaultModel`, `packages`, `sessionDir`, …), so writes go through the shared-config gateway with `defaultTools` as the only owned key — everything else is preserved and the file is never deleted. A config that does not state `defaultTools` leaves the key exactly as you left it. See the [Pi settings reference](https://pi.dev/docs/latest/settings).\n\nFor Warp, this generates the command allow/deny regex lists in Warp's global user `settings.toml` (**global mode only** — Warp has no project-scoped permissions file). Since Warp promoted file-backed execution profiles to Stable (2026-07-28), the surface runtime enforcement actually reads is the `command_allowlist` / `command_denylist` arrays of the `default` record under `[agents.execution_profiles.<id>]`; rulesync merges the lists into that `default` profile **in place** whenever the collection exists, preserving every other profile key and every other profile ID. The legacy `agent_mode_command_execution_allowlist` / `agent_mode_command_execution_denylist` keys under `[agents.profiles]` are still written for un-migrated installs and old clients — but on a migrated install they are inert (Warp consumes them only once during its one-shot migration). When the `[agents.execution_profiles]` collection does not exist yet, rulesync deliberately does **not** create it: on such an un-migrated install the legacy keys are still live, and creating the collection would mark Warp's migration complete early and strand the user's other legacy settings. Note that rulesync manages only the `default` profile — if a different execution profile is active in Warp, the generated lists (including `deny` rules) are not enforced until the user switches back to `default`. The settings file path differs per platform: macOS `~/.warp/settings.toml`, Linux `~/.config/warp-terminal/settings.toml`, Windows `%LOCALAPPDATA%\\warp\\Warp\\config\\settings.toml`. Only the `bash` category maps (`allow` → allowlist, `deny` → denylist); Warp matches commands with **regular expressions**, so patterns are emitted verbatim — author canonical `bash` patterns as regexes when targeting Warp (mirrors Zed). Warp has no per-command `ask` list, so `ask` rules are dropped, and non-`bash` categories are skipped (with a warning when they carry `deny` rules). Writing a `command_denylist` at all **replaces** Warp's built-in default denylist — which covers `rm`, `curl`, `wget`, `eval`, `ssh`, shells, and other risky command patterns — so rulesync warns whenever it emits a non-empty denylist; add canonical `deny` rules equivalent to the built-in patterns you want to keep (see the [Warp CLI permissions docs](https://docs.warp.dev/cli/permissions-and-profiles/)). On import, the `default` execution profile's lists are preferred (falling back to the legacy keys when no collection exists), and a pattern present in both lists resolves to `deny` (Warp's denylist wins). Both blocks are merged into the existing `settings.toml`, preserving other Warp settings, and the file is never deleted. **rulesync owns the command lists** (it is the source of truth): they are replaced from the rulesync config on each `--global` generate, so a manually curated Warp allowlist/denylist not mirrored in `.rulesync/permissions.jsonc` is overwritten — keep command permissions in rulesync (run `rulesync import` first to capture an existing hand-curated list). MCP allow/deny is a separate Warp surface not modeled here. See the [Warp agent profiles & permissions docs](https://docs.warp.dev/agent-platform/capabilities/agent-profiles-permissions/).\n\n> **Warp-only override (`warp` key):** Warp's `[agents.profiles]` table also exposes file-read/read-only autonomy knobs that do not fit the per-command `allow`/`ask`/`deny` model — `agent_mode_coding_permissions` (`always_ask_before_reading` / `always_allow_reading` / `allow_reading_specific_files`), `agent_mode_coding_file_read_allowlist` (an array of paths the agent may read), and `agent_mode_execute_readonly_commands` (a boolean auto-executing read-only commands). Add a tool-scoped `warp` override to author them: its keys are merged into `[agents.profiles]` (the override wins) while the shared `permission` block keeps driving the command lists. On **import**, these keys are lifted from `settings.toml` into the `warp` override, so they round-trip faithfully instead of being dropped. These legacy autonomy keys are part of Warp's one-shot migration, so on a migrated install they are inert; their execution-profile counterparts are authored through the nested `warp.execution_profile` block instead — `read_files` / `apply_code_diffs` / `execute_commands` / `mcp_permissions` (each `agent_decides` / `always_allow` / `always_ask`), `write_to_pty` (`always_allow` / `always_ask` / `ask_on_first_write`), `ask_user_question` (`never` / `ask_except_in_auto_approve` / `always_ask`), `run_agents` (`never_allow` / `always_allow` / `always_ask`), `computer_use` (`never` / `always_ask` / `always_allow`), `directory_allowlist` (paths readable without approval), and `mcp_allowlist` / `mcp_denylist` (MCP server IDs). Its keys are merged into the `default` record of `[agents.execution_profiles.<id>]` under the same guard as the command lists (only when the collection already exists — creating it would complete Warp's migration early; a warning is logged and the block skipped on an un-migrated install), unknown keys pass through verbatim for forward compatibility (export-only: import lifts back exactly the permission keys listed above, while profile-management keys such as `name` or the model overrides never round-trip), and the rulesync-owned `command_allowlist`/`command_denylist` always win. Example:\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git .*\": \"allow\" } },\n>   \"warp\": {\n>     \"agent_mode_coding_permissions\": \"always_allow_reading\",\n>     \"agent_mode_execute_readonly_commands\": true,\n>     \"execution_profile\": {\n>       \"read_files\": \"always_allow\",\n>       \"directory_allowlist\": [\"/home/me/projects\"],\n>       \"mcp_denylist\": [\"untrusted-server\"]\n>     }\n>   }\n> }\n> ```\n>\n> See the [Warp settings reference](https://docs.warp.dev/terminal/settings/all-settings/).\n\nFor deepagents-cli (dcode), this generates the `[shell].allow_list` array of the user config `~/.deepagents/config.toml` (**global mode only** — dcode reads no project-level config file). dcode auto-approves a shell command when the **executable name** of every segment of its pipeline is in that list and asks about everything else, matching the first token exactly (no globs) after rejecting command substitution, redirects, and process substitution outright. Canonical `bash` rules are therefore reduced to their executable: `git *`, `git:*`, `git commit:*`, and a bare `git` all emit `git` — every spelling but the first two widens the rule, since dcode holds no arguments to narrow it by, so they are written with a warning. The wildcard pattern `*` (or its `*:*` and `* *` spellings) becomes the sentinel `allow_list = [\"all\"]`, which auto-approves every command **and** skips that dangerous-pattern check, so it warns too, and is emitted as the sole entry since dcode rejects the option outright when `all` shares the list. When the same config **denies** anything, `all` is not written at all: turning the dangerous-pattern check off in the name of a rule meant to restrict would leave you with less than dcode's own default, so deny wins and the `*` allow is dropped with a warning. A pattern whose executable still holds a glob (`npm-*`), a shell metacharacter (`git;rm`, `$(id)`), a quote (`\"git\"`) or an escape (`\\git`), or is longer than the 255 characters any file name can hold, is skipped with a warning — dcode compares the name exactly, so a glob matches nothing, and a name holding a metacharacter, a quote or an escape is one dcode splits on, refuses outright, or reads differently than it is written, as is one that reduces to a sentinel name (`all`, `recommended` — use `*` for \"every command\"). `ask` needs no output, since a command outside the list already prompts; `deny` has no counterpart at all — dcode asks about an unlisted command rather than blocking it — so deny rules are reported as skipped. An `ask` or `deny` that collides with an allow beside it is worse than unenforced: the reduction collides them on the executable and dcode keeps the allow, so that command is auto-approved with no prompt. That covers a narrower rule (`npm publish` or `npm* publish` against `npm *`) and a broader one alike (`*` against any allow at all, `npm*` against every allowed name it matches), because canonically the stricter rule wins whatever its width — Rulesync collapses colliding rules as deny > ask > allow, and Claude Code applies deny first, then ask, then allow. A quoted or escaped executable (`\"git\" push`, `\\git push`) is read the way dcode reads it — without them — so an odd spelling does not hide the collision. Those cases get a warning of their own — narrow or drop the allow rule that covers them. On **import**, entries come back as `bash` allow rules named by the executable — an entry dcode could not match in the first place (`git status`, `npm-*`, anything holding a shell metacharacter, a quote or an escape such as `git;rm`, `$(id)` or `\\git`, which dcode splits, rejects or unquotes before it ever compares a name, or a name longer than 255 characters) is skipped with a warning rather than recorded as a permission the tool is not applying, and sentinels are recognized case-insensitively because upstream lowercases them — `all` as `*`, and a list mixing `all` with command names as nothing, since upstream raises on that combination and ignores the option, so those commands are not actually auto-approved. An `allow_list` holding any non-string element, or one that is not a list or a string at all, imports as nothing too, with a warning: dcode requires every element to be a string and drops the whole option otherwise. A `recommended` entry is dropped rather than expanded, with a warning of its own, because the curated list behind it is upstream's to edit — the next generate therefore drops those commands from the allowlist, which fails closed, so re-add by name the ones you want. The `all`-plus-names case warns too, since dcode ignores the whole option there and none of those commands is actually auto-approved. `config.toml` holds every dcode setting, so the `[shell]` and `[startup]` tables are merged in place and the file is never deleted; the merge is a parse and a re-emit, which keeps every unrelated key and table but **does not preserve comments**. A `shell` or `startup` that is not a table at all is left exactly as you have it, with a warning, rather than replaced. See the [deepagents-cli configuration docs](https://docs.langchain.com/oss/deepagents/code/configuration).\n\n> **deepagents-only override (`deepagents` key):** dcode's approval mode is a separate axis from the allowlist and has no canonical per-command slot, so it is authored through a tool-scoped `deepagents` override whose `startup` block is merged into `[startup]` verbatim (unknown keys pass through for forward compatibility): `mode` (`manual` / `auto` / `yolo`, the approval mode a bare launch starts in), `yolo_switcher` (whether YOLO stays in the Shift+Tab mode cycle), and `read_project_dotenv` (whether an untrusted repository's `.env` is loaded into the process environment). On **import**, exactly those three keys are lifted back into the override, and only when the value is one dcode itself would accept (a known `mode`, a real boolean for the switches) — anything else is left behind with a warning, because dcode falls back to its own default for it and writing it would produce a permissions file the next generate could not parse. `startup.recent` is deliberately not lifted at all, since dcode rewrites it as the user cycles modes and committing it would publish one session's state. Generate drops `recent` for the same reason and one more: with no explicit `mode` beside it, that key is what restores auto-approval at launch, so writing it would be a second, quieter way for a repository to change a machine's approval mode. Because this block is written into your **global** config from a `.rulesync/permissions.jsonc` a repository can carry, a value that relaxes what dcode does on its own — `mode` of `auto` or `yolo`, or a `yolo_switcher`/`read_project_dotenv` that was explicitly `false` being turned back on — is warned about by name, alongside the value it replaces (both booleans default to `true` upstream, so writing `true` over an unset key grants nothing and says nothing), and a key rulesync does not know is named too rather than passed through silently. Example:\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git *\": \"allow\" } },\n>   \"deepagents\": {\n>     \"startup\": { \"mode\": \"auto\", \"yolo_switcher\": false }\n>   }\n> }\n> ```\n\nFor the Antigravity IDE, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the committable workspace `.antigravity/settings.json` (**project mode only**). Antigravity 2.0 evaluates these `Deny > Ask > Allow` and uses `action(target)` entries; rulesync maps canonical categories onto the IDE action vocabulary: `read` → `read_file`, `edit`/`write` → `write_file`, `bash` → `command`, `webfetch`/`websearch` → `read_url`, `mcp` → `mcp` (the IDE-only `execute_url` / `unsandboxed` actions have no canonical equivalent and pass through verbatim). Because `edit`/`write` collapse to `write_file` and `webfetch`/`websearch` collapse to `read_url`, importing normalizes back to `write` / `webfetch` (a documented, lossy mapping). The `settings.json` file holds other workspace settings, so the `permissions` block is merged in place — entries for unmanaged actions are preserved — and the file is never deleted. The User-scope settings file is a platform-dependent VS-Code-style path outside rulesync's home-relative global model, so **global mode is not supported**; the workspace file is intended to be checked into git. See the [Antigravity permissions docs](https://antigravity.google/docs/permissions).\n\nFor the Antigravity CLI (`agy`), this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the global `~/.gemini/antigravity-cli/settings.json` (**global mode only**). The CLI shares Antigravity 2.0's Fine-Grained Permissions Engine with the IDE, so the same `action(target)` vocabulary and `Deny > Ask > Allow` precedence apply: `read` → `read_file`, `edit`/`write` → `write_file`, `bash` → `command`, `webfetch`/`websearch` → `read_url`, `mcp` → `mcp` (the engine-only `execute_url` / `unsandboxed` actions pass through verbatim). Because `edit`/`write` collapse to `write_file` and `webfetch`/`websearch` collapse to `read_url`, importing normalizes back to `write` / `webfetch` (a documented, lossy mapping). The `settings.json` holds other CLI settings, so the `permissions` block is merged in place — entries for unmanaged actions are preserved — and the file is never deleted. Five CLI-only autonomy/sandbox knobs outside the allow/ask/deny arrays can be authored (and round-trip) through an optional `antigravity-cli` override block in `.rulesync/permissions.jsonc`: `toolPermission` (the global autonomy preset — `request-review` (default) / `proceed-in-sandbox` / `always-proceed` / `strict`), `enableTerminalSandbox` (a boolean confining agent-run commands to OS containment), `artifactReviewPolicy` (whether the agent's artifact changes are gated on a review prompt — `asks-for-review` (default) / `agent-decides` / `always-proceed`), `allowNonWorkspaceAccess` (a boolean, off by default, letting the agent read or write files outside the active workspace roots), and `agentMode` (the baseline execution mode a session starts in — `default` / `accept-edits` / `plan`). Antigravity applies the allow/deny lists as per-rule exceptions to the preset at runtime, so rulesync authors these keys verbatim as top-level siblings of `permissions` with no precedence modeling. This override is **CLI-only** — the Antigravity IDE exposes the same concepts through a GUI with no documented JSON schema, so it does not apply to `antigravity-ide`. Example: `{ \"permission\": { … }, \"antigravity-cli\": { \"toolPermission\": \"strict\", \"enableTerminalSandbox\": true, \"artifactReviewPolicy\": \"agent-decides\", \"allowNonWorkspaceAccess\": false, \"agentMode\": \"accept-edits\" } }`. Verified against the [Antigravity CLI reference](https://antigravity.google/docs/cli/reference), [sandbox docs](https://antigravity.google/docs/cli/sandbox), [settings reference](https://antigravity.google/docs/cli/settings) and [execution modes](https://antigravity.google/docs/cli/modes). See the [Antigravity CLI permissions docs](https://antigravity.google/docs/cli-permissions).\n\nFor Rovo Dev CLI, this generates the `toolPermissions` block of `config.yml` — the global `~/.rovodev/config.yml`, and in project mode the repo-committed `.rovodev/config.yml` that the [Bitbucket Cloud Agentic Pipelines guide](https://support.atlassian.com/bitbucket-cloud/docs/rovo-dev-advanced-agentic-configuration/) documents (referenced from `bitbucket-pipelines.yml` via `config.path`, or the `--config-file` CLI flag); the project file is deliberately **not** gitignored, since committing it is how Rovo Dev permissions get enforced in CI. Rovo Dev's three levels (`allow`/`ask`/`deny`) are an exact 1:1 with rulesync's canonical actions, so action values pass through verbatim. The `bash` category maps the catch-all `*` pattern to `bash.default` and every other pattern to a `bash.commands[]` entry `{ command: <pattern as regex>, permission }` (Rovo Dev matches commands as regexes, so author `bash` patterns accordingly). The `read` category maps to the inspection tools (`open_files`, `expand_code_chunks`, `expand_folder`, `grep`) and `edit`/`write` to the mutation tools (`find_and_replace_code`, `create_file`, `delete_file`, `move_file`), written under **`toolPermissions.tools`** — the depth Rovo Dev documents. (Earlier Rulesync versions wrote them one level up, directly under `toolPermissions`, where Rovo Dev ignores them; import still reads that legacy shape as a fallback for keys the nested block says nothing about, so an old file is not lost, and a regenerate deletes the stale copies.) Because these per-tool keys hold a single level (no per-pattern rules), only the catch-all `*` of each category sets the level. Rovo Dev rewrites a single tool key when the user answers \"always allow\" to one prompt, so the four keys of a category can disagree; import collapses them back onto one catch-all by taking the strictest level (`deny` > `ask` > `allow`) rather than whichever key is read last. Rovo Dev's planning and Atlassian tools split the same way, so they ride the same two categories rather than getting one of their own: `read` also reaches `getJiraIssue` and `getConfluencePage`, and `edit`/`write` also reach `createJiraIssue`, `updateJiraIssue`, `createConfluencePage`, `updateConfluencePage` and `createTechnicalPlan` (grouped with the mutating tools because it is the planning tool that produces an artifact rather than reading one). Bear that in mind when authoring: an `edit: deny` reaches Jira and Confluence, not just the working tree. Because `edit` and `write` both map onto the same mutation tools, a conflicting catch-all between them cannot be represented; the stricter of the two levels is kept — the same `deny` > `ask` > `allow` rule import uses — and a warning is logged. Non-catch-all `allow` paths in those categories are surfaced as `allowedExternalPaths` so explicit grants are not dropped; non-`allow` non-catch-all rules cannot be expressed per-path and are skipped with a warning. Categories without a clean Rovo Dev target (e.g. `webfetch`) are skipped with a warning. `config.yml` holds all of Rovo Dev's settings (`agent`, `sessions`, `mcp`, etc.), so the `toolPermissions` block is merged in place — every other top-level key is preserved, as is any key inside `toolPermissions` that Rulesync does not manage — including tools inside `toolPermissions.tools` that no canonical category maps to, and the `toolPermissions.bash` sub-keys Rulesync never writes: `env` (the `${VAR}` passthrough that is the documented way to give a CI run a secret whose name matches Rovo Dev's `token|key|password|secret|auth|credential` filter) and `runInSandbox`. Only the `bash.default` and `bash.commands` leaves are rewritten — the `bash` map itself is merged, not replaced. Because those sub-keys now survive every generate rather than being cleared by one, treat them as durable state: the project `config.yml` is committed, so prefer `${VAR}` references over literal credentials in `bash.env`, and note that a `runInSandbox: false` committed to the file stays in force — a regenerate is not a way to reset it, and says so with a warning when it carries one through. On **import**, a tool key the file is silent about counts as the implicit fallback level (`toolPermissions.default`, or Rovo Dev's own `ask`) rather than as absent, and the category still collapses to the strictest of the set. That matters because Rovo Dev writes a single key when the user answers \"always allow\" to one prompt: without the fallback, one such answer about `create_file` would import as a blanket `edit: allow`, and the next generate would hand that grant to every other tool of the category — Jira and Confluence writes included. A category the file says nothing about at all is still skipped rather than invented.\n\n**Migration note.** `toolPermissions.default` and the seven planning/Atlassian keys became Rulesync-owned in the release that added them. Ownership means the first generate after upgrading removes a hand-written value for one of them unless `.rulesync/permissions.*` produces it — a hand-written `tools.createJiraIssue: deny` or `default: deny` with no matching rule in the rulesync source is dropped (with a warning naming each key), falling back to Rovo Dev's `ask`. Run `rulesync import --targets rovodev --features permissions` before the first generate to carry those values into the rulesync source.\n\nThe canonical all-tools category `*` maps to `toolPermissions.default`, the level Rovo Dev falls back to for any tool with no more specific setting (Rovo Dev's own default is `ask`) — derived from its catch-all exactly as `bash.default` is derived from `bash`'s, and round-tripped back on import. The default is a single level, so a pattern rule inside the `*` category has no counterpart and is skipped with a warning. The keys Rulesync does manage (`default`, `bash.default`, `bash.commands`, `allowedExternalPaths`, and the per-tool keys above) are owned rather than merged: each generate rewrites them from `.rulesync/permissions.*`, so removing a rule there removes it from `config.yml` too (a source stating no rule at all clears them; one whose rules simply have no Rovo Dev counterpart keeps the block's restrictions but strips its grants — an `allow` there is normally a leftover of an earlier generate, and dropping one falls back to Rovo Dev's stricter default, whereas clearing the whole block would relax every level), logging a warning naming each owned key it removes — per-tool levels and `allowedExternalPaths` are written from inside a Rovo Dev session too, by an \"always allow\" prompt answer and the `/directories` command, and a hand-edit to one of those keys — including a path added with the in-session `/directories` command, which writes to `allowedExternalPaths` — is replaced on the next generate (values only — YAML comments and formatting in the existing file are not retained on rewrite) — and the file is never deleted. See the [Rovo Dev CLI settings](https://support.atlassian.com/rovo/docs/manage-rovo-dev-cli-settings/) and [tool permissions](https://support.atlassian.com/rovo/docs/use-tools-in-rovo-dev-cli/) docs.\n\nFor Goose, this generates the `user` block of the global `~/.config/goose/permission.yaml` (**global mode only** — Goose persists per-tool permission overrides only under the home directory and has no project-scoped permissions file). Goose stores permissions as a YAML map of mode key → `{ always_allow, ask_before, never_allow }`, where each field is a list of tool-name strings; rulesync writes the user-set decisions under the `user` key. Action mapping is a 1:1: `allow` → `always_allow`, `ask` → `ask_before`, `deny` → `never_allow`. Tool-name mapping: `bash` → `developer__shell`, `edit` → `developer__text_editor`; every other category passes through verbatim as the Goose tool name (so namespaced tools like `developer__text_editor` or `developer__image_processor` round-trip). Because Goose permission lists hold **whole tool names** rather than per-command/per-path globs, only a category's catch-all `*` pattern is representable — non-catch-all patterns are skipped with a warning. `write` collapses onto `developer__text_editor` too, so a conflicting `edit`/`write` catch-all cannot be represented; `edit` takes precedence and a warning is logged. The `permission.yaml` file is merged in place: the `user` block is owned by rulesync, while every other top-level key (notably the `smart_approve` LLM-decision cache) is preserved, and the file is never deleted. See the [Goose tool permissions docs](https://goose-docs.ai/docs/guides/managing-tools/tool-permissions/).\n\nFor the Grok Build CLI (`grokcli`), this generates Grok's Claude-style `[permission]` rule arrays — `allow` / `deny` / `ask` — in the project `./.grok/config.toml` (project mode) or the user `~/.grok/config.toml` (global mode, via `--global`). Grok documents that \"Project configs are limited to MCP servers, plugins, and permission rules, not full user configs\" ([settings docs](https://docs.x.ai/build/settings)), so the fine-grained `[permission]` rules are valid at both scopes. Each canonical `permission.<category>.<pattern>` becomes a Grok entry bucketed into the matching array: `bash`→`Bash`, `read`→`Read`, `edit`→`Edit`, `grep`→`Grep`, `webfetch`→`WebFetch`, `websearch`→`WebSearch`, and `mcp__<server>__<tool>`→`MCPTool(<server>__<tool>)`; a `*` pattern emits the bare tool name (e.g. `Bash`) and a concrete pattern emits `Tool(pattern)` (e.g. `Bash(git *)`). `write` collapses onto `Edit` (Grok has no separate `Write` tool — a documented lossy mapping), and categories with no Grok tool (`glob`, `notebookedit`, `agent`) are skipped, with a warning when a skipped category carries a `deny` rule. Grok evaluates the arrays with precedence `deny > ask > allow`, which import mirrors (a tool listed in multiple arrays resolves to the strictest action). The coarse `[ui] permission_mode` toggle (`\"ask\"` / `\"always-approve\"`) is still written as a backward-compatible fallback for older Grok versions: `always-approve` when the config is pure-`allow`, otherwise `ask` (conservative — never `always-approve` while any `deny`/`ask` rule exists, so it never contradicts the fine-grained arrays). Grok's third mode, `auto` (classifier-based, toggled in the TUI with `/auto`), is an exception in both directions: nothing in the canonical model derives it, so Rulesync never writes it — and a `config.toml` that already selects it keeps it, since overwriting would silently downgrade the user to `ask` on every `generate --global`. The fine-grained arrays are still written in that case; only the coarse toggle is left alone. On import, both documented `[permission]` forms are parsed back into canonical categories: the compact `allow`/`deny`/`ask` arrays and the verbose `[[permission.rules]]` tables (`{ action = \"allow\", tool = \"bash\", pattern = \"git *\" }`). The verbose `tool` field is documented lowercase (`any`/`bash`/`edit`/`read`/`grep`/`mcp`/`webfetch`) while the compact entries are capitalized, so it is matched case-insensitively and `mcp` folds into the canonical `mcp__…` categories exactly as `MCPTool(…)` does; a rule with no `pattern` covers the whole tool. Rules from the two forms merge with the same `deny > ask > allow` precedence, and a rule naming a tool with no canonical category (e.g. `any`) is skipped. Only when neither form carries a rule do we fall back to the coarse mode (`always-approve` ⇄ `bash: { \"*\": \"allow\" }`, `ask`/unset ⇄ `bash: { \"*\": \"ask\" }`). Generate always writes the compact arrays. `config.toml` is shared with the MCP feature, so rulesync owns the `[permission]` `allow`/`deny`/`ask` arrays and `[ui] permission_mode` while every other key (e.g. `[mcp_servers]`, `[sandbox]`) is preserved, and the file is never deleted — including a hand-authored verbose `rules` array, which is read on import but left untouched on generate rather than reconciled against the arrays rulesync writes. **Migration:** a `config.toml` written by an earlier Rulesync may carry hand-authored `WebSearch` entries that were preserved verbatim as unmanaged; they are now parsed into the canonical `websearch` category and regenerated as Rulesync-owned entries. See the [Grok CLI settings reference](https://docs.x.ai/build/settings/reference) and [modes docs](https://docs.x.ai/build/modes-and-commands).\n\nFor Vibe (mistral-vibe), this generates per-tool `[tools.<tool>]` tables in the shared `.vibe/config.toml` (project mode) or `~/.vibe/config.toml` (global mode). Tool-name mapping: `bash` → `bash`, `read` → `read_file`, `edit` → `edit`, `write` → `write_file`, `webfetch` → `web_fetch`, `websearch` → `web_search`, `grep` → `grep`, `agent` → `task`. These are Vibe's builtin tool names (`BaseTool.get_name()`, the snake_case of each tool class); `edit` and `write_file` are distinct tools — `write_file` has been create-only since v2.14.0 — so the two canonical categories no longer collapse onto one name. **Migration:** a `config.toml` written by an earlier Rulesync may still carry `write_file` entries derived from the `edit` category, or inert `[tools.fetch]` / `[tools.search_web]` / `[tools.agent]` blocks. Rulesync only rewrites the names it now emits, so remove those stale entries by hand — a leftover `disabled_tools = [\"write_file\"]` keeps Vibe's `write_file` disabled even though no canonical rule asks for it, and inert `[tools.glob]` / `[tools.notebookedit]` tables an earlier Rulesync emitted for tools Vibe does not have stay on disk until removed by hand (new generates skip those categories instead of rewriting them). Within a category, the catch-all `*` pattern sets the per-tool `permission` (`allow` → `always`, `ask` → `ask`, `deny` → `never`); a wildcard deny additionally adds the tool to the top-level `disabled_tools` filter. A wildcard allow deliberately does **not** touch the top-level `enabled_tools` key: upstream treats it as an **exclusive** allowlist (“if set, only these tools will be active”), so expressing allows through it — as earlier Rulesync versions did — silently switched off every other builtin and MCP tool; the per-tool `permission = \"always\"` entry carries the allow completely, and a regenerate now removes the exclusive entries an earlier version wrote for the tools it configures (`disabled_tools` entries, by contrast, are only cleared by a category that actually states a base permission with a `*` rule — clearing them for a category holding pattern rules alone would silently promote a disabled tool to “enabled, with a denylist”; on **import**, a `disabled_tools` entry likewise wins over a `[tools.<name>]` table that contradicts it — permission and patterns alike are skipped for that tool, because Vibe applies the filter last and unconditionally: reading the table's `permission = “ask”` (or `always` plus an `allowlist`) as the tool's real state would import a hand-written contradiction as a mere prompt and drop the filter on the next generate, and importing one of its patterns as an `allow` would carry a hole through a switched-off tool into every **other** tool's generated config. The match is on Vibe's own tool name rather than the canonical category, since `name_matches` globs the raw name: a bare `disabled_tools = [“read”]` matches no builtin upstream, so it must not silence `[tools.read_file]`. The entry itself is still imported as a deny for its canonical category, because Rulesync cannot see Vibe's registry — an MCP server may well publish a tool named exactly `read` — and denying something that is already off costs nothing where dropping a real deny would. The match follows upstream's `name_matches`, which trims each entry, skips a blank one, and then applies a case-insensitive `fnmatch` glob over the raw name — so `disabled_tools = [\"read_*\"]`, `[\"READ_FILE\"]` and `[\" read_file \"]` all silence `[tools.read_file]`, while `[\"\"]` silences nothing and is dropped rather than imported as an empty category: the canonical `read` category is denied on import, beside the literal `read_*` entry, which is carried out verbatim so the glob keeps its reach over the tools Rulesync cannot enumerate — an MCP tool registered at run time. A `re:`-prefixed entry, which Vibe matches as a Python regular expression, is deliberately **not** evaluated: Python's regex dialect is not JavaScript's, and a wrong verdict either drops a table's rules or carries a disabled tool out as an allow, so such an entry is matched only by its exact spelling and a warning names the tables that were therefore imported as authored; a glob longer than 256 characters is left alone and reported the same way, since a tool name is short in every registry Vibe reads and matching a kilobyte-long entry against a kilobyte-long table name buys nothing. A glob that _is_ resolved is walked step by step against fnmatch's own rules rather than translated into a JavaScript regular expression: the two dialects disagree about exactly the bracket corners (a `]` straight after `[` is a member to fnmatch and an empty class to JavaScript; an inverted range such as `[z-a]` is not dropped upstream but _closed over_, taking the member before it and the member after it with it, so `[z-a]` matches nothing, `[!z-a]` matches everything, `[b-ax]` is just `[x]`, and `[a--!]` collapses to a bare `!` that then negates an empty class and matches everything), and a translated `*a*a*a*b` backtracks catastrophically against a long tool name where the walk stays linear per `*`. The deny patterns of a table the filter switches off are carried across even though its allow patterns are not: dropping them would lose a deny the file states outright, which is the broadening direction. Where a canonical category is shared — `read_file` and a bare `read` MCP table both land on `read`, as do `task` and `agent` — the blanket deny is re-asserted after every table has been read, so the category is denied whichever order the tables happen to sit in; letting the later table decide made the import depend on that order, and in one of the two orders a tool the file had switched off was imported as a live allow. On **generate**, a glob left in `disabled_tools` is for the same reason never deleted to make room for an allow Rulesync just wrote — it reaches tools Rulesync cannot see, and removing it would switch those back on — so the contradiction is reported with a warning instead, since Vibe applies the filter last and unconditionally — the warning names only the globs that actually reach a table Rulesync wrote, and an entry Rulesync does not work out — a `re:` regular expression, or a glob past the 256-character cap — gets a warning of its own asking you to check it by hand rather than being listed beside tables some other glob matched. Both warnings print each name with its control characters stripped and its width capped at 80 terminal columns, and name at most ten before counting the rest, since the text comes from a `config.toml` that may have been checked in by someone else); specific patterns become **`allowlist` / `denylist`** entries — these are the keys Vibe's permission engine actually reads (`BaseToolConfig`), so the legacy `allow` / `deny` keys are dropped on generate from every table a category writes (still honored on import). A table carrying **both** spellings holds one list Vibe enforces and one it ignores, so both are read as a single list and written back under the canonical key: preferring either alone would drop the other, and on the deny side that silently discards a restriction Vibe was applying — multiplied across all three shell tables by the fan-out below. The two sides are not symmetric: reading both deny lists can only restrict further, while reading both allow lists **promotes** a pattern Vibe was ignoring into one it enforces (an `allowlist` match is unconditionally allowed even under `permission = “never”`), so that promotion is announced with a warning naming the patterns — delete them from `config.toml` if the legacy list was stale. Vibe has no per-pattern `ask`, so pattern-level `ask` rules are skipped with a warning. A canonical category with no Vibe builtin tool at all (e.g. `glob`, `notebookedit`) is likewise skipped with a warning instead of emitting an inert `[tools.<category>]` table — a `deny` written there would look applied while Vibe ignores it. The all-tools `*` category is skipped for a different reason: Vibe's config has per-tool tables only, and while `disabled_tools` does match glob patterns (`name_matches`), an entry there removes the tool from the registry outright rather than acting as a default the sibling `[tools.<name>]` tables can override — so `disabled_tools = [\"*\"]` would silently swallow every `allow` authored next to the wildcard. A category that is **not** a canonical Rulesync category is taken at face value as a Vibe tool name and written to `[tools.<name>]`: Vibe's tool manager resolves that table for every registered tool rather than only the builtins, so this is how per-MCP-tool permissions are authored, and `vibe.permission.<name>.sensitive_patterns` works there too. Because Vibe publishes an MCP tool as `<server>_<tool>`, the cross-tool canonical spelling `mcp__<server>__<tool>` is translated to that name on generate (`mcp__github__create_issue` → `[tools.github_create_issue]`; only the first `__` is split, so a tool name may itself contain one). The translation is one-way — Vibe's name carries no `mcp` marker — so import keeps `github_create_issue` as the category; regenerating from it writes the same table. A server-scoped `mcp__<server>` category is skipped with a warning, since Vibe has no server-level permission table; so is a wildcard one (`mcp__<server>__*`, `mcp__*__<tool>`), because a `[tools.<name>]` lookup is exact even though `disabled_tools` entries are glob-matched, which would make `[tools.\"github_*\"]` an inert deny. Since a non-canonical name is written verbatim, a misspelled builtin (`powershel`) becomes an inert table; case mistakes (`Bash`), a mis-cased MCP prefix (`MCP__github__x`) and a glob in the name (`github_*`, whose pattern-level rules Vibe never looks up because `[tools.<name>]` is matched exactly) are the ones detectable without guessing, and those are warned about. The `bash` category is written to three tables — `bash`, `git_bash` and `powershell` — because Vibe's managed shell is a different tool on each platform: the POSIX one publishes `bash`, but on Windows it is `git_bash` or `powershell`, so a `bash` deny landing only on `[tools.bash]` left the shell fully allowed there. Author `git_bash` or `powershell` as its own category in the shared `permission` block to override the fan-out for that shell. A `vibe.permission.<shell>` entry does **not** claim it for the base permission: that block carries `sensitive_patterns` only, so treating it as a claim would strip the `bash` permission from the shell without putting anything in its place — its patterns are merged onto the fanned-out table instead, and a `vibe.permission.<shell>` entry does keep `vibe.permission.bash`'s patterns from overwriting the ones authored for that shell. A shell category that expresses nothing Vibe can read (only pattern-level `ask` rules, or no rules at all) likewise does not claim the shell, since it would otherwise cancel the `bash` deny and write nothing in its place. The fan-out also stands down for a shell the existing `config.toml` already configures differently from `[tools.bash]`, and warns when it does — that is a permission decision made outside the `bash` category, and overwriting it could broaden a `permission = \"never\"` into whatever the canonical `bash` category says. Standing down costs that shell only its **base permission and allow patterns**: the `bash` category's `deny` patterns are still merged into the shell's `denylist` (and its legacy `deny` key folded into the canonical one), because Vibe resolves a denylist match before the allowlist and before the configured permission, so those entries can only restrict the shell further — leaving them out would let a deny you authored go silently missing on one of the three shells. A shell that exists only as a `disabled_tools` entry is skipped there: it is off the registry entirely, so a `denylist` for it would be inert, and writing one would invent a table you never authored. A shell that has its own category in the shared `permission` block is neither stood down from nor reported: that category owns the table outright. The one exception is a `bash` category whose `*` rule is a **deny**: that cannot broaden anything — the shell ends up disabled outright, which is at least as strict as whatever it held — and standing down there would leave an authored deny silently absent from one of the three shells, the exact failure the fan-out exists to prevent. A wildcard deny therefore overwrites the shell (with a warning, which also says that the shell's own `allowlist` / `denylist` entries are replaced along with its permission — the shell ends up disabled outright, so nothing it held is still enforced). Author that shell as its own category to keep a different permission for it. Only the permission keys the fan-out itself mirrors take part in that comparison (`permission`, `allowlist`, `denylist` — with the legacy `allow` / `deny` spellings normalized to the canonical ones — plus `disabled_tools` membership), so a key outside it on `[tools.bash]` — a `timeout`, say, which is carried over for `bash` but never copied to the aliases — does not make Rulesync's own output look hand-authored and freeze the fan-out on the next generate. `sensitive_patterns` is outside it for the same reason: that key is written by the `vibe.permission` pass, which addresses each shell **by name**, so a `vibe.permission.git_bash` entry legitimately leaves that shell holding patterns `[tools.bash]` does not have — counting it would read Rulesync's own output as an outside decision and freeze the fan-out, and mirroring it would overwrite the per-shell patterns you asked for. It is still **filled in** where a shell has none of its own, so a hand-authored `[tools.bash] sensitive_patterns` guard travels with the permission it guards instead of the shells receiving the bare allow. The copy keeps the order it was authored in: `[tools.bash]`'s own list is a key Rulesync does not write, so it is left alone, and sorting only the copy made one guard read as two different lists across the three shells. The fill is one-way — it never clears a shell's patterns — so deleting the `[tools.bash]` guard afterwards leaves the copies behind on the Windows shells; that asymmetry is reported with a warning, because an import would otherwise read them as per-shell rules and write `vibe.permission.<shell>.sensitive_patterns` entries you never authored, which claim those shells out of the fan-out for good. Values are compared as sets, not as written: `denylist = [\"b\", \"a\"]` beside `denylist = [\"a\", \"b\"]` is the same decision, and treating the order as a divergence would strand a `bash` deny on a shell that already agrees with it. A table holding none of those keys — or holding one only as an empty list, which is the absent key spelled out (and which Rulesync drops from its output rather than carrying over) — states no decision and is fanned out over; a key whose value is not a list at all (`denylist = “rm -rf *”`) does count as a decision, even though Vibe's own `BaseToolConfig` types it as `list[str]` and fails to load the file — of the two ways to be wrong about it, deleting the key is the one you cannot recover from (the `bash` deny merge stands down from such a table too, with a warning, since merging into a non-list would replace it rather than add to it — and in that case, as when the `bash` category carries no `deny` patterns at all, the stand-down warning says that **nothing** from the category reaches the shell rather than promising a merge that does not happen); the stand-down warning is likewise only raised when there is a `bash` permission to stand down — when only a `vibe.permission.bash` entry exists, the warning says that its `sensitive_patterns` are what does not reach the shell. The fan-out is also skipped when the `bash` category itself expresses nothing Vibe can read: with no permission to spread, mirroring would push whatever `[tools.bash]` already carries onto shells the file never configured, silently broadening them. When the fan-out does run it **mirrors** `[tools.bash]`'s permission keys onto the two aliases rather than merging each alias with its own previous contents (their unmanaged keys are kept): merging would diverge them the first time `[tools.bash]` carried an entry the aliases lacked — which Rulesync's own output does as soon as a hand-authored `denylist` is merged into `bash` — and that divergence would then stand the fan-out down forever, stranding every later `bash` deny on POSIX. Mirroring is safe precisely because a shell stating a decision of its own has already been excluded, and it makes regenerating idempotent. `disabled_tools` membership is mirrored too, for the same reason. `enabled_tools` membership is deliberately excluded: it is an exclusive registry filter rather than a permission, and counting it let `enabled_tools = [\"powershell\"]` take that shell out of a `bash` deny while leaving it the only active tool. On import, a Windows shell table identical to `bash` is collapsed back into the single `bash` category, while one that differs is kept as its own. Unknown `[tools.*]` tables already on disk still round-trip untouched. The `config.toml` file is shared with the MCP feature, so writes merge non-destructively and the file is never deleted. See [mistral-vibe](https://github.com/mistralai/mistral-vibe) (`vibe/core/tools/base.py`).\n\n> **Vibe-only override (`vibe` key):** Vibe's `BaseToolConfig` also carries a `sensitive_patterns` list — patterns that escalate to **ASK even when the base permission is ALWAYS** (allow). The canonical model can only set a pattern to a single `allow`/`ask`/`deny`, so an \"allow by default but ask on these patterns\" escalation cannot be expressed in the shared block. Add a tool-scoped `vibe` override to author it: `vibe.permission.<category>.sensitive_patterns` carries the list per canonical category (e.g. `bash`, `edit`), while the shared `permission` block still sets the base permission and allow/deny lists. On import, a tool's `sensitive_patterns` round-trips back into the `vibe` override (the base allow stays in the shared block). rulesync owns the list for any category named in the override (a present list is set, an empty one clears it); categories not named keep whatever the existing `config.toml` had. A `vibe.permission.bash` entry is fanned out to the Windows shells like the base permission is, but where a shell's `config.toml` table already sets **different** patterns of its own it **merges** into them instead of replacing them, and warns that it did: those patterns are what still escalates to ASK once the base permission becomes ALWAYS, so they are the author's only remaining defense there, while dropping the override's patterns would strand a newly added guard on that one shell. A union is safe in both directions because `sensitive_patterns` only ever escalates to ASK. An empty `sensitive_patterns = []` counts as no patterns of the shell's own — it is the absent key spelled out, and Vibe's own config dump writes it that way — so the override's list is applied there in full. The reverse case is the exception to “an empty list clears it”: an empty `vibe.permission.bash.sensitive_patterns` clears the patterns this override owns, but a shell that authored **different** patterns of its own keeps them (with a warning saying so) — delete them from `config.toml` to clear them. Name that shell in `vibe.permission.<shell>.sensitive_patterns` to own its list outright. `sensitive_patterns` is the only key this override can express — a `permission`, `allowlist` or `denylist` written inside `vibe.permission.<category>` is ignored with a warning, since the shared `permission` block is where those belong and the base permission it sets can be the exact opposite of what the ignored key asked for. The override also carries `vibe.enabled_tools` — the only way to author Vibe's top-level **exclusive** allowlist. The list is written verbatim in Vibe's tool-name vocabulary (declaring it, even empty, makes rulesync own the whole key), and on import a non-empty `enabled_tools` is lifted back into the override rather than being misread as a set of `\"*\": \"allow\"` grants. Note the `config.toml` scope semantics: since v2.24.0 Vibe installs the user and project TOML layers **together** rather than picking one, so a trusted project config overlays the user config instead of replacing it, and a `--global` run is no longer discarded wholesale by a project `config.toml` — the project layer still wins key by key where it sets one, but every key it leaves unset falls through to the global file. Merging is per key: `mcp_servers` and `connectors` union-merge by name, `tools` deep-merges, `disabled_tools` concatenates, and `enabled_tools` is replaced wholesale by the higher layer. An org-enforced `AdminConfigLayer` sits above every layer at runtime and can override anything below it. (Whether a project layer is read at all still depends on Vibe trusting the project, so treat the overlay as the trusted-project behavior.)\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"*\": \"allow\" } },\n>   \"vibe\": { \"permission\": { \"bash\": { \"sensitive_patterns\": [\"rm *\", \"sudo *\"] } } }\n> }\n> ```\n\nFor Takt, this generates the `default_permission_mode` under `provider_profiles.<provider>` in the shared `.takt/config.yaml` (project mode) or `~/.takt/config.yaml` (global mode). Takt does not have per-tool / per-pattern rules; tool gating is a single coarse mode per provider profile, ordered `readonly` < `edit` < `full` (`readonly` may only read, `edit` may also edit/write files, `full` may also run shell commands). The active provider is resolved from `runtime.yaml` first when Takt is in runtime provider mode (see below) — the provider of the profile named by `provider.defaults.profile`, with no fallback, matching Takt (a lone profile is not promoted to the default, and `defaults.pool`/ladder forms resolve at run time) — and otherwise from the top-level `provider:` key of `config.yaml`, the sole `provider_profiles` entry, or the `claude` default. `provider_profiles` itself stays in `config.yaml` in every version: it is not a legacy provider signal, and Takt does not move permission modes into `runtime.yaml`. The mapping is therefore **lossy**: on generate, a single mode is derived with this precedence — (1) any `deny` rule anywhere ⇒ `readonly` (conservative — keep the narrowest mode whenever the user expressed any restriction); (2) else any `edit`/`write` category `allow` rule ⇒ `edit`; (3) else any `bash` category `allow` rule ⇒ `full`; (4) else ⇒ `readonly` (safe default). On import, `full` ⇄ `bash: { \"*\": \"allow\" }`, `edit` ⇄ `edit: { \"*\": \"allow\" }`, and `readonly` (or an unset/unknown mode) ⇄ `bash: { \"*\": \"deny\" }`. `config.yaml` is shared with other Takt settings, so the mode is merged in place — every other provider profile and all other top-level keys are preserved — and the file is never deleted. Takt's default-deny **workflow security policies** — `workflow_arpeggio` (`custom_data_source_modules`, `custom_merge_inline_js`, `custom_merge_files`), `workflow_runtime_prepare.custom_scripts`, `workflow_command_gates.custom_scripts`, `sync_conflict_resolver.auto_approve_tools`, and the `allow_git_hooks` / `allow_git_filters` booleans — have no canonical permission category, so they are authored through the `takt` override block of `.rulesync/permissions.*` and round-trip on import. Each admits one class of user-supplied code, so only the exact shapes Takt itself accepts are written: a sub-key Takt does not declare is dropped with a warning rather than passed through, since Takt's schemas are strict and reject the whole file on an unknown key, while a value of the wrong type fails when `.rulesync/permissions.*` is read. Removing one of these keys from `config.yaml` because the source no longer states it is warned about too — including a key put there by hand, which owning them implies. Deleting `.rulesync/permissions.*` altogether is different: the feature has no source to generate from, so nothing runs and whatever is in `config.yaml` stays. These keys are also authoritative rather than merged — revoking one in `.rulesync/permissions.*` removes it from `config.yaml`, instead of leaving the capability switched on. `workflow_mcp_servers` stays with the MCP feature, which derives it from the transports in use.\n\nTwo Takt-specific surfaces with no canonical category can be authored (and round-trip) through an optional `takt` override block in `.rulesync/permissions.jsonc`: `step_permission_overrides` (a per-workflow-step map `<step>` ⇒ `readonly`/`edit`/`full`, written inside the active provider profile and layered by Takt on top of `default_permission_mode`) and `provider_options` (a top-level, per-provider table of sandbox/network knobs orthogonal to the mode, e.g. `codex.network_access`, `claude.sandbox.allow_unsandboxed_commands`, `opencode.allowed_tools`). Example: `{ \"permission\": { … }, \"takt\": { \"step_permission_overrides\": { \"ai_review\": \"readonly\" }, \"provider_options\": { \"codex\": { \"network_access\": true } } } }`. Note the workflow-step `required_permission_mode` floor is a field of the **workflow YAML**, not `config.yaml`, so it is intentionally out of scope (Takt's config loader hard-rejects unknown top-level keys).\n\n**`provider_options` and Takt 0.56.0 (`runtime.yaml`).** From 0.56.0, provider configuration lives in `runtime.yaml` (`.takt/runtime.yaml` for the project, `~/.takt/runtime.yaml` globally), and \"runtime provider mode\" is active as soon as its `provider:` section carries an actual assignment — a non-empty `defaults`, `profiles` or `auto_routing`, or a `targets` map with at least one non-empty entry. A file holding only `version: 1`, or empty maps such as `defaults: {}`, is inactive and leaves the legacy resolution in place. While runtime mode is active, **any** legacy provider setting in `config.yaml` — `provider_options` among them — stops Takt with `Mixed provider configuration detected` before it runs an agent, and Takt generates an active `~/.takt/runtime.yaml` on first launch in a fresh environment, so new installs are in runtime mode by default. Rulesync therefore reads `runtime.yaml` — both the scope being generated and the global one, because Takt collects legacy signals from both `config.yaml` files — and merges them the way Takt's loader does before deciding anything: `provider.profiles` is a union in which a project profile replaces the global profile of the same name, while `defaults`, `targets` and `auto_routing` are taken from the project file whole whenever it states them at all, so a project `targets: {}` masks the global one rather than merging with it. On that merged document, while runtime mode is active, rulesync **refuses to write `provider_options`** into `config.yaml`, warning instead of quietly emitting a key that would take the install down. Rulesync does not write `runtime.yaml` itself: a profile is provider- **and** scope-specific, and Takt replaces a same-named profile wholesale across scopes rather than merging it field by field, so there is no key rulesync could own there without clobbering the user's provider and model. Author those options yourself under `provider.profiles.<profile>.options` in `runtime.yaml` — a **flat bag applying to that profile's own provider**, so the `codex:` / `claude:` segment of `provider_options` is dropped — and remove `provider_options` from the `takt` block of `.rulesync/permissions.*`. Anything already written into `config.yaml` by hand is left untouched; rulesync does not own that key. On **import**, both sides are read: the legacy `provider_options` table and, in runtime mode, each profile's `options` from the `runtime.yaml` of the scope being imported (import stays inside the tree it was pointed at), re-keyed by the profile's own `provider` (the runtime side wins on a collision), so nothing is lost. One consequence worth knowing: importing a runtime-mode install produces a `takt.provider_options` block that a later generate will refuse and warn about — drop it from the rulesync source once the options are settled in `runtime.yaml`. Installs with no `runtime.yaml`, or an inactive one, keep the pre-0.56.0 behavior unchanged: `provider_options` is written to `config.yaml` exactly as before.\n\nSee the [Takt configuration docs](https://github.com/nrslib/takt/blob/main/docs/configuration.md).\n\nFor Amp, this writes to the shared `.amp/settings.json` (project mode) or `~/.config/amp/settings.json` (global mode), using **two** permission surfaces. In rulesync's canonical model the category name **is** the Amp tool name. A **whole-tool deny** (pattern `*`) is written to the bare `amp.tools.disable` array (the tool name is pushed verbatim, preserving `builtin:` prefixes and the `*` glob) for backwards compatibility. Every **lossy** case is written to the ordered `amp.permissions` array instead of being dropped: an **argument-specific deny** (pattern `!== \"*\"`) becomes `{ tool, action: \"reject\", matches: { cmd: <pattern> } }`, and every `allow` / `ask` rule becomes `{ tool, action, matches?: { cmd } }` (the `matches` object is omitted for the `*` catch-all). Amp evaluates `amp.permissions` **first-match-wins**, so generated entries are ordered deterministically and fail-closed: sorted by tool name, then entries **with** `matches.cmd` (more specific) before catch-alls, then by action priority **`reject` < `ask` < `allow`**, then by `cmd`. `amp.permissions` is Amp's documented **legacy / backwards-compatibility** surface — it remains functional and is the only place to express `allow`/`ask` and argument-specific `reject` rules. **Ownership:** rulesync OWNS and wholesale-replaces the `allow`/`ask`/`reject` entries on every generate, but **preserves any existing `action: \"delegate\"` entry** (rulesync's canonical model has no `delegate` equivalent); preserved `delegate` entries are placed **after** the rulesync-generated entries (so the regenerated rules take precedence under first-match-wins). On **import**, both keys are read and merged into one canonical config: `amp.tools.disable[tool]` → `{ tool: { \"*\": \"deny\" } }`, and each `amp.permissions` entry → `{ tool: { (matches?.cmd ?? \"*\"): mapped } }` (`reject` → `deny`, `allow` → `allow`, `ask` → `ask`; `delegate` is skipped). When both sources target the same tool+pattern, the **most restrictive action wins** (`deny` > `ask` > `allow`). The settings file is shared with the MCP feature (`amp.mcpServers`), so all other keys are preserved on round-trip and the file is never deleted. Tool names and `cmd` patterns that are prototype-pollution keys (`__proto__`, `constructor`, `prototype`) are skipped defensively.\n\nAmp shapes with no canonical category are authored (and round-trip) through an optional `amp` override block in `.rulesync/permissions.jsonc`: `permissions` — extra `amp.permissions` entries with non-`cmd` matchers (`path`/`url`/`query`/…), regex/array match values, `context` (`thread`/`subagent`), `delegate` (+`to`), or `reject` (+`message`), appended **after** the canonical-generated entries (so generated allow/ask/reject rules take precedence under first-match-wins, with authored entries as later fallbacks); `mcpPermissions` — Amp's `amp.mcpPermissions` array; `guardedFiles` — `amp.guardedFiles.allowlist` (globs allowed without confirmation); and `dangerouslyAllowAll` — `amp.dangerouslyAllowAll`. When the override authors `permissions` it becomes the source of truth for the extra entries; otherwise any hand-authored `delegate` entry in the existing file is preserved. On import, `amp.permissions` entries that are **not** canonical-expressible (non-`cmd` matcher, `delegate`, `reject`+`message`, `context`) are lifted verbatim into `amp.permissions` of the override rather than dropped. Example: `{ \"permission\": { … }, \"amp\": { \"dangerouslyAllowAll\": false, \"guardedFiles\": { \"allowlist\": [\"docs/**\"] }, \"permissions\": [{ \"tool\": \"Bash\", \"action\": \"delegate\", \"to\": \"approve.sh\" }] } }`. See the [Amp manual](https://ampcode.com/manual).\n\nFor JetBrains Junie CLI, this generates the Action Allowlist `rules` object in `~/.junie/allowlist.json` (**global mode only** — Junie CLI resolves exactly one allowlist path under its home directory and never reads a project-scope `.junie/allowlist.json`; verified against release `2383.10`). Junie evaluates the allowlist top-to-bottom (first match wins) and groups rules into buckets, onto which rulesync categories map: `bash` → `executables`, `edit`/`write` → `fileEditing`, `read` → `readOutsideProject`, `mcp` → `mcpTools`. Every rule group is written as Junie's `AllowListRuleSet` **object** — `{ \"default\"?: \"allow\"|\"ask\", \"rules\": [ … ] }` — never a bare array: Junie's parser rejects the array form for the **whole file** and then discards and overwrites `allowlist.json`, so the shape matters. Earlier rulesync versions emitted the array form; it is still tolerated on import, but only the object form is generated. Each rule carries an `action` plus either a literal `prefix` (matches commands that start with it) or a glob `pattern` (`*`, `**`, `?`, `[abc]`, `[!abc]`); rulesync emits `pattern` when the canonical pattern contains a glob metacharacter (`*`, `?`, `[`) and `prefix` otherwise. Junie accepts only `allow` and `ask` as actions — there is **no `deny`** (a `deny` fails the whole-file parse) — so a canonical `deny` is downgraded to the nearest valid action, `ask` (which still withholds auto-approval), with a warning (`allow`/`ask` map 1:1). Categories Junie cannot represent (e.g. `webfetch`, `websearch`) are skipped with a warning when they carry rules. rulesync **owns each mapped group's rule list** (replaced on each generate), while a per-group `default` and the whole `readSecretFile` group — which restricts what Junie may read — are preserved from the existing file when not authored via the `junie` override below. Because `edit`/`write` both collapse onto `fileEditing`, importing normalizes back to `edit` (a documented, lossy mapping). The `allowlist.json` file is never deleted. See the [Junie Action Allowlist docs](https://junie.jetbrains.com/docs/action-allowlist-junie-cli.html).\n\n> **Junie-only override (`junie` key):** Junie's `allowlist.json` has settings with no canonical per-glob slot — the top-level autonomy knobs `allowReadonlyCommands` (a boolean auto-allowing read-only commands) and `defaultBehavior` (the fallback action when no rule matches; an `allow`/`ask` enum — Junie's `AllowListDecision` accepts nothing else, and an invalid value fails the whole-file parse), plus two group-shaped settings: `readSecretFile` (the fifth rule group, restricting reads of secret files — canonical `read` is already taken by `readOutsideProject`, so this group is authored whole as `{ \"default\"?, \"rules\": [ … ] }`) and `ruleDefaults` (each mapped group's own fallback action, e.g. `{ \"executables\": \"ask\" }`). Add a tool-scoped `junie` override to author them: the scalar knobs are merged onto the top level of `allowlist.json` (the override wins) while the shared `permission` block keeps driving the mapped groups' rule lists, and the group-shaped settings land inside the `rules` object. On **import**, all of these are lifted from `allowlist.json` into the `junie` override, so they are authorable and portable instead of only round-trip-preserved. Any other unmodeled top-level key is preserved verbatim. Example:\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git \": \"allow\" } },\n>   \"junie\": {\n>     \"allowReadonlyCommands\": true,\n>     \"defaultBehavior\": \"ask\",\n>     \"ruleDefaults\": { \"executables\": \"ask\" },\n>     \"readSecretFile\": { \"rules\": [{ \"pattern\": \"**/.env\", \"action\": \"ask\" }] }\n>   }\n> }\n> ```\n\nFor Reasonix, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the `[permissions]` table of the shared `reasonix.toml` (project mode) or `~/.reasonix/config.toml` (global mode) — the same TOML file the MCP feature's `[[plugins]]` array-of-tables lives in. The rule syntax mirrors Claude Code's: entries are `Bash(<pattern>)`, `Read(<pattern>)`, `Edit(<pattern>)`, `Write(<pattern>)`, `WebFetch(<pattern>)`, `WebSearch(<pattern>)`, `Grep(<pattern>)`, `Glob(<pattern>)`, `NotebookEdit(<pattern>)`, `Agent(<pattern>)`, etc. (Reasonix's SPEC.md documents these as \"Claude Code-style\" families; `agent` → `Agent` is the one lower-confidence mapping, since Reasonix's own delegation tool is internally named `task`). `[permissions].mode` (the writer fallback: `ask`/`allow`/`deny`) has no canonical rulesync equivalent and is preserved untouched. The TOML file is shared with the MCP feature, so writes only replace the `permissions` table — every other table (`[[plugins]]`, `[agent]`, `[ui]`, …) is preserved on round-trip, and the file is never deleted. See [SPEC.md §3.7 Permissions](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md).\n\n> **Reasonix-only override (`reasonix` key):** Reasonix has security axes orthogonal to per-tool allow/ask/deny with no canonical category — the `[sandbox]` enforcement table (`workspace_root`, `allow_write`, `forbid_read`, `bash` = `enforce`/`off`, `network`) and the plan-mode read-only command list under `[agent]` (`plan_mode_read_only_commands`, which upstream keeps for legacy compatibility only — Plan bash goes through Permissions now). Its sibling `plan_mode_allowed_tools` left the documented config surface in v1.17.18: an existing value is still lifted out of `[agent]` on import, so it does not vanish from an imported config, but whenever the override writes `[agent]` the key is removed from the file with a warning — including a value already there, since leaving that one alone would mean narrowing the list is the one edit that never lands. Add a tool-scoped `reasonix` override to author them: `reasonix.sandbox` and `reasonix.agent` are shallow-merged into the matching `reasonix.toml` table at its top level (override keys win, unrelated sibling keys such as `[agent].model` are preserved), while the shared `permission` block keeps driving `[permissions].allow`/`ask`/`deny`. The override also carries `rawAllow`/`rawAsk`/`rawDeny` — verbatim `[permissions]` entries merged into the generated arrays untranslated. They exist for the first-class `Bash=<literal>` exact-command form (SPEC §3.7, v1.18.0: metacharacters in the literal are ordinary characters and only the identical complete command matches), which the canonical tool→pattern→action shape cannot express. It is also the pattern-level way to pre-authorize **nested or indirect** Bash — command and process substitution, `eval`, `source`, `sh -c` and the like, which Reasonix gates harder than a merely dynamic command line — in a headless `reasonix run`; upstream additionally offers the blanket `[permissions] allow_dynamic_bash` opt-in (added in v1.19.0, which lets an Allow fallback cover that whole class) and YOLO, but authoring either through rulesync is not supported today. Exact entries already in `reasonix.toml` — Reasonix writes them itself as remembered approvals — are always preserved on generate, even for tools the shared block manages. On import, the whole `[sandbox]` table round-trips (it is a dedicated security surface), only the plan-mode keys are lifted from `[agent]`, and exact `Tool=<literal>` entries are lifted into `rawAllow`/`rawAsk`/`rawDeny` instead of masquerading as a bogus tool category in the shared block.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git status*\": \"allow\" } },\n>   \"reasonix\": {\n>     \"sandbox\": { \"bash\": \"enforce\", \"network\": false },\n>     \"agent\": { \"plan_mode_read_only_commands\": [\"gh pr diff\"] }\n>   }\n> }\n> ```\n>\n> The retired `[[plugins]].trusted_read_only_tools` MCP read-only trust list is per-plugin (an array-of-tables shared with the MCP feature) and is not covered by this override.\n\n> **Note: Interaction with deprecated ignore feature.** Both the ignore feature and the permissions feature can manage `Read` tool deny entries in `.claude/settings.json`. When both features configure the `Read` tool, the **permissions feature takes precedence** and a warning is emitted. Migrate the ignore patterns to `read` deny rules in `.rulesync/permissions.jsonc`, then remove `ignore` from the project features and delete the obsolete ignore source.\n",
-	"reference/mcp-server": "# Rulesync MCP Server\n\nRulesync provides an MCP (Model Context Protocol) server that enables AI agents to manage your Rulesync files. This allows AI agents to discover, read, create, update, and delete files dynamically.\n\n> [!NOTE]\n> The MCP server exposes the only one tool to minimize your agent's token usage. Approximately less than 1k tokens for the tool definition.\n\n## Supported Features and Operations\n\nThe single `rulesyncTool` multiplexes by `feature` and `operation`:\n\n- `rule`, `command`, `subagent`, `skill`: `list`, `get`, `put`, `delete`\n- `ignore`, `mcp`, `permissions`, `hooks`: `get`, `put`, `delete`\n- `generate`: `run`\n- `import`: `run`\n- `convert`: `run`\n\nThe `permissions` feature operates on `.rulesync/permissions.jsonc` and the `hooks` feature operates on `.rulesync/hooks.jsonc`. Both accept a `content` string (valid JSONC) on `put`.\n\n### `skill` other files\n\nA skill directory may contain files other than `SKILL.md`. They are passed as `otherFiles`, where each entry has:\n\n| Field      | Type                  | Required | Description                                                                    |\n| ---------- | --------------------- | -------- | ------------------------------------------------------------------------------ |\n| `name`     | `string`              | Yes      | Path of the file relative to the skill directory (e.g. `references/logo.png`). |\n| `body`     | `string`              | Yes      | File content, encoded according to `encoding`.                                 |\n| `encoding` | `\"utf-8\" \\| \"base64\"` | No       | Defaults to `\"utf-8\"`. Use `\"base64\"` for binary files such as images.         |\n\nOn `get`, every returned entry carries an explicit `encoding`: `\"utf-8\"` when the file content survives a UTF-8 round trip unchanged, and `\"base64\"` otherwise. On `put`, the declared `encoding` is trusted and the decoded bytes are written verbatim, so binary files round-trip byte for byte.\n\nWhen feeding entries returned by `get` back into `put`, keep their `encoding` field. Dropping it makes a `\"base64\"` body be stored as literal text and corrupts the file.\n\nA `\"base64\"` body must be canonical base64 (the standard or the URL-safe alphabet, padding optional); otherwise `put` fails with `Invalid base64 body for other file <name>`. The 1MB skill size limit is evaluated against the decoded byte length of each other file.\n\n### `convert` / `run` options\n\nWhen invoking `feature: \"convert\"` with `operation: \"run\"`, pass `convertOptions` with the following shape:\n\n| Option     | Type       | Required | Description                                                                        |\n| ---------- | ---------- | -------- | ---------------------------------------------------------------------------------- |\n| `from`     | `string`   | Yes      | Source tool name (e.g. `\"claudecode\"`). Must be a valid `ToolTarget`.              |\n| `to`       | `string[]` | Yes      | One or more destination tool names. Must not be empty and must not include `from`. |\n| `features` | `string[]` | No       | Features to convert (e.g. `[\"rules\", \"commands\"]`). Defaults to `[\"*\"]`.           |\n| `global`   | `boolean`  | No       | Convert global (user-scope) configurations. Defaults to `false`.                   |\n| `dryRun`   | `boolean`  | No       | Preview changes without writing files. Defaults to `false`.                        |\n\n## Usage\n\n### Starting the MCP Server\n\n```bash\nrulesync mcp\n```\n\nThis starts an MCP server using stdio transport that AI agents can communicate with.\n\n### Configuration\n\nAdd the Rulesync MCP server to your `.rulesync/mcp.jsonc`:\n\n```json\n{\n  \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json\",\n  \"mcpServers\": {\n    \"rulesync-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"rulesync\", \"mcp\"],\n      \"env\": {}\n    }\n  }\n}\n```\n",
-	"reference/supported-tools": "# Supported Tools and Features\n\nRulesync supports both **generation** and **import** for All of the major AI coding tools:\n\n<!-- SUPPORTED_TOOLS_DOCS:BEGIN -->\n\n| Tool                      | --targets          | rules | ignore |   mcp    | commands | subagents | skills | hooks | permissions | checks |\n| ------------------------- | ------------------ | :---: | :----: | :------: | :------: | :-------: | :----: | :---: | :---------: | :----: |\n| AGENTS.md                 | agentsmd           |  ✅   |        |          |    🎮    |    🎮     |   🎮   |       |             |        |\n| AgentsSkills              | agentsskills       |       |        |          |          |           | ✅ 🌏  |       |             |        |\n| Amp                       | amp                | ✅ 🌏 |        |  ✅ 🌏   |          |           | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    | ✅ 🌏  |\n| Claude Code               | claudecode         | ✅ 🌏 |   ✅   |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Claude Code plugin        | claudecode-plugin  |       |        |    ✅    |    ✅    |    ✅     |   ✅   |  ✅   |             |        |\n| Codex CLI                 | codexcli           | ✅ 🌏 |        | ✅ 🌏 🔧 |    🌏    |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| GitHub Copilot            | copilot            | ✅ 🌏 |        |    ✅    |    ✅    |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     ✅      |        |\n| GitHub Copilot CLI        | copilotcli         | ✅ 🌏 |        | ✅ 🌏 🔧 |          |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Goose                     | goose              | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   |   ✅   | ✅ 🌏 |     🌏      |        |\n| Hermes Agent              | hermesagent        |  ✅   |   ✅   |  🌏 🔧   |    🌏    |   ✅ 🌏   |   🌏   |  🌏   |     🌏      |   ✅   |\n| Grok CLI                  | grokcli            | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Cursor                    | cursor             |  ✅   |   ✅   |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |   ✅   |\n| deepagents-cli            | deepagents         | ✅ 🌏 |        | ✅ 🌏 🔧 |          |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     🌏      |        |\n| Factory Droid             | factorydroid       | ✅ 🌏 |        | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |   ✅   |\n| OpenCode                  | opencode           | ✅ 🌏 |        | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Cline                     | cline              | ✅ 🌏 |   ✅   |    🌏    |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     ✅      |        |\n| Kilo Code                 | kilo               | ✅ 🌏 |   ✅   | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Kimi Code                 | kimi-code          | ✅ 🌏 |        | ✅ 🌏 🔧 |          |   ✅ 🌏   | ✅ 🌏  |  🌏   |     🌏      |        |\n| Roo Code ⚠️               | roo                | ✅ 🌏 |   ✅   |  ✅ 🔧   |  ✅ 🌏   |    ✅     | ✅ 🌏  |       |     ✅      |        |\n| Zoo Code                  | zoocode            | ✅ 🌏 |   ✅   |  ✅ 🔧   |  ✅ 🌏   |    ✅     | ✅ 🌏  |       |     ✅      |        |\n| Rovodev (Atlassian)       | rovodev            | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |       |    ✅ 🌏    |   ✅   |\n| Takt                      | takt               | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |       |    ✅ 🌏    | ✅ 🌏  |\n| Vibe Code                 | vibe               | ✅ 🌏 |   ✅   | ✅ 🌏 🔧 |          |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Qwen Code                 | qwencode           | ✅ 🌏 |   ✅   | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Meta Muse Code            | musecode           |  ✅   |        |    🌏    |          |           | ✅ 🌏  |       |             |        |\n| Reasonix                  | reasonix           | ✅ 🌏 | ✅ 🌏  |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Kiro ⚠️                   | kiro               | ✅ 🌏 | ✅ 🌏  | ✅ 🌏 🔧 |    ✅    |    ✅     |   ✅   |  ✅   |     ✅      |        |\n| Kiro CLI                  | kiro-cli           | ✅ 🌏 | ✅ 🌏  | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     ✅      |        |\n| Kiro IDE                  | kiro-ide           | ✅ 🌏 | ✅ 🌏  | ✅ 🌏 🔧 |    ✅    |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     ✅      |        |\n| Google Antigravity IDE    | antigravity-ide    | ✅ 🌏 |        | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     ✅      |        |\n| Google Antigravity CLI    | antigravity-cli    | ✅ 🌏 |   ✅   | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     🌏      |        |\n| Google Antigravity plugin | antigravity-plugin |  ✅   |        |  ✅ 🔧   |          |    ✅     |   ✅   |  ✅   |             |        |\n| JetBrains AI Assistant    | aiassistant        |  ✅   |   ✅   |  ✅ 🌏   |          |           |   ✅   |       |             |        |\n| JetBrains Junie           | junie              | ✅ 🌏 |   ✅   |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |  🌏   |     🌏      |        |\n| AugmentCode               | augmentcode        | ✅ 🌏 |   ✅   |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |   ✅   |\n| Devin Desktop             | devin              | ✅ 🌏 | ✅ 🌏  | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Warp                      | warp               | ✅ 🌏 |   ✅   |  ✅ 🌏   |  ✅ 🌏   |           | ✅ 🌏  |       |     🌏      |        |\n| Replit                    | replit             |  ✅   |        |          |          |           | ✅ 🌏  |       |             |        |\n| Pi Coding Agent           | pi                 | ✅ 🌏 |        |          |  ✅ 🌏   |           | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Zed                       | zed                | ✅ 🌏 | ✅ 🌏  |  ✅ 🌏   |          |           | ✅ 🌏  |       |    ✅ 🌏    |        |\n| ZCode (Z.ai)              | zcode              | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |           | ✅ 🌏  |       |             |        |\n\n<!-- SUPPORTED_TOOLS_DOCS:END -->\n\n- ✅: Supports project mode\n- 🌏: Supports global mode\n- 🎮: Supports simulated commands/subagents/skills (Project mode only)\n- 🔧: Supports MCP tool config (`enabledTools`/`disabledTools`)\n- ⚠️: Deprecated — still supported, but see the note below\n\n## Hermes Agent compatibility\n\nThe `hermesagent` target is validated against Hermes Agent v0.20.2 (release\n`v2026.8.16`). The supported contract covers project rules, ignore patterns,\nsubagents, and checks, plus global MCP servers, commands, subagents, skills,\nhooks, and permissions. Generation, `--check`, and import round-trips are\ncovered for both advertised scopes.\n\nRulesync honors Hermes profiles through `HERMES_HOME`. When it is set, its value\nis the profile root itself: global configuration is read and written directly\nunder `$HERMES_HOME` (`config.yaml`, `skills/`, `plugins/`, and `rulesync/`),\nwithout appending `.hermes`. When it is unset, Rulesync follows Hermes's own\nplatform default: `~/.hermes` everywhere except Windows, where it is\n`%LOCALAPPDATA%\\hermes`. Because `HERMES_HOME` names where Hermes itself reads\nthe profile, it also takes precedence over `--output-roots` in global scope.\nProject-scoped paths remain rooted in the project.\n\nChanging which profile root Rulesync resolves strands whatever it generated\nunder the previous one. `--delete` reconciles only the root resolved for the\ncurrent run, so files under a root it no longer resolves are invisible to it and\nmust be removed by hand once you are sure Hermes no longer reads them. This\napplies whenever you set or change `HERMES_HOME`, and to two upgrades that moved\nthe resolved root on their own: before v16.0.0 global files went to `~/.hermes`\neven when `HERMES_HOME` was set, and before v16.2.0 they went there on Windows\ntoo, rather than to `%LOCALAPPDATA%\\hermes`.\n\nProject plugins are registered by adding their names to\n`$HERMES_HOME/config.yaml`, but Rulesync does not persist Hermes's global\nproject-plugin trust gate. Run Hermes from a trusted project root with\n`HERMES_ENABLE_PROJECT_PLUGINS=true` for an explicit, session-scoped opt-in. A\nfuture Hermes release that changes its loaders, schemas, or plugin API requires\na new compatibility validation.\n\n## Deprecation notes\n\n- **Google Antigravity (`antigravity-ide` / `antigravity-cli`)** — Antigravity 2.0 splits into two products: the desktop **`antigravity-ide`** and the **`antigravity-cli`** (`agy`). As of Antigravity 2.0 the IDE reads its global MCP config and skills from the shared `~/.gemini/config/` tree — `~/.gemini/config/mcp_config.json` and `~/.gemini/config/skills/`, matching the current [MCP](https://antigravity.google/docs/mcp) and [Skills](https://antigravity.google/docs/skills) docs. The `antigravity-cli` global MCP config also lives in the shared `~/.gemini/config/mcp_config.json`, while the CLI keeps its own global skills tree at `~/.gemini/antigravity-cli/skills/`. Both targets also intentionally **share** the global rule file `~/.gemini/GEMINI.md` and the global hooks file `~/.gemini/config/hooks.json` — enabling both targets in `--global` mode writes those shared files once. For project-scope rules, **both `antigravity-ide` and `antigravity-cli`** emit the root rule as a plain cross-tool **`AGENTS.md`** at the project root (the Gemini-lineage discovery order is `AGENTS.md`, `CONTEXT.md`, `GEMINI.md`; the IDE has read `AGENTS.md` since v1.20.3) and non-root rules under `.agents/rules/` (the IDE adds trigger frontmatter to non-root rules; the CLI keeps them as plain markdown). For **commands (workflows)**, both targets share the project `.agents/workflows/` directory (invoked as `/workflow-name`); in `--global` mode the IDE writes to `~/.gemini/antigravity/global_workflows/` while the CLI keeps its own `~/.gemini/antigravity-cli/global_workflows/` tree (mirroring the CLI's global skills tree).\n- **Kiro (`kiro`)** — Kiro ships as two products with diverging config formats: the **Kiro IDE** reads Markdown subagents (`.kiro/agents/*.md`) and structured JSON hooks (`.kiro/hooks/*.json`, format `{ \"version\": \"v1\", \"hooks\": [ ... ] }`), while the **Kiro CLI** reads JSON agent-config subagents (`.kiro/agents/*.json`). A single target cannot emit both subagent shapes faithfully, so `kiro` is split into **`kiro-cli`** and **`kiro-ide`**. The legacy `kiro` target is kept as a **deprecated alias** (its current mixed output is unchanged for backward compatibility). Shared surfaces (steering rules with `inclusion`, `.kiro/settings/mcp.json`, `.kiro/prompts/` commands, `.kiro/skills/`, `.kiroignore`, permissions) are identical between the two; they differ only in **subagents** (`.md` vs `.json`). **Hooks** are the same for both: a single `.kiro/hooks/rulesync.json` (whose `hooks` array holds every generated hook) in both project (`.kiro/hooks/`) and global (`~/.kiro/hooks/`) scope, mapping canonical lifecycle events to Kiro's PascalCase triggers (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) and supporting both `agent` (prompt) and `command` actions. Kiro CLI 3.0 [migrated to that format](https://kiro.dev/docs/cli/v3/hooks-migration/) and no longer reads the embedded agent hooks in `.kiro/agents/default.json`, which only the deprecated `kiro` alias still writes (including `cacheTtl` ⇄ `cache_ttl_seconds`). Global **skills** (`~/.kiro/skills/`), global **ignore** (`~/.kiro/settings/kiroignore`), and global Kiro IDE **subagents** (`~/.kiro/agents/`) are also supported, as are global Kiro CLI **commands** (`~/.kiro/prompts/`) and **subagents** (`~/.kiro/agents/`). Kiro's shared MCP file preserves per-server `disabledTools`.\n- **Roo Code (`roo`)** — Roo Code is end of life: its final release was **v3.54.0 (2026-05-15)** and the [Roo-Code repository](https://github.com/RooCodeInc/Roo-Code) is archived, so nothing about the target will move again. New projects should target **`zoocode`** instead — [Zoo Code](https://github.com/Zoo-Code-Org/Zoo-Code) is the community continuation named by the Roo shutdown notice, and it continues Roo's release numbering. The `roo` target stays supported because Zoo Code still reads the `.roo/` project tree and `~/.roo` global tree verbatim, so existing `roo` output keeps working; what it no longer tracks is anything Zoo Code added after the fork. The two targets write the same files, so enable one per project rather than both — see the Zoo Code note in [File formats](./file-formats.md) for the fail-open hazard a `--targets roo` generate creates in a shared `.roomodes`. **Permissions are the one exception**: the two lineages spell the command allow/deny lists differently (`roo-cline.*` vs `zoo-code.*`), so both pairs coexist in one `.vscode/settings.json` and neither target touches the other's — see the Roo Code paragraph in [File formats](./file-formats.md).\n",
+	"reference/file-formats": "# File Formats\n\n## Symlinks\n\nRulesync follows symbolic links when it discovers source files, whether you use a plain `.rulesync/` directory or separate `--input-roots`. Glob-based discovery (rules, commands, subagents, skills) follows symlinked files and directories; single fixed-path files such as `.rulesyncignore`, `.rulesync/mcp.jsonc`, and `.rulesync/permissions.jsonc` are likewise resolved transparently by the OS when read. A symlink inside the input tree that points elsewhere is followed transparently, and the resolved file content is copied into the generated output. This is intentional: it lets you centralize shared skills or rules in one place and reference them via symlinks without duplication (see [issue #1707](https://github.com/dyoshikawa/rulesync/issues/1707)).\n\nThe trust boundary is the directory you point Rulesync at. There is **no** `realpath`-based containment check on individual symlinks, so a link may resolve to a target outside the input root — enforcing containment would break the shared-file use case above. Only run Rulesync against trees you control. Directory symlink **cycles** are handled safely: glob-based results are deduplicated by the real file they resolve to, so a cycle does not produce duplicated output, and two names for one file (a `docs/reference.md` link pointing at a top-level `reference.md`, say) yield a single entry. Skill directories are not discovered by globs at all — they are walked directly, and that walk keeps every entry it reaches, so a supporting file remains available under each name the skill gives it. Note that the remote-fetch path (`rulesync fetch` from a Git repository) is a separate, hardened code path that never **follows** a symlink. A symlink in the remote repository is skipped rather than downloaded, so untrusted remote content never has its links resolved. Locally, the stale-file prune described in [CLI Commands](./cli-commands.md#pruning-fetched-skill-directories) removes a stale link itself without reading through it, and refuses to prune a skill directory that is a symlink at all, so a shared skill you linked in stays untouched.\n\nThree exceptions narrow this within skill directories. First, the entries a skill directory never carries (listed in the supporting-file note below) are excluded by the name they really resolve to, not just the name they have inside the skill — a link called `vendor` pointing at `~/.aws` is refused exactly as a directory called `.aws` is. Second, a link whose real path lands in a system pseudo-filesystem (`/proc`, `/sys`, `/dev`) is refused: `/proc/self/environ` looks like an ordinary file but reads back the environment of the running process. Third, a skill directory's companion files include hidden (dot-prefixed) entries, so an ordinary-looking link to a home directory would otherwise pull in every dotfile beneath it: a hidden entry whose real path resolves outside the skill directory is **not** carried, and the skipped paths are named in a warning. Copy such a file into the directory if the skill really needs it.\n\nWhat decides that third rule is the name inside the skill directory, not the path the link resolves through: a named file keeps the behavior above even when its target sits under a dot-directory such as `~/.dotfiles/skills/`, because somebody chose that name. Reaching outside the directory is reported either way — carried or not — since the content is about to be copied into every enabled tool root.\n\nOne discovery pass is deliberately excluded from the follow-symlinks rule: the scan for nested `AGENTS.md` files (see the `agentsmd` note below). Unlike every other glob above, it walks the whole project rather than a rulesync-owned directory, so a symlink committed to a repository you cloned could otherwise pull a file from outside the project into version-controlled `.rulesync/`. That scan does not follow symlinks.\n\n## `rulesync/rules/*.md`\n\nExample:\n\n```md\n---\nroot: true # true for root-level rules, false for details such as `.agents/memories/*.md`\nlocalRoot: false # (optional, default: false) true for project-specific local rules. Claude Code: CLAUDE.local.md; Rovodev (Rovo Dev CLI), Roo Code, Zoo Code and Devin: AGENTS.local.md; Qwen Code: .qwen/QWEN.local.md; Others: append to root file. See the localRoot note below for import behavior\ntargets: [\"*\"] # * = all, or specific tools\ndescription: \"Rulesync project overview and development guidelines for unified AI rules management CLI tool\"\nglobs: [\"**/*\"] # file patterns to match (e.g., [\"*.md\", \"*.txt\"])\nagentsmd: # agentsmd and codexcli specific parameters\n  # Support for using nested AGENTS.md files for subprojects in a large monorepo.\n  # This option is available only if root is false.\n  # If subprojectPath is provided, the file is located in `${subprojectPath}/AGENTS.md`.\n  # If subprojectPath is not provided and root is false, the file is located in `.agents/memories/*.md`.\n  subprojectPath: \"path/to/subproject\"\ncursor: # cursor specific parameters\n  alwaysApply: true\n  description: \"Rulesync project overview and development guidelines for unified AI rules management CLI tool\"\n  globs: [\"*\"]\ncopilot: # copilot specific parameters (non-root `*.instructions.md` files only)\n  name: \"TypeScript Style\" # (optional) display name shown in the VS Code UI; defaults to the file name\n  excludeAgent: \"code-review\" # (optional) \"code-review\" or \"cloud-agent\": skip this file for that agent\n  # Any other frontmatter key found in a hand-written `*.instructions.md` is imported into this\n  # section and written back out, so a field Rulesync does not model is not lost on regeneration.\n  # `description` and `applyTo` are the exception: they have canonical homes (`description` and\n  # `globs`), so a value written for them in this section is overwritten by the canonical one.\nantigravity: # antigravity specific parameters\n  trigger: \"always_on\" # always_on, glob, manual, or model_decision\n  globs: [\"**/*\"] # (optional) file patterns to match when trigger is \"glob\"\n  description: \"When to apply this rule\" # (optional) used with \"model_decision\" trigger\ndevin: # devin (Devin Desktop, formerly Windsurf) specific parameters\n  trigger: \"always_on\" # always_on, glob, manual, or model_decision\n  globs: [\"**/*\"] # (optional) file patterns to match when trigger is \"glob\"\n  description: \"When to apply this rule\" # (optional) used with \"model_decision\" trigger\naugmentcode: # augmentcode specific parameters\n  type: \"always_apply\" # always_apply, manual, or agent_requested\n  description: \"When to apply this rule\" # (optional) used with \"agent_requested\" type\nkiro: # kiro specific parameters (steering inclusion)\n  inclusion: \"fileMatch\" # always, fileMatch, manual, or auto\n  fileMatchPattern: [\"src/components/**/*.tsx\"] # (optional) glob string or array of globs, used when inclusion is \"fileMatch\"\n  name: \"api-design\" # (optional) required when inclusion is \"auto\"; the steering entry key\n  description: \"REST API design patterns. Use when creating or modifying API endpoints.\" # (optional) required when inclusion is \"auto\"; Kiro auto-includes the file when a request matches this\ntakt: # takt specific parameters (optional; emitted under .takt/facets/policies/ — frontmatter is dropped on emit)\n  name: \"renamed-stem\" # (optional) override the emitted filename stem (no path separators or \"..\")\n  extends: \"base\" # (optional) emit a leading `{extends:<parent>}` facet-inheritance directive (Takt 0.39.0+)\n  facet: \"output-contracts\" # (optional) \"policies\" (default) or \"output-contracts\": redirect this rule to Takt's output-structure/report-template facet\n---\n\n# Rulesync Project Overview\n\nThis is Rulesync, a Node.js CLI tool that automatically generates configuration files for various AI development tools from unified AI rule files. The project enables teams to maintain consistent AI coding assistant rules across multiple tools.\n\n...\n```\n\nMultiple files can set `root: true` for the same target in project and global modes. Rulesync renders each file through the target adapter, then combines compatible root or plain-Markdown single-file outputs in deterministic source-discovery order with one blank line between fragments. Local rules are ordered lexicographically by source file path and composed before non-overridden `.curated/` rules, which are also ordered lexicographically; filename prefixes such as `10-` and `20-` control composition order within each set. Targets that map source rules to distinct native paths keep those files separate. Explicitly supported plain-Markdown modular rules that normalize to the same output path are combined; a fragment whose generated output carries its own frontmatter block (such as Amp's `globs:` gate) is never composed and stays a separate file instead. Unsafe collisions involving a source `root: true` rule fail. Other exact or case-insensitive modular collisions remain separate and produce a warning that the last write wins wherever the filesystem treats their paths as the same.\n\n> **localRoot import note:** For the tools that emit a separate personal local file (Claude Code and its legacy layout: `CLAUDE.local.md`; Rovodev, Roo Code, Zoo Code and Devin: `AGENTS.local.md`; Qwen Code: `.qwen/QWEN.local.md`), `rulesync import` also reads that file back as a `localRoot: true` rule under `.rulesync/rules/`, keeping the tool-side basename. The imported rule's `targets` is scoped to the tool it was imported from, not `\"*\"` — a wildcard would spread the personal content into other tools' committed root files on the next generate (tools without a separate local file append `localRoot` bodies to their root file), and importing from several tools would otherwise produce conflicting wildcard `localRoot` rules. Widen `targets` by hand if you do want the content shared. The same scoping applies to `rulesync convert`: converting to a different tool drops the source tool's personal local file rather than folding it into the destination's root file. The derived `.gitignore` covers the imported copy via `.rulesync/rules/*.local.md`; run `rulesync gitignore` after a first import if the project's `.gitignore` has not been generated yet, so the personal content stays untracked. Project scope only, like `localRoot` generation itself.\n\n> **AGENTS.md standard note (`agentsmd`):** Nested `AGENTS.md` files are the standard's only scoping mechanism — agents read the nearest file in the directory tree, so the closest one wins. Rulesync writes them from `agentsmd.subprojectPath` and, on **import**, discovers them by scanning the project for `**/AGENTS.md`. Hidden directories (other tools' generated output, including rulesync's own) are skipped at any depth, as are `node_modules/` and `__pycache__/`. Build, vendoring and scratch directories (`vendor/`, `third_party/`, `dist/`, `build/`, `out/`, `target/`, `coverage/`, `tmp/`, `temp/`, `venv/`) are skipped **at the project root only**, because a top-level `build/` is a build directory while `packages/build/` is a real subproject. Beyond those names, the scan honors your `.gitignore`: a file git does not track is not your project's source, and copying a vendored dependency's rule file into version-controlled `.rulesync/rules/` would hand third-party instructions to every tool — including the ones that concatenate non-root rules into a single always-loaded file. (Ignore rules come from the `.gitignore` files at and below the output root — a parent repository's rules are not consulted, so running against a subdirectory only sees that subdirectory's own. The test is applied to the _directories_ above each file, not the file itself, so the `**/AGENTS.md` entry that `rulesync gitignore` writes for its own output does not disable the scan; the flip side is that ignoring one individual `AGENTS.md` no longer keeps it out of the import.) Symbolic links are not followed, so a link committed to a repository cannot pull a file from outside the project into version-controlled `.rulesync/`. The scan is import-only: a nested file rulesync did not write is never removed by `--delete`. That means deleting the rulesync rule stops the reference from being listed in the root `AGENTS.md`, but leaves the subproject file itself on disk — where agents still read it, since the nearest file wins. Remove it by hand. Each discovered file is imported to `.rulesync/rules/<directory-with-hyphens>.md` (e.g. `packages/api/AGENTS.md` → `packages-api.md`) carrying `agentsmd.subprojectPath`, so the next generate puts it back where it came from. A subproject that would claim the reserved `overview.md` name gets an `-agents` suffix instead, so the root rule is never overwritten; any other pair of sources deriving the same name is reported at import time, since only the last one survives. Import always rewrites `.rulesync/rules/`, so a subproject whose derived name matches a rule file you wrote by hand replaces it — pick distinct names, or keep hand-written rules out of the derived namespace. See <https://agents.md/>.\n\n> **Kiro note:** Kiro reads steering files from `.kiro/steering/*.md` and uses an `inclusion` frontmatter block to decide when each is loaded (`always`, `fileMatch` with a `fileMatchPattern`, `manual`, or `auto` — which auto-includes the file when a request matches its companion `description`, keyed by `name`). Rulesync derives this for non-root steering files: an explicit `kiro.inclusion` block round-trips as-is (carrying `name`/`description` through for `auto`); otherwise specific (non-wildcard) `globs` map to `inclusion: fileMatch` (a single glob is written as a string and multiple as a YAML array, both of which Kiro accepts), so the rule applies only to matching files instead of always; otherwise the file stays always-on and is written without a frontmatter block (Kiro's no-frontmatter default). The root overview index is always written plain so Kiro always loads it. A rule carrying the shared directory-scoping carrier `agentsmd.subprojectPath` is written to `<dir>/AGENTS.md` **instead of** `.kiro/steering/`: Kiro CLI 2.18.0 and IDE 1.0.309 load `AGENTS.md` as steering context from anywhere in the workspace tree, so a directory-scoped rule reaches only the subtree it applies to rather than being flattened into an always-loaded steering file. A nested file is written plain (no `inclusion` block — that frontmatter belongs to `.kiro/steering/*.md`), and imports back as a `kiro`-targeted rule named after its directory (`services/api` → `services-api-kiro.md`). Like every other nested scan, discovery is **import-only**: the matches are hand-authored files outside a rulesync-owned directory, so `generate --delete` never sweeps them. Nesting is project scope only — under `~/.kiro/steering/` there is no workspace tree to scope against, so `subprojectPath` is ignored there. In **global** mode (`--global`), steering is written to `~/.kiro/steering/` with the root rule as `~/.kiro/steering/product.md` (Kiro does not read `~/AGENTS.md`, so the project-scope root `AGENTS.md` is not used at the home level), and global MCP is written to `~/.kiro/settings/mcp.json`.\n\n> **Grok CLI note:** Grok Build writes the root rule to the auto-loaded `AGENTS.md` (project) / `~/.grok/AGENTS.md` (global, via `--global`), and non-root rules to `.grok/rules/*.md` (project) / `~/.grok/rules/*.md` (global). Grok scans that directory flat and in name order, alongside the AGENTS.md family — earlier Rulesync versions folded every topic rule into the single root file, which matched Grok 0.2.54 but not the current release, so regenerate to split them back out. Non-root files carry no frontmatter. Because this is a directory Grok defines rather than one Rulesync invented, a project may already have hand-written files there: Rulesync owns it from now on, so `--delete` removes anything in it — `~/.grok/rules/` included, in global mode — that `.rulesync/rules/` does not produce. Move those files into `.rulesync/rules/` first.\n\n> **Kilo Code note:** Kilo writes the root rule to the auto-loaded `AGENTS.md` and non-root rules to `.kilo/rules/*.md`. Because Kilo v7 does not auto-load files under `.kilo/rules/`, Rulesync also registers each generated non-root rule file in the `instructions` array of the shared `kilo.jsonc` (the root `AGENTS.md` is auto-loaded and is therefore not registered). This merge is non-destructive: existing keys such as `mcp`, `tools`, and `permission` are preserved. Within the `instructions` list rulesync owns the entries under `.kilo/rules/` — that subset is rebuilt from the current generate, so deleting a rule also drops its registration — while entries outside it pass through verbatim; the result is deduped and sorted.\n\n> In global mode (`--global`), Kilo's own layout is asymmetric: the root rule goes to `~/.config/kilo/AGENTS.md`, while non-root rules go to `~/.kilo/rules/*.md` — the same `.kilo`-relative path the skills adapter uses in both scopes. Global rules need no `instructions` registration, because Kilo auto-discovers every `~/.kilo/rules/*.md` on config load; writing the files is enough, and no global `kilo.jsonc` is touched by the rules feature.\n\n> **Kimi Code note:** Kimi Code reads `.kimi-code/AGENTS.md` at project scope and `~/.kimi-code/AGENTS.md` at user scope. When `KIMI_CODE_HOME` is set, Rulesync follows Kimi and resolves every global Kimi-specific file (`AGENTS.md`, `mcp.json`, `config.toml`, `skills/`, and `agents/`) under that custom data root; the shared `~/.agents/skills/` and `~/.agents/agents/` discovery roots remain under the user's real home directory. Because Kimi has no dedicated directory for topic-based instruction files, Rulesync folds every non-root rule body into that single file. See the [Kimi Code agents and instruction-files docs](https://moonshotai.github.io/kimi-code/en/customization/agents.html) and [environment-variable docs](https://moonshotai.github.io/kimi-code/en/configuration/env-vars.html).\n\n> **OpenCode note:** OpenCode writes the root rule to the auto-loaded `AGENTS.md` and non-root rules to `.opencode/memories/*.md`. Because OpenCode auto-loads only the root `AGENTS.md` plus files explicitly listed in the `instructions` array of `opencode.json` (it does not auto-discover a rules directory), Rulesync also registers each generated non-root rule file in the `instructions` array of the shared `opencode.json`/`opencode.jsonc` (the root `AGENTS.md` is auto-loaded and is therefore not registered). The same applies in **global** mode (via `--global`): OpenCode reads `instructions` from the global `~/.config/opencode/opencode.json` too, so global non-root rules are written to `~/.config/opencode/memories/*.md` and registered there (entries relative to the config file's directory, e.g. `memories/style.md`) instead of being dropped. This merge is non-destructive: existing keys such as `mcp`, `tools`, and `permission` are preserved. Within the `instructions` list rulesync owns the entries under its managed rules directory (`.opencode/memories/`, or `memories/` in the global config) — that subset is rebuilt from the current generate, so deleting a rule also drops its registration — while entries outside it pass through verbatim; the result is deduped and sorted.\n\n> **Qwen Code note:** Qwen Code writes the root rule to the auto-loaded `QWEN.md` (project) / `~/.qwen/QWEN.md` (global, via `--global`) as plain Markdown, and non-root rules to its path-based context-rule directory `.qwen/rules/` (project) / `~/.qwen/rules/` (global). Each non-root rule is a Markdown file with optional YAML frontmatter: Rulesync maps `globs` ⇄ Qwen's `paths` (a picomatch glob array) and `description` ⇄ `description`. A rule **with** specific `paths` is _conditional_ — Qwen lazily injects it only when the model touches a matching file — while a rule **without** `paths` (empty or wildcard `**/*`/`*` globs) is a _baseline_ rule loaded at session start and is written as plain Markdown with no frontmatter block. The `.qwen/rules/` directory supersedes the legacy `.qwen/memories/` import surface, so each rule is emitted to exactly one location; the root `QWEN.md` is unchanged. A `localRoot: true` rule is emitted to `.qwen/QWEN.local.md` (project scope only) — Qwen Code v0.16.2's personal project context file, loaded after the shared `QWEN.md` so it can override team instructions; the file is covered by the derived `.gitignore` since Qwen Code does not gitignore it for you. See the [Qwen Code memory/context docs](https://github.com/QwenLM/qwen-code).\n\n> **Cline note:** Cline writes the root rule to the auto-loaded `AGENTS.md` (project) as plain Markdown, and non-root rules to its flat `.clinerules/` directory. Each non-root rule is a Markdown file with optional YAML frontmatter for conditional activation: Rulesync maps `globs` ⇄ Cline's `paths` (a glob array; the rule loads only when a matching file is in context) and `description` ⇄ `description`. A rule with **specific** `globs` emits `paths`; a rule with **universal** globs (`**/*` or `*`) emits `alwaysApply: true` (always load); a rule **without** globs is written as plain Markdown with no frontmatter block (always active). In global mode (via `--global`), the root rule is written to the cross-tool `~/.agents/AGENTS.md` (Cline CLI v3.0.15+) as plain Markdown, and non-root rules go to `~/Documents/Cline/Rules/*.md` — the global modular-rules directory both the VS Code extension and the SDK/CLI read — with the same conditional-frontmatter conversion project rules get. See the [Cline rules docs](https://docs.cline.bot/customization/cline-rules).\n\n> **Warp note (rules):** Warp reads project rules from the root `AGENTS.md` (or the back-compat `WARP.md`) and does not scan a modular rules directory, so non-root rule bodies are folded into the single root `./AGENTS.md`. In global mode (via `--global`), the root rule is written to the cross-tool `~/.agents/AGENTS.md` — Warp's third rule source alongside project and Warp Drive rules, also used from remote hosts in SSH sessions — with the same folding. Other targets (e.g. Cline) own the same global path; as with the shared project-root `AGENTS.md`, each target regenerates the file per its own semantics. See the [Warp rules docs](https://docs.warp.dev/agent-platform/capabilities/rules/) and [file locations](https://docs.warp.dev/terminal/settings/file-locations/).\n\n> **Pi note:** Pi writes the root rule to the auto-loaded `AGENTS.md` (project) / `~/.pi/agent/AGENTS.md` (global, via `--global`) as plain Markdown, and folds non-root rules into that single file (Pi has no modular rules directory). Pi additionally loads two system-prompt instruction files. `.pi/APPEND_SYSTEM.md` (project) / `~/.pi/agent/APPEND_SYSTEM.md` (global) **appends** to the default system prompt, and Rulesync emits it from any rule that opts in via a `pi.systemPrompt: append` frontmatter block — those rule bodies are routed to `APPEND_SYSTEM.md` instead of `AGENTS.md`, multiple opted-in rules concatenate in source order, and the file is managed by generate/import/delete like the root file (note: if you hand-authored `.pi/APPEND_SYSTEM.md` before this feature existed, `generate --delete` for the `pi` target now treats it as a managed path and removes it unless a rule opts in — import it first to convert it into a canonical rule). The opt-in is ignored on the `root: true` rule, which always stays on `AGENTS.md` (routing the root away would leave the context file without a merge target). `.pi/SYSTEM.md` (project) / `~/.pi/agent/SYSTEM.md` (global) **replaces** the default system prompt entirely — which silently disables Pi's built-in tool instructions — so Rulesync deliberately never emits it and leaves it to be authored by hand. Example:\n>\n> ```yaml\n> ---\n> targets: [\"pi\"]\n> description: \"House style for the system prompt\"\n> pi:\n>   systemPrompt: append # routes this rule's body to .pi/APPEND_SYSTEM.md / ~/.pi/agent/APPEND_SYSTEM.md\n> ---\n> ```\n>\n> Pi tries `AGENTS.override.md` before `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md` and `CLAUDE.MD` in every directory it scans (including the global `~/.pi/agent/` one), loading it **instead of** the others from that directory. Set `pi.contextFile: override` on the **`root: true`** rule to emit the root context file under that name — useful when another target owns the shared `AGENTS.md`, or when a `CLAUDE.md` sits next to it and Pi should deterministically prefer Rulesync's output. Because Pi folds every rule body into the root context file, one opted-in root rule decides for the whole Pi output: the flag is applied to every other Pi rule (root ones included), and setting it _only_ on a non-root rule is ignored with a warning — emitting both files would hide everything left in `AGENTS.md`. `AGENTS.override.md` is Pi-exclusive, so it is imported and deleted like the root file, and toggling the flag off cleans it up. The project-root `AGENTS.md` is never deleted on Pi's behalf, with or without the flag: `agentsmd`, `codexcli`, `warp` and others write that same path, so the `pi` target leaves a stale one behind rather than removing another target's output (the global `~/.pi/agent/AGENTS.md` is Pi-exclusive and is still cleaned up). Example:\n>\n> ```yaml\n> ---\n> root: true\n> targets: [\"pi\"]\n> pi:\n>   contextFile: override # emits AGENTS.override.md instead of AGENTS.md\n> ---\n> ```\n>\n> See the [Pi usage docs](https://pi.dev/docs/latest/usage) and the [context-file discovery in the Pi source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/resource-loader.ts).\n\n> **Devin note:** The root rule is emitted to the project-root `AGENTS.md` — the file [Devin CLI / Devin Local actually reads](https://docs.devin.ai/cli/extensibility/rules) (its rules page does not list `.devin/rules/` among its sources) — as plain markdown, while non-root rules keep going to `.devin/rules/*.md`, the Devin Desktop Cascade directory whose `trigger` activation modes (`always_on`, `glob`, `manual`, `model_decision`) are driven by the `devin` frontmatter block. Global mode mirrors that layout: the root rule is a plain `~/.config/devin/AGENTS.md`, and non-root rules are emitted one file per rule into `~/.devin/rules/*.md` with the same `trigger`/`globs` frontmatter. Note the directory split — the per-rule global directory is the home `~/.devin/`, not the `~/.config/devin/` tree the global root and Devin's other global surfaces use; that is what the rules page documents (`~/.devin/rules/*.md`, `~/.devin/global_rules.md`).\n\n> **Amp note:** Amp gates an @-mentioned guidance file on `globs:` YAML frontmatter — the file is loaded only after Amp has read a file matching one of the globs, and **without** the frontmatter it is always loaded. Rulesync therefore emits each non-root rule's `globs` as that frontmatter on the generated `.agents/memories/*.md` file (in addition to the advisory `applyTo` value in the root file's TOON table, which Amp does not enforce), and restores it into the canonical `globs` on import. Amp implicitly prefixes each glob with `**/` unless it starts with `./` or `../`, so canonical globs pass through verbatim. See [Globs in AGENTS.md](https://ampcode.com/news/globs-in-AGENTS.md).\n\n> **Junie note:** Junie CLI resolves project guidelines in order — `.junie/AGENTS.md` → root `AGENTS.md` combined with `.junie/playbook.md` and every `.junie/rules/*.md` → the legacy `.junie/guidelines.md` / `.junie/guidelines/`. The multi-file branch is unreachable whenever `.junie/AGENTS.md` exists, because that file \"is used exclusively and no other guidelines files are combined with it\". Rulesync therefore writes the root rule to `.junie/AGENTS.md` (project) / `~/.junie/AGENTS.md` (global, via `--global`) and folds non-root rules into that single file — lossless, since Junie loads it in full. Emitting `.junie/rules/*.md` beside it would produce files Junie never reads, and moving the root output to the project-root `AGENTS.md` would change every existing output path and collide with the `agentsmd` target, so the fold stays. The multi-file branch **is** read on import, but only while `.junie/AGENTS.md` is absent — exactly when Junie itself reads it. Hand-authored `.junie/rules/*.md` (that directory itself, not a tree below it) and `.junie/playbook.md` are then imported as non-root rules. They are import-only read roots — Rulesync never generates them, never deletes them as orphans, and never adds them to `.gitignore` — so the `generate` that follows folds their content into `.junie/AGENTS.md` and leaves the originals untouched. Later imports skip them with a single warning naming up to ten skipped files (the rest are folded into an `and N more` count): re-reading rules the root file already contains would fold the same content in again on every import/generate cycle. Only `.junie/AGENTS.md` closes that gate — the legacy `.junie/guidelines.md` does not, since Junie ranks it _below_ the multi-file branch and Rulesync never writes it, so nothing has been folded into it. In that legacy layout both branches are imported at once, so a `.junie/rules/overview.md` and the legacy root claim the same `.rulesync/rules/overview.md`; the root file wins, and the usual collision warning names the file that lost. Delete them once you have checked the fold, since Junie stops reading them the moment `.junie/AGENTS.md` exists. In that pre-`.junie/AGENTS.md` layout Junie's root file is the project-root `AGENTS.md`, which belongs to the `agentsmd` target. `rulesync import` takes one target at a time, so run `rulesync import --targets agentsmd` before `rulesync import --targets junie` if you want a root rule as well: a `junie`-only import of that layout yields non-root rules alone, and the next `generate` writes `.junie/AGENTS.md` — at which point Junie stops reading the project-root `AGENTS.md` whose content was never imported. The legacy `.junie/guidelines.md` is still accepted as an import fallback. Earlier Rulesync versions emitted non-root rules to `.junie/memories/*.md`, which is not a documented Junie read path; those files are no longer generated (stale outputs stay gitignored but are not cleaned up automatically). See the [Junie guidelines docs](https://junie.jetbrains.com/docs/guidelines-and-memory.html) and the [Junie IDE plugin docs](https://junie.jetbrains.com/docs/junie-ide-plugin.html) — the IDE plugin page is where the exclusivity sentence quoted above appears.\n\n> **Reasonix note:** Reasonix auto-injects a hierarchical instruction document, reading its vendor-specific `REASONIX.md` (alongside the cross-tool `AGENTS.md`/`CLAUDE.md`) by walking user-home → ancestors → project root/local. Rulesync writes the vendor `REASONIX.md` at the project root (project) / `~/.reasonix/REASONIX.md` (global, via `--global`) and folds non-root rules into that single file, since Reasonix has no modular rules directory. Directory-scoped rules are the exception: Context Engine v2 (v1.18.0) also walks from the workspace root to the target path loading per-directory instruction files (“Deeper directories beat broader directories”), so a non-root rule carrying `agentsmd.subprojectPath` is emitted as a nested `<subprojectPath>/REASONIX.md` (project scope only) instead of being folded — its paragraphs load only under that path rather than being carried on every turn. On **import**, nested `REASONIX.md` files are discovered by the same project scan the AGENTS.md standard uses (same dependency/build-directory exclusions; import-only, never removed by `--delete`) and land in `.rulesync/rules/<directory-with-hyphens>-reasonix.md` with `targets: [\"reasonix\"]` and the `subprojectPath` carried, so the next generate puts them back. The `-reasonix` suffix and the reasonix-only targeting keep them from clobbering the AGENTS.md standard's derived names or surprising other tools with new nested files; note that a rule targeting both `agentsmd` and `reasonix` with a `subprojectPath` produces a nested `AGENTS.md` **and** a nested `REASONIX.md` in the same directory, both of which Reasonix loads — scope such rules to one target. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md) and [Context Engine v2 docs](https://github.com/esengine/DeepSeek-Reasonix/blob/v1.18.0/docs/SESSION_MEMORY_RETRIEVAL.md).\n\n> **Vibe Code note:** Vibe reads the project-root `AGENTS.md` (project) / `~/.vibe/AGENTS.md` (global, via `--global`) and folds non-root rules into that single file, since it has no modular rules directory. Directory-scoped rules are the exception: Vibe's harness manager walks the directories between the workspace root and the file being read and loads every `AGENTS.md` it finds along the way (`find_subdirectory_agents_md`), injecting the result into the `read_file` tool's output since v2.19.1 — so a non-root rule carrying `agentsmd.subprojectPath` is emitted as a nested `<subprojectPath>/AGENTS.md` (project scope only) instead of being folded. On **import**, nested files are discovered by the same project scan the AGENTS.md standard uses (same dependency/build-directory exclusions; import-only, never removed by `--delete`). Unlike the Reasonix note above, the imported rule is **not** suffixed or target-scoped: Vibe's nested file is literally the AGENTS.md standard's own per-directory file at the same path, so it lands in `.rulesync/rules/<directory-with-hyphens>.md` with `targets: [\"*\"]` — importing the same file through `agentsmd` and `vibe` therefore yields one rulesync rule, not two copies that would fold duplicated content back into the same `AGENTS.md`. Because the emitted file is the plain per-directory `AGENTS.md`, a rule scoped with `targets: [\"vibe\"]` is still picked up by every other AGENTS.md reader working in that directory — Vibe's nested surface is the shared standard's file, so target-scoping it is structurally impossible. See [mistral-vibe](https://github.com/mistralai/mistral-vibe) (`vibe/core/config/harness_files/_harness_manager.py`).\n\n> **Meta Muse Code note:** Muse Code walks up from the working directory to the `.git` boundary and loads one instruction file per directory level, preferring `AGENTS.md` over `CLAUDE.md` when both exist. The `musecode` target writes the root rule to the shared project-root `AGENTS.md` (the same file `agentsmd`, `codexcli` and others write) and folds non-root rules into it, since Muse Code has no modular rules directory. Muse Code has user/global rules, but their path is not documented, so the `musecode` rules target is project-scope only. See the [Muse Code configuration docs](https://dev.meta.ai/docs/muse-code/configuration.md).\n\n> **ZCode note:** ZCode (Z.ai's agentic development environment for the GLM family) reads exactly two instruction files — the user-global `~/.zcode/AGENTS.md` and the workspace `AGENTS.md` at the project root — and appends them in that order. Its docs are explicit that it \"does not merge multiple `AGENTS.md` files across directory levels\" and \"does not scan child directories\", so there is no nested rules surface to emit: rulesync writes the project-root `AGENTS.md` (project) / `~/.zcode/AGENTS.md` (global, via `--global`) and folds non-root rules into that single file. `CLAUDE.md` is deliberately not written for `zcode`: ZCode reads it only once, during onboarding, as a migration source. See the [ZCode AGENTS.md docs](https://zcode.z.ai/en/docs/agents).\n\n## `.rulesync/hooks.jsonc`\n\n`.rulesync/hooks.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/hooks.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nA key named `__proto__`, `constructor`, or `prototype` is rejected with an error naming its path, rather than being dropped in silence. The \"Rejected keys\" paragraph in the `.rulesync/permissions.jsonc` section below describes this handling, which is the same for all three source files.\n\nHermes Agent accepts native snake-case events under `hermesagent.hooks`: `pre_tool_call`, `post_tool_call`, `transform_terminal_output`, `transform_tool_result`, `transform_llm_output`, `pre_llm_call`, `post_llm_call`, `on_stream_start`, `on_stream_delta`, `on_stream_end`, `on_interim_message`, `pre_verify`, `pre_api_request`, `post_api_request`, `api_request_error`, `on_session_start`, `on_session_end`, `on_session_finalize`, `on_session_reset`, `on_skill_lifecycle`, `subagent_start`, `subagent_stop`, `pre_gateway_dispatch`, `pre_approval_request`, `post_approval_response`, `pre_transcription`, `kanban_task_claimed`, `kanban_task_completed`, `kanban_task_blocked`, `on_kanban_worker_spawned`, `on_kanban_worker_exited`, `on_kanban_worker_stale_claim`, `on_kanban_task_updated`, `on_kanban_dispatch_tick`, `gateway_platform_event`, and `pre_command`. That is 36 of the 37 `VALID_HOOKS` entries at v0.20.2: `transform_api_error_classification` is subtracted by `SHELL_UNSUPPORTED_HOOKS`, because a shell hook cannot return its directive and Hermes refuses the registration — authoring it still emits the entry, with a warning saying it will never run. Rulesync maps shared canonical events first, applies canonical keys from `hermesagent.hooks` next, then applies exact native keys last. An exact native key therefore wins when both forms resolve to the same Hermes event. Native-only events remain under `hermesagent.hooks` on import instead of leaking into other targets. Rulesync owns the event keys inside the `hooks:` mapping of `config.yaml`, but not the mapping itself: Hermes v0.20.0 nests the [outbound webhook registry](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks) under the same key as `hooks.outbound`, so any key there that is not a Hermes hook event is carried over from the existing file untouched. Rulesync neither authors nor imports `outbound`, since it is a list of webhook targets rather than a hook event; it only makes sure a regenerate leaves it alone. An event key Rulesync did write, including one under an undocumented event name supplied through `hermesagent.hooks`, is still retracted when it disappears from the source.\n\nHooks run scripts at lifecycle events (e.g. session start, before tool use). Events use **canonical camelCase** in this file, and Rulesync translates them per tool: Cursor uses them as-is; Claude Code, Factory Droid, Codex CLI, Qwen Code, and Goose get PascalCase (with a few tool-specific name mappings) in their settings files; OpenCode and Kilo hooks are emitted as JavaScript plugins (`.opencode/plugins/rulesync-hooks.js`, `.kilo/plugins/rulesync-hooks.js`) — both share one event surface apart from `notification` (see below), in which `preToolUse`/`postToolUse` become named `tool.execute.before`/`tool.execute.after` hooks, `preCompact` becomes the named `experimental.session.compacting` hook and `beforeSubmitPrompt` the named `chat.message` hook (both receive `(input, output)` and expose nothing to match on, so a `matcher` on either is dropped), `beforeShellExecution`/`afterShellExecution` also land in those named `tool.execute.*` hooks with an implicit `input.tool === \"bash\"` gate — OpenCode has no shell-execution lifecycle event (`command.executed`, which earlier Rulesync versions mapped `afterShellExecution` to, is a _slash-command_ event, so the hook never fired on shell commands; regenerate to fix), and matchers on the shell events are dropped with a warning since the named hooks expose no command text, and the rest are `event.type` dispatches — `sessionStart` → `session.created`, `stop` → `session.idle`, `afterFileEdit` → `file.edited`, `permissionRequest` → `permission.asked`, `permissionDenied` → `permission.replied` (which fires for every reply, so the generated handler is gated on `event.properties.reply === \"reject\"`), `notification` → `tui.toast.show` (**OpenCode only** — Kilo's plugin docs document no TUI events, so `notification` is not part of its surface; note too that OpenCode's toast channel is broader than the canonical event, since every `info`/`success`/`warning`/`error` toast fires the hook rather than only the ones asking for your attention, and most toasts originate in the TUI client, so a headless `opencode run` rarely fires it at all), `postCompact` → `session.compacted`, `afterError` → `session.error`, `fileChanged` → `file.watcher.updated`; Amp hooks are emitted as a TypeScript plugin (`.amp/plugins/rulesync-hooks.ts`, or `~/.config/amp/plugins/rulesync-hooks.ts` in global mode) using `session.start`, `tool.call`, `tool.result`, `agent.start`, and `agent.end`; Pi Coding Agent hooks are emitted as a Rulesync-owned TypeScript extension (`.pi/extensions/rulesync-hooks.ts`, or `~/.pi/agent/extensions/rulesync-hooks.ts` in global mode) that subscribes to Pi's snake_case extension events (`sessionStart` → `session_start`, `stop` → `agent_end`, `preToolUse` → `tool_call` with the matcher tested as a regex against the tool name, `preCompact` → `session_before_compact`, `postCompact` → `session_compact`, `postModelInvocation` → `message_end` gated on assistant messages so it runs once per finalized model response, `beforeSubmitPrompt` → `input`) — `tool_call` is Pi's only tool gate, so a `preToolUse` command that exits non-zero denies the call with `{ block: true, reason }` (the reason is the command's stderr, falling back to its stdout and then to its exit code, with terminal escape sequences, control and C1 characters, and format characters such as bidirectional overrides and zero-width joiners stripped, carriage returns folded into newlines so the text cannot overwrite an already printed line, the sanitized result capped at 2000 characters (and only the first 128000 characters of the command's output scanned at all) — sanitizing first so a reason that opens with a progress banner is still reported by its content — and a generic `Hook command failed.` used when nothing survives), and `input` is its prompt-submission gate, so a `beforeSubmitPrompt` command that exits non-zero cancels the prompt with `{ action: \"handled\" }` — that result carries no reason field, so the same text is reported through `ctx.ui.notify`, falling back to stderr in print (`-p`) and JSON modes where that channel is a no-op; three limits are worth knowing before relying on the prompt gate: Pi checks extension slash commands before the `input` event, so input consumed as a `/cmd` never reaches the gate, messages another extension injects via `sendUserMessage` (`event.source === \"extension\"`) are deliberately passed through because the canonical event covers prompts the user submits, and the hook command receives no prompt text (Pi's `input` event exposes it, but the generated handler runs the command with no stdin or arguments, unlike Claude Code's `UserPromptSubmit`), so the gate can only decide from ambient state; a `matcher` on `beforeSubmitPrompt` is dropped, since `input` exposes no tool name to test it against; every other event, `postToolUse`/`tool_result` included, observes only and cannot block or mutate Pi events; a denied call deliberately leaves Pi's `terminate` flag unset so control returns to the model instead of ending the turn; Copilot and Copilot CLI map event names to their own camelCase (e.g. `beforeSubmitPrompt` → `userPromptSubmitted`, `stop` → `agentStop`, `afterError` → `errorOccurred`) and write the command into the `bash`/`powershell` field named by the canonical `shell` selector, or into the portable `command` field when none is set — Copilot CLI additionally covers a wider event set and supports `prompt` and `http` hook types beyond `command`; deepagents-cli gets the Hooks v2 PascalCase `HookEvent` names (e.g. `SessionStart`, `PostToolUseFailure`) in a `{ \"hooks\": { \"<Event>\": [{ \"matcher\": …, \"hooks\": [{ \"type\": \"command\", … }] }] } }` document — this requires deepagents-code 0.1.52+, the release where Hooks v2 became generally available (the legacy flat list is removed upstream on 2026-09-01; Rulesync still imports the legacy format but no longer writes it); `kiro-cli` and `kiro-ide` emit hooks into the standalone `.kiro/hooks/rulesync.json` with PascalCase triggers, while the deprecated `kiro` alias still writes them into `.kiro/agents/default.json` using the older event names (`agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop`); Qwen Code emits PascalCase events into the `hooks` key of `.qwen/settings.json` (its supported event set differs from Gemini CLI's).\n\nExample:\n\n```json\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"sessionStart\": [{ \"type\": \"command\", \"command\": \".rulesync/hooks/session-start.sh\" }],\n    \"preToolUse\": [{ \"matcher\": \"Bash\", \"command\": \".rulesync/hooks/confirm.sh\" }],\n    \"postToolUse\": [{ \"matcher\": \"Write|Edit\", \"command\": \".rulesync/hooks/format.sh\" }],\n    \"stop\": [{ \"command\": \".rulesync/hooks/audit.sh\" }]\n  },\n  \"cursor\": {\n    \"hooks\": {\n      \"afterFileEdit\": [{ \"command\": \".cursor/hooks/format.sh\" }]\n    }\n  },\n  \"claudecode\": {\n    \"hooks\": {\n      \"notification\": [\n        {\n          \"matcher\": \"permission_prompt\",\n          \"command\": \"$CLAUDE_PROJECT_DIR/.claude/hooks/notify.sh\"\n        }\n      ]\n    }\n  },\n  \"opencode\": {\n    \"hooks\": {\n      \"afterShellExecution\": [{ \"command\": \".rulesync/hooks/post-shell.sh\" }]\n    }\n  },\n  \"copilot\": {\n    \"hooks\": {\n      \"afterError\": [{ \"command\": \".rulesync/hooks/report-error.sh\" }]\n    }\n  }\n}\n```\n\n**Top-level keys:**\n\n- `version`: Schema version (currently `1`).\n- `hooks`: Map of canonical event names to an array of hook entries. These are dispatched to every tool that supports the given event.\n- `amp.hooks`, `cursor.hooks`, `claudecode.hooks`, `opencode.hooks`, `kilo.hooks`, `copilot.hooks`, `copilotcli.hooks`, `factorydroid.hooks`, `codexcli.hooks`, `goose.hooks`, `deepagents.hooks`, `kiro.hooks`, `qwencode.hooks`, `grokcli.hooks`: Tool-specific **override keys**. Entries under these keys are emitted only for the corresponding tool, so tool-only events (e.g. `afterFileEdit` for Cursor/OpenCode/Kilo, `worktreeCreate` for Claude Code, `afterError` for Copilot/Copilot CLI, `PostFileSave`/`PreTaskExec` for Kiro) can coexist with shared ones without leaking to other tools. `copilotcli.hooks` falls back to `copilot.hooks`, which in turn falls back to the shared `hooks` block.\n\n**Hook entry keys:**\n\n- `command` (required): Shell command to execute when the event fires.\n- `type` (optional): One of `\"command\"` (default), `\"prompt\"`, `\"http\"`, `\"agent\"`, `\"mcp_tool\"`, or `\"function\"` — the union of the hook types accepted across supported tools. Each tool supports a subset (most support only `command`); hooks with a type a tool does not support are skipped for that tool with a warning. See notes below.\n- `matcher` (optional): Regex used by tools that scope hooks to specific tool names (e.g. `preToolUse`, `postToolUse`, `notification`). Ignored by events that do not take a matcher (e.g. `sessionStart`, `worktreeCreate`, `worktreeRemove`).\n- `timeout` (optional): Per-hook timeout in seconds, forwarded to tools that support it.\n- `cacheTtl` (optional): Number of seconds to cache a successful hook result. Forwarded to the deprecated `kiro` alias's agent-config format as `cache_ttl_seconds`; `0` disables caching and Kiro never caches `AgentSpawn` hooks.\n- `failClosed` (optional): Boolean. When `true`, a hook failure (crash, timeout, invalid JSON) blocks the action instead of allowing it through. Passed through to Cursor's `.cursor/hooks.json`, to JetBrains Junie's `~/.junie/config.json` (as Junie's equivalently-named `blockOnError` flag), and to Hermes Agent's `~/.hermes/config.yaml` (as `fail_closed`). Hermes only honours it on `pre_tool_call`, its one blocking-capable event, so a `failClosed` set on any other canonical event is dropped with a warning.\n- `commandRegex` (optional): Regex applied to the shell command string, narrowing an `Execute` matcher group further (e.g. `\"^git \"`). Forwarded to Factory Droid, which skips invalid regex values. Like `matcher`, it belongs to the whole matcher group, so every hook sharing that matcher receives it.\n- `async` (optional): Boolean. When `true`, the hook command runs in the background without blocking. Forwarded to Qwen Code (`.qwen/settings.json`), JetBrains Junie (`~/.junie/config.json`, same field name), Claude Code and Codex CLI (`.codex/hooks.json`, same field name — Codex runs up to eight background hooks concurrently per session and queues the rest).\n- `env` (optional, `command` hooks): a map of extra environment variables merged into the hook process's environment. Forwarded to Qwen Code (`.qwen/settings.json`), Copilot CLI, and Grok CLI (`.grok/hooks/rulesync.json`, upstream `HookConfig.env`, merged into the spawned command's `extra_env`). Documented on command hooks only, so it is neither emitted on a hook of another type nor imported from one (a value found there is dropped with a warning). For Grok CLI, an entry whose key is empty or contains `=`, or whose key or value contains a newline, carriage return or NUL, is refused in both directions — the tool rebuilds each entry into a `KEY=VALUE` string, so such a key would name a different variable than it appears to.\n- `shell` (optional): Either `\"bash\"` or `\"powershell\"` — the only two interpreter values any tool accepts. Forwarded to Qwen Code, Claude Code, Copilot and Copilot CLI command hooks; for the two Copilot targets it names the `bash`/`powershell` field the command is written into, and leaving it unset selects their portable `command` field. Like `args`, `async` and `asyncRewake`, it is documented on command hooks only, so it is neither emitted on a hook of another type nor imported from one (a value found there is dropped with a warning).\n- `url` / `headers` / `allowedEnvVars` (optional, `http` hooks): the POST target URL, request headers (values support `$VAR` interpolation), and the env-var allowlist for that interpolation. Forwarded to Claude Code and Qwen Code http hooks.\n- `server` / `tool` / `input` (optional, `mcp_tool` hooks): the configured MCP server name, the tool to call on it, and the (arbitrary JSON) arguments, whose string values support `${path}` substitution from the hook input. Forwarded to Claude Code mcp_tool hooks.\n- `model` (optional, `prompt` / `agent` hooks): the model used for evaluation (defaults to a fast model). Forwarded to Claude Code prompt/agent hooks and to Qwen Code prompt hooks.\n- `args` (optional, `command` hooks): an argument list. When present — an empty list counts, and is the form the Claude Code docs use — the tool spawns `command` directly as an executable with these arguments. There is no shell, so Rulesync writes the project-directory prefix as the braced placeholder `${CLAUDE_PROJECT_DIR}/…` that Claude Code substitutes itself, rather than the quoted shell form. Forwarded to Claude Code and AugmentCode. Only `command` is prefixed; entries of `args` are passed through exactly as written.\n- `asyncRewake` (optional): boolean. Like `async`, but wakes Claude when the hook exits with code 2. Forwarded to Claude Code command hooks.\n- `once` (optional): boolean. Run the hook once per session, then remove it. Forwarded to Claude Code (honored in skill frontmatter; accepted but ignored in settings files) and Qwen Code http hooks.\n- `continueOnBlock` (optional): boolean. Feed a blocking hook's rejection reason back to the model and continue the turn instead of ending it. Forwarded to Claude Code.\n- `commandWindows` (optional): a Windows-only override for `command`, so one hook set can be cross-platform. Forwarded to Codex CLI command hooks (`.codex/hooks.json`), which is the only tool that accepts it.\n- `additionalContextLimit` (optional): a non-negative integer. The token threshold above which the tool writes the hook's additional context to a file and passes that path instead of the text itself (upstream default 2500). Forwarded to Codex CLI command hooks (`.codex/hooks.json`), which is the only tool that accepts it.\n- `statusMessage` (optional): the progress text shown while the hook runs. Forwarded to Qwen Code (command and http hooks) and to Codex CLI command hooks.\n- `enabled` (optional): boolean, default `true`. Whether the hook is active. Forwarded to Kiro's standalone hooks file (`.kiro/hooks/rulesync.json`, written by the `kiro-cli` and `kiro-ide` targets), the only place with a per-hook on-disk enable flag Rulesync writes; an imported `enabled: false` round-trips, so a deliberately disabled hook is not silently switched back on by the next generate. Every other target has no way to express it, so the hook is emitted there as an ordinary **active** hook and a warning is logged at generate time — to turn a hook off everywhere, remove it rather than setting `enabled: false`. (Antigravity has an `enabled` flag of its own, but on the named hook group rather than the individual definition, so it is not driven by this field.)\n- `if` (optional): a single permission rule (same syntax as `settings.json` permission rules, e.g. `\"Bash(rm *)\"`) that filters a hook by tool arguments in addition to the tool name. Forwarded to Claude Code, where it is evaluated only on tool events (`preToolUse`, `postToolUse`, `postToolUseFailure`, `permissionRequest`, `permissionDenied`); it round-trips as an opaque string.\n\nA field a tool documents on `command` hooks only (`args`, `env`, `shell`, `async`, `asyncRewake`) is dropped with a warning in both directions when it appears on a hook of another type — on generate for a value authored in `.rulesync/hooks.*`, and on import for one found in an existing tool config. Import additionally checks each value against the constraint the canonical field declares (e.g. `shell` must be `\"bash\"` or `\"powershell\"`, `additionalContextLimit` must be a non-negative integer, and no string field may carry a newline, carriage return or NUL); a value that fails is skipped with a warning naming the constraint, rather than imported into a file the next generate would refuse to read. When the offending value is a `command`, `prompt` or `matcher`, the whole hook is skipped instead of just that field, since a hook without its command runs nothing and a hook without its matcher fires on everything.\n\nTop-level `hooks` keys must be canonical event names; unknown event names are rejected at parse time. Tool-specific override blocks (e.g. `kiro.hooks`) additionally accept tool-native event keys, which pass through verbatim.\n\nEvents present in the shared `hooks` block but unsupported by a given tool are skipped for that tool (a warning is logged at generate time). The canonical `notification` event maps to deepagents-cli's Hooks v2 `Notification` event, whose matcher selects the notification kind (e.g. `agent_needs_input`); canonical `contextOffload` is skipped for deepagents-cli, since its legacy `context.offload` event has no Hooks v2 counterpart.\n\n### Hook event × tool matrix\n\n<!-- HOOK_EVENTS_MATRIX:BEGIN -->\n\n| Event                  | Amp | Claude Code | Claude Code plugin | Codex CLI | GitHub Copilot | GitHub Copilot CLI | Goose | Hermes Agent | Grok CLI | Cursor | deepagents-cli | Factory Droid | OpenCode | Cline | Kilo Code | Kimi Code | Vibe Code | Qwen Code | Reasonix | Kiro ⚠️ | Kiro CLI | Kiro IDE | Google Antigravity IDE | Google Antigravity CLI | Google Antigravity plugin | JetBrains Junie | AugmentCode | Devin Desktop | Pi Coding Agent |\n| ---------------------- | :-: | :---------: | :----------------: | :-------: | :------------: | :----------------: | :---: | :----------: | :------: | :----: | :------------: | :-----------: | :------: | :---: | :-------: | :-------: | :-------: | :-------: | :------: | :-----: | :------: | :------: | :--------------------: | :--------------------: | :-----------------------: | :-------------: | :---------: | :-----------: | :-------------: |\n| `sessionStart`         | ✅  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      ✅      |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |  ✅   |    ✅     |    ✅     |     —     |    ✅     |    ✅    |   ✅    |    ✅    |    ✅    |           —            |           —            |             —             |       ✅        |     ✅      |      ✅       |       ✅        |\n| `sessionEnd`           |  —  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      ✅      |    ✅    |   ✅   |       ✅       |      ✅       |    —     |  ✅   |     —     |    ✅     |     —     |    ✅     |    ✅    |   ✅    |    —     |    —     |           —            |           —            |             —             |       ✅        |     ✅      |      ✅       |       ✅        |\n| `preToolUse`           | ✅  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      ✅      |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |  ✅   |    ✅     |    ✅     |    ✅     |    ✅     |    ✅    |   ✅    |    ✅    |    ✅    |           ✅           |           ✅           |            ✅             |       ✅        |     ✅      |      ✅       |       ✅        |\n| `postToolUse`          | ✅  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      ✅      |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |  ✅   |    ✅     |    ✅     |    ✅     |    ✅     |    ✅    |   ✅    |    ✅    |    ✅    |           ✅           |           ✅           |            ✅             |        —        |     ✅      |      ✅       |       ✅        |\n| `preModelInvocation`   |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      ✅      |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           ✅           |           ✅           |            ✅             |        —        |      —      |       —       |       ✅        |\n| `postModelInvocation`  |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      ✅      |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    ✅    |    —    |    —     |    —     |           ✅           |           ✅           |            ✅             |        —        |      —      |       —       |       ✅        |\n| `beforeSubmitPrompt`   | ✅  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      —       |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |  ✅   |    ✅     |    ✅     |     —     |    ✅     |    ✅    |   ✅    |    ✅    |    ✅    |           —            |           —            |             —             |       ✅        |     ✅      |      ✅       |       ✅        |\n| `stop`                 | ✅  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |  ✅   |      —       |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |   —   |    ✅     |    ✅     |    ✅     |    ✅     |    ✅    |   ✅    |    ✅    |    ✅    |           ✅           |           ✅           |            ✅             |       ✅        |     ✅      |      ✅       |       ✅        |\n| `subagentStop`         |  —  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |   —   |      ✅      |    ✅    |   ✅   |       ✅       |      ✅       |    —     |   —   |     —     |    ✅     |     —     |    ✅     |    ✅    |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `preCompact`           |  —  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |   —   |      —       |    ✅    |   ✅   |       ✅       |      ✅       |    ✅    |  ✅   |    ✅     |    ✅     |     —     |    ✅     |    ✅    |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |       ✅        |\n| `postCompact`          |  —  |     ✅      |         ✅         |    ✅     |       —        |         —          |   —   |      —       |    ✅    |   —    |       —        |       —       |    ✅    |   —   |    ✅     |    ✅     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |      ✅       |       ✅        |\n| `postToolUseFailure`   |  —  |     ✅      |         ✅         |     —     |       ✅       |         ✅         |  ✅   |      —       |    ✅    |   ✅   |       ✅       |       —       |    —     |   —   |     —     |    ✅     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `subagentStart`        |  —  |     ✅      |         ✅         |    ✅     |       ✅       |         ✅         |   —   |      ✅      |    ✅    |   ✅   |       ✅       |       —       |    —     |   —   |     —     |    ✅     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `beforeShellExecution` |  —  |      —      |         —          |     —     |       —        |         —          |  ✅   |      —       |    —     |   ✅   |       —        |       —       |    ✅    |   —   |    ✅     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterShellExecution`  |  —  |      —      |         —          |     —     |       —        |         —          |  ✅   |      —       |    —     |   ✅   |       —        |       —       |    ✅    |   —   |    ✅     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `beforeMCPExecution`   |  —  |      —      |         —          |     —     |       —        |         ✅         |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterMCPExecution`    |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `beforeReadFile`       |  —  |      —      |         —          |     —     |       —        |         —          |  ✅   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterFileEdit`        |  —  |      —      |         —          |     —     |       —        |         —          |  ✅   |      —       |    —     |   ✅   |       —        |       —       |    ✅    |   —   |    ✅     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterAgentResponse`   |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterAgentThought`    |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `beforeTabFileRead`    |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterTabFileEdit`     |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `permissionRequest`    |  —  |     ✅      |         ✅         |    ✅     |       —        |         ✅         |   —   |      —       |    —     |   —    |       ✅       |       —       |    ✅    |   —   |    ✅     |    ✅     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |       ✅        |      —      |      ✅       |        —        |\n| `notification`         |  —  |     ✅      |         ✅         |     —     |       —        |         ✅         |   —   |      —       |    ✅    |   —    |       ✅       |      ✅       |    ✅    |  ✅   |     —     |    ✅     |     —     |    ✅     |    ✅    |    —    |    —     |    —     |           —            |           —            |             —             |        —        |     ✅      |       —       |        —        |\n| `setup`                |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `afterError`           |  —  |      —      |         —          |     —     |       ✅       |         ✅         |   —   |      —       |    —     |   —    |       —        |       —       |    ✅    |  ✅   |    ✅     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `worktreeCreate`       |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `worktreeRemove`       |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `workspaceOpen`        |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   ✅   |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `messageDisplay`       |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `todoCreated`          |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `todoCompleted`        |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `stopFailure`          |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    ✅    |   —    |       —        |       —       |    —     |   —   |     —     |    ✅     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |       ✅        |      —      |       —       |        —        |\n| `stopCancelled`        |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    ✅    |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `instructionsLoaded`   |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `userPromptExpansion`  |  —  |     ✅      |         ✅         |     —     |       ✅       |         ✅         |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `postToolBatch`        |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `permissionDenied`     |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    ✅    |   —    |       —        |       —       |    ✅    |   —   |    ✅     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `taskCreated`          |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `taskCompleted`        |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |  ✅   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `teammateIdle`         |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `configChange`         |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `cwdChanged`           |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `fileChanged`          |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    ✅    |   —   |    ✅     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `directoryAdded`       |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `elicitation`          |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `elicitationResult`    |  —  |     ✅      |         ✅         |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |     —     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n| `sessionDelete`        |  —  |      —      |         —          |     —     |       —        |         —          |   —   |      —       |    —     |   —    |       —        |       —       |    —     |   —   |     —     |     —     |     —     |    ✅     |    —     |    —    |    —     |    —     |           —            |           —            |             —             |        —        |      —      |       —       |        —        |\n\n<!-- HOOK_EVENTS_MATRIX:END -->\n\n> **Note:** `beforeSubmitPrompt`, `stop`, `worktreeCreate`, `worktreeRemove`, `messageDisplay`, `postToolBatch`, `taskCreated`, `taskCompleted`, `teammateIdle`, and `cwdChanged` are the Claude Code events the [matcher table](https://code.claude.com/docs/en/hooks) lists as not supporting the `matcher` field (they fire on every occurrence). A matcher authored on one of them is dropped with a warning rather than written into `settings.json` to be ignored. `directoryAdded` is **not** one of them: the matcher table documents it as filtering on how the directory was added (`slash_command`, `register_repo_root`), so a matcher written on it is emitted as-is.\n\n> **Note:** Rulesync implements OpenCode hooks as a plugin at `.opencode/plugins/rulesync-hooks.js` and Kilo hooks as a plugin at `.kilo/plugins/rulesync-hooks.js`, so importing from OpenCode/Kilo to rulesync is not supported. Both only support command-type hooks (not prompt-type).\n\n> **Note:** Rulesync implements Amp hooks as a generated TypeScript plugin at `.amp/plugins/rulesync-hooks.ts` (project) or `~/.config/amp/plugins/rulesync-hooks.ts` (global), so importing arbitrary Amp plugin code is not supported. Amp supports command hooks for `sessionStart` → `session.start`, `preToolUse` → `tool.call`, `postToolUse` → `tool.result`, `beforeSubmitPrompt` → `agent.start`, and `stop` → `agent.end`. Tool-event matchers are regular expressions against the Amp tool name; definitions with a matcher on any lifecycle event are skipped with a warning. A failing `preToolUse` command rejects the tool call and lets the agent continue; other mapped events observe the command result.\n\n> **Amp command syntax:** Amp executes plugin commands with [Bun Shell](https://bun.com/docs/runtime/shell), whose syntax differs slightly from POSIX shells. Use `$VAR` for environment expansion (`${VAR}` remains literal) and `$(command)` for command substitution (backticks remain literal). Rulesync passes the authored command through unchanged so quoting and escaped operators retain their Bun Shell meaning.\n\n> **Note:** GitHub Copilot's format uses separate `powershell` and `bash` fields for hooks, plus a portable `command` field that upstream copies into both when neither is present. Rulesync picks between them with the canonical `shell` selector, and writes the portable `command` field when a hook does not set one. Earlier versions chose the field from the platform Rulesync happened to run on; regenerate to get a machine-independent file.\n\n> **Note:** Hook file paths per tool:\n>\n> - **Copilot (cloud agent / VS Code)** — project: `<project>/.github/hooks/copilot-hooks.json`; global: `~/.copilot/hooks/copilot-ide-hooks.json`. Command hooks carry `bash`/`powershell` with optional `timeoutSec`, plus the canonical `env` map and a pass-through `cwd`. On import, `timeout` is honored as an alias for `timeoutSec` when `timeoutSec` is absent. Which command field is written is chosen by the canonical `shell` selector; without it the portable `command` field is written, which upstream copies to both. It is deliberately **not** chosen from the platform Rulesync runs on: the cloud agent runs hooks in a **Linux sandbox** where only `bash` and `command` are honored, so a `powershell` entry generated on a Windows machine would simply never run. It also keeps the output identical everywhere, which matters because the cloud agent reads this file from the repository. For the same reason, an imported entry carrying both fields resolves to `bash` (with a warning) on every platform. VS Code and the coding agent both document `~/.copilot/hooks` as the user scope and load every `*.json` in that folder; the Copilot CLI's global file already occupies `copilot-hooks.json` there, so the VS Code target uses a distinct filename and the two never overwrite each other. Note the flip side of \"every `*.json` is loaded\": generating **both** `copilot` and `copilotcli` in global mode leaves two files in that one folder, and a reader of the folder runs the hooks from both — so a command present in your canonical config fires twice per event. Generate only one of the two globally unless you want that.\n> - **Copilot CLI** — project: `<project>/.github/hooks/copilotcli-hooks.json`; global: `~/.copilot/hooks/copilot-hooks.json`. The Copilot CLI docs let you choose any filename inside `.github/hooks/`, so Rulesync uses the CLI-specific name to avoid colliding with the cloud-agent file when both targets are enabled. The global path is a Rulesync convention; the official Copilot CLI documentation does not currently enumerate a global hooks location, so this placement may change if the spec later mandates an alternate layout. Copilot CLI uses a **wider event surface** than the shared cloud-agent set (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `agentStop` ← `stop`, `subagentStart`, `subagentStop`, `errorOccurred` ← `afterError`, `preCompact`, `permissionRequest`, `notification`, `userPromptTransformed` ← `userPromptExpansion`, `preMcpToolCall` ← `beforeMCPExecution`) and supports three hook types: **`command`** (`bash`/`powershell` with optional `timeoutSec`, plus pass-through `cwd`/`env`; on import the portable `command` field is read as the cross-platform fallback when neither shell field is present, and `timeout` is honored as an alias for `timeoutSec` when `timeoutSec` is absent. On generate the canonical `shell` selector chooses `bash` or `powershell`; without it the portable `command` field is written, so the generated file does not depend on the machine Rulesync ran on. An imported entry carrying both shell fields resolves to `bash` (with a warning) on every platform, so importing the same file yields the same canonical config everywhere), **`prompt`** (a `prompt` string — Copilot CLI only honors prompt hooks on `sessionStart`, so prompt hooks on other events are dropped), and **`http`** (`url`/`headers`/`allowedEnvVars` with optional `timeoutSec`). An entry's optional `matcher` field is emitted and round-tripped on the six events the hooks reference documents as matcher-aware — `preToolUse` and `postToolUse` (regex on the tool name), `permissionRequest` (tool name), `notification` (notification type), `preCompact` (the trigger, `manual` or `auto`) and `subagentStart` (agent name); on any other event a matcher is dropped with a warning because the CLI does not honor it there. See the [hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference).\n> - **Antigravity IDE / Antigravity CLI** — project: `<project>/.agents/hooks.json`; global: `~/.gemini/config/hooks.json`. Both targets share the same dedicated `hooks.json` (a Claude-Code-style matcher map nested under a generated `rulesync` hook name), so enabling both writes the same file.\n> - **Devin Desktop (formerly Windsurf)** — project: `<project>/.windsurf/hooks.json`; global: `~/.codeium/windsurf/hooks.json`. The Cascade Hooks file location is unchanged by the Devin Desktop rebrand.\n> - **Factory Droid** — project: `<project>/.factory/hooks.json`; global: `~/.factory/hooks.json`. A standalone `hooks.json` is keyed **directly by event name** (`{\"PreToolUse\": [...]}`); the `hooks` wrapper Droid documents belongs to `settings.json` only, so Rulesync writes the bare event map. The file is Rulesync-owned and rewritten wholesale, which also repairs a `hooks.json` an earlier version left in the wrapped shape — Droid found no known event key at the top level of that file, so none of those hooks ever fired; regenerate to fix. Import accepts both shapes: the top level when it names an event, and the `hooks` key otherwise, which is also how the legacy `.factory/settings.json` read-time fallback is understood. Import falls back in order: `.factory/hooks.json`, then the `.factory/settings.json` `hooks` key (with `.factory/settings.local.json` overlaid, since Droid reads the pair as one) when those settings actually carry a `hooks` key — an unrelated `settings.local.json` therefore does not shadow the next step — then the pre-1.0 `.factory/hooks/hooks.json` — last because Droid renames that file to `hooks.migrated.json` once it has migrated it, so a copy still sitting there is the least likely to be live. Only `.factory/hooks.json` is ever written. As with permissions below, a hook that came from the machine-local file is imported into `.rulesync/hooks.json` like any other, so the next `generate` writes it into the committed hooks files of every targeted tool — and a hook carries a command someone else's machine would then run. Drop a personal hook from `.rulesync/hooks.json` after importing if it should stay personal. Whatever the local file contributed is named in a warning while importing, so a personal value is visible before it is committed; a key that governs what the tool may run — a sandbox tier, an autonomy ceiling, the hooks it executes — is called out on its own, since publishing one machine's relaxed value makes it the team's.\n> - **AugmentCode** — project: `<project>/.augment/settings.json`; global: `~/.augment/settings.json`. Hooks are merged under the top-level `hooks` key of the shared settings file (which also holds `toolPermissions`).\n> - **Kimi Code** — global only: `~/.kimi-code/config.toml`. Hooks are merged into the shared `[[hooks]]` array without replacing unrelated model, provider, or permission settings.\n> - **Vibe Code** — project: `<project>/.vibe/hooks.toml`; global: `~/.vibe/hooks.toml`. Stable since v2.21.0, which removed the `enable_experimental_hooks` flag: declaring a hook is enough, so Rulesync writes nothing into `.vibe/config.toml` for hooks.\n\n> **Note:** Because each AI tool evolves its own hook surface at its own pace, the matrix above reflects the events Rulesync currently translates. When a tool ships a new event that Rulesync does not yet support, the most reliable path is to open an issue — the matrix is the intended baseline to compare against.\n\n> **Note:** Kiro has two hook formats, and the target you pick decides which one you get. The **`kiro-cli`** and **`kiro-ide`** targets write the standalone `{ \"version\": \"v1\", \"hooks\": [ … ] }` file that both products read today — `.kiro/hooks/rulesync.json` in project scope and `~/.kiro/hooks/rulesync.json` in user scope — with one array entry per hook carrying `name`, `trigger`, an optional `matcher`, an `action` (`{ \"type\": \"command\", \"command\": … }` for a canonical `command` hook, `{ \"type\": \"agent\", \"prompt\": … }` for a `prompt` hook), an optional `timeout` in seconds, and `enabled`. Triggers are PascalCase (`sessionStart` ⇄ `SessionStart`, `stop` ⇄ `Stop`, …); triggers with no canonical event, such as `PostFileSave` or `PreTaskExec`, are reachable through the **shared `kiro.hooks` override block** and pass through verbatim. Both targets write the same filename, so they read that one block rather than per-target `kiro-cli.hooks` / `kiro-ide.hooks` blocks — otherwise a divergent override would make the file's content depend on which target was generated last. Generating either or both targets therefore always yields the same file. A block authored under `kiro-cli.hooks` or `kiro-ide.hooks` is read by nothing and reported with a warning; move it to `kiro.hooks` (the same key the deprecated `kiro` alias, and the Kiro MCP and permissions wiring, already use). A second filename would not help either, since Kiro runs every `*.json` in the directory and both products read the same one. The deprecated `kiro` alias reads the same block but writes a different format, so the two writers each keep to their own vocabulary: a standalone-only trigger (`PostFileSave`, `PreTaskExec`, …) in `kiro.hooks` is dropped from the alias's `.kiro/agents/default.json` output with a warning, and an agent-config spelling (`agentSpawn`, `fileEdited`, …) is translated to its v1 equivalent (`SessionStart`, `PostFileSave`) for the standalone targets rather than written as a trigger Kiro does not define. Keys neither writer recognizes still pass through unchanged.\n>\n> The deprecated **`kiro`** alias still writes the older embedded format: `.kiro/agents/default.json` under the `hooks` field, merged with any existing agent configuration (tools, allowedTools, etc.). There, both `sessionEnd` and `stop` map to Kiro's `stop` event, only `command`-type hooks are supported (`prompt`-type hooks are silently skipped), per-hook timeouts are `timeout_ms` (milliseconds), and `cache_ttl_seconds` maps to the canonical `cacheTtl` field in both directions. Kiro's [hooks migration guide](https://kiro.dev/docs/cli/v3/hooks-migration/) states this format \"does not work in 3.0\", so prefer `kiro-cli`.\n>\n> If you generated `kiro-cli` hooks with an earlier Rulesync version, the `hooks` block it left in `.kiro/agents/default.json` is not removed for you — that file is shared with the permissions and subagents features, so Rulesync never deletes it. On Kiro CLI 2.x, which reads both formats, leaving it in place means every hook fires twice; delete the block by hand (or run Kiro's own agent migration) after regenerating. For the same reason, `rulesync import --targets kiro-cli --features hooks` now reads only the standalone file: to pull hooks out of an existing agent config, import with `--targets kiro`. Two event-surface differences come with the switch as well: Kiro's standalone triggers have no `SessionEnd`, so a canonical `sessionEnd` hook is dropped with a warning — use `stop` instead — and `cacheTtl` has no counterpart outside the agent-config format.\n\n> **Note:** Antigravity (IDE and CLI) writes a dedicated `hooks.json` keyed by a **named hook** whose value holds the event map, e.g. `{ \"rulesync\": { \"PreToolUse\": [ { \"matcher\": \"...\", \"hooks\": [...] } ], \"Stop\": [ { \"hooks\": [...] } ] } }`. Rulesync emits a single generated hook under the stable name `rulesync`. It supports five lifecycle events — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `preModelInvocation` ⇄ `PreInvocation`, `postModelInvocation` ⇄ `PostInvocation`, and `stop` ⇄ `Stop` — where `PreInvocation`/`PostInvocation`/`Stop` are matcher-less handler lists. On import, both the named-hook wrapper and a legacy flat top-level event map are accepted, and the optional per-hook `enabled` flag is ignored.\n\n> **Note:** Devin Desktop (formerly Windsurf) Cascade Hooks (GA) are written to a dedicated `hooks.json` whose top-level `hooks` key maps each Cascade event name to a **flat array** of hook objects (no `matcher`, no `type`, no inner `hooks` wrapper, and no `timeout`). Each object carries `command` and/or `powershell`, plus optional `show_output` and `working_directory`. Rulesync splits the generic tool lifecycle into Devin's file/command/MCP-specific events, so the canonical events map bijectively: `beforeReadFile` ⇄ `pre_read_code`, `beforeTabFileRead` ⇄ `post_read_code`, `afterTabFileEdit` ⇄ `pre_write_code`, `afterFileEdit` ⇄ `post_write_code`, `beforeShellExecution` ⇄ `pre_run_command`, `afterShellExecution` ⇄ `post_run_command`, `beforeMCPExecution` ⇄ `pre_mcp_tool_use`, `afterMCPExecution` ⇄ `post_mcp_tool_use`, `beforeSubmitPrompt` ⇄ `pre_user_prompt`, `afterAgentResponse` ⇄ `post_cascade_response`, `beforeAgentResponse` ⇄ `post_cascade_response_with_transcript`, and `worktreeCreate` ⇄ `post_setup_worktree`. Canonical events with no Devin equivalent (e.g. `sessionStart`, `stop`) are dropped with a logged warning. The Cascade Hooks file location (`.windsurf/hooks.json` / `~/.codeium/windsurf/hooks.json`) is retained from the Windsurf era and is unaffected by the rebrand.\n\n> **Note:** AugmentCode (Auggie CLI) hooks are merged under the top-level `hooks` key of the shared `.augment/settings.json` (project) / `~/.augment/settings.json` (global), mirroring Claude Code's per-event matcher arrays (`{ \"EventName\": [ { \"matcher\": \"...\", \"hooks\": [ { \"type\": \"command\", \"command\": \"...\", \"timeout\": ... } ] } ] }`). The `hooks` block is merged in place so it coexists with the `toolPermissions` block from the permissions feature. Seven lifecycle events are supported — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `stop` ⇄ `Stop`, `notification` ⇄ `Notification`, and `beforeSubmitPrompt` ⇄ `PromptSubmit` (added in Auggie 0.27.0). The `matcher` field (a case-sensitive regex, default `.*`, with `mcp:*` support) applies only to the tool events `PreToolUse`/`PostToolUse`; any matcher on the session events (including `Notification` and `PromptSubmit`) is dropped with a logged warning. Two Auggie-specific fields round-trip as well: a command hook's `args` (extra argv the runner appends, authored as `args` on the canonical hook) and the matcher group's `metadata` (`includeConversationData` / `includeMCPMetadata` / `includeUserContext`, which select what the runner puts in the JSON payload the script receives). `metadata` belongs to the group upstream, so it is authored on any hook of the group and re-applied to every hook of that group on import. Both matter because the `hooks` key is owned in the shared settings file: a value not written here is erased from a hand-written `settings.json` on the next generate. Commands are emitted verbatim — Auggie exposes `AUGMENT_PROJECT_DIR` as a runtime environment variable, not as an inline command substitution, so no directory prefix is added. Only `command`-type hooks are supported. On **import** (project scope), Rulesync also reads the layered overrides file `<workspace>/.augment/settings.local.json` — a gitignored, machine-specific file that Auggie merges on top of `settings.json` — and combines it over the base settings before importing, following Auggie's documented layering (simple values take the local override, `mcpServers`/`plugins` replace wholesale, and other objects/lists — including the `hooks` events — are combined across tiers), so personal hook overrides are picked up without dropping base events. This overlay is **import-only and project-only**: Rulesync never writes `settings.local.json`, AugmentCode documents no global `~/.augment/settings.local.json`, so the overlay is skipped in global mode. Whatever the local file contributed is named in a warning while importing, so a personal value is visible before it is committed; a key that governs what the tool may run — a sandbox tier, an autonomy ceiling, the hooks it executes — is called out on its own, since publishing one machine's relaxed value makes it the team's.\n\n> **Note:** Vibe Code (mistral-vibe) hooks are written to a dedicated `.vibe/hooks.toml` (project) / `~/.vibe/hooks.toml` (global) as a flat `[[hooks]]` TOML array. Each entry carries its own event `type`, a `command`, and optional `name`, `timeout` (seconds, default 60), and `description`. Tool-hook entries (`pre_tool` / `post_tool`) additionally carry a tool-name `match` (an fnmatch glob like `bash`/`mcp_*` or a `re:`-prefixed regex, case-insensitive — the canonical `matcher` field; `*` means \"any tool\") and an optional `strict` flag; `post_agent` carries neither. Three events are supported — `preToolUse` ⇄ `pre_tool`, `postToolUse` ⇄ `post_tool`, and `stop` ⇄ `post_agent` (fires after every assistant turn that ends without pending tool calls). Only `command`-type hooks are emitted. Vibe v2.21.0 graduated hooks from experimental: it renamed all three types (`before_tool` → `pre_tool`, `after_tool` → `post_tool`, `post_agent_turn` → `post_agent`) and removed the `enable_experimental_hooks` flag, so declaring a hook is enough and Rulesync no longer writes an auxiliary `.vibe/config.toml`. `HookType` is a strict enum upstream, so an entry using an old name is rejected outright. Import still reads the three old spellings, so a `hooks.toml` left behind from before the rename is repaired into the current names rather than being lost.\n\n> **Cline note (hooks):** Cline's file-based hooks are executables, not a config file: it resolves one script per lifecycle event from `<project>/.clinerules/hooks/` (project) or `~/Documents/Cline/Hooks/` (global, via `--global`), named exactly after the event — the extensionless name on Unix, `<Event>.ps1` on Windows. Rulesync emits a wrapper script per configured event in **both** spellings (the POSIX one with mode `0755`, since Cline spawns the file itself), plus a `rulesync-hooks.json` manifest listing the scripts it owns. The wrapper feeds the event payload it receives on stdin to each configured command in order and answers on stdout with `{\"cancel\": …, \"contextModification\": \"\", \"errorMessage\": …}`: a command exiting `2` cancels the task, any other non-zero exit is surfaced through `errorMessage` without cancelling. Nine canonical events map onto Cline's fixed script names — `sessionStart` → `TaskStart`, `sessionEnd` → `SessionShutdown`, `beforeSubmitPrompt` → `UserPromptSubmit`, `preToolUse` → `PreToolUse`, `postToolUse` → `PostToolUse`, `preCompact` → `PreCompact`, `notification` → `Notification`, `taskCompleted` → `TaskComplete`, `afterError` → `TaskError`. That set is the union of the two runtimes reading the same directory: the VS Code extension's `VALID_HOOK_TYPES` and the SDK/CLI's `HookConfigFileName`, which drops `Notification` but adds `TaskError` and `SessionShutdown`. A script named for an event the running runtime does not know is simply never spawned. That applies to unknown _names_ only: for an event it does know, the SDK/CLI runtime spawns **both** spellings, because it lists hook files per path rather than per event. Each generated script therefore opens with a guard that stands down on the platform the other one owns — the `.ps1` is a no-op off Windows, and the extensionless script is a no-op on Windows. Both are needed: off Windows the runtime runs the `.ps1` through `pwsh`, and on Windows it infers the extensionless file's interpreter from its `#!/bin/bash` shebang and normalizes it to a bare `bash`, so with Git Bash on `PATH` the two spellings **both execute your commands** — a genuine double fire. (The Unix side was noise rather than duplication: the `.ps1` body shells out through `cmd /c`, which Unix does not have, so it failed on every fire instead.) The PowerShell guard tests that `$IsWindows` is both defined and false, since it does not exist at all in the Windows PowerShell 5.1 that `powershell -File` starts; the POSIX guard matches `$OSTYPE`/`uname` against the `msys`/`cygwin`/`mingw` family. Cline's `TaskResume` and `TaskCancel` have no canonical counterpart and are left unmapped; only `command`-type hooks are supported, and `matcher` is ignored because the wrapper is a plain shell script with no payload parser. Each command is passed to `bash -c` as a single quoted argument, so its own quotes and operators cannot break the wrapper; a command that is not valid shell syntax is reported through `errorMessage` instead of cancelling (an unparseable command would otherwise exit `2`). Note that the same command string runs under `bash` on Unix and `cmd /c` on Windows, so shell-specific syntax is not portable across the two generated spellings. Three caveats on ownership: the hooks directory is also where you hand-author your own hooks and the filenames are fixed by Cline, so every generated script carries a `rulesync-owned: cline-hooks` marker line and a script **without** that marker is never overwritten (that event is then not managed by Rulesync, and generate warns about it); a script whose event you remove is rewritten as a no-op rather than deleted, while dropping the `cline` target with `--delete` removes the marked scripts outright; and `rulesync gitignore` lists the generated script names explicitly rather than the whole directory, so a hand-authored hook sharing one of those names needs a negation in your own `.gitignore` if you want to commit it. Generated scripts cannot be imported back into canonical hooks, so this target is generate-only. Cline's in-process hook surface (`AgentHooks` from `@cline/core`) is a separate mechanism that Rulesync does not target. See [`VALID_HOOK_TYPES`](https://github.com/cline/cline/blob/main/apps/vscode/src/core/hooks/utils.ts) and [`HookConfigFileName`](https://github.com/cline/cline/blob/main/sdk/packages/core/src/hooks/hook-file-config.ts) in the Cline source.\n\n> **Note:** Goose hooks follow the Open Plugins spec: Rulesync writes a plugin directory `hooks/hooks.json` that Goose auto-discovers at startup. Locations are `<project>/.agents/plugins/rulesync/hooks/hooks.json` (project) and `~/.agents/plugins/rulesync/hooks/hooks.json` (global). The JSON shape matches Claude Code's (`{ \"hooks\": { \"EventName\": [ { \"matcher\": \"...\", \"hooks\": [ { \"type\": \"command\", \"command\": \"...\" } ] } ] } }`). Eleven lifecycle events are supported — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `stop` ⇄ `Stop`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `beforeReadFile` ⇄ `BeforeReadFile`, `afterFileEdit` ⇄ `AfterFileEdit`, `beforeShellExecution` ⇄ `BeforeShellExecution`, and `afterShellExecution` ⇄ `AfterShellExecution` — matching Goose's `HookEvent` enum exactly (it has no `SubagentStart`/`SubagentStop`). The `matcher` regex is preserved, commands are emitted verbatim (Goose exposes `PLUGIN_ROOT` as a runtime environment variable), and only `command`-type hooks are supported. One exception applies to the matcher: Goose compiles it with `Regex::new` and **silently drops the whole rule** when compilation fails, and the canonical catch-all `\"*\"` is not a valid regex, so it is emitted as _no_ matcher (which Goose treats as match-all) instead of verbatim.\n\n> **Note:** Qwen Code hooks are written under the top-level `hooks` key of `.qwen/settings.json` (project) / `~/.qwen/settings.json` (global), using Claude-style PascalCase per-matcher arrays (`{ \"EventName\": [ { \"matcher\": \"...\", \"sequential\": false, \"hooks\": [ { \"type\": \"command\", \"command\": \"...\", \"timeout\": ... } ] } ] }`). Qwen's supported event set **differs from Gemini CLI's**, so rulesync defines a Qwen-specific mapping. Twenty-two lifecycle events are supported — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `postToolBatch` ⇄ `PostToolBatch`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `userPromptExpansion` ⇄ `UserPromptExpansion`, `stop` ⇄ `Stop`, `stopFailure` ⇄ `StopFailure`, `subagentStart` ⇄ `SubagentStart`, `subagentStop` ⇄ `SubagentStop`, `preCompact` ⇄ `PreCompact`, `postCompact` ⇄ `PostCompact`, `permissionRequest` ⇄ `PermissionRequest`, `permissionDenied` ⇄ `PermissionDenied`, `notification` ⇄ `Notification`, `instructionsLoaded` ⇄ `InstructionsLoaded`, `todoCreated` ⇄ `TodoCreated`, `todoCompleted` ⇄ `TodoCompleted`, `messageDisplay` ⇄ `MessageDisplay` (fires repeatedly as the reply streams; added in Qwen Code v0.19.10), and `sessionDelete` ⇄ `SessionDelete` (fires after an explicitly selected session is deleted, via the interactive `/delete` command or the ACP `deleteSession` request; matcher-less, added in Qwen Code v0.21.3). Commands are emitted verbatim (no `$GEMINI_PROJECT_DIR` rewriting). Qwen's four hook types are supported: `command`, `prompt` (which carries the required `prompt` body — with `$ARGUMENTS` interpolation — and an optional `model` override, both round-tripped; a prompt hook without a `prompt` is warned about at generate time since Qwen Code loads it and fails it at runtime), `http` (which carries a `url` and POSTs JSON to it; the type and URL round-trip), and `function`. Per-hook fields added in [Qwen Code PR #2827](https://github.com/QwenLM/qwen-code/pull/2827) round-trip as well: command hooks carry `async` (run in the background), `env` (extra subprocess environment variables), and `shell` (`bash`/`powershell`); http hooks carry `headers` (with `${VAR}` interpolation), `allowedEnvVars` (the env-var allowlist), and `once` (single execution per event per session); `statusMessage` (progress text) applies to both. Command-only fields are emitted only on command hooks and http-only fields only on http hooks. The group-level `sequential` flag (parallel by default) and the top-level `disableAllHooks` switch are both round-tripped, and other top-level keys in `settings.json` are preserved. See the [Qwen Code hooks docs](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/hooks.md).\n\n> **Note:** Reasonix hooks are written to a dedicated `.reasonix/settings.json` (project) / `~/.reasonix/settings.json` (global) — a Claude-Code-style but standalone JSON file, separate from the `[permissions]`/`[[plugins]]` TOML config. Unlike Claude Code, each event key maps directly to a **flat array** of hook objects (no `matcher`/`hooks` wrapper): `{ \"EventName\": [ { \"match\": \"...\", \"command\": \"...\", \"description\": \"...\", \"timeout\": ... } ] }`. All ten of Reasonix's documented events are mapped — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `stop` ⇄ `Stop`, `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `subagentStop` ⇄ `SubagentStop`, `postModelInvocation` ⇄ `PostLLMCall`, `notification` ⇄ `Notification`, and `preCompact` ⇄ `PreCompact`. `match` (Reasonix's matcher field name) is honored only on `PreToolUse`/`PostToolUse`; a matcher on any other event is dropped with a warning. The canonical `timeout` field is documented in seconds, while Reasonix's `timeout` is milliseconds, so rulesync converts (`× 1000` on generate, `÷ 1000` on import). Only `command`-type hooks are supported. The `settings.json` file is not documented as holding anything besides hooks today, but rulesync merges non-destructively and never deletes it, in case a future Reasonix version adds other keys. See the [Reasonix Hooks guide](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/DESKTOP_HOOKS.zh-CN.md).\n\n> **Note:** Grok CLI (xAI Grok Build) hooks are written to a dedicated, standalone `rulesync.json` that Grok auto-discovers from `.grok/hooks/*.json` (project) / `~/.grok/hooks/*.json` (global). The JSON shape is Claude-Code-compatible: each event nests under the top-level `hooks` key as a per-matcher array (`{ \"hooks\": { \"EventName\": [ { \"matcher\": \"...\", \"hooks\": [ { \"type\": \"command\", \"command\": \"...\", \"timeout\": ... } ] } ] } }`). All fifteen documented events map 1:1 onto canonical arms — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `permissionDenied` ⇄ `PermissionDenied`, `stop` ⇄ `Stop`, `stopFailure` ⇄ `StopFailure`, `stopCancelled` ⇄ `StopCancelled`, `notification` ⇄ `Notification`, `subagentStart` ⇄ `SubagentStart`, `subagentStop` ⇄ `SubagentStop`, `preCompact` ⇄ `PreCompact`, and `postCompact` ⇄ `PostCompact`. `StopCancelled` runs **instead of** `Stop` when a turn ends without completing — a user interrupt, a declined permission prompt, the `--max-turns` limit, or a no-progress bail-out — so a `stop` hook alone does not cover interrupted turns; it is observation-only and cannot block. A `matcher` (a regex) is honored on every event except `Stop` and `UserPromptSubmit`, which always fire; a matcher on either of those two is dropped with a warning. What the regex tests depends on the event: the tool name on `PreToolUse` / `PostToolUse` / `PostToolUseFailure` / `PermissionDenied`, the notification type on `Notification` (e.g. `idle_prompt`), the subagent type on `SubagentStart` / `SubagentStop` (e.g. `explore`), the start source on `SessionStart`, the end reason on `SessionEnd`, the compaction trigger (`manual` or `auto`) on `PreCompact` / `PostCompact`, the error type on `StopFailure` (`rate_limit`, `authentication_failed`, …), and the cancellation reason on `StopCancelled` (`user_interrupt`, `permission_rejected`, `permission_cancelled`, `max_turns`, `no_progress`, or `unknown`). Earlier Rulesync versions inferred a much narrower set from Claude Code compatibility and dropped the other matchers, so a hook authored that way fired on everything; regenerate to get them back. Commands are emitted verbatim (Grok documents no project-directory variable). See the [Grok hooks docs](https://docs.x.ai/build/features/hooks). Both handler types Grok defines round-trip: a `command` hook runs a command, and an `http` hook POSTs the payload to its `url`. A command hook's `env` map (upstream `HookConfig.env`, merged into the spawned command's `extra_env`) round-trips as well. Note that a `.rulesync/hooks.*` obtained with `rulesync fetch` can therefore point a Grok hook at any URL — read it before generating.\n\n> **Note:** Kimi Code hooks are global-only and written as flat `[[hooks]]` entries in `~/.kimi-code/config.toml`, with `event`, `command`, and optional `matcher`/`timeout`. Rulesync maps fourteen canonical lifecycle events to Kimi's PascalCase names: `sessionStart`, `sessionEnd`, `beforeSubmitPrompt`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `permissionRequest`, `stop`, `stopFailure`, `notification`, `subagentStart`, `subagentStop`, `preCompact`, and `postCompact`. Kimi's native `PermissionResult`, `Interrupt`, `TurnStarted`, `UserPromptQueued`, `TaskStarted`, and `SessionHeartbeat` events have no canonical equivalents, but they can be written and preserved through the `kimi-code.hooks` override under their native names. (`TaskStarted` is deliberately not folded into the canonical `taskCreated`: it fires when a background task starts and matches on task kind, while `taskCreated` models Claude Code's blocking, matcher-less `TaskCreated` fired during task creation.) Only `command` hooks are emitted. A matcher is dropped with a warning on `Stop`, `SessionHeartbeat`, and `Interrupt`, the three events whose Event Reference row documents the matcher as an empty string. Kimi treats `matcher` as a regular expression tested against the event target, so on these events it is tested against `\"\"` and any non-trivial matcher never matches — such a hook silently never ran. Dropping the matcher is therefore a behavior change for existing configs: the hook now fires, which is what authoring it meant. Every other event matches a real value (`UserPromptSubmit` the submitted prompt text, `PermissionRequest` and `PermissionResult` the tool name, `PreCompact` the trigger, and so on), so matchers there are kept. Kimi normally runs these user-level hooks with each current session project as the working directory, which would let an unrelated repository substitute a relative script or influence commands such as `npm test`. Rulesync therefore wraps every generated command so it first changes to the trusted absolute directory containing the source `.rulesync/hooks.jsonc`; relative paths and project-aware commands consistently resolve against that source rather than whichever repository Kimi later opens. Kimi requires `timeout` to be an integer from 1 to 600 seconds; invalid canonical values are omitted with a warning so Kimi can still load the config. The shared TOML file is merged in place and never deleted. See the [Kimi Code hooks docs](https://moonshotai.github.io/kimi-code/en/customization/hooks.html).\n\n## `.github/mcp.json` and `.copilot/mcp-config.json`\n\nExample:\n\n```json\n{\n  \"mcpServers\": {\n    \"serena\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/oraios/serena\", \"serena\", \"start-mcp-server\"]\n    },\n    \"github\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:3000/mcp\"\n    },\n    \"local-dev\": {\n      \"type\": \"local\",\n      \"command\": \"node\",\n      \"args\": [\"scripts/start-local-mcp.js\"]\n    }\n  }\n}\n```\n\nThis file is used by the GitHub Copilot CLI for MCP server configuration. Rulesync manages it by converting from the unified `.rulesync/mcp.jsonc` format. Both scopes use the same `{ \"mcpServers\": {...} }` shape but write to different paths:\n\n- **Project mode:** `.github/mcp.json` (relative to project root) — the Copilot CLI auto-loads MCP servers from this workspace config file ([changelog v1.0.61, 2026-06-09](https://github.com/github/copilot-cli)).\n- **Global mode:** `~/.copilot/mcp-config.json` (relative to home directory) — the personal/global MCP configuration.\n\n> **Migration note:** earlier Rulesync versions wrote the **project-mode** Copilot CLI MCP config to `.copilot/mcp-config.json` (the same path used for global mode). Project mode now writes the dedicated workspace file `.github/mcp.json` instead, so a previously generated project-scope `.copilot/mcp-config.json` is no longer managed and can be removed by hand.\n\nRulesync preserves explicit `type` values for `http`, `sse`, and `local` servers. For command-based servers that omit a transport type, Rulesync emits the mandatory `\"type\": \"stdio\"` field required by the Copilot CLI. `streamable-http` is written as `http`, the transport it names, and the canonical `httpUrl` alias is normalized to the `url` Copilot CLI reads. A server the Copilot CLI config cannot express is skipped with a warning rather than failing the run: one that declares no transport at all (the shape a Kilo `{\"enabled\": …}` toggle imports as, which switches off a server some other config layer defines — every entry here defines a server), one that names a remote transport but no `url`/`httpUrl`, one that names a local transport but no `command`, and a `ws` server, since Copilot CLI has no WebSocket transport.\n\nThe canonical per-server `enabledTools` is written as Copilot CLI's own [`tools` allowlist](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) — `[\"*\"]` (the default) exposes every tool, a list exposes only those names — and imports back as `enabledTools`. A server that already carries a native `tools` value keeps it, and a colliding `enabledTools` is dropped with a warning. `disabledTools` has no counterpart upstream (expressing it would need the server's full tool list), so it is not emitted.\n\n## `rulesync/commands/*.md`\n\nExample:\n\n```md\n---\ndescription: \"Review a pull request\" # command description\ntargets: [\"*\"] # * = all, or specific tools\ncopilot: # copilot specific parameters (optional)\n  description: \"Review a pull request\"\n  agent: \"agent\" # (optional) VS Code prompt-file agent: \"ask\", \"agent\", \"plan\", or a custom agent name (replaces the deprecated \"mode\")\nantigravity: # antigravity specific parameters\n  trigger: \"/review\" # Specific trigger for workflow (renames file to review.md)\n  turbo: true # (Optional, default: true) Append // turbo for auto-execution\ntakt: # takt specific parameters (optional; emitted under .takt/facets/instructions/)\n  name: \"renamed-stem\" # (optional) override the emitted filename stem (no path separators or \"..\")\n  extends: \"base\" # (optional) emit a leading `{extends:<parent>}` facet-inheritance directive (Takt 0.39.0+)\npi: # pi coding agent specific parameters (optional)\n  argument-hint: \"[message]\" # Hint shown in Pi's command palette\ncodexcli: # Codex CLI custom-prompt specific parameters (optional)\n  argument-hint: \"[message]\" # Hint shown for the custom prompt's arguments\nroo: # Roo Code specific parameters (optional)\n  mode: \"architect\" # (optional) mode slug to switch to before running the command body (e.g. \"code\", \"architect\")\n---\n\ntarget_pr = $ARGUMENTS\n\nIf target_pr is not provided, use the PR of the current branch.\n\nExecute the following in parallel:\n\n...\n```\n\nThe command body itself uses a Claude Code-compatible **universal syntax** (e.g. `$ARGUMENTS`, `` !`cmd` ``). When a target tool expects a different placeholder syntax, rulesync translates it automatically on generation and reverses the translation on import. See [Command Syntax](./command-syntax.md) for the full mapping.\n\n> **Codex CLI deprecation note:** Codex CLI's own docs now state \"Custom prompts are deprecated. Use skills for reusable instructions\" (see [Custom Prompts](https://developers.openai.com/codex/custom-prompts)). Rulesync's `codexcli` commands still generate the global-only `~/.codex/prompts/*.md` custom-prompt files described above — they remain functional and no removal date has been announced, so this behavior is unchanged for now. For new reusable instructions, prefer rulesync's `codexcli` skills support (see `.rulesync/skills/*/SKILL.md` below) instead.\n\n> **Warp note:** Warp documents skills as its custom slash-command surface — any skill is invocable as `/{skill-name}` with `$ARGUMENTS` / `$ARGUMENTS[N]` / `$N` argument substitution — so rulesync emits each command onto the native skills surface as `.warp/skills/<name>/SKILL.md` (project) / `~/.warp/skills/<name>/SKILL.md` (global, via `--global`), with `name`/`description` frontmatter derived from the command file. Warp's `.warp/workflows/` YAML files are parameterized shell-command templates, not agent prompts, and are deliberately not used. Commands import and `--delete` are no-ops for `warp` because the skills feature owns the `.warp/skills/` tree (importing it as commands would double-import every skill) — mirrors the Devin note below. Keep command and skill names distinct for this target, since a command and a skill sharing a name write the same `SKILL.md` path. See the [Warp skills docs](https://docs.warp.dev/agent-platform/capabilities/skills/).\n\n> **Devin note:** Devin's extensibility docs no longer document a standalone workflows/commands component — reusable prompts invoked as slash commands are [Skills](https://docs.devin.ai/cli/extensibility/skills/overview) (`/name`). Rulesync therefore emits each command onto the native skills surface as `.devin/skills/<name>/SKILL.md` (project) / `~/.config/devin/skills/<name>/SKILL.md` (global, via `--global`), with `name`/`description` frontmatter derived from the command file. The legacy Windsurf/Cascade-era `.devin/workflows/` and `~/.codeium/windsurf/global_workflows/` locations are no longer emitted (stale outputs there stay gitignored but are not cleaned up automatically). Commands import and `--delete` are no-ops for `devin` because the skills feature owns the `.devin/skills/` tree (importing it as commands would double-import every skill). Note that a command and a skill sharing the same name write the same `SKILL.md` path, so keep command and skill names distinct for this target.\n\n> **Agent Skills standard note (`agentsskills`):** Rulesync accepts the legacy rulesync spellings on input but always **emits** the shapes the [specification](https://agentskills.io/specification) requires: `allowed-tools` becomes a space-separated scalar (a YAML list is joined), `compatibility` becomes a string (an object is flattened to `key: value` pairs), and `metadata` values are stringified so the block stays a string→string map. Generation also checks the normative constraints and warns — without failing the run — when `name` is empty, longer than 64 characters, contains anything but lowercase letters, digits and single hyphens, or does not match its parent directory name; when `description` is empty or longer than 1024 characters; when `compatibility` exceeds 500 characters; or when an `allowed-tools` list entry contains whitespace, which the space-separated form cannot represent. These are warnings rather than errors because a conformant client only _skips_ such a skill, and because import stays lenient as the [client-implementation guide](https://agentskills.io/client-implementation/adding-skills-support) advises. **Import** reports the same empty-`description` violation, for the one reason it matters on that side too: a conformant client would skip the skill, so a user who is never told has no reason to fix it. Rulesync converts rather than loads, so the skill is imported all the same — dropping the directory would lose content that is still repairable. `hermesagent` reads the same shape and reports it identically. A value that normalizes to the empty string (`compatibility: {}`, `allowed-tools: []`) is dropped rather than written, since the spec requires `compatibility` to be 1–500 characters when present. On **import**, `allowed-tools` is normalized back to the canonical rulesync list, so a generate → import round trip leaves `.rulesync/skills/**` in the shape it started in (the `compatibility` and `metadata` coercions are one-way, because the legacy object/number forms have no conformant equivalent). `hermesagent` reads the same `agentsskills` block and applies the same normalization in both directions, so one rulesync source never produces two different on-disk spellings — except for `metadata`, which stays structured there because Hermes reads `metadata.hermes.*` as YAML. A `hermesagent:` override still wins over the shared block (as for every tool-specific section), so a list or mapping written there is emitted as-is and reported as a spec violation rather than rewritten. Validate the result with the spec's own [`skills-ref validate`](https://github.com/agentskills/agentskills/tree/main/skills-ref). Import leniency is root-based as well as tool-based: any tool scanning an Agent Skills interop root (project `.agents/skills/`, global `~/.agents/skills/`, or Amp's `~/.config/agents/skills/`) skips-and-warns on a skill (directory-form or flat-file) that fails to load there — the cross-vendor directory is where foreign-authored, potentially non-conformant skills live — while each tool's own native root (e.g. Rovo Dev's `.rovodev/skills/`) stays fail-fast.\n\n> **Malformed frontmatter note:** a `SKILL.md` whose YAML fails to parse is retried once with its top-level unquoted values quoted, which recovers the case the Agent Skills [client-implementation guide](https://agentskills.io/client-implementation/adding-skills-support) names — `description: Use this skill when: the user asks about PDFs`, where the second colon ends the scalar. The retry rewrites only top-level `key: value` lines whose value contains a colon followed by whitespace, so a URL (`homepage: https://example.com`) and anything already quoted, a flow collection or a block scalar are left alone. An inline comment is cut off before the value is examined, so `allowed-tools: Read # TODO: add Bash later` is neither rewritten nor turned into a value that grants what the comment had disabled; a file the retry cannot fix still fails with the error it actually has. Recovery is reported with a warning: fix the file itself, since other tools read it with their own parsers.\n\n> **Replit note:** Replit's skills page states conformance to the [Agent Skills specification](https://agentskills.io/specification), so `replit.allowed-tools` accepts either the spec's space-separated string or a canonical rulesync list and is always **emitted** as the string; `replit.compatibility` likewise accepts the spec's string alongside the legacy object form. On import, `allowed-tools` is normalized back to the list, mirroring `deepagents` — so keep list entries free of whitespace, since the space-separated form cannot represent an entry such as `Bash(git commit:*)` and a client would read it back as two. An object `compatibility` is emitted unchanged rather than flattened: unlike the join, that conversion would be one-way, so the legacy form stays as-is and is simply not spec-conformant on disk.\n\n> **Junie skills note:** Junie treats `description` as **optional** in a skill's `SKILL.md` — \"If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content as the description.\" Rulesync's canonical frontmatter requires one, so on **import** a missing `description` is filled in the same way, from the first body paragraph (wrapped lines joined into a single line, since it becomes a YAML scalar); a `SKILL.md` Junie loads fine therefore no longer aborts the import. **Markdown headings are skipped**, matching upstream's \"If the body is also empty or contains only headings, the skill will fail to load\" — so a body opening with `# Skill Name` yields the prose beneath it, not the title. That matters beyond the import: an imported description is written back out explicitly on the next generate, so importing the title would replace Junie's own correct fallback with it, for every tool. A fenced code block is **not** special-cased — it is ordinary content, so a body whose first non-heading paragraph is a fence yields the fence text, which is a good reason to author a `description` explicitly. When nothing remains (an empty or headings-only body), Junie could not load the skill either, so Rulesync skips **that one skill** with a warning and keeps importing the rest. Generation always writes an explicit `description`, which Junie's own docs recommend. Junie also loads skills from the shared Agent Skills root — `<projectRoot>/.agents/skills/` and `~/.agents/skills/` — so Rulesync registers it as an import fallback at either scope; it is import-only (the `agentsskills` target owns writing there) and is never removed by Junie-target orphan deletion. When the same skill name exists in both roots, the Junie-specific `.junie/skills/` root takes precedence — Junie's own docs are silent on that ordering, so this matches how Rulesync already resolves the shared root for `kimi-code`. Names are compared case-insensitively there too, so `.agents/skills/My-Skill` does not shadow `.junie/skills/my-skill`; see the cross-root duplicate note under [`.rulesync/skills/*/SKILL.md`](#rulesyncskillsskillmd). Junie's third skill source — the custom folders added with `--skill-location` or the `skill-locations` key of its `config.json` — is out of scope for the `junie` target: Rulesync neither reads nor writes those paths, so a skill kept only there stays invisible to `rulesync import`. See the [agent skills docs](https://junie.jetbrains.com/docs/agent-skills.html).\n\n> **Vibe skills note:** Vibe discovers skills under `.vibe/skills/` (project) and `~/.vibe/skills/` (global), plus the shared `.agents/skills/` root at **both** scopes — Vibe's `user_skills_dirs` returns `~/.vibe/skills` and `~/.agents/skills` alike. Rulesync registers the shared root as an import fallback at either scope; it is import-only and is never removed by Vibe-target orphan deletion. When the same skill name exists in both roots the Vibe-specific root takes precedence, compared case-insensitively; see the cross-root duplicate note under [`.rulesync/skills/*/SKILL.md`](#rulesyncskillsskillmd).\n\n> **Pi skills note:** Pi implements the [Agent Skills specification](https://agentskills.io/specification), so `pi.allowed-tools` accepts either the spec's space-delimited string or a canonical rulesync list and is always **emitted** as the string; `pi.compatibility` likewise accepts the spec's string alongside the legacy object form. Importing a spec-conformant `SKILL.md` used to fail outright. On import, `allowed-tools` is normalized back to the list, mirroring `deepagents`; keep list entries free of whitespace, since the space-delimited form cannot represent an entry such as `Bash(git commit:*)`. An `allowed-tools` value that normalizes to the empty string (an empty list) is dropped rather than written. An object `compatibility` is emitted unchanged rather than flattened, because that conversion would be one-way.\n\n> **Hermes Agent note:** Commands are global-only and remain distinct from skills. Rulesync writes JSON command specs to `~/.hermes/rulesync/commands/<name>.json`, installs the `rulesync-commands` plugin under `~/.hermes/plugins/`, and enables it in `~/.hermes/config.yaml`. The plugin registers each spec with Hermes's [`ctx.register_command()` plugin API](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins/) and dispatches the prompt through `delegate_task`; invocation arguments are appended to the prompt. `.rulesync/skills/<name>/SKILL.md` still generates a full [Hermes Agent Skill](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/) under `~/.hermes/skills/<name>/SKILL.md`, which Hermes also exposes as a dynamic slash command. Rulesync rejects command/skill names that would collide in Hermes's slash-command namespace, and rejects nested command paths that flatten to the same name. Generate commands with `rulesync generate --targets hermesagent --features commands --global`.\n>\n> Releases before this native plugin transport emitted Hermes commands as `~/.hermes/skills/<name>/SKILL.md`. Rulesync cannot distinguish those files from real user-authored skills safely, so remove an obsolete legacy file manually after confirming that `.rulesync/skills/<name>/SKILL.md` does not own it.\n\n> **Qwen Code note:** Custom commands are emitted as **Markdown** files (not TOML — TOML is deprecated upstream) under `.qwen/commands/` (project) and `~/.qwen/commands/` (global, via `--global`). The file is an optional YAML frontmatter block followed by the prompt body; besides `description`, Qwen Code's command loader reads `when_to_use` (invocation guidance), `argument-hint` (completion hint), and `disable-model-invocation`, all typed and round-tripped. Subdirectory namespacing is supported: `.qwen/commands/git/commit.md` becomes the `/git:commit` command. Any extra fields are preserved on round-trip under the `qwencode:` block.\n\n> **OpenCode import note:** OpenCode lets commands live both as Markdown files under `.opencode/commands/*.md` **and** inline in `opencode.json`/`opencode.jsonc` under the top-level `command` key. On import, rulesync reads both: each inline entry's `template` becomes the command body and its `description`/`agent`/`model`/`subtask` fields become frontmatter. A Markdown file takes precedence over an inline entry with the same name.\n\n> **AugmentCode note:** Commands are written to `.augment/commands/<name>.md` (project) / `~/.augment/commands/<name>.md` (global, via `--global`). Subdirectories are namespaces — `.augment/commands/git/commit.md` is `/git:commit` — so nested rulesync commands keep their nesting rather than being flattened to a basename. If you generated AugmentCode commands with an earlier Rulesync, the flattened files it wrote are still on disk under their old names; `--delete` removes them. Auggie also discovers commands under the cross-tool `.agents/commands/` root, so **import** reads that root too and treats a command found there as if it lived under `.augment/commands/` — the command's name is its path under whichever root it came from. Generation stays on `.augment/commands/`, and `.agents/commands/` is never written to or swept for orphans, since the files there may belong to another tool — Rulesync itself writes that root for the `agentsmd` target, so a command already imported from `.augment/commands/` is not imported again from there under a flattened name. Auggie's other shared root, `.claude/commands/`, is deliberately not read: it is Claude Code's own output, which Rulesync already imports as that target. Importing from a shared root is announced, because the result is a Rulesync command written for every target on the next generate. See the [custom commands docs](https://docs.augmentcode.com/cli/custom-commands).\n\n> **Reasonix note:** Custom slash commands are Markdown files under `.reasonix/commands/` (project) / `~/.reasonix/commands/` (global, via `--global`) — directly analogous to Claude Code's `.claude/commands/`, since Reasonix explicitly mirrors Claude Code's conventions. Frontmatter supports `description` and `argument-hint`, and the body uses the same `$ARGUMENTS` / `$1`…`$N` placeholder syntax. Subdirectory namespacing is supported (`git/commit.md` → `/git:commit`). Any extra fields are preserved on round-trip under the `reasonix:` block. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md#slash-commands).\n\n> **Grok CLI note:** Custom slash commands are Markdown files under `.grok/commands/` (project) / `~/.grok/commands/` (global, via `--global`), read by the same Claude-Code-compatible frontmatter parser Grok uses for skills. Rulesync emits `description` plus, from the `grokcli:` block, `argument-hint`, `user-invocable` (default true) and `disable-model-invocation` (default false) — the same invocation-control pair Grok skills honor. Two upstream constraints are worth knowing. Grok's command scan is **flat and non-recursive**, so subdirectory namespacing is not supported: a nested `git/commit.md` is flattened onto `commit.md`, and two nested commands with the same basename collide (rulesync warns and the last one wins). And Grok collects skills before commands, letting **skills win name collisions** — a `.grok/skills/<name>/` shadows `.grok/commands/<name>.md`, so avoid giving a rulesync skill and a rulesync command the same name when targeting Grok. Any extra frontmatter keys are preserved on round-trip under the `grokcli:` block. See the [skills, plugins and marketplaces docs](https://docs.x.ai/build/features/skills-plugins-marketplaces).\n\n> **Rovo Dev CLI note:** Rovo Dev's \"saved prompts\" are a file-based custom-command surface made of a `prompts.yml` manifest plus per-prompt Markdown content files, invoked via `/prompts [title] [extra]`. Rulesync writes the content (no frontmatter) to `.rovodev/prompts/<name>.md` (project) / `~/.rovodev/prompts/<name>.md` (global, via `--global`), and rebuilds the sibling `.rovodev/prompts.yml` / `~/.rovodev/prompts.yml` manifest with one `{ name, description, content_file }` entry per prompt, `content_file` pointing at `prompts/<name>.md` (resolved relative to `prompts.yml`, matching Rovo Dev's own resolution order). The `prompts` array is fully replaced from the current rulesync commands on each generate (mirrors the Rovodev MCP adapter fully replacing `mcpServers`); any other top-level key in an existing manifest is preserved, and the manifest is never deleted. See the [saved prompts](https://support.atlassian.com/rovo/docs/save-and-reuse-a-prompt-in-rovo-dev-cli/) and [CLI commands](https://support.atlassian.com/rovo/docs/rovo-dev-cli-commands/) docs.\n\n> **ZCode note:** Custom commands are Markdown files under `.zcode/commands/` (project) / `~/.zcode/commands/` (global, via `--global`), invoked from the input box with `/`. Only the global path is spelled out in ZCode's docs, which describe the workspace scope as \"workspace-level commands live in the project directory\"; the `.zcode/commands/` project path is rulesync's inference from that sentence and from the layout ZCode uses for its other workspace assets, not a documented path. The file name is the command's identifier, and the frontmatter carries the `description` shown in the command picker plus an `argument-hint`. ZCode's command scan is flat, so subdirectory namespacing is not modeled. Any extra frontmatter fields are preserved on round-trip under the `zcode:` block. See the [ZCode commands docs](https://zcode.z.ai/en/docs/commands).\n\n## `rulesync/subagents/*.md`\n\nExample:\n\n```md\n---\nname: planner # subagent name\ntargets: [\"*\"] # * = all, or specific tools\ndescription: >- # subagent description\n  This is the general-purpose planner. The user asks the agent to plan to\n  suggest a specification, implement a new feature, refactor the codebase, or\n  fix a bug. This agent can be called by the user explicitly only.\nclaudecode: # for claudecode-specific parameters\n  model: inherit # opus, sonnet, haiku, fable, a full model id, or inherit (default)\n  tools: [\"Read\", \"Write\"] # (optional) allowed tools (string or list)\n  disallowedTools: [\"Bash\"] # (optional) tools to remove (string or list)\n  permissionMode: default # (optional) default | acceptEdits | bypassPermissions | plan\n  maxTurns: 20 # (optional) maximum agentic turns\n  skills: [\"skill-creator\"] # (optional) Agent Skills to utilize (string or list)\n  color: cyan # (optional) UI color (e.g. red, blue, green, cyan, ...)\n  memory: project # (optional) user | project | local\n  effort: high # (optional) low | medium | high | xhigh | max\n  isolation: worktree # (optional) run the subagent in an isolated git worktree\n  background: false # (optional) run the subagent in the background\n  initialPrompt: \"Start by reading the spec.\" # (optional) seed prompt for the subagent\n  mcpServers: {} # (optional) MCP server config (passed through verbatim)\n  hooks: {} # (optional) hook config (passed through verbatim)\ncopilot: # for GitHub Copilot specific parameters\n  tools:\n    # Listed tools are emitted verbatim; omit `tools` entirely to grant the agent\n    # all tools. `agent/runSubagent` is opt-in — add it explicitly only when this\n    # subagent needs to orchestrate other subagents.\n    - web/fetch\n    - agent/runSubagent\nopencode: # for OpenCode-specific parameters\n  mode: subagent # (optional, defaults to \"subagent\") OpenCode agent mode\n  model: anthropic/claude-sonnet-4-20250514\n  temperature: 0.1\n  tools:\n    write: false\n    edit: false\n    bash: false\n  permission:\n    bash:\n      \"git diff\": allow\nkilo: # for Kilo-specific parameters\n  mode: all # (optional, defaults to \"all\") use \"subagent\" for hidden/subagent-only agents\ncursor: # for Cursor-specific parameters (generated to .cursor/agents/*.md)\n  model: inherit # (optional, defaults to \"inherit\") model id, or \"inherit\" to use the parent's model\n  readonly: false # (optional, defaults to false) restrict the subagent to read-only tools\n  is_background: false # (optional, defaults to false) run the subagent as a background agent\njunie: # for JetBrains Junie CLI specific parameters (generated to .junie/agents/*.md; also imported from .agents/*.md)\n  tools: [\"Read\", \"Grep\", \"Edit\"] # allowed tools\n  disallowedTools: [\"Bash\", \"WebSearch\"] # disallowed tools\n  mcpServers: [\"github\"] # MCP servers the subagent may use\n  model: sonnet # model id\n  permissionMode: acceptEdits # (optional, defaults to \"default\") default | acceptEdits | dontAsk | bypassPermissions | plan\n  reasoningLevel: high # low | medium | high\n  maxTurns: 20 # max agentic turns\n  skills: [\"kotlin\", \"writerside\"] # Agent Skills to utilize\n  allowPromptArgument: true # whether the subagent accepts a prompt argument\ntakt: # takt specific parameters (optional; emitted under .takt/facets/personas/)\n  name: \"renamed-stem\" # (optional) override the emitted filename stem (no path separators or \"..\")\nroo: # for Roo Code specific parameters (optional; aggregated into the root .roomodes file)\n  slug: planner # (optional) custom mode slug (^[a-zA-Z0-9-]+$); defaults to the sanitized file name\n  whenToUse: \"When planning a task\" # (optional) guidance for automated mode selection\n  customInstructions: \"Be concise.\" # (optional) extra behavioral guidelines\n  roleDefinition: \"You are the planner.\" # (optional) overrides the body as the mode's roleDefinition\n  groups: # (optional, defaults to [\"read\", \"edit\", \"command\", \"mcp\"]) tool access\n    - read\n    - [\"edit\", { fileRegex: \"\\\\.md$\", description: \"Markdown files\" }]\n---\n\nYou are the planner for any tasks.\n\nBased on the user's instruction, create a plan while analyzing the related files. Then, report the plan in detail. You can output files to @tmp/ if needed.\n\nAttention, again, you are just the planner, so though you can read any files and run any commands for analysis, please don't write any code.\n```\n\n> **Antigravity note:** Antigravity custom agents (CLI v1.1.6+, shared by the IDE and the CLI) are emitted as Markdown + YAML frontmatter to `.agents/agents/<name>.md` (project) and `~/.gemini/config/agents/<name>.md` (global, via `--global`); the body after the frontmatter is the agent's system prompt. Both `antigravity-ide` and `antigravity-cli` read the same two locations, so enabling both writes the same file — the same way they already share `.agents/hooks.json`. Antigravity also accepts a directory form (`<name>/agent.md`); Rulesync emits and imports the flat file form only. `name` and `description` are **required** upstream, so a canonical subagent without a description gets a minimal generated fallback rather than a file Antigravity refuses to load. Because the two share that file, every Antigravity target reads the `antigravity-ide` and `antigravity-cli` blocks merged in a fixed order (the CLI block wins) — the same rule the MCP feature uses for the same shared-output reason — so generation order never changes the file's content; the `antigravity-plugin` block is layered on top for the plugin bundle only. Besides the shared `name`/`description`, those blocks accept these optional fields (all preserved on round-trip): `tools` (string list), `mainAgent` (boolean, default `true`), `subagent` (boolean, default `true`), `model` (`inherit` | `flash` | `pro`), `commandExecutionPolicy` (`off` | `auto` | `eager` | `sandbox`), `mcpServers`, `skills`, and `plugins`. `hidden` and `inheritMcp` appear in the v1.1.6 release notes but not in the documented frontmatter table, so they pass through verbatim with no behavior modeled around them; the schema is loose, so any extra keys survive the round-trip too. The `antigravity-plugin` target writes the same file format into a plugin bundle's `agents/` directory (project scope only). See the [Antigravity subagents docs](https://antigravity.google/docs/subagents) and the [plugin bundle layout](https://antigravity.google/docs/cli/plugins).\n\n> **`.agents/agents/` ownership note (`agentsmd`):** `.agents/agents/` is not an AGENTS.md convention — the AGENTS.md standard defines only `AGENTS.md` itself. It is the cross-vendor location AGENTS.md-era clients actually scan for agent definitions: both Antigravity targets generate into it, and Kimi Code reads it alongside its own agents directory. The **simulated** `agentsmd` subagent writer therefore emits there too, and because it has no frontmatter model of its own it emits exactly what the Antigravity targets emit — same merged `antigravity-ide` → `antigravity-cli` blocks, same serialization — so a simulated writer can never degrade the file a native target owns. Earlier Rulesync versions wrote these files to `.agents/subagents/`, a directory no documented client reads; they are no longer generated there (stale outputs stay gitignored but are not cleaned up automatically), so move or delete anything you hand-authored under the old path. Note that, unlike the shared root Kimi Code reads (which is import-only for that target), `.agents/agents/` is a **generated** path for `agentsmd` and the Antigravity targets, so `generate --delete` sweeps orphans there: a hand-authored agent in that directory that no `.rulesync/subagents/*.md` produces is removed. Import it first if you want to keep it. A subagent pinned to one writer of this directory (`targets: [\"antigravity-cli\"]`, say) survives a run that includes the other writers: `generate` claims every path the run writes, across all the targets it runs, and holds the orphan sweep back until the last of them has written, so no writer of a shared directory treats a sibling's output as a leftover. Narrowing `--targets` narrows that claim set, though — a later `generate --targets antigravity-ide --delete` knows nothing about the `antigravity-cli`-pinned file and sweeps it — so generate the writers of a shared directory together. Because the file is shared, an `agentsmd`-only generate still emits the Antigravity blocks (`tools`, `model`, `commandExecutionPolicy`, `mcpServers`, …) verbatim: writing a reduced file would be exactly the silent degradation this shared-path arrangement exists to prevent. That is a deliberate trade-off — a subagent pulled in from someone else's repository with `rulesync fetch` becomes a live, executable agent definition as soon as any target that writes this path runs, so review `.rulesync/subagents/*.md` after fetching, exactly as you would review any other fetched configuration before generating.\n\n> **Qwen Code note:** Subagents are emitted as Markdown + YAML frontmatter under `.qwen/agents/` (project) and `~/.qwen/agents/` (user/global, via `--global`); the body is the subagent's system prompt. Besides the shared `name`/`description`, the `qwencode:` block accepts these optional fields (all preserved on round-trip): `model`, `approvalMode` (`default` | `plan` | `auto-edit` | `yolo` | `bubble`), `tools` (allowlist), `disallowedTools` (denylist), `maxTurns`, `color`, `mcpServers` (per-agent MCP overrides — accepts both a record of server specs, matching Qwen's documented shape, and a plain array of server names), and `hooks` (per-agent hook registrations). See the [Qwen Code sub-agents docs](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/sub-agents.md).\n\n> **Kimi Code note:** Subagents are emitted as Markdown files under `.kimi-code/agents/` (project) and `~/.kimi-code/agents/` (global). The shared `name` and required `description` fields are written to YAML frontmatter; Kimi-specific `whenToUse`, `override`, `tools`, `disallowedTools`, and `subagents` fields can be authored under the `kimi-code:` block and round-trip unchanged. Kimi recursively scans both its Kimi-specific agents directory and the shared `.agents/agents/` directory, so Rulesync imports nested Markdown files from both locations and flattens them into `.rulesync/subagents/<name>.md` using the validated kebab-case agent name. The Kimi-specific root has precedence over `.agents/agents/`; if multiple source files resolve to the same logical agent name, the first one wins and Rulesync warns about the duplicate. The shared root is import-only and is never removed by Kimi-target orphan deletion. See the [Kimi Code custom-agents docs](https://moonshotai.github.io/kimi-code/en/customization/agents.html).\n\n> **Kiro CLI note:** Subagents are emitted as JSON agent configurations under `.kiro/agents/` (project) and `~/.kiro/agents/` (global). Kiro allows the JSON `name` field to be omitted, in which case the filename stem is the agent name; Rulesync accepts that form on import and writes the derived name into the Rulesync frontmatter. Imports through the `kiro-cli` target retain `targets: [\"kiro-cli\"]`, so they can be generated back to the same target without changing the target metadata.\n\n> **Cline note:** Cline file-based agents are emitted as YAML files (`<name>.yaml`) into `.cline/agents/` (project) and `~/.cline/agents/` (global, via `--global`). The file is a YAML frontmatter block followed by the system prompt body, matching Cline's agent config loader: `name` and `description` are **required** (Cline cli-v3.0.23+ refuses to load an agent whose `description` is missing or empty — a canonical subagent without one gets a minimal generated fallback rather than a file Cline cannot load), and the typed optional fields `tools`, `skills`, `providerId`, `modelId`, and `maxIterations` round-trip through the `cline:` section. Import reads `.yml` alongside `.yaml`, matching Cline's `isYamlFile()`.\n\n> **Devin note:** Devin Local custom subagent profiles are emitted as `AGENT.md` files in a **directory-per-agent** layout: `.devin/agents/<name>/AGENT.md` (project) and `~/.config/devin/agents/<name>/AGENT.md` (global, via `--global`). The directory name `<name>` is the profile id (derived from the rulesync subagent file name). The `AGENT.md` is a YAML frontmatter block followed by the subagent's system prompt. Besides the shared `name`/`description`, the `devin` subagent block accepts these optional fields (all preserved on round-trip): `model` (string, override the subagent LLM), `allowed-tools` (list of strings, restrict available tools), `permissions` (object with `allow`/`deny`/`ask` string lists, override tool permissions), and `max-nesting` (integer, enable nested subagent spawning up to the given depth). See the [Devin subagents docs](https://docs.devin.ai/cli/subagents).\n\n> **Reasonix note:** Reasonix native subagents are Skill profiles emitted as `SKILL.md` files in a **directory-per-agent** layout: `.reasonix/skills/<name>/SKILL.md` (project) and `~/.reasonix/skills/<name>/SKILL.md` (global, via `--global`). The directory name `<name>` is the profile id (derived from the rulesync subagent file name). A subagent is a Skill whose YAML frontmatter declares `invocation: manual` and `runAs: subagent` — Rulesync always injects both markers so the SKILL.md is recognized as a manually invoked subagent rather than an auto-discovered skill. Besides the shared `name`/`description`, the `reasonix` subagent block accepts these optional fields (all preserved on round-trip): `model` (string, subagent LLM), `effort` (string, reasoning effort), `allowed-tools` (list of strings, restrict available tools), and `color` (string, display color). The schema is loose, so any extra keys survive the round-trip. See the [Reasonix subagent profiles docs](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SUBAGENT_PROFILES.md).\n\n> **Roo / Zoo Code mode-specific rules note:** Both tools load `.roo/rules-{mode}/` (global `~/.roo/rules-{mode}/`) **instead of** the mode-agnostic `.roo/rules/` while that custom mode is active. Set a `roo:` frontmatter section with `mode: architect` on a rule to route it there; the section is shared by the `roo` and `zoocode` targets, which write the same `.roo/` tree. The slug must match `^[a-zA-Z0-9-]+$` (the alphabet the tools themselves accept) — anything else is ignored with a warning and the rule lands in `.roo/rules/`, rather than interpolating an arbitrary string into a directory name. The key is ignored on the `root: true` rule, which has no mode-specific counterpart. On import, a file under a mode directory comes back as `.rulesync/rules/{name}-{mode}.md` carrying `roo.mode`, suffixed so it cannot collide with a same-named generic rule (an already-suffixed name is left alone, so repeated generate/import cycles converge) and targeted at the importing tool alone, since a wildcard would make every other target emit a mode-scoped rule as an always-on one; mode-directory import is project scope only. Note that mode directories are **not swept by orphan deletion** — `generate --delete` only clears `.roo/rules/` — because a `rules-*` glob would also match mode rules you wrote by hand, so a file left behind by a removed rule has to be deleted yourself. Mode-specific _skills_ need no directory support: Zoo Code reads `modeSlugs` from a skill's own frontmatter at higher priority than the directory it sits in, so the existing `roo: modeSlugs` frontmatter already scopes a skill in `.roo/skills/` to a mode.\n\n> **Roo skills/commands note (final v3.54.0 state — Roo Code is EOL and its repository archived):** Commands are generated to `.roo/commands/` (project) and `~/.roo/commands/` (global, via `--global`; project wins on a name collision). Skill frontmatter beyond `name`/`description` — most usefully `modeSlugs: string[]` for mode targeting — is authored via the `roo:` section of `.rulesync/skills/*/SKILL.md` and lifted back into it on import, so it survives the round-trip. A localRoot rule is emitted as `AGENTS.local.md`, the personal, gitignored override file Roo loads alongside `AGENTS.md`.\n\n> **Zoo Code note:** Zoo Code ([Zoo-Code-Org/Zoo-Code](https://github.com/Zoo-Code-Org/Zoo-Code)) is the community continuation of the archived Roo Code, named by the Roo shutdown notice and continuing Roo's release numbering (v3.54.0 → v3.72.0 as of 2026-07-25). It still resolves `~/.roo` and the project `.roo/` layout — the `.zoo` renaming is confined to provider/auth code — so the `zoocode` target reuses the `roo` adapters' path model verbatim across rules (including `AGENTS.local.md` local-root handling), ignore (`.rooignore`), MCP (`.roo/mcp.json`), commands (`.roo/commands/`), skills (`.roo/skills/`, `roo:` frontmatter section), and subagents (the aggregated `.roomodes` file). Shared mode/skill fields keep riding the `roo:` frontmatter sections, so one rulesync source never produces two spellings; targeting both `roo` and `zoocode` writes the same files, so pick one target per project — and note the fail-open hazard the shared `.roomodes` creates: a `--targets roo` generate rewrites it **without** `allowedMcpServers`, so opening that workspace in Zoo Code makes every MCP server available to the mode. The post-fork divergence is carried by the `zoocode:` subagent section: `allowedMcpServers` (Zoo Code v3.60.0+), a per-mode MCP server allowlist (\"when omitted, all servers are available; when set, only the listed servers are injected\"), emitted into the mode and lifted back into `zoocode:` on import. See the [Zoo Code docs](https://docs.zoocode.dev/features/custom-modes).\n\n> **Vibe note:** Vibe agent profiles are emitted as TOML to `.vibe/agents/<name>.toml` (project) and `~/.vibe/agents/<name>.toml` (global, via `--global`). The subagent body is **not** written into the profile: Vibe's settable field is `system_prompt_id`, while `system_prompt` is a read-only property on its config schema and unknown TOML keys are ignored rather than rejected — so a profile carrying `system_prompt` loads fine and silently runs with the **default** system prompt. Rulesync therefore writes the body to `.vibe/prompts/<name>.md` and sets `system_prompt_id = \"<name>\"`, the same mechanism Vibe's own builtin profiles use (`EXPLORE` sets `\"system_prompt_id\": \"explore\"`). The two files are always written together, because `VibeConfigSchema._check_system_prompt` evaluates the id during validation and an unresolvable one makes `AgentRegistry._try_load` drop the agent with a warning. On import, `system_prompt_id` is resolved against `.vibe/prompts/` and becomes the canonical body; a legacy `system_prompt` is still read, and an id that resolves to nothing is preserved in the `vibe:` block so a hand-maintained prompt file keeps working. A subagent with an empty body writes no prompt file and leaves any `system_prompt_id` you authored alone. Note that `.vibe/prompts/` is not swept by orphan deletion — `generate --delete` only clears `.vibe/agents/` — so a prompt file left behind by a removed subagent has to be deleted by hand.\n\n> **Roo note (as of 2026-06-16):** Roo Code reads project custom modes from a single aggregated `.roomodes` file at the workspace root (YAML; JSON also accepted). Rulesync therefore collapses every Roo-targeted subagent into that file's `customModes` array — each subagent becomes one mode whose `slug` is derived from the file name (sanitized to `^[a-zA-Z0-9-]+$`), `name`/`description` come from the shared frontmatter, and `roleDefinition` is the subagent body. The optional `roo:` block supplies `groups` (defaults to `[\"read\", \"edit\", \"command\", \"mcp\"]`), `whenToUse`, `customInstructions`, an explicit `slug`, and a `roleDefinition` override. (Roo's previous `.roo/subagents/` output was inert — Roo Code never read it.) See the [Roo custom-modes docs](https://roocodeinc.github.io/Roo-Code/features/custom-modes).\n\n> **OpenCode import note:** OpenCode lets agents live both as Markdown files under `.opencode/agents/*.md` **and** inline in `opencode.json`/`opencode.jsonc` under the top-level `agent` key. On import, rulesync reads both: each inline entry's `prompt` becomes the subagent body (a `\"{file:./path}\"` reference is resolved relative to the config file's location, as OpenCode does), and the remaining fields (`description`/`mode`/`model`/`tools`/`permission`/...) become frontmatter under the `opencode:` block. A Markdown file takes precedence over an inline entry with the same name, compared case-insensitively — `.opencode/agents/planner.md` and an inline `Planner` are one `.rulesync/subagents/` file on macOS and Windows, so the inline copy is dropped with a warning rather than silently overwriting the file (two inline entries differing only in case resolve the same way, keeping the earlier one).\n\n> **Kilo note (as of 2026-05-13):** Kilo's documented default for user-defined agents is `mode: all`, which makes the agent available both as a top-level pick and as a subagent. Set `kilo.mode: subagent` to opt into hidden/subagent-only behavior.\n\nBesides `mode`, the `kilo` subagent block accepts these optional fields (all preserved on round-trip):\n\n| Field         | Type             | Notes                                                                                                                                                                                                                                                            |\n| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `displayName` | string           | Human-friendly name shown in pickers                                                                                                                                                                                                                             |\n| `model`       | string           | Model id                                                                                                                                                                                                                                                         |\n| `variant`     | string           | Model variant                                                                                                                                                                                                                                                    |\n| `temperature` | number           | Sampling temperature                                                                                                                                                                                                                                             |\n| `top_p`       | number           | Nucleus-sampling parameter                                                                                                                                                                                                                                       |\n| `permission`  | string \\| object | Permission profile name, or a per-tool `{ <tool>: { allow, deny, ask } }` object                                                                                                                                                                                 |\n| `prompt`      | string           | Inline system prompt                                                                                                                                                                                                                                             |\n| `color`       | string           | UI color                                                                                                                                                                                                                                                         |\n| `native`      | boolean          | Native (built-in) agent flag                                                                                                                                                                                                                                     |\n| `hidden`      | boolean          | Hide from top-level picker                                                                                                                                                                                                                                       |\n| `disable`     | boolean          | Disable the agent                                                                                                                                                                                                                                                |\n| `deprecated`  | boolean          | Mark as deprecated                                                                                                                                                                                                                                               |\n| `steps`       | positive integer | Maximum agentic iterations before a text-only response is forced (an explicit `null` is accepted and round-trips as-is, so a file that already carries one still imports; earlier Rulesync versions took a list of step objects here, which Kilo never accepted) |\n| `options`     | object           | Free-form key/value options                                                                                                                                                                                                                                      |\n\n> **Migration note (`steps`):** earlier Rulesync versions typed `steps` as a list of step objects, which Kilo never accepted — a subagent authored that way produced a file Kilo ignored. It is now the iteration count Kilo documents, so a `kilo` block (or a `.kilo/agents/*.md` file) still carrying the list form fails validation with the offending file named, and the run stops rather than writing a file that would not work. Replace the list with the number of iterations you want, or drop the field.\n\n> **Hermes Agent note:** Project generation writes subagent JSON specs under `.hermes/rulesync/subagents/` and installs `.hermes/plugins/rulesync-subagents/`. The plugin resolves specs relative to its own installation, so the same code works in project and global scope. For project scope, Rulesync also enables `rulesync-subagents` in `$HERMES_HOME/config.yaml`. Run Hermes from the trusted project root with `HERMES_ENABLE_PROJECT_PLUGINS=true`; Rulesync deliberately does not persist that global trust gate.\n\n> **ZCode note:** ZCode subagents are **global only**: its docs state that the current Beta \"manages global / user-level subagents stored under `~/.zcode/agents/`\" and that creating workspace / project-level ones \"is not available yet\". `zcode` is therefore offered for `--global` runs only, and a project-scope `rulesync generate --features subagents` writes nothing for it. Each subagent is one Markdown file named after the agent, `~/.zcode/agents/<name>.md`, with YAML frontmatter whose keys are camelCase and case-sensitive: `name` and `description` are required, and `model`, `thoughtLevel`, `color`, `tools`, `disallowedTools`, `maxTurns` (a positive integer), `injectAgentsMd` and `mcpServers` are optional. Put those optional fields in the `zcode:` block of the canonical subagent; any extra keys are preserved on round-trip through the same block. See the [ZCode subagents docs](https://zcode.z.ai/en/docs/subagents).\n\n## `.rulesync/checks/*.md`\n\nCode review checks are per-check instructions an agent runs during code review. Each check is a single Markdown file with YAML frontmatter (the source of the check identity is the file name — e.g. `.rulesync/checks/security.md` defines the `security` check).\n\nExample:\n\n```md\n---\ntargets: [\"*\"] # * = all, or specific tools\ndescription: Flags common security issues # (optional) short summary of the check\nseverity: high # (optional) low | medium | high | critical\ntools: [\"Read\", \"Grep\"] # (optional) tool names the check may use\n---\n\nReview the diff for injection vulnerabilities, hardcoded secrets, and unsafe\ndeserialization. Report each finding with a file and line reference.\n```\n\nAmp, AugmentCode, Cursor, Factory Droid, Hermes Agent, Rovo Dev CLI and Takt consume checks. Amp receives one Markdown file per check:\n\n- **Project scope:** `.agents/checks/<name>.md`\n- **Global scope** (`--global`): `~/.config/amp/checks/<name>.md`\n\nFor Cursor, checks are [Bugbot](https://cursor.com/docs/bugbot) code review instructions, and Bugbot reads one aggregated instruction file per directory rather than a file per check — so every check targeting Cursor collapses into the repository-root `.cursor/BUGBOT.md`. Each check becomes one section: an HTML-comment marker carrying the check name, an `## <name>` heading, and the check body as the instruction text (the `description` is used when the body is empty). Bugbot reads the file as free prose, so a check's `severity` and `tools` have no equivalent there — they are not written and do not come back on import, and neither is `description` whenever the check also has a body. Project scope only: Bugbot reads repository files and there is no user-level instruction file. Because Bugbot only sees the file when it is **committed**, the derived `.gitignore` deliberately does not ignore `.cursor/BUGBOT.md` (Rovo Dev's `.rovodev/.review-agent.md` and Factory Droid's `.factory/skills/review-guidelines/SKILL.md` get the same treatment) — commit the generated file for the reviewer to pick it up. Example output:\n\n```md\n<!-- rulesync:check:security -->\n\n## security\n\nReview the diff for injection vulnerabilities.\n```\n\nOn import the markers split the file back into one check per section, each with `targets: [\"*\"]` because Bugbot instructions are plain prose that applies anywhere. Content sitting ahead of the first marker — and a hand-written `BUGBOT.md` with no markers at all — is imported as a single `bugbot` check, so nothing in the file is dropped. A check body that contains a marker line of its own (a quoted rulesync doc fragment, say) is written as `<!-- rulesync:literal-check:… -->` and restored on import, so it cannot split the check it belongs to. Bugbot also merges nested `<dir>/.cursor/BUGBOT.md` files found while traversing upward from changed files, but rulesync check sources carry no directory-placement semantics, so only the root file is generated.\n\nGenerating checks for Cursor replaces `.cursor/BUGBOT.md`, so run `rulesync import --targets cursor --features checks` first if the repository already has a hand-written one — generation warns when it is about to replace instructions rulesync did not write. Deletion is guarded: a `BUGBOT.md` holding anything rulesync did not write — no marker at all, or hand-written text ahead of the first marker — is never removed, so dropping the last check that targets Cursor takes rulesync's own output with it and nothing else.\n\nFor Rovo Dev CLI, checks are [code-review custom instructions](https://support.atlassian.com/rovo/docs/set-custom-instructions-for-code-reviews/), and Rovo Dev reads one plain-Markdown file rather than a file per check — so every check targeting Rovo Dev collapses into `.rovodev/.review-agent.md` (note the leading dot in the file name). The file takes **no frontmatter**. Everything else works exactly as it does for Cursor Bugbot above, because the two surfaces are the same shape: one marked-up section per check, `severity`/`tools` dropped, `description` used only when the body is empty, markers splitting the file back on import (with a hand-written file importing as a single `review-agent` check), the same `<!-- rulesync:literal-check:… -->` escaping, the same replace-and-warn on generate, and the same deletion guard for a file holding anything rulesync did not write. Project scope only — these are per-repository review instructions and Rovo Dev documents no user-level equivalent, which is the opposite of the Rovo Dev permissions surface (global only).\n\nFor Factory Droid, checks are its [repository-specific review guidelines](https://docs.factory.ai/software-factory/code-review-ci). Factory's automated code review has no dedicated instruction file: it reads a skill named `review-guidelines` and injects it into every review run, so every check targeting Factory Droid collapses into `.factory/skills/review-guidelines/SKILL.md`. The file is plain Markdown with **no frontmatter**, matching Factory's documented example — and frontmatter would be self-defeating anyway, since anything ahead of the first marker counts as hand-written text. Everything else works exactly as it does for Cursor Bugbot above (one marked-up section per check, `severity`/`tools` dropped, the same escaping, the same deletion guard), with a hand-written file importing as a single `review-guidelines` check (its YAML frontmatter, if it has any, is skill metadata rather than review prose and is dropped on the way in). Project scope only: the reviewer runs against a repository and reads the file out of it, so there is no user-level equivalent to write. Because the output lives inside the `.factory/skills/` tree the `skills` feature also writes, the derived `.gitignore` ignores that tree as `**/.factory/skills/**` and re-includes this one file — git cannot un-ignore a path inside an ignored directory, so the directory pattern has to be the broader one. Re-run `rulesync gitignore` after upgrading: an earlier rulesync wrote the directory itself as `**/.factory/skills/`, and git never descends into an ignored directory, so that one line left in place would keep the re-include from working and the reviewer would never see the generated file. The command takes the old spelling out for you, wherever in the file it sits. A `review-guidelines` skill you authored yourself collides with the generated file. Generation does not replace it: a file holding anything ahead of the first generated marker is left exactly as it is, no Factory Droid checks are written at all for that run, and a warning names the file — the path has a single owner rather than a merge rule, and a file here may be an ordinary skill written for Droid's skill loader rather than review prose, so rulesync does not rewrite it (this is stricter than Cursor Bugbot's replace-and-warn, whose path only the reviewer reads). Import it with `rulesync import --targets factorydroid --features checks` and then delete the file: importing copies the text into `.rulesync/checks/` but leaves the file itself alone, so generation stays blocked until it is gone, and the next generate writes the path back from `.rulesync/checks/`. Delete it outright if you no longer want it, or rename the directory if what it holds is an ordinary skill rather than review guidelines. The `skills` feature leaves this path alone in every direction, whatever the file holds: a project-scoped `review-guidelines` skill is never imported as a skill, never swept as an orphan skill directory by `generate --delete`, and never generated into `.factory/skills/review-guidelines/` in the first place — a rulesync skill of that name is skipped for Factory Droid with a warning, so rename it if you want it generated. Global scope is unaffected, since checks has no user-level output: `~/.factory/skills/review-guidelines/` is an ordinary skill. Deleting the file when the last check targeting Factory Droid goes away is still guarded: it is removed only when it holds nothing but generated sections. Note that this file is **committed**, unlike the rest of `.factory/skills/`: Factory's reviewer reads it out of the checked-out repository, so whatever it contains is injected into every review run — review it as you would any other committed instruction file, in particular when it came from `rulesync fetch`.\n\nFor AugmentCode, checks are [Augment Code Review guidelines](https://docs.augmentcode.com/codereview/review-guidelines), which live in one YAML file at `.augment/code_review_guidelines.yaml` rather than in a file per check. Augment groups rules into named **areas**, each with a `description`, the `globs` it applies to, and a list of `rules` — every rule an `id` / `description` / `severity` triple, all of them required. Rulesync maps one check onto one rule: the body becomes the rule's `description` (the check's `description` is used when the body is empty, and the file stem when neither is set), and the rule lands in an area of its own, keyed by the check's file stem. An `augmentcode` frontmatter block moves it: `area` groups several checks under one key, with `areaDescription` and `globs` taken from the first check to name that area (`globs` defaults to `[\"**\"]`, matching Augment's own example; an authored empty list is kept as written, since an area matching nothing is a narrower statement than the catch-all, not an absent value), and `id` overrides the rule id. An authored `area` is used verbatim — Augment's own documented example keys an area `memory_safety`, and rewriting the underscores would leave the original area behind while a second one appeared beside it. Only the file-stem default is slugified, since that has to become a legal key from an arbitrary file name. Rule ids are kept distinct because Augment reports findings by id: two same-named checks in different subdirectories become `security` and `security-2`, and a generated id also steps aside for one a preserved hand-written area already uses. Example:\n\n```md\n---\ntargets: [\"augmentcode\"]\nseverity: high\naugmentcode:\n  area: databases\n  areaDescription: \"Data and Database related rules\"\n  globs: [\"db/**\"]\n  id: \"no_pii_in_bigquery\"\n---\n\nNever store PII data in BigQuery tables.\n```\n\n**Severity is lossy in one direction.** Augment's scale is `high` / `medium` / `low` with no band above `high`, so canonical `critical` is written as `high` and imports back as `high` — the canonical value is not recoverable from Augment's file alone. A check with no `severity` emits `medium`, since the field cannot be omitted: `high` would push every unannotated check past the ones deliberately marked `medium`, and `low` would bury them.\n\nGeneration **merges** rather than replaces, because Augment's documentation tells users to hand-write this file. Only the areas the current check set claims are rewritten — and a claimed area is replaced as a whole, so a field you hand-added inside one Rulesync regenerates does not survive. Every other area, the `file_paths_to_ignore` list, and any key Augment adds later are left untouched. `file_paths_to_ignore` is recognized and preserved but never authored or imported — the canonical check model has no ignore surface, and adding one is a separate question. The cost of merging is that rulesync cannot tell its own leftovers from a hand-written area: renaming a check strands the area under the old key, and when checks remain but none target AugmentCode the existing areas are left in place with a warning rather than guessed at. For the same reason the file is never deleted once it exists — unlike the Markdown surfaces, YAML carries no marker saying which text is rulesync's, since a rewrite drops comments and an unknown top-level key risks Augment's own parser.\n\nOn import, each rule becomes its own check (an area of three rules is three checks, not one), carrying the area key, description and globs back in its `augmentcode` block so the next generate regroups them exactly where they were. A rule missing `id` or `description` is left in the YAML rather than imported, and a rule id repeated across two areas is suffixed so the second check does not overwrite the first. Project scope only — the reviewer reads the file from the committed repository, and Augment documents no user-level equivalent.\n\nFor Hermes Agent, Rulesync writes project-local JSON specs under `.hermes/plugins/rulesync-checks/checks/` and a `rulesync-checks` plugin beside them. Its one-shot [`pre_verify` hook](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/#pre-verify) fires only for coding turns with changed paths and `attempt == 0`, then asks Hermes to run all configured checks before finishing. `tools` is preserved as advisory guidance because Hermes does not enforce an Amp-style per-check tool allowlist. Run Hermes with the project plugin explicitly trusted for that invocation:\n\n```sh\nHERMES_ENABLE_PROJECT_PLUGINS=1 hermes\n```\n\nRulesync adds `rulesync-checks` to `plugins.enabled` in `$HERMES_HOME/config.yaml` but deliberately leaves `$HERMES_HOME/.env` unchanged, preserving Hermes's global trust boundary. Existing plugin configuration is preserved; an explicit `plugins.disabled` conflict fails generation.\n\nFor Takt, checks are **quality gates**, and they live in the `workflow_overrides` block of the shared `.takt/config.yaml` (project) / `~/.takt/config.yaml` (global) rather than in files of their own — so every check targeting Takt collapses into that one file. A check becomes one gate: by default a **string gate**, the body text, which Takt injects into the agent step prompt as a completion directive (the `description` is used when the body is empty, and the file stem when neither is set); with `command` in the check's `takt` frontmatter block, a **command gate** (`{type: command, name, command, cwd, timeout_ms}`), which Takt runs after the step and fails on a non-zero exit code. `name` defaults to the file stem so Takt's logs identify the gate. `name`, `cwd` and `timeout_ms` belong to a command gate, so they are ignored on a check that states no `command`. `steps` and `personas` in that block scope a gate to named workflow steps or personas (`workflow_overrides.steps.<step>.quality_gates`); an unscoped gate applies everywhere, and a gate naming both is written to both. `quality_gates_edit_only` is a property of the block as a whole, so one check setting it turns it on for all of them. It reaches only the unscoped gates — Takt runs a `steps`/`personas`-scoped gate whether or not the step may edit files — so the reach it narrows is the other checks' unscoped gates, which is warned about when there are any. Takt gates carry no severity or tool allowlist, so a check's `severity` and `tools` are not written and do not come back on import. Takt merges quality gates additively and dedupes them (project over global over the workflow YAML's own gates). Example:\n\n```md\n---\ntargets: [\"takt\"]\ntakt:\n  command: ./.takt/quality-gates/check.sh # omit for a string gate\n  timeout_ms: 300000\n  steps: [\"review\"] # (optional) scope to named workflow steps\n  personas: [\"coder\"] # (optional) scope to named personas\n---\n```\n\nA command gate's `command` is run by Takt with no further gating — Takt's default-deny `workflow_command_gates.custom_scripts` policy applies to gates declared in workflow YAML, not to these — so read the frontmatter of any check you obtain with `rulesync fetch` before generating. The body of a check that carries a `command` is not used. `workflow_overrides` is owned by the checks feature: it is rewritten from `.rulesync/checks/` on every generate, so a gate deleted there disappears from `config.yaml` too, while every other key of the file is preserved and the file is never deleted. When checks remain but none of them target Takt — every one names other tools — the block is retracted with a warning, whether an earlier generate or a hand edit put it there; that is what owning the key means, so author gates as checks rather than in `config.yaml`. A project with no `config.yaml` does not get one. Emptying `.rulesync/checks/` altogether is different: the feature has no source to generate from, so nothing runs and the gates already in `config.yaml` stay. Delete the block by hand in that case — a command gate left behind keeps running after every step. On import, each gate becomes its own check file, named from the gate text or the command gate's `name`. A string gate is prose that applies anywhere, so it imports with `targets: [\"*\"]` like an Amp check; a command gate imports as `targets: [\"takt\"]`, since its body is empty and would generate an empty check for every other tool. A gate scoped to both a step and a persona becomes two checks, and a command gate carrying a field of the wrong type is left in `config.yaml` rather than imported. The default-deny `workflow_command_gates.custom_scripts` policy is **not** written here — Takt validates it against gates declared in workflow YAML, not against these, and it is authorable through the `takt` block of `.rulesync/permissions.*`, which owns the security policies. See the [Takt workflows docs](https://github.com/nrslib/takt/blob/main/docs/workflows.md).\n\nThe emitted Amp frontmatter is derived from the source as follows:\n\n| Amp field          | Source                                                   |\n| ------------------ | -------------------------------------------------------- |\n| `name`             | the source file basename without `.md` (required by Amp) |\n| `description`      | `description`                                            |\n| `severity-default` | `severity`                                               |\n| `tools`            | `tools`                                                  |\n\nThe frontmatter schema is loose, so extra Amp-specific keys survive a generate/import round-trip (except keys that collide with a rulesync tool-target name such as `cursor` — those are treated as tool-scoped sections and are not re-emitted). A tool-scoped section (e.g. `amp: { \"severity-default\": \"critical\" }`) overrides the canonical values for that tool — the tool-specific value takes precedence, and the section itself is not emitted (except `name`, which always comes from the file name). On import, `severity-default` maps back to the generic `severity` field, and the `name` field is dropped because it is re-derived from the file name on the next generate.\n\n> **v1 limitation:** Amp also discovers subtree-scoped checks (e.g. `api/.agents/checks/`), but rulesync sources carry no directory-placement semantics, so those subtree-scoped checks are not generated. See the [Amp manual](https://ampcode.com/manual).\n\n## `.rulesync/skills/*/SKILL.md`\n\nExample:\n\n```md\n---\nname: example-skill # skill name\ndescription: >- # skill description\n  A sample skill that demonstrates the skill format\ntargets: [\"*\"] # * = all, or specific tools\n# (optional) shared default for tools that support the flag — claudecode, copilot,\n# copilotcli, cursor, zed, pi, qwencode, grokcli, and factorydroid. Any of those\n# tool sections can override it by setting their own `disable-model-invocation`\n# value below. devin also reads this root value (true maps onto a user-only\n# `triggers` list); it has no section key of the same name, but devin.triggers\n# overrides it.\ndisable-model-invocation: true\n# (optional) shared default for tools that support the flag — claudecode, copilot,\n# copilotcli, cursor, qwencode, vibe, grokcli, and factorydroid. Any of those tool\n# sections can override it by setting their own `user-invocable` value below.\n# devin also reads this root value (false maps onto a model-only `triggers`\n# list); it has no section key of the same name, but devin.triggers overrides it.\nuser-invocable: false\nclaudecode: # for claudecode-specific parameters\n  model: sonnet # opus, sonnet, haiku, or any string\n  when_to_use: When the user asks to review a PR # (optional) extra trigger context appended to description\n  allowed-tools: # (optional) tools usable without asking; accepts a string or a list\n    - \"Bash\"\n    - \"Read\"\n    - \"Write\"\n    - \"Grep\"\n  disallowed-tools: # (optional) removes these tools while the skill is active (string or list)\n    - \"WebFetch\"\n  effort: high # (optional) effort while active: low | medium | high | xhigh | max\n  argument-hint: \"[pr-number]\" # (optional) autocomplete hint for expected arguments\n  arguments: # (optional) named positional arguments for $name substitution (string or list)\n    - \"pr_number\"\n  context: fork # (optional) set to \"fork\" to run the skill in a forked subagent context\n  agent: code-reviewer # (optional) subagent type to use when context: fork\n  background: false # (optional, context: fork only) wait for the forked subagent in the invoking turn instead of backgrounding it (default true)\n  shell: bash # (optional) shell for ! command blocks: bash (default) or powershell\n  hooks: # (optional) hooks scoped to the skill's lifecycle (free-form per the Claude Code docs)\n    PreToolUse:\n      - matcher: \"Bash\"\n  disable-model-invocation: true # (optional) disable model invocation for this skill\n  user-invocable: false # (optional) hide from the / menu while keeping model access\n  scheduled-task: true # (optional) emit to .claude/scheduled-tasks/<name>/SKILL.md instead of .claude/skills/<name>/SKILL.md\n  # paths (optional) limits auto-activation to matching globs. Accepts a\n  # comma-separated string, e.g. paths: \"src/**/*.ts,test/**/*.ts\", or a list:\n  paths:\n    - \"src/**/*.ts\"\n    - \"test/**/*.ts\"\n  # Claude Code accepts the three Agent Skills standard fields below but acts on\n  # none of them; they matter for claude.ai skill uploads, the Skills API, and\n  # packaging with package_skill.py.\n  license: Apache-2.0 # (optional) license covering the skill\n  compatibility: Requires Node.js 22 or later # (optional) environment requirements, up to 500 characters\n  metadata: # (optional) free-form map for your own tooling; a non-map value is dropped by Claude Code\n    catalog: internal\ncodexcli: # for codexcli-specific parameters\n  short-description: A brief user-facing description\n  # The following sections are emitted to the agents/openai.yaml sidecar next to SKILL.md.\n  # See https://developers.openai.com/codex/skills.md\n  interface: # (optional) UI metadata\n    display_name: Example Skill\n    short_description: A brief user-facing description\n    default_prompt: Do the thing\n  policy: # (optional) invocation policy\n    allow_implicit_invocation: false # only invoke explicitly via $skill\n  dependencies: # (optional) tool dependencies\n    tools:\n      - type: mcp\n        value: example\n        description: Example MCP tool\npi: # for Pi Coding Agent-specific parameters (optional; Agent Skills standard)\n  # Authored either as a canonical list or as the spec's space-delimited string;\n  # emitted to SKILL.md as the string, and imported back as the list.\n  allowed-tools:\n    - \"Bash\"\n    - \"Read\"\n  disable-model-invocation: true # (optional) disable model invocation for this skill\n  license: MIT # (optional)\n  compatibility: \"Requires git and jq\" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n  metadata: # (optional) free-form metadata\n    author: rulesync\nreplit: # for Replit Agent-specific parameters (optional; Agent Skills standard)\n  # Authored either as a canonical list or as the spec's space-separated string;\n  # emitted to SKILL.md as the string, and imported back as the list.\n  allowed-tools:\n    - \"Bash\"\n    - \"Read\"\n  license: MIT # (optional)\n  compatibility: \"Requires git and docker\" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n  metadata: # (optional) free-form metadata\n    author: rulesync\ndeepagents: # for deepagents-cli (dcode)-specific parameters (optional; Agent Skills standard)\n  # Authored as a canonical list; emitted to SKILL.md as a space-delimited string\n  # (e.g. \"Bash Read\") because dcode rejects a YAML list at runtime.\n  allowed-tools:\n    - \"Bash\"\n    - \"Read\"\n  license: MIT # (optional)\n  compatibility: # (optional) free-form compatibility metadata\n    deepagents-version: \">=0.1.0\"\n  metadata: # (optional) free-form metadata\n    author: rulesync\nopencode: # for OpenCode-specific parameters (optional)\n  license: MIT # (optional)\n  compatibility: # (optional) free-form compatibility metadata\n    opencode-version: \">=1.16.0\"\n  metadata: # (optional) free-form metadata\n    author: rulesync\n  allowed-tools: # (optional) Anthropic-spec passthrough; OpenCode ignores unknown fields\n    - \"Bash\"\n    - \"Read\"\nkilo: # for Kilo Code-specific parameters (optional)\n  license: MIT # (optional)\n  compatibility: # (optional) free-form compatibility metadata\n    kilo-version: \">=7.0.0\"\n  metadata: # (optional) free-form metadata\n    author: rulesync\n  allowed-tools: # (optional) backward-compat passthrough; not part of Kilo's official SKILL.md frontmatter\n    - \"Bash\"\n    - \"Read\"\nkiro: # for Kiro-specific parameters (optional; project .kiro/skills/, global ~/.kiro/skills/)\n  license: MIT # (optional)\n  compatibility: \"Requires network access\" # (optional) free-form string (an object is also accepted for back-compat)\n  metadata: # (optional) free-form metadata\n    author: rulesync\n  # Any other frontmatter key found in a hand-written SKILL.md is imported into this section and\n  # written back out, so a field Rulesync does not model is not lost on regeneration. `name` and\n  # `description` are the exception: they have canonical homes at the top level.\nkimi-code: # for Kimi Code-specific parameters (optional; project/global .kimi-code/skills/)\n  type: inline # (optional) prompt, inline, or flow\n  whenToUse: \"When reviewing pull requests\" # (optional) model invocation hint\n  disableModelInvocation: false # (optional) prevent automatic model invocation\n  arguments: [\"pull_request\"] # (optional) named arguments, also accepts a whitespace-separated string\nagentsskills: # for the Agent Skills standard target (optional; supports project + global ~/.agents/skills/)\n  license: MIT # (optional)\n  compatibility: \"Requires Python 3.14+ and uv\" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n  metadata: # (optional) free-form metadata (spec-recommended place for skill versioning)\n    version: \"1.0.0\"\n  allowed-tools: \"shell\" # (optional, experimental) space-separated string or list\namp: # for Amp-specific parameters (optional; project .agents/skills/, global ~/.config/agents/skills/)\n  # Amp reads the open Agent Skills standard and documents no frontmatter field beyond\n  # `name`/`description`, so this section exists only to carry keys a hand-written SKILL.md adds:\n  # they are imported into it and written back to the top level of the generated file instead of\n  # being erased on regeneration. `name` and `description` are the exception — they have canonical\n  # homes at the top level and a section value of either is ignored.\ncopilot: # for GitHub Copilot-specific parameters (optional; project .github/skills/, global ~/.copilot/skills/)\n  license: MIT # (optional)\n  allowed-tools: \"shell\" # (optional) tools pre-approved without per-use confirmation\n  argument-hint: \"[message]\" # (optional) hint shown for the skill's expected arguments\n  user-invocable: true # (optional, default true) whether users can run it with /SKILL-NAME\n  disable-model-invocation: false # (optional, default false) stop the agent from invoking it on its own\n  context: fork # (optional, experimental) run the skill in a forked session (VS Code 1.118+)\n  # Any other frontmatter key found in a hand-written SKILL.md is imported into this section and\n  # written back out, so a field Rulesync does not model is not lost on regeneration. `name` and\n  # `description` are the exception: they have canonical homes at the top level. Like the modeled\n  # fields below, such a key rides one section only, so the shared-path caveat that follows applies\n  # to it too.\n  # `copilot` and `copilotcli` write the same SKILL.md path at both scopes, so with both targets\n  # enabled the one generated last wins — and that is the order the targets are listed in, so which\n  # section decides the file is not fixed. Set the value in both sections (or, for the two invocation\n  # gates, in the shared top-level fields) whenever you generate for both. `context` has no\n  # `copilotcli` counterpart, so it survives only when `copilot` is generated last.\ncopilotcli: # for GitHub Copilot CLI-specific parameters (optional; project .github/skills/, global ~/.copilot/skills/)\n  license: MIT # (optional)\n  allowed-tools: \"shell\" # (optional) tools pre-approved without per-use confirmation\n  argument-hint: \"[message]\" # (optional) hint shown for the skill's expected arguments\n  user-invocable: true # (optional, default true) whether users can run it with /SKILL-NAME\n  disable-model-invocation: false # (optional, default false) stop the agent from invoking it on its own\n  # As in the `copilot` section, any other frontmatter key found in a hand-written SKILL.md is\n  # imported here and written back out.\nrovodev: # for Rovo Dev CLI-specific parameters (optional; Agent Skills standard)\n  allowed-tools: \"grep bash\" # (optional) space-separated string (a YAML list is also accepted)\n  license: MIT # (optional)\n  compatibility: \"Requires Python 3.14+ and uv\" # (optional) free-form string (object form also accepted)\n  metadata: # (optional) free-form metadata\n    author: rulesync\nzed: # for Zed-specific parameters (optional)\n  disable-model-invocation: true # (optional) prevent the model from auto-invoking this skill\ncursor: # for Cursor-specific parameters (optional)\n  paths: # (optional) glob patterns (string or list) scoping the skill to matching files\n    - \"src/**/*.ts\"\n  disable-model-invocation: true # (optional) only include the skill when invoked via /skill-name\n  user-invocable: false # (optional) hide from / autocomplete and typed /skill-name, keep model access\n  metadata: # (optional) free-form metadata\n    author: rulesync\nfactorydroid: # for Factory Droid-specific parameters (optional)\n  disable-model-invocation: true # (optional) prevent the model from auto-invoking this skill\n  user-invocable: false # (optional) hide from the slash-command menu, keep model access\n  enabled: false # (optional, default true) keep the skill on disk but stop Droid loading it\n  allowed-tools: \"Read Execute\" # (optional) tools the skill is designed to use (string or list)\n  # Droid documents the four packaging fields below without a type and never validates\n  # them, so rulesync carries whatever value they hold through in both directions.\n  license: MIT # (optional) license metadata for shared skills\n  compatibility: droid # (optional) compatibility metadata for catalogs, plugins, or team tooling\n  metadata: # (optional) structured metadata for your own tooling\n    owner: platform-team\n  version: \"1.0.0\" # (optional) version string for shared or packaged skills — quote it, since\n  # an unquoted 1.0 is a YAML number and is emitted back as `version: 1`\n  # `name` and `description` are the exception: the top-level values always win over a\n  # value of the same key inside this section.\n  # As in the `kiro` section, any other frontmatter key found in a hand-written SKILL.md is\n  # imported here and written back out.\ntakt: # takt specific parameters (optional; emitted under .takt/facets/knowledge/ — frontmatter is dropped on emit)\n  name: \"renamed-stem\" # (optional) override the emitted filename stem (no path separators or \"..\")\n  extends: \"base\" # (optional) emit a leading `{extends:<parent>}` facet-inheritance directive (Takt 0.39.0+)\ndevin: # for Devin-specific parameters (optional; project .devin/skills/, global ~/.config/devin/skills/)\n  argument-hint: \"[environment]\" # (optional) hint shown after the slash-command name\n  model: \"fast\" # (optional) model override while the skill runs\n  subagent: true # (optional) run the skill in a subagent (string or boolean per Devin's docs)\n  agent: \"deployer\" # (optional) named agent profile to run the skill with\n  allowed-tools: # (optional) tools available while the skill runs (string or list)\n    - \"Bash(git status:*)\"\n  permissions: {} # (optional) auto-approval rules applied while the skill runs (load-bearing since Devin CLI v3000.1.23)\n  triggers: [\"user\"] # (optional) invocation gating; omitted = user + model. The shared disable-model-invocation / user-invocable flags map onto this when unset.\nqwencode: # for Qwen Code-specific parameters (optional; project .qwen/skills/, global ~/.qwen/skills/)\n  priority: 10 # (optional) higher values appear earlier in /skills listings\n  paths: # (optional) glob patterns gating model discovery to matching files (a scalar is coerced to the array Qwen Code requires)\n    - \"src/**/*.ts\"\n  user-invocable: false # (optional) hide from slash-command invocation, keep model access\n  disable-model-invocation: true # (optional) hide from the model but allow direct user invocation\n  allowedTools: # (optional) permissions.allow-syntax rules auto-approved while the skill is active\n    - \"Shell(git status:*)\"\n  model: \"fast\" # (optional) model override while the skill runs (model id, fast, authType:modelId, inherit)\n  hooks: {} # (optional) session-scoped hooks registered while the skill runs (settings.json shape)\n  when_to_use: \"Use when deploying\" # (optional) invocation guidance surfaced in the SkillTool description\n  argument-hint: \"[environment]\" # (optional) hint shown after the slash-command name in completion\ngrokcli: # for Grok CLI-specific parameters (optional)\n  user-invocable: false # (optional) hide from the skill tool, keep model access\n  disable-model-invocation: true # (optional) block auto-invocation, keep the slash command\nvibe: # for Vibe Code-specific parameters (optional)\n  user-invocable: false # (optional) hide from slash-command invocation, keep model access\n  allowed-tools: \"Bash Read\" # (optional) space-delimited or list of allowed tool names\n---\n\nThis is the skill body content.\n\nYou can provide instructions, context, or any information that helps the AI agent understand and execute this skill effectively.\n\nThe skill can include:\n\n- Step-by-step instructions\n- Code examples\n- Best practices\n- Any relevant context\n\nSkills are directory-based and can include additional files alongside SKILL.md.\n\nWhen `claudecode.scheduled-task: true` is set, that skill is emitted only as a Claude Code scheduled task and is not emitted to other tools even if `targets` contains `\"*\"`.\n```\n\n> **Supporting-file note:** every file beside `SKILL.md` in a skill directory is copied **byte for byte**, to whichever tool root the skill is generated into. Most of them are user assets — images, archives, fixtures whose CRLF line endings or missing trailing newline are deliberate — so unlike `SKILL.md`, whose body and frontmatter Rulesync composes, they get no UTF-8 round-trip, no line-ending normalization and no trailing newline appended. Change detection compares them byte for byte too, so a supporting file written by an older Rulesync (which normalized text files) or edited in place by a formatter is rewritten from the source on the next generate. The one exception is a supporting file Rulesync composes itself rather than carries through — Codex CLI's `agents/openai.yaml` — which is compared by parsed content so that re-indenting it does not report a change on every generate. Dot-prefixed entries count as supporting files too — the specification says a skill directory \"may contain any files and directories beyond the required `SKILL.md`\", and a hidden `.env.example` or `.config/` is content the skill needs. Some entries are never carried, whether they are reached by their own name or through a symbolic link that renames them:\n>\n> - `.git`, `.hg` and `.svn` — a nested repository, whose tracked files are copied but whose history is not. Rulesync warns when it skips a top-level `.git`.\n> - `.DS_Store` — the macOS Finder's index.\n> - Credential stores and credential-shaped files: anything under `.ssh/`, `.aws/` or `.gnupg/`, plus `.npmrc`, `.netrc`, `.git-credentials`, `.pgpass`, `.pypirc`, `.htpasswd`, `.dockercfg`, `.envrc`, `.docker/config.json`, `.kube/config`, `.config/gh/hosts.yml`, `.config/gcloud/credentials.db`, `.gem/credentials`, `gcloud/application_default_credentials.json`, `.codex/auth.json` and `.gemini/oauth_creds.json`. A credential name counts wherever it appears in the path, not only as the last segment: `.env/production` and `.netrc/machine` hold what the files of those names hold, so a directory given a credential file's name is refused with everything under it. Carrying a secret would copy it into every enabled tool root, multiplying the places it can be committed from. A link that leaves the skill directory to reach a `.config/`, `.local/`, `.azure/`, `.m2/`, `.terraform.d/`, `.docker/`, `.kube/` or `Keychains/` tree is refused entirely — those are the per-application directories of a home directory, where naming each credential file is a list always one release behind — while a `.config/` the skill ships itself is carried as ordinary content. The exemption is for a sibling: a link that goes no higher than the skill directory's own parent, so a global skill under `~/.config/agents/skills/` still shares `../_shared` there while the same skill reaching `~/.config/gcloud/` is refused like any other; a tool home such as `~/.claude/` is deliberately not on the list, because that is where the global skills this feature exists to share are kept.\n> - `.env` and every `.env.<suffix>` spelling except the template ones — the last piece of the name decides, so `.env.example`, `.env.sample`, `.env.template`, `.env.dist`, `.env.defaults` and compound spellings such as `.env.local.example` are carried, being the case this support exists for, while `.env.local` and `.env.production` hold real values.\n> - Build, cache and virtual-environment trees: `.cache`, `.venv`, `.tox`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, `.gradle`, `.next`, `.nuxt`, `.turbo`, `.parcel-cache`, `.nyc_output` and `.terraform`. These are regenerated from the skill's own sources, and copying a `.venv` into every enabled tool root would multiply thousands of files that are not skill content.\n>\n> Names are compared case-insensitively, so `.SSH/` is excluded on the platforms that treat it as `.ssh/`, and trailing dots and spaces are trimmed first, because Windows drops them when the file lands (`.env ` becomes `.env` there). Leaving out a credential-shaped entry is reported in a warning, and so is an entry whose own name says nothing about it — a link named `assets` pointing into a `.cache/` tree; the ordinary exclusions, where the name in the skill directory is the excluded one — `.DS_Store`, build and cache trees — stay quiet.\n>\n> A skill directory is also walked within bounds, because a symbolic link in it may point anywhere: at most **12 directories deep**, at most **10,000 files**, at most **10,000 directories**, at most **200,000 entries looked at**, and at most **100MB** in total per directory, and each real directory is visited once so that a link pointing back at an ancestor collapses instead of multiplying the walk. Because only one route to a directory is walked, the route is chosen rather than left to the walk order: everything reachable without crossing a symbolic link first, then everything one link away, and so on — so a file keeps the path its `SKILL.md` refers to. When a route that the hidden-entry rule below then refuses is the one that reached a tree, the directory is walked once more with the hidden routes left out, so a tree that a fully named path also reaches is still carried under that name. Reaching any of those limits leaves files out, so it is always reported in a warning rather than silently truncating the skill; so is an entry that cannot be read at all. A route that passes through `/proc`, `/sys` or `/dev` is refused at every hop rather than only at its destination: `/proc/<pid>/fd/N` and `exe` resolve to whatever a running process holds open, so a check of the destination alone would carry another program's private key as though it were an ordinary file. Each hop's parent directory is resolved as well, since a link named `fds` pointing at `/proc/self/fd` leaves no `/proc` in the path `fds/3` to check; the hops a chain costs count against the entry limit above, so a directory of long chains cannot buy more work than a directory of files.\n\n> **`.agents/skills/` ownership note:** `.agents/skills/` is not an AGENTS.md convention — the AGENTS.md standard defines only `AGENTS.md` itself. It is the [Agent Skills](https://agentskills.io/specification) project location, which the native `agentsskills` target writes. Several targets write there — `agentsskills`, `agentsmd`, `aiassistant`, `codexcli`, `amp`, `zed`, `replit` and both Antigravity targets — because they all implement the same convention. Each native target writes its own documented frontmatter, so enabling more than one and reordering `--targets` can change which optional keys end up in the file; that is inherent to several tools sharing one path and is not specific to any of them.\n\n> The **simulated** `agentsmd` writer is the exception that is fixed: it has no frontmatter model of its own (the AGENTS.md standard defines no skills at all), so it used to overwrite the native output with a bare `name`/`description` pair and silently drop `license`, `compatibility`, `metadata` and `allowed-tools`. It now emits exactly what `agentsskills` emits, so a simulated writer can never degrade the file a native target owns.\n\n> **Cross-root duplicate note:** Several targets discover skills in more than one root — a shared Agent Skills root beside the tool-specific one (`junie`, `vibe`, `kimi-code`, `rovodev`, `augmentcode`), nested `.claude/skills/` directories (`claudecode`), or roots the tool's own config points at (`opencode`). The roots are scanned in precedence order and the first one to claim a skill name keeps it; the multi-root subagent targets follow the same rule, and for targets whose native format aggregates many subagents into one file (Roo's `.roomodes`) the same de-duplication is applied to the paths the entries fan out to. The comparison is **case-insensitive** (and Unicode normalizing), because every imported skill is written back into a single `.rulesync/skills/` tree, where `.junie/skills/my-skill` and `.agents/skills/My-Skill` are one directory on macOS and Windows — comparing the names exactly would let both through, and the shared copy, written last, would overwrite the tool-specific one, inverting the precedence the roots were ordered by. A collision that differs only in case is reported with a warning naming the ignored copy; an exact repeat stays quiet, being the ordinary overlay. Kimi Code is the exception on both counts: it identifies a skill or subagent by its frontmatter `name` folded to lower case, so two spellings are already one name upstream and the duplicate is resolved silently. **Trade-off:** the rule applies on every platform, so on a case-sensitive filesystem — where the two really are separate skills — `rulesync import` and `rulesync convert` drop the lower-precedence one instead of importing it under its own name. Rename one of them if you need both — and if the dropped copy lives in a shared `.agents/skills/` root, import `agentsskills` in the same run, so the skill still reaches `.rulesync/` and a later `agentsskills` generate does not prune it as an orphan. Slash commands are not covered by this rule yet: `augmentcode` reads both `.augment/commands/` and the shared `.agents/commands/`, but their names are still compared exactly, so `deploy.md` and `Deploy.md` are both imported and collide in `.rulesync/commands/` on a case-insensitive filesystem ([issue #2741](https://github.com/dyoshikawa/rulesync/issues/2741)).\n\n> **Claude Code nested skills note:** Claude Code v2.1.178+ also loads skills from **nested** `.claude/skills/` directories below the working directory (a skill in `apps/web/.claude/skills/` becomes available when working on files there, and a name clash with a root skill keeps both under a directory-qualified name like `apps/web:deploy`). `rulesync import --targets claudecode --features skills` discovers those nested directories (import-only, lenient, same dependency/build-directory exclusions as the nested `AGENTS.md` scan; symlinks not followed) so an existing nested skill is no longer invisible. A nested directory whose reported path does not resolve inside the project is skipped with a warning rather than followed: a glob rewrites a backslash in a directory name into a path separator, so the path it reports may belong to nothing on disk, or lead out of the project — through a `..` the name also carries, or through a symlink the scan itself never follows. A reported path that stays inside the project but resolves onto something that is not a `.claude/skills` directory of its own — a dependency or build tree, or the project root itself — is skipped the same way, since reading it as a skills directory would offer every directory under it as a skill. On a name clash the root skill wins the import — rulesync's flat skill namespace cannot express the qualified variant. Because generation stays targeted at the project-root `.claude/skills/`, a nested skill's location-based scoping would otherwise be lost, so the import derives it: a skill found in `apps/web/.claude/skills/` gets `claudecode.paths: [\"apps/web/**\"]` written for it. Glob metacharacters in the directory names are escaped, so a Next.js-style `app/[slug]/.claude/skills/` still derives a literal match. A `paths` value the skill already declares is kept as-is — Claude Code does not document whether a nested skill's `paths` resolves against the project root or its own directory, so rulesync does not rewrite the author's glob, which means a declared value narrower than the subtree (`src/**`) is re-anchored at the project root once the skill moves there; write it subtree-qualified (`apps/web/src/**`) if that matters. Root-discovered skills get nothing added, and the derived value lands in the `claudecode:` block only — other targets with their own `paths` field (`cursor:`, `qwencode:`) are untouched. To scope a skill's _activation_ to a subtree yourself, write the `paths` frontmatter, or run a separate generate with `--output-roots <subdir>` for physical co-location.\n\n> **Note:** `claudecode.disallowed-tools` (a space/comma-separated string or a YAML list) removes the listed tools from the model while the skill is active. The same field is available on Claude Code slash commands. Both round-trip through the `claudecode` frontmatter section.\n\n> **Note:** Codex CLI reads UI metadata, invocation policy, and tool dependencies from an `agents/openai.yaml` sidecar next to `SKILL.md` (Codex's `SKILL.md` frontmatter only carries `name` and `description`). When `codexcli.interface`, `codexcli.policy`, or `codexcli.dependencies` is present, Rulesync emits `.agents/skills/<name>/agents/openai.yaml` and reads it back on import. If the sidecar is emitted and `interface.short_description` is absent, the legacy `codexcli.short-description` is routed there. See the [Codex skills docs](https://developers.openai.com/codex/skills.md).\n\n> **Takt-driven Codex note:** Rulesync's `codexcli` skills land in `.agents/skills/` (project) and `~/.agents/skills/` (global), but a Takt workflow driving Codex does **not** inherit repository or user skills from there by default — upstream's wording is \"TAKT workflows do not inherit repository or user Codex Skills by default\" — so skills you generated will not reach a Takt-driven Codex run unless you turn inheritance on. (`takt exec` is the documented exception: each scope defaults to inheritance when it is not explicitly configured.) The setting is `provider_options.codex.skills.repo` for the project tree and `.user` for the global one, added in Takt 0.53.0. **Where it goes depends on your Takt version.** Up to 0.55.x, and on any later version whenever `runtime.yaml` is inactive (a file carrying only `version: 1` counts as inactive and leaves the legacy resolution in place), it belongs in `provider_options` in `.takt/config.yaml` — which is also where a `takt` block in `.rulesync/permissions.*` writes it. From 0.56.0, `runtime.yaml` owns provider configuration, and while it is active **any** legacy provider setting in `config.yaml` — `provider_options` included — stops Takt with `Mixed provider configuration detected` before it runs an agent. Takt generates `~/.takt/runtime.yaml` active on first launch in a fresh environment, so a new install is in runtime mode by default; there, set the flag in `runtime.yaml` under the `options` of a profile whose provider is Codex, and keep `provider_options` out of `config.yaml`. Mind the shape when you move it: a profile's `options` is a **flat bag applying to that profile's own provider**, so the `codex` segment is dropped — `options: { skills: { repo: true } }`, not `options: { codex: { skills: { repo: true } } }`. The nested spelling is not a schema error; it is simply never read, so inheritance stays off while the config looks right. Takt 0.57.0 adds a workflow-side alternative to writing `provider_options` inline: a workflow, step, or parallel sub-step can declare `capabilities: enable-skills`, a bundled preset covering the Codex repo and user skills. Takt 0.55.0 made the same default change for Claude providers (`provider_options.claude.skills.enabled`, plus `--disable-slash-commands` on CLI-backed ones), so Rulesync-generated Claude Code skills and slash commands are off in Takt-driven sessions unless re-enabled the same way. See the [Takt configuration docs](https://github.com/nrslib/takt/blob/main/docs/configuration.md) and [CHANGELOG](https://github.com/nrslib/takt/blob/main/CHANGELOG.md).\n\n> **Reasonix note:** Reasonix discovers Anthropic-style directory-layout skills (`<name>/SKILL.md`) under `.reasonix/skills/` (project) / `~/.reasonix/skills/` (global, via `--global`). Rulesync emits the portable `name`/`description` frontmatter (Reasonix supports additional optional keys, but only that pair is modeled); the schema is loose, so any extra keys on an imported `SKILL.md` survive the round-trip. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md).\n\n> **Meta Muse Code note:** Muse Code discovers Agent Skills (`<skill-id>/SKILL.md`) under `.agents/skills/` (project) and under `$XDG_CONFIG_HOME/muse/skills` plus `~/.agents/skills` (user). Rulesync emits the shared `.agents/skills/` directory in project mode and only the XDG-default `~/.config/muse/skills` in global mode (via `--global`), so a skill is written exactly once. Muse Code's compatibility scans of repo-local `.codex/skills` and `.claude/skills` belong to other tools and are not emitted for `musecode`. Only the portable `name`/`description` frontmatter pair is modeled; the schema is loose, so extra keys on an imported `SKILL.md` survive the round-trip. See the [Muse Code extending docs](https://dev.meta.ai/docs/muse-code/extending.md).\n\n> **Hermes Agent note:** Hermes skills are global-only under `~/.hermes/skills/<name>/SKILL.md`. Standard Agent Skills fields (`license`, `compatibility`, and `allowed-tools`) round-trip through `agentsskills` and are normalized to the Agent Skills spec shapes described above (so `allowed-tools` is written and imported the same way as for `agentsskills`); Hermes-native fields such as `version`, `author`, `platforms`, `environments`, `required_environment_variables`, `required_credential_files`, and `metadata.hermes` round-trip through `hermesagent`. Canonical `name` and `description` always own those two frontmatter keys.\n\n> **Kimi Code note:** Kimi Code discovers skills under `.kimi-code/skills/` (project) and `~/.kimi-code/skills/` (global), plus the shared `.agents/skills/` root at either scope. Rulesync generates the recommended directory layout (`<name>/SKILL.md`) and imports both that layout and flat `<name>.md` skills; for flat files, a missing `name` comes from the filename and a missing `description` falls back to the first non-empty body line (up to 240 characters), matching Kimi. Imported skills are written to `.rulesync/skills/<logical-name>/SKILL.md`, using the normalized logical frontmatter name rather than the source directory or filename. Duplicate precedence follows Kimi's case-insensitive logical frontmatter `name`: the Kimi-specific root takes precedence over `.agents/skills/`, and a directory skill takes precedence over a same-named flat file within one root. Shared roots are import-only and are never removed by Kimi-target orphan deletion. Besides `name`/`description`, Rulesync maps Kimi's `type`, `whenToUse`, `disableModelInvocation`, and `arguments` frontmatter through the `kimi-code:` block and preserves supporting files beside directory-layout `SKILL.md`. The shared top-level `disable-model-invocation` value supplies the Kimi flag unless the tool-specific block overrides it. See the [Kimi Code Agent Skills docs](https://moonshotai.github.io/kimi-code/en/customization/skills.html).\n\n> **ZCode note:** ZCode discovers Anthropic-style directory-layout skills (`<name>/SKILL.md`) and invokes them with `$`. The documented location is the user one, `~/.zcode/skills/`; the workspace scope its import dialog offers is taken to be served from the project's own `.zcode/skills/`, so rulesync writes `.zcode/skills/<name>/SKILL.md` in project mode and `~/.zcode/skills/<name>/SKILL.md` with `--global`. That project path is inferred from the import dialog and from ZCode's other workspace assets, not documented. Only the portable `name`/`description` pair is modeled; the schema is loose, so an imported `SKILL.md` carrying extra keys still parses, but — as with every other skill target — only that pair is carried into the canonical skill. ZCode rejects a `description` longer than 1024 characters and truncates a body past 100KB when it loads the skill; rulesync does not enforce either limit, since the canonical skill is shared with every other target. See the [ZCode skills docs](https://zcode.z.ai/en/docs/skill).\n\n## `.rulesync/mcp.jsonc`\n\n`.rulesync/mcp.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/mcp.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nA key named `__proto__`, `constructor`, or `prototype` is rejected with an error naming its path, rather than being dropped in silence. The \"Rejected keys\" paragraph in the `.rulesync/permissions.jsonc` section below describes this handling, which is the same for all three source files.\n\nExample:\n\n```json\n{\n  \"mcpServers\": {\n    \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json\",\n    \"serena\": {\n      \"description\": \"Code analysis and semantic search MCP server\",\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/oraios/serena\",\n        \"serena\",\n        \"start-mcp-server\",\n        \"--context\",\n        \"ide-assistant\",\n        \"--enable-web-dashboard\",\n        \"false\",\n        \"--project\",\n        \".\"\n      ],\n      \"env\": {}\n    },\n    \"context7\": {\n      \"description\": \"Library documentation search server\",\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@upstash/context7-mcp\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### Tool-scoped server blocks (`{toolname}.mcpServers`)\n\nServers under the shared `mcpServers` key are emitted to every targeted tool. To scope a server to a single tool, add a tool-scoped `{toolname}` block alongside it — mirroring `{toolname}.hooks` in `.rulesync/hooks.jsonc` and `{toolname}.permission` in `.rulesync/permissions.jsonc`:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"shared-server\": { \"type\": \"stdio\", \"command\": \"echo\" },\n  },\n  \"claudecode\": {\n    \"mcpServers\": {\n      // Added only to Claude Code's MCP config.\n      \"claude-only-server\": { \"type\": \"http\", \"url\": \"https://example.com/mcp\" },\n      // `null` removes a shared server for Claude Code only.\n      \"shared-server\": null,\n    },\n  },\n}\n```\n\n- A tool-scoped entry with the same name as a shared server **replaces it wholesale** for that tool (no field-level merge).\n- A tool-scoped entry set to `null` **removes** the shared server for that tool.\n- Any MCP-capable `--targets` name is accepted as a block key (`claudecode`, `cursor`, `codexcli`, ...). Targets that share one output file resolve identically so the shared file never depends on generation order: the deprecated `claudecode-legacy` target reads the `claudecode` block; the `kiro-cli` / `kiro-ide` targets read the `kiro` block (all three write the same `.kiro/settings/mcp.json`); and the `antigravity-ide` / `antigravity-cli` targets both apply both `antigravity-*` blocks in a fixed order (`antigravity-ide` first, then `antigravity-cli` — the CLI block wins per server) because they share their output file at both scopes (`.agents/mcp_config.json` in project mode, `~/.gemini/config/mcp_config.json` in global mode).\n\n> **Generation filter: per-server `enabled`.** Set `\"enabled\": false` on a server (in the shared map or a tool-scoped block) to keep the definition in the source file while emitting it to **no** tool config at all — a temporary off switch that does not lose the entry. Omitted means enabled, so existing configs keep generating everything; writing `\"enabled\": true` is opt-in clarity. This is distinct from the canonical `disabled`, which is a **pass-through** field the tools read (written as `disabled: true`, or translated to each tool's own spelling): `enabled: false` wins and drops the server entirely, while `disabled` only matters for servers still emitted. The field is rulesync-source-only and never reaches generated output — several tools (OpenCode, Kilo, Grok CLI, Goose) have a native `enabled` field with different semantics — and import never invents it: a tool's native enabled/disabled state keeps mapping to the canonical `disabled` (though a stray hand-written `enabled` in a passthrough-imported tool file does come back as the canonical filter). Two edges to know: a tool-scoped entry **replaces the shared entry wholesale**, so a same-named tool-scoped entry without `enabled: false` re-emits the server for that tool (per-tool re-enabling); and on merge-style shared configs (e.g. Hermes Agent's `config.yaml`), disabling a previously generated server stops writing it but does not remove the already-written entry — same as deleting the definition.\n\n> **Deprecated: per-server `targets`.** The older per-server `\"targets\": [\"tool\", ...]` array is still honored as a filter (a missing value or `[\"*\"]` means every tool), but it is deprecated and logs a warning at generate time. Migrate by moving the server into the matching `{toolname}.mcpServers` block(s).\n\n> **JetBrains AI Assistant note:** Rulesync writes the native `{ \"mcpServers\": { ... } }` configuration to `.ai/mcp/mcp.json` in project mode and `~/.ai/mcp/mcp.json` in global mode. Both scopes support STDIO and remote server entries using the shape documented in [JetBrains AI Assistant's MCP guide](https://www.jetbrains.com/help/ai-assistant/mcp.html).\n\n#### JSON Schema Support\n\nRulesync provides a JSON Schema for editor validation and autocompletion. Add the `$schema` property to your `.rulesync/mcp.jsonc`:\n\n```json\n{\n  \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json\",\n  \"mcpServers\": {}\n}\n```\n\n### Transport types (`type` / `transport`)\n\nThe `type` (and the equivalent `transport`) field accepts `local`, `stdio`, `sse`, `http`, `ws`, and `streamable-http`. `streamable-http` is the MCP specification's name for the HTTP transport and is accepted as an alias of `http`, so configurations copied from a server's documentation work unchanged. `ws` is the WebSocket transport (a persistent bidirectional connection) and accepts the same `url`/`headers`/`headersHelper`/`timeout` fields as `http`. Tools that do not recognize a given transport keep it on round-trip but may ignore it at runtime.\n\n> **OpenCode skills note:** on import, Rulesync also reads the `skills.paths` array of `opencode.json` / `opencode.jsonc` (\"Additional paths to skill folders\") and scans each entry as an extra skill root, so skills a project keeps outside `.opencode/skills/` are no longer invisible to `rulesync import`. These roots are import-only — generation keeps writing to Rulesync's own managed root — and a skill of the same name found in a managed root still wins. Each entry is resolved against the directory the config was read from — the project root in project mode, `~/.config/opencode/` in global mode — which is what OpenCode itself does. An absolute path, or one that escapes that directory, is ignored, and a directory under a configured root that is not a skill is skipped with a warning rather than failing the run, since a configured root is arbitrary user territory. `skills.urls` is a remote-fetch surface and is out of scope for a file-based generator.\n\n> **Kilo Code note:** Kilo's MCP config uses its own native shape in `kilo.jsonc` (`type: \"local\" | \"remote\"`, `environment`, `enabled`, `command` as an array). Rulesync maps `stdio`/`local` ⇄ Kilo `local` and `http`/`sse` ⇄ Kilo `remote`; on import, Kilo `remote` is normalized to the canonical `http` transport (the deprecated `sse` is no longer emitted). The Kilo-specific `timeout` (local + remote, a positive integer in milliseconds) and `oauth` (remote only — either an OAuth-config object or `false` to disable auto-detection) fields are preserved on round-trip. The `kilo.jsonc` `skills` config key (`skills.paths` for extra skill locations and `skills.urls` for remote skill manifests) is likewise preserved when Rulesync writes the file. A bare `{\"enabled\": false}` entry — Kilo's way of switching off a server another config layer defines, such as the global config or a marketplace — round-trips as itself: it imports as a canonical server carrying only `disabled: true`/`disabled: false` and no transport, and a server in that shape is written back as `{\"enabled\": …}` rather than as a local server with an empty command it cannot start. The enabled state has to be stated outright in both directions: for a transport-less server that says nothing about `disabled`, a toggle already in `kilo.jsonc` is left exactly as it is, and if there is none the server is skipped with a warning — a toggle overrides the layer that defines the server, so writing `enabled: true` for it would switch back on what you turned off there. Kilo's per-tool `enabledTools`/`disabledTools` reach the generated file at all now — they used to be stripped before this adapter saw them, so a filter read out of `kilo.jsonc` was deleted from it on the next generate. A skipped server's filters are written to the `tools` map either way, since that map is keyed by server name and reaches servers `mcp` does not list; on import, a `tools` entry naming no listed server comes back as a server carrying nothing but the filters, so it survives the round-trip. A server with no transport — a toggle, or one of those filter-only entries — is imported into the tool-scoped `kilo.mcpServers` block rather than the shared `mcpServers` map, because an entry with no command and no url is a server the other tools' configs cannot start. All of this applies equally to OpenCode: its published schema carries the same bare-toggle union member, it round-trips a toggle as itself under the same explicit-state rule, its `tools` map works the same way, and its transport-less servers land in `opencode.mcpServers`. The entry must carry no field of a local or remote server (`type`, `command`, `url`, `headers`, `environment`, `cwd`, `timeout`, `oauth`); an entry that is malformed in some other way still fails loudly rather than being quietly read as a toggle and written back with its command, headers, or OAuth secrets gone, while an unrelated key Kilo adds later is accepted rather than failing the run (it is not carried across the round-trip, though — a toggle imports as its enabled state and nothing else). Since a toggle keeps nothing but its enabled state, a canonical server that declares no transport but still carries fields such as `args` or `env` is written as a toggle with those fields dropped and a warning naming them. A server that names a transport it cannot reach — a `type` with no `command`, an `http` with no `url` — is skipped with a warning instead, because `{\"type\": \"local\", \"command\": []}` is a server Kilo cannot start. An existing `kilo.jsonc` carrying that shape (earlier Rulesync versions wrote it) imports as a server with no transport rather than failing the run. The same applies to OpenCode, whose config uses the same shape. Rejecting it used to fail the whole `--targets kilo` run rather than the MCP feature alone, because `kilo.jsonc` is the file the rules feature writes too.\n\n> **Zed note:** Zed configures MCP servers under `context_servers` in its shared settings file (`.zed/settings.json` project, `~/.config/zed/settings.json` global — `%APPDATA%\\Zed\\settings.json` on Windows), whose value is an untagged shape with no `type` field: a stdio server is `{\"command\": <string>, \"args\", \"env\", \"timeout\"}`, a remote one `{\"url\", \"headers\", \"timeout\"}`, and an extension-provided one neither. Rulesync translates the canonical fields into those shapes instead of forwarding them verbatim (which used to hand Zed keys it silently ignores — most seriously `disabled: true`, which left the server **enabled**): `disabled: true` becomes `enabled: false` (and imports back as `disabled: true`), the `httpUrl` alias is normalized to `url`, an array `command` is flattened to Zed's single command string with the rest prepended to `args`, and canonical-only fields (`type`/`transport`, `alwaysAllow`, `trust`, `cwd`, `networkTimeout`, the Kiro lists) are dropped. Fields rulesync does not model — a remote server's `oauth` block, an extension server's `settings` — pass through untouched, so they are best authored in the tool-scoped `zed.mcpServers` block. A server Zed cannot start is skipped with a warning rather than written broken: an `sse` or `ws` server (Zed has neither transport), a remote server with no `url`, a local one with no `command`. A server with no transport at all is written as Zed's extension-provided variant, and on import such an entry lands in the tool-scoped `zed.mcpServers` block rather than the shared `mcpServers` map, since other tools cannot start it.\n\n> **Kimi Code note:** MCP servers are written to `.kimi-code/mcp.json` (project) and `~/.kimi-code/mcp.json` (global). Kimi Code supports stdio, HTTP, and SSE plus `env`, `cwd`, `headers`, `bearerTokenEnvVar`, `enabled`, `startupTimeoutMs`, `toolTimeoutMs`, `enabledTools`, and `disabledTools`; Rulesync preserves the canonical fields that Kimi accepts. Canonical `local` maps to stdio and `streamable-http` maps to HTTP. WebSocket servers are skipped with a warning because Kimi has no WebSocket transport. A `kimi-code` block may also carry `startupTimeoutMs` / `toolTimeoutMs`, which are **not** per-server: they become Kimi's `[mcp] startup_timeout_ms` / `tool_timeout_ms` defaults in the shared global `~/.kimi-code/config.toml`, applying to every MCP server including ones Rulesync did not write (a per-server value in `mcp.json` still wins). Global scope only, since `config.toml` has no project counterpart, and merged in place so the `hooks` and `permission` sections of the same file survive. The merge is per key: authoring only one of the two timeouts leaves a hand-written sibling alone, and dropping the override entirely leaves the section as it stands rather than deleting it — remove the keys from `config.toml` by hand if you want them gone. See the [Kimi Code MCP docs](https://moonshotai.github.io/kimi-code/en/customization/mcp.html) and [config-files reference](https://moonshotai.github.io/kimi-code/en/configuration/config-files.html#mcp).\n\n> **Hermes Agent note:** Hermes MCP servers live under `mcp_servers` in the shared `~/.hermes/config.yaml`. Rulesync preserves OAuth fields (`redirect_uri`, `redirect_host`, `redirect_port`, `client_id`, `client_secret`, and `scopes`) plus `idle_timeout_seconds`, `max_lifetime_seconds`, `ssl_verify` (`true`/`false` or a PEM CA-bundle path), `skip_preflight`, `keepalive_interval` (liveness ping cadence in seconds), `trust` (`full` or `untrusted`, where every write-capable tool call needs approval — copied verbatim, since Hermes reads any unrecognized value as `untrusted`), and the `sampling`, `elicitation`, and `identity_header` mappings (carried as opaque objects so new sub-keys keep working). A canonical `sse` server is written with Hermes's own `transport: sse` (v0.20.0) and imports back as `type: \"sse\"`; without it Hermes connects to a `url` server over Streamable HTTP, so the transport would silently change. Streamable HTTP is Hermes's default and stays implicit. On import, portable server fields remain in shared `mcpServers`; Hermes-only fields are isolated in the full `hermesagent.mcpServers.<name>` replacement block so they cannot leak to other targets.\n\n> **Devin note:** Since Devin v3000.3 (the Local 3.6 release), MCP servers live in a dedicated `mcpServers`-keyed file: `.devin/mcp_config.json` (project) and `~/.config/devin/mcp_config.json` (global, via `--global`). The file is MCP-only and rulesync-owned (rewritten whole, deletable), unlike the shared `.devin/config.json` that permissions and hooks keep patching in place. Rulesync no longer writes the legacy `config.json` `mcpServers` key — Devin auto-migrates it away on startup, so re-seeding it would fight the migration — but import still falls back to that key when no `mcp_config.json` exists, so pre-v3000.3 repos migrate cleanly. The gitignored personal override `.devin/mcp_config.local.json` is never read or written (it is covered by the derived `.gitignore`). See the [Devin MCP configuration docs](https://docs.devin.ai/cli/extensibility/mcp/configuration).\n\n> **Warp note:** Warp reads file-based MCP servers from `.warp/.mcp.json` (project) and `~/.warp/.mcp.json` (global). Warp spells the working directory `working_directory` (used for resolving relative paths), so the canonical `cwd` is translated to it on generate and back on import; a tool-native `working_directory` already on the server wins over `cwd`. See the [Warp MCP docs](https://docs.warp.dev/agent-platform/capabilities/mcp/).\n\n> **Takt note (partial / transport-allowlist only):** Takt does **not** have a project- or global-level registry of MCP server _definitions_. The concrete `mcp_servers` map (`command`/`args`/`env` or `type`/`url`/`headers`) is declared **per workflow step** inside individual workflow YAML files; there is no top-level `mcp_servers` key in `config.yaml`, and Takt's config loader hard-rejects unknown top-level keys (introduced with MCP support in [Takt v0.21.0](https://github.com/nrslib/takt/blob/main/CHANGELOG.md)). What `config.yaml` _does_ hold is the **default-deny transport allowlist** `workflow_mcp_servers: { stdio, sse, http }` — without it, workflow-defined MCP servers are refused regardless of how they are declared. So Rulesync emits **only** this allowlist into the shared `.takt/config.yaml` (project) / `~/.takt/config.yaml` (global), enabling exactly the transports your `.rulesync/mcp.jsonc` servers use (`local`/`stdio` ⇒ `stdio`; `sse` ⇒ `sse`; `http`/`streamable-http`/`ws` ⇒ `http`). The merge is in place — every other top-level key (`provider`, `provider_profiles`, …) is preserved and the file is never deleted. **Documented lossiness:** per-server names, commands, env, URLs, and headers are not representable in `config.yaml` and are intentionally **not** written; you still declare the concrete servers in your workflow YAML steps, and Rulesync only opens the transport gate that permits them. As a corollary, **import** cannot reconstruct server definitions from a transport allowlist and yields an empty `mcpServers` map. See the [Takt configuration docs](https://github.com/nrslib/takt/blob/main/docs/configuration.md).\n\n### MCP Tool Config (`enabledTools` / `disabledTools`)\n\nYou can control which individual tools from an MCP server are enabled or disabled using `enabledTools` and `disabledTools` arrays per server.\n\n```json\n{\n  \"mcpServers\": {\n    \"serena\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/oraios/serena\", \"serena\", \"start-mcp-server\"],\n      \"enabledTools\": [\"search_symbols\", \"find_references\"],\n      \"disabledTools\": [\"rename_symbol\"]\n    }\n  }\n}\n```\n\n- `enabledTools`: An array of tool names that should be explicitly enabled for this server.\n- `disabledTools`: An array of tool names that should be explicitly disabled for this server.\n\n> **Kiro note:** Kiro MCP servers are written under `mcpServers` in `.kiro/settings/mcp.json` (project) and `~/.kiro/settings/mcp.json` (global). Kiro supports `disabledTools` natively and Rulesync preserves it on generate and import. Kiro does not expose a corresponding per-server `enabledTools` allowlist, so that field is omitted for Kiro targets. The two Rulesync-only authoring keys are translated onto the field names Kiro actually reads: `kiroAutoApprove` becomes `autoApprove` (tools run without a confirmation prompt) and `kiroAutoBlock` becomes `disabledTools` (tools hidden from the agent). A server that already spells `autoApprove` or `disabledTools` natively keeps working — the two lists are merged rather than one overwriting the other. On import, `autoApprove` is lifted back into `kiroAutoApprove`; `disabledTools` stays as-is because it is already a canonical Rulesync field with the same meaning, so `kiroAutoBlock` has no import counterpart. That makes `kiroAutoBlock` a redundant spelling of `disabledTools`: a Kiro config imported after a generate comes back as canonical `disabledTools`, which then also reaches the other targets that support it. Prefer authoring `disabledTools` directly, which makes that scope explicit from the start.\n\n> **Roo Code / Zoo Code note:** Both targets write `.roo/mcp.json` through the same adapter, and their per-server MCP schema is **denylist-only**: `disabledTools` clears each named tool's `enabledForPrompt` (the tool stops being offered to the model), and there is no corresponding `enabledTools` allowlist, so that field is omitted for these targets. The server config is emitted verbatim, so `disabledTools` round-trips as itself. Earlier Rulesync versions stripped it before the adapter saw it, which meant a filter you had written into `.roo/mcp.json` by hand — or through Zoo Code's own tool toggles, which write the same key — was deleted on the next generate.\n\n> **deepagents note:** MCP servers are written to `.deepagents/.mcp.json` (project) / `~/.deepagents/.mcp.json` (global). Two translations apply, because dcode **drops an individual server it cannot validate** — the rest of the file still loads, so a mistake here is silent rather than loud. **Transports:** dcode accepts only `stdio`, `sse` and `http` (plus the aliases `streamable_http` / `streamable-http` → `http`), so canonical `local` is written as `stdio` and `streamable-http` as `http`; canonical `ws` has no counterpart and the server is skipped with a warning at generate time, where you can still see it. Whether the value lands under `type` or `transport` follows whichever key you authored — dcode reads the two interchangeably, and with neither set it infers `http` from a `url` and `stdio` otherwise. On import, both spellings of the `streamable_http` alias come back as canonical `http`. **Tool filters:** canonical `enabledTools` becomes `allowedTools` (dcode never reads `enabledTools`, and it ignores unknown keys silently, so forwarding the canonical name would be a no-op), while `disabledTools` carries its own name; each entry is a tool name or an `fnmatch` glob, and import lifts `allowedTools` back. Upstream rejects a server that sets **both** filters and rejects an **empty** list, and each case is resolved the way that does not hand the model more tools than your canonical config allows. Setting both is valid canonically — other targets apply the two lists independently — but has no form here, so the **server is skipped** with a warning rather than written without filters, which would leave it running with every tool including the denied ones. An empty `enabledTools` likewise **skips the server**, since an allowlist of nothing means no tools at all and dropping the key would publish all of them. An empty `disabledTools` is the one genuine no-op, so only that key is dropped (with a warning) and the server is still written. See the [MCP tools docs](https://docs.langchain.com/oss/deepagents/code/mcp-tools).\n\n> **Qwen Code note:** MCP servers are written to the `mcpServers` key of `.qwen/settings.json` (project) / `~/.qwen/settings.json` (global, via `--global`). Qwen supports stdio (`command`/`args`), SSE (`url`), and HTTP (`httpUrl`) transports. Rulesync maps the canonical per-server `enabledTools` ⇄ Qwen's `includeTools` (allowlist) and `disabledTools` ⇄ Qwen's `excludeTools` (denylist). Other top-level keys in `settings.json` are preserved on round-trip.\n\n> **Codex CLI server-name note:** Codex requires MCP server names matching `[a-zA-Z0-9_-]+`, so Rulesync auto-normalizes non-conforming names on generate (lowercase, runs of other characters become `_`, leading/trailing `_` trimmed) — e.g. `Postgres MCP - Production - Read Only` becomes `postgres_mcp_production_read_only`. If two names normalize to the same Codex name, the last processed server overwrites the earlier one (with a warning). A name with no representable characters at all (e.g. a fully Japanese name) falls back to a stable hash-derived name like `mcp_1a2b3c4d` instead of being dropped; rename the server in `.rulesync/mcp.jsonc` to pick a readable Codex name. This normalization is one-way: importing back from the generated `config.toml` yields the normalized name, not the original.\n\n> **Codex CLI key-translation note:** Codex's `[mcp_servers.<name>]` table reads its own field names, so the canonical fields are translated rather than forwarded. `headers` is written as `http_headers` (and imports back as `headers`), which Codex accepts only on a url-based server — on a stdio server it is a load error upstream, so the headers are dropped with a warning instead. The canonical millisecond timeouts become Codex's second-based ones: `timeout` ⇄ `tool_timeout_sec` (the default timeout for tool calls) and `networkTimeout` ⇄ `startup_timeout_sec` (initialize + list-tools), dividing by 1000 on generate and multiplying on import, so a sub-second remainder is emitted as a fraction. Codex also accepts `startup_timeout_ms`, which imports verbatim into `networkTimeout` unless the config sets `startup_timeout_sec` too — Codex prefers the seconds spelling when both are present, and so does Rulesync. The canonical `tools` array is **not** written: Codex declares `tools` as a table of per-tool approval settings (`tools.<tool>.approval_mode`), and an array where it expects a table is a hard deserialization error that takes the whole server entry down, so it is dropped with a warning — use `enabledTools` / `disabledTools`, which map onto Codex's `enabled_tools` / `disabled_tools`. For the same reason the approval table is never imported into the canonical model; it stays in `config.toml`, where the approval-preserving merge carries it across regenerates. Both timeouts must be non-negative: Codex builds a duration out of them and errors on a negative value, which fails the whole file, so such a value is dropped with a warning. Canonical fields Codex has no counterpart for (`type`/`transport` — Codex infers the transport from `command` versus `url` — plus `alwaysAllow`, `trust`, and the Kiro lists) are dropped silently; on import a server carrying a `url` and no `command` gets `type: \"http\"` restated, so a config read out of Codex still reaches the tools that branch on the transport. That restatement is one-way, like the server-name normalization: Codex's only remote transport is `streamable_http`, so a canonical `sse` (or `ws`, or `streamable-http`) server comes back from a round-trip as `http`. Fields Rulesync does not model, such as `env_http_headers` and `bearer_token_env_var`, pass through under their own names.\n\n### Codex-specific: pass shell env vars to MCP servers (`envVars`)\n\nCodex CLI supports a per-server array of shell env var names to inherit when launching the MCP server process. The source schema uses `envVars` (camelCase, matching the project convention used by sibling fields like `enabledTools`/`disabledTools`); the codex generator renames it to `env_vars` (snake_case) for codex's native `config.toml` format.\n\nThis is distinct from `env` (which is a literal `{name: value}` map) — `envVars` is a list of names whose **values come from the user's environment at runtime**. Both fields may coexist on the same server.\n\n```json\n{\n  \"mcpServers\": {\n    \"pal\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/BeehiveInnovations/pal-mcp-server.git\",\n        \"pal-mcp-server\"\n      ],\n      \"envVars\": [\"OPENAI_API_KEY\", \"OPENROUTER_API_KEY\", \"GEMINI_API_KEY\"]\n    }\n  }\n}\n```\n\nGenerated `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.pal]\ntype = \"stdio\"\ncommand = \"uvx\"\nargs = [\"--from\", \"git+https://github.com/BeehiveInnovations/pal-mcp-server.git\", \"pal-mcp-server\"]\nenv_vars = [\"OPENAI_API_KEY\", \"OPENROUTER_API_KEY\", \"GEMINI_API_KEY\"]\n```\n\nAn entry may also be an object naming the environment to read the variable from: `{ \"name\": \"REMOTE_TOKEN\", \"source\": \"remote\" }` reads it from the remote executor environment (and requires remote MCP stdio support), while a bare name and `\"source\": \"local\"` read from Codex's own environment. The object form is written to `config.toml` as an inline table, matching Codex's documented shape. Only `name` and `source` are accepted in that object — Codex rejects an unknown key there, and rejecting one server's entry would take the whole `config.toml` down with it, so Rulesync fails on the canonical file instead. For the same reason an entry that a `config.toml` already holds in some other shape is dropped with a warning on import rather than written into a `.rulesync/mcp.jsonc` the next generate would refuse.\n\n- Emitted only into the codex CLI output. Stripped from `RulesyncMcp.getMcpServers()` so it does not appear in other tools' generated configs (Claude Code, Kilo, OpenCode, Gemini CLI, Cursor, Cline, Junie, Factorydroid, Rovodev, etc.).\n- Use this for secrets and API keys you do not want literal-encoded into a committed `mcp.json`.\n- Precedence: codex CLI resolves these names from the user's runtime shell environment. If a name is also set in `env` (literal value), the codex CLI behavior is upstream-defined; see the [Codex configuration reference](https://developers.openai.com/codex/config-reference#mcp_serversid-env_vars) (last checked 2026-05-13) for the exact resolution rule.\n\n### Codex-specific: run a stdio server remotely (`experimentalEnvironment`)\n\nFor stdio servers, `experimentalEnvironment: \"remote\"` starts the server through a remote executor environment when one is available. It is written as `experimental_environment` in `config.toml`. Like `envVars`, it is stripped before every other tool's MCP config is written, so it cannot leak into a config that would not understand it — and for the same reason, a server config copied straight out of a `config.toml` may spell it `experimental_environment`, which is accepted and normalized on the way to Codex.\n\nSee the [Codex MCP reference](https://learn.chatgpt.com/docs/extend/mcp) for both fields.\n\n#### Codex-specific: OAuth client id (`oauth.clientId` → `client_id`)\n\nA server's `oauth` block is preserved in the canonical Claude Code shape (camelCase `clientId`), but Codex CLI reads the OAuth client id from snake_case `oauth.client_id`. Without it, `codex mcp login <server>` falls back to dynamic client registration and fails for providers that do not support it (e.g. Slack). The codex generator therefore **duplicates** `clientId` into a sibling `client_id`, keeping the camelCase key so tools that expect it keep working:\n\n```toml\n[mcp_servers.slack.oauth]\nclientId = \"1601185624273.8899143856786\"\nclient_id = \"1601185624273.8899143856786\"\ncallbackPort = 3118\n```\n\nOnly a string `clientId` is duplicated (a non-string value would not be a usable OAuth client id), and an explicit `client_id` already present in the source is left untouched. On import, `client_id` collapses back to the canonical `clientId` (and is dropped when both are present) so the round-trip stays stable.\n\n> **Grok CLI note:** MCP servers are written to a `[mcp_servers.<name>]` table in `.grok/config.toml` (project) / `~/.grok/config.toml` (global, via `--global`). The file is treated as shared Grok config: Rulesync only replaces the `mcp_servers` key and preserves every other table on round-trip, and it is never deleted. Unlike Codex CLI, Grok uses a literal `env` table (it does not support the `env_vars` runtime-passthrough list) and has no per-server tool allow/deny lists, so the only field rename is `disabled` (rulesync) ⇄ `enabled = false` (grok); an active server simply omits `enabled`. Servers with no environment variables are emitted without a dangling `[mcp_servers.<name>.env]` table (empty nested tables are stripped), and a server whose entire configuration would be empty is dropped with a warning.\n\n### Goose-specific: MCP servers as `extensions` (global) and open-plugin manifest (project)\n\nGoose configures MCP servers in two locations depending on scope:\n\n- **Global (`--global`):** MCP servers are written as **extensions** in the shared user config `~/.config/goose/config.yaml`. The schema is non-standard, so Rulesync maps canonical MCP fields to Goose's: `command` → `cmd` (an array `command` folds its tail into `args`), `env` → `envs`, `url`/`httpUrl` → `uri`, and `disabled: true` → `enabled: false`. The `type` is derived — `command` ⇒ `stdio`, a remote `url` ⇒ `streamable_http` (or `sse` when the canonical `type` is `sse`). Each extension also carries its own `name`. A canonical server with no `command` and no `url` is **skipped with a warning** rather than written as a `stdio` extension with no `cmd`, which Goose cannot start. Generation merges the `extensions:` block into the existing `config.yaml`, preserving other Goose settings (model, provider, ...), and the file is never deleted. The `extensions:` map itself is co-owned: Goose's own `builtin`/`platform`/`frontend`/`inline_python` extensions (`developer`, `memory`, ...) live there alongside MCP servers and are **carried over untouched**, as is any entry Rulesync cannot read as an MCP server, while every entry it positively identifies as one (`stdio`/`streamable_http`/`sse`) is Rulesync-owned, so a server deleted from `.rulesync/.mcp.json` is retracted with a warning naming it. Import mirrors this: a non-MCP extension type is skipped with a warning instead of being imported as a server (importing a `builtin` used to strip the type that makes it work). This location supports **both stdio and remote** (http/sse) servers.\n- **Project:** Goose v1.39.0+ discovers MCP extensions in **open plugins** at `<project>/.agents/plugins/<name>/.mcp.json` (and `~/.agents/plugins/<name>/.mcp.json` at user scope). Rulesync emits `.agents/plugins/rulesync/.mcp.json`, reusing the same `.agents/plugins/rulesync/` tree already used for Goose hooks. The manifest uses the **Claude-style** `{ \"mcpServers\": { \"<name>\": { \"command\", \"args\", \"env\", \"cwd\" } } }` shape. This manifest is **stdio-only** — it cannot express `url`/`headers`, so **remote (http/sse) servers are skipped with a warning** in project mode; sync them with `--global` to `~/.config/goose/config.yaml` instead. The `.mcp.json` manifest is owned by Rulesync and is deleted when no servers remain.\n\nSee the [Goose extensions docs](https://goose-docs.ai/docs/getting-started/using-extensions/) and [open-plugins MCP PR #9471](https://github.com/aaif-goose/goose/pull/9471).\n\n### Goose-specific: commands as recipes, subagents as custom agents\n\nGoose [recipes](https://goose-docs.ai/docs/guides/recipes/recipe-reference/) are reusable YAML workflow files. **Commands** map to top-level recipes at `.goose/recipes/<name>.yaml` (project) and `~/.config/goose/recipes/<name>.yaml` (global); the command body becomes the recipe `prompt`, `title` defaults to the file name and `description` to the rulesync `description` (falling back to `title`), `version` defaults to `1.0.0`, and any other recipe field round-trips through the rulesync `goose` section of a command.\n\nA recipe on disk is not invocable as `/name` on its own: Goose resolves slash commands from the `slash_commands` list in the user config (`~/.config/goose/config.yaml`), whose entries are `{ command, recipe_path }` pairs. In **global mode** Rulesync therefore registers every generated recipe there. `recipe_path` is written as an **absolute** path, because Goose resolves it with a bare `PathBuf::from(...)` on this code path (the tilde expansion used by `goose run --recipe` does not apply, so a `~/…` registration would never resolve), and the command name is lowercased, because Goose lowercases the typed command and compares it against the stored value verbatim. There is no project-level registration surface upstream, so project-scope recipes must still be run with `goose run --recipe`.\n\nThe list is co-owned: entries whose `recipe_path` points outside `~/.config/goose/recipes/` — and sub-recipes under `recipes/subagents/` — are carried over untouched, while **every** entry pointing directly into that directory is Rulesync-owned and recomputed on each `--global` generate. That retracts a deleted command's registration and drops the key once nothing is registered, but it also means a slash command you registered yourself (via Goose's own UI or `goose recipe`) for a recipe living in that directory is removed on the next generate — keep such recipes elsewhere, or author them in `.rulesync/commands/`. Command names must be unique, contain no spaces, and must not shadow a built-in command such as `/recipe`, `/compact`, or `/help`; Rulesync does not check the built-in names for you. See the [slash-command mapping in the Goose source](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/slash_commands/recipe_slash_command.rs).\n\n**Subagents** map to Goose's [custom agents](https://goose-docs.ai/docs/guides/context-engineering/custom-agents/) (v1.34.0+): Markdown files with `name` (required) / `description` / `model` frontmatter whose body is the agent instructions, invocable via `@name` or delegation. They are emitted to the goose-specific discovery dirs `.goose/agents/<name>.md` (project) and `~/.config/goose/agents/<name>.md` (global), so the output cannot collide with a future shared `.agents/agents/` target; `model` and unknown future fields round-trip through the rulesync `goose` subagent section. Earlier rulesync versions emitted subagents as sub-recipe YAML under `.goose/recipes/subagents/` — a location Goose's agent discovery never scans, so those files were inert; they are no longer generated (stale outputs stay gitignored but are not cleaned up automatically).\n\n### Vibe-specific: stdio `cwd` and MCP `[auth]` block\n\nVibe (mistral-vibe) MCP servers live in `[[mcp_servers]]` arrays of the shared `.vibe/config.toml`. In addition to the flat fields, Rulesync passes through the stdio `cwd` (working directory), a structured per-server `auth` block (Vibe v2.15.0+), and the four keys Vibe's `/mcp` panel writes back when you toggle a server or one of its tools — `prompt`, `sampling_enabled`, `disabled` and `disabled_tools`. Because `mcp_servers` is replaced as a whole array on each generate, a server Rulesync writes is seeded from the on-disk entry of the same name for exactly those keys, so a toggle you made in the TUI survives — unless your `.rulesync/mcp.json` states the value itself, which wins. `disabled_tools` is the canonical `disabledTools` under Vibe's spelling; `prompt` and `sampling_enabled` have no canonical equivalent and pass through as-is. The `auth` table is discriminated on `type`: `static` (`headers`, `api_key_env`, `api_key_header`, `api_key_format`) and `oauth` (`scopes`, `client_id` / `client_metadata_url`, `redirect_port`). Because Vibe rejects mixing legacy top-level static-auth keys with an explicit `[auth]` block, Rulesync suppresses the legacy keys (`headers`/`api_key_env`/`api_key_header`/`api_key_format`) whenever a server carries an `auth` block. Servers added outside Rulesync — through `vibe mcp add` (v2.23.0) or the `/mcp add` panel, both of which persist straight into this TOML — are preserved after the managed entries instead of being deleted by the array replace. The flip side: removing a server from `.rulesync/mcp.jsonc` no longer removes it from `config.toml`; delete it there too (or run `vibe mcp remove`). Deleting it from one scope may not be enough either: since v2.24.0 Vibe stacks the user and project layers and union-merges `mcp_servers` by name, so a server of the same name left in `~/.vibe/config.toml` still resolves after you remove it from the project file. See [mistral-vibe](https://github.com/mistralai/mistral-vibe) (`vibe/core/config/models.py`).\n\n> **GitHub Copilot (VS Code) MCP note:** the `copilot` target writes `.vscode/mcp.json`, which has three documented top-level sections: `servers`, `inputs` (secret prompts referenced as `${input:id}`) and `sandbox` (filesystem/network rules for sandboxed servers, added in VS Code v1.112). Rulesync owns and replaces only `servers`; the rest of the document — including any future top-level section — is read back and preserved on each generate. VS Code recommends committing this file, so dropping an `inputs` entry would leave `${input:…}` unresolvable and the affected servers would fail to start. If the existing file cannot be parsed, generate fails with an error rather than overwriting it. See the [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).\n\n> **Rovo Dev CLI MCP note:** Rovo Dev documents the per-server transport key as `transport` (`stdio` | `http` | `sse`), not the canonical `type`. Rulesync translates on the way out (`local` → `stdio`, `streamable-http` → `http`) and back on import; `ws` has no Rovo Dev equivalent, so those servers are skipped with a warning, and a `transport` value outside Rovo Dev's vocabulary is dropped on import rather than written into the canonical config, whose transport field is a strict enum. `disabled` is stripped from the servers that are written, since `mcp.json` is not where a Rovo Dev server is switched on and off — see the toggle handling below. `mcp.json` is written at both scopes: the global `~/.rovodev/mcp.json`, and in project mode the repo-committed `.rovodev/mcp.json` the Bitbucket Cloud Agentic Pipelines guide documents (pointed at via `mcp.mcpConfigPath`, which Rulesync now writes into the project `config.yml` for you: Rovo Dev's `mcpConfigPath` default points at the _global_ MCP file, so without the pointer the generated project `mcp.json` is never read. The pointer names one config instead of merging with the default, so it is written only when the project has a Rovo Dev server to run — one that targets `rovodev`, is not disabled, and names a `command`/`url` to start — since otherwise the project would trade the user's global servers for an empty file; writing it is logged, being the step that makes Rovo Dev start those servers. If the last such server is later removed or switched off, the pointer is not taken back out (Rulesync cannot tell its own past value from a user who typed the same string) but the now-empty result is reported with a warning. A `mcpConfigPath` already aimed somewhere else is left in place — it is the user's choice — and reported with a warning naming the file that stays unread. One value earns its own message in global scope: `~/.rovodev/mcp_config.json`, the default the settings reference documents, which Rovo Dev may therefore have written itself rather than the user choosing it. That is exactly the user this pointer exists for, so the warning says what to change and whether that file holds servers they would lose by changing it. The comparison recognizes the other spelling of the same home-directory file — an already-expanded absolute path — so a pointer that already names the generated file is not reported as unread, and a stale one still is. `$HOME/...` and `${HOME}/...` are deliberately not counted as correct: nothing in Atlassian's documentation says Rovo Dev expands environment variables in this setting, and a pointer that resolves literally reads no MCP servers at all, so that spelling gets a warning of its own asking for the `~` form instead. Global scope gets the same treatment, with the home-anchored value `~/.rovodev/mcp.json`, because Atlassian's own pages disagree about the default: the [settings reference](https://support.atlassian.com/rovo/docs/manage-rovo-dev-cli-settings/) documents `~/.rovodev/mcp_config.json`, while the [MCP guide](https://support.atlassian.com/rovo/docs/connect-to-an-mcp-server-in-rovo-dev-cli/) has servers registered in `~/.rovodev/mcp.json`. Under the first spelling the global file Rulesync writes is never read, so naming it explicitly is what makes the outcome the same either way; the value has to be home-anchored rather than repo-relative, since `~/.rovodev/config.yml` is read from whatever directory Rovo Dev runs in. That same disagreement is why the global pointer is **withheld** when `~/.rovodev/mcp_config.json` holds servers of its own — if the settings reference is the spelling in force, those are the servers Rovo Dev is running today, and naming `mcp.json` instead would stop them being read on every project on the machine. Rulesync does not write that file, so it could neither import them first nor put them back; it reports what it found and leaves the pointer for you to set once you have moved what you want to keep into `.rulesync/mcp.jsonc`. A `mcp_config.json` that cannot be parsed, cannot be read (a directory or a permission error at that path, which costs this one decision rather than aborting the run), or carries a shape Rulesync does not recognize all count the same way, since none of them can be shown to be empty; only an `mcpServers` map with no entries — or a literally empty `{}` — releases the pointer. Each of those reports also says what to do when the file turns out to hold nothing you need — set `mcp.mcpConfigPath` yourself, which Rulesync never overwrites, or change it if it is already set — so a file Rulesync cannot see inside is never a dead end. Writing the global pointer is a warning rather than a note, the project pointer changing one repository where this one changes Rovo Dev everywhere. The project file is not gitignored, since committing it is the point). A server the canonical config marks `disabled: true` is no longer dropped: its definition is written to `mcp.json` (minus the flag, which the file cannot express) and its name goes to `mcp.disabledMcpServers` in the sibling `config.yml` — the key Rovo Dev actually consults — where rulesync owns the toggle for the servers it manages while user keys (`allowedMcpServers`, ...) and disabled names for unmanaged servers survive. On import, names listed in `mcp.disabledMcpServers` come back as `disabled: true` on the matching servers; a `config.yml` that exists but cannot be parsed fails both directions closed (the import errors instead of silently re-enabling servers, and generate skips disabled definitions it cannot switch off). Since the project `mcp.json` is committed, prefer env-var references over literal credentials in server `env`/`headers`; note that rulesync owns the `mcpServers` map in that file, so servers hand-added there (rather than to `.rulesync/mcp.jsonc`) are replaced on the next generate. Rovo Dev's per-server `enable_instructions` — which opts the server's own initialization-response instructions into the agent's system prompt, and which Atlassian warns to \"only enable for MCP servers you trust, since the instructions become part of the agent's prompt and can influence its behavior\" — is authored as the Rulesync-only key `rovodevEnableInstructions` (Rovo Dev's own `enable_instructions` spelling is accepted too, so an entry copied out of Atlassian's docs works) and written out as `enable_instructions`; on import it is lifted back onto `rovodevEnableInstructions`. Only a literal `true` counts in either direction, since absent and `false` mean the same thing to Rovo Dev, and when both spellings are present on one entry the canonical key decides — so an explicit `rovodevEnableInstructions: false` overrides an `enable_instructions: true` left over from a copied example rather than losing to it. Every server that receives the flag is named in a warning on generate, since it is the one thing Rulesync writes that widens what steers the model. Like `musecodeMode`, the key is stripped from every other target's output — and here that matters more than tidiness: it decides whether a third-party server's text joins the model's prompt, so it must not reach a tool you were not writing about. See the [Rovo Dev MCP docs](https://support.atlassian.com/rovo/docs/connect-to-an-mcp-server-in-rovo-dev-cli/).\n\n> **Meta Muse Code MCP note:** Muse Code reads MCP servers only from the `mcp_servers` block of the **global** user settings file `~/.config/muse/settings.json` — no project-scoped MCP location is documented, so the `musecode` MCP target requires `--global`. Each server entry carries a `transport` discriminator: `stdio` servers get `command` (a single string), `args` and `env`, and remote servers become `transport: \"streamable_http\"` with `url`/`headers` (Muse Code's only documented remote transport). A server that states `sse` or `ws` — or carries a `ws://`/`wss://` URL with no stated type — is skipped with a warning rather than rewritten onto a transport it does not speak. A canonical `disabled: true` maps to Muse's `enabled: false` and back. The settings file must carry `\"schema_version\": 1` — Muse Code fails startup with `malformed settings file` without it — so Rulesync bootstraps the key when it creates the file and preserves an existing value; every other settings key is preserved on round-trip and the file is never deleted. There are no per-server tool allow/deny lists. Muse Code's per-server `mode` — `required` (its default) aborts the whole run when the server fails to start, `optional` skips it with a warning — is authored as the Rulesync-only key `musecodeMode` and written out as `mode`; on import a `mode` of `required` or `optional` is lifted back into `musecodeMode`, while any other value is dropped with a warning naming the server — keeping it would copy a Muse Code key into every _other_ target's generated config, since Rulesync's server schema is loose, and the next generate would drop it from the Muse Code side regardless. `musecodeMode` is stripped from every other target's output, so it is safe to leave on a shared server entry. See the [Muse Code extending docs](https://dev.meta.ai/docs/muse-code/extending.md) and [configuration docs](https://dev.meta.ai/docs/muse-code/configuration.md).\n\n> **Reasonix note:** MCP servers are written as `[[plugins]]` array-of-tables entries (Reasonix's MCP-compatible external plugins) in `reasonix.toml` (project) / `~/.reasonix/config.toml` (global, via `--global`). Each entry carries a `name` plus the standard transport fields: `type` selects the transport (`stdio` default — `command`/`args`/`env`; `http`, a.k.a. `streamable-http` — `url`/`headers`; `sse`, the legacy 2024-11-05 HTTP+SSE transport, written verbatim — Reasonix re-implemented it in v1.17.18, and collapsing it onto `http` pointed the client at Streamable HTTP so the server could not connect). The file is treated as shared Reasonix config: Rulesync only replaces the `plugins` key and preserves every other table (providers, ui, agent, …) on round-trip, and it is never deleted. Reasonix has no per-server tool allow/deny lists. The `trusted_read_only_tools` array (raw MCP tool names pre-seeded as trusted for planner/read-only use) is neither written nor imported: v1.17.18 retired it along with `default_tools_approval_mode`, `tools.<raw>.approval_mode` and `approvals_reviewer` — installing a server is the authorization decision now, and Reasonix ignores the key on load and strips it the next time it saves that entry. Importing it would put a Reasonix-only dead key into the canonical `mcpServers` that every MCP target writes out, so it would surface in `.mcp.json` and the rest. Note that Rulesync owns the `plugins` key, so the next generate drops the key from an older `reasonix.toml` as well; nothing is lost that Reasonix still reads. An MCP server whose transport Reasonix does not implement (`ws`, including a `ws://`/`wss://` URL that states no transport at all) is skipped with a warning rather than written as a `type` its loader rejects. Each entry also supports `startup_timeout_seconds` (a per-server cap on the background launch/authorization/`initialize`/`tools/list` sequence, overriding the global `mcp_startup_timeout_seconds`; `0` means defer to that global cap, and is preserved rather than dropped), `call_timeout_seconds` (a per-server MCP call timeout) and `tool_timeout_seconds` (a per-tool inline table keyed by raw MCP tool name). All three round-trip as passthrough fields on the canonical MCP server object rather than through a deep mapping. For the latter two there is no canonical counterpart at all; `startup_timeout_seconds` does have a near-equivalent in canonical `networkTimeout` (which Codex CLI deep-maps to its `startup_timeout_sec`), but canonical timeouts are milliseconds while Reasonix takes seconds, and Reasonix's meaningful `0` has no canonical spelling — so mapping it would either invent a value or lose one. Vibe's `startup_timeout_sec` passes through for the same reason. See the [Reasonix plugins guide](https://github.com/esengine/deepseek-reasonix/blob/main-v2/docs/GUIDE.md#plugins-mcp) and [SPEC.md](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md) (`[[plugins]]` schema).\n\n> **ZCode MCP note:** ZCode reads MCP servers from the `mcp.servers` block of its own JSON config: `<project>/.zcode/config.json` (project) and `~/.zcode/cli/config.json` (global, via `--global`). A stdio server carries `command`, `args` and `env`; a remote server carries `type` — `http` (what rulesync calls `streamable-http`) or `sse` — plus `url` and optional `headers`. ZCode's own page shows a JSON example for stdio servers only and describes remote ones through its UI (\"Service URL\" plus optional headers), so the remote JSON spelling used here is inferred from the configuration Z.ai documents for the other MCP clients it supports. A server with no stated transport and an `http(s)` URL is written as `type: \"http\"`, ZCode's default remote transport, while a `ws`/`wss` server is skipped with a warning rather than rewritten onto a transport ZCode does not implement. ZCode's per-server toggle is `enable`, which defaults to `true` when absent, so a canonical `disabled: true` is written as `enable: false` and lifted back on import. The file is shared ZCode config: rulesync only replaces the `mcp` key (preserving its non-`servers` siblings and every other top-level key such as `model`), never deletes the file, and fails closed rather than overwriting a `config.json` it cannot parse. ZCode's legacy `.agents/mcp.json` fallback — consulted only while the `.zcode` file of the same scope lists no server — is neither written nor imported, so a hand-maintained one is left alone. Because rulesync replaces the whole `servers` map, a server added to `config.json` by hand is dropped on the next `generate`; add it to `.rulesync/.mcp.json` instead. The project file is committable, so prefer `env` entries that reference environment variables over literal credentials. There are no per-server tool allow/deny lists. See the [ZCode MCP services docs](https://zcode.z.ai/en/docs/mcp-services).\n\n## `.rulesync/.aiignore` or `.rulesyncignore` (deprecated)\n\n> **Deprecation notice:** The `ignore` feature is deprecated in favor of the more expressive [`permissions` feature](#rulesync-permissions-jsonc). Existing ignore configurations, generation, import, conversion, and explicit `rulesync add ignore` scaffolding remain supported throughout Rulesync 14.x. Removal, if any, will be decided separately and will not occur before a future major release. `rulesync init` no longer enables or scaffolds ignore for new projects.\n\nRulesync continues to support a single legacy ignore list in either location:\n\n- `.rulesync/.aiignore` (preferred legacy location)\n- `.rulesyncignore` (older project-root location)\n\nRules and behavior:\n\n- You may use either location.\n- When both exist, Rulesync prefers `.rulesync/.aiignore` over `.rulesyncignore` when reading.\n- Explicitly running `rulesync add ignore` creates `.rulesync/.aiignore` when neither location exists.\n\nExample:\n\n```ignore\ntmp/\ncredentials/\n```\n\n### Migrating to permissions\n\nMove each ignore pattern into the `read` category of `.rulesync/permissions.jsonc` with the `deny` action:\n\n```jsonc\n{\n  \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json\",\n  \"permission\": {\n    \"read\": {\n      \"tmp/**\": \"deny\",\n      \"credentials/**\": \"deny\",\n    },\n  },\n}\n```\n\nThis is the closest replacement for preventing an agent from reading ignored paths — except for Zed, whose read-only tools are not permission-gated at all: there the replacement is `private_files`, which the ignore feature writes, so a `read` deny rule is dropped with a warning instead. If the old policy was also intended to prevent changes, repeat the patterns under `edit` and `write`. Target tools differ in the permission categories they can represent, so review the [Supported Tools and Features](./supported-tools.md) table and the tool-specific permission notes below before removing the old ignore feature from a multi-tool project.\n\n### Where ignore patterns are written per tool\n\nMost tools get a dedicated ignore file (for example `.cursorignore`,\n`.geminiignore`, `.clineignore`). Antigravity CLI is built on the same engine\nas Gemini CLI, so it reads the project-root `.geminiignore` file. Claude Code is the exception: it does not\nread a separate ignore file, so Rulesync writes the deny list into Claude\nCode's settings file as `permissions.deny` entries (`Read(<pattern>)`).\n\nReasonix has no ignore file either, so its deny list goes into the `[permissions]` table of the shared `reasonix.toml` (project) / `~/.reasonix/config.toml` (global, via `--global`) as `Read(<pattern>)` entries — the same Claude-Code-style rule syntax the permissions feature writes there. `deny` is used rather than `[sandbox].forbid_read` because deny rules take glob specifiers and are documented as \"a hard block in every mode\", while `forbid_read` takes absolute paths with no documented glob support. The file is shared with the MCP and permissions features: only `Read(...)` deny entries are replaced, every other table and deny entry is preserved, and the file is never deleted. When the permissions feature also manages the `Read` category its explicit rules win, and the overwrite is warned about. As with the MCP and permissions features, the file is re-serialized on write, so hand-written comments, blank lines, and key ordering in `reasonix.toml` are not preserved.\n\nKiro reads `.kiroignore` in project scope and `~/.kiro/settings/kiroignore` in user scope. The `kiro`, `kiro-cli`, and `kiro-ide` targets therefore support `--global` for the deprecated ignore feature, as do `reasonix` and `zed` (whose config files exist in both scopes), as well as `devin`; the remaining ignore targets are project-only.\n\nDevin writes the project file as `.devinignore` (reading the pre-rebrand `.codeiumignore` and `.windsurfignore` as import fallbacks, in that order — the docs list the three names side by side without defining a precedence, so the order is rulesync's own choice), and in global scope writes `~/.codeium/.codeiumignore`. Three things about that global path are worth knowing: it keeps the **legacy brand spelling** — the rename to `.devinignore` covered only the project file, so no `.devinignore` variant is written or read there, not even as a fallback; it is documented in the Devin **Desktop** docs tree rather than the Devin Local (CLI) one, which is why it sits outside `~/.config/devin` where the other global Devin paths live; and it is positioned as an **enterprise** feature for enforcing ignore rules across many repositories, not as a general per-user setting. See [the Devin ignore docs](https://docs.devin.ai/desktop/context-awareness/windsurf-ignore).\n\nZed has no ignore file: its deny list is the `private_files` array inside the shared settings file — `.zed/settings.json` in project scope and `~/.config/zed/settings.json` in global scope (`%APPDATA%\\Zed\\settings.json` on Windows). `private_files` is a worktree setting, and Zed layers default → user → project, so the key is honored in the user settings file too. The array is **owned wholesale by Rulesync**: it is replaced with the patterns from `.rulesync/.aiignore` on every generation, so a pattern deleted there is retracted from the file Rulesync writes instead of surviving forever. Note that this narrows what Rulesync's own layer contributes, not the effective set: Zed's shipped default and any other settings layer still add their own patterns (see below). When no patterns remain at all, the key is removed rather than written as `[]`. `private_files` is an `ExtendingVec`: each settings layer's value is appended to the one below it (`merge_from` calls `extend_from_slice`) instead of replacing it, and Zed ships a populated default (`**/.env*`, `**/*.pem`, …). Writing the key is therefore purely additive — an empty array would neither disable Zed's secret redaction nor mean anything at all — so omitting it is how Rulesync says it contributes nothing here. Every other key in the file — including the MCP `context_servers` and permissions `agent` blocks and unrelated editor settings — is preserved, and the file is never deleted.\n\nGoose retired `.gooseignore` upstream (\"removed some time ago in favour of other ignore things like gitignore etc\" — [goose#10343](https://github.com/aaif-goose/goose/issues/10343)), so rulesync no longer generates it; the replacement guidance is `.gitignore` plus tool permissions. Stale `.gooseignore` files from earlier versions stay gitignored but are not cleaned up automatically.\n\nCline's `.clineignore` is still emitted, but its own docs now title it \"deprecate soon\" and state it is not a security or access-control boundary — upstream's replacement direction is a Cline plugin enforcing via a `beforeTool` hook. Treat the matrix ✅ as a deprecated surface.\n\nHermes Agent uses a project-local `rulesync-ignore` plugin under `.hermes/plugins/`. It applies the canonical gitignore-style patterns through [`pre_tool_call`](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/#pre-tool-call) to `read_file`, `write_file`, and `patch` before execution, and filters ignored paths from `search_files` results through `transform_tool_result`. This is defense in depth around Hermes file tools; terminal commands and paths already present in conversation context are outside the plugin's enforcement surface. Hermes deliberately requires [explicit trust for project plugins](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins/), so run it from the trusted project root with that invocation opted in:\n\n```sh\nHERMES_ENABLE_PROJECT_PLUGINS=1 hermes\n```\n\nRulesync adds `rulesync-ignore` to `plugins.enabled` in `$HERMES_HOME/config.yaml` but deliberately leaves `$HERMES_HOME/.env` unchanged. Existing configuration is preserved, explicit `plugins.disabled` conflicts fail, and `--delete` retains the additive user-level activation.\n\nFor Cursor, Rulesync emits only `.cursorignore` — the file that **blocks access\nentirely** (semantic search, Tab, Agent, Inline Edit, and `@`-mentions). Cursor\nalso supports a second file, `.cursorindexingignore`, which excludes files from\n**indexing only** while keeping them accessible to the AI on demand. These two\nfiles mean _different_ things, and Rulesync's `ignore` feature models a single\ncanonical ignore list per tool with no per-pattern distinction between\n\"block access\" and \"exclude from indexing only\". Emitting the same patterns to\nboth files would be incorrect, so `.cursorindexingignore` is intentionally **not\ngenerated** (an intentional non-goal). Author it by hand if you need\nindexing-only excludes.\n\nBy default, Claude Code's deny list is written to the **shared**\n`.claude/settings.json` so that the policy can be committed and reviewed by\nthe team. This is intentional (see issue #1094), but it means that running\n`rulesync gitignore` will not add `.claude/settings.json` to `.gitignore` —\nthat file may also contain other shared Claude config you actively want to\ncommit.\n\nIf you would rather keep the deny list out of version control, opt into the\n**local** mode using the per-feature options object form:\n\n```jsonc\n// rulesync.jsonc\n{\n  \"targets\": [\"claudecode\"],\n  \"features\": {\n    \"claudecode\": {\n      \"ignore\": { \"fileMode\": \"local\" },\n    },\n  },\n}\n```\n\n| `fileMode`           | Output file                   | Tracked by git by default                             |\n| -------------------- | ----------------------------- | ----------------------------------------------------- |\n| `\"shared\"` (default) | `.claude/settings.json`       | Yes — meant to be committed and shared with the team. |\n| `\"local\"`            | `.claude/settings.local.json` | No — `rulesync gitignore` already excludes this file. |\n\n## `.rulesync/permissions.jsonc`\n\n`.rulesync/permissions.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/permissions.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nFor Hermes Agent imports, Rulesync treats a valid private `permissions.rulesync` block as provenance, then reconciles it with current native settings. `command_allowlist`, `approvals.deny`, and an enabled `security.website_blocklist` are authoritative for their mapped canonical rules, so hand edits replace stale generated values. A config with no private block still imports those native rules. Unmodeled `approvals`, `security`, `skills`, and `memory` settings remain under the `hermes` override; unrelated root settings such as `model` are not imported.\n\n`rulesync init` scaffolds a `codexcli` block with `approval_policy: \"on-request\"`, `approvals_reviewer: \"auto_review\"`, and `base_permission_profile: \":danger-full-access\"`. On generation, the profile value becomes Codex's top-level `default_permissions`.\n\nPermissions define which tool actions are allowed, require confirmation, or are denied. The canonical format uses **lowercase tool category names** and **glob patterns** mapped to permission actions.\n\n**Permission actions:**\n\n- `allow` -- Automatically permitted without user confirmation\n- `ask` -- Requires user confirmation before execution\n- `deny` -- Blocked from execution\n\n**Supported tool categories:** `bash`, `read`, `edit`, `write`, `webfetch`, `websearch`, `grep`, `glob`, `notebookedit`, `agent`, the all-tools key `*` (a rule written under it is meant for every tool, shell commands included; how faithfully each adapter carries it is described per tool below), and MCP-specific tool names (e.g., `mcp__puppeteer__puppeteer_navigate`)\n\nExample:\n\n```json\n{\n  \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json\",\n  \"permission\": {\n    \"bash\": {\n      \"git *\": \"allow\",\n      \"npm run *\": \"allow\",\n      \"rm -rf *\": \"deny\",\n      \"*\": \"ask\"\n    },\n    \"edit\": {\n      \"src/**\": \"allow\"\n    },\n    \"read\": {\n      \".env\": \"deny\",\n      \"credentials/**\": \"deny\"\n    }\n  }\n}\n```\n\n**Rejected keys.** Two kinds of key are refused when the source file is read, rather than being carried into generated configs:\n\n- A **blank key** (empty, or only whitespace), whether it names a pattern or a category. A blank pattern is a prefix of every command and a substring of every path, so a tool that honors it grants or denies everything, while a tool that filters it — Roo Code keeps only entries passing `cmd.trim().length > 0` — ignores it entirely. A blank **category** is worse still: every target reads categories by name, so nothing under it reaches any tool and the rules written there are silently dead. Rather than let each target decide, Rulesync rejects both on the source file.\n- A key named `__proto__`, `constructor`, or `prototype`. Rulesync strips these from every source document it parses, because assigning them would reach the prototype chain instead of the object, so such an entry could never reach a generated file. Rulesync names the offending path instead of dropping it in silence — in `.rulesync/permissions.jsonc`, `.rulesync/mcp.jsonc`, and `.rulesync/hooks.jsonc` alike.\n\nImporting removes a blank key rather than reproducing it: keeping one would write a source file the very next `generate` refuses — and that refusal is fatal for the whole file, so a single blank key carried over would take every tool's permissions with it. This applies to blank patterns and blank categories, in the shared `permission` block and in tool-scoped `{toolname}.permission` blocks alike, since importing OpenCode or Kilo routes their tool-only categories into the tool-scoped block. The one exception is the _patterns_ inside `vibe.permission`, whose categories hold `sensitive_patterns` objects rather than pattern maps, so the keys inside them are field names and are left alone; its category names are filtered like any other. Removals are reported in warnings naming the tool config they were read from and how many keys were dropped from each block — patterns and categories reported separately, because dropping a pattern can widen what the imported configuration allows (a blanket blank pattern may have been the only entry denying anything) while dropping a category only removes rules that were never going to be generated.\n\nWhen removing a blank pattern leaves a category with no rules at all, the category itself is removed rather than left as an empty object. An empty category means \"Rulesync manages this category and it has no rules\", which makes the next `generate` delete the entries the tool's own config already had; removing the category leaves them alone. When that empties a tool-scoped block outright, the `permission` key is dropped too — and with it the whole `{toolname}` block if nothing else was authored under it — so no empty override is left behind for the next reader to puzzle over. In a tool-scoped block the removal also changes what the block means, from \"override this category with nothing\" to \"inherit the shared block\"; that is deliberate, since the alternative is the next `generate` deleting rules written by hand in the tool's own config, and every removal is warned about.\n\n### Tool-scoped permission blocks (`{toolname}.permission`)\n\nThe shared `permission` block applies to every targeted tool. To scope rules to a single tool, add a tool-scoped `{toolname}` block with a `permission` record of the same shape — mirroring `{toolname}.hooks` in `.rulesync/hooks.jsonc` and `{toolname}.mcpServers` in `.rulesync/mcp.jsonc`:\n\n```jsonc\n{\n  \"permission\": {\n    \"bash\": { \"git *\": \"allow\", \"*\": \"ask\" },\n  },\n  \"claudecode\": {\n    \"permission\": {\n      // Replaces the shared `bash` category for Claude Code only.\n      \"bash\": { \"git *\": \"allow\", \"git push *\": \"deny\", \"*\": \"ask\" },\n    },\n  },\n}\n```\n\n- Categories are merged **per category**: a tool-scoped category replaces the shared category wholesale for that tool; shared categories it does not name still apply.\n- Any permissions-capable `--targets` name is accepted as a block key. `kiro-cli`/`kiro-ide` alias to the `kiro` key and `hermesagent` to `hermes` (matching the shared output file each writes).\n- OpenCode, Kilo, and Vibe keep their existing tool-native `permission` override semantics (bare action strings / tool-only categories / `sensitive_patterns` — see the tool-specific callouts below); their blocks are consumed by their translators instead of the central merge.\n\n#### JSON Schema Support\n\nRulesync provides a JSON Schema for editor validation and autocompletion. Add the `$schema` property to your `.rulesync/permissions.jsonc`:\n\n```json\n{\n  \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json\",\n  \"permission\": {}\n}\n```\n\nFor Claude Code, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in `.claude/settings.json` (project mode) or `~/.claude/settings.json` (global mode) using PascalCase tool names (e.g., `Bash(git *)`, `Edit(src/**)`, `Read(.env)`).\n\nClaude Code's file permission checks match only `Edit(path)` and `Read(path)` rules: a `Write(path)`, `NotebookEdit(path)` or `Glob(path)` rule \"is accepted but never matched by those checks, so Claude Code warns at startup for each allow, deny, or ask rule in one of these unmatched forms\" ([permissions docs](https://code.claude.com/docs/en/permissions), v2.1.210+). Rulesync therefore writes a canonical `write` or `notebookedit` rule that carries a pattern as `Edit(pattern)`, and a `glob` rule as `Read(pattern)`. A rule whose pattern is `*` is a tool-name rule with no path — it matches the tool everywhere and produces no warning — so it is still written as the bare `Write` / `NotebookEdit` / `Glob`. Entries an earlier Rulesync wrote in the warned form are replaced on the next generate, and so is a rewritten entry whose action changed, so flipping a rule from deny to allow never leaves the old deny behind to win. Rewriting a rule does **not** make Rulesync claim the `Edit` or `Read` namespace as a whole: a `Read(...)` deny the [ignore feature](#rulesyncignore) wrote, or an `Edit(...)` rule you added to `settings.json` by hand, is left alone unless the canonical config manages that category itself. Import stays tolerant of both forms, so an existing `settings.json` still round-trips; a rewritten rule comes back under `edit` or `read` rather than the category it was authored in, since that is the rule Claude Code actually applies. Note that this widens a `glob` **allow** rule: `Read(pattern)` permits reading the files' contents, not just listing their names — the docs prescribe the substitution, but author `glob` allow rules with that in mind. When two categories resolve to the same entry with different actions (`edit` allowing what `write` denies, say) both are written and Rulesync warns — Claude Code applies deny first, then ask, then allow. A rule under the all-tools `*` category has no Claude Code counterpart: a rule there names one tool, and no name stands for every tool, so `{\"*\": {\"rm *\": \"deny\"}}` is written as `*(rm *)` — an entry that carries the rule back on import but matches no tool while Claude Code runs. Rulesync warns about every such rule, since an inert deny beside a `Bash` allow reads as a restriction that is not there; write the rule under the categories it is meant for (`bash`, `read`, ...) to have Claude Code enforce it.\n\n> **Claude Code-only override (`claudecode` key):** Claude Code's `permissions` object also carries non-list fields with no canonical permission category — notably `defaultMode` (the session-start permission mode: `default` | `acceptEdits` | `plan` | `bypassPermissions`) and `additionalDirectories` (extra working directories). Add a tool-scoped `claudecode` override key alongside the shared block to author them: the fields under `claudecode.permissions` are merged into the settings `permissions` object and emitted **only** for Claude Code, while the shared `permission` block continues to drive the managed `allow`/`ask`/`deny` arrays. The block is a verbatim passthrough (so other/future `permissions` fields such as the org locks `disableBypassPermissionsMode`/`disableAutoMode` can be set too), but any `allow`/`ask`/`deny` placed inside it is ignored — rulesync owns those arrays. On import, the non-list `permissions` fields round-trip back into the `claudecode` override. Note that these fields are merged **additively** into the existing `settings.json` (so hand-added settings survive): removing a field from the `claudecode` override does not delete a value already written to `settings.json` — clear it there by hand.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git *\": \"allow\" } },\n>   \"claudecode\": {\n>     \"permissions\": { \"defaultMode\": \"acceptEdits\", \"additionalDirectories\": [\"../shared\"] },\n>     \"sandbox\": { \"network\": { \"allowedDomains\": [\"example.com\"], \"strictAllowlist\": true } },\n>     \"editorMode\": \"vim\",\n>     \"env\": { \"MY_VAR\": \"1\" }\n>   }\n> }\n> ```\n>\n> The same override key also carries `sandbox`, the sibling top-level settings subtree governing the sandbox commands run in (`sandbox.network.*`, `sandbox.filesystem.*`, `sandbox.credentials`, `sandbox.allowAppleEvents`, ...). It has no canonical permission category either — it constrains _how_ a permitted command runs rather than which commands are permitted — so it is a verbatim passthrough on the same terms, merged into the top level of `settings.json` and round-tripped back on import — except for the three paths naming an executable, covered by the Trust caveat below, which are dropped in both directions. The merge is recursive, unlike the flat `permissions` fields above: `sandbox` subtrees carry restriction lists (`network.deniedDomains`, `filesystem.denyRead`), so setting one flag under `network` must not drop the denials beside it. A sibling key at any depth survives; a list you author replaces the existing list rather than being appended to. **Scope caveat:** Claude Code honors a subset of `sandbox.*` only from user settings, managed settings and the `--settings` flag — `filesystem.disabled`, `network.strictAllowlist`, `network.tlsTerminate`, `credentials.allowPlaintextInject`, `credentials.awsPairs`, `credentials.sigv4` and `allowAppleEvents` — and ignores them in a repository's `.claude/settings.json` / `.claude/settings.local.json`. Rulesync therefore skips those keys when generating project scope (warning once per key) and emits them only under `--global`, so it never _writes_ a project-scope sandbox policy that does nothing. The same restriction applies **per entry** inside `credentials.files` and `credentials.envVars`: an entry with `\"mode\": \"mask\"` is ignored in a repository's settings file, so Rulesync drops just those entries at project scope (warning once per list) while keeping the `deny` entries in the same list, which every scope does honor. Values already in the file are left untouched — both ones you hand-wrote and ones an earlier Rulesync version generated — because the two cannot be told apart and clobbering your file would be worse; so an inert key committed before this behavior existed stays there until you remove it by hand. Import stays scope-agnostic. See the [sandboxing docs](https://code.claude.com/docs/en/sandboxing).\n>\n> **Any other key is a top-level `settings.json` key.** Everything in the `claudecode` block other than `permission`, `permissions`, `sandbox` and `hooks` is written straight to the top level of `.claude/settings.json` and round-trips back on import, so a setting Claude Code adds needs no Rulesync release to become authorable — `editorMode`, `emojiCompletionEnabled`, `workflowSizeGuideline`, `keybindingFlavor`, `env`, `model`, `alwaysThinkingEnabled` and anything after them all work the same way. The merge is recursive, like `sandbox`, so setting one key under `env` keeps the variables already in the file. `hooks` is excluded because the [hooks feature](#rulesynchooksjsonc) owns it, `permission`/`permissions`/`sandbox` because they have their own handling above, and `$schema` because it is an editor pointer rather than a Claude Code setting. **Scope caveat:** the [settings reference](https://code.claude.com/docs/en/settings-reference) documents a scope per key, and Rulesync skips a key the file it is writing cannot honor (warning once per key): keys scoped `User or managed` / `User, local, or managed` (`spellcheck`, `autoMode`, `vimInsertModeRemaps`, `pluginConfigs`, `sshConfigs`, `syncClaudeAiSkills`, ...) are skipped at project scope and emitted only under `--global`, while keys scoped `Managed` (`allowManagedHooksOnly`, `requiredMinimumVersion`, `strictKnownMarketplaces`, ...) or `Global config` (`diffTool`, `autoConnectIde`, `teammateDefaultModel`, ...) are skipped in both scopes, because neither file Rulesync writes is the file that reads them — set those by hand in the managed settings file or `~/.claude.json`. The alternate spellings `additionalMarketplaces` and `allowedMarketplaces` are resolved to their canonical keys (`extraKnownMarketplaces` and `strictKnownMarketplaces`) before that check, so an alias is treated exactly as the key it spells. **Trust caveat:** a permissions file is shareable — `rulesync fetch` copies `.rulesync/permissions.jsonc` out of another repository — so a file whose name promises restrictions must not be able to hand Claude Code a command to run. Rulesync therefore refuses the keys whose value _is_ an executed command, in both scopes and in both directions: `apiKeyHelper`, `awsAuthRefresh`, `awsCredentialExport`, `fileSuggestion`, `gcpAuthRefresh`, `otelHeadersHelper`, `policyHelper`, `processWrapper`, `statusLine` and `subagentStatusLine` are never written (warning once per key) and are silently dropped on import — author commands in [`.rulesync/hooks.jsonc`](#rulesynchooksjsonc), where a reviewer expects them, or set these by hand in `settings.json`. The same line applies inside `sandbox`, which has its own merge branch: `sandbox.ripgrep`, `sandbox.bwrapPath` and `sandbox.socatPath` each name an executable Claude Code runs, so they are refused in both scopes and dropped on import too. The scope caveat reaches inside `sandbox` as well: `sandbox.filesystem.allowManagedReadPathsOnly` and `sandbox.network.allowManagedDomainsOnly` are scoped `Managed`, so they are skipped in both scopes for the same reason the `Managed` top-level keys are — set them in the managed settings file by hand. Keys that widen what Claude Code trusts rather than running something themselves are still written, but every one of them is named in a single summary warning per file — one line listing each setting and what it affects, rather than a run of near-identical lines: `env`, `disableAllHooks`, `disableSkillShellExecution` set to anything but `true` (which re-opens inline shell execution a user setting had turned off), `enableAllProjectMcpServers`, `enabledMcpjsonServers` and `allowedMcpServers`, `autoMode`, `skipAutoPermissionPrompt` and `skipDangerousModePermissionPrompt`, `enabledPlugins` and `extraKnownMarketplaces`, `agent` and `outputStyle` (which replace the prompt and tools every session starts with), `httpHookAllowedEnvVars` and `allowedHttpHookUrls` (which relax what an existing HTTP hook may send and where), `claudeMdExcludes` (which drops the CLAUDE.md files its patterns match), `crossSessionInbound` set to anything but `hold` or `refuse` (which lets messages from your other sessions reach Claude), `modelOverrides` (which decides the inference profile a call is routed to), `skipWebFetchPreflight` set to anything but `false` (which turns off the WebFetch domain safety check), `remoteControlAtStartup` set to anything but `false`, `prUrlTemplate` (which rewrites the PR links Claude Code renders), `companyAnnouncements`, `permissions.additionalDirectories`, a `permissions.defaultMode` of `bypassPermissions`, `acceptEdits` or `auto`, and the `sandbox` paths that loosen the sandbox rather than naming something to run — `enabled`, `autoAllowBashIfSandboxed`, `allowUnsandboxedCommands`, `excludedCommands`, `allowAppleEvents`, `enableWeakerNestedSandbox`, `enableWeakerNetworkIsolation`, `ignoreViolations`, `filesystem.allowRead`, `filesystem.allowWrite`, `network.allowedDomains`, `network.allowMachLookup`, `network.allowUnixSockets`, `network.allowAllUnixSockets`, `network.allowLocalBinding`, `network.httpProxyPort` and `network.socksProxyPort`. The `allow*` lists are in that set because Claude Code merges a list across settings scopes rather than replacing it, so a project file can only ever add to them; their `deny*` counterparts, which restrict, are not. These warnings fire only on the value that actually loosens the policy, so authoring the restrictive one (`allowUnsandboxedCommands: false`, an empty `excludedCommands`) stays quiet. Each condition names the value that stays quiet rather than the one that warns, so a value of the wrong type — a `skipWebFetchPreflight` of `1` rather than `true` — is reported rather than passed over. `allowUnsandboxedCommands` and `autoAllowBashIfSandboxed` both default to `true`, and an explicit `true` is reported even so: a project `.claude/settings.json` outranks the user file, so writing it there re-opens what a user's `false` closed. `remoteControlAtStartup` is the one key whose _scope_ depends on its value — Claude Code honors a `false` from a project file but ignores a `true`, so a `true` is skipped at project scope and emitted only under `--global`. They are also emitted after the scope filter, so a path the scope drops is reported as skipped rather than as written. Every one of these warnings exists for the same reason: a value that arrived with a fetched override should be visible rather than silent. (`env` is warned about rather than refused because it has too many ordinary uses to drop, even though a value such as `NODE_OPTIONS` or `PATH` does run code.) As with `sandbox`, the filter only applies to what Rulesync writes: a value already in the file is left untouched, and removing a key from the override block does not delete the value an earlier generate wrote — clear it in `settings.json` by hand.\n\nFor OpenCode, this generates the `permission` object in `opencode.json` / `opencode.jsonc` (project mode) or `.config/opencode/opencode.json` / `.config/opencode/opencode.jsonc` (global mode), preserving other existing OpenCode config fields. OpenCode's `webfetch`, `websearch`, `todowrite`, `question`, and `doom_loop` keys accept only a single action string, so Rulesync emits their canonical `{ \"*\": \"allow\" }` form as `\"allow\"`. If one of these categories contains pattern-specific rules, Rulesync collapses them to the most restrictive action (`deny` > `ask` > `allow`) and logs a warning because OpenCode cannot represent those patterns; a map without `*` includes an implicit `ask` fallback so a narrow allowlist never becomes blanket `allow`, while an empty map becomes `deny` instead of falling through to OpenCode's default allow behavior.\n\n> **OpenCode-only override (`opencode` key):** OpenCode exposes permission categories that other tools do not understand (e.g. `external_directory`). Placing these in the shared `permission` block would push meaningless entries into Claude Code, Codex, etc. To scope them to OpenCode, add a tool-scoped `opencode` override key alongside the shared block — mirroring the tool-scoped override keys used by [hooks](#hooks) (`opencode.hooks`) and rules frontmatter. Categories under `opencode.permission` are merged on top of the shared block **per category** (the override wins) and are emitted **only** into `opencode.json` / `opencode.jsonc`; every other tool ignores them. Values may use a bare action string (`\"deny\"`) or, for OpenCode keys that support fine-grained matching, a pattern map (`{ \"*\": \"ask\" }`).\n>\n> ```jsonc\n> {\n>   \"permission\": {\n>     \"bash\": { \"git *\": \"allow\", \"*\": \"ask\" },\n>   },\n>   // Emitted only into opencode.json's `permission`; never leaks to other tools.\n>   \"opencode\": {\n>     \"permission\": {\n>       \"external_directory\": \"deny\",\n>     },\n>   },\n> }\n> ```\n>\n> On **import**, any OpenCode category that is not a shared canonical rulesync category (`bash`, `read`, `edit`, `write`, `webfetch`, `websearch`, `grep`, `glob`, `notebookedit`, `agent`, the all-tools key `*`, or an `mcp__*` tool name) is routed into the `opencode` override rather than the shared block, so a subsequent `rulesync generate` does not leak it into other tools.\n>\n> You may also override a **shared** category for OpenCode specifically (e.g. put `webfetch` under `opencode.permission` to give OpenCode a different value than the shared block sends to other tools). On generate this works as expected, but note the override is not round-trip stable for shared categories: re-importing the generated `opencode.json` classifies a shared category back into the shared block, so prefer expressing OpenCode-only categories here and keeping cross-tool categories in the shared block.\n\nFor Hermes Agent, permissions are written into the shared `~/.hermes/config.yaml` (global only). Canonical rules map onto the structures Hermes's runtime actually enforces:\n\n- `allow` patterns (all categories) → `command_allowlist`.\n- `bash` `deny` patterns → `approvals.deny` — Hermes's hard denylist, evaluated **before** `--yolo` / `approvals.mode: off`.\n- `webfetch` `deny` patterns → `security.website_blocklist.domains`.\n- Every `ask` rule, and `deny` rules in categories other than `bash`/`webfetch`, have no native per-pattern Hermes primitive; they survive only for round-trip (Rulesync also stores the full canonical config under a private `permissions.rulesync` key so `.rulesync/permissions.jsonc` reconstructs losslessly).\n\n> **Hermes-only override (`hermes` key):** Hermes exposes approval/security controls with no canonical permission category — e.g. `approvals` (`mode`, `cron_mode`, `mcp_reload_confirm`, ...), `security` (`allow_private_urls`, ...), `skills.write_approval`, `memory.write_approval`. Add a tool-scoped `hermes` override key alongside the shared block to author them; its contents are **deep-merged** into `config.yaml` (so an `approvals.mode` here coexists with the `approvals.deny` derived from canonical deny rules) and are emitted **only** for Hermes. The block is a verbatim passthrough, so any current or future Hermes config key can be set without Rulesync modeling each one. Note that the deep merge replaces **arrays** wholesale, so setting `hermes.approvals.deny` or `hermes.security.website_blocklist.domains` overrides (does not append to) the list derived from the shared `permission` block — use it only when you intend to replace the canonical-derived deny list for Hermes. The top-level `permissions` key is reserved by Rulesync for the round-trip blob, so a `permissions` key inside the `hermes` override is ignored.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"rm -rf *\": \"deny\" } },\n>   \"hermes\": { \"approvals\": { \"mode\": \"smart\" }, \"security\": { \"allow_private_urls\": false } }\n> }\n> ```\n\nFor Codex CLI, this generates a `rulesync` named profile in `.codex/config.toml` under `[permissions.rulesync]` and sets `default_permissions = \"rulesync\"` (project/global depending on mode). It also generates `.codex/rules/rulesync.rules` from `permission.bash` entries using `prefix_rule(...)`. Current Rulesync-to-Codex mapping supports `bash`, `read`, `edit`/`write`, and `webfetch` categories:\n\n- `bash`: generates one `prefix_rule(...)` per command pattern in `.codex/rules/rulesync.rules` (`allow` → `allow`, `ask` → `prompt`, `deny` → `forbidden`)\n- `read`: `allow` → `read`, `ask`/`deny` → `deny` in `permissions.<profile>.filesystem`\n- `edit` / `write`: `allow` → `write`, `ask`/`deny` → `deny` in `permissions.<profile>.filesystem`\n- `webfetch`: `allow`/`deny` map to `permissions.<profile>.network.domains` (Codex does not support `ask` for domain rules); `network.enabled = true` is emitted only when at least one `allow` rule is present. Deny-only domain sets are emitted without `enabled`, which Codex treats as restricted (its default) while the deny entries still round-trip back into Rulesync rules. Codex rejects the global wildcard `*` in denied domains at config load time, so `webfetch: { \"*\": \"deny\" }` is skipped with a warning (unlisted domains are denied by Codex's allowlist-first policy anyway); `webfetch: { \"*\": \"allow\" }` is emitted as a regular `\"*\" = \"allow\"` domain entry, which Codex accepts for denylist-only setups ([openai/codex#15549](https://github.com/openai/codex/pull/15549)). On import, `deny` entries are always taken, while `allow` entries are imported only when `enabled = true` is explicit — Codex treats a missing `enabled` as restricted, so importing an allow entry from a disabled profile would activate a grant Codex never had. A Codex profile with `network.enabled = true` but no `domains` is imported as `webfetch: { \"*\": \"allow\" }`, which reflects Codex's default semantics where `enabled = true` grants sandbox-wide network access (under Codex's experimental `network_proxy` feature, `enabled = true` without an allowlist blocks requests instead, and the regenerated `\"*\" = \"allow\"` entry is the closest equivalent).\n\nRelative filesystem globs such as `src/**` or `**/*.tf` are emitted under `permissions.<profile>.filesystem.\":workspace_roots\"` instead of the top-level filesystem table, because Codex expects top-level filesystem keys to be absolute paths, `~/...`, or named roots. Rulesync also sets `glob_scan_max_depth = 8` when generated workspace-root rules contain unbounded `**` patterns.\n\nThe `:workspace_roots` table also receives a default `.git` carve-out: `\".git/**\" = \"write\"`. Codex's `:workspace` baseline keeps `.git` read-only inside workspace roots, which denies basic git workflows (commit/stage operations write to `.git/index`, `.git/objects`, refs, and logs; everyday commands such as `git remote add`, `git push -u`, and local-scope `git config` write to `.git/config`). The write rule reopens the whole subtree, including `.git/config` — an earlier `\".git/config\" = \"read\"` security guard (a writable `.git/config` lets a sandboxed process set keys like `core.fsmonitor` or `core.hooksPath` that execute code outside the sandbox) was dropped because it blocked those everyday commands while the protection it added was already partial (`.git/hooks/`, and `.git/modules/**` for submodules, remains writable so hook managers such as lefthook and simple-git-hooks keep working; a sandboxed process could still install a hook directly). Users who want stricter isolation can author a more specific rule (e.g. `read: { \".git/config\": \"allow\" }` or `read: { \".git/hooks/**\": \"allow\" }`) in the canonical permissions, which wins over the default (Codex resolves the more specific path with priority). Because `.git/**` is an unbounded `**` pattern, the carve-out also means `glob_scan_max_depth = 8` is effectively always emitted unless it is suppressed.\n\nThe carve-out is skipped in three cases: a user rule for the same pattern always wins per key; the `codexcli.git_write_rules` override set to `false` suppresses it entirely (only an explicit `false` does; the default is `true`); and it is not injected when `codexcli.base_permission_profile` is `\":read-only\"` (it would grant `.git` write access inside a sandbox the user explicitly chose to keep read-only) or when the canonical rules contain a direct `\":workspace_roots\"` pattern (a whole-tree access decision that the defaults must not override). Like `:minimal`, the default-valued carve-out is not imported into the Rulesync model on `rulesync import` — it is re-added on every generate — while customized `.git` values import normally. One limitation: the `git_write_rules` flag itself cannot be recovered from `config.toml`, so it does not round-trip through `rulesync import`; if you opted out with `false`, re-add the flag to the canonical permissions config after importing (and if you want the same `.git` rules while opted out, author them as canonical `read`/`write` rules rather than hand-writing them in `config.toml` — though note that import cannot tell a user-authored `\".git/**\" = \"write\"` from the default carve-out, so that exact pattern/value pair is still skipped on import and must be re-authored in the canonical config afterwards). Migration note: configs generated before the `\".git/config\" = \"read\"` default was removed still carry that entry, and `rulesync import` now treats it as a user-authored rule — it lands in the canonical config as `read: { \".git/config\": \"allow\" }` and, because Codex gives the more specific path priority, keeps `.git/config` read-only on every regenerate. If you want the current writable default instead, delete that rule from the canonical permissions after importing.\n\nThe generated `[permissions.rulesync]` profile always extends one of Codex's built-in permission profiles via `extends`. The baseline is chosen with the `codexcli.base_permission_profile` override key (`\":read-only\"` | `\":workspace\"` | `\":danger-full-access\"`) and defaults to `\":workspace\"` when unspecified. Codex's built-in `:workspace` baseline grants read access to the whole filesystem and write access to the entire workspace root plus `/tmp` and `$TMPDIR` (with carve-outs protecting `.git`, `.codex`, and `.agents`), while `:read-only` keeps command execution read-only; the generated `filesystem` entries then grant or deny access on top of the chosen baseline. Codex's third built-in profile, `:danger-full-access`, is rejected by `extends` at Codex config load time — so selecting it works differently: Rulesync emits `default_permissions = \":danger-full-access\"` directly and skips the managed `[permissions.rulesync]` profile entirely (with the sandbox removed there is nothing for filesystem/network rules to refine; canonical `read`/`edit`/`write`/`webfetch` rules are ignored for Codex CLI with a warning, and any stale managed profile from a previous generate is pruned while sibling hand-written profiles are preserved). On import, a profile's `extends` value round-trips back into `codexcli.base_permission_profile` when it names one of the two extendable built-ins, and a top-level `default_permissions = \":danger-full-access\"` round-trips the same way; a custom parent profile is skipped and replaced by the managed baseline on regeneration (with a warning).\n\nRulesync emits `\":minimal\" = \"read\"` in the generated filesystem table by default. This enables `include_platform_defaults()` ([FileSystemSpecialPath::Minimal](https://github.com/openai/codex/pull/13434)), which provides the platform/runtime read access needed for basic sandboxed command execution on macOS, Linux, and Windows. `:minimal` is the only special path treated as a fixed baseline: it is always present in the generated table and is never imported into Rulesync's own permission model, regardless of its value. A canonical rule for `:minimal` still overrides the emitted value on generate (e.g. a `write: { \":minimal\": \"allow\" }` rule emits `\":minimal\" = \"write\"` — see the [FAQ](../faq.md#codex-cli-denies-ssh-agent-access-temp-dir-writes-or-reading-its-own-config-with-a-generated-permissions-profile) for when that is needed), but because import always skips `:minimal`, such a customization does not round-trip: after `rulesync import`, re-author the rule or the next generate falls back to `\"read\"`. The other special paths `:root`, `:tmpdir`, and `:slash_tmp` are user-managed access rules that are imported into the Rulesync model and re-emitted from it like any ordinary filesystem entry (`:root = \"deny\"` becomes a read/edit deny, `:tmpdir = \"write\"` becomes an edit allow, and so on). Because they round-trip through `.rulesync/permissions.jsonc` rather than relying on an existing `.codex/config.toml`, a restrictive value such as `:root = \"deny\"` survives a fresh-clone `rulesync generate` with no pre-existing Codex config.\n\n`network.mode`, `network.unix_sockets`, and `description` have no equivalent in Rulesync's canonical permissions model and are not generated. If an existing `.codex/config.toml` already contains these fields on the `rulesync` profile, Rulesync preserves them on regeneration — as it does any other network key it does not model (e.g. `dangerously_allow_all_unix_sockets` or Codex's proxy keys), since network settings are user territory by design. `network.enabled` is only half-managed: Rulesync sets `enabled = true` itself when the canonical model contains an allow domain, but when a regeneration computes no `enabled` value, a user-authored `enabled` is preserved (with a warning) instead of being deleted — see the [FAQ](../faq.md#codex-cli-denies-ssh-agent-access-temp-dir-writes-or-reading-its-own-config-with-a-generated-permissions-profile) for the recommended user-managed entries. The preservation applies only when the existing profile carries no allow domain: an existing `enabled` next to allow domains is Rulesync's own managed output, so removing every webfetch allow rule from the canonical model removes `enabled` too (falling back to Codex's restricted default) instead of leaving an unscoped `enabled = true` behind. Note that `filesystem`, `network.domains`, and `extends` are always managed by Rulesync (`filesystem`/`network.domains` derived from `edit`/`write`/`webfetch` rules, `extends` from `codexcli.base_permission_profile`), so hand-authored values in those fields will be replaced on regeneration.\n\n> **Codex CLI-only override (`codexcli` key):** Codex CLI's permission surface is richer than the canonical allow/ask/deny model — its approval workflow, permission-profile baseline, and per-app tool gating have no canonical category. Add a tool-scoped `codexcli` override to author them: except for `base_permission_profile`, its fields are written verbatim as **top-level `.codex/config.toml` keys** (the override wins per key; existing sibling keys the user set directly are preserved, and table values are shallow-merged) while the shared `permission` block keeps driving the managed `[permissions.rulesync]` profile and `default_permissions`. Supported keys: `base_permission_profile` (`:read-only` | `:workspace` | `:danger-full-access`, default `:workspace` — not a top-level key; it becomes the managed profile's `extends` baseline, or with `:danger-full-access` the directly-selected `default_permissions` value, see above), `approval_policy` (`untrusted` | `on-request` (legacy alias `on-failure`) | `never`, or a `{ granular = { … } }` table kept verbatim; defaults to `on-request` when neither the override nor the existing config sets it), `apps` (per-app tool gating — `apps.<id>.tools.<tool>.approval_mode` / `.enabled`, `apps.<id>.default_tools_approval_mode`), `approvals_reviewer` (`user` | `auto_review` (legacy alias `guardian_subagent`), or a table; defaults to `auto_review` when neither the override nor the existing config sets it), `tui` (the `[tui]` table — e.g. `vim_mode_default = true` for the modal Vim composer added in Codex 0.129.0, and the `tui.keymap.*` bindings beside it; the shallow merge applies one level deep, so authoring `keymap` replaces the whole existing `[tui.keymap]` table rather than merging into it), and `git_write_rules` (boolean, default `true` — like `base_permission_profile` it is not a top-level key: it controls whether the managed profile's `:workspace_roots` table emits the default `.git` carve-out described above; only an explicit `false` suppresses it). **Deprecated:** `sandbox_mode` (`read-only` | `workspace-write` | `danger-full-access`) with the sibling `sandbox_workspace_write` table (`network_access`, `writable_roots`, …) belong to Codex's classic sandbox system, which permission profiles supersede — Codex prioritizes these legacy keys over permission profiles when both are present, so authoring them disables the generated `[permissions.rulesync]` profile; they are still accepted (with a warning) so existing configs round-trip, but use `base_permission_profile` and the shared `permission` block instead. On import, the top-level keys round-trip back into the `codexcli` override, and the managed profile's `extends` round-trips into `base_permission_profile`. It is a `looseObject`, so future top-level Codex config keys can be authored here (merged verbatim on generate; only the listed keys are re-extracted on import). Example: `{ \"permission\": { … }, \"codexcli\": { \"base_permission_profile\": \":workspace\", \"approval_policy\": \"on-request\", \"approvals_reviewer\": \"auto_review\" } }`. **Out of scope:** `mcp_servers.*` per-MCP gating is **not** authorable here — it is owned by the MCP feature (`codexcli-mcp.ts` writes the `mcp_servers` tables in the same `config.toml`), and `permissions` / `default_permissions` are owned by the canonical model; any such key placed in the override is skipped with a warning. See the [Codex configuration reference](https://developers.openai.com/codex/config-reference) and [permissions docs](https://developers.openai.com/codex/permissions).\n\nFor Kiro, this generates tool permission settings in `.kiro/agents/default.json` (project mode):\n\n- `bash` maps to `toolsSettings.shell.allowedCommands` / `toolsSettings.shell.deniedCommands`\n- `read` maps to `toolsSettings.read.allowedPaths` / `toolsSettings.read.deniedPaths`\n- `edit` / `write` map to `toolsSettings.write.allowedPaths` / `toolsSettings.write.deniedPaths`\n- `grep` maps to `toolsSettings.grep.allowedPaths` / `toolsSettings.grep.deniedPaths`\n- `glob` maps to `toolsSettings.glob.allowedPaths` / `toolsSettings.glob.deniedPaths` (both emitted only when a rule is present, so existing configs do not gain empty tables)\n- `webfetch` / `websearch` with pattern `*` map to `allowedTools` entries (`web_fetch` / `web_search`)\n- `ask` rules are skipped with a warning (Kiro config does not support explicit ask entries)\n\n> **Kiro-only override (`kiro` key):** Kiro's agent config exposes per-tool `toolsSettings` knobs with no canonical allow/ask/deny category. Author them through a tool-scoped `kiro` override under `toolsSettings`: the shell auto-trust flags `shell.autoAllowReadonly` / `shell.denyByDefault`, the `aws` built-in tool's `allowedServices` / `deniedServices` (+ `autoAllowReadonly`), and the `web_fetch` domain trust arrays `trusted` / `blocked` (regex host patterns; Kiro documents these for `web_fetch` only — `web_search` has no domain-trust surface). Example: `{ \"permission\": { … }, \"kiro\": { \"toolsSettings\": { \"shell\": { \"autoAllowReadonly\": true }, \"aws\": { \"allowedServices\": [\"s3\"], \"deniedServices\": [\"eks\"] }, \"web_fetch\": { \"trusted\": [\".*github\\\\.com.*\"] } } } }`. The override is **deep-merged per `toolsSettings` key** (the override wins at the leaf) so authoring `shell.autoAllowReadonly` keeps the canonical-generated `shell.allowedCommands`; the shared `permission` block keeps driving `shell.{allowed,denied}Commands`, `read`/`write`/`grep`/`glob` paths, and the `web_fetch`/`web_search` `allowedTools` toggles. Existing non-canonical `shell` flags are preserved across regenerate even without an override. On **import**, these Kiro-specific surfaces are lifted into the `kiro` override so they round-trip. It is a `looseObject` at every level, so future Kiro `toolsSettings` fields pass through verbatim. Kiro MCP `disabledTools` lives in the separate `.kiro/settings/mcp.json` file and is modeled by the MCP feature; MCP `autoApprove` remains outside this permissions translator. See the [Kiro built-in tools](https://kiro.dev/docs/cli/reference/built-in-tools/) and [configuration reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/) docs.\n\nFor Cursor CLI, this generates `permissions` entries in `.cursor/cli.json` (project mode) or `~/.cursor/cli-config.json` (global mode). Cursor CLI only supports `allow` and `deny` decisions, so `ask` rules are skipped with a warning. Tool categories are mapped to PascalCase Cursor tool names (`bash` → `Shell`, `read` → `Read`, `edit`/`write` → `Write`, `webfetch` → `WebFetch`, `mcp__*` → `Mcp`). Existing Cursor-specific entries that Rulesync does not manage (for example, MCP entries with extra fields) are preserved on round-trip. Note Cursor scopes the file asymmetrically — \"Only permissions can be configured at the project level. All other CLI settings must be set globally\" — so in project mode Rulesync contributes only the `permissions` key, and no longer stamps `version` or `editor.vimMode` there (both are written in global mode, where Cursor reads them). Content already in a project `cli.json` is passed through untouched either way, including a `version` an earlier Rulesync version stamped: Rulesync cannot tell a key it wrote from one you wrote, so it does not delete it.\n\n> **Cursor-only override (`cursor` key):** Cursor's `cli.json` carries scalar autonomy settings with no canonical permission category — `approvalMode` (`allowlist` | `auto-review` | `unrestricted`) and a `sandbox` object (`mode`/`networkAccess`). Add a tool-scoped `cursor` override to author them: its fields are merged into the top level of the config file while the shared `permission` block keeps driving the `permissions.allow`/`permissions.deny` arrays (the override cannot clobber that managed block). These settings are **global-only** upstream, so they are written only when generating with `--global`; in project scope they are skipped with a warning naming each one, rather than written into a `.cursor/cli.json` where Cursor would ignore them and the authored setting would silently never take effect. On import, `approvalMode` and `sandbox` round-trip back into the `cursor` override. It is a `looseObject`, so `sandbox`'s (currently undocumented) value set passes through verbatim and extra `cli.json` keys can be authored here (they are merged verbatim on generate); note that only `approvalMode` and `sandbox` are re-extracted on import.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git *\": \"allow\" } },\n>   \"cursor\": { \"approvalMode\": \"auto-review\" }\n> }\n> ```\n>\n> The separate Cursor **IDE** `permissions.json` (`mcpAllowlist`, `terminalAllowlist`, `autoRun.*`) is a different file and is not targeted by this translator.\n\nFor GitHub Copilot (`copilot`), this manages the three `chat.tools.*.autoApprove` maps in the workspace `.vscode/settings.json` (project mode only). VS Code has no standalone, environment-agnostic Copilot policy file, so project-level auto-approvals are configured through VS Code Copilot Chat's workspace settings. Three canonical categories have a clean, non-lossy mapping and are emitted: `bash` → `chat.tools.terminal.autoApprove` (command patterns), `edit` → `chat.tools.edits.autoApprove` (file globs) and `webfetch` → `chat.tools.urls.autoApprove` (URL patterns). In all three, `allow` → `true` (auto-approve) and `deny` → `false` (never auto-approve); an `ask` rule is represented by **omitting** the entry, so VS Code falls through to its default in-chat approval prompt. The canonical `read` category has no VS Code approval surface, and `write` is deliberately **not** folded into the edits map alongside `edit` — doing so would make the two indistinguishable on import — so neither is emitted. VS Code also accepts a `{ \"approveRequest\": …, \"approveResponse\": … }` object per URL pattern; that form has no canonical equivalent, so it is skipped on import, and because Rulesync owns the key outright it is replaced whenever the canonical config carries any `webfetch` rule. `.vscode/settings.json` is a general workspace file (JSONC), so Rulesync merges only those three keys non-destructively and never deletes the file; every unrelated setting is preserved. VS Code's user-scope `settings.json` lives at a platform-dependent path outside Rulesync's home-relative global model, so only project scope is supported. The all-or-nothing `chat.tools.global.autoApprove` boolean and the registry-allowlist `chat.mcp.access` setting are intentionally **not** mapped, since collapsing per-pattern rules into them would misrepresent what was configured. See the [VS Code agent approvals docs](https://code.visualstudio.com/docs/agents/approvals) and the [edit-approval docs](https://code.visualstudio.com/docs/copilot/chat/review-code-edits).\n\nFor Zoo Code (`zoocode`), this manages the two command lists `zoo-code.allowedCommands` and `zoo-code.deniedCommands` in the workspace `.vscode/settings.json` (project mode only). Zoo Code is a VS Code extension and has no policy file in its `.roo/` tree; these two settings are contributed without a `scope`, which in VS Code means they are settable per workspace, and `ClineProvider.mergeCommandLists()` unions the workspace values into the lists the auto-approval decision reads. Only the canonical `bash` category maps, since Zoo Code gates terminal commands and nothing else through these settings: `allow` → `allowedCommands`, `deny` → `deniedCommands`, and an `ask` rule is represented by **omitting** the pattern from both lists so Zoo Code falls through to its own approval prompt. Entries are matched as command **prefixes**, and Zoo Code resolves a command matching both lists by the **longer** prefix — auto-approval needs a strictly longer allowed match, and a denied match that is longer or equal auto-denies — so a pattern present in both lists imports as `deny`. Patterns are literal prefixes rather than globs: apart from a bare `*` (the one entry treated as a wildcard), a pattern such as `rm -rf *` is compared with `startsWith` and so never matches `rm -rf /`. Rulesync handles that mismatch by which way it fails. A glob- or regex-shaped **deny** fails open — the entry never matches, so the command stays auto-approved — so the literal prefix it pins down is **added alongside** it (`rm -rf *` also emits `rm -rf `, `/^curl /` also emits `curl `), which makes the deny take effect and denies at least everything the original named; the addition is reported at generate time so you can narrow it if it is wider than you meant. Your own pattern stays in the file, so importing the settings back does not quietly narrow the canonical rule and change what other targets generate from it. The added prefix comes back with it, though: importing from these targets leaves the derived entry in the canonical config alongside the pattern you wrote, and every other target then emits it too (`Bash(rm -rf *)` gains a `Bash(rm -rf )` beside it). It denies no more than the pattern it came from, so it is redundant rather than wrong — delete it from `.rulesync/permissions.jsonc` if you would rather not carry it. A deny that pins down no prefix at all is left as-is and reported as inert instead: `*.sh` would yield the empty prefix, which `startsWith` matches every command against, and an alternation such as `npm run (build|test)` names alternatives rather than a prefix — write one entry per alternative. A glob-shaped **allow** fails closed — it approves fewer commands than it looks like it does, and the rest reach the approval prompt — so it is passed through unchanged and only warned about. Only unambiguous matcher syntax counts here: `*`, grouping and alternation, a leading `^`, and **anchored** `/^…/` regex literals. Everything else is a literal prefix and is left strictly alone. That includes absolute command paths — `/bin/sh` and `/etc/init.d/x` have the shape of a regex literal but are commands, which is why the anchor is required — and shell syntax generally, since Zoo Code restores variables, brackets, braces and quoted strings verbatim before matching: `echo $HOME`, `[ -f x ]` and `mv a{,.bak}` really do match, and widening them would auto-deny far more than you wrote. Once the `bash` category is stated, Rulesync owns both keys, and the two empty cases differ because their contributed defaults do. An empty allow list is written as `[]`: Zoo Code reads the _effective_ setting value, and `allowedCommands` is contributed with the default `[\"git log\", \"git diff\", \"git show\"]`, so removing the key would silently re-grant those three auto-approvals. An empty deny list **retracts** its key instead: `deniedCommands` is contributed as `[]`, so nothing resurfaces, and because VS Code resolves array settings by scope precedence rather than by merging, writing `[]` per workspace would erase a deny list you hand-authored in your user-scope `settings.json`. A canonical config that states no `bash` category at all leaves both keys exactly as you wrote them. `.vscode/settings.json` is a general workspace file (JSONC) shared with the `copilot` target's `chat.tools.*.autoApprove` keys, so Rulesync merges only its own keys non-destructively and never deletes the file. VS Code's user-scope `settings.json` lives at a platform-dependent path outside Rulesync's home-relative global model, so only project scope is supported. The `zoo-code.*` namespace is Zoo-era (the v3.74.0 rebrand renamed it from `roo-cline.*`), so the `roo` target deliberately does not emit these keys and writes its own lineage's spelling instead — see the Roo Code paragraph below. See the [Zoo Code settings contributions](https://github.com/Zoo-Code-Org/Zoo-Code/blob/main/src/package.json).\n\nFor Roo Code (`roo`), this manages the same pair of command lists under the archived lineage's own spelling, `roo-cline.allowedCommands` and `roo-cline.deniedCommands`, in the workspace `.vscode/settings.json` (project mode only). The extension's package name is `roo-cline`, so that is the namespace its contributed settings live under; both keys are present in Roo Code's final release, v3.54.0, which is why they are in the `roo` target's scope rather than being a post-fork Zoo Code addition. The mapping is identical to Zoo Code's, and shares its implementation: only the canonical `bash` category maps, `allow` → `allowedCommands`, `deny` → `deniedCommands`, an `ask` rule is represented by omitting the pattern from both lists, once the category is stated an empty allow list is written as `[]` so the contributed `allowedCommands` default cannot resurface while an empty deny list retracts its key so a user-scope deny list survives, glob- or regex-shaped denies additionally emit the literal prefix they pin down (and are reported) while glob-shaped allows are passed through with a warning, and a canonical config stating no `bash` category leaves both keys untouched. Roo Code resolves a command matching both lists by the **longer** prefix — auto-approval needs a strictly longer allowed match, and a denied match that is longer or equal auto-denies — so a pattern present in both lists still imports as `deny`. Because `roo` and `zoocode` write different keys in the same file, enabling both targets leaves all four keys in `.vscode/settings.json` and neither adapter touches the other's pair; the general advice to pick one of the two targets per project still applies, since every other feature they share writes the same files. See the [Roo Code v3.54.0 settings contributions](https://github.com/RooCodeInc/Roo-Code/blob/v3.54.0/src/package.json).\n\nFor the GitHub Copilot CLI (`copilotcli`), this manages the two URL lists in the CLI's settings file: `.github/copilot/settings.json` (project mode, repository scope — the file [shipped in CLI v1.0.60](https://github.com/github/copilot-cli/blob/main/changelog.md)) and `~/.copilot/settings.json` (global mode, user scope). Only the canonical `webfetch` category maps: `allow` → `allowedUrls`, `deny` → `deniedUrls`, and an `ask` rule is represented by **omitting** the pattern, since the CLI prompts for any URL that is in neither list. No other category is emitted — the CLI's `permissions.allow`/`ask`/`deny` rule arrays are accepted only in MDM/enterprise managed settings, and interactive tool approvals are machine-written to `permissions-config.json`, so neither is authorable here. **Scope matters:** the repository-scope key table documents `deniedUrls` (union — a repository may add denials, never remove them) but **not** `allowedUrls`, so an allow rule is only enforceable at user scope; at project scope allow rules are dropped with a warning telling you to author them with `--global`, rather than being written to a key the CLI ignores (v1.0.79 additionally warns on startup about unknown top-level keys in the user `settings.json`, so Rulesync emits documented keys only there too). On import, a project-scope `allowedUrls` is likewise ignored so a dead entry does not become an enforced allow rule, and a pattern present in both lists imports as `deny`. `settings.json` also carries unrelated keys (`model`, `effortLevel`, `hooks`, `sandbox.*`, …), so Rulesync merges only the URL keys non-destructively and never deletes the file. See the [CLI config directory reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference).\n\nFor Kilo Code, this generates the `permission` object in `kilo.jsonc` (project mode) or `~/.config/kilo/kilo.jsonc` (global mode). The shape is identical to OpenCode's (Kilo is an OpenCode fork), so categories like `bash`, `read`, `edit`, `write`, `webfetch`, and `mcp` accept either a string catch-all (`\"allow\" | \"ask\" | \"deny\"`) or a `{ <pattern>: <action> }` map. Other top-level keys in `kilo.jsonc` are preserved on round-trip. **The `permission` object is merged per top-level tool key**: for each tool key present in the rulesync output, that key is replaced entirely from rulesync (rulesync owns its managed keys; manual edits inside a managed key will be overwritten on the next generation). Tool keys that exist in the existing `kilo.jsonc` but are NOT in the rulesync output are preserved verbatim so user-added Kilo-only categories survive regeneration. When a regenerate replaces a key whose existing value contained `deny` patterns that disappear from the new rulesync output, an aggregated `logger.warn` enumerates the dropped patterns (matching the project convention used by every other permissions translator). Edits to other top-level keys (e.g. `model`) are preserved. **Malformed `kilo.jsonc` aborts the run**: the `jsonc-parser` library would otherwise silently coerce a syntax error to `{}` and overwrite the corrupted file with an empty `permission`, dropping the user's existing `deny` rules. Rulesync now surfaces parse errors so the run aborts before any destructive write — matching the strict `JSON.parse` behavior used by every other permissions translator.\n\n> **Kilo-only override (`kilo` key):** Kilo's `permission` object carries tool-specific keys with no canonical permission category — OpenCode-inherited ones (`external_directory`, `doom_loop`, `lsp`, `question`, `todowrite`, `skill`, `task`, `list`) and Kilo-unique ones (`agent_manager`, `notebook_read`, `notebook_edit`, `notebook_execute`, `repo_clone`, `repo_overview`). Add a tool-scoped `kilo` override key alongside the shared block (mirroring the `opencode` override) to author these; entries under `kilo.permission` are merged on top of the shared block **per key** (the override wins) and are emitted **only** into `kilo.jsonc`. Each value may be a bare action string or a pattern map. On **import**, any Kilo key that is not a shared canonical category (`bash`, `read`, `edit`, `webfetch`, `websearch`, `grep`, `glob`, the all-tools key `*`, or an `mcp__*` tool name) is routed into the `kilo` override rather than the shared block, so a subsequent `rulesync generate` does not leak it into other tools.\n>\n> **Kilo-only override (`kilo.sandbox`):** the `sandbox` block Kilo runs commands in is a security surface orthogonal to per-tool allow/ask/deny, with no canonical category, so it is authored under the same tool-scoped `kilo` override: `enabled` (boolean), `network` (e.g. `\"deny\"`), `allowed_hosts` (a list of `host` / `host:port` destination exceptions) and `writable_paths`. It is shallow-merged into the top-level `sandbox` key of `kilo.jsonc` — the override's keys win, unrelated sibling keys you set directly are preserved — and the whole block round-trips back into `kilo.sandbox` on import. **Scope matters here.** Kilo honors `allowed_hosts` and `writable_paths` from the _global_ config only, and lets a project config merely tighten (`enabled: true`, `network: \"deny\"`); a project-level network denial even clears the global destination exceptions. Rulesync mirrors that rather than writing config Kilo would ignore: at project scope only `enabled` and `network` are emitted, and any other key is dropped with a warning telling you to author it with `--global`. See the [sandboxing docs](https://kilo.ai/docs/getting-started/settings/sandboxing).\n\n> **Name-mismatch traps.** Canonical category names do not always match Kilo's key names: Kilo folds **`write` into `edit`** (there is no `write` key), uses **`notebook_edit`** (not the canonical `notebookedit`) and **`task`/`agent_manager`** (not `agent`), and has **no `mcp` key** (MCP is addressed via `mcp__*` tool-name keys). Rulesync passes key names through verbatim, so author Kilo keys using Kilo's own names (e.g. put a `notebook_edit` rule under `kilo.permission`, not the canonical `notebookedit`). Kilo also treats a `null` action as a delete sentinel; Rulesync does not model `null` and only round-trips `allow`/`ask`/`deny`.\n\nFor AugmentCode CLI, this generates `toolPermissions` entries in `.augment/settings.json` (project mode) or `~/.augment/settings.json` (global mode). Each entry has `toolName`, an optional `shellInputRegex` (only for shell commands), and `permission.type` ∈ `\"allow\" | \"deny\" | \"ask-user\"`. Tool category mapping: `bash` → `launch-process`, `read` → `view`, `edit` → `str-replace-editor`, `write` → `save-file`, `webfetch` → `web-fetch`, `websearch` → `web-search`. Action mapping: rulesync `ask` → AugmentCode `ask-user`. For `bash` patterns other than `*`, the glob pattern is converted to a regex and emitted as `shellInputRegex`. The glob → regex conversion maps `*` to `.*`, `?` to `.`, escapes `\\^$.|+(){}[]`, and anchors at both ends; characters outside that set (notably `-`, `/`, `:`, `,`) are emitted verbatim, so Augment will match them literally. Generated entries are sorted **deny first, ask second, allow last**, with more specific patterns (those carrying `shellInputRegex`) before catch-alls — this is required because Augment's `toolPermissions` is evaluated **first-match-wins**. Existing `toolPermissions` entries whose `toolName` is NOT in the rulesync-managed set are preserved on round-trip; existing **`deny` entries for ANY managed `toolName`** (`launch-process`, `view`, `str-replace-editor`, `save-file`, `web-fetch`, `web-search`) are also preserved (fail-closed) so a user-added deny rule on any managed tool cannot be silently downgraded by regeneration. Existing managed-tool `allow` / `ask-user` entries are still replaced (rulesync owns the permissive surface for managed namespaces). **Non-bash categories do not have a documented per-input matcher in AugmentCode**, so Rulesync emits at most one catch-all entry per tool: if the rulesync category contains any `deny` rule, Rulesync emits a single `deny` entry for the entire tool (fail-closed) and warns; otherwise only `*`-pattern allow/ask rules are emitted and any non-`*` allow/ask patterns are dropped with a warning. Importing AugmentCode entries back into rulesync recovers `bash` patterns from `shellInputRegex` but the other categories always import as the catch-all `*` pattern. **The import direction also applies fail-closed precedence** when multiple existing entries collapse to the same `(canonical, \"*\")` key (e.g. `[{view: deny}, {view: allow}]`): the most restrictive action wins regardless of iteration order (precedence: `deny` > `ask` > `allow`), so a user-added deny in the source file is never silently dropped by import order. The `launch-process` (bash) path is unchanged because each entry has its own `shellInputRegex`-derived pattern with no `\"*\"` collapse. On **import** (project scope), Rulesync also reads the layered overrides file `<workspace>/.augment/settings.local.json` — a gitignored, machine-specific file that Auggie merges on top of `settings.json` — and combines it over the base settings before converting to the canonical model, following Auggie's documented layering (simple values take the local override, `mcpServers`/`plugins` replace wholesale, and other objects/lists — including `toolPermissions`, which Auggie concatenates local-first under first-match — are combined across tiers), so personal permission overrides are picked up without dropping a committed base `deny`. This overlay is **import-only and project-only**: Rulesync never writes `settings.local.json` (it stays a user-owned, gitignored file), and AugmentCode documents no global `~/.augment/settings.local.json`, so the overlay is skipped in global mode. Whatever the local file contributed is named in a warning while importing, so a personal value is visible before it is committed; a key that governs what the tool may run — a sandbox tier, an autonomy ceiling, the hooks it executes — is called out on its own, since publishing one machine's relaxed value makes it the team's. An unknown top-level key such as `recommendedMarketplaces` (added in Auggie CLI 0.20.0) is preserved verbatim through the generate round-trip via the `{...settings}` merge.\n\n> **AugmentCode-only override (`augmentcode` key):** AugmentCode's `toolPermissions[]` supports \"custom policy\" entries the canonical allow/ask/deny model cannot express — `permission.type` of `webhook-policy` / `script-policy` (delegating the decision to a `webhookUrl` / `script`) and an `eventType` of `tool-response` (a post-execution check rather than the default pre-execution `tool-call`). Author these through a tool-scoped `augmentcode` override with a `toolPermissions` array of verbatim entries: `{ \"permission\": { … }, \"augmentcode\": { \"toolPermissions\": [ { \"toolName\": \"github-api\", \"permission\": { \"type\": \"webhook-policy\", \"webhookUrl\": \"https://api.example.com/validate\" } }, { \"toolName\": \"view\", \"eventType\": \"tool-response\", \"permission\": { \"type\": \"allow\" } } ] } }`. Authored entries are **prepended** — ahead of the canonical-generated basic rules — so a webhook/script gate or tool-response check is never shadowed by a regenerated allow/deny/ask entry under first-match-wins. When the override authors `toolPermissions` it becomes the source of truth for the special entries (the existing file's specials are no longer separately preserved, avoiding a double-emit); without an override, any special entries already present in `settings.json` are preserved verbatim as before. On **import**, special entries are lifted verbatim into the `augmentcode` override (rather than being skipped with a warning) so they round-trip and become user-authorable; basic entries continue to drive the shared `permission` block. The entry objects stay a loose passthrough so `shellInputRegex`, `webhookUrl`, `script`, and future non-policy fields survive untouched, while the documented bounded fields are validated as enums: `permission.type` (`allow` | `deny` | `ask-user` | `webhook-policy` | `script-policy`) and `eventType` (`tool-call` | `tool-response`). Both project and global scope are supported.\n\nFor Factory Droid, this generates `commandAllowlist` / `commandDenylist` arrays in `.factory/settings.json` (project mode) or `~/.factory/settings.json` (global mode). Factory Droid only gates **shell commands** through these two lists, so the rulesync `bash` category is what is translated: `allow` patterns become `commandAllowlist` entries (run without confirmation) and `deny` patterns become `commandDenylist` entries (always require confirmation; the denylist wins when a command is in both). Factory Droid has **no separate `ask` list** — any command not in the allowlist already prompts — so rulesync `ask` rules write nothing, though an `ask` does withhold every `allow` that names any of the same commands (an `ask` on `npm *` withholds an allowed `npm publish`, an `ask` on `npm publish` withholds an allowed `npm *`, and an `ask` on `* --force` withholds an allowed `git *` even though neither pattern covers the other's spelling — the two overlap on every `git … --force` command), because canonically the stricter rule wins whatever its width, so auto-approving a command the file also asks about would answer the prompt the author wanted. The all-tools `*` category is read as well, but only for its **restricting** rules: a `deny` written there covers shell commands too, so it lands in `commandDenylist` — skipping it would auto-approve the very command the file blocks. A `bash` deny keeps the `allow` beside it, since the denylist outranks the allowlist and a `bash` pattern names a command by construction: `{\"bash\": {\"git *\": \"allow\", \"git push *\": \"deny\"}}` blocks the push and auto-approves the rest. A deny written under `*` is entered in the denylist too — for the case where it _is_ a command — but it **also** withholds the `allow` rules it covers, because a pattern there need not name a command at all: `{\"*\": {\"secrets/**\": \"deny\"}}` beside an allowed `*` would otherwise auto-approve every command while the denylist entry matches none of them. A `*` deny that had `allow` rules to overlap, overlapped none of them, and is not also written under `bash` is reported: nothing observed says it names a command, so the denylist entry may block nothing at all — write it under `bash` too if it is a command pattern. A config with no `allow` rules at all, or one that spells the same pattern under `bash` as well, is not reported, since neither says anything about whether the pattern names a command. A `bash` `ask` that withheld no `allow` is **not** reported: Droid prompts for whatever its allowlist does not cover, so an `ask` on a command no `allow` overlaps is already honored exactly as written. An `ask` under `*` writes nothing and withholds the same way a `bash` one does, but one that withheld nothing is reported on the same terms as the `*` deny above — a pattern there need not name a command, and withholding is the only way an `ask` can restrict here, so nothing observed says the rule does anything at all. Working out which `allow` rules a restriction overlaps is bounded work, so a configuration large enough to exhaust that budget stops comparing patterns and withholds **every** `allow` beside a restriction — the fail-closed direction, at the cost of auto-approving less than the config asked for — and says so in a warning. This read is one-way: import writes patterns back into the `bash` category only, never into `*`. Its `allow` rules are deliberately never carried over, since a pattern under `*` need not be a command at all (`secrets/**` there denies a path) — the skip is named in a warning rather than made silently; both directions therefore fail closed. Categories other than `bash` and `*` cannot be represented in the command allow/deny model and are skipped, with a `logger.warn` when a skipped category carries a `deny` or an `ask` rule (to surface the gap — a foreign `ask` restricts as surely as a foreign `deny`). rulesync owns the `commandAllowlist` / `commandDenylist` keys (they are replaced from the rulesync output), while every other key in `settings.json` (e.g. `hooks`) is preserved verbatim on round-trip — except the Factory-specific security keys covered by the `factorydroid` override below, which are lifted into that override on import. Importing reads the two lists back into the `bash` category, with `.factory/settings.local.json` overlaid on top of `settings.json` first — Droid layers the two, so importing without the overlay would read permissions it does not actually enforce. Rulesync never _writes_ `settings.local.json`; generation only ever writes `settings.json`. Note the consequence for a full round-trip: a value that came from the local file is imported into `.rulesync/permissions.jsonc` like any other, so the next `generate` writes it into the shared `settings.json`. If a personal override should stay personal, drop it from `.rulesync/permissions.jsonc` after importing. Whatever the local file contributed is named in a warning while importing, so a personal value is visible before it is committed; a key that governs what the tool may run — a sandbox tier, an autonomy ceiling, the hooks it executes — is called out on its own, since publishing one machine's relaxed value makes it the team's. Rulesync gitignores `.factory/settings.local.json` itself, matching Factory's guidance to keep it out of version control.\n\n> **Factory Droid-only override (`factorydroid` key):** Factory Droid has security controls that do not fit the per-command `allow`/`ask`/`deny` model — the hard-block `commandBlocklist` tier (commands that can **never** run, not even under full autonomy — distinct from an approvable `deny`), plus `networkPolicy` (`allowedIps`), `sandbox` (`enabled`/`mode`/`filesystem`/`network`), `mcpPolicy`, `enableDroidShield`, autonomy settings (`sessionDefaultSettings`, `maxAutonomyLevel`, `subagentAutonomyLevel`, `interactionMode`, and the per-tool `mcpAutonomyOverrides`), the plugin-bootstrap keys `extraKnownMarketplaces` / `enabledPlugins` (Droid auto-registers those marketplaces and installs those plugins on start — the upstream distribution path for the same artifacts rulesync generates), the `hooksDisabled` kill-switch, `disabledSkills` (an array of skill names to disable without deleting their files), and the organization controls `modelPolicy` and `missionPolicy`. Add a tool-scoped `factorydroid` override to author them: its keys are merged into `settings.json` (the override wins) while the shared `permission` block keeps driving `commandAllowlist`/`commandDenylist`. On **import**, these keys are lifted into the `factorydroid` override — so `commandBlocklist` now round-trips faithfully (its never-runs guarantee is preserved) rather than being collapsed onto an approvable `deny`.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git *\": \"allow\" } },\n>   \"factorydroid\": { \"commandBlocklist\": [\"curl *\"], \"sandbox\": { \"enabled\": true } }\n> }\n> ```\n\nFor Cline CLI, this generates `.cline/command-permissions.json` (project mode only). Cline reads this file via the `CLINE_COMMAND_PERMISSIONS` environment variable; you can wire it up with `export CLINE_COMMAND_PERMISSIONS=$(cat .cline/command-permissions.json)`. The schema is `{ \"allow\": [...], \"deny\": [...], \"allowRedirects\": false }`. Cline only supports shell commands and only `allow`/`deny`. Categories other than `bash` and the all-tools `*` are dropped, and `bash` `ask` rules are **translated to `deny`** (fail-closed safety, since Cline lacks `ask` semantics). The all-tools `*` category contributes its **restricting** rules — a `deny` written there covers shell commands too, so skipping it would auto-approve a command the file blocks — while its `allow` rules are never carried over, since a pattern under `*` need not be a command at all (the skip is named in the translation notice rather than made silently); both directions therefore fail closed. A `bash` `deny` is written to `deny` and keeps the `allow` beside it — [Cline documents that deny rules always take precedence](https://docs.cline.bot/cli/cli-reference), and a `bash` pattern names a command by construction — which is how a narrow `deny` carves an exception out of a wider `allow` (`git *` allowed, `git push` denied). A `deny` under `*` is written as well, but it **also** withholds the `allow` rules it covers, since a pattern there need not name a command: `{\"*\": {\"secrets/**\": \"deny\"}}` beside an allowed `*` would otherwise auto-approve every command while the `deny` entry matches none. A `*` deny that had `allow` rules to overlap, overlapped none of them, and is not also written under `bash` is reported the same way, since nothing observed says it names a command Cline can block. An `ask` under `*` is **not** translated: a pattern written there need not name a command, and denying it outright would turn the ordinary catch-all `{\"*\": {\"*\": \"ask\"}}` into a block on every command — one the additive `deny` merge below would then keep forever. It **withholds** the `allow` rules it covers instead (whatever the two patterns' widths, since canonically the stricter rule wins regardless of how wide it is), which leaves those commands prompting, exactly as an `ask` asks. A `*` ask that had `allow` rules to overlap, overlapped none of them, and is not also written under `bash` is reported: withholding is the only way it can restrict here, so nothing observed says the pattern names a command — write it under `bash` if it is one. One that withheld no `allow` at all is not reported, since the `allow` array below is a gate: a command no `allow` covers already prompts, which is what the ask asked for. Working out which `allow` rules a restriction overlaps is bounded work, so a configuration large enough to exhaust that budget stops comparing patterns and withholds **every** `allow` beside a restriction — the fail-closed direction — and says so in the translation notice. Note that Cline's `allow` array is a gate rather than a list of exceptions — once it is present, only the commands matching it run without approval — so a config whose every `allow` is withheld asks about every command. The `*` read is one-way: import writes patterns back into the `bash` category only, never into `*`. All of those translation notices are surfaced via a single aggregated `logger.warn` per generation (matching the project convention used by every other permissions translator) so the translation stays visible without tripping CI gates that treat error lines as failures. **The `allow` array is wholesale-replaced by rulesync** — user-added entries inside `allow` are not preserved on regenerate. **The `deny` array is additive** — user-added denies in the existing file are preserved on every generation alongside the rulesync-derived denies (fail-closed standard). The `allowRedirects` field (a single global boolean gating shell redirection operators `>`/`>>`/`<`) can be authored from rulesync via a tool-scoped **`cline` override** — add `\"cline\": { \"allowRedirects\": true }` alongside the shared `permission` block. Precedence: the `cline` override wins, otherwise the existing file value is preserved, otherwise it defaults to `false`. On import, a `true` value round-trips back into the `cline` override (the default `false` emits no override). Cline does not have a stable per-user file location for command permissions, so global mode is not supported. If a pattern still ends up in **both** `allow` and `deny` — which the additive merge can produce when the existing file carries a hand-written `deny` matching a generated `allow` — Rulesync emits a warning, since deny wins and the `allow` entry therefore has no effect.\n\nFor Zed, this generates the `agent.tool_permissions` object in `.zed/settings.json` (project mode) or `~/.config/zed/settings.json` (global mode — `%APPDATA%\\Zed\\settings.json` on Windows). Each canonical category becomes a key under `agent.tool_permissions.tools.<tool>` (tool-name mapping: `bash` → `terminal`, `edit` → `edit_file`, `write` → `write_file`, `webfetch` → `fetch`, `websearch` → `search_web`; unknown categories pass through unchanged). Per-tool MCP categories are translated: canonical `mcp__<server>__<tool>` becomes Zed's `mcp:<server>:<tool>`, and imports back into the canonical spelling, so a category authored once reaches Zed and the other targets alike (a key already written in Zed's spelling is emitted unchanged but still normalizes to the canonical form on import). Only the first separator is split, so a tool whose own name contains `__` survives the round-trip. Inside an MCP category only the catch-all `*` rule is emitted, as the tool's `default`; pattern-scoped rules are dropped with a warning, because Zed dispatches every MCP tool with a single empty input (\"MCP tools are gated only by tool id (no per-input pattern matching)\"), so a pattern would be matched against `\"\"` rather than against anything meaningful. A category that omits or wildcards either half — `mcp__<server>`, `mcp__<server>__*`, `mcp__*__<tool>` — is dropped with a warning too, since Zed looks the tool up by exact key on the full triple with no glob or prefix matching. Any canonical-spelled `mcp__<server>__<tool>` entry an earlier Rulesync version left in `settings.json` is swept on the next generate, whether or not the current config still names that category: it is not a Zed tool name, so it can only be Rulesync's own output, and leaving it would resurrect stale rules on the next import. Read-only categories are not written at all: Zed's [gated tool list](https://zed.dev/docs/ai/tool-permissions#supported-tools) does not include `read_file`, `grep`, `find_path` or `list_directory` — they are in Zed's own `EXCLUDED_TOOLS` and never consult the permission settings, so neither a per-tool entry nor the global `default` reaches them. Canonical `read`, `grep` and `glob` (and a category naming one of those Zed tools directly) are therefore **dropped**, with a warning when the category carried a `deny` or `ask` rule, rather than written as entries Zed ignores. Zed's read-denial surface is `private_files`, which the ignore feature writes from `.rulesync/.aiignore`. An inert entry an earlier Rulesync version wrote is left in place rather than deleted — Rulesync cannot tell it from one you wrote, and Zed ignores it either way — and it still imports back as the canonical category, so remove it by hand if you want it gone. The canonical `*` category is the exception: its catch-all `*` rule sets the top-level `agent.tool_permissions.default` — rung 6 of Zed's precedence ladder, and the mechanism Zed documents for MCP tools — rather than an inert `tools[\"*\"]` entry (`*` is not a Zed tool name; a stale `tools[\"*\"]` entry written by an earlier version is cleaned up when the canonical config carries a `*` category, and the `default` imports back as `*: { \"*\": <action> }`). Pattern-scoped rules in the `*` category have no Zed counterpart and are dropped with a warning. Within every other category, the catch-all `*` pattern sets the per-tool `default`, while specific patterns become `always_allow` / `always_deny` / `always_confirm` entries of the form `{ \"pattern\": <regex>, \"case_sensitive\": false }`. Action mapping: rulesync `ask` ⇄ Zed `confirm` (`allow`/`deny` are shared). Because Zed matches with regular expressions, patterns are emitted verbatim — author canonical patterns as regexes when targeting Zed. The settings file is shared with the MCP (`context_servers`) and ignore (`private_files`) features, so writes merge non-destructively: unrelated settings, a user-set `agent.tool_permissions.default` (when the canonical config has no `*` category), and any `tools.<tool>` entries NOT managed by rulesync are preserved on round-trip. The canonical model has no slot for per-pattern case sensitivity, so rulesync always emits `case_sensitive: false`; a hand-authored `case_sensitive: true` on a rulesync-managed tool is overwritten on the next generate.\n\n> **Zed-only override (`zed` key):** two Zed surfaces sit outside the canonical allow/ask/deny model and are authored verbatim through a tool-scoped `zed` override. `zed.sandbox_permissions` is written into `agent.sandbox_permissions`: Zed's OS-level agent sandbox, which since [Zed 1.14.2](https://zed.dev/releases/stable) (2026-08-05) is **on by default** for the `terminal` and `fetch` tools and by default forbids network access, writing outside the project directories, and writing to `.git`. Most real setups therefore need to relax one of `network_hosts` (exact hostnames or leading `*.` wildcards), `allow_all_hosts`, `write_paths`, `allow_fs_write_all` or `allow_unsandboxed` — none of which the canonical categories can express, since this is process containment rather than tool gating. `zed.profiles` is written into `agent.profiles`, Zed's tool-availability layer: a separate enforcement stage from `tool_permissions`, because a tool absent from the active profile cannot be used no matter what the permission rules allow (per-profile keys `name`, `tools`, `enable_all_context_servers`, `context_servers`, `default_model`). Example: `{ \"permission\": { … }, \"zed\": { \"sandbox_permissions\": { \"network_hosts\": [\"*.github.com\"], \"write_paths\": [\"/tmp\"] }, \"profiles\": { \"review\": { \"name\": \"Review\", \"tools\": { \"terminal\": false } } } } }`. Both blocks pass through untouched — Rulesync canonicalizes neither, and validates only the documented `profiles` keys (`sandbox_permissions` is unvalidated, since Zed adds to it release over release) — and each is **replaced wholesale** when the override supplies it, since Zed reads each as a single policy unit; omit the key and whatever is already in `settings.json` is left alone rather than deleted, so removing a block is a manual edit. On **import**, both are lifted back into the `zed` override so a hand-written sandbox policy or profile set round-trips — including approvals you did not write by hand, since Zed saves an always-allow you clicked in the sandbox prompt into `agent.sandbox_permissions` itself. Read the imported block before committing it: an ad-hoc `allow_unsandboxed` picked up from your own machine would otherwise be regenerated into the project file and shipped to everyone. The same wholesale replace works the other way too — regenerating from an authored override discards approvals Zed had recorded since. The `zed` block authors these two keys and nothing else: `agent.tool_permissions` belongs to the canonical `permission` block, and any other key — a misspelling, or a blunt instrument such as Zed's `agent.always_allow_tool_actions` — is ignored with a warning, so nothing reachable from the override can weaken a reviewed deny. Both scopes are written, like the sibling `agent.tool_permissions`: Zed layers user settings under project settings, and a project's `.zed/settings.json` is applied once the worktree is trusted. That trust prompt is the thing to watch when you clone a repository — a project-scoped `allow_unsandboxed` or `allow_all_hosts` is a real grant, not an inert one, so review a `.zed/settings.json` you did not write before trusting the worktree. See the [Zed sandboxing](https://zed.dev/docs/ai/sandboxing) and [agent profiles](https://zed.dev/docs/ai/agent-profiles) docs.\n\nFor Qwen Code, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in `.qwen/settings.json` (project mode) or `~/.qwen/settings.json` (global mode). The format mirrors Claude Code's: entries are `Bash(<pattern>)`, `Read(<pattern>)`, `Edit(<pattern>)`, `Write(<pattern>)`, `WebFetch(<pattern>)`, `WebSearch(<pattern>)`, `Grep(<pattern>)`, `Glob(<pattern>)`, `Agent(<pattern>)`, etc. Other top-level keys in `settings.json` are preserved on round-trip. Patterns may contain nested parentheses (e.g. `Bash(echo (a))`); Rulesync uses the **last** `)` as the closing delimiter when parsing, so inner parens round-trip. Malformed entries (missing closing paren, trailing characters) emit a warning; for **`deny`** they fall back to the catch-all pattern `*` (fail-closed: broadening a deny is the safer direction), but for **`allow` / `ask`** they are **dropped** rather than broadened — silently turning a narrow user rule into `*` would be a fail-open round-trip. Generation does not create the `.qwen/` directory until `writeAiFiles` runs, so dry-run is side-effect-free.\n\nFor Kimi Code, permissions are global-only and generate `[[permission.rules]]` entries in `~/.kimi-code/config.toml`. Canonical categories map to Kimi tool patterns (`bash` → `Bash`, `read` → `Read`, `write` → `Write`, `edit` → `Edit`, `grep` → `Grep`, `glob` → `Glob`, `websearch` → `WebSearch`, `webfetch` → `FetchURL`, `agent` → `Agent`, and `mcp__…` passes through as the MCP tool name); a `*` canonical pattern emits the bare tool name and a specific pattern emits `Tool(pattern)`. Actions map 1:1 to Kimi's `allow` / `ask` / `deny`, and generated rules use `scope = \"user\"`. Kimi evaluates rules first-match-wins, so Rulesync sorts canonical output fail-closed: all `deny` rules precede `ask`, all `ask` rules precede `allow`, and more-specific patterns precede broader patterns within each action. Kimi does not match MCP tool arguments; an argument-specific MCP `allow`/`ask` is skipped with a warning rather than broadened, while an argument-specific `deny` becomes a whole-tool deny with a warning. The optional `kimi-code.defaultPermissionMode` override writes Kimi's top-level `default_permission_mode` (`manual` / `yolo` / `auto`), while `kimi-code.rules` accepts native rules that canonical categories cannot express and emits them first in their authored order. On import, Rulesync preserves the complete ordered rule list under `kimi-code.rules`, including rules that could otherwise fit the shared permission model, so regeneration cannot change Kimi's first-match behavior. A `kimi-code.tools` override writes Kimi's `[tools] enabled` / `disabled` lists — a separate enforcement layer from `[[permission.rules]]`, since a rule prompts while these remove the tool from every agent in every session. Entries pass through verbatim because the section uses agent-file tool syntax (exact built-in names, `mcp__server__*` globs) rather than the canonical category/pattern shape. Note that Kimi registers `[tools]` in its v2 engine, so today it applies under `kimi web` and experimental `kimi -p` rather than the interactive TUI. Like the MCP defaults, the section merges per key: authoring only `enabled` leaves a hand-written `disabled` list alone, and dropping the override leaves the section as it stands. Values are carried through exactly as written, empty lists included — `enabled = []` is an allowlist admitting _nothing_, the strictest setting there is, while an absent `enabled` means no allowlist at all, so the two are never interchanged. The TOML file is shared with hooks, the MCP timeout defaults and other Kimi settings, so updates merge in place and never delete the file. See the [Kimi Code permission docs](https://moonshotai.github.io/kimi-code/en/configuration/config-files.html).\n\n> **Qwen-only override (`qwencode` key):** Qwen's `settings.json` exposes autonomy/sandbox controls with no canonical permission category — under `tools` (`approvalMode` = `plan`/`default`/`auto-edit`/`auto`/`yolo`, `autoAccept`, `sandbox`, `sandboxImage`, `disabled`, `visible` — the deferred-tool startup visibility list, union-merged by Qwen across scopes), `security` (`folderTrust`, plus the two guardrails on `type: \"http\"` hooks — `allowedHttpHookUrls`, the allowlist of URL patterns a hook may POST to, where an empty list means allow-all, and `allowPrivateNetworkHooks`, which relaxes the private-IP (SSRF) check), and `permissions.autoMode` (the Auto Mode classifier config: `hints.{allow,softDeny,hardDeny}`, `environment`, `classifyAllShell`). Add a tool-scoped `qwencode` override to author them: `qwencode.tools` and `qwencode.security` are shallow-merged into the matching `settings.json` group at the **top level of that group** (an unrelated sibling key such as `tools.core` is preserved, an override key wins, and a nested object the override supplies such as `security.folderTrust` replaces the existing one wholesale rather than being deep-merged), while `qwencode.autoMode` is emitted as `permissions.autoMode` (replacing the existing `autoMode` wholesale) and the shared `permission` block keeps driving the `permissions.allow`/`ask`/`deny` arrays. On import, the documented autonomy keys (`tools.{approvalMode,autoAccept,sandbox,sandboxImage,disabled,visible}`, `security.{folderTrust,allowedHttpHookUrls,allowPrivateNetworkHooks}`, and `permissions.autoMode`) round-trip back into the override; other `tools`/`security` keys are left in `settings.json` and not extracted. One scope caveat applies: Qwen Code honors `security.allowPrivateNetworkHooks` only in user/system settings and deliberately **ignores** a workspace value, so that a cloned repository cannot grant itself private-network access. Rulesync therefore skips that key with a warning when generating project-scoped `settings.json` (a value already written into the project file by hand is left untouched), and emits it only in global mode. Import lifts it in either scope, because the file being read carries no scope marker — so if you import a project `.qwen/settings.json` that came from a repository you cloned, review the key before regenerating with `--global`, since that promotes an inert workspace value into one Qwen Code actually enforces.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"*\": \"allow\" } },\n>   \"qwencode\": {\n>     \"tools\": { \"approvalMode\": \"auto-edit\" },\n>     \"security\": { \"folderTrust\": { \"enabled\": true } },\n>     \"autoMode\": { \"hints\": { \"allow\": [\"Running tests\"] }, \"classifyAllShell\": true }\n>   }\n> }\n> ```\n>\n> **Alias overlap:** Qwen's `Read` is a meta-tool that also covers grep/glob/list, so canonical `grep`/`glob` rules are emitted as their own `Grep(...)`/`Glob(...)` entries but overlap Qwen's `Read` category at runtime; and Qwen folds web search into `web_fetch`, so a canonical `websearch` rule (`WebSearch(...)`) may not correspond to a distinct Qwen tool. `tools.disabled` is a hard whole-tool disable (stronger than `deny`) and is only authorable via the override, not the canonical `deny`.\n\nFor Pi Coding Agent, this generates the `defaultTools` array in `.pi/settings.json` (project mode) or `~/.pi/agent/settings.json` (global mode). Pi exposes no allow/ask/deny rule surface, so **no canonical permission category maps onto it** — its one repository-syncable tool gate is `defaultTools`, the list of built-in tools enabled at startup (added in Pi v0.84.2). It is an enable-list rather than an allow/deny rule set, so it is authored through a `pi` override block in `.rulesync/permissions.jsonc` — e.g. `{ \"permission\": {}, \"pi\": { \"defaultTools\": [\"bash\", \"edit\", \"write\"] } }` — and round-trips back into it on import. An empty array is meaningful and emitted as written: upstream reads it as \"start with no built-in tools\" while keeping extension and SDK custom tools. **Scope semantics are the opposite of the union merge most targets use**: a project `defaultTools` array _replaces_ the global array rather than adding to it, so the two scopes are written independently and never combined. CLI flags outrank the setting (`--tools` is a strict allowlist over all tools, `--no-tools` disables everything, `--no-builtin-tools` drops the built-in defaults, `--exclude-tools` filters the result). `settings.json` is a hand-edited file holding many unrelated keys (`theme`, `defaultModel`, `packages`, `sessionDir`, …), so writes go through the shared-config gateway with `defaultTools` as the only owned key — everything else is preserved and the file is never deleted. A config that does not state `defaultTools` leaves the key exactly as you left it. See the [Pi settings reference](https://pi.dev/docs/latest/settings).\n\nFor Warp, this generates the command allow/deny regex lists in Warp's global user `settings.toml` (**global mode only** — Warp has no project-scoped permissions file). Since Warp promoted file-backed execution profiles to Stable (2026-07-28), the surface runtime enforcement actually reads is the `command_allowlist` / `command_denylist` arrays of the `default` record under `[agents.execution_profiles.<id>]`; rulesync merges the lists into that `default` profile **in place** whenever the collection exists, preserving every other profile key and every other profile ID. The legacy `agent_mode_command_execution_allowlist` / `agent_mode_command_execution_denylist` keys under `[agents.profiles]` are still written for un-migrated installs and old clients — but on a migrated install they are inert (Warp consumes them only once during its one-shot migration). When the `[agents.execution_profiles]` collection does not exist yet, rulesync deliberately does **not** create it: on such an un-migrated install the legacy keys are still live, and creating the collection would mark Warp's migration complete early and strand the user's other legacy settings. Note that rulesync manages only the `default` profile — if a different execution profile is active in Warp, the generated lists (including `deny` rules) are not enforced until the user switches back to `default`. The settings file path differs per platform: macOS `~/.warp/settings.toml`, Linux `~/.config/warp-terminal/settings.toml`, Windows `%LOCALAPPDATA%\\warp\\Warp\\config\\settings.toml`. The `bash` category maps (`allow` → allowlist, `deny` → denylist); Warp matches commands with **regular expressions**, so patterns are emitted verbatim — author canonical `bash` patterns as regexes when targeting Warp (mirrors Zed). Warp has no per-command `ask` list, so `ask` rules write nothing — but an `ask` still withholds every `allow` that names any of the same commands (an `ask` on `npm *` withholds an allowed `npm publish`, an `ask` on `npm publish` withholds an allowed `npm *`, and an `ask` on `* --force` withholds an allowed `git *` even though neither pattern covers the other's spelling), since canonically the stricter rule wins whatever its width. A `bash` `ask` that withheld no `allow` is not reported, since Warp prompts for whatever its allowlist does not cover and the rule is therefore honored as written. An `ask` written under `*` is reported in that case, on the same terms as a `*` deny: Warp has no ask list to write it to, so withholding is the only way it restricts, and a pattern there need not name a command — `.*--force` is read as a glob needing a literal leading `.` and overlaps none. The all-tools `*` category is read for its **restricting** rules only, and those never reach the denylist: writing any denylist replaces Warp's built-in default one (see below), and a `*` pattern need not name a command at all, so an inert `secrets/**` entry there would trade real protection for a rule that matches nothing. A `deny` or `ask` under `*` therefore withholds the `allow` rules it covers instead — restricting in the same direction without touching the denylist — and is reported in a warning; author the rule under `bash` as a regex to have it enforced as a command. Its `allow` rules are never carried over either, since a pattern under `*` need not be a command — the skip is named in a warning rather than made silently, and both directions fail closed. Note that this read is one-way: import writes patterns back into the `bash` category only, never into `*`. Because Warp's patterns are regexes while the overlap test compares globs, each `bash` pattern is first rewritten into the widest glob it could stand for: a class (`[rf]`), a group (`(sudo )?`), a character escape (`\\s`), a code-point escape together with its digits (`\\x20`, `\\u0020`, `\\U00000067`, `\\x{263A}`), a Unicode-class escape together with its class (`\\pL`, `\\p{Greek}`, `\\PL`), a top-level `|`, a quantifier together with the atom in front of it (`commits?` covers `git commit`, `ab*c` covers `ac`), and a missing `^`/`$` anchor all become `*`. A construct rulesync cannot read as one sequence makes the **whole** pattern `*` — a class, group or quantifier that never closes, a `{` that spells no repetition (`{a|b}` is an alternation in braces, not a quantifier), or a class holding a nested `[` (Rust's regex crate, which Warp matches with, builds one class out of `[a[b]c]`) — since guessing at the rest could only narrow the result. The rewrite only ever widens, so an inexact reading withholds an allow rather than writing one the config restricts. Note what an unanchored pattern means here: `secret .*` matches any command that merely _contains_ `secret `, so it overlaps an unanchored `git .*` and withholds it — anchor both ends (`^git .*$`, `^secret .*$`) when an `ask` on one command should leave the rest auto-approved. Working out which `allow` rules a restriction overlaps is bounded work, so a configuration large enough to exhaust that budget stops comparing patterns and withholds **every** `allow` beside a restriction — the fail-closed direction — and says so in a warning. A pattern written under the all-tools `*` category is deliberately **not** rewritten: it is canonical, read by every tool, so it is a glob already and is compared as one (`secrets/**` there is a path, not a regex that matches every command mentioning `secrets`). The consequence is worth spelling out: a **regex** written under `*` is not understood as one here, so `.*--force` there is read as a glob needing a literal leading `.` and overlaps no command — author a Warp command rule under `bash`, where it is read as the regex you wrote. Categories other than `bash` and `*` are skipped (with a warning when they carry `deny` or `ask` rules). Writing a `command_denylist` at all **replaces** Warp's built-in default denylist — which covers `rm`, `curl`, `wget`, `eval`, `ssh`, shells, and other risky command patterns — so rulesync warns whenever it emits a non-empty denylist; add canonical `deny` rules equivalent to the built-in patterns you want to keep (see the [Warp CLI permissions docs](https://docs.warp.dev/cli/permissions-and-profiles/)). On import, the `default` execution profile's lists are preferred (falling back to the legacy keys when no collection exists), and a pattern present in both lists resolves to `deny` (Warp's denylist wins). Both blocks are merged into the existing `settings.toml`, preserving other Warp settings, and the file is never deleted. **rulesync owns the command lists** (it is the source of truth): they are replaced from the rulesync config on each `--global` generate, so a manually curated Warp allowlist/denylist not mirrored in `.rulesync/permissions.jsonc` is overwritten — keep command permissions in rulesync (run `rulesync import` first to capture an existing hand-curated list). MCP allow/deny is a separate Warp surface not modeled here. See the [Warp agent profiles & permissions docs](https://docs.warp.dev/agent-platform/capabilities/agent-profiles-permissions/).\n\n> **Warp-only override (`warp` key):** Warp's `[agents.profiles]` table also exposes file-read/read-only autonomy knobs that do not fit the per-command `allow`/`ask`/`deny` model — `agent_mode_coding_permissions` (`always_ask_before_reading` / `always_allow_reading` / `allow_reading_specific_files`), `agent_mode_coding_file_read_allowlist` (an array of paths the agent may read), and `agent_mode_execute_readonly_commands` (a boolean auto-executing read-only commands). Add a tool-scoped `warp` override to author them: its keys are merged into `[agents.profiles]` (the override wins) while the shared `permission` block keeps driving the command lists. On **import**, these keys are lifted from `settings.toml` into the `warp` override, so they round-trip faithfully instead of being dropped. These legacy autonomy keys are part of Warp's one-shot migration, so on a migrated install they are inert; their execution-profile counterparts are authored through the nested `warp.execution_profile` block instead — `read_files` / `apply_code_diffs` / `execute_commands` / `mcp_permissions` (each `agent_decides` / `always_allow` / `always_ask`), `write_to_pty` (`always_allow` / `always_ask` / `ask_on_first_write`), `ask_user_question` (`never` / `ask_except_in_auto_approve` / `always_ask`), `run_agents` (`never_allow` / `always_allow` / `always_ask`), `computer_use` (`never` / `always_ask` / `always_allow`), `directory_allowlist` (paths readable without approval), and `mcp_allowlist` / `mcp_denylist` (MCP server IDs). Its keys are merged into the `default` record of `[agents.execution_profiles.<id>]` under the same guard as the command lists (only when the collection already exists — creating it would complete Warp's migration early; a warning is logged and the block skipped on an un-migrated install), unknown keys pass through verbatim for forward compatibility (export-only: import lifts back exactly the permission keys listed above, while profile-management keys such as `name` or the model overrides never round-trip), and the rulesync-owned `command_allowlist`/`command_denylist` always win. Example:\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git .*\": \"allow\" } },\n>   \"warp\": {\n>     \"agent_mode_coding_permissions\": \"always_allow_reading\",\n>     \"agent_mode_execute_readonly_commands\": true,\n>     \"execution_profile\": {\n>       \"read_files\": \"always_allow\",\n>       \"directory_allowlist\": [\"/home/me/projects\"],\n>       \"mcp_denylist\": [\"untrusted-server\"]\n>     }\n>   }\n> }\n> ```\n>\n> See the [Warp settings reference](https://docs.warp.dev/terminal/settings/all-settings/).\n\nFor deepagents-cli (dcode), this generates the `[shell].allow_list` array of the user config `~/.deepagents/config.toml` (**global mode only** — dcode reads no project-level config file). dcode auto-approves a shell command when the **executable name** of every segment of its pipeline is in that list and asks about everything else, matching the first token exactly (no globs) after rejecting command substitution, redirects, and process substitution outright. Canonical `bash` rules are therefore reduced to their executable: `git *`, `git:*`, `git commit:*`, and a bare `git` all emit `git` — every spelling but the first two widens the rule, since dcode holds no arguments to narrow it by, so they are written with a warning. The wildcard pattern `*` (or its `*:*` and `* *` spellings) becomes the sentinel `allow_list = [\"all\"]`, which auto-approves every command **and** skips that dangerous-pattern check, so it warns too, and is emitted as the sole entry since dcode rejects the option outright when `all` shares the list. When the same config **restricts** anything — a `deny` or an `ask`, for commands or for another tool — `all` is not written at all: turning the dangerous-pattern check off and approving every command unseen, in the name of a rule meant to restrict, would leave you with less than dcode's own default, so the stricter rule wins and the `*` allow is dropped with a warning. A pattern whose executable still holds a glob (`npm-*`), a shell metacharacter (`git;rm`, `$(id)`), a quote (`\"git\"`) or an escape (`\\git`), or is longer than the 255 characters any file name can hold, is skipped with a warning — dcode compares the name exactly, so a glob matches nothing, and a name holding a metacharacter, a quote or an escape is one dcode splits on, refuses outright, or reads differently than it is written, as is one that reduces to a sentinel name (`all`, `recommended` — use `*` for \"every command\"). `ask` needs no output of its own, since a command outside the list already prompts; `deny` has no counterpart at all — dcode asks about an unlisted command rather than blocking it — so a deny rule with no allow entry to hold back is reported as skipped. The all-tools `*` category restricts commands too, so its `deny` and `ask` rules are read alongside the `bash` ones (its `allow` rules never are — a pattern under `*` need not be a command at all — so both directions fail closed, and the skipped allow rules are named in a warning): a `*` deny of `rm *` beside a `bash` allow of `rm *` withholds that allow rather than quietly auto-approving `rm`. Because an entry auto-approves its executable however it is invoked, an `ask` or `deny` on any command that entry would run collides with it — a narrower pattern (`npm publish`) against an allowed `npm *`, and equally a pattern naming no executable at all (`*delete*`, `*--privileged*`) against an allowed `kubectl` or `docker`, since the entry runs those invocations unasked — and dcode has no denylist to settle that collision in — so the colliding `allow` entries are **withheld** from `allow_list` instead: keeping them would auto-approve the very commands the author wanted stopped, while dropping them leaves those executables prompting, which is what an `ask` asks for and the closest dcode comes to a `deny`. Only the colliding entries go; allow rules the restriction says nothing about stay. That covers a narrower rule (`npm publish` or `npm* publish` against `npm *`) and a broader one alike (`*` against every allow, `npm*` against every allowed name it matches), because canonically the stricter rule wins whatever its width — Rulesync collapses colliding rules as deny > ask > allow, and Claude Code applies deny first, then ask, then allow. A quoted or escaped executable (`\"git\" push`, `\\git push`) is read the way dcode reads it — without them — so an odd spelling does not hide the collision. The rule that withheld them is named in a warning, so a deny rule narrower than you meant is visible as the reason a command started prompting. Matching each restriction against what every entry approves is bounded work as well, so a configuration large enough to exhaust that budget treats every allowed executable as colliding and withholds them all — the same fail-closed direction, and the warning says the limit was reached rather than naming a collision nothing compared. On **import**, entries come back as `bash` allow rules named by the executable — an entry dcode could not match in the first place (`git status`, `npm-*`, anything holding a shell metacharacter, a quote or an escape such as `git;rm`, `$(id)` or `\\git`, which dcode splits, rejects or unquotes before it ever compares a name, or a name longer than 255 characters) is skipped with a warning rather than recorded as a permission the tool is not applying, and sentinels are recognized case-insensitively because upstream lowercases them — `all` as `*`, and a list mixing `all` with command names as nothing, since upstream raises on that combination and ignores the option, so those commands are not actually auto-approved. An `allow_list` holding any non-string element, or one that is not a list or a string at all, imports as nothing too, with a warning: dcode requires every element to be a string and drops the whole option otherwise. A `recommended` entry is dropped rather than expanded, with a warning of its own, because the curated list behind it is upstream's to edit — the next generate therefore drops those commands from the allowlist, which fails closed, so re-add by name the ones you want. The `all`-plus-names case warns too, since dcode ignores the whole option there and none of those commands is actually auto-approved. `config.toml` holds every dcode setting, so the `[shell]` and `[startup]` tables are merged in place and the file is never deleted; the merge is a parse and a re-emit, which keeps every unrelated key and table but **does not preserve comments**. A `shell` or `startup` that is not a table at all is left exactly as you have it, with a warning, rather than replaced. See the [deepagents-cli configuration docs](https://docs.langchain.com/oss/deepagents/code/configuration).\n\n> **deepagents-only override (`deepagents` key):** dcode's approval mode is a separate axis from the allowlist and has no canonical per-command slot, so it is authored through a tool-scoped `deepagents` override whose `startup` block is merged into `[startup]` verbatim (unknown keys pass through for forward compatibility): `mode` (`manual` / `auto` / `yolo`, the approval mode a bare launch starts in), `yolo_switcher` (whether YOLO stays in the Shift+Tab mode cycle), and `read_project_dotenv` (whether an untrusted repository's `.env` is loaded into the process environment). On **import**, exactly those three keys are lifted back into the override, and only when the value is one dcode itself would accept (a known `mode`, a real boolean for the switches) — anything else is left behind with a warning, because dcode falls back to its own default for it and writing it would produce a permissions file the next generate could not parse. `startup.recent` is deliberately not lifted at all, since dcode rewrites it as the user cycles modes and committing it would publish one session's state. Generate drops `recent` for the same reason and one more: with no explicit `mode` beside it, that key is what restores auto-approval at launch, so writing it would be a second, quieter way for a repository to change a machine's approval mode. Because this block is written into your **global** config from a `.rulesync/permissions.jsonc` a repository can carry, a value that relaxes what dcode does on its own — `mode` of `auto` or `yolo`, or a `yolo_switcher`/`read_project_dotenv` that was explicitly `false` being turned back on — is warned about by name, alongside the value it replaces (both booleans default to `true` upstream, so writing `true` over an unset key grants nothing and says nothing), and a key rulesync does not know is named too rather than passed through silently. Example:\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git *\": \"allow\" } },\n>   \"deepagents\": {\n>     \"startup\": { \"mode\": \"auto\", \"yolo_switcher\": false }\n>   }\n> }\n> ```\n\nFor the Antigravity IDE, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the committable workspace `.antigravity/settings.json` (**project mode only**). Antigravity 2.0 evaluates these `Deny > Ask > Allow` and uses `action(target)` entries; rulesync maps canonical categories onto the IDE action vocabulary: `read` → `read_file`, `edit`/`write` → `write_file`, `bash` → `command`, `webfetch`/`websearch` → `read_url`, `mcp` → `mcp` (the IDE-only `execute_url` / `unsandboxed` actions have no canonical equivalent and pass through verbatim). Because `edit`/`write` collapse to `write_file` and `webfetch`/`websearch` collapse to `read_url`, importing normalizes back to `write` / `webfetch` (a documented, lossy mapping). The `settings.json` file holds other workspace settings, so the `permissions` block is merged in place — entries for unmanaged actions are preserved — and the file is never deleted. The User-scope settings file is a platform-dependent VS-Code-style path outside rulesync's home-relative global model, so **global mode is not supported**; the workspace file is intended to be checked into git. See the [Antigravity permissions docs](https://antigravity.google/docs/permissions).\n\nFor the Antigravity CLI (`agy`), this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the global `~/.gemini/antigravity-cli/settings.json` (**global mode only**). The CLI shares Antigravity 2.0's Fine-Grained Permissions Engine with the IDE, so the same `action(target)` vocabulary and `Deny > Ask > Allow` precedence apply: `read` → `read_file`, `edit`/`write` → `write_file`, `bash` → `command`, `webfetch`/`websearch` → `read_url`, `mcp` → `mcp` (the engine-only `execute_url` / `unsandboxed` actions pass through verbatim). Because `edit`/`write` collapse to `write_file` and `webfetch`/`websearch` collapse to `read_url`, importing normalizes back to `write` / `webfetch` (a documented, lossy mapping). The `settings.json` holds other CLI settings, so the `permissions` block is merged in place — entries for unmanaged actions are preserved — and the file is never deleted. Five CLI-only autonomy/sandbox knobs outside the allow/ask/deny arrays can be authored (and round-trip) through an optional `antigravity-cli` override block in `.rulesync/permissions.jsonc`: `toolPermission` (the global autonomy preset — `request-review` (default) / `proceed-in-sandbox` / `always-proceed` / `strict`), `enableTerminalSandbox` (a boolean confining agent-run commands to OS containment), `artifactReviewPolicy` (whether the agent's artifact changes are gated on a review prompt — `asks-for-review` (default) / `agent-decides` / `always-proceed`), `allowNonWorkspaceAccess` (a boolean, off by default, letting the agent read or write files outside the active workspace roots), and `agentMode` (the baseline execution mode a session starts in — `default` / `accept-edits` / `plan`). Antigravity applies the allow/deny lists as per-rule exceptions to the preset at runtime, so rulesync authors these keys verbatim as top-level siblings of `permissions` with no precedence modeling. This override is **CLI-only** — the Antigravity IDE exposes the same concepts through a GUI with no documented JSON schema, so it does not apply to `antigravity-ide`. Example: `{ \"permission\": { … }, \"antigravity-cli\": { \"toolPermission\": \"strict\", \"enableTerminalSandbox\": true, \"artifactReviewPolicy\": \"agent-decides\", \"allowNonWorkspaceAccess\": false, \"agentMode\": \"accept-edits\" } }`. Verified against the [Antigravity CLI reference](https://antigravity.google/docs/cli/reference), [sandbox docs](https://antigravity.google/docs/cli/sandbox), [settings reference](https://antigravity.google/docs/cli/settings) and [execution modes](https://antigravity.google/docs/cli/modes). See the [Antigravity CLI permissions docs](https://antigravity.google/docs/cli-permissions).\n\nFor Rovo Dev CLI, this generates the `toolPermissions` block of `config.yml` — the global `~/.rovodev/config.yml`, and in project mode the repo-committed `.rovodev/config.yml` that the [Bitbucket Cloud Agentic Pipelines guide](https://support.atlassian.com/bitbucket-cloud/docs/rovo-dev-advanced-agentic-configuration/) documents (referenced from `bitbucket-pipelines.yml` via `config.path`, or the `--config-file` CLI flag); the project file is deliberately **not** gitignored, since committing it is how Rovo Dev permissions get enforced in CI. Rovo Dev's three levels (`allow`/`ask`/`deny`) are an exact 1:1 with rulesync's canonical actions, so action values pass through verbatim. The `bash` category maps the catch-all `*` pattern to `bash.default` and every other pattern to a `bash.commands[]` entry `{ command: <pattern as regex>, permission }` (Rovo Dev matches commands as regexes, so author `bash` patterns accordingly). The `read` category maps to the inspection tools (`open_files`, `expand_code_chunks`, `expand_folder`, `grep`) and `edit`/`write` to the mutation tools (`find_and_replace_code`, `create_file`, `delete_file`, `move_file`), written under **`toolPermissions.tools`** — the depth Rovo Dev documents. (Earlier Rulesync versions wrote them one level up, directly under `toolPermissions`, where Rovo Dev ignores them; import still reads that legacy shape as a fallback for keys the nested block says nothing about, so an old file is not lost, and a regenerate deletes the stale copies.) Because these per-tool keys hold a single level (no per-pattern rules), only the catch-all `*` of each category sets the level. Rovo Dev rewrites a single tool key when the user answers \"always allow\" to one prompt, so the four keys of a category can disagree; import collapses them back onto one catch-all by taking the strictest level (`deny` > `ask` > `allow`) rather than whichever key is read last. Rovo Dev's planning and Atlassian tools split the same way, so they ride the same two categories rather than getting one of their own: `read` also reaches `getJiraIssue` and `getConfluencePage`, and `edit`/`write` also reach `createJiraIssue`, `updateJiraIssue`, `createConfluencePage`, `updateConfluencePage` and `createTechnicalPlan` (grouped with the mutating tools because it is the planning tool that produces an artifact rather than reading one). Bear that in mind when authoring: an `edit: deny` reaches Jira and Confluence, not just the working tree. Because `edit` and `write` both map onto the same mutation tools, a conflicting catch-all between them cannot be represented; the stricter of the two levels is kept — the same `deny` > `ask` > `allow` rule import uses — and a warning is logged. Non-catch-all `allow` paths in those categories are surfaced as `allowedExternalPaths` so explicit grants are not dropped; non-`allow` non-catch-all rules cannot be expressed per-path and are skipped with a warning. Categories without a clean Rovo Dev target (e.g. `webfetch`) are skipped with a warning. `config.yml` holds all of Rovo Dev's settings (`agent`, `sessions`, `mcp`, etc.), so the `toolPermissions` block is merged in place — every other top-level key is preserved, as is any key inside `toolPermissions` that Rulesync does not manage — including tools inside `toolPermissions.tools` that no canonical category maps to, and the `toolPermissions.bash` sub-keys Rulesync never writes: `env` (the `${VAR}` passthrough that is the documented way to give a CI run a secret whose name matches Rovo Dev's `token|key|password|secret|auth|credential` filter) and `runInSandbox`. Only the `bash.default` and `bash.commands` leaves are rewritten — the `bash` map itself is merged, not replaced. Because those sub-keys now survive every generate rather than being cleared by one, treat them as durable state: the project `config.yml` is committed, so prefer `${VAR}` references over literal credentials in `bash.env`, and note that a `runInSandbox: false` committed to the file stays in force — a regenerate is not a way to reset it, and says so with a warning when it carries one through. On **import**, a tool key the file is silent about counts as the implicit fallback level (`toolPermissions.default`, or Rovo Dev's own `ask`) rather than as absent, and the category still collapses to the strictest of the set. That matters because Rovo Dev writes a single key when the user answers \"always allow\" to one prompt: without the fallback, one such answer about `create_file` would import as a blanket `edit: allow`, and the next generate would hand that grant to every other tool of the category — Jira and Confluence writes included. A category the file says nothing about at all is still skipped rather than invented.\n\n**Migration note.** `toolPermissions.default` and the seven planning/Atlassian keys became Rulesync-owned in the release that added them. Ownership means the first generate after upgrading removes a hand-written value for one of them unless `.rulesync/permissions.*` produces it — a hand-written `tools.createJiraIssue: deny` or `default: deny` with no matching rule in the rulesync source is dropped (with a warning naming each key), falling back to Rovo Dev's `ask`. Run `rulesync import --targets rovodev --features permissions` before the first generate to carry those values into the rulesync source.\n\nThe canonical all-tools category `*` maps to `toolPermissions.default`, the level Rovo Dev falls back to for any tool with no more specific setting (Rovo Dev's own default is `ask`) — derived from its catch-all exactly as `bash.default` is derived from `bash`'s, and round-tripped back on import. The default is a single level, so a pattern rule inside the `*` category has no counterpart and is skipped with a warning. The keys Rulesync does manage (`default`, `bash.default`, `bash.commands`, `allowedExternalPaths`, and the per-tool keys above) are owned rather than merged: each generate rewrites them from `.rulesync/permissions.*`, so removing a rule there removes it from `config.yml` too (a source stating no rule at all clears them; one whose rules simply have no Rovo Dev counterpart keeps the block's restrictions but strips its grants — an `allow` there is normally a leftover of an earlier generate, and dropping one falls back to Rovo Dev's stricter default, whereas clearing the whole block would relax every level), logging a warning naming each owned key it removes — per-tool levels and `allowedExternalPaths` are written from inside a Rovo Dev session too, by an \"always allow\" prompt answer and the `/directories` command, and a hand-edit to one of those keys — including a path added with the in-session `/directories` command, which writes to `allowedExternalPaths` — is replaced on the next generate (values only — YAML comments and formatting in the existing file are not retained on rewrite) — and the file is never deleted. See the [Rovo Dev CLI settings](https://support.atlassian.com/rovo/docs/manage-rovo-dev-cli-settings/) and [tool permissions](https://support.atlassian.com/rovo/docs/use-tools-in-rovo-dev-cli/) docs.\n\nFor Goose, this generates the `user` block of the global `~/.config/goose/permission.yaml` (**global mode only** — Goose persists per-tool permission overrides only under the home directory and has no project-scoped permissions file). Goose stores permissions as a YAML map of mode key → `{ always_allow, ask_before, never_allow }`, where each field is a list of tool-name strings; rulesync writes the user-set decisions under the `user` key. Action mapping is a 1:1: `allow` → `always_allow`, `ask` → `ask_before`, `deny` → `never_allow`. Tool-name mapping: `bash` → `developer__shell`, `edit` → `developer__text_editor`; every other category passes through verbatim as the Goose tool name (so namespaced tools like `developer__text_editor` or `developer__image_processor` round-trip). Because Goose permission lists hold **whole tool names** rather than per-command/per-path globs, only a category's catch-all `*` pattern is representable — non-catch-all patterns are skipped with a warning. `write` collapses onto `developer__text_editor` too, so a conflicting `edit`/`write` catch-all cannot be represented; `edit` takes precedence and a warning is logged. The `permission.yaml` file is merged in place: the `user` block is owned by rulesync, while every other top-level key (notably the `smart_approve` LLM-decision cache) is preserved, and the file is never deleted. See the [Goose tool permissions docs](https://goose-docs.ai/docs/guides/managing-tools/tool-permissions/).\n\nFor the Grok Build CLI (`grokcli`), this generates Grok's Claude-style `[permission]` rule arrays — `allow` / `deny` / `ask` — in the project `./.grok/config.toml` (project mode) or the user `~/.grok/config.toml` (global mode, via `--global`). Grok documents that \"Project configs are limited to MCP servers, plugins, and permission rules, not full user configs\" ([settings docs](https://docs.x.ai/build/settings)), so the fine-grained `[permission]` rules are valid at both scopes. Each canonical `permission.<category>.<pattern>` becomes a Grok entry bucketed into the matching array: `bash`→`Bash`, `read`→`Read`, `edit`→`Edit`, `grep`→`Grep`, `webfetch`→`WebFetch`, `websearch`→`WebSearch`, and `mcp__<server>__<tool>`→`MCPTool(<server>__<tool>)`; a `*` pattern emits the bare tool name (e.g. `Bash`) and a concrete pattern emits `Tool(pattern)` (e.g. `Bash(git *)`). `write` collapses onto `Edit` (Grok has no separate `Write` tool — a documented lossy mapping), and categories with no Grok tool (`glob`, `notebookedit`, `agent`) are skipped, with a warning when a skipped category carries a `deny` or an `ask` rule. Grok evaluates the arrays with precedence `deny > ask > allow`, which import mirrors (a tool listed in multiple arrays resolves to the strictest action). The coarse `[ui] permission_mode` toggle (`\"ask\"` / `\"always-approve\"`) is still written as a backward-compatible fallback for older Grok versions: `always-approve` when the config is pure-`allow`, otherwise `ask` (conservative — never `always-approve` while any `deny`/`ask` rule exists, so it never contradicts the fine-grained arrays). Grok's third mode, `auto` (classifier-based, toggled in the TUI with `/auto`), is an exception in both directions: nothing in the canonical model derives it, so Rulesync never writes it — and a `config.toml` that already selects it keeps it, since overwriting would silently downgrade the user to `ask` on every `generate --global`. The fine-grained arrays are still written in that case; only the coarse toggle is left alone. On import, both documented `[permission]` forms are parsed back into canonical categories: the compact `allow`/`deny`/`ask` arrays and the verbose `[[permission.rules]]` tables (`{ action = \"allow\", tool = \"bash\", pattern = \"git *\" }`). The verbose `tool` field is documented lowercase (`any`/`bash`/`edit`/`read`/`grep`/`mcp`/`webfetch`) while the compact entries are capitalized, so it is matched case-insensitively and `mcp` folds into the canonical `mcp__…` categories exactly as `MCPTool(…)` does; a rule with no `pattern` covers the whole tool. Rules from the two forms merge with the same `deny > ask > allow` precedence, and a rule naming a tool with no canonical category (e.g. `any`) is skipped. Only when neither form carries a rule do we fall back to the coarse mode (`always-approve` ⇄ `bash: { \"*\": \"allow\" }`, `ask`/unset ⇄ `bash: { \"*\": \"ask\" }`). Generate always writes the compact arrays. `config.toml` is shared with the MCP feature, so rulesync owns the `[permission]` `allow`/`deny`/`ask` arrays and `[ui] permission_mode` while every other key (e.g. `[mcp_servers]`, `[sandbox]`) is preserved, and the file is never deleted — including a hand-authored verbose `rules` array, which is read on import but left untouched on generate rather than reconciled against the arrays rulesync writes. **Migration:** a `config.toml` written by an earlier Rulesync may carry hand-authored `WebSearch` entries that were preserved verbatim as unmanaged; they are now parsed into the canonical `websearch` category and regenerated as Rulesync-owned entries. See the [Grok CLI settings reference](https://docs.x.ai/build/settings/reference) and [modes docs](https://docs.x.ai/build/modes-and-commands).\n\nFor Vibe (mistral-vibe), this generates per-tool `[tools.<tool>]` tables in the shared `.vibe/config.toml` (project mode) or `~/.vibe/config.toml` (global mode). Tool-name mapping: `bash` → `bash`, `read` → `read_file`, `edit` → `edit`, `write` → `write_file`, `webfetch` → `web_fetch`, `websearch` → `web_search`, `grep` → `grep`, `agent` → `task`. These are Vibe's builtin tool names (`BaseTool.get_name()`, the snake_case of each tool class); `edit` and `write_file` are distinct tools — `write_file` has been create-only since v2.14.0 — so the two canonical categories no longer collapse onto one name. **Migration:** a `config.toml` written by an earlier Rulesync may still carry `write_file` entries derived from the `edit` category, or inert `[tools.fetch]` / `[tools.search_web]` / `[tools.agent]` blocks. Rulesync only rewrites the names it now emits, so remove those stale entries by hand — a leftover `disabled_tools = [\"write_file\"]` keeps Vibe's `write_file` disabled even though no canonical rule asks for it, and inert `[tools.glob]` / `[tools.notebookedit]` tables an earlier Rulesync emitted for tools Vibe does not have stay on disk until removed by hand (new generates skip those categories instead of rewriting them). Within a category, the catch-all `*` pattern sets the per-tool `permission` (`allow` → `always`, `ask` → `ask`, `deny` → `never`); a wildcard deny additionally adds the tool to the top-level `disabled_tools` filter. A wildcard allow deliberately does **not** touch the top-level `enabled_tools` key: upstream treats it as an **exclusive** allowlist (“if set, only these tools will be active”), so expressing allows through it — as earlier Rulesync versions did — silently switched off every other builtin and MCP tool; the per-tool `permission = \"always\"` entry carries the allow completely, and a regenerate now removes the exclusive entries an earlier version wrote for the tools it configures (`disabled_tools` entries, by contrast, are only cleared by a category that actually states a base permission with a `*` rule — clearing them for a category holding pattern rules alone would silently promote a disabled tool to “enabled, with a denylist”; on **import**, a `disabled_tools` entry likewise wins over a `[tools.<name>]` table that contradicts it — permission and patterns alike are skipped for that tool, because Vibe applies the filter last and unconditionally: reading the table's `permission = “ask”` (or `always` plus an `allowlist`) as the tool's real state would import a hand-written contradiction as a mere prompt and drop the filter on the next generate, and importing one of its patterns as an `allow` would carry a hole through a switched-off tool into every **other** tool's generated config. The match is on Vibe's own tool name rather than the canonical category, since `name_matches` globs the raw name: a bare `disabled_tools = [“read”]` matches no builtin upstream, so it must not silence `[tools.read_file]`. The entry itself is still imported as a deny for its canonical category, because Rulesync cannot see Vibe's registry — an MCP server may well publish a tool named exactly `read` — and denying something that is already off costs nothing where dropping a real deny would. The match follows upstream's `name_matches`, which trims each entry, skips a blank one, and then applies a case-insensitive `fnmatch` glob over the raw name — so `disabled_tools = [\"read_*\"]`, `[\"READ_FILE\"]` and `[\" read_file \"]` all silence `[tools.read_file]`, while `[\"\"]` silences nothing and is dropped rather than imported as an empty category: the canonical `read` category is denied on import, beside the literal `read_*` entry, which is carried out verbatim so the glob keeps its reach over the tools Rulesync cannot enumerate — an MCP tool registered at run time. A `re:`-prefixed entry, which Vibe matches as a Python regular expression, is deliberately **not** evaluated: Python's regex dialect is not JavaScript's, and a wrong verdict either drops a table's rules or carries a disabled tool out as an allow, so such an entry is matched only by its exact spelling and a warning names the tables that were therefore imported as authored; a glob longer than 256 characters is left alone and reported the same way, since a tool name is short in every registry Vibe reads and matching a kilobyte-long entry against a kilobyte-long table name buys nothing. A glob that _is_ resolved is walked step by step against fnmatch's own rules rather than translated into a JavaScript regular expression: the two dialects disagree about exactly the bracket corners (a `]` straight after `[` is a member to fnmatch and an empty class to JavaScript; an inverted range such as `[z-a]` is not dropped upstream but _closed over_, taking the member before it and the member after it with it, so `[z-a]` matches nothing, `[!z-a]` matches everything, `[b-ax]` is just `[x]`, and `[a--!]` collapses to a bare `!` that then negates an empty class and matches everything), and a translated `*a*a*a*b` backtracks catastrophically against a long tool name where the walk stays linear per `*`. The deny patterns of a table the filter switches off are carried across even though its allow patterns are not: dropping them would lose a deny the file states outright, which is the broadening direction. Where a canonical category is shared — `read_file` and a bare `read` MCP table both land on `read`, as do `task` and `agent` — the blanket deny is re-asserted after every table has been read, so the category is denied whichever order the tables happen to sit in; letting the later table decide made the import depend on that order, and in one of the two orders a tool the file had switched off was imported as a live allow. On **generate**, a glob left in `disabled_tools` is for the same reason never deleted to make room for an allow Rulesync just wrote — it reaches tools Rulesync cannot see, and removing it would switch those back on — so the contradiction is reported with a warning instead, since Vibe applies the filter last and unconditionally — the warning names only the globs that actually reach a table Rulesync wrote, and an entry Rulesync does not work out — a `re:` regular expression, or a glob past the 256-character cap — gets a warning of its own asking you to check it by hand rather than being listed beside tables some other glob matched. Both warnings print each name with its control characters stripped and its width capped at 80 terminal columns, and name at most ten before counting the rest, since the text comes from a `config.toml` that may have been checked in by someone else); specific patterns become **`allowlist` / `denylist`** entries — these are the keys Vibe's permission engine actually reads (`BaseToolConfig`), so the legacy `allow` / `deny` keys are dropped on generate from every table a category writes (still honored on import). A table carrying **both** spellings holds one list Vibe enforces and one it ignores, so both are read as a single list and written back under the canonical key: preferring either alone would drop the other, and on the deny side that silently discards a restriction Vibe was applying — multiplied across all three shell tables by the fan-out below. The two sides are not symmetric: reading both deny lists can only restrict further, while reading both allow lists **promotes** a pattern Vibe was ignoring into one it enforces (an `allowlist` match is unconditionally allowed even under `permission = “never”`), so that promotion is announced with a warning naming the patterns — delete them from `config.toml` if the legacy list was stale. Vibe has no per-pattern `ask`, so pattern-level `ask` rules are skipped with a warning. A canonical category with no Vibe builtin tool at all (e.g. `glob`, `notebookedit`) is likewise skipped with a warning instead of emitting an inert `[tools.<category>]` table — a `deny` written there would look applied while Vibe ignores it. The all-tools `*` category is skipped for a different reason: Vibe's config has per-tool tables only, and while `disabled_tools` does match glob patterns (`name_matches`), an entry there removes the tool from the registry outright rather than acting as a default the sibling `[tools.<name>]` tables can override — so `disabled_tools = [\"*\"]` would silently swallow every `allow` authored next to the wildcard. A category that is **not** a canonical Rulesync category is taken at face value as a Vibe tool name and written to `[tools.<name>]`: Vibe's tool manager resolves that table for every registered tool rather than only the builtins, so this is how per-MCP-tool permissions are authored, and `vibe.permission.<name>.sensitive_patterns` works there too. Because Vibe publishes an MCP tool as `<server>_<tool>`, the cross-tool canonical spelling `mcp__<server>__<tool>` is translated to that name on generate (`mcp__github__create_issue` → `[tools.github_create_issue]`; only the first `__` is split, so a tool name may itself contain one). The translation is one-way — Vibe's name carries no `mcp` marker — so import keeps `github_create_issue` as the category; regenerating from it writes the same table. A server-scoped `mcp__<server>` category is skipped with a warning, since Vibe has no server-level permission table; so is a wildcard one (`mcp__<server>__*`, `mcp__*__<tool>`), because a `[tools.<name>]` lookup is exact even though `disabled_tools` entries are glob-matched, which would make `[tools.\"github_*\"]` an inert deny. Since a non-canonical name is written verbatim, a misspelled builtin (`powershel`) becomes an inert table; case mistakes (`Bash`), a mis-cased MCP prefix (`MCP__github__x`) and a glob in the name (`github_*`, whose pattern-level rules Vibe never looks up because `[tools.<name>]` is matched exactly) are the ones detectable without guessing, and those are warned about. The `bash` category is written to three tables — `bash`, `git_bash` and `powershell` — because Vibe's managed shell is a different tool on each platform: the POSIX one publishes `bash`, but on Windows it is `git_bash` or `powershell`, so a `bash` deny landing only on `[tools.bash]` left the shell fully allowed there. Author `git_bash` or `powershell` as its own category in the shared `permission` block to override the fan-out for that shell. A `vibe.permission.<shell>` entry does **not** claim it for the base permission: that block carries `sensitive_patterns` only, so treating it as a claim would strip the `bash` permission from the shell without putting anything in its place — its patterns are merged onto the fanned-out table instead, and a `vibe.permission.<shell>` entry does keep `vibe.permission.bash`'s patterns from overwriting the ones authored for that shell. A shell category that expresses nothing Vibe can read (only pattern-level `ask` rules, or no rules at all) likewise does not claim the shell, since it would otherwise cancel the `bash` deny and write nothing in its place. The fan-out also stands down for a shell the existing `config.toml` already configures differently from `[tools.bash]`, and warns when it does — that is a permission decision made outside the `bash` category, and overwriting it could broaden a `permission = \"never\"` into whatever the canonical `bash` category says. Standing down costs that shell only its **base permission and allow patterns**: the `bash` category's `deny` patterns are still merged into the shell's `denylist` (and its legacy `deny` key folded into the canonical one), because Vibe resolves a denylist match before the allowlist and before the configured permission, so those entries can only restrict the shell further — leaving them out would let a deny you authored go silently missing on one of the three shells. A shell that exists only as a `disabled_tools` entry is skipped there: it is off the registry entirely, so a `denylist` for it would be inert, and writing one would invent a table you never authored. A shell that has its own category in the shared `permission` block is neither stood down from nor reported: that category owns the table outright. The one exception is a `bash` category whose `*` rule is a **deny**: that cannot broaden anything — the shell ends up disabled outright, which is at least as strict as whatever it held — and standing down there would leave an authored deny silently absent from one of the three shells, the exact failure the fan-out exists to prevent. A wildcard deny therefore overwrites the shell (with a warning, which also says that the shell's own `allowlist` / `denylist` entries are replaced along with its permission — the shell ends up disabled outright, so nothing it held is still enforced). Author that shell as its own category to keep a different permission for it. Only the permission keys the fan-out itself mirrors take part in that comparison (`permission`, `allowlist`, `denylist` — with the legacy `allow` / `deny` spellings normalized to the canonical ones — plus `disabled_tools` membership), so a key outside it on `[tools.bash]` — a `timeout`, say, which is carried over for `bash` but never copied to the aliases — does not make Rulesync's own output look hand-authored and freeze the fan-out on the next generate. `sensitive_patterns` is outside it for the same reason: that key is written by the `vibe.permission` pass, which addresses each shell **by name**, so a `vibe.permission.git_bash` entry legitimately leaves that shell holding patterns `[tools.bash]` does not have — counting it would read Rulesync's own output as an outside decision and freeze the fan-out, and mirroring it would overwrite the per-shell patterns you asked for. It is still **filled in** where a shell has none of its own, so a hand-authored `[tools.bash] sensitive_patterns` guard travels with the permission it guards instead of the shells receiving the bare allow. The copy keeps the order it was authored in: `[tools.bash]`'s own list is a key Rulesync does not write, so it is left alone, and sorting only the copy made one guard read as two different lists across the three shells. The fill is one-way — it never clears a shell's patterns — so deleting the `[tools.bash]` guard afterwards leaves the copies behind on the Windows shells; that asymmetry is reported with a warning, because an import would otherwise read them as per-shell rules and write `vibe.permission.<shell>.sensitive_patterns` entries you never authored, which claim those shells out of the fan-out for good. Values are compared as sets, not as written: `denylist = [\"b\", \"a\"]` beside `denylist = [\"a\", \"b\"]` is the same decision, and treating the order as a divergence would strand a `bash` deny on a shell that already agrees with it. A table holding none of those keys — or holding one only as an empty list, which is the absent key spelled out (and which Rulesync drops from its output rather than carrying over) — states no decision and is fanned out over; a key whose value is not a list at all (`denylist = “rm -rf *”`) does count as a decision, even though Vibe's own `BaseToolConfig` types it as `list[str]` and fails to load the file — of the two ways to be wrong about it, deleting the key is the one you cannot recover from (the `bash` deny merge stands down from such a table too, with a warning, since merging into a non-list would replace it rather than add to it — and in that case, as when the `bash` category carries no `deny` patterns at all, the stand-down warning says that **nothing** from the category reaches the shell rather than promising a merge that does not happen); the stand-down warning is likewise only raised when there is a `bash` permission to stand down — when only a `vibe.permission.bash` entry exists, the warning says that its `sensitive_patterns` are what does not reach the shell. The fan-out is also skipped when the `bash` category itself expresses nothing Vibe can read: with no permission to spread, mirroring would push whatever `[tools.bash]` already carries onto shells the file never configured, silently broadening them. When the fan-out does run it **mirrors** `[tools.bash]`'s permission keys onto the two aliases rather than merging each alias with its own previous contents (their unmanaged keys are kept): merging would diverge them the first time `[tools.bash]` carried an entry the aliases lacked — which Rulesync's own output does as soon as a hand-authored `denylist` is merged into `bash` — and that divergence would then stand the fan-out down forever, stranding every later `bash` deny on POSIX. Mirroring is safe precisely because a shell stating a decision of its own has already been excluded, and it makes regenerating idempotent. `disabled_tools` membership is mirrored too, for the same reason. `enabled_tools` membership is deliberately excluded: it is an exclusive registry filter rather than a permission, and counting it let `enabled_tools = [\"powershell\"]` take that shell out of a `bash` deny while leaving it the only active tool. On import, a Windows shell table identical to `bash` is collapsed back into the single `bash` category, while one that differs is kept as its own. Unknown `[tools.*]` tables already on disk still round-trip untouched. The `config.toml` file is shared with the MCP feature, so writes merge non-destructively and the file is never deleted. See [mistral-vibe](https://github.com/mistralai/mistral-vibe) (`vibe/core/tools/base.py`).\n\n> **Vibe-only override (`vibe` key):** Vibe's `BaseToolConfig` also carries a `sensitive_patterns` list — patterns that escalate to **ASK even when the base permission is ALWAYS** (allow). The canonical model can only set a pattern to a single `allow`/`ask`/`deny`, so an \"allow by default but ask on these patterns\" escalation cannot be expressed in the shared block. Add a tool-scoped `vibe` override to author it: `vibe.permission.<category>.sensitive_patterns` carries the list per canonical category (e.g. `bash`, `edit`), while the shared `permission` block still sets the base permission and allow/deny lists. On import, a tool's `sensitive_patterns` round-trips back into the `vibe` override (the base allow stays in the shared block). rulesync owns the list for any category named in the override (a present list is set, an empty one clears it); categories not named keep whatever the existing `config.toml` had. A `vibe.permission.bash` entry is fanned out to the Windows shells like the base permission is, but where a shell's `config.toml` table already sets **different** patterns of its own it **merges** into them instead of replacing them, and warns that it did: those patterns are what still escalates to ASK once the base permission becomes ALWAYS, so they are the author's only remaining defense there, while dropping the override's patterns would strand a newly added guard on that one shell. A union is safe in both directions because `sensitive_patterns` only ever escalates to ASK. An empty `sensitive_patterns = []` counts as no patterns of the shell's own — it is the absent key spelled out, and Vibe's own config dump writes it that way — so the override's list is applied there in full. The reverse case is the exception to “an empty list clears it”: an empty `vibe.permission.bash.sensitive_patterns` clears the patterns this override owns, but a shell that authored **different** patterns of its own keeps them (with a warning saying so) — delete them from `config.toml` to clear them. Name that shell in `vibe.permission.<shell>.sensitive_patterns` to own its list outright. `sensitive_patterns` is the only key this override can express — a `permission`, `allowlist` or `denylist` written inside `vibe.permission.<category>` is ignored with a warning, since the shared `permission` block is where those belong and the base permission it sets can be the exact opposite of what the ignored key asked for. The override also carries `vibe.enabled_tools` — the only way to author Vibe's top-level **exclusive** allowlist. The list is written verbatim in Vibe's tool-name vocabulary (declaring it, even empty, makes rulesync own the whole key), and on import a non-empty `enabled_tools` is lifted back into the override rather than being misread as a set of `\"*\": \"allow\"` grants. Note the `config.toml` scope semantics: since v2.24.0 Vibe installs the user and project TOML layers **together** rather than picking one, so a trusted project config overlays the user config instead of replacing it, and a `--global` run is no longer discarded wholesale by a project `config.toml` — the project layer still wins key by key where it sets one, but every key it leaves unset falls through to the global file. Merging is per key: `mcp_servers` and `connectors` union-merge by name, `tools` deep-merges, `disabled_tools` concatenates, and `enabled_tools` is replaced wholesale by the higher layer. An org-enforced `AdminConfigLayer` sits above every layer at runtime and can override anything below it. (Whether a project layer is read at all still depends on Vibe trusting the project, so treat the overlay as the trusted-project behavior.)\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"*\": \"allow\" } },\n>   \"vibe\": { \"permission\": { \"bash\": { \"sensitive_patterns\": [\"rm *\", \"sudo *\"] } } }\n> }\n> ```\n\nFor Takt, this generates the `default_permission_mode` under `provider_profiles.<provider>` in the shared `.takt/config.yaml` (project mode) or `~/.takt/config.yaml` (global mode). Takt does not have per-tool / per-pattern rules; tool gating is a single coarse mode per provider profile, ordered `readonly` < `edit` < `full` (`readonly` may only read, `edit` may also edit/write files, `full` may also run shell commands). The active provider is resolved from `runtime.yaml` first when Takt is in runtime provider mode (see below) — the provider of the profile named by `provider.defaults.profile`, with no fallback, matching Takt (a lone profile is not promoted to the default, and `defaults.pool`/ladder forms resolve at run time) — and otherwise from the top-level `provider:` key of `config.yaml`, the sole `provider_profiles` entry, or the `claude` default. `provider_profiles` itself stays in `config.yaml` in every version: it is not a legacy provider signal, and Takt does not move permission modes into `runtime.yaml`. The mapping is therefore **lossy**: on generate, a single mode is derived with this precedence — (1) any `deny` rule anywhere ⇒ `readonly` (conservative — keep the narrowest mode whenever the user expressed any restriction); (2) else any `edit`/`write` category `allow` rule ⇒ `edit`; (3) else any `bash` category `allow` rule ⇒ `full`; (4) else ⇒ `readonly` (safe default). On import, `full` ⇄ `bash: { \"*\": \"allow\" }`, `edit` ⇄ `edit: { \"*\": \"allow\" }`, and `readonly` (or an unset/unknown mode) ⇄ `bash: { \"*\": \"deny\" }`. `config.yaml` is shared with other Takt settings, so the mode is merged in place — every other provider profile and all other top-level keys are preserved — and the file is never deleted. Takt's default-deny **workflow security policies** — `workflow_arpeggio` (`custom_data_source_modules`, `custom_merge_inline_js`, `custom_merge_files`), `workflow_runtime_prepare.custom_scripts`, `workflow_command_gates.custom_scripts`, `sync_conflict_resolver.auto_approve_tools`, and the `allow_git_hooks` / `allow_git_filters` booleans — have no canonical permission category, so they are authored through the `takt` override block of `.rulesync/permissions.*` and round-trip on import. Each admits one class of user-supplied code, so only the exact shapes Takt itself accepts are written: a sub-key Takt does not declare is dropped with a warning rather than passed through, since Takt's schemas are strict and reject the whole file on an unknown key, while a value of the wrong type fails when `.rulesync/permissions.*` is read. Removing one of these keys from `config.yaml` because the source no longer states it is warned about too — including a key put there by hand, which owning them implies. Deleting `.rulesync/permissions.*` altogether is different: the feature has no source to generate from, so nothing runs and whatever is in `config.yaml` stays. These keys are also authoritative rather than merged — revoking one in `.rulesync/permissions.*` removes it from `config.yaml`, instead of leaving the capability switched on. `workflow_mcp_servers` stays with the MCP feature, which derives it from the transports in use.\n\nTwo Takt-specific surfaces with no canonical category can be authored (and round-trip) through an optional `takt` override block in `.rulesync/permissions.jsonc`: `step_permission_overrides` (a per-workflow-step map `<step>` ⇒ `readonly`/`edit`/`full`, written inside the active provider profile and layered by Takt on top of `default_permission_mode`) and `provider_options` (a top-level, per-provider table of sandbox/network knobs orthogonal to the mode, e.g. `codex.network_access`, `claude.sandbox.allow_unsandboxed_commands`, `opencode.allowed_tools`). Example: `{ \"permission\": { … }, \"takt\": { \"step_permission_overrides\": { \"ai_review\": \"readonly\" }, \"provider_options\": { \"codex\": { \"network_access\": true } } } }`. Note the workflow-step `required_permission_mode` floor is a field of the **workflow YAML**, not `config.yaml`, so it is intentionally out of scope (Takt's config loader hard-rejects unknown top-level keys).\n\n**`provider_options` and Takt 0.56.0 (`runtime.yaml`).** From 0.56.0, provider configuration lives in `runtime.yaml` (`.takt/runtime.yaml` for the project, `~/.takt/runtime.yaml` globally), and \"runtime provider mode\" is active as soon as its `provider:` section carries an actual assignment — a non-empty `defaults`, `profiles` or `auto_routing`, or a `targets` map with at least one non-empty entry. A file holding only `version: 1`, or empty maps such as `defaults: {}`, is inactive and leaves the legacy resolution in place. While runtime mode is active, **any** legacy provider setting in `config.yaml` — `provider_options` among them — stops Takt with `Mixed provider configuration detected` before it runs an agent, and Takt generates an active `~/.takt/runtime.yaml` on first launch in a fresh environment, so new installs are in runtime mode by default. Rulesync therefore reads `runtime.yaml` — both the scope being generated and the global one, because Takt collects legacy signals from both `config.yaml` files — and merges them the way Takt's loader does before deciding anything: `provider.profiles` is a union in which a project profile replaces the global profile of the same name, while `defaults`, `targets` and `auto_routing` are taken from the project file whole whenever it states them at all, so a project `targets: {}` masks the global one rather than merging with it. On that merged document, while runtime mode is active, rulesync **refuses to write `provider_options`** into `config.yaml`, warning instead of quietly emitting a key that would take the install down. Rulesync does not write `runtime.yaml` itself: a profile is provider- **and** scope-specific, and Takt replaces a same-named profile wholesale across scopes rather than merging it field by field, so there is no key rulesync could own there without clobbering the user's provider and model. Author those options yourself under `provider.profiles.<profile>.options` in `runtime.yaml` — a **flat bag applying to that profile's own provider**, so the `codex:` / `claude:` segment of `provider_options` is dropped — and remove `provider_options` from the `takt` block of `.rulesync/permissions.*`. Anything already written into `config.yaml` by hand is left untouched; rulesync does not own that key. On **import**, both sides are read: the legacy `provider_options` table and, in runtime mode, each profile's `options` from the `runtime.yaml` of the scope being imported (import stays inside the tree it was pointed at), re-keyed by the profile's own `provider` (the runtime side wins on a collision), so nothing is lost. One consequence worth knowing: importing a runtime-mode install produces a `takt.provider_options` block that a later generate will refuse and warn about — drop it from the rulesync source once the options are settled in `runtime.yaml`. Installs with no `runtime.yaml`, or an inactive one, keep the pre-0.56.0 behavior unchanged: `provider_options` is written to `config.yaml` exactly as before.\n\nSee the [Takt configuration docs](https://github.com/nrslib/takt/blob/main/docs/configuration.md).\n\nFor Amp, this writes to the shared `.amp/settings.json` (project mode) or `~/.config/amp/settings.json` (global mode), using **two** permission surfaces. In rulesync's canonical model the category name **is** the Amp tool name. A **whole-tool deny** (pattern `*`) is written to the bare `amp.tools.disable` array (the tool name is pushed verbatim, preserving `builtin:` prefixes and the `*` glob) for backwards compatibility. Every **lossy** case is written to the ordered `amp.permissions` array instead of being dropped: an **argument-specific deny** (pattern `!== \"*\"`) becomes `{ tool, action: \"reject\", matches: { cmd: <pattern> } }`, and every `allow` / `ask` rule becomes `{ tool, action, matches?: { cmd } }` (the `matches` object is omitted for the `*` catch-all). Amp evaluates `amp.permissions` **first-match-wins**, so generated entries are ordered deterministically and fail-closed: sorted by tool name, then entries **with** `matches.cmd` (more specific) before catch-alls, then by action priority **`reject` < `ask` < `allow`**, then by `cmd`. `amp.permissions` is Amp's documented **legacy / backwards-compatibility** surface — it remains functional and is the only place to express `allow`/`ask` and argument-specific `reject` rules. **Ownership:** rulesync OWNS and wholesale-replaces the `allow`/`ask`/`reject` entries on every generate, but **preserves any existing `action: \"delegate\"` entry** (rulesync's canonical model has no `delegate` equivalent); preserved `delegate` entries are placed **after** the rulesync-generated entries (so the regenerated rules take precedence under first-match-wins). On **import**, both keys are read and merged into one canonical config: `amp.tools.disable[tool]` → `{ tool: { \"*\": \"deny\" } }`, and each `amp.permissions` entry → `{ tool: { (matches?.cmd ?? \"*\"): mapped } }` (`reject` → `deny`, `allow` → `allow`, `ask` → `ask`; `delegate` is skipped). When both sources target the same tool+pattern, the **most restrictive action wins** (`deny` > `ask` > `allow`). The settings file is shared with the MCP feature (`amp.mcpServers`), so all other keys are preserved on round-trip and the file is never deleted. Tool names and `cmd` patterns that are prototype-pollution keys (`__proto__`, `constructor`, `prototype`) are skipped defensively.\n\nAmp shapes with no canonical category are authored (and round-trip) through an optional `amp` override block in `.rulesync/permissions.jsonc`: `permissions` — extra `amp.permissions` entries with non-`cmd` matchers (`path`/`url`/`query`/…), regex/array match values, `context` (`thread`/`subagent`), `delegate` (+`to`), or `reject` (+`message`), appended **after** the canonical-generated entries (so generated allow/ask/reject rules take precedence under first-match-wins, with authored entries as later fallbacks); `mcpPermissions` — Amp's `amp.mcpPermissions` array; `guardedFiles` — `amp.guardedFiles.allowlist` (globs allowed without confirmation); and `dangerouslyAllowAll` — `amp.dangerouslyAllowAll`. When the override authors `permissions` it becomes the source of truth for the extra entries; otherwise any hand-authored `delegate` entry in the existing file is preserved. On import, `amp.permissions` entries that are **not** canonical-expressible (non-`cmd` matcher, `delegate`, `reject`+`message`, `context`) are lifted verbatim into `amp.permissions` of the override rather than dropped. Example: `{ \"permission\": { … }, \"amp\": { \"dangerouslyAllowAll\": false, \"guardedFiles\": { \"allowlist\": [\"docs/**\"] }, \"permissions\": [{ \"tool\": \"Bash\", \"action\": \"delegate\", \"to\": \"approve.sh\" }] } }`. See the [Amp manual](https://ampcode.com/manual).\n\nFor JetBrains Junie CLI, this generates the Action Allowlist `rules` object in `~/.junie/allowlist.json` (**global mode only** — Junie CLI resolves exactly one allowlist path under its home directory and never reads a project-scope `.junie/allowlist.json`; verified against release `2383.10`). Junie evaluates the allowlist top-to-bottom (first match wins) and groups rules into buckets, onto which rulesync categories map: `bash` → `executables`, `edit`/`write` → `fileEditing`, `read` → `readOutsideProject`, `mcp` → `mcpTools`. Every rule group is written as Junie's `AllowListRuleSet` **object** — `{ \"default\"?: \"allow\"|\"ask\", \"rules\": [ … ] }` — never a bare array: Junie's parser rejects the array form for the **whole file** and then discards and overwrites `allowlist.json`, so the shape matters. Earlier rulesync versions emitted the array form; it is still tolerated on import, but only the object form is generated. Each rule carries an `action` plus either a literal `prefix` (matches commands that start with it) or a glob `pattern` (`*`, `**`, `?`, `[abc]`, `[!abc]`); rulesync emits `pattern` when the canonical pattern contains a glob metacharacter (`*`, `?`, `[`) and `prefix` otherwise. Junie accepts only `allow` and `ask` as actions — there is **no `deny`** (a `deny` fails the whole-file parse) — so a canonical `deny` is downgraded to the nearest valid action, `ask` (which still withholds auto-approval), with a warning (`allow`/`ask` map 1:1). Categories Junie cannot represent (e.g. `webfetch`, `websearch`) are skipped with a warning when they carry rules. rulesync **owns each mapped group's rule list** (replaced on each generate), while a per-group `default` and the whole `readSecretFile` group — which restricts what Junie may read — are preserved from the existing file when not authored via the `junie` override below. Because `edit`/`write` both collapse onto `fileEditing`, importing normalizes back to `edit` (a documented, lossy mapping). The `allowlist.json` file is never deleted. See the [Junie Action Allowlist docs](https://junie.jetbrains.com/docs/action-allowlist-junie-cli.html).\n\n> **Junie-only override (`junie` key):** Junie's `allowlist.json` has settings with no canonical per-glob slot — the top-level autonomy knobs `allowReadonlyCommands` (a boolean auto-allowing read-only commands) and `defaultBehavior` (the fallback action when no rule matches; an `allow`/`ask` enum — Junie's `AllowListDecision` accepts nothing else, and an invalid value fails the whole-file parse), plus two group-shaped settings: `readSecretFile` (the fifth rule group, restricting reads of secret files — canonical `read` is already taken by `readOutsideProject`, so this group is authored whole as `{ \"default\"?, \"rules\": [ … ] }`) and `ruleDefaults` (each mapped group's own fallback action, e.g. `{ \"executables\": \"ask\" }`). Add a tool-scoped `junie` override to author them: the scalar knobs are merged onto the top level of `allowlist.json` (the override wins) while the shared `permission` block keeps driving the mapped groups' rule lists, and the group-shaped settings land inside the `rules` object. On **import**, all of these are lifted from `allowlist.json` into the `junie` override, so they are authorable and portable instead of only round-trip-preserved. Any other unmodeled top-level key is preserved verbatim. Example:\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git \": \"allow\" } },\n>   \"junie\": {\n>     \"allowReadonlyCommands\": true,\n>     \"defaultBehavior\": \"ask\",\n>     \"ruleDefaults\": { \"executables\": \"ask\" },\n>     \"readSecretFile\": { \"rules\": [{ \"pattern\": \"**/.env\", \"action\": \"ask\" }] }\n>   }\n> }\n> ```\n\nFor Reasonix, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the `[permissions]` table of the shared `reasonix.toml` (project mode) or `~/.reasonix/config.toml` (global mode) — the same TOML file the MCP feature's `[[plugins]]` array-of-tables lives in. The rule syntax mirrors Claude Code's: entries are `Bash(<pattern>)`, `Read(<pattern>)`, `Edit(<pattern>)`, `Write(<pattern>)`, `WebFetch(<pattern>)`, `WebSearch(<pattern>)`, `Grep(<pattern>)`, `Glob(<pattern>)`, `NotebookEdit(<pattern>)`, `Agent(<pattern>)`, etc. (Reasonix's SPEC.md documents these as \"Claude Code-style\" families; `agent` → `Agent` is the one lower-confidence mapping, since Reasonix's own delegation tool is internally named `task`). `[permissions].mode` (the writer fallback: `ask`/`allow`/`deny`) has no canonical rulesync equivalent and is preserved untouched. The TOML file is shared with the MCP feature, so writes only replace the `permissions` table — every other table (`[[plugins]]`, `[agent]`, `[ui]`, …) is preserved on round-trip, and the file is never deleted. See [SPEC.md §3.7 Permissions](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md).\n\n> **Reasonix-only override (`reasonix` key):** Reasonix has security axes orthogonal to per-tool allow/ask/deny with no canonical category — the `[sandbox]` enforcement table (`workspace_root`, `allow_write`, `forbid_read`, `bash` = `enforce`/`off`, `network`) and the plan-mode read-only command list under `[agent]` (`plan_mode_read_only_commands`, which upstream keeps for legacy compatibility only — Plan bash goes through Permissions now). Its sibling `plan_mode_allowed_tools` left the documented config surface in v1.17.18: an existing value is still lifted out of `[agent]` on import, so it does not vanish from an imported config, but whenever the override writes `[agent]` the key is removed from the file with a warning — including a value already there, since leaving that one alone would mean narrowing the list is the one edit that never lands. Add a tool-scoped `reasonix` override to author them: `reasonix.sandbox` and `reasonix.agent` are shallow-merged into the matching `reasonix.toml` table at its top level (override keys win, unrelated sibling keys such as `[agent].model` are preserved), while the shared `permission` block keeps driving `[permissions].allow`/`ask`/`deny`. The override also carries `rawAllow`/`rawAsk`/`rawDeny` — verbatim `[permissions]` entries merged into the generated arrays untranslated. They exist for the first-class `Bash=<literal>` exact-command form (SPEC §3.7, v1.18.0: metacharacters in the literal are ordinary characters and only the identical complete command matches), which the canonical tool→pattern→action shape cannot express. It is also the pattern-level way to pre-authorize **nested or indirect** Bash — command and process substitution, `eval`, `source`, `sh -c` and the like, which Reasonix gates harder than a merely dynamic command line — in a headless `reasonix run`; upstream additionally offers the blanket `[permissions] allow_dynamic_bash` opt-in (added in v1.19.0, which lets an Allow fallback cover that whole class) and YOLO, but authoring either through rulesync is not supported today. Exact entries already in `reasonix.toml` — Reasonix writes them itself as remembered approvals — are always preserved on generate, even for tools the shared block manages. On import, the whole `[sandbox]` table round-trips (it is a dedicated security surface), only the plan-mode keys are lifted from `[agent]`, and exact `Tool=<literal>` entries are lifted into `rawAllow`/`rawAsk`/`rawDeny` instead of masquerading as a bogus tool category in the shared block.\n>\n> ```json\n> {\n>   \"permission\": { \"bash\": { \"git status*\": \"allow\" } },\n>   \"reasonix\": {\n>     \"sandbox\": { \"bash\": \"enforce\", \"network\": false },\n>     \"agent\": { \"plan_mode_read_only_commands\": [\"gh pr diff\"] }\n>   }\n> }\n> ```\n>\n> The retired `[[plugins]].trusted_read_only_tools` MCP read-only trust list is per-plugin (an array-of-tables shared with the MCP feature) and is not covered by this override.\n\n> **Note: Interaction with deprecated ignore feature.** Both the ignore feature and the permissions feature can manage `Read` tool deny entries in `.claude/settings.json`. When both features configure the `Read` tool, the **permissions feature takes precedence** and a warning is emitted. Migrate the ignore patterns to `read` deny rules in `.rulesync/permissions.jsonc`, then remove `ignore` from the project features and delete the obsolete ignore source.\n",
+	"reference/mcp-server": "# Rulesync MCP Server\n\nRulesync provides an MCP (Model Context Protocol) server that enables AI agents to manage your Rulesync files. This allows AI agents to discover, read, create, update, and delete files dynamically.\n\n> [!NOTE]\n> The MCP server exposes the only one tool to minimize your agent's token usage. Approximately less than 1k tokens for the tool definition.\n\n## Supported Features and Operations\n\nThe single `rulesyncTool` multiplexes by `feature` and `operation`:\n\n- `rule`, `command`, `subagent`, `skill`: `list`, `get`, `put`, `delete`\n- `ignore`, `mcp`, `permissions`, `hooks`: `get`, `put`, `delete`\n- `generate`: `run`\n- `import`: `run`\n- `convert`: `run`\n\nThe `permissions` feature operates on `.rulesync/permissions.jsonc` and the `hooks` feature operates on `.rulesync/hooks.jsonc`. Both accept a `content` string (valid JSONC) on `put`.\n\n### Warnings from `generate` / `run`, `import` / `run`, and `convert` / `run`\n\nThe server writes nothing to a console the calling agent can read, so a diagnostic raised while reading the source tool's files, or while generating — for example, that a machine-local overrides file such as `.factory/settings.local.json` was read into files rulesync commits — travels back in the result instead, as a `warnings` array of strings. The field is omitted when the operation had nothing to report, and is present on failures too, since a run that warned and then failed is exactly when the warnings matter. At most 100 warnings are returned, each truncated to 1,000 characters and 8,000 characters in total; a run that exceeds any of those limits says so in a final entry rather than growing the result without bound. These three operations are the only ones that report warnings — the `list` / `get` / `put` / `delete` operations read and write `.rulesync/` files that the caller can inspect for itself, and say nothing.\n\n### `skill` other files\n\nA skill directory may contain files other than `SKILL.md`. They are passed as `otherFiles`, where each entry has:\n\n| Field      | Type                  | Required | Description                                                                    |\n| ---------- | --------------------- | -------- | ------------------------------------------------------------------------------ |\n| `name`     | `string`              | Yes      | Path of the file relative to the skill directory (e.g. `references/logo.png`). |\n| `body`     | `string`              | Yes      | File content, encoded according to `encoding`.                                 |\n| `encoding` | `\"utf-8\" \\| \"base64\"` | No       | Defaults to `\"utf-8\"`. Use `\"base64\"` for binary files such as images.         |\n\nOn `get`, every returned entry carries an explicit `encoding`: `\"utf-8\"` when the file content survives a UTF-8 round trip unchanged, and `\"base64\"` otherwise. On `put`, the declared `encoding` is trusted and the decoded bytes are written verbatim, so binary files round-trip byte for byte.\n\nWhen feeding entries returned by `get` back into `put`, keep their `encoding` field. Dropping it makes a `\"base64\"` body be stored as literal text and corrupts the file.\n\nA `\"base64\"` body must be canonical base64 (the standard or the URL-safe alphabet, padding optional); otherwise `put` fails with `Invalid base64 body for other file <name>`. The 1MB skill size limit is evaluated against the decoded byte length of each other file.\n\n### `convert` / `run` options\n\nWhen invoking `feature: \"convert\"` with `operation: \"run\"`, pass `convertOptions` with the following shape:\n\n| Option     | Type       | Required | Description                                                                        |\n| ---------- | ---------- | -------- | ---------------------------------------------------------------------------------- |\n| `from`     | `string`   | Yes      | Source tool name (e.g. `\"claudecode\"`). Must be a valid `ToolTarget`.              |\n| `to`       | `string[]` | Yes      | One or more destination tool names. Must not be empty and must not include `from`. |\n| `features` | `string[]` | No       | Features to convert (e.g. `[\"rules\", \"commands\"]`). Defaults to `[\"*\"]`.           |\n| `global`   | `boolean`  | No       | Convert global (user-scope) configurations. Defaults to `false`.                   |\n| `dryRun`   | `boolean`  | No       | Preview changes without writing files. Defaults to `false`.                        |\n\n## Usage\n\n### Starting the MCP Server\n\n```bash\nrulesync mcp\n```\n\nThis starts an MCP server using stdio transport that AI agents can communicate with.\n\n### Configuration\n\nAdd the Rulesync MCP server to your `.rulesync/mcp.jsonc`:\n\n```json\n{\n  \"$schema\": \"https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json\",\n  \"mcpServers\": {\n    \"rulesync-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"rulesync\", \"mcp\"],\n      \"env\": {}\n    }\n  }\n}\n```\n",
+	"reference/supported-tools": "# Supported Tools and Features\n\nRulesync supports both **generation** and **import** for All of the major AI coding tools:\n\n<!-- SUPPORTED_TOOLS_DOCS:BEGIN -->\n\n| Tool                      | --targets          | rules | ignore |   mcp    | commands | subagents | skills | hooks | permissions | checks |\n| ------------------------- | ------------------ | :---: | :----: | :------: | :------: | :-------: | :----: | :---: | :---------: | :----: |\n| AGENTS.md                 | agentsmd           |  ✅   |        |          |    🎮    |    🎮     |   🎮   |       |             |        |\n| AgentsSkills              | agentsskills       |       |        |          |          |           | ✅ 🌏  |       |             |        |\n| Amp                       | amp                | ✅ 🌏 |        |  ✅ 🌏   |          |           | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    | ✅ 🌏  |\n| Claude Code               | claudecode         | ✅ 🌏 |   ✅   |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Claude Code plugin        | claudecode-plugin  |       |        |    ✅    |    ✅    |    ✅     |   ✅   |  ✅   |             |        |\n| Codex CLI                 | codexcli           | ✅ 🌏 |        | ✅ 🌏 🔧 |    🌏    |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| GitHub Copilot            | copilot            | ✅ 🌏 |        |    ✅    |    ✅    |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     ✅      |        |\n| GitHub Copilot CLI        | copilotcli         | ✅ 🌏 |        | ✅ 🌏 🔧 |          |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Goose                     | goose              | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   |   ✅   | ✅ 🌏 |     🌏      |        |\n| Hermes Agent              | hermesagent        |  ✅   |   ✅   |  🌏 🔧   |    🌏    |   ✅ 🌏   |   🌏   |  🌏   |     🌏      |   ✅   |\n| Grok CLI                  | grokcli            | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Cursor                    | cursor             |  ✅   |   ✅   |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |   ✅   |\n| deepagents-cli            | deepagents         | ✅ 🌏 |        | ✅ 🌏 🔧 |          |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     🌏      |        |\n| Factory Droid             | factorydroid       | ✅ 🌏 |        | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |   ✅   |\n| OpenCode                  | opencode           | ✅ 🌏 |        | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Cline                     | cline              | ✅ 🌏 |   ✅   |    🌏    |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     ✅      |        |\n| Kilo Code                 | kilo               | ✅ 🌏 |   ✅   | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Kimi Code                 | kimi-code          | ✅ 🌏 |        | ✅ 🌏 🔧 |          |   ✅ 🌏   | ✅ 🌏  |  🌏   |     🌏      |        |\n| Roo Code ⚠️               | roo                | ✅ 🌏 |   ✅   |  ✅ 🔧   |  ✅ 🌏   |    ✅     | ✅ 🌏  |       |     ✅      |        |\n| Zoo Code                  | zoocode            | ✅ 🌏 |   ✅   |  ✅ 🔧   |  ✅ 🌏   |    ✅     | ✅ 🌏  |       |     ✅      |        |\n| Rovodev (Atlassian)       | rovodev            | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |       |    ✅ 🌏    |   ✅   |\n| Takt                      | takt               | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |       |    ✅ 🌏    | ✅ 🌏  |\n| Vibe Code                 | vibe               | ✅ 🌏 |   ✅   | ✅ 🌏 🔧 |          |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Qwen Code                 | qwencode           | ✅ 🌏 |   ✅   | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Meta Muse Code            | musecode           |  ✅   |        |    🌏    |          |           | ✅ 🌏  |       |             |        |\n| Reasonix                  | reasonix           | ✅ 🌏 | ✅ 🌏  |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Kiro ⚠️                   | kiro               | ✅ 🌏 | ✅ 🌏  | ✅ 🌏 🔧 |    ✅    |    ✅     |   ✅   |  ✅   |     ✅      |        |\n| Kiro CLI                  | kiro-cli           | ✅ 🌏 | ✅ 🌏  | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     ✅      |        |\n| Kiro IDE                  | kiro-ide           | ✅ 🌏 | ✅ 🌏  | ✅ 🌏 🔧 |    ✅    |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     ✅      |        |\n| Google Antigravity IDE    | antigravity-ide    | ✅ 🌏 |        | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     ✅      |        |\n| Google Antigravity CLI    | antigravity-cli    | ✅ 🌏 |   ✅   | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |     🌏      |        |\n| Google Antigravity plugin | antigravity-plugin |  ✅   |        |  ✅ 🔧   |          |    ✅     |   ✅   |  ✅   |             |        |\n| JetBrains AI Assistant    | aiassistant        |  ✅   |   ✅   |  ✅ 🌏   |          |           |   ✅   |       |             |        |\n| JetBrains Junie           | junie              | ✅ 🌏 |   ✅   |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  |  🌏   |     🌏      |        |\n| AugmentCode               | augmentcode        | ✅ 🌏 |   ✅   |  ✅ 🌏   |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |   ✅   |\n| Devin Desktop             | devin              | ✅ 🌏 | ✅ 🌏  | ✅ 🌏 🔧 |  ✅ 🌏   |   ✅ 🌏   | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Warp                      | warp               | ✅ 🌏 |   ✅   |  ✅ 🌏   |  ✅ 🌏   |           | ✅ 🌏  |       |     🌏      |        |\n| Replit                    | replit             |  ✅   |        |          |          |           | ✅ 🌏  |       |             |        |\n| Pi Coding Agent           | pi                 | ✅ 🌏 |        |          |  ✅ 🌏   |           | ✅ 🌏  | ✅ 🌏 |    ✅ 🌏    |        |\n| Zed                       | zed                | ✅ 🌏 | ✅ 🌏  |  ✅ 🌏   |          |           | ✅ 🌏  |       |    ✅ 🌏    |        |\n| ZCode (Z.ai)              | zcode              | ✅ 🌏 |        |  ✅ 🌏   |  ✅ 🌏   |    🌏     | ✅ 🌏  |       |             |        |\n\n<!-- SUPPORTED_TOOLS_DOCS:END -->\n\n- ✅: Supports project mode\n- 🌏: Supports global mode\n- 🎮: Supports simulated commands/subagents/skills (Project mode only)\n- 🔧: Supports MCP tool config (`enabledTools`/`disabledTools`)\n- ⚠️: Deprecated — still supported, but see the note below\n\n## Hermes Agent compatibility\n\nThe `hermesagent` target is validated against Hermes Agent v0.20.2 (release\n`v2026.8.16`). The supported contract covers project rules, ignore patterns,\nsubagents, and checks, plus global MCP servers, commands, subagents, skills,\nhooks, and permissions. Generation, `--check`, and import round-trips are\ncovered for both advertised scopes.\n\nRulesync honors Hermes profiles through `HERMES_HOME`. When it is set, its value\nis the profile root itself: global configuration is read and written directly\nunder `$HERMES_HOME` (`config.yaml`, `skills/`, `plugins/`, and `rulesync/`),\nwithout appending `.hermes`. When it is unset, Rulesync follows Hermes's own\nplatform default: `~/.hermes` everywhere except Windows, where it is\n`%LOCALAPPDATA%\\hermes`. Because `HERMES_HOME` names where Hermes itself reads\nthe profile, it also takes precedence over `--output-roots` in global scope.\nProject-scoped paths remain rooted in the project.\n\nChanging which profile root Rulesync resolves strands whatever it generated\nunder the previous one. `--delete` reconciles only the root resolved for the\ncurrent run, so files under a root it no longer resolves are invisible to it and\nmust be removed by hand once you are sure Hermes no longer reads them. This\napplies whenever you set or change `HERMES_HOME`, and to two upgrades that moved\nthe resolved root on their own: before v16.0.0 global files went to `~/.hermes`\neven when `HERMES_HOME` was set, and before v16.2.0 they went there on Windows\ntoo, rather than to `%LOCALAPPDATA%\\hermes`.\n\nProject plugins are registered by adding their names to\n`$HERMES_HOME/config.yaml`, but Rulesync does not persist Hermes's global\nproject-plugin trust gate. Run Hermes from a trusted project root with\n`HERMES_ENABLE_PROJECT_PLUGINS=true` for an explicit, session-scoped opt-in. A\nfuture Hermes release that changes its loaders, schemas, or plugin API requires\na new compatibility validation.\n\n## Deprecation notes\n\n- **Google Antigravity (`antigravity-ide` / `antigravity-cli`)** — Antigravity 2.0 splits into two products: the desktop **`antigravity-ide`** and the **`antigravity-cli`** (`agy`). As of Antigravity 2.0 the IDE reads its global MCP config and skills from the shared `~/.gemini/config/` tree — `~/.gemini/config/mcp_config.json` and `~/.gemini/config/skills/`, matching the current [MCP](https://antigravity.google/docs/mcp) and [Skills](https://antigravity.google/docs/skills) docs. The `antigravity-cli` global MCP config also lives in the shared `~/.gemini/config/mcp_config.json`, while the CLI keeps its own global skills tree at `~/.gemini/antigravity-cli/skills/`. Both targets also intentionally **share** the global rule file `~/.gemini/GEMINI.md` and the global hooks file `~/.gemini/config/hooks.json` — enabling both targets in `--global` mode writes those shared files once. For project-scope rules, **both `antigravity-ide` and `antigravity-cli`** emit the root rule as a plain cross-tool **`AGENTS.md`** at the project root (the Gemini-lineage discovery order is `AGENTS.md`, `CONTEXT.md`, `GEMINI.md`; the IDE has read `AGENTS.md` since v1.20.3) and non-root rules under `.agents/rules/` (the IDE adds trigger frontmatter to non-root rules; the CLI keeps them as plain markdown). For **commands (workflows)**, both targets share the project `.agents/workflows/` directory (invoked as `/workflow-name`); in `--global` mode the IDE writes to `~/.gemini/antigravity/global_workflows/` while the CLI keeps its own `~/.gemini/antigravity-cli/global_workflows/` tree (mirroring the CLI's global skills tree).\n- **Kiro (`kiro`)** — Kiro ships as two products with diverging config formats: the **Kiro IDE** reads Markdown subagents (`.kiro/agents/*.md`) and structured JSON hooks (`.kiro/hooks/*.json`, format `{ \"version\": \"v1\", \"hooks\": [ ... ] }`), while the **Kiro CLI** reads JSON agent-config subagents (`.kiro/agents/*.json`). A single target cannot emit both subagent shapes faithfully, so `kiro` is split into **`kiro-cli`** and **`kiro-ide`**. The legacy `kiro` target is kept as a **deprecated alias** (its current mixed output is unchanged for backward compatibility). Shared surfaces (steering rules with `inclusion`, `.kiro/settings/mcp.json`, `.kiro/prompts/` commands, `.kiro/skills/`, `.kiroignore`, permissions) are identical between the two; they differ only in **subagents** (`.md` vs `.json`). **Hooks** are the same for both: a single `.kiro/hooks/rulesync.json` (whose `hooks` array holds every generated hook) in both project (`.kiro/hooks/`) and global (`~/.kiro/hooks/`) scope, mapping canonical lifecycle events to Kiro's PascalCase triggers (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) and supporting both `agent` (prompt) and `command` actions. Kiro CLI 3.0 [migrated to that format](https://kiro.dev/docs/cli/v3/hooks-migration/) and no longer reads the embedded agent hooks in `.kiro/agents/default.json`, which only the deprecated `kiro` alias still writes (including `cacheTtl` ⇄ `cache_ttl_seconds`). Global **skills** (`~/.kiro/skills/`), global **ignore** (`~/.kiro/settings/kiroignore`), and global Kiro IDE **subagents** (`~/.kiro/agents/`) are also supported, as are global Kiro CLI **commands** (`~/.kiro/prompts/`) and **subagents** (`~/.kiro/agents/`). Kiro's shared MCP file preserves per-server `disabledTools`.\n- **Roo Code (`roo`)** — Roo Code is end of life: its final release was **v3.54.0 (2026-05-15)** and the [Roo-Code repository](https://github.com/RooCodeInc/Roo-Code) is archived, so nothing about the target will move again. New projects should target **`zoocode`** instead — [Zoo Code](https://github.com/Zoo-Code-Org/Zoo-Code) is the community continuation named by the Roo shutdown notice, and it continues Roo's release numbering. The `roo` target stays supported because Zoo Code still reads the `.roo/` project tree and `~/.roo` global tree verbatim, so existing `roo` output keeps working; what it no longer tracks is anything Zoo Code added after the fork. The two targets write the same files, so enable one per project rather than both — see the Zoo Code note in [File formats](./file-formats.md) for the fail-open hazard a `--targets roo` generate creates in a shared `.roomodes`. **Permissions are the one exception**: the two lineages spell the command allow/deny lists differently (`roo-cline.*` vs `zoo-code.*`), so both pairs coexist in one `.vscode/settings.json` and neither target touches the other's — see the Roo Code paragraph in [File formats](./file-formats.md).\n",
 	"tools/takt": "# Takt\n\n[Takt](https://github.com/nrslib/takt) is a faceted-prompting AI coding workflow tool. Rulesync generates plain-Markdown facet files into Takt's `.takt/facets/` layout (or `~/.takt/facets/` in global mode).\n\n## Output mapping\n\nEach rulesync feature maps onto a dedicated Takt facet directory. The target directory is fixed per feature, except that **rules** may opt into Takt's fifth facet — `output-contracts` — via the `takt.facet` override (see below).\n\n| Rulesync feature | Takt facet directory                                                                    |\n| ---------------- | --------------------------------------------------------------------------------------- |\n| `rules`          | `.takt/facets/policies/` (default) or `.takt/facets/output-contracts/` via `takt.facet` |\n| `commands`       | `.takt/facets/instructions/`                                                            |\n| `subagents`      | `.takt/facets/personas/`                                                                |\n| `skills`         | `.takt/facets/knowledge/`                                                               |\n\nTakt-specific frontmatter knobs:\n\n```yaml\n---\ntakt:\n  name: my-renamed-stem # rename the emitted filename stem\n  extends: base # emit a leading {extends:base} facet-inheritance directive\n  facet: output-contracts # \"policies\" (default) or \"output-contracts\"\n---\n```\n\n- `takt.name` is **optional**; the source filename stem is used by default. Unsafe values (path separators, `..` segments, etc.) raise a hard validation error at `generate` time.\n- `takt.facet` is **optional** and defaults to `policies`. Setting it to `output-contracts` redirects the rule to Takt's output-structure / report-template facet, which has no dedicated rulesync feature. Both `policies` and `output-contracts` support `{extends:...}` inheritance. The other facets (`instructions`, `personas`, `knowledge`) are owned by the commands, subagents, and skills features and are not selectable via `takt.facet`.\n- Like `takt.name` and `takt.extends`, `takt.facet` is a generate-side authoring control. Because Takt facet files are plain Markdown with no frontmatter, the facet selection cannot be recovered on import (see [Importing](#importing-existing-takt-files-into-rulesync) below).\n\nOutput files are **plain Markdown** — the source frontmatter is dropped entirely and the body is written verbatim:\n\n```\n.rulesync/rules/style.md         →  .takt/facets/policies/style.md\n.rulesync/rules/review-format.md →  .takt/facets/output-contracts/review-format.md  (with takt.facet: output-contracts)\n.rulesync/commands/review.md     →  .takt/facets/instructions/review.md\n.rulesync/subagents/coder.md     →  .takt/facets/personas/coder.md\n.rulesync/skills/oncall/SKILL.md →  .takt/facets/knowledge/oncall.md\n```\n\n## MCP (partial — transport allowlist only)\n\nTakt has no project- or global-level registry of MCP server _definitions_: the concrete `mcp_servers` map (`command`/`args`/`env` or `type`/`url`/`headers`) is declared **per workflow step** inside individual workflow YAML files, and Takt's `config.yaml` loader rejects unknown top-level keys. The one MCP knob `config.yaml` does expose is the **default-deny transport allowlist** `workflow_mcp_servers: { stdio, sse, http }`; until a transport is enabled there, every workflow-defined MCP server using it is refused.\n\nRulesync therefore emits **only** this allowlist into the shared `.takt/config.yaml` (project) / `~/.takt/config.yaml` (global), turning on exactly the transports the servers in `.rulesync/mcp.jsonc` use (`local`/`stdio` → `stdio`, `sse` → `sse`, `http`/`streamable-http`/`ws` → `http`). The merge is in place, so the active provider, provider profiles, and all other config keys are preserved; the file is never deleted.\n\n**Lossiness:** the per-server names, commands, env, URLs, and headers are not representable in `config.yaml` and are intentionally not written — you still declare the concrete servers in your workflow YAML steps; Rulesync only opens the transport gate that permits them. Because of this, reverse import cannot reconstruct server definitions and yields an empty `mcpServers` map.\n\n## Checks — quality gates\n\n`.rulesync/checks/*.md` become TAKT **quality gates** in the `workflow_overrides` block of the shared `config.yaml`. A check's body is a string gate — a completion directive TAKT injects into the agent step prompt — unless the check's `takt` frontmatter block names a `command`, which makes it a command gate TAKT runs after the step, failing the gate on a non-zero exit.\n\n**A command gate runs unconditionally.** TAKT's default-deny `workflow_command_gates.custom_scripts` policy applies to gates declared in workflow YAML, not to gates coming from `workflow_overrides`, so a `takt.command` in a check is executed after every step it applies to with no further gating. Read the frontmatter of any check you obtain with `rulesync fetch` before generating.\n\n**Lossiness:** TAKT gates carry no severity or tool allowlist, so a check's `severity` and `tools` fields are not written and do not come back on import.\n\n`quality_gates_edit_only` in a check's `takt` block applies to the whole block, and reaches only the gates with no `steps` / `personas` scope — TAKT runs a scoped gate whether or not the step may edit files.\n\nThe block is owned by the checks feature: it is rewritten from `.rulesync/checks/` on every generate, and retracted when checks remain but none target TAKT. Emptying `.rulesync/checks/` altogether leaves the gates in place — the feature has no source to generate from — so delete them by hand in that case. See [file formats](../reference/file-formats.md) for the frontmatter reference.\n\n## Scope\n\nBoth project mode (`.takt/facets/...`, `.takt/config.yaml`) and global mode (`~/.takt/facets/...`, `~/.takt/config.yaml`) are supported.\n\n## `--delete` and `.takt/facets/knowledge/`\n\nSkills are written as flat files sharing one facet root instead of each getting a directory of its own, so `generate --delete` sweeps `.takt/facets/knowledge/` (or `~/.takt/facets/knowledge/` in global mode) by file name rather than by directory: a `.md` file directly under the root that no `.rulesync/skills/` source produces is deleted. That is what makes a renamed or deleted skill stop being served to TAKT. The other facets are unaffected — rules, commands, and subagents each get their own directory and are swept normally.\n\nThe root itself is never deleted, and neither is anything nested inside it: a subdirectory under `.takt/facets/knowledge/` is left alone, files and all. Symbolic links and hidden dotfiles in the root are skipped too, and so is any file whose name TAKT itself could never have written — a facet name is limited to ASCII letters, digits, `_`, `-`, and `.`, so `Design Doc.md` or `設計メモ.md` is never touched.\n\nA hand-authored `.md` placed **directly** in the facet root, under a name that _does_ look generated, is another matter. It is indistinguishable from a real skill file, so `--delete` sweeps it — the same as for `policies/`, `instructions/`, and `personas/`, which the rules, commands, and subagents features own outright. Keep hand-authored knowledge in a subdirectory (for example `.takt/facets/knowledge/my-notes/`) to put it out of the sweep's reach. The same applies in global mode: `~/.takt/facets/knowledge/` is swept exactly like the project root.\n\nThe sweep only runs for a root this generate wrote a file into. If no skill targets TAKT — or `.rulesync/skills/` is empty — the facet root has no rulesync source behind it, so nothing in it is touched. That also means emptying `.rulesync/skills/` altogether leaves the last generated files in place, the same as the checks block above: delete them by hand in that case.\n\nTwo gaps are worth knowing about. A skill's companion files are flattened into the same root, and only the `.md` files directly under it are swept: a companion that is not Markdown (`runbook.txt`) or that sits in a subdirectory of its own (`refs/notes.md`) survives its skill's removal and has to be deleted by hand. And a skill whose `takt.name` starts with a dot writes a hidden file, which the sweep does not enumerate, so that one is never swept either.\n\n## Importing existing TAKT files into rulesync\n\nImporting the **facet** features (rules, commands, subagents, skills) is **not supported**. TAKT facet files are plain Markdown with no frontmatter, so the original skill / command / subagent metadata cannot be recovered. Attempting to import a TAKT skill raises a clear error rather than silently producing a stub that round-trips badly.\n\nThe `config.yaml` features do import: `rulesync import --targets takt --features checks` reads the quality gates back into `.rulesync/checks/`, and `--features permissions` reads the permission mode and the Takt-specific override keys. MCP is the exception noted above — the allowlist carries no server definitions to reconstruct.\n"
 };
 //#endregion
@@ -4948,7 +4986,7 @@ async function doctorCommand(logger, options) {
 		}
 	});
 	if (warningCount > 0) {
-		logger.warn(`Doctor finished with ${summary}.`);
+		if (!logger.jsonMode) logger.warn(`Doctor finished with ${summary}.`);
 		return;
 	}
 	logger.success(`✓ No problems found (${summary}).`);
@@ -5320,6 +5358,39 @@ const WHITESPACE_RUN_PATTERN = /\s+/gu;
 function normalizedFormOf(name) {
 	return require_import.stripHiddenCharacters(require_import.stripHiddenCharacters(name).normalize("NFKC")).replace(WHITESPACE_RUN_PATTERN, " ").trim();
 }
+/** Whitespace at either end of a name, which the row it is drawn on shows none of. */
+const EDGE_WHITESPACE_PATTERN = /^\s|\s$/u;
+/** Two blanks running, which the row draws as the one gap it draws for any number. */
+const REPEATED_WHITESPACE_PATTERN = /\s\s/u;
+/**
+* Whether the name carries more whitespace than the row it is printed on shows.
+*
+* Two shapes, and both are about how much rather than which: whitespace at an
+* edge, where `pdf ` and `pdf` end at the same column and the space is only
+* found by the cursor landing past the name, and a run of it, which a terminal
+* draws as one gap however many blanks are in it. Between them they are what
+* lets a name be padded to reach under the row beneath it.
+*
+* A single blank inside a name that is merely not the plain space — a no-break
+* space, an ideographic one — is deliberately not this check's business. It is
+* drawn, and it is a substitution rather than an extent, so the name it
+* imitates is one the display-form check already reports the pair of; marking
+* it here would put a warning on `設定 ガイド` written with the ideographic
+* space, which is an ordinary name written the ordinary way. At an edge it is
+* marked like any other blank, since there what is at stake is not which
+* character was chosen but that the name reaches past where it appears to end.
+* The tab and the other blank control characters are not here either: a name
+* carrying one is refused outright before it is ever offered.
+*
+* A name with a twin already carries a note, since the two share a display
+* form. This is for the one without: nothing else on the list says that the
+* name reaches past what can be seen of it, and a name padded to sit under
+* another row is padded whether or not that other row is on the same list.
+*/
+function hasWhitespaceThatDoesNotShow(name) {
+	const shown = require_import.stripHiddenCharacters(name);
+	return EDGE_WHITESPACE_PATTERN.test(shown) || REPEATED_WHITESPACE_PATTERN.test(shown);
+}
 /**
 * The form of `name` a terminal draws: what two pieces of text have to share to
 * be the same thing on screen rather than the same thing to `===`.
@@ -5362,7 +5433,48 @@ function foldLookalikes(text) {
 * The case is dropped last, once both folds have had the case they need.
 */
 function latinSkeletonOf(name) {
-	return foldLookalikes(normalizedFormOf(foldLookalikes(name))).toLowerCase();
+	return foldLatinDigraphs(foldLookalikes(normalizedFormOf(foldLookalikes(name))).toLowerCase());
+}
+/**
+* The letter pairs that are drawn as a single other letter once they are set
+* side by side: `rn` for `m`, `vv` for `w`.
+*
+* The tables above map one character onto one character, which is what the
+* confusable data of UTS #39 is mostly made of, and it is why `dep1oy` is
+* caught while `forrnat` is not — the imitation there is not a letter drawn as
+* another letter but two letters drawn as one, and `format` beside it is plain
+* ASCII in a single script, so no other check has anything to say about the
+* pair either. Only the direction that loses information is folded, so both
+* spellings converge on the shorter one and a name that already holds the
+* single letter is left as it is.
+*
+* A pair is one column wider than the letter it imitates, which is the same
+* objection that keeps the em dash out of the tables above. It is not the same
+* situation: the em dash is judged beside the hyphen it imitates, both drawn on
+* screen, where a difference in width is a difference a reader can see, while
+* the name a pair imitates is a skill on disk that no row shows. Counting the
+* columns of a name is no help when there is nothing to count them against.
+*
+* `cl` for `d` is deliberately not on the list, though it is the third of the
+* classic three. `cl` opens too many ordinary words — `clean`, `clear`,
+* `clone`, `cli` — and folding it would report `clone` against a `done` the
+* user happens to have, on a fetch where nothing is wrong. The two that are
+* left cost far less: `modern` folding onto `modem` is the one pair of ordinary
+* words either of them makes, and a note on that pair costs a reader a glance,
+* where `clone` against `done` would be a note on a fetch anyone who keeps a
+* skill called `done` would see.
+*/
+const LATIN_DIGRAPH_LOOKALIKES = [["rn", "m"], ["vv", "w"]];
+/**
+* `form` with each of those pairs replaced by the letter it is drawn as.
+*
+* Run on the lowercased skeleton, after the single-character folds and the
+* normalization, so that a pair spelled with lookalikes of its own — a Cyrillic
+* `с` in front of an `l` — is folded here too rather than only the ASCII
+* spelling of it.
+*/
+function foldLatinDigraphs(form) {
+	return LATIN_DIGRAPH_LOOKALIKES.reduce((folded, [pair, letter]) => folded.split(pair).join(letter), form);
 }
 /**
 * The script a name written entirely in Latin lookalikes is really spelled in,
@@ -5419,7 +5531,31 @@ function mixedScriptsOf(name) {
 	return found;
 }
 /**
-* Note, per name, why it may not be told apart from another name on sight.
+* The two forms a name is compared against other names in: the one a terminal
+* draws it as, and the one it reads as once the lookalike letters are folded.
+*/
+function comparableFormsOf(name) {
+	return {
+		displayForm: displayFormOf(name),
+		skeleton: latinSkeletonOf(name)
+	};
+}
+/** How many of the given names share each display form and each reading. */
+function countComparableForms(forms) {
+	const displayForms = /* @__PURE__ */ new Map();
+	const skeletons = /* @__PURE__ */ new Map();
+	for (const form of forms) {
+		displayForms.set(form.displayForm, (displayForms.get(form.displayForm) ?? 0) + 1);
+		skeletons.set(form.skeleton, (skeletons.get(form.skeleton) ?? 0) + 1);
+	}
+	return {
+		displayForms,
+		skeletons
+	};
+}
+/**
+* Note, per name, why it may not be told apart on sight from what it appears to
+* be.
 *
 * This is display-only: it never removes a name from a list or changes what a
 * name stands for. Two directories whose names differ only in code points the
@@ -5427,38 +5563,61 @@ function mixedScriptsOf(name) {
 * still writes exactly what was picked — the note is there so the picker can
 * tell that two entries which look identical are not.
 *
-* Four things are reported: two names with the same display form, two names
-* that read the same once the lookalike letters are matched up, a name spelled
-* entirely in letters that read as Latin ones, and a name that mixes scripts it
-* has no ordinary reason to. None of the four is a complete answer — the
-* lookalike tables hold the common pairs rather than all of them, a name
-* written entirely in a script the tables do not map is compared against
-* nothing, and a hand-picked pair of unrelated-looking names from one script
-* escapes every check — so the note is a prompt to look closer, not a guarantee
-* that unmarked entries are distinct.
+* Five things are reported: two names with the same display form, two names
+* that read the same once the lookalike letters are matched up, a name that
+* carries more whitespace than the row shows, a name spelled entirely in
+* letters that read as Latin ones, and a name that mixes scripts it has no
+* ordinary reason to. None of the five is a complete answer — the lookalike
+* tables hold the common pairs rather than all of them, a name written entirely
+* in a script the tables do not map is compared against nothing, and a
+* hand-picked pair of unrelated-looking names from one script escapes every
+* check — so the note is a prompt to look closer, not a guarantee that unmarked
+* entries are distinct.
+*
+* `localNames` are names that sit beside the list without being on it: the
+* skills the user already has. They are compared against and never described,
+* because the question a picker asks is which of the names on offer may be
+* taken for something else, and a name already on disk is one of the things
+* they may be taken for. Without them a list of one imitation and no original
+* — a repository publishing `dep1oy` alone, against a `deploy` the user has had
+* for months — is a list with nothing to compare, and every check stays quiet.
+*
+* A local name spelled exactly like one on the list is dropped from the
+* comparison first: that is the skill being updated rather than one imitating
+* it, and a second fetch of the same repository would otherwise mark every row
+* it refreshes. Only that much is decided here, because only that much can be
+* decided from the names alone. Whether a local `pdf` is also the directory a
+* listed `PDF` would be written into is a question about the filesystem, not
+* about the spellings, and the caller answers it before handing the names over
+* — see `readSkillRootNames` and its caller in `fetch.ts`.
+*
+* Where both a listed name and a local one collide, the listed one is named — it
+* is the pair a reader can compare on screen — and the row carries one reason
+* either way.
 *
 * Names absent from the returned map carry no note. Duplicates in `names` are
 * folded first, so a list that repeats a name does not report that name as
 * colliding with itself.
 */
-function describeConfusableNames(names) {
+function describeConfusableNames(params) {
+	const { names, localNames } = params;
 	const entries = [...new Set(names)].map((name) => ({
 		name,
-		displayForm: displayFormOf(name),
-		skeleton: latinSkeletonOf(name)
+		...comparableFormsOf(name)
 	}));
-	const displayFormCounts = /* @__PURE__ */ new Map();
-	const skeletonCounts = /* @__PURE__ */ new Map();
-	for (const entry of entries) {
-		displayFormCounts.set(entry.displayForm, (displayFormCounts.get(entry.displayForm) ?? 0) + 1);
-		skeletonCounts.set(entry.skeleton, (skeletonCounts.get(entry.skeleton) ?? 0) + 1);
-	}
+	const listed = new Set(entries.map((entry) => entry.name));
+	const counts = countComparableForms(entries);
+	const localCounts = countComparableForms([...new Set(localNames)].filter((name) => !listed.has(name)).map(comparableFormsOf));
 	const notes = /* @__PURE__ */ new Map();
 	for (const entry of entries) {
 		const reasons = [];
-		const sameDisplayForm = displayFormCounts.get(entry.displayForm) ?? 0;
+		const sameDisplayForm = counts.displayForms.get(entry.displayForm) ?? 0;
+		const sameLocalDisplayForm = localCounts.displayForms.get(entry.displayForm) ?? 0;
 		if (sameDisplayForm > 1) reasons.push("another entry has the same display form");
-		if ((skeletonCounts.get(entry.skeleton) ?? 0) > sameDisplayForm) reasons.push("another entry differs from it only by lookalike letters");
+		else if (sameLocalDisplayForm > 0) reasons.push("a local skill has the same display form");
+		if ((counts.skeletons.get(entry.skeleton) ?? 0) > sameDisplayForm) reasons.push("another entry differs from it only by lookalike letters");
+		else if ((localCounts.skeletons.get(entry.skeleton) ?? 0) > sameLocalDisplayForm) reasons.push("a local skill differs from it only by lookalike letters");
+		if (hasWhitespaceThatDoesNotShow(entry.name)) reasons.push("carries more whitespace than the row shows");
 		const mixedScripts = mixedScriptsOf(entry.displayForm);
 		if (mixedScripts === void 0) {
 			const impostorScript = scriptReadAsLatin(entry.name);
@@ -5494,7 +5653,7 @@ const SKILL_PROMPT_SHORTCUTS = {
 	invert: "i"
 };
 /**
-* How wide a label the prompt draws, in terminal columns.
+* The widest label the prompt draws, in terminal columns.
 *
 * A directory name can be 255 bytes long, which wraps across several lines of a
 * terminal and lets a name padded with spaces paint what looks like another
@@ -5506,14 +5665,95 @@ const SKILL_PROMPT_SHORTCUTS = {
 * Columns rather than characters, because the two part ways precisely where an
 * attacker would want them to: 66 ideographic spaces are 66 characters and 132
 * columns, so a limit counted in characters would wave them through.
+*
+* A ceiling rather than the budget itself: the terminal has the other half of
+* the say, and `skillLabelBudget` takes the smaller of the two.
 */
 const MAX_SKILL_LABEL_WIDTH = 72;
 /**
+* What the prompt draws in front of a label, in columns.
+*
+* `@inquirer/checkbox` renders each row as `${cursor}${checkbox} ${name}` (its
+* `renderItem`, as of 5.2.2): the pointer, the box, and the space between the
+* box and the label. Nothing is drawn in front of a continuation line, so a
+* label that overruns the row paints its tail flush against the left margin,
+* which is exactly where a padded name wants it.
+*
+* The widest the three can come to rather than the width they usually are, and
+* what sets that is the fallback. `@inquirer/figures` draws the pointer and the
+* box as `❯` and `◯` where the terminal has the font for them and as `>` and
+* `( )` where it does not — the Linux console, and the older Windows console
+* outside Terminal — and the fallback box alone is three columns, for five in
+* all. The Unicode spelling comes to four at its widest: of the three glyphs
+* only `◯` is East Asian Ambiguous, which this project counts at one column and
+* a terminal set to draw the ambiguous characters wide draws at two, while the
+* pointer `❯` and the checked box `◉` are Neutral and stay at one either way.
+*
+* Five, then, because a budget two columns short is a row that wraps, and two
+* columns spent on a prefix that turned out to be narrower is two characters of
+* a name.
+*/
+const CHOICE_PREFIX_WIDTH = 5;
+/**
+* The width to assume when the terminal does not say how wide it is.
+*
+* The same 80 that `@inquirer/core` falls back to when it wraps the rows
+* (`readlineWidth`, by way of `cli-width`), so the budget is derived from the
+* width the rows are actually broken at rather than from a second guess.
+*/
+const FALLBACK_TERMINAL_WIDTH = 80;
+/**
 * How much of a name survives however long the note in front of it is. A name
 * cut to nothing would leave the picker choosing between rows it cannot tell
-* apart at all, which is worse than a label that wraps.
+* apart at all, which is worse than a name cut short.
+*
+* It is what a name is given where there is that much to give: in a terminal
+* too narrow for both, the row is shared out rather than overrun, since a label
+* wider than its budget wraps onto a line that carries no marker of the
+* prompt's own — which is the row this whole module exists to keep a name from
+* painting.
 */
 const MIN_SHORTENED_NAME_WIDTH = 16;
+/**
+* How wide a label may be in the terminal it is about to be drawn in.
+*
+* The cap above is not enough on its own: `@inquirer/core` breaks every
+* rendered row at the real terminal width, and the columns of pointer and
+* checkbox come out of that width without being repeated on the continuation
+* line. In anything narrower than 77 columns — a 120-column window split in
+* half is 60 — a 72-column label wraps, and the second line a name can paint
+* beneath itself is back, carrying no note, since a name padded with ordinary
+* visible characters is not confusable with anything.
+*
+* A width of zero is treated as no width at all rather than as a terminal three
+* columns narrower than nothing. A TTY reports it while it is being resized,
+* and `cli-width` — which is what decides where the rows are actually broken —
+* turns it into the same 80 this does, so taking it literally would budget
+* against a width the renderer never uses. (`cli-width` reads `CLI_WIDTH` from
+* the environment before it falls back to 80, which this does not; a prompt is
+* refused outright without a TTY, and a TTY answers before either is asked.)
+*
+* `process.stdout` is the same stream the renderer measures because `checkbox`
+* is called without an `output` option and `@inquirer/core` defaults the
+* readline output to it. A caller that passes one would decouple the budget
+* from the width the rows are broken at.
+*
+* Read once, before the prompt opens, where the renderer re-measures on every
+* render: a window narrowed while the picker is up puts the labels back over
+* the wrap point until it is closed and reopened. Recorded rather than solved,
+* since the checkbox API offers no way to relabel a prompt in flight.
+*
+* The floor is the one a name is kept to anyway, and below it there is nothing
+* left to shorten toward: a label cut past that point is an ellipsis and little
+* else, and a list of rows that cannot be told apart at all is worse than one
+* whose rows are too long for the window. In a terminal that narrow the row
+* wraps whatever this returns, so the floor is where the shortening stops
+* rather than a width anything is promised to fit in.
+*/
+function skillLabelBudget() {
+	const terminalWidth = process.stdout.columns || FALLBACK_TERMINAL_WIDTH;
+	return Math.max(Math.min(MAX_SKILL_LABEL_WIDTH, terminalWidth - CHOICE_PREFIX_WIDTH), MIN_SHORTENED_NAME_WIDTH);
+}
 /** Marks the label as carrying the tool's own warning rather than a name. */
 const NOTE_MARKER = "[!] ";
 /** Separates the note from the name; an em dash appears in no directory name. */
@@ -5533,6 +5773,14 @@ const NOTE_SEPARATOR = " — ";
 * note, and the reasons are ordered by weight, so a cut takes them from the
 * tail: the marker survives every time, and so does the beginning of the first
 * reason.
+*
+* The name is given `MIN_SHORTENED_NAME_WIDTH` columns however long the note
+* is, but never more than the row has left after the marker, the separator and
+* the one column a cut note is still drawn in. That is what shares out a
+* terminal too narrow to seat both, and the composed label is cut to the budget
+* on the way out, so what is returned is the width it was budgeted or less
+* however the pieces fall — a wider label wraps onto a line the prompt draws no
+* marker on, which is the row this module exists to keep a name from painting.
 */
 function formatSkillChoiceLabel(params) {
 	const { name, note, budget } = params;
@@ -5543,13 +5791,16 @@ function formatSkillChoiceLabel(params) {
 	const available = budget - require_import.displayWidthOf(NOTE_MARKER) - require_import.displayWidthOf(NOTE_SEPARATOR);
 	const shownName = require_import.shortenToWidth({
 		text: name,
-		budget: Math.max(available - require_import.displayWidthOf(note), MIN_SHORTENED_NAME_WIDTH)
+		budget: Math.min(Math.max(available - require_import.displayWidthOf(note), MIN_SHORTENED_NAME_WIDTH), Math.max(available - 1, 0))
 	});
 	const shownNote = require_import.shortenToWidth({
 		text: note,
 		budget: available - require_import.displayWidthOf(shownName)
 	});
-	return `${NOTE_MARKER}${shownNote}${NOTE_SEPARATOR}${shownName}`;
+	return require_import.shortenToWidth({
+		text: `${NOTE_MARKER}${shownNote}${NOTE_SEPARATOR}${shownName}`,
+		budget
+	});
 }
 /**
 * The text a name is given a note of its own for starting with: the mark this
@@ -5597,7 +5848,7 @@ function numberPrefixOf(position) {
 * note can — but it does say they are two rows and not one printed twice.
 */
 function formatSkillChoiceLabels(params) {
-	const { names, notes } = params;
+	const { names, notes, budget } = params;
 	const noteFor = (name) => {
 		const reasons = [PROMPT_MARKUP_PATTERN.test(readingFormOf(name)) ? PROMPT_MARKUP_NOTE : void 0, notes.get(name)].filter((reason) => reason !== void 0);
 		return reasons.length > 0 ? reasons.join("; ") : void 0;
@@ -5606,7 +5857,7 @@ function formatSkillChoiceLabels(params) {
 	const labels = names.map((name, index) => formatSkillChoiceLabel({
 		name,
 		note: notesByIndex[index],
-		budget: MAX_SKILL_LABEL_WIDTH
+		budget
 	}));
 	const readings = labels.map((label) => readingFormOf(label));
 	const counts = /* @__PURE__ */ new Map();
@@ -5618,7 +5869,7 @@ function formatSkillChoiceLabels(params) {
 		return `${prefix}${formatSkillChoiceLabel({
 			name,
 			note: notesByIndex[index],
-			budget: MAX_SKILL_LABEL_WIDTH - require_import.displayWidthOf(prefix)
+			budget: budget - require_import.displayWidthOf(prefix)
 		})}`;
 	});
 }
@@ -5631,13 +5882,21 @@ function formatSkillChoiceLabels(params) {
 * @param availableSkills - Skill names discovered in the source repository
 * @param preselectedSkills - Skill names to pre-check (from --skills); when
 *   empty, every skill starts unchecked and the user opts in
+* @param localSkillNames - Skill names already in the output directory. Only
+*   compared against, never offered: a row is marked for reading like a skill
+*   the user already has, which is the collision no listing of the source
+*   repository can show.
 * @returns The skill names the user selected
 */
 async function promptSkillSelection(params) {
-	const { availableSkills, preselectedSkills } = params;
+	const { availableSkills, preselectedSkills, localSkillNames } = params;
 	const labels = formatSkillChoiceLabels({
 		names: availableSkills,
-		notes: describeConfusableNames(availableSkills)
+		notes: describeConfusableNames({
+			names: availableSkills,
+			localNames: localSkillNames
+		}),
+		budget: skillLabelBudget()
 	});
 	try {
 		return await (0, _inquirer_checkbox.default)({
@@ -5821,7 +6080,9 @@ function resolveFeatures(features) {
 	return features.filter((f) => require_import.ALL_FEATURES.includes(f));
 }
 /** Where a skill directory sits, under the output base path and in the remote. */
-const SKILLS_DIR_PREFIX = "skills/";
+const SKILLS_DIR_NAME = "skills";
+/** The same directory as the head of a POSIX path, for prefix comparisons. */
+const SKILLS_DIR_PREFIX = `${SKILLS_DIR_NAME}/`;
 /**
 * The one `non-skill` verdict, shared by every caller that reaches it. It is
 * frozen because it is shared: a verdict is a value, and one handed out this
@@ -5938,9 +6199,14 @@ function validateSkillSelectionOptions(params) {
 * Files outside the skills directory pass through untouched.
 */
 async function applySkillSelection(params) {
-	const { files, requestedSkills, interactive, logger } = params;
+	const { files, requestedSkills, interactive, outputBasePath, logger } = params;
 	const selectsEverything = requestedSkills.length === 0 && !interactive;
 	const availableSkills = listAvailableSkills(files);
+	const localSkillNames = await localSkillNamesToCompare({
+		outputBasePath,
+		localNames: await readSkillRootNames(outputBasePath),
+		listedNames: availableSkills
+	});
 	let selectedSkills = [];
 	if (!selectsEverything) {
 		if (requestedSkills.length > 0) {
@@ -5957,7 +6223,8 @@ async function applySkillSelection(params) {
 		} else {
 			selectedSkills = await promptSkillSelection({
 				availableSkills,
-				preselectedSkills: requestedSkills
+				preselectedSkills: requestedSkills,
+				localSkillNames
 			});
 			if (selectedSkills.length === 0) logger.warn("No skills were selected in the interactive prompt; skipping all skills.");
 		}
@@ -5977,7 +6244,8 @@ async function applySkillSelection(params) {
 	if (!interactive) {
 		const confusable = formatConfusableSkillsWarning({
 			fetched: listAvailableSkills(selected),
-			available: availableSkills
+			available: availableSkills,
+			localSkillNames
 		});
 		if (confusable !== void 0) logger.warn(confusable);
 	}
@@ -6007,17 +6275,21 @@ function formatCappedList(params) {
 *
 * The same notes the interactive prompt puts beside a row, for the runs that
 * have no prompt to put them beside — judged the way the prompt judges them,
-* against every name the repository publishes rather than against the few a
-* `--skills` run picked out of them. It changes nothing about what is fetched:
-* a name that reads like another is still a name the user asked for, on a path
-* where there is nobody to ask.
+* against every name the repository publishes and every skill already in the
+* output directory, rather than against the few a `--skills` run picked out of
+* them. It changes nothing about what is fetched: a name that reads like
+* another is still a name the user asked for, on a path where there is nobody
+* to ask.
 */
 function formatConfusableSkillsWarning(params) {
-	const { fetched, available } = params;
+	const { fetched, available, localSkillNames } = params;
 	const fetchedNames = new Set(fetched);
-	const notes = new Map([...describeConfusableNames(available)].filter(([name]) => fetchedNames.has(name)));
+	const notes = new Map([...describeConfusableNames({
+		names: available,
+		localNames: localSkillNames
+	})].filter(([name]) => fetchedNames.has(name)));
 	if (notes.size === 0) return;
-	return `Some fetched skill names may not be told apart on sight from another name the source repository publishes, which this run may not have fetched: ${formatCappedList({
+	return `Some fetched skill names may not be told apart on sight from what they appear to be — from another name the source repository publishes, which this run may not have fetched, from a skill already in the output directory, or from the plainer name the row itself reads as: ${formatCappedList({
 		items: [...notes].toSorted(([a], [b]) => a < b ? -1 : 1).map(([name, note]) => `${JSON.stringify(require_import.stripControlCharacters(name))} (${note})`),
 		separator: "; "
 	})}. Check that each is the skill you meant to fetch.`;
@@ -6052,19 +6324,72 @@ function formatDroppedSkillsWarning(droppedUnsafeNames) {
 /**
 * The names the local skills directory holds, or none when it is not there.
 *
-* Read once per fetch and only to compare names against each other: what is on
-* disk is how a case-insensitive filesystem shows itself, since a write to
-* `skills/PDF` lands in an existing `skills/pdf` and leaves the old name behind
-* in the listing.
+* Read only to compare names against each other: what is on disk is how a
+* case-insensitive filesystem shows itself, since a write to `skills/PDF` lands
+* in an existing `skills/pdf` and leaves the old name behind in the listing.
+*
+* Read twice per fetch, and the two readings are of different moments on
+* purpose: the comparison reads before anything is written, so that it sees the
+* skills the user already had rather than the ones this run is adding, and the
+* prune reads after the writes, so that it sees what the run left behind.
+*
+* A symlink standing where a skill directory would be counts as one. `readdir`
+* reports the link rather than what it points at, and a skill kept as a link
+* into a shared tree — an ordinary arrangement in a monorepo — is a skill the
+* user has. The link is counted without asking what is behind it, so a link to
+* a file is counted too: both callers only ever read the names, and a name too
+* many can only make the comparison mention a pair it need not have, or keep
+* the prune from deleting something. Nothing here follows a link, and the prune
+* walk's own guard is what keeps a delete from reaching through one.
 */
 async function readSkillRootNames(outputBasePath) {
 	try {
-		return (await (0, node_fs_promises.readdir)((0, node_path.join)(outputBasePath, SKILLS_DIR_PREFIX), { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+		return (await (0, node_fs_promises.readdir)((0, node_path.join)(outputBasePath, SKILLS_DIR_NAME), { withFileTypes: true })).filter((entry) => entry.isDirectory() || entry.isSymbolicLink()).map((entry) => entry.name).toSorted();
 	} catch {
 		return [];
 	}
 }
 /**
+* The local skill names an incoming listing is worth being compared against.
+*
+* A name the fetch would write into is the skill being refreshed rather than
+* one imitating it, and marking it would put a note on a row that is doing
+* exactly what the user asked. An identical spelling is that case and
+* `describeConfusableNames` drops it on its own. The spellings that differ only
+* in case, or only in how the name is composed in Unicode, are the ones no
+* comparison of names can settle: `skills/PDF` is `skills/pdf` on macOS and
+* Windows and a second directory on Linux, so the same pair is a quiet refresh
+* on one machine and two directories that read alike on another.
+*
+* So the filesystem is asked, once per ambiguous pair. A listed name that is
+* absent from the listing but resolves to a directory anyway is a name this
+* filesystem folds onto one of the entries, and the local name it folds onto is
+* dropped; where it resolves to nothing, the two are separate directories and
+* the local name stays in the comparison. Dropping it also asks that the two
+* read alike, so that a local name a second entry imitates keeps its place on
+* the comparison even while the first entry refreshes it. That the listed name comes from the
+* remote repository is safe to join here without a further check: it case-folds
+* onto a name `readdir` returned, and no separator survives being folded into
+* one that holds none.
+*/
+async function localSkillNamesToCompare(params) {
+	const { outputBasePath, localNames, listedNames } = params;
+	const localSpellings = new Set(localNames);
+	const listedByIdentity = require_import.groupSpellingsByCaseFoldedIdentity(listedNames);
+	const kept = [];
+	for (const localName of localNames) {
+		const localReading = readingFormOf(localName);
+		const twins = (listedByIdentity.get(require_import.caseFoldIdentity(localName)) ?? []).filter((name) => name !== localName && !localSpellings.has(name) && readingFormOf(name) === localReading);
+		let folded = false;
+		for (const twin of twins) if (await require_import.directoryExists((0, node_path.join)(outputBasePath, SKILLS_DIR_NAME, twin))) {
+			folded = true;
+			break;
+		}
+		if (!folded) kept.push(localName);
+	}
+	return kept;
+}
+/**
 * Whether the set holds `root` itself or anything beneath it. Both sides are
 * POSIX paths, so a plain prefix comparison is enough.
 */
@@ -6144,11 +6469,11 @@ async function pruneDirectory(params) {
 	const { outputBasePath, relativeDirPath, fetchedPaths, fetchedIds, deleted, depth = 0, logger } = params;
 	const dirPath = (0, node_path.join)(outputBasePath, relativeDirPath);
 	if (depth > 15) {
-		logger.warn(`Not pruning below ${require_import.stripControlCharacters(relativeDirPath)}: it is more than 15 directories deep.`);
+		logger.warn(`Not pruning below ${JSON.stringify(require_import.stripControlCharacters(relativeDirPath))}: it is more than 15 directories deep.`);
 		return "kept";
 	}
 	if (await isSymbolicLink(dirPath)) {
-		logger.warn(`Not pruning ${require_import.stripControlCharacters(relativeDirPath)}: it is a symbolic link, and its target is outside what this fetch may delete from. Remove unwanted files by hand.`);
+		logger.warn(`Not pruning ${JSON.stringify(require_import.stripControlCharacters(relativeDirPath))}: it is a symbolic link, and its target is outside what this fetch may delete from. Remove unwanted files by hand.`);
 		return "kept";
 	}
 	let entries;
@@ -6177,7 +6502,7 @@ async function pruneDirectory(params) {
 				relativePath: entryRelativePath,
 				status: "deleted"
 			});
-			logger.debug(`Deleted stale skill entry: ${require_import.stripControlCharacters(entryRelativePath)}`);
+			logger.debug(`Deleted stale skill entry: ${JSON.stringify(require_import.stripControlCharacters(entryRelativePath))}`);
 			continue;
 		}
 		if (entry.isDirectory()) {
@@ -6208,7 +6533,7 @@ async function pruneDirectory(params) {
 				relativePath: `${entryRelativePath}/`,
 				status: "deleted"
 			});
-			logger.debug(`Removed stale skill directory: ${require_import.stripControlCharacters(entryRelativePath)}`);
+			logger.debug(`Removed stale skill directory: ${JSON.stringify(require_import.stripControlCharacters(entryRelativePath))}`);
 			continue;
 		}
 		if (fetchedPaths.has(entryRelativePath)) {
@@ -6225,7 +6550,7 @@ async function pruneDirectory(params) {
 			relativePath: entryRelativePath,
 			status: "deleted"
 		});
-		logger.debug(`Deleted stale skill file: ${require_import.stripControlCharacters(entryRelativePath)}`);
+		logger.debug(`Deleted stale skill file: ${JSON.stringify(require_import.stripControlCharacters(entryRelativePath))}`);
 	}
 	return survivors > 0 ? "kept" : "emptied";
 }
@@ -6308,22 +6633,22 @@ async function pruneStaleSkillFiles(params) {
 	const deleted = [];
 	for (const [skillDir, remoteDir] of [...skillDirs].toSorted(([a], [b]) => a < b ? -1 : 1)) {
 		if (remoteDir === void 0) {
-			logger.warn(`Not pruning ${require_import.stripControlCharacters(skillDir)}: the remote directory it was fetched from could not be worked out, so there is nothing to judge the local files against. Remove unwanted files by hand.`);
+			logger.warn(`Not pruning ${JSON.stringify(require_import.stripControlCharacters(skillDir))}: the remote directory it was fetched from could not be worked out, so there is nothing to judge the local files against. Remove unwanted files by hand.`);
 			continue;
 		}
 		if (hasPathAtOrUnder(incompleteRemoteDirs, remoteDir)) {
-			logger.warn(`Not pruning ${require_import.stripControlCharacters(skillDir)}: the remote listing for it came back incomplete, so a stale local file cannot be told apart from one the listing left out. Remove unwanted files by hand.`);
+			logger.warn(`Not pruning ${JSON.stringify(require_import.stripControlCharacters(skillDir))}: the remote listing for it came back incomplete, so a stale local file cannot be told apart from one the listing left out. Remove unwanted files by hand.`);
 			continue;
 		}
 		if (/[.\s]$/.test(skillDir) || /~\d+(?:\.[^.]*)?$/.test(skillDir)) {
-			logger.warn(`Not pruning ${require_import.stripControlCharacters(skillDir)}: its name is one some systems resolve to a different directory, so it may not be the directory this name reads as. Remove unwanted files by hand.`);
+			logger.warn(`Not pruning ${JSON.stringify(require_import.stripControlCharacters(skillDir))}: its name is one some systems resolve to a different directory, so it may not be the directory this name reads as. Remove unwanted files by hand.`);
 			continue;
 		}
-		const skillName = skillDir.slice(7);
+		const skillName = skillDir.slice(SKILLS_DIR_PREFIX.length);
 		const foldedSkillName = require_import.caseFoldIdentity(skillName);
 		const variant = localSkillNames.find((entry) => entry !== skillName && require_import.caseFoldIdentity(entry) === foldedSkillName);
 		if (variant !== void 0) {
-			logger.warn(`Not pruning ${require_import.stripControlCharacters(skillDir)}: ${SKILLS_DIR_PREFIX}${require_import.stripControlCharacters(variant)} is also there and differs only in ways some filesystems ignore, so this name may not be the directory it reads as. Remove unwanted files by hand.`);
+			logger.warn(`Not pruning ${JSON.stringify(require_import.stripControlCharacters(skillDir))}: ${JSON.stringify(`${SKILLS_DIR_PREFIX}${require_import.stripControlCharacters(variant)}`)} is also there and differs only in ways some filesystems ignore, so this name may not be the directory it reads as. Remove unwanted files by hand.`);
 			continue;
 		}
 		require_import.checkPathTraversal({
@@ -6340,8 +6665,8 @@ async function pruneStaleSkillFiles(params) {
 				logger
 			});
 		} catch (error) {
-			if (!isFileSystemError(error)) throw error;
-			logger.warn(`Stopped partway through pruning ${require_import.stripControlCharacters(skillDir)}. ${require_import.stripControlCharacters(require_import.formatError(error))}`);
+			if (!require_import.isFileSystemError(error)) throw error;
+			logger.warn(`Stopped partway through pruning ${JSON.stringify(require_import.stripControlCharacters(skillDir))}. ${require_import.stripControlCharacters(require_import.formatError(error))}`);
 		}
 	}
 	if (deleted.length > 0) logger.warn(`Deleted ${deleted.length} local ${deleted.length === 1 ? "path" : "paths"} inside the skill ${skillDirs.size === 1 ? "directory" : "directories"} this fetch wrote, because the remote skill no longer has ${deleted.length === 1 ? "it" : "them"}. They are listed in the summary below. Pass --no-prune to keep local files instead.`);
@@ -6355,14 +6680,6 @@ function isSymbolicLinkLoopError(error) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === "ELOOP";
 }
 /**
-* Whether the error came from the filesystem rather than from the walk itself.
-* Node stamps every `fs` rejection with a `code`, so its presence is what tells
-* an I/O failure apart from a programming error raised in the same call.
-*/
-function isFileSystemError(error) {
-	return error instanceof Error && "code" in error && typeof error.code === "string";
-}
-/**
 * Whether removing the directory failed because something is still in it.
 */
 function isDirectoryNotEmptyError(error) {
@@ -6440,11 +6757,12 @@ async function fetchFiles(params) {
 		relativePath: outputDir,
 		intendedRootDir: outputRoot
 	});
+	const outputBasePath = (0, node_path.join)(outputRoot, outputDir);
 	const client = new GitHubClient({ token: GitHubClient.resolveToken(options.token) });
 	logger.debug(`Validating repository: ${parsed.owner}/${parsed.repo}`);
 	if (!await client.validateRepository(parsed.owner, parsed.repo)) throw new GitHubClientError(`Repository not found: ${parsed.owner}/${parsed.repo}. Check the repository name and your access permissions.`, 404);
 	const ref = resolvedRef ?? await client.getDefaultBranch(parsed.owner, parsed.repo);
-	logger.debug(`Using ref: ${require_import.stripControlCharacters(ref)}`);
+	logger.debug(`Using ref: ${JSON.stringify(require_import.stripControlCharacters(ref))}`);
 	if (isToolTarget(target)) return fetchAndConvertToolFiles({
 		client,
 		parsed,
@@ -6474,6 +6792,7 @@ async function fetchFiles(params) {
 		files: collectedFiles,
 		requestedSkills,
 		interactive,
+		outputBasePath,
 		logger
 	});
 	if (filesToFetch.length === 0) {
@@ -6483,7 +6802,6 @@ async function fetchFiles(params) {
 			ref
 		});
 	}
-	const outputBasePath = (0, node_path.join)(outputRoot, outputDir);
 	for (const { relativePath, size } of filesToFetch) {
 		require_import.checkPathTraversal({
 			relativePath,
@@ -6495,7 +6813,7 @@ async function fetchFiles(params) {
 		const localPath = (0, node_path.join)(outputBasePath, relativePath);
 		const exists = await require_import.fileExists(localPath);
 		if (exists && conflictStrategy === "skip") {
-			logger.debug(`Skipping existing file: ${require_import.stripControlCharacters(relativePath)}`);
+			logger.debug(`Skipping existing file: ${JSON.stringify(require_import.stripControlCharacters(relativePath))}`);
 			return {
 				relativePath,
 				status: "skipped"
@@ -6504,7 +6822,7 @@ async function fetchFiles(params) {
 		const content = await withSemaphore(semaphore, () => client.getFileContent(parsed.owner, parsed.repo, remotePath, ref));
 		await require_import.writeFileContent(localPath, content);
 		const status = exists ? "overwritten" : "created";
-		logger.debug(`Wrote: ${require_import.stripControlCharacters(relativePath)} (${status})`);
+		logger.debug(`Wrote: ${JSON.stringify(require_import.stripControlCharacters(relativePath))} (${status})`);
 		return {
 			relativePath,
 			status
@@ -6561,7 +6879,7 @@ async function collectFeatureFiles(params) {
 						size: fileEntry.size
 					});
 				} catch (error) {
-					if (isNotFoundError(error)) logger.debug(`File not found: ${require_import.stripControlCharacters(fullPath)}`);
+					if (isNotFoundError(error)) logger.debug(`File not found: ${JSON.stringify(require_import.stripControlCharacters(fullPath))}`);
 					else throw error;
 				}
 				else {
@@ -6587,7 +6905,7 @@ async function collectFeatureFiles(params) {
 				}
 			} catch (error) {
 				if (isNotFoundError(error)) {
-					logger.debug(`Feature not found: ${require_import.stripControlCharacters(fullPath)}`);
+					logger.debug(`Feature not found: ${JSON.stringify(require_import.stripControlCharacters(fullPath))}`);
 					return collected;
 				}
 				throw error;
@@ -6608,6 +6926,7 @@ async function collectFeatureFiles(params) {
 */
 async function fetchAndConvertToolFiles(params) {
 	const { client, parsed, ref, resolvedPath, enabledFeatures, requestedSkills, interactive, target, outputDir, outputRoot, conflictStrategy: _conflictStrategy, logger } = params;
+	const outputBasePath = (0, node_path.join)(outputRoot, outputDir);
 	const tempDir = await require_import.createTempDirectory();
 	logger.debug(`Created temp directory: ${tempDir}`);
 	const semaphore = new es_toolkit_promise.Semaphore(10);
@@ -6626,6 +6945,7 @@ async function fetchAndConvertToolFiles(params) {
 			files: collectedFiles,
 			requestedSkills,
 			interactive,
+			outputBasePath,
 			logger
 		});
 		if (filesToFetch.length === 0) {
@@ -6650,7 +6970,7 @@ async function fetchAndConvertToolFiles(params) {
 		}));
 		const { converted, convertedPaths } = await convertFetchedFilesToRulesync({
 			tempDir,
-			outputDir: (0, node_path.join)(outputRoot, outputDir),
+			outputDir: outputBasePath,
 			target,
 			features: enabledFeatures,
 			logger
@@ -8108,8 +8428,14 @@ const gitignoreCommand = async (logger, options) => {
 		logger.captureData("entriesRemoved", gitignoreResult.entriesRemoved);
 	}
 	if (gitignoreResult.entriesRemoved.length > 0) {
-		logger.warn("The following entries were removed from the rulesync-managed block in .gitignore and are no longer gitignored by rulesync:");
-		for (const entry of gitignoreResult.entriesRemoved) logger.warn(`  ${entry}`);
+		if (logger.jsonMode) {
+			const removedCount = gitignoreResult.entriesRemoved.length;
+			const single = removedCount === 1;
+			logger.warn(`${removedCount} ${single ? "entry" : "entries"} listed under "entriesRemoved" ${single ? "was" : "were"} removed from the rulesync-managed block in .gitignore and ${single ? "is" : "are"} no longer gitignored by rulesync.`);
+		} else {
+			logger.warn("The following entries were removed from the rulesync-managed block in .gitignore and are no longer gitignored by rulesync:");
+			for (const entry of gitignoreResult.entriesRemoved) logger.warn(`  ${entry}`);
+		}
 		logger.warn("Review these paths before committing — user-managed settings files may contain secrets.");
 	}
 	if (gitignoreResult.updated) logger.success("Updated .gitignore with rulesync entries:");
@@ -9718,7 +10044,7 @@ const maxChecksCount = 1e3;
 async function listChecks() {
 	const checksDir = (0, node_path.join)(process.cwd(), require_import.RULESYNC_CHECKS_RELATIVE_DIR_PATH);
 	try {
-		const mdFiles = (await require_import.listDirectoryFiles(checksDir)).filter((file) => file.endsWith(".md"));
+		const mdFiles = (await require_import.listDirectoryEntryNames(checksDir)).filter((file) => file.endsWith(".md"));
 		return (await Promise.all(mdFiles.map(async (file) => {
 			try {
 				const check = await require_import.RulesyncCheck.fromFile({
@@ -9885,7 +10211,7 @@ const maxCommandsCount = 1e3;
 async function listCommands() {
 	const commandsDir = (0, node_path.join)(process.cwd(), require_import.RULESYNC_COMMANDS_RELATIVE_DIR_PATH);
 	try {
-		const mdFiles = (await require_import.listDirectoryFiles(commandsDir)).filter((file) => file.endsWith(".md"));
+		const mdFiles = (await require_import.listDirectoryEntryNames(commandsDir)).filter((file) => file.endsWith(".md"));
 		return (await Promise.all(mdFiles.map(async (file) => {
 			try {
 				require_import.checkPathTraversal({
@@ -10039,6 +10365,13 @@ const commandTools = {
 	}
 };
 //#endregion
+//#region src/mcp/types.ts
+/** Spreads into a result, contributing the key only when there is something in it. */
+function warningsField(logger) {
+	const warnings = logger.getWarnings();
+	return warnings.length > 0 ? { warnings } : {};
+}
+//#endregion
 //#region src/mcp/convert.ts
 /**
 * Schema for convert options
@@ -10065,54 +10398,61 @@ function parseToolTarget(value, label) {
 * Configuration priority: MCP Parameters > rulesync.local.jsonc > rulesync.jsonc > Default values
 */
 async function executeConvert$1(options) {
+	const logger = new require_import.WarningCollectingLogger({
+		verbose: false,
+		silent: true
+	});
 	try {
-		if (!options.from) return {
-			success: false,
-			error: "from is required. Please specify a source tool to convert from."
-		};
-		if (!options.to || options.to.length === 0) return {
-			success: false,
-			error: "to is required and must not be empty. Please specify destination tools."
-		};
-		const fromTool = parseToolTarget(options.from, "source");
-		const toToolsRaw = options.to.map((t) => parseToolTarget(t, "destination"));
-		const toTools = Array.from(new Set(toToolsRaw));
-		if (toTools.includes(fromTool)) return {
-			success: false,
-			error: `Destination tools must not include the source tool '${fromTool}'. Converting a tool onto itself is likely a mistake and may cause lossy round-trips.`
-		};
-		const config = await require_import.ConfigResolver.resolve({
-			targets: [fromTool, ...toTools],
-			features: options.features ?? ["*"],
-			global: options.global,
-			dryRun: options.dryRun,
-			verbose: false,
-			silent: true
-		});
-		const logger = new require_import.ConsoleLogger({
-			verbose: false,
-			silent: true
-		});
-		return buildSuccessResponse$2({
-			convertResult: await require_import.convertFromTool({
-				config,
-				fromTool,
-				toTools,
-				logger
-			}),
-			config,
-			fromTool,
-			toTools
+		return await require_import.withFallbackLoggerTarget({
+			logger,
+			operation: async () => {
+				if (!options.from) return {
+					success: false,
+					error: "from is required. Please specify a source tool to convert from."
+				};
+				if (!options.to || options.to.length === 0) return {
+					success: false,
+					error: "to is required and must not be empty. Please specify destination tools."
+				};
+				const fromTool = parseToolTarget(options.from, "source");
+				const toToolsRaw = options.to.map((t) => parseToolTarget(t, "destination"));
+				const toTools = Array.from(new Set(toToolsRaw));
+				if (toTools.includes(fromTool)) return {
+					success: false,
+					error: `Destination tools must not include the source tool '${fromTool}'. Converting a tool onto itself is likely a mistake and may cause lossy round-trips.`
+				};
+				const config = await require_import.ConfigResolver.resolve({
+					targets: [fromTool, ...toTools],
+					features: options.features ?? ["*"],
+					global: options.global,
+					dryRun: options.dryRun,
+					verbose: false,
+					silent: true
+				});
+				return buildSuccessResponse$2({
+					convertResult: await require_import.convertFromTool({
+						config,
+						fromTool,
+						toTools,
+						logger
+					}),
+					config,
+					fromTool,
+					toTools,
+					logger
+				});
+			}
 		});
 	} catch (error) {
 		return {
 			success: false,
-			error: require_import.formatError(error)
+			error: require_import.formatError(error),
+			...warningsField(logger)
 		};
 	}
 }
 function buildSuccessResponse$2(params) {
-	const { convertResult, config, fromTool, toTools } = params;
+	const { convertResult, config, fromTool, toTools, logger } = params;
 	const totalCount = calculateTotalCount(convertResult);
 	return {
 		success: true,
@@ -10134,12 +10474,13 @@ function buildSuccessResponse$2(params) {
 			features: config.getFeatures(),
 			global: config.getGlobal(),
 			dryRun: config.isPreviewMode()
-		}
+		},
+		...warningsField(logger)
 	};
 }
 const convertTools = { executeConvert: {
 	name: "executeConvert",
-	description: "Execute the rulesync convert command to convert configuration files between AI tools without writing intermediate .rulesync/ files. Requires a source tool (from) and one or more destination tools (to).",
+	description: "Execute the rulesync convert command to convert configuration files between AI tools without writing intermediate .rulesync/ files. Requires a source tool (from) and one or more destination tools (to). A 'warnings' array of strings is present, on success and on failure alike, when the run had something worth acting on to report.",
 	parameters: { executeConvert: convertOptionsSchema }.executeConvert,
 	execute: async (options) => {
 		const result = await executeConvert$1(options);
@@ -10149,34 +10490,66 @@ const convertTools = { executeConvert: {
 //#endregion
 //#region src/mcp/generate.ts
 /**
-* A logger that keeps what it reports as errors.
+* Keeps the reasons a `.rulesync/` source would not load, so the failure this
+* tool reports can name them.
 *
 * Over stdio MCP the server's own stderr does not reach the calling agent, so
 * a failure that is only logged is a failure the agent cannot act on. Holding
 * the messages lets the tool answer with the specific reason a source could not
 * be read — which file, and what was wrong with it — rather than just the fact
 * that something was.
-*/
-/**
-* Keeps the reasons a `.rulesync/` source would not load, so the failure this
-* tool reports can name them.
 *
 * Only the tagged lines are kept. Collecting every `error()` would fold in
 * whatever else the run happened to log — one line per target for an unrelated
 * tool config, say — and the agent reading the response would have to guess
-* which of them explains the failure.
+* which of them explains the failure. Warnings are the base class's job; this
+* one adds the error channel to it.
 */
-var CollectingLogger = class extends require_import.ConsoleLogger {
+var ErrorCollectingLogger = class extends require_import.WarningCollectingLogger {
 	errors = [];
+	errorsLength = 0;
+	omittedErrors = 0;
 	error(message, code, ...args) {
-		if (code === require_import.ErrorCodes.SOURCE_LOAD_FAILED) this.errors.push(message instanceof Error ? message.message : message);
+		if (code === require_import.ErrorCodes.SOURCE_LOAD_FAILED) this.collect(message instanceof Error ? message.message : message);
 		super.error(message, code, ...args);
 	}
+	collect(message) {
+		const kept = require_import.truncateText({
+			text: require_import.stripControlCharactersKeepingLineFeeds(message),
+			maxLength: MAX_COLLECTED_ERROR_LENGTH,
+			suffix: "…(truncated)"
+		});
+		if (this.errors.length >= MAX_COLLECTED_ERRORS || this.errorsLength + kept.length > MAX_COLLECTED_ERRORS_TOTAL_LENGTH) {
+			this.omittedErrors++;
+			return;
+		}
+		this.errors.push(kept);
+		this.errorsLength += kept.length;
+	}
 	getErrors() {
-		return this.errors;
+		if (this.omittedErrors === 0) return this.errors;
+		return [...this.errors, `… and ${this.omittedErrors} more source(s) that could not be read`];
 	}
 };
 /**
+* How many unreadable sources the failure names, and how much of each reason.
+*
+* These lines become the `error` of an MCP result the calling agent reads as
+* context, and each one quotes a file rulesync did not write. A `.rulesync/`
+* tree with a thousand broken sources is a plausible accident; a failure
+* message sized to it is not something an agent can act on, and the first few
+* reasons are what says which file to open.
+*/
+const MAX_COLLECTED_ERRORS = 20;
+const MAX_COLLECTED_ERROR_LENGTH = 1e3;
+/**
+* The binding limit, as it is for the collected warnings: the joined lines
+* become one `Error` message, and `formatError` bounds that in turn. Keeping
+* the sum under its bound is what makes the trailing "and N more" line survive
+* the join rather than being the part that gets truncated away.
+*/
+const MAX_COLLECTED_ERRORS_TOTAL_LENGTH = 4e3;
+/**
 * Schema for generate options
 * Excluded parameters:
 * - outputRoots: Always use [process.cwd()] in MCP context
@@ -10198,39 +10571,46 @@ const generateOptionsSchema = zod_mini.z.object({
 * Configuration priority: MCP Parameters > rulesync.local.jsonc > rulesync.jsonc > Default values
 */
 async function executeGenerate$1(options = {}) {
+	const logger = new ErrorCollectingLogger({
+		verbose: false,
+		silent: true
+	});
 	try {
-		const config = await require_import.ConfigResolver.resolve({
-			targets: options.targets,
-			features: options.features,
-			delete: options.delete,
-			global: options.global,
-			simulateCommands: options.simulateCommands,
-			simulateSubagents: options.simulateSubagents,
-			simulateSkills: options.simulateSkills,
-			verbose: false,
-			silent: true
-		});
-		const inputRoots = config.getInputRoots();
-		const inputRootInspection = await require_import.inspectInputRoots(inputRoots);
-		if (inputRootInspection.message !== void 0) throw new Error(inputRootInspection.message);
-		const logger = new CollectingLogger({
-			verbose: false,
-			silent: true
-		});
-		const generateResult = await require_import.generate({
-			config,
-			logger
-		});
-		const sourceLoadFailureMessage = require_import.formatSourceLoadFailure(generateResult);
-		if (sourceLoadFailureMessage !== void 0) throw new Error([sourceLoadFailureMessage, ...logger.getErrors()].join("\n"));
-		return buildSuccessResponse$1({
-			generateResult,
-			config
+		return await require_import.withFallbackLoggerTarget({
+			logger,
+			operation: async () => {
+				const config = await require_import.ConfigResolver.resolve({
+					targets: options.targets,
+					features: options.features,
+					delete: options.delete,
+					global: options.global,
+					simulateCommands: options.simulateCommands,
+					simulateSubagents: options.simulateSubagents,
+					simulateSkills: options.simulateSkills,
+					verbose: false,
+					silent: true
+				});
+				const inputRoots = config.getInputRoots();
+				const inputRootInspection = await require_import.inspectInputRoots(inputRoots);
+				if (inputRootInspection.message !== void 0) throw new Error(inputRootInspection.message);
+				const generateResult = await require_import.generate({
+					config,
+					logger
+				});
+				const sourceLoadFailureMessage = require_import.formatSourceLoadFailure(generateResult);
+				if (sourceLoadFailureMessage !== void 0) throw new Error([sourceLoadFailureMessage, ...logger.getErrors()].join("\n"));
+				return buildSuccessResponse$1({
+					generateResult,
+					config,
+					logger
+				});
+			}
 		});
 	} catch (error) {
 		return {
 			success: false,
-			error: require_import.formatError(error)
+			error: require_import.formatError(error),
+			...warningsField(logger)
 		};
 	}
 }
@@ -10250,7 +10630,7 @@ function buildGenerateMessage(params) {
 	return `No files needed updating for targets [${targets}] and features [${features}]. 'generate' only writes files whose content changed, so a totalCount of 0 means the outputs are already up to date — this is a successful no-op, not a failure.`;
 }
 function buildSuccessResponse$1(params) {
-	const { generateResult, config } = params;
+	const { generateResult, config, logger } = params;
 	const totalCount = calculateTotalCount(generateResult);
 	return {
 		success: true,
@@ -10279,12 +10659,13 @@ function buildSuccessResponse$1(params) {
 			simulateCommands: config.getSimulateCommands(),
 			simulateSubagents: config.getSimulateSubagents(),
 			simulateSkills: config.getSimulateSkills()
-		}
+		},
+		...warningsField(logger)
 	};
 }
 const generateTools = { executeGenerate: {
 	name: "executeGenerate",
-	description: "Execute the rulesync generate command to create output files for AI tools. Uses rulesync.jsonc settings by default, but options can override them. Idempotent: only files whose content changed are written, so a totalCount of 0 means the outputs are already up to date (a successful no-op), not a failure. See the 'message' field for a human-readable summary.",
+	description: "Execute the rulesync generate command to create output files for AI tools. Uses rulesync.jsonc settings by default, but options can override them. Idempotent: only files whose content changed are written, so a totalCount of 0 means the outputs are already up to date (a successful no-op), not a failure. See the 'message' field for a human-readable summary. A 'warnings' array of strings is present, on success and on failure alike, when the run had something worth acting on to report.",
 	parameters: { executeGenerate: generateOptionsSchema }.executeGenerate,
 	execute: async (options = {}) => {
 		const result = await executeGenerate$1(options);
@@ -10508,41 +10889,48 @@ const importOptionsSchema = zod_mini.z.object({
 * Configuration priority: MCP Parameters > rulesync.local.jsonc > rulesync.jsonc > Default values
 */
 async function executeImport$1(options) {
+	const logger = new require_import.WarningCollectingLogger({
+		verbose: false,
+		silent: true
+	});
 	try {
-		if (!options.target) return {
-			success: false,
-			error: "target is required. Please specify a tool to import from."
-		};
-		const config = await require_import.ConfigResolver.resolve({
-			targets: [options.target],
-			features: options.features,
-			global: options.global,
-			verbose: false,
-			silent: true
-		});
-		const tool = config.getTargets()[0];
-		const logger = new require_import.ConsoleLogger({
-			verbose: false,
-			silent: true
-		});
-		return buildSuccessResponse({
-			importResult: await require_import.importFromTool({
-				config,
-				tool,
-				logger
-			}),
-			config,
-			tool
+		return await require_import.withFallbackLoggerTarget({
+			logger,
+			operation: async () => {
+				if (!options.target) return {
+					success: false,
+					error: "target is required. Please specify a tool to import from."
+				};
+				const config = await require_import.ConfigResolver.resolve({
+					targets: [options.target],
+					features: options.features,
+					global: options.global,
+					verbose: false,
+					silent: true
+				});
+				const tool = config.getTargets()[0];
+				return buildSuccessResponse({
+					importResult: await require_import.importFromTool({
+						config,
+						tool,
+						logger
+					}),
+					config,
+					tool,
+					logger
+				});
+			}
 		});
 	} catch (error) {
 		return {
 			success: false,
-			error: require_import.formatError(error)
+			error: require_import.formatError(error),
+			...warningsField(logger)
 		};
 	}
 }
 function buildSuccessResponse(params) {
-	const { importResult, config, tool } = params;
+	const { importResult, config, tool, logger } = params;
 	const totalCount = calculateTotalCount(importResult);
 	return {
 		success: true,
@@ -10562,12 +10950,13 @@ function buildSuccessResponse(params) {
 			target: tool,
 			features: config.getFeatures(),
 			global: config.getGlobal()
-		}
+		},
+		...warningsField(logger)
 	};
 }
 const importTools = { executeImport: {
 	name: "executeImport",
-	description: "Execute the rulesync import command to import configuration files from an AI tool into .rulesync directory. Requires exactly one target tool to import from.",
+	description: "Execute the rulesync import command to import configuration files from an AI tool into .rulesync directory. Requires exactly one target tool to import from. A 'warnings' array of strings is present, on success and on failure alike, when the run had something worth acting on to report.",
 	parameters: { executeImport: importOptionsSchema }.executeImport,
 	execute: async (options) => {
 		const result = await executeImport$1(options);
@@ -10798,7 +11187,7 @@ const maxRulesCount = 1e3;
 async function listRules() {
 	const rulesDir = (0, node_path.join)(process.cwd(), require_import.RULESYNC_RULES_RELATIVE_DIR_PATH);
 	try {
-		const mdFiles = (await require_import.listDirectoryFiles(rulesDir)).filter((file) => file.endsWith(".md"));
+		const mdFiles = (await require_import.listDirectoryEntryNames(rulesDir)).filter((file) => file.endsWith(".md"));
 		return (await Promise.all(mdFiles.map(async (file) => {
 			try {
 				const frontmatter = (await require_import.RulesyncRule.fromFile({
@@ -11202,7 +11591,7 @@ const maxSubagentsCount = 1e3;
 async function listSubagents() {
 	const subagentsDir = (0, node_path.join)(process.cwd(), require_import.RULESYNC_SUBAGENTS_RELATIVE_DIR_PATH);
 	try {
-		const mdFiles = (await require_import.listDirectoryFiles(subagentsDir)).filter((file) => file.endsWith(".md"));
+		const mdFiles = (await require_import.listDirectoryEntryNames(subagentsDir)).filter((file) => file.endsWith(".md"));
 		return (await Promise.all(mdFiles.map(async (file) => {
 			try {
 				const frontmatter = (await require_import.RulesyncSubagent.fromFile({
@@ -11602,7 +11991,7 @@ const rulesyncTool = {
 	name: "rulesyncTool",
 	description: "Manage Rulesync files through a single MCP tool. Features: rule/command/subagent/skill/check support list/get/put/delete; ignore/mcp/permissions/hooks support get/put/delete only; generate supports run only; import supports run only; convert supports run only. Parameters: list requires no targetPathFromCwd (lists all items); get/delete require targetPathFromCwd; put requires targetPathFromCwd, frontmatter, and body (or content for ignore/mcp/permissions/hooks); generate/run uses generateOptions to configure generation; import/run uses importOptions to configure import; convert/run uses convertOptions to configure conversion. skill otherFiles entries accept an optional encoding (\"utf-8\" by default, \"base64\" for binary files) and are returned with the encoding they require.",
 	parameters: rulesyncToolSchema,
-	execute: async (args) => {
+	execute: async (args) => await require_import.withWarnOnceScope(async () => {
 		const parsed = rulesyncToolSchema.parse(args);
 		assertSupported({
 			feature: parsed.feature,
@@ -11610,8 +11999,8 @@ const rulesyncTool = {
 		});
 		const executor = featureExecutors[parsed.feature];
 		if (!executor) throw new Error(`Unknown feature: ${parsed.feature}`);
-		return executor(parsed);
-	}
+		return await executor(parsed);
+	})
 };
 //#endregion
 //#region src/cli/commands/mcp.ts
@@ -12133,8 +12522,13 @@ function wrapCommand$1({ name, errorCode, handler, getVersion, loggerFactory = c
 		logger.configure(cliLoggerOptions);
 		require_import.fallbackLogger.configure(cliLoggerOptions);
 		try {
-			await handler(logger, options, globalOpts, positionalArgs);
-			logger.outputJson(true);
+			await require_import.withFallbackLoggerTarget({
+				logger,
+				operation: async () => {
+					await handler(logger, options, globalOpts, positionalArgs);
+					logger.outputJson(true);
+				}
+			});
 		} catch (error) {
 			const code = error instanceof require_import.CLIError ? error.code : errorCode;
 			const errorArg = error instanceof Error ? error : require_import.formatError(error);
@@ -12145,7 +12539,7 @@ function wrapCommand$1({ name, errorCode, handler, getVersion, loggerFactory = c
 }
 //#endregion
 //#region src/cli/program.ts
-const getVersion = () => "16.18.0";
+const getVersion = () => "16.20.0";
 const FEATURES_HELP = `${require_import.ALL_FEATURES.join(",")}; ignore is deprecated, use permissions`;
 function wrapCommand(name, errorCode, handler) {
 	return wrapCommand$1({