ai-rulez 4.22.2 → 4.23.0

package/README.md

@@ -41,6 +41,8 @@ ai-rulez generates correct, tool-native output for **14 platforms**: Claude, Cur
 
 For a tool that isn't built in, a custom preset can point at a declarative **provider spec** (`provider = ".ai-rulez/providers/my-tool.toml"`) and get the same full feature set as a built-in — root instructions file, skills/agents/commands, per-agent frontmatter, and MCP sidecars. See [Custom Presets](docs/configuration.md#provider-backed-presets-full-parity).
 
+Set `agents_md = true` to write `AGENTS.md` and `.agents/skills/` once for the tools that read them (Codex, Cursor, Copilot, Gemini, Claude through an `@AGENTS.md` shim, and more) instead of one copy per tool. Off by default. See [docs/agents-md.md](docs/agents-md.md).
+
 ## Generate Plugins, Not Just Config
 
 ai-rulez doesn't only write config into _your_ repo — it also packages your project as **distributable plugins**. Run `ai-rulez generate --plugin` and the same `.ai-rulez/` source (skills, commands, agents, MCP servers) becomes installable **plugin bundles and a marketplace index** for Claude, Cursor, Codex, Gemini, Kimi, OpenCode, Factory, and Hermes Agent. An opt-in **Agent Plugins** runtime (`runtimes = ["agent-plugins"]`) additionally emits portable [Agent Plugins 1.0.0](https://agent-plugins.org) packages.
@@ -63,9 +65,10 @@ Set `builtins` in your config — `true` for every domain, or a list to pick —
 without being named, unless you exclude one with `!`. Omit the `builtins` field entirely and no builtin
 content is loaded at all.
 
-Each one ships **always-on content** (rules, or context such as the agent roster), inlined into
-`CLAUDE.md` and so read on every request, and some also ship **on-demand skills**, whose body costs
-nothing until the assistant loads it.
+Each one ships **always-on content** (rules, or context such as the agent roster) that is read on every
+request — rules in `.claude/rules/` under the default split mode (inlined into `CLAUDE.md` with
+`[rules] mode = "inline"`), context and the agent roster in `CLAUDE.md` — and some also ship
+**on-demand skills**, whose body costs nothing until the assistant loads it.
 
 | Domain               | Always-on rules                                                                                                            | On-demand skills                        |
 | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
@@ -161,14 +164,16 @@ Recommended for shared, skill-first modules.
 
 **Native rules folders** — Rules are written to each tool's own rules folder (`.claude/rules`, `.cursor/rules`, `.github/instructions`, `.windsurf/rules`, ...) with native `paths`/`globs` frontmatter, so path-scoped rules load only when relevant. `split` is the default since 4.22.0; set `[rules] mode = "inline"` to keep rules in the root files. See [docs/rules.md](docs/rules.md).
 
-**Local overrides** — Personal, machine-local instructions that never get committed:
+**Local configuration** — Personal, machine-local content and settings that never get committed:
 
 ```bash
-ai-rulez add rule my-scratch-notes --local   # → .ai-rulez/local/rules/, generates CLAUDE.local.md
+ai-rulez add rule my-scratch-notes --local   # → .ai-rulez/local/rules/, generates .claude/rules/my-scratch-notes.local.md
+ai-rulez local set presets '["codex", "!cursor"]'   # → .ai-rulez/config.local.toml overlay
 ```
 
-`.ai-rulez/local/` and the generated `*.local.md` outputs are gitignored unconditionally. See
-[docs/local-overrides.md](docs/local-overrides.md).
+`.ai-rulez/local/`, the `config.local.*` overlay and the generated `*.local.*` outputs are gitignored
+unconditionally, and `generate` refuses to let local config change tracked shared files (use
+`--no-local` for the teammate view). See [docs/local-overrides.md](docs/local-overrides.md).
 
 **Reasoning effort across providers** — Tune how hard each AI tool thinks:
 
@@ -325,7 +330,7 @@ Add to `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/Goldziher/ai-rulez
-    rev: v4.22.2
+    rev: v4.23.0
     hooks:
       - id: ai-rulez-recursive # generate outputs across the repo
       - id: ai-rulez-validate # dry-run validation
@@ -346,7 +351,7 @@ repository needs. This requires AI-Rulez 4.9.0+ and Poly 0.14.0+:
 [[hooks.sources]]
 id = "ai-rulez"
 git = "https://github.com/Goldziher/ai-rulez.git"
-revision = "v4.22.2"
+revision = "v4.23.0"
 hooks = ["ai-rulez-recursive", "ai-rulez-plugin-verify"]
 ```
 
@@ -377,9 +382,15 @@ pre-commit:
   commands:
     ai-rulez:
       glob: ".ai-rulez/**"
-      run: ai-rulez generate --recursive
+      run: ai-rulez generate --recursive --no-local
 ```
 
+Hooks run on each developer's machine and would otherwise load that developer's gitignored
+`config.local.*` overlay and `.ai-rulez/local/` content. Pass `--no-local` (also accepted by `validate`
+and `tokens`) where a hook should see only the shared configuration, as a teammate or CI does. If you do
+not, `generate` still refuses to write local-derived changes into tracked shared files; never add
+`--allow-local-drift` to a hook. See [Poly hooks guide](docs/poly-hooks.md#machine-local-configuration-in-hooks).
+
 In a monorepo, `ai-rulez generate --recursive` and `ai-rulez validate --recursive` (`-r`) process every nested
 `.ai-rulez/` root, report all failures, and exit non-zero if any root failed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-rulez",
-  "version": "4.22.2",
+  "version": "4.23.0",
   "description": "Complete AI development workflow for 14 AI coding tools. Ships with builtin rules, agents, and conventions. Generate native configs for Claude, Cursor, Copilot, Windsurf, Gemini, Codex and more from a single source.",
   "keywords": [
     "agents",