@ainova-systems/intelligence 0.11.0-rc.8 → 0.11.0

package/engine/adapters/pi.sh

@@ -15,6 +15,20 @@
 
 source "$(dirname "${BASH_SOURCE[0]}")/../lib/common.sh"
 
+adapter_contract_pi() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_requires agents
+    adapter_contract_managed ".agents/skills"
+    adapter_contract_owned "$output/intelligence-sync"
+    adapter_contract_managed "$output/extensions"
+    adapter_contract_managed "$output/prompts"
+    adapter_contract_ignore ".agents/skills/"
+    adapter_contract_ignore "$output/intelligence-sync/"
+    adapter_contract_ignore "$output/extensions/intelligence-sync-rules.ts"
+    adapter_contract_ignore "$output/prompts/intelligence-agent-*.md"
+}
+
 pi_ts_escape() {
     local s="$1"
     s="${s//\\/\\\\}"
@@ -193,13 +207,12 @@ sync_pi_agents() {
 
             access_note=""
             if [ "$access" = "readonly" ]; then
-                access_note=$(cat <<'EOF'
-## Access Mode
+                # Bash 3.2 (the macOS system shell) misparses an apostrophe in
+                # a quoted heredoc nested inside command substitution.
+                access_note="## Access Mode
 
 Default to read-only analysis. Do not change files or run mutating commands unless the user explicitly asks you to override this agent's normal restriction.
-
-EOF
-)
+"
             fi
 
             {

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.8",
+  "version": "0.11.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/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 preserved in the initial backup |
+| `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/
@@ -92,11 +92,11 @@ intelligence package add github:acme/backend-intelligence
 intelligence package add 'git+https://git.example.com/acme/backend.git@main#package'
 ```
 
-Registries are an ordered trust list and the only resolver for a package name. There is no built-in catalog and no `@org/name` → GitHub guessing. An explicit `github:` or `git+` spec bypasses registry lookup while remaining recorded and pinned in the manifest and lock.
+Registries are an ordered trust list and the only resolver for a package name. There is no built-in catalog and no `@org/name` → GitHub guessing. An explicit `github:` or `git+` spec bypasses registry lookup. In every case the manifest stores only requested `version` or `ref`; resolved URL/path and SHA live in the lock.
 
 Stable Git tags provide package versions. Semver ranges select the highest matching stable tag; a `ref:` pin names a branch or commit and does not move during `intelligence update`. One package name has one version per project.
 
-Commit `intelligence.lock`. It records requested versions, source URLs and paths, resolved refs and commit SHAs. After cloning, `intelligence sync` restores a missing store strictly from that lock before rendering; manifest/lock or SHA drift is refused.
+Commit `intelligence.lock`. It records requested versions, source URLs and paths, resolved refs and commit SHAs. After cloning, `intelligence sync` restores a missing store strictly from that lock before rendering; manifest/lock or SHA drift is refused. Re-run `package add` when deliberately changing a source.
 
 `@ainova-systems/sync` is ordinary package content exact-pinned to the bundled engine version. `intelligence init` installs it unless `--bare` is used. Lifecycle preflight keeps that pin and `schema_version` aligned with the installed CLI; package-range updates never move it independently.
 
@@ -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,24 @@ 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/settings.json
+.cursor/*
+!.cursor/settings.json
 
 # Generated open-standard and Codex content
-.agents/
+.agents/skills/
 .codex/agents/
 
 # Generated Pi content
@@ -320,12 +322,45 @@ 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 with an exact
+`git rm --cached -- '<path>'` command; this preserves the local file while
+removing it from the index.
+
+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` into project-owned rules, verify the
+generated tool output, then remove the legacy file. Keep a 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 instruction source.
+
+Before the first render, `intelligence init` preserves existing AI prompt paths
+under `<content-dir>/_backup/`. Its `manifest.tsv` labels the snapshot
+`initial-onboarding` and lists exact original paths. The context-learning skill
+first recovers or verifies CLI setup, then routes that state through
+`onboarding-migration.md` and repository learning. The backup remains until the
+user approves removal.
 
 ## Project-owned adapters
 
@@ -337,7 +372,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 +380,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 +417,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 |