@ainova-systems/intelligence 0.11.0-rc.9 → 0.11.1

package/engine/lib/adapter-contract.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# Declarative adapter ownership contract shared by the engine and CLI.
+#
+# Every adapter exposes adapter_contract_<name> <configured-output>. The
+# function emits tab-separated records through the helpers below. Keeping the
+# declaration beside sync_to_<name>() makes backup, rollback, git policy and
+# lifecycle checks consume the same ownership model as the writer itself.
+
+adapter_contract_version()  { printf 'version\t%s\n' "$1"; }
+adapter_contract_requires() { printf 'requires\t%s\n' "$1"; }
+adapter_contract_owned()    { printf 'owned\t%s\n' "$1"; }
+adapter_contract_managed()  { printf 'managed\t%s\n' "$1"; }
+adapter_contract_legacy()   { printf 'legacy\t%s\n' "$1"; }
+adapter_contract_preserve() { printf 'preserve\t%s\n' "$1"; }
+adapter_contract_ignore()   { printf 'ignore\t%s\n' "$1"; }
+adapter_contract_include()  { printf 'include\t%s\n' "$1"; }
+
+adapter_contract_function() {
+    printf 'adapter_contract_%s' "$1"
+}
+
+# Reject records that could address anything outside the repository. Contract
+# paths are always repo-relative; ignore/include records may contain globs.
+adapter_contract_safe_path() {
+    local path="$1"
+    case "$path" in
+        ""|/*|*\\*|[A-Za-z]:*|..|../*|*/../*|*/..|*$'\t'*|*$'\n'*) return 1 ;;
+        *) return 0 ;;
+    esac
+}
+
+adapter_contract_safe_concrete_path() {
+    adapter_contract_safe_path "$1" || return 1
+    case "$1" in
+        *'*'*|*'?'*|*'['*) return 1 ;;
+        *) return 0 ;;
+    esac
+}
+
+# adapter_contract_records <adapter-name> <adapter-file> <configured-output>
+# Source and query in a subshell so a project adapter cannot leak shell state
+# into the caller. Project adapters are trusted executable code during sync;
+# the isolation here is for correctness, not a security boundary.
+adapter_contract_records() (
+    local name="$1" file="$2" output="$3" fn line kind value saw_version=0
+    # shellcheck source=/dev/null
+    source "$file"
+    fn="$(adapter_contract_function "$name")"
+    declare -F "$fn" >/dev/null 2>&1 || {
+        echo "ERROR: adapter '$name' has no $fn contract" >&2
+        return 1
+    }
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        kind="${line%%$'\t'*}"
+        if [ "$kind" = "$line" ]; then
+            echo "ERROR: adapter '$name' emitted a malformed contract record" >&2
+            return 1
+        fi
+        value="${line#*$'\t'}"
+        case "$kind" in
+            version)
+                [ "$value" = "1" ] || {
+                    echo "ERROR: adapter '$name' uses unsupported contract version '$value'" >&2
+                    return 1
+                }
+                saw_version=1
+                ;;
+            requires)
+                case "$value" in
+                    ""|[!abcdefghijklmnopqrstuvwxyz]*|*[!abcdefghijklmnopqrstuvwxyz0123456789_]*)
+                        echo "ERROR: adapter '$name' declares invalid requirement '$value'" >&2
+                        return 1
+                        ;;
+                esac
+                ;;
+            owned|managed|legacy|preserve)
+                adapter_contract_safe_concrete_path "$value" || {
+                    echo "ERROR: adapter '$name' declares unsafe $kind path '$value'" >&2
+                    return 1
+                }
+                ;;
+            ignore|include)
+                adapter_contract_safe_path "$value" || {
+                    echo "ERROR: adapter '$name' declares unsafe $kind path '$value'" >&2
+                    return 1
+                }
+                ;;
+            *)
+                echo "ERROR: adapter '$name' emitted unknown contract record '$kind'" >&2
+                return 1
+                ;;
+        esac
+        printf '%s\n' "$line"
+    done < <("$fn" "$output")
+    [ "$saw_version" -eq 1 ] || {
+        echo "ERROR: adapter '$name' contract did not declare version 1" >&2
+        return 1
+    }
+)

package/engine/lib/common.sh

@@ -806,6 +806,11 @@ warn_unsynced() {
         case "$rel_dir" in
             .claude/*|.cursor/*|.github/*|.codex/*|.agents/*|.intelligence/*|*/node_modules/*|*/vendor/*|*/dist/*) continue ;;
         esac
+        # Initial onboarding backups are immutable migration evidence, never
+        # source directories. Suggesting one would reintroduce legacy content.
+        case "/$rel_dir/" in
+            *"/$intel_basename/_backup/"*) continue ;;
+        esac
 
         # Skip ignore/submodule patterns.
         local skip=false

package/engine/lib/contract.sh

@@ -9,8 +9,8 @@
 #   * the IS_STATUS / IS_RC_* codes every engine flow reports.
 #
 # Schema migrations themselves are NOT here: the CLI owns them behind
-# `intelligence init`, and a v1 project is brought forward by the archived v1
-# engine before `intelligence init` converts it.
+# `intelligence init`, and a legacy Intelligence Sync project is brought forward
+# by its archived engine before `intelligence init` converts it.
 
 # The applied-schema version is a managed key in the manifest.
 #

package/engine/sync.sh

@@ -19,6 +19,7 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
 source "$SCRIPT_DIR/lib/common.sh"
 source "$SCRIPT_DIR/lib/contract.sh"
+source "$SCRIPT_DIR/lib/adapter-contract.sh"
 
 if [ -z "${CONFIG_FILE:-}" ] || [ ! -f "${CONFIG_FILE:-}" ]; then
     is_status config-missing "CONFIG_FILE=${CONFIG_FILE:-}"
@@ -85,31 +86,6 @@ echo "  Config: $CONFIG_FILE"
 echo "  Root:   $REPO_ROOT"
 echo ""
 
-# Invariant: AGENTS.md is the canonical carrier of always-on rules for
-# Cursor / Copilot / Codex / Pi / opencode (their adapters skip always-on
-# rules to avoid duplication, since each tool reads AGENTS.md natively for
-# baseline project context). If those targets are enabled, `agents` must
-# also be enabled — otherwise always-on rules go nowhere for those tools.
-# Skip the check when the user requested a single target via $TARGET_FILTER:
-# they may be syncing only one IDE intentionally.
-if [ -z "$TARGET_FILTER" ]; then
-    agents_enabled=$(is_target_enabled "$CONFIG_FILE" "agents")
-    if [ "$agents_enabled" != "1" ]; then
-        # AGENTS.md-dependent adapters: any tool whose adapter skips always-on
-        # rule emission (because the tool reads AGENTS.md natively) must be
-        # listed here. Add new adapters to this list when they ship.
-        for tool in cursor copilot codex pi opencode; do
-            if [ "$(is_target_enabled "$CONFIG_FILE" "$tool")" = "1" ]; then
-                echo "ERROR: targets.$tool is enabled but targets.agents is not." >&2
-                echo "  $tool relies on AGENTS.md to deliver always-on rules — without it," >&2
-                echo "  always-on rules would be invisible to $tool." >&2
-                echo "  Either enable targets.agents in $CONFIG_FILE, or disable targets.$tool." >&2
-                exit 1
-            fi
-        done
-    fi
-fi
-
 # Lint frontmatter across all source files (rules, agents, skills).
 # Catches issues like unquoted colons that strict YAML consumers reject.
 for section in rules agents skills; do
@@ -167,6 +143,88 @@ for adapters_dir in "$SCRIPT_DIR/adapters" "$INTELLIGENCE_DIR/adapters"; do
     done
 done
 
+# 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
+# point of view.
+SYNC_TX_DIR="$(mktemp -d -t intelligence-sync-XXXXXX)"
+SYNC_TX_INDEX="$SYNC_TX_DIR/paths.tsv"
+SYNC_TX_SEEN="$SYNC_TX_DIR/seen"
+mkdir -p "$SYNC_TX_DIR/data"
+: > "$SYNC_TX_INDEX"
+: > "$SYNC_TX_SEEN"
+SYNC_TX_ACTIVE=0
+
+snapshot_sync_path() {
+    local adapter_name="$1" rel="$2" src index present=0
+    grep -Fqx -- "$rel" "$SYNC_TX_SEEN" && return 0
+    printf '%s\n' "$rel" >> "$SYNC_TX_SEEN"
+    validate_output_path "$REPO_ROOT" "$CONFIG_FILE" "$adapter_name" "$REPO_ROOT/$rel"
+    index="$(wc -l < "$SYNC_TX_INDEX" | tr -d ' ')"
+    src="$REPO_ROOT/$rel"
+    if [ -e "$src" ] || [ -L "$src" ]; then
+        cp -a "$src" "$SYNC_TX_DIR/data/$index"
+        present=1
+    fi
+    printf '%s\t%s\t%s\n' "$index" "$rel" "$present" >> "$SYNC_TX_INDEX"
+}
+
+restore_sync_snapshot() {
+    local index rel present dst
+    while IFS=$'\t' read -r index rel present; do
+        [ -n "$rel" ] || continue
+        dst="$REPO_ROOT/$rel"
+        rm -rf "$dst"
+        if [ "$present" = "1" ]; then
+            mkdir -p "$(dirname "$dst")"
+            cp -a "$SYNC_TX_DIR/data/$index" "$dst"
+        fi
+    done < "$SYNC_TX_INDEX"
+}
+
+finish_sync_transaction() {
+    local rc=$?
+    trap - EXIT INT TERM
+    set +e
+    if [ "${SYNC_TX_ACTIVE:-0}" = "1" ] && [ "$rc" -ne 0 ]; then
+        restore_sync_snapshot
+        echo "ERROR: sync failed; all adapter-owned paths were restored to their pre-sync state." >&2
+    fi
+    rm -rf "$SYNC_TX_DIR"
+    exit "$rc"
+}
+trap finish_sync_transaction EXIT
+trap 'exit 130' INT TERM
+
+preflight_idx=0
+while [ "$preflight_idx" -lt "${#ADAPTERS[@]}" ]; do
+    adapter="${ADAPTERS[$preflight_idx]}"
+    adapter_file="${ADAPTER_FILES[$preflight_idx]}"
+    preflight_idx=$((preflight_idx + 1))
+    if [ -n "$TARGET_FILTER" ] && [ "$adapter" != "$TARGET_FILTER" ]; then
+        continue
+    fi
+    [ "$(is_target_enabled "$CONFIG_FILE" "$adapter")" = "1" ] || continue
+    output="$(get_target_output "$CONFIG_FILE" "$adapter")"
+    [ -n "$output" ] || output=".$adapter"
+    validate_output_path "$REPO_ROOT" "$CONFIG_FILE" "$adapter" "$REPO_ROOT/$output"
+    records="$(adapter_contract_records "$adapter" "$adapter_file" "$output")" || exit 1
+    while IFS=$'\t' read -r kind value; do
+        [ "$kind" = "requires" ] || continue
+        if [ "$(is_target_enabled "$CONFIG_FILE" "$value")" != "1" ]; then
+            echo "ERROR: targets.$adapter requires enabled target '$value'." >&2
+            echo "       Enable it first: intelligence adapter enable $value" >&2
+            exit 1
+        fi
+    done <<< "$records"
+    while IFS=$'\t' read -r kind value; do
+        case "$kind" in
+            owned|managed) snapshot_sync_path "$adapter" "$value" ;;
+        esac
+    done <<< "$records"
+done
+SYNC_TX_ACTIVE=1
+
 synced=0
 adapter_count=${#ADAPTERS[@]}
 adapter_idx=0
@@ -224,6 +282,10 @@ if [ $synced -eq 0 ]; then
     exit 1
 fi
 
+SYNC_TX_ACTIVE=0
+rm -rf "$SYNC_TX_DIR"
+trap - EXIT INT TERM
+
 # Warn about unsynced directories
 warn_unsynced "$REPO_ROOT" "$CONFIG_FILE"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.11.0-rc.9",
+  "version": "0.11.1",
   "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/agents/intelligence-architect.md

@@ -46,8 +46,8 @@ The per-artifact checks are procedure, so they live in the meta-skills rather th
 | `intelligence-add-rule` / `intelligence-add-agent` / `intelligence-add-skill` | author one artifact |
 | `intelligence-extract-skill` | turn an observed workflow into a skill |
 | `intelligence-review-skills` | audit the layer for duplication, drift, size, hardcoded paths |
-| `intelligence-learn-from-repository` | propose the initial project-owned layer from repository evidence |
-| `intelligence-learn-from-context` | fold a session's lessons back into the layer |
+| `intelligence-learn-from-repository` | recover and complete first-time repository onboarding |
+| `intelligence-learn-from-context` | fold one later session lesson into an established layer |
 | `intelligence-sync` | project the source to every tool channel |
 | `intelligence-update` | interpret and apply the CLI's unified update plan |
 | `intelligence-install-adapter` / `intelligence-uninstall-adapter` | research and manage a tool adapter |

package/packages/sync/references/adapters.md

@@ -42,14 +42,25 @@ To stop syncing a target:
 intelligence adapter disable mytool
 ```
 
-Disabling changes only target state. Generated output is deliberately kept because a generic command cannot know which paths a custom adapter owns. Remove only documented owned paths after reviewing them. A disabled project adapter can be deleted with `intelligence adapter remove mytool`; removal prompts by default, accepts `--apply` for explicit non-interactive use, and also keeps generated output. Built-in adapter source cannot be removed. Use `intelligence adapter list` to inspect source, state and output.
+Disabling changes only target state. Generated output is deliberately kept so disabling is reversible; the adapter contract identifies its paths for review. A disabled project adapter can be deleted with `intelligence adapter remove mytool`; removal prompts by default, accepts `--apply` for explicit non-interactive use, and also keeps generated output. Built-in adapter source cannot be removed. Use `intelligence adapter list` to inspect source, state and output.
 
-## Required function
+## Required interface
 
-The file name and function name form the adapter's identity:
+The file name, contract function and sync function form the adapter's identity:
 
 ```bash
 # <content-dir>/adapters/mytool.sh
+adapter_contract_mytool() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_owned "$output/rules"
+    adapter_contract_owned "$output/agents"
+    adapter_contract_owned "$output/skills"
+    adapter_contract_ignore "$output/rules/"
+    adapter_contract_ignore "$output/agents/"
+    adapter_contract_ignore "$output/skills/"
+}
+
 sync_to_mytool() {
     local repo_root="$1"
     local config_file="$2"
@@ -59,6 +70,30 @@ sync_to_mytool() {
 }
 ```
 
+The contract accepts the configured repo-relative output path and emits only
+records through these helpers:
+
+| Record | Meaning |
+|---|---|
+| `adapter_contract_version 1` | Required interface version |
+| `adapter_contract_requires <name>` | Another target that must be enabled for a full sync |
+| `adapter_contract_owned <path>` | Path exclusively regenerated by this adapter |
+| `adapter_contract_managed <path>` | Shared or marker-managed path modified by this adapter |
+| `adapter_contract_legacy <path>` | Pre-Intelligence input backed up, then quarantined for the first transactional render |
+| `adapter_contract_preserve <path>` | Settings or state preserved in place and included in the initial backup |
+| `adapter_contract_ignore <pattern>` | Exact `.gitignore` pattern managed on enable/init |
+| `adapter_contract_include <pattern>` | Exact negated `.gitignore` pattern managed on enable/init |
+
+All paths are repository-relative. The CLI refuses missing, malformed, unsafe,
+or unsupported contracts before enabling or syncing an adapter. `owned` and
+`managed` paths form the transactional write-set: if any adapter fails, the
+engine restores every selected adapter path to its pre-sync state.
+
+For an existing `.vscodeignore`, `.npmignore`, or `.dockerignore`, enable/init
+also excludes the configured adapter output plus its `owned`, `managed`, and
+`legacy` paths from published or build artifacts. This packaging policy is
+separate from the narrower Git policy expressed by `ignore` and `include`.
+
 The engine calls:
 
 ```text
@@ -162,7 +197,7 @@ Built-ins currently emit Claude and Cursor Markdown, Copilot `.agent.md`, Codex
 
 Content shipped in `@ainova-systems/sync` cannot assume the project's content-directory name or package-store location. It uses these tokens:
 
-| Token | v2 expansion |
+| Token | Expansion |
 |---|---|
 | `<content-dir>` | Project content directory, usually `intelligence` |
 | `<module>` | Installed sync package, usually `.intelligence/packages/@ainova-systems/sync` |
@@ -177,8 +212,8 @@ Call `finalize_output_file` on every text file after transformation. It expands
 
 Adapters regenerate output, so cleanup is part of their public contract.
 
-1. Delete only paths the adapter owns. Preserve sibling settings, commands, extensions, workflows and hand-authored files.
-2. Make ownership obvious in `sync_to_<name>()`; the same list is what a user removes after disabling or uninstalling the adapter.
+1. Delete only paths declared `owned`. Preserve sibling settings, commands, extensions, workflows and hand-authored files.
+2. Keep `adapter_contract_<name>()` exactly aligned with every path `sync_to_<name>()` writes or deletes.
 3. Use marker-based cleanup when generated and hand-authored files share a directory. The OpenCode adapter is the reference implementation.
 4. Use `sync_open_skill_dirs` for `.agents/skills/`; multiple adapters share it.
 5. Write only beneath the supplied `output_dir`, except for an explicitly shared standard path handled by a shared helper.
@@ -211,6 +246,13 @@ sync_mytool_rules() {
     done < <(read_yaml_list "$config_file" "rules")
 }
 
+adapter_contract_mytool() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_owned "$output/rules"
+    adapter_contract_ignore "$output/rules/"
+}
+
 sync_to_mytool() {
     local repo_root="$1" config_file="$2" output_dir="$3"
 
@@ -221,7 +263,7 @@ sync_to_mytool() {
 
 ## Testing
 
-Use a disposable Git repository with a v2 manifest and representative always-on/scoped rules, agents, skills and bundled skill resources.
+Use a disposable Git repository with an Intelligence manifest and representative always-on/scoped rules, agents, skills and bundled skill resources.
 
 ```bash
 intelligence sync mytool
@@ -234,6 +276,8 @@ Verify:
 - skill resources are present;
 - no literal layout tokens remain;
 - hand-authored siblings under the tool root survive;
+- a deliberately failing later adapter restores all earlier output byte-for-byte;
+- `intelligence status --check` accepts the contract and its Git policy;
 - output paths cannot overlap sources or escape the repository;
 - a second sync produces no Git diff.
 

package/packages/sync/references/conventions.md

@@ -18,7 +18,7 @@ Use these tests:
 
 Do not bury conventions in agents, workflows in rules or reusable expertise in skills. Each misplaced concern either fails to load when needed or consumes context when it is not needed.
 
-## v2 project structure
+## Intelligence project structure
 
 ```text
 project/
@@ -57,7 +57,7 @@ project:
   name: payments
   intelligence_dir: "intelligence"  # optional; this is the default
 
-schema_version: "0.11.0"
+schema_version: "0.11.1"
 
 sources:
   rules:
@@ -104,7 +104,7 @@ Commit `intelligence.lock`. It records requested versions, source URLs and paths
 
 Package-owned artifacts cannot assume the project's content-directory name or their installed package path. They use tokens expanded by every adapter through `finalize_output_file`:
 
-| Token | v2 expansion |
+| Token | Expansion |
 |---|---|
 | `<content-dir>` | Repo-relative content directory, usually `intelligence` |
 | `<module>` | Installed sync package, usually `.intelligence/packages/@ainova-systems/sync` |
@@ -283,7 +283,7 @@ Size limits are backstops, not quotas:
 
 Every line enters a finite context budget. Prefer subtraction, consolidation and precise scope over exhaustive prose.
 
-## Generated output
+## Generated output and version control
 
 | Target | Rules | Skills | Agents |
 |---|---|---|---|
@@ -297,22 +297,26 @@ Every line enters a finite context budget. Prefer subtraction, consolidation and
 
 `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.
 
-Generated IDE output may be gitignored when every collaborator can reproduce it with `intelligence sync`. Use narrow ownership patterns so hand-authored tool settings remain trackable:
+By default, commit the manifest, lock, project-owned content, `AGENTS.md`, and shared `.github/` output. Ignore the restorable package store and tool output owned by enabled adapters. `intelligence init` and `intelligence adapter enable` add these patterns without ignoring shared tool roots or settings:
 
 ```gitignore
 # CLI-managed package store
 .intelligence/
 
-# Generated Claude and Cursor content; settings remain trackable
-.claude/rules/
-.claude/agents/
-.claude/skills/
-.cursor/rules/
-.cursor/agents/
-.cursor/skills/
+# Local root instructions migrate into project rules; local preferences stay ignored
+CLAUDE.md
+.cursorrules
+
+# Generated Claude and Cursor content; shared settings remain trackable
+.claude/*
+!.claude/
+!.claude/settings.json
+.cursor/*
+!.cursor/
+!.cursor/settings.json
 
 # Generated open-standard and Codex content
-.agents/
+.agents/skills/
 .codex/agents/
 
 # Generated Pi content
@@ -320,12 +324,47 @@ Generated IDE output may be gitignored when every collaborator can reproduce it
 .pi/extensions/intelligence-sync-rules.ts
 .pi/prompts/intelligence-agent-*.md
 
-# Generated OpenCode agents. Its commands directory may also contain
-# hand-authored files, so choose per-project ignores there.
+# Generated OpenCode agents. Commands share a directory with hand-authored
+# files, so they remain tracked unless the project chooses exact file ignores.
 .opencode/agents/
 ```
 
-Copilot output lives under `.github/`; choose whether to commit it with other repository-level GitHub configuration. Do not ignore `.github/` wholesale.
+Copilot output lives under `.github/` and is committed with other repository-level GitHub configuration. Do not ignore `.github/` wholesale. `AGENTS.md` is also committed so every clone has the shared tool-neutral entry point before sync.
+
+Git tracking and release packaging are separate policies. When a project
+already has `.vscodeignore`, `.npmignore`, or `.dockerignore`, the CLI appends a
+small idempotent block excluding the package store, `intelligence.yaml`,
+`intelligence.lock`, the complete project content directory, and enabled
+adapter output. Existing entries remain untouched and absent secondary ignore
+files are not created.
+
+An ignore rule does not untrack a file already in Git. After init or adapter
+enable, the CLI reports each affected tracked path that remains in the
+worktree with an exact `git rm --cached -- '<path>'` command; this preserves
+the local file while removing it from the index. Legacy root entry points
+quarantined into the initial backup are ordinary worktree deletions to review
+and stage, not candidates for `git rm --cached`.
+
+Before release, inspect the packager's actual file list. An npm `files`
+allowlist can force inclusion despite `.npmignore`, and a Dockerfile-specific
+`<name>.Dockerfile.dockerignore` takes precedence over the root
+`.dockerignore`. Use the relevant pack/list command as the final proof rather
+than inferring contents from Git status.
+
+`AGENTS.md` is the only shared root instruction entry point. During onboarding,
+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.
+
+Before the first render, `intelligence init` preserves existing AI prompt paths
+under `<content-dir>/_backup/`. Its `manifest.tsv` labels the snapshot
+`initial-onboarding`, lists exact original paths, and marks legacy entry points.
+Those legacy paths are quarantined only for the transactional first render; a
+failed render restores them, while a successful render leaves them inactive for
+repository learning. The backup remains until the user approves removal.
 
 ## Project-owned adapters
 
@@ -337,7 +376,7 @@ intelligence adapter create mytool
 intelligence adapter enable mytool
 ```
 
-Project adapters survive CLI upgrades and may override a built-in by name. `intelligence adapter enable mytool` runs a full sync so shared context stays current. `intelligence adapter disable mytool` keeps generated output for explicit, adapter-aware cleanup; a disabled project adapter can then be deleted with `intelligence adapter remove mytool`. See `adapters.md` for the function, ownership and safety contracts.
+Project adapters survive CLI upgrades and may override a built-in by name. Each adapter declares a versioned ownership contract beside its sync function; backup, rollback, dependencies and Git policy all consume it. `intelligence adapter enable mytool` runs a full transactional sync so shared context stays current. `intelligence adapter disable mytool` keeps generated output for explicit cleanup; a disabled project adapter can then be deleted with `intelligence adapter remove mytool`. See `adapters.md` for the interface and safety contract.
 
 ## Schema and command boundaries
 
@@ -345,14 +384,14 @@ The permanent applied-schema key is the top-level scalar `schema_version` in `in
 
 The public lifecycle is deliberately compact:
 
-- `intelligence init [--preview|--apply]` is universal: it creates a new setup, aligns an existing v2 project, or plans/applies conversion of an eligible v1 project.
-- `intelligence sync [adapter]` first aligns an existing v2 project with the installed CLI, restores a missing store strictly from `intelligence.lock`, then renders. In CI it refuses an upgrade that would change tracked files and points to a local `intelligence init --apply` plus review/commit.
+- `intelligence init [--preview|--apply]` is universal: it creates a new setup, aligns an existing Intelligence project, or plans/applies conversion of an eligible legacy Intelligence Sync project.
+- `intelligence sync [adapter] [--compact]` first aligns an existing Intelligence project with the installed CLI, restores a missing store strictly from `intelligence.lock`, then renders. Compact mode shows only final status on success and all diagnostics on failure. In CI it refuses an alignment that would change tracked files and points to a local `intelligence init --apply` plus review/commit.
 - `intelligence update [@scope/name] [--preview|--apply]` is the only update surface. It prints the CLI/project/package plan; default mode prompts, `--preview` never writes, and `--apply` does not prompt. It never moves `ref:` pins.
 - `intelligence package add|remove|list|search` owns package inventory.
 - `intelligence adapter list|create|enable|disable|remove` owns adapter inventory and target state.
 - `intelligence status [--check]` reports state; `--check` runs deep consistency checks.
 
-Implement v2 schema changes as idempotent structural checks. Stage and verify replacement state before deleting or replacing prior state. A stale engine refuses a manifest whose `schema_version` is newer; normal v2 entry points close a behind-project gap through lifecycle preflight.
+Implement Intelligence schema changes as idempotent structural checks. Stage and verify replacement state before deleting or replacing prior state. A stale engine refuses a manifest whose `schema_version` is newer; normal project entry points close a behind-project gap through lifecycle preflight.
 
 Breaking changelog entries use a `### Breaking` checklist of verifiable post-conditions. The update skill reads every release across the version gap, chooses the package/CLI/project command sequence and verifies those conditions after the deterministic command completes.
 
@@ -382,4 +421,4 @@ Callers capture the real code with `command || rc=$?`. Do not use `if ! command;
 | `<content-dir>/{rules,agents,skills,adapters}/` | Project source of truth | Tracked |
 | `.intelligence/` | Restorable package store | Ignored |
 | `AGENTS.md` | Generated canonical project context | Normally tracked |
-| Tool output directories | Generated native content | Project policy; use narrow ignores |
+| Tool output directories | Generated native content | Built-in adapter-owned paths ignored; shared settings tracked |

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

@@ -0,0 +1,87 @@
+# Migrating Existing AI Instructions
+
+Read this reference only when repository onboarding finds pre-existing AI
+instructions, an `<content-dir>/_backup/` created by `intelligence init`, or a
+Git diff showing that the first sync replaced tracked tool output.
+
+## Inventory and recovery
+
+When `<content-dir>/_backup/manifest.tsv` contains
+`state<TAB>initial-onboarding`, it is the authoritative inventory from before
+the first generated write. Read each `target`, `path`, and `legacy` record
+before looking at current adapter output. A `legacy` record means the CLI
+quarantined that active entry point before the first successful render. If
+`path<TAB>AGENTS.md` is present, the backed-up
+file is the original custom project contract; keep following it while deciding
+how to migrate its durable guidance.
+
+Treat these as migration inputs, not as current generated output:
+
+- root `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and
+  `.github/copilot-instructions.md`;
+- Claude and Cursor rules, agents, skills, and commands;
+- Copilot instructions, prompts, agents, and skills;
+- Codex/Open Agent Skills, Pi rules/prompts, and OpenCode agents/commands;
+- scripts or documentation that describe an older sync path.
+
+Prefer the copy under `<content-dir>/_backup/`; do not restore quarantined root
+monoliths as active instructions. If the backup is absent and the first
+sync changed tracked files, inspect their pre-sync content read-only through
+Git (`git diff` and `git show HEAD:<path>`). Never restore old content directly
+into an adapter output directory.
+
+Build one conflict report before proposing changes:
+
+- `MIGRATE`: instruction-bearing files whose useful content needs a
+  project-owned destination;
+- `PRESERVE`: settings and unrelated shared files the adapters do not own;
+- `REPLACE`: adapter-owned paths that sync regenerates;
+- `STALE`: references to removed paths or commands requiring a decision.
+
+Always preserve `.claude/settings.json`, `.claude/settings.local.json`,
+`.cursor/settings.json`, Git metadata, workflows, and non-AI repository files.
+
+## Reverse mappings
+
+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 |
+| `.claude/rules/*.md` | Rule; preserve valid `paths:` |
+| `.cursor/rules/*.mdc` | Rule; rename `globs:` to `paths:` and remove `alwaysApply:` |
+| Claude/Cursor/Copilot agents | Agent; map native model/readonly/tool fields back to `tier:` and `access:` |
+| Claude/Cursor/Copilot skills or commands | Skill when the procedure is repeated, multi-step, stable, and verifiable; otherwise a rule or no artifact |
+| Pi/OpenCode/Codex prompt artifacts | Rule, agent, or skill according to responsibility, after removing tool-specific wrappers |
+
+Verify every retained claim against repository code or executable
+configuration. Do not preserve stale instructions merely because they existed.
+Prefer updating an existing project-owned artifact to creating a sibling.
+
+## Apply and cleanup
+
+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.
+
+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
+replacement directly; ask about narrative or otherwise ambiguous references.
+
+The CLI owns generated-output `.gitignore` entries and its blocks in existing
+`.vscodeignore`, `.npmignore`, and `.dockerignore` files. Verify them against
+the enabled adapters. Treat CLI-reported tracked ignored paths that still exist
+locally as unresolved until the user approves the exact `git rm --cached`
+commands. A quarantined tracked legacy path is already a worktree deletion;
+review and stage that deletion normally instead of using `git rm --cached`. Preserve
+`AGENTS.md`, `.github/`, shared settings, and unrelated files under shared tool
+roots in Git, while excluding development-only Intelligence content from
+published artifacts. Inspect the packager's actual file list before release;
+do not infer package or Docker context contents from Git status.
+
+Keep `<content-dir>/_backup/` until the user separately approves its removal
+after migration and reference checks pass. The backup remains gitignored.