@ainova-systems/intelligence 0.20.0 → 0.22.0

package/engine/lib/contract.sh

@@ -100,18 +100,27 @@ is_status() {
     fi
 }
 
+# engine_root_var — set IS_ENGINE_ROOT to the engine directory, one level above
+# this lib. A project adapter that overrides a built-in finds the engine's own
+# files through it, never beside itself.
+engine_root_var() {
+    local lib="${BASH_SOURCE[0]}"
+    case "$lib" in
+        */*) lib="${lib%/*}" ;;
+        *) lib="." ;;
+    esac
+    IS_ENGINE_ROOT="$lib/.."
+}
+
 # Engine version = VERSION one level above this lib (BASH_SOURCE works when
 # sourced). Empty if unreadable — callers treat empty as "no guard".
 # engine_version_var sets IS_ENGINE_VERSION, and IS_ENGINE_VERSION_FOUND=1 when
 # the file exists; it reads the file once per process.
 engine_version_var() {
     [ -z "${IS_ENGINE_VERSION_FOUND:-}" ] || return 0
-    local lib="${BASH_SOURCE[0]}" vf content=""
-    case "$lib" in
-        */*) lib="${lib%/*}" ;;
-        *) lib="." ;;
-    esac
-    vf="$lib/../VERSION"
+    local vf content=""
+    engine_root_var
+    vf="$IS_ENGINE_ROOT/VERSION"
     IS_ENGINE_VERSION=""
     IS_ENGINE_VERSION_FOUND=0
     [ -f "$vf" ] || return 0

package/engine/sync.sh

@@ -115,40 +115,17 @@ done <<< "${IS_YL_UNRESOLVED:-}"
 
 
 # Sources stay read-only for the whole run (validate_output_path refuses an
-# output inside one), so read_source_artifact_files enumerates each section
-# once, in this shell, and its later callers — the agents adapter, the shared
-# skill directory, the context report — replay it. Adapters that list sources
-# with in-shell globs spawn nothing and keep their own, locale-ordered listing.
-# The skills pass also settles every symlink in a skills source and warns once
-# about each it leaves out (decision 0017).
+# output inside one), so the source catalog is built once, in this shell, and
+# every renderer replays it: AGENTS.md, every adapter, the shared skill
+# directory and the context report read sources through source_artifacts_var
+# (decision 0021). Building it names every artifact, settles which of a name
+# renders, refuses ambiguous names before any output is touched, settles every
+# symlink in a skills source (decision 0017), and lints the frontmatter of every
+# source — skills as the inventory renders them: SKILL.md behind a link inside
+# its source is linted, one that leaves its source is never read.
 # shellcheck disable=SC2034  # read by read_source_artifact_files in lib/common.sh
 IS_SOURCE_FILES_MEMO=1
-for section in rules agents skills; do
-    read_source_artifact_files "$REPO_ROOT" "$CONFIG_FILE" "$section"
-done
-
-# Lint frontmatter across all source files (rules, agents, skills).
-# Catches issues like unquoted colons that strict YAML consumers reject.
-# Skills are the rendered ones the pass above settled: SKILL.md behind a link
-# inside its source is linted, one that leaves its source is never read.
-LINT_FILES=()
-LINT_SKILLS=()
-[ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || LINT_SKILLS=("${IS_SOURCE_FILES[@]}")
-for section in rules agents; do
-    load_yaml_list "$CONFIG_FILE" "$section"
-    while IFS= read -r src; do
-        [ -z "$src" ] && continue
-        src_dir="$REPO_ROOT/$src"
-        [ -d "$src_dir" ] || continue
-        for f in "$src_dir"/*.md; do
-            [ -f "$f" ] && LINT_FILES+=("$f")
-        done
-    done <<< "$IS_YAML_LIST"
-done
-[ "${#LINT_SKILLS[@]}" -eq 0 ] || LINT_FILES+=("${LINT_SKILLS[@]}")
-if [ "${#LINT_FILES[@]}" -gt 0 ]; then
-    lint_frontmatter_files "${LINT_FILES[@]}"
-fi
+source_catalog_build "$REPO_ROOT" "$CONFIG_FILE" lint
 
 # Adapters come from two places, discovered by filename (minus `.sh`,
 # `_template` excluded):
@@ -189,6 +166,11 @@ for adapters_dir in "$SCRIPT_DIR/adapters" "$INTELLIGENCE_DIR/adapters"; do
     done
 done
 
+# A `targets:` or `exclude_targets:` id must name an adapter this project has,
+# enabled or not, or the group `committed` (decision 0021). Refused here,
+# before anything is snapshotted or written.
+source_catalog_check_ids "$REPO_ROOT" "${ADAPTERS[*]}" || exit 1
+
 # Validate every selected adapter contract before any output is touched, then
 # snapshot the declared write-set. If a later adapter fails, the EXIT handler
 # restores all earlier adapter outputs so sync is atomic from the repository's
@@ -377,6 +359,20 @@ note_agents_dependent() {
 }
 SELECTED_RECORDS=()
 RENDER_PARALLEL="$SYNC_PARALLEL"
+# What a source may render into depends on Git policy only when the catalog
+# holds a local artifact: then every contract is read with the manifest, which
+# may choose that policy (targets.copilot.commit_output), and its ignore and
+# include records become IS_COMMIT_POLICY. Every other sync reads ownership
+# alone, as decision 0020 keeps it (decision 0021).
+policy_manifest=""
+[ "$IS_CAT_NEED_COMMITTED" != 1 ] || policy_manifest="$CONFIG_FILE"
+IS_COMMIT_POLICY=""
+# The tools that read .agents/skills/ and AGENTS.md, by their contracts: a
+# skill lands in .agents/skills/ when it is for any of them, and a shared path
+# that delivers an artifact to a tool outside its targets is named.
+IS_OPEN_SKILLS_READERS=""
+IS_AGENTS_READERS=""
+IS_ENABLED_ADAPTERS=""
 preflight_idx=0
 while [ "$preflight_idx" -lt "${#ADAPTERS[@]}" ]; do
     adapter="${ADAPTERS[$preflight_idx]}"
@@ -387,13 +383,26 @@ while [ "$preflight_idx" -lt "${#ADAPTERS[@]}" ]; do
     target_output_var "$CONFIG_FILE" "$adapter"
     output="$IS_TGT_OUTPUT"
     [ -n "$output" ] || output=".$adapter"
-    records="$(adapter_contract_records "$adapter" "$adapter_file" "$output")" || exit 1
+    records="$(adapter_contract_records "$adapter" "$adapter_file" "$output" "$policy_manifest")" || exit 1
 
     if ! adapter_claims_add_records "$adapter" "$records"; then
         echo "ERROR: $IS_ADAPTER_CLAIM_CONFLICT." >&2
         echo "       Give each adapter its own output: intelligence adapter list" >&2
         exit 1
     fi
+    IS_ENABLED_ADAPTERS="$IS_ENABLED_ADAPTERS${IS_ENABLED_ADAPTERS:+ }$adapter"
+    while IFS=$'\t' read -r kind value; do
+        case "$kind" in
+            requires) [ "$value" != agents ] || IS_AGENTS_READERS="$IS_AGENTS_READERS${IS_AGENTS_READERS:+ }$adapter" ;;
+            ignore|include) IS_COMMIT_POLICY="$IS_COMMIT_POLICY$adapter"$'\t'"$kind"$'\t'"$value"$'\n' ;;
+            owned|managed)
+                adapter_contract_rel_path "$value"
+                if [ "$IS_ADAPTER_REL_PATH" = ".agents/skills" ]; then
+                    IS_OPEN_SKILLS_READERS="$IS_OPEN_SKILLS_READERS${IS_OPEN_SKILLS_READERS:+ }$adapter"
+                fi
+                ;;
+        esac
+    done <<< "$records"
 
     if [ -n "$TARGET_FILTER" ] && [ "$adapter" != "$TARGET_FILTER" ]; then
         # Not selected: its claims are registered, its output is not touched.
@@ -428,6 +437,13 @@ while [ "$preflight_idx" -lt "${#ADAPTERS[@]}" ]; do
         esac
     done <<< "$records"
 done
+# shellcheck disable=SC2034  # read by output_committed in lib/common.sh
+[ -z "$policy_manifest" ] || IS_COMMIT_POLICY_SET=1
+# A local artifact that names a committed output in its targets is refused
+# before any adapter writes; then every shared path that delivers an artifact
+# beyond its targets, and every target no channel reaches, is named once.
+source_catalog_check_local "$REPO_ROOT" || exit 1
+source_catalog_warn "$REPO_ROOT"
 
 # Every adapter that requires `agents` skips always-on rules because AGENTS.md
 # carries them — and each of those tools reads AGENTS.md at the workspace root

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Build, version and distribute AI agent intelligence across your organization — one CLI, versioned Intelligence Packages, and a sync engine for Claude Code, Cursor, Copilot, Codex, Pi and OpenCode.",
   "bin": {
     "intelligence": "bin/intelligence.js"

package/packages/sync/references/adapters.md

@@ -129,6 +129,17 @@ Code ignore theirs, and never `.github/` itself. `targets.copilot.commit_output:
 true` keeps them tracked for Copilot on github.com; the setting is defined in
 [Generated output and version control](conventions.md#generated-output-and-version-control).
 
+The Claude adapter renders a Claude Code plugin into `<output>/skills/intelligence/`
+when `targets.claude.plugin` is `true` (decision 0022): a mod that checks
+`intelligence sync --check` at session start and every five minutes, shows the
+verdict in a line above the prompt and runs sync from a button there or
+`/intelligence sync`.
+The template is `engine/adapters/claude-plugin/`, copied with the engine version
+stamped into `plugin.json`. It lives inside the owned `skills` path, so it needs
+no contract record of its own. The field's values, the name collision it refuses
+and the plugin's limits are defined in the
+[CLI reference](https://github.com/ainova-systems/intelligence/blob/main/docs/cli.md#intelligence-sync).
+
 The engine calls:
 
 ```text
@@ -141,22 +152,26 @@ The engine has already loaded `engine/lib/common.sh` before it sources the adapt
 
 `sources.rules`, `sources.agents` and `sources.skills` contain repo-relative directory paths. Packages have already been resolved, fetched and pinned by the CLI, so package content appears as an ordinary path under `.intelligence/packages/`. The manifest may name a package's directory by the package's full name or alias instead; `read_yaml_list` and `load_yaml_list` hand an adapter the store path either way, and leave out a reference that names nothing, so an adapter reads every source the same way. Adapters never perform network access or parse `packages:`.
 
-Iterate a source section in manifest order:
+Read a section through the source catalog, never with a glob of your own. `AGENTS.md`, every built-in adapter and the template read it the same way (decision 0021):
 
 ```bash
-while IFS= read -r src; do
-    [ -n "$src" ] || continue
-    dir="$(resolve_source_dir "$repo_root" "$src")"
-    [ -d "$dir" ] || continue
-
-    for file in "$dir"/*.md; do
-        [ -f "$file" ] || continue
-        # transform file
-    done
-done < <(read_yaml_list "$config_file" "rules")
+output_rel_var "$repo_root" "$output_dir"
+source_artifacts_var "$repo_root" "$config_file" rules mytool "$IS_OUTPUT_REL/rules/{}.md"
+for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
+    # IS_SOURCE_FILES[i] is the source, IS_SOURCE_NAMES[i] its rendered name,
+    # IS_SOURCE_SCOPED[i] is 1 for a rule with paths:
+    :
+done
 ```
 
-Later sources intentionally overwrite same-named artifacts from earlier sources. Package sources are wired before project sources, so project content can override a package artifact by name.
+The last argument is the repository-relative path an artifact lands at, `{}` standing for its name. The catalog lists sources in manifest order and each directory's entries in byte order, and settles four things before any adapter runs:
+
+- **Names.** An artifact is named by its file name without a leading `.`, `.md` and a trailing `.local`, a skill by its directory name without the leading `.` and `.local`: `.draft.md` renders as `draft`, `deploy.local/` as `deploy/`. Write each output under `IS_SOURCE_NAMES`, never under the source file name; `finalize_copy_named` and `copy_skill_bundle_dirs_named` take the `IS_SOURCE_NAME_MAP` the call leaves.
+- **Overrides.** Of two artifacts with one name, only the later source's is listed. Package sources are wired before project sources, so project content overrides a package artifact by name. Two of one name in one directory, or a local and a non-local one anywhere, refuse the sync before any adapter runs.
+- **Local artifacts.** A `*.local.md` rule or agent and a `*.local/` skill are listed only for an output path no `ignore` record of your contract covers — what Git tracks never holds one. That is why the path must be the real one: an adapter that globs sources itself, or names a path it does not write, can put a teammate's local file into a committed output.
+- **Targets.** An artifact whose `targets:` leaves your adapter out, or whose `exclude_targets:` names it, is not listed for it; `committed` in either field is resolved against the path you pass ([Selecting adapters](conventions.md#selecting-adapters)). Your adapter's id is a valid target as soon as its file exists, and sync has removed both fields from every copy the shared helpers write; strip them from any frontmatter you copy yourself.
+
+`IS_SOURCE_IN_AGENTS` is 1 when `AGENTS.md` carries the artifact too. An adapter whose tool reads `AGENTS.md` renders an always-on rule only where it is 0: that is a local rule, or one whose targets leave `agents` out, and the tool's own always-on channel is the only way it arrives.
 
 ## Shared functions
 
@@ -164,6 +179,10 @@ Use the engine library instead of copying parsers or file-handling logic.
 
 | Function | Purpose |
 |---|---|
+| `source_artifacts_var(root, config, section, adapters, output)` | The artifacts of a section that render for one of `adapters` at `output` (`{}` is the name): `IS_SOURCE_FILES`, `IS_SOURCE_NAMES`, `IS_SOURCE_SCOPED`, `IS_SOURCE_IN_AGENTS`, `IS_SOURCE_NAME_MAP`. |
+| `output_rel_var(root, output_dir)` | The output's repository-relative path in `IS_OUTPUT_REL`, as `source_artifacts_var` takes it. |
+| `finalize_copy_named(dest, map, src...)` | Copy-and-finalize every source into `dest` under its rendered name, in one process. |
+| `copy_skill_bundle_dirs_named(tool, dest_root, map, src...)` | `copy_skill_bundle_dirs_for` with each skill copied under its rendered name. |
 | `resolve_source_dir(repo_root, source)` | Resolve a manifest source to its local directory. |
 | `read_yaml_list(config, section)` | Stream entries from `sources.<section>`, package references as their store paths. |
 | `load_yaml_list(config, section)` | Same list into `IS_YAML_LIST`, cached — no subprocess on repeat reads. |
@@ -178,7 +197,6 @@ Use the engine library instead of copying parsers or file-handling logic.
 | `copy_skill_bundle(src, dest)` | Copy `SKILL.md` and all resources safely, normalize Markdown, quote free-text frontmatter, and keep a valid `effort:` as written, as the shared skills tree does. |
 | `copy_skill_bundle_dirs(dest_root, src...)` | Batch form: copy every skill directory into `dest_root/<name>` with one copy and one finalize pass. |
 | `copy_skill_bundle_dirs_for(tool, dest_root, src...)` | The batch form for a tree one tool reads: `SKILL.md`'s `effort:` becomes that tool's level, or is removed when it has none. |
-| `skill_source_rendered(skill_dir)` | Whether sync renders a skill directory an adapter listed with its own glob; a skill left out for its symlinks fails it. |
 | `sync_open_skill_dirs(root, config, dest)` | Own and populate a shared Agent Skills directory such as `.agents/skills/`, deriving Codex's `agents/openai.yaml` for a skill with `disable-model-invocation: true`. |
 | `finalize_output_file(file)` | Expand layout tokens and normalize line endings; required for every emitted text file. |
 | `finalize_output_files(file...)` / `finalize_copy_files(dest, src...)` | Batch forms: finalize in place, or copy-and-finalize into a directory, in one process. |
@@ -196,18 +214,20 @@ Prefer the batched forms inside per-file loops: a process spawn costs tens of mi
 
 Rules without `paths:` are always-on. Rules with `paths:` are scoped.
 
-Intelligence routes always-on rules once through `AGENTS.md` for tools that consume it. An adapter for such a tool should not copy those rules again. If the tool has a native scoped-rule channel, transform `paths:` to the tool's equivalent.
+Intelligence routes always-on rules once through `AGENTS.md` for tools that consume it. An adapter for such a tool should not copy those rules again — except one `AGENTS.md` does not carry (`IS_SOURCE_IN_AGENTS` is 0), which reaches the tool only through its own always-on channel. If the tool has a native scoped-rule channel, transform `paths:` to the tool's equivalent.
 
-| Built-in | Always-on rules | Scoped rules |
-|---|---|---|
-| `agents` | Inline in `AGENTS.md` | List with links |
-| `antigravity` | Omit; reads `AGENTS.md` | `.agents/rules/*.md` with `trigger: glob` and `globs:` |
-| `claude` | Copy | Copy with `paths:` preserved |
-| `cursor` | Omit; reads `AGENTS.md` | `.mdc` with `globs:` |
-| `copilot` | Omit; reads `AGENTS.md` | `.instructions.md` with `applyTo:` |
-| `codex` | Omit; reads `AGENTS.md` | No native channel |
-| `pi` | Omit; reads `AGENTS.md` | Generated on-demand files and extension |
-| `opencode` | Omit; reads `AGENTS.md` | No native channel |
+| Built-in | Always-on rules | Always-on, not in `AGENTS.md` | Scoped rules |
+|---|---|---|---|
+| `agents` | Inline in `AGENTS.md` | — | List with links |
+| `antigravity` | Omit; reads `AGENTS.md` | `.agents/rules/*.md` with `trigger: always_on` | `.agents/rules/*.md` with `trigger: glob` and `globs:` |
+| `claude` | Copy | Copy | Copy with `paths:` preserved |
+| `cursor` | Omit; reads `AGENTS.md` | `.mdc` with `alwaysApply: true` | `.mdc` with `globs:` |
+| `copilot` | Omit; reads `AGENTS.md` | `.instructions.md` with `applyTo: "**"` | `.instructions.md` with `applyTo:` |
+| `codex` | Omit; reads `AGENTS.md` | `AGENTS.override.md`: all of `AGENTS.md` plus these rules | No native channel |
+| `pi` | Omit; reads `AGENTS.md` | Added to the system prompt by the generated extension | Generated on-demand files and extension |
+| `opencode` | Omit; reads `AGENTS.md` | No channel; sync warns | No native channel |
+
+Codex reads `AGENTS.override.md` instead of `AGENTS.md` in the same directory, so the Codex adapter writes it — the whole rendered `AGENTS.md`, then the rules only Codex receives — while such a rule exists, and removes it when none does. Its contract manages and ignores the path; a file there that Intelligence did not generate is never touched, and a render that needs the path refuses until it is moved.
 
 If a new adapter relies on `AGENTS.md` for always-on rules, its target must require `agents`. Add that invariant to `engine/sync.sh` when contributing the adapter upstream.
 
@@ -242,7 +262,7 @@ copy_skill_bundle "$source_skill_dir" "$output_dir/skills/$skill_name"
 
 Do not use plain `cp` for skill bundles. `copy_skill_bundle` preserves non-Markdown assets, normalizes Markdown, expands layout tokens and quotes `description` and `argument-hint` where strict YAML readers require strings. It renders `effort:` as the shared tree does; a tree only one tool reads uses `copy_skill_bundle_dirs_for <tool>`, so the copy carries that tool's level or no effort at all. It never writes a symlink; how a link in a skills source renders is defined in [conventions](conventions.md#skill-body-and-resources).
 
-An adapter that lists a skills source with its own glob checks each directory with `skill_source_rendered`. A skill whose directory or `SKILL.md` is a link leaving its source is left out of every output, and sync has already warned about it once.
+`source_artifacts_var ... skills` lists only the skills sync renders: one whose directory or `SKILL.md` is a link leaving its source is left out of every output, and sync has already warned about it once. Copy them with `copy_skill_bundle_dirs_named` and the call's `IS_SOURCE_NAME_MAP`, so `deploy.local/` lands as `deploy/`.
 
 Antigravity, Codex, Pi and OpenCode share `.agents/skills/`. Any adapter writing that open-standard directory must call `sync_open_skill_dirs`; it is the single lifecycle owner for immediate skill subdirectories.
 
@@ -308,21 +328,16 @@ This example copies rules without frontmatter. A real adapter must decide how th
 #!/bin/bash
 
 sync_mytool_rules() {
-    local repo_root="$1" config_file="$2" output_dir="$3"
+    local repo_root="$1" config_file="$2" output_dir="$3" i out
     mkdir -p "$output_dir/rules"
 
-    while IFS= read -r src; do
-        [ -n "$src" ] || continue
-        local dir
-        dir="$(resolve_source_dir "$repo_root" "$src")"
-        [ -d "$dir" ] || continue
-
-        for file in "$dir"/*.md; do
-            [ -f "$file" ] || continue
-            strip_frontmatter "$file" > "$output_dir/rules/$(basename "$file")"
-            finalize_output_file "$output_dir/rules/$(basename "$file")"
-        done
-    done < <(read_yaml_list "$config_file" "rules")
+    output_rel_var "$repo_root" "$output_dir"
+    source_artifacts_var "$repo_root" "$config_file" rules mytool "$IS_OUTPUT_REL/rules/{}.md"
+    for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
+        out="$output_dir/rules/${IS_SOURCE_NAMES[i]}.md"
+        strip_frontmatter "${IS_SOURCE_FILES[i]}" > "$out"
+        finalize_output_file "$out"
+    done
 }
 
 adapter_contract_mytool() {
@@ -352,6 +367,7 @@ Verify:
 
 - native file names, frontmatter and model/permission mappings;
 - scoped and always-on routing without duplicated context;
+- a dotfile or `*.local.md` source renders under its name, and a local one only into outputs the contract ignores;
 - skill resources are present;
 - no literal layout tokens remain;
 - hand-authored siblings under the tool root survive;
@@ -368,9 +384,9 @@ For a built-in adapter, add the same assertions to the repository's smoke or lif
 |---|---|
 | `agents` | `AGENTS.md` |
 | `antigravity` | `.agents/rules`, `.agents/agents`, `.agents/skills` |
-| `claude` | `.claude/rules`, `.claude/agents`, `.claude/skills` |
+| `claude` | `.claude/rules`, `.claude/agents`, `.claude/skills` (with `plugin: true`, `.claude/skills/intelligence` is the Claude Code plugin) |
 | `cursor` | `.cursor/rules`, `.cursor/agents`, `.cursor/skills` |
 | `copilot` | `.github/instructions`, `.github/agents`, `.github/skills` |
-| `codex` | `.codex/agents`, `.agents/skills` |
+| `codex` | `.codex/agents`, `.agents/skills`, marker-owned `AGENTS.override.md` |
 | `pi` | `.pi/intelligence-sync`, `.pi/extensions`, `.pi/prompts`, `.agents/skills` |
 | `opencode` | `.opencode/agents`, marker-owned `.opencode/commands`, `.agents/skills` |

package/packages/sync/references/conventions.md

@@ -73,7 +73,7 @@ sources:
 
 A package's directory may also be named by the package instead of its store path: `@ainova-systems/sync/rules` names folder `rules` of the package `packages:` declares as `@ainova-systems/sync`, and `sync:rules` names it through the alias that package declares (`intelligence package alias @ainova-systems/sync sync`). Both render exactly as the store path, and both are installed package content like it: edit that content in its source repository. The CLI writes store paths and never rewrites a reference a person wrote; an `@scope/name/...` entry for a package `packages:` does not declare is an ordinary project path.
 
-Missing project-owned source directories are skipped, so a package-only project need not create empty `rules/`, `agents/` or `skills/` directories. Source order matters: later files with the same artifact name overwrite earlier ones. Package sources are wired before project sources so the project can override a package artifact deliberately.
+Missing project-owned source directories are skipped, so a package-only project need not create empty `rules/`, `agents/` or `skills/` directories. Source order matters: of two artifacts with one name, the later source's renders everywhere, `AGENTS.md` included, and the earlier one renders nowhere (see [Artifact names](#artifact-names-and-local-artifacts)). Package sources are wired before project sources so the project can override a package artifact deliberately.
 
 Project-owned entries are managed with `intelligence source add|remove|list` rather than by hand — it validates the path against the way the engine resolves it and prints the resulting order. `add` appends by default; `--before <entry>` / `--after <entry>` place content that should behave like a package ahead of the project's own directories.
 
@@ -164,6 +164,41 @@ Common skill verbs:
 
 The verb describes the outcome, not whether the skill implements the work or delegates to another command or skill.
 
+## Artifact names and local artifacts
+
+An artifact's name is its file name without a leading `.`, `.md` and a trailing `.local`; a skill's is its directory name without the leading `.` and the trailing `.local`. `backend.md`, `.backend.md` and `backend.local.md` are all the rule `backend`, `deploy.local/` is the skill `deploy`, and every generated copy carries the name: `.claude/rules/backend.md`, `.cursor/rules/backend.mdc`, `.claude/skills/deploy/`. A leading dot means nothing — a dotfile source renders like any other.
+
+Names stay unique. Across sources the later source's artifact renders and the earlier one does not, in `AGENTS.md` as in every tool's output; a skill a later source overrides is replaced whole, resources included. Sync refuses two artifacts with one name in one source directory (`backend.md` beside `.backend.md`), and a local and a non-local artifact with one name anywhere in the sources: a local file that overrode or yielded to a committed one would change what committed output holds.
+
+A **local** artifact is personal or machine-specific guidance — the OS, the shell, a local service, a personal habit — that only this clone loads: a rule or agent named `*.local.md`, or a skill directory named `*.local/`. `intelligence init` writes the matching patterns, for the project's content directory, into its managed `.gitignore` block, so Git and sync agree on which files are local:
+
+```gitignore
+intelligence/rules/*.local.md
+intelligence/agents/*.local.md
+intelligence/skills/*.local/
+```
+
+Sync renders a local artifact only into outputs Git ignores, and never into one it tracks: not `AGENTS.md`, not OpenCode's slash commands, not Copilot's output under `commit_output: true`. A clone without the file therefore renders the same committed files, and `intelligence sync --check` passes in CI. A local always-on rule reaches each tool through that tool's own always-on channel (see [Routing](#routing)), since `AGENTS.md` cannot carry it; OpenCode has none, and sync says so. `intelligence status --check` reports a missing pattern, and `intelligence init` restores it.
+
+A pattern never applies to a file Git already tracks, and a source outside the content directory has no pattern at all. `intelligence status --check` therefore names every file with a local name that Git tracks in a project-owned source: rename it to share it, or `git rm --cached` it to keep it on this machine.
+
+## Selecting adapters
+
+Every rule, agent and skill renders to every enabled adapter. Two frontmatter fields narrow that, for guidance that matters to one tool or should cost no other tool context:
+
+```yaml
+---
+targets: [claude, cursor]      # only these adapters; without it, every enabled one
+exclude_targets: [committed]   # remove these from that set
+---
+```
+
+Both take adapter ids — built-in or the project's own — and the group `committed`: every output path Git tracks, resolved per path from each adapter's contract. `AGENTS.md` always belongs to it, and so do OpenCode's slash commands and, under `commit_output: true`, Copilot's output; OpenCode's agents and the shared `.agents/skills/` do not. Write them in the list syntax `paths:` takes — a flow list `[a, b]` or a block list — and in `SKILL.md` for a skill. `targets: []` renders the artifact nowhere. Sync removes both fields from every generated copy.
+
+An id that names no adapter refuses the sync. An adapter that is not enabled is simply no target: enablement stays the manifest's decision. A local artifact excludes `committed` already, and one whose `targets` names a committed output — `agents`, `committed`, or an adapter all of whose output Git tracks — refuses the sync, because every other clone and CI render that output without it.
+
+Two paths are shared, not per tool, and a filter can withhold an artifact from a shared path but never from one of its readers. An artifact whose set contains `agents` goes into `AGENTS.md` and reaches every tool that reads it. A skill whose set contains any reader of `.agents/skills/` — Antigravity, Codex, Pi, OpenCode — lands there for all of them. Sync prints a `WARNING:` line when a shared path delivers an artifact to an enabled adapter outside its set, and when an adapter in its set can receive it through no channel. An artifact with neither field nor a `.local` name keeps the routing, and the warnings, it always had.
+
 ## Agent conventions
 
 ```yaml
@@ -246,9 +281,12 @@ Rule content in Markdown.
 |---|---|---|---|---|---|
 | Scoped | copied with `paths:` | `.mdc` with `globs:` | `.md` with `trigger: glob` and `globs:` | `.instructions.md` with `applyTo:` | listed in `AGENTS.md`; Pi also gets on-demand files and an extension |
 | Always-on | copied | omitted | omitted | omitted | inlined once into `AGENTS.md` |
+| Always-on, not in `AGENTS.md` | copied | `.mdc` with `alwaysApply: true` | `.md` with `trigger: always_on` | `.instructions.md` with `applyTo: "**"` | Codex: `AGENTS.override.md`; Pi: added to the system prompt by its extension; OpenCode: none |
 
 Cursor, Copilot, Codex, Pi, OpenCode and Antigravity consume `AGENTS.md`, so always-on rules are not duplicated in their tool-specific channels. Claude does not consume `AGENTS.md`, so it receives the full rule set. OpenCode and Codex have no generated path-scoped rule channel; OpenCode users may configure `instructions:` globs themselves.
 
+An always-on rule `AGENTS.md` does not carry — a local one, or one whose set leaves `agents` out (see [Selecting adapters](#selecting-adapters)) — reaches each tool in its set through that tool's own channel instead, the last row. Codex reads `AGENTS.override.md` instead of `AGENTS.md` in the same directory, so the file holds the whole `AGENTS.md` plus the rules only Codex receives; it is ignored, exists only while such a rule does, and one Intelligence did not generate is never touched. Antigravity's `trigger: always_on` belongs to the same undocumented key family as its `trigger: glob`. OpenCode reads instructions only from `AGENTS.md` or its committed `opencode.json`, so it can receive neither a local nor a tool-targeted always-on rule.
+
 Keep always-on rules small. Put narrow framework or component guidance behind `paths:` so unrelated tasks do not pay its context cost.
 
 ## Skill conventions
@@ -270,7 +308,7 @@ argument-hint: "<route-name>"
 4. Report the changed route and verification.
 ```
 
-Standard optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and tool extensions pass through unchanged. A tool ignores fields it does not understand. `effort:` is the exception: sync renders it per tool, as [Effort mappings](#effort-mappings) describes.
+Standard optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and tool extensions pass through unchanged. A tool ignores fields it does not understand. `effort:` is the exception: sync renders it per tool, as [Effort mappings](#effort-mappings) describes. `targets:` and `exclude_targets:` select the adapters that receive the skill and are removed from every copy ([Selecting adapters](#selecting-adapters)).
 
 `disable-model-invocation: true` makes a skill one only the owner starts, as a slash command: use it for a procedure that changes versions, the lock or generated outputs, where an agent selecting it unasked is the failure. Claude Code, Cursor and Copilot read the field itself; Codex does not, so sync writes `agents/openai.yaml` with `allow_implicit_invocation: false` beside the skill in `.agents/skills/`. Keep the source to the field. A skill that ships its own `agents/openai.yaml` keeps everything else in it: sync adds the policy when the file sets none, and refuses one that sets it otherwise or not as a plain `allow_implicit_invocation: false` directly under `policy:`.
 
@@ -338,12 +376,12 @@ Every line enters a finite context budget. Prefer subtraction, consolidation and
 | Target | Rules | Skills | Agents |
 |---|---|---|---|
 | `agents` | Always-on inlined; scoped listed in `AGENTS.md` | Listed | Listed |
-| Antigravity | `AGENTS.md` plus scoped `.agents/rules/*.md` | `.agents/skills/` | `.agents/agents/*.md` |
+| Antigravity | `AGENTS.md` plus `.agents/rules/*.md` | `.agents/skills/` | `.agents/agents/*.md` |
 | Claude | `.claude/rules/` | `.claude/skills/` | `.claude/agents/` |
-| Cursor | scoped `.cursor/rules/*.mdc` | `.cursor/skills/` | `.cursor/agents/` |
-| Copilot | scoped `.github/instructions/*.instructions.md` | `.github/skills/` | `.github/agents/` |
-| Codex | `AGENTS.md` only | `.agents/skills/` | `.codex/agents/*.toml` |
-| Pi | `AGENTS.md` plus scoped `.pi/intelligence-sync/rules/` | `.agents/skills/` | `.pi/prompts/intelligence-agent-*.md` |
+| Cursor | `AGENTS.md` plus `.cursor/rules/*.mdc` | `.cursor/skills/` | `.cursor/agents/` |
+| Copilot | `AGENTS.md` plus `.github/instructions/*.instructions.md` | `.github/skills/` | `.github/agents/` |
+| Codex | `AGENTS.md`, or `AGENTS.override.md` while a rule needs it | `.agents/skills/` | `.codex/agents/*.toml` |
+| Pi | `AGENTS.md` plus scoped `.pi/intelligence-sync/rules/` and its extension | `.agents/skills/` | `.pi/prompts/intelligence-agent-*.md` |
 | OpenCode | `AGENTS.md` only | `.agents/skills/` plus slash commands | `.opencode/agents/*.md` |
 
 `AGENTS.md` is regenerated by the `agents` adapter. Its optional static header is `targets.agents.header` in `intelligence.yaml`; generated rule, agent and skill sections follow it. Commit `AGENTS.md` when it is the project's shared canonical context.
@@ -354,7 +392,12 @@ By default, commit the manifest, lock, project-owned content and `AGENTS.md`. Ig
 # CLI-managed package store
 .intelligence/
 
-# Local root instructions migrate into project rules; local preferences stay ignored
+# Local rules, agents and skills of the content directory stay on this machine
+intelligence/rules/*.local.md
+intelligence/agents/*.local.md
+intelligence/skills/*.local/
+
+# Root tool instructions migrate into project rules and stay ignored
 CLAUDE.md
 .cursorrules
 GEMINI.md
@@ -374,6 +417,7 @@ GEMINI.md
 .agents/rules/
 .agents/agents/
 .codex/agents/
+AGENTS.override.md
 
 # Generated Pi content
 .pi/intelligence-sync/
@@ -430,9 +474,10 @@ than inferring contents from Git status.
 move useful repository guidance from legacy root files such as `.cursorrules`
 and instruction-bearing `CLAUDE.md` out of their quarantined backup copies and
 into project-owned rules, then verify the generated tool output. Do not restore
-the original root monolith. Create a new root tool-specific file only when it
-contains genuinely local configuration that an adapter cannot represent; keep
-that exception gitignored rather than maintaining a second committed source.
+the original root monolith. Genuinely machine-local guidance becomes a local
+rule, agent or skill (see
+[Artifact names and local artifacts](#artifact-names-and-local-artifacts)), not
+a new root tool-specific file.
 
 Before the first render, `intelligence init` preserves existing AI prompt paths
 under `<content-dir>/_backup/`. Its `manifest.tsv` labels the snapshot
@@ -496,6 +541,7 @@ Callers capture the real code with `command || rc=$?`. Do not use `if ! command;
 | `intelligence.yaml` | Manifest and schema contract | Tracked |
 | `intelligence.lock` | Resolved package state | Tracked |
 | `<content-dir>/{rules,agents,skills,adapters}/` | Project source of truth | Tracked |
+| `<content-dir>/{rules,agents}/*.local.md`, `<content-dir>/skills/*.local/` | Local artifacts, this clone only | Ignored |
 | `.intelligence/` | Restorable package store | Ignored |
 | `AGENTS.md` | Generated canonical project context | Normally tracked |
 | Tool output directories | Generated native content | Built-in adapter-owned paths ignored; shared settings tracked |

package/packages/sync/references/onboarding-migration.md

@@ -47,7 +47,7 @@ Migrate meaning, not tool syntax:
 
 | Existing format | Project-owned destination |
 |---|---|
-| Root `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Copilot root instructions | Split verified guidance by topic into rules; keep local machine preferences in a gitignored root file only when no adapter representation exists |
+| Root `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Copilot root instructions | Split verified guidance by topic into rules; move machine-local preferences into local rules (`<content-dir>/rules/<name>.local.md`), which Git ignores and sync keeps out of committed output |
 | `.claude/rules/*.md` | Rule; preserve valid `paths:` |
 | `.cursor/rules/*.mdc` | Rule; rename `globs:` to `paths:` and remove `alwaysApply:` |
 | Claude/Cursor/Copilot agents, Codex `.codex/agents/*.toml` | Agent; map native model/readonly/tool fields back to `tier:` and `access:`, and a native effort level (`effort:`, `model_reasoning_effort`) back to `effort:` |
@@ -64,9 +64,9 @@ Obtain approval per `CREATE`, `UPDATE`, `REMOVE`, or `KEEP` proposal. Apply
 project-owned source changes first, then run `intelligence sync` and
 `intelligence status --check`. Inspect the enabled targets to prove the
 migrated guidance arrived and verify quarantined old root instructions remain
-absent. Create a new root tool file only from a separately approved, genuinely
-machine-local subset that has no adapter representation; never restore the
-original instruction monolith.
+absent. A separately approved, genuinely machine-local subset becomes a local
+rule, `<content-dir>/rules/<name>.local.md`, not a new root tool file; never
+restore the original instruction monolith.
 
 For every removed or renamed path, search all tracked files with `git ls-files`
 and report remaining references with file and line number. Apply an unambiguous

package/packages/sync/rules/intelligence-authoring.md

@@ -48,13 +48,13 @@ The mistakes that actually happen, in order of frequency:
 
 ## Rules
 
-**Scope with `paths:`.** A rule without `paths:` is loaded into *every* session and inlined into `AGENTS.md` — the most expensive context real estate there is. Earn it. A rule that only matters when someone touches the frontend belongs scoped to the frontend.
+**Scope with `paths:`.** A rule without `paths:` is loaded into *every* session and inlined into `AGENTS.md` — the most expensive context real estate there is. Earn it. A rule that only matters when someone touches the frontend belongs scoped to the frontend. Guidance about one tool belongs to that tool: `targets: [claude]` keeps it out of every other tool's context. A rule whose targets leave `agents` out also leaves `AGENTS.md`, and sync names any tool that can then no longer receive it.
 
 **Lead with the positive default, then the invariant.** The model acts on the first instruction it reads, and it follows whatever is named — negation ("never do X") draws attention to X. Reserve absolute language (NEVER, MUST) for true must-nots: safety, security, output format. A judgement call written as a NEVER only teaches the model that NEVERs are negotiable.
 
 **Derive from the code, not from prose that already exists.** Every REQUIRED and every invariant must be backed by something observed in the repository. Documentation is a claim, not evidence — read the file.
 
-**Describe the repository, not a machine.** The OS, the shell, the editor, a local dev stack, personal tooling — these are environment facts. They belong in a personal, gitignored `CLAUDE.md`. A rule is committed and read by everyone, so a shell-specific command or an absolute local path in it is simply wrong for whoever is on another platform.
+**Describe the repository, not a machine.** The OS, the shell, the editor, a local dev stack, personal tooling — these are environment facts. They belong in a local rule, `<content-dir>/rules/<name>.local.md`: Git ignores it, and sync renders it only into outputs Git ignores. A rule is committed and read by everyone, so a shell-specific command or an absolute local path in it is simply wrong for whoever is on another platform.
 
 **Explain the why — but only a why you can back.** A reason the reader can check is what makes an instruction survive a judgement call. An invented reason is worse than none: it sounds like evidence.
 

package/packages/sync/skills/intelligence-learn-from-repository/SKILL.md

@@ -59,9 +59,10 @@ mechanics; this skill supplies repository judgement.
    Treat backed-up legacy root instructions such as `.cursorrules` and an
    instruction-bearing `CLAUDE.md` as migration sources, not permanent parallel
    entry points. Move still-valid shared guidance into project-owned rules; do
-   not restore the original monolith. Only when approved machine-local guidance
-   remains, create a small new gitignored `CLAUDE.md` from that subset after
-   migration. `AGENTS.md` remains the shared root instruction entry point.
+   not restore the original monolith. Approved machine-local guidance becomes a
+   local rule, `<content-dir>/rules/<name>.local.md`, which Git ignores and sync
+   keeps out of committed output. `AGENTS.md` remains the shared root
+   instruction entry point.
 
    Review `.gitignore` and every existing `.vscodeignore`, `.npmignore`, and
    `.dockerignore` against the CLI-managed policy. Detect tracked files which
@@ -95,8 +96,9 @@ explains itself well.
     relevant generated `AGENTS.md`, Cursor rules, Claude rules, and any
     packaging/build file list affected by ignore policy. Verify quarantined
     legacy root entry points remain absent. If the user approved a genuinely
-    machine-local exception, create a concise new gitignored root file from only
-    that content; never copy the backed-up monolith back. Completion requires
+    machine-local exception, write only that content to a local rule
+    (`<content-dir>/rules/<name>.local.md`); never copy the backed-up monolith
+    back. Completion requires
     `IS_STATUS=ok`, a clean final check, and no `onboarding is pending` header
     after accepted migration.
 11. Report what was created, updated, removed, or deliberately kept. Remind the

package/packages/sync/skills/intelligence-review-context/references/audit-checks.md

@@ -9,7 +9,7 @@ Apply these checks to the source groups resolved by the review skill.
 | **Over the cap** | `SKILL.md` over 1000 lines, rule over 500, agent over 200 | `SPLIT` — two artifacts, or move detail into `references/<topic>.md` |
 | **Shared instruction budget** | The measured shared agents output, or `agents-md` in sync's `CONTEXT:` summary, is over 32 KiB (32,768 bytes) | `COMPACT` — this is Intelligence's recommended maximum, not an adapter rejection threshold; use the compaction procedure in `intelligence-review-context` to reduce the owning sources without teaching terse output |
 | **Rule links to a rule** | A markdown link from one rule to another (`R1`) | `UNLINK` — name the rule instead: always-on rules are inlined into `AGENTS.md` and the scoped channels carry only scoped rules, so the link is dead in at least one output |
-| **Machine facts in a rule** | OS, shell, editor or a local absolute path (`R2`) | `MOVE` — these belong in a personal, gitignored `CLAUDE.md`; a rule is committed and read by everyone, including whoever is on another platform |
+| **Machine facts in a rule** | OS, shell, editor or a local absolute path (`R2`) | `MOVE` — these belong in a local rule, `<content-dir>/rules/<name>.local.md`, which Git ignores and sync keeps out of committed output; a rule is committed and read by everyone, including whoever is on another platform |
 | **Literal path or command in a skill** | A path *outside the skill's own folder* baked into a procedure (`R3`) | `PARAMETERIZE` — a skill is *executed*, so a literal path breaks the moment the layout moves; resolve it from a rule or from `<manifest>`. **Exempt:** the skill's own bundle (`references/`, `scripts/`, `assets/` — content is co-located with its skill by default); rules and agents (describing the repository is their job); an example inside an output-format block; the resolution step itself |
 | **Skill with no verification** | Nothing at the end proves the procedure worked (`R4`) | `FLAG` — a procedure that proves nothing is a note, or just the work: give it a verification, or delete it |
 | **Pressure marker** | A heading or section named CRITICAL / MANDATORY / HARD RULE / READ FIRST, or a density of `MUST` / `NEVER` / `ALWAYS` with no reason beside it (`R5`) | `REWRITE` - plain heading, one reason per constraint; when several instructions are each marked critical the marker stops carrying information, so keep emphasis for the one instruction demonstrably under-weighted without it |

package/packages/sync/skills/intelligence-update-context/references/rules.md

@@ -13,6 +13,11 @@
    Architecture, Build and test, Examples, and Patterns to recognize and replace.
    Keep reasons that guide judgment and reference real examples. An accepted
    user preference is identified as a preference, not a claim about existing code.
+5. Guidance that belongs to one machine or one person — the OS, the shell, a
+   local service, a personal habit — goes in a local rule,
+   `<content-dir>/rules/<name>.local.md`. Git ignores it, and sync renders it
+   only into outputs Git ignores, so it never reaches `AGENTS.md` or a teammate.
+   A local rule cannot share a name with a committed one.
 
 For a scoped rule: