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

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/
@@ -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 |

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

@@ -0,0 +1,79 @@
+# 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` and `path` record before looking
+at current adapter output. 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/`. If it 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 before removing old root instructions or tool files.
+
+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 as unresolved
+until the user approves the exact `git rm --cached` commands. 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.

package/packages/sync/skills/intelligence-install-adapter/SKILL.md

@@ -22,17 +22,24 @@ rules, agents, and skills.
    agents, skills, and whether it reads `AGENTS.md`. Record links and separate
    verified behavior from assumptions.
 
-3. Run `intelligence adapter create $ARGUMENTS`, then implement
-   `sync_to_$ARGUMENTS()` in the scaffolded project adapter. Follow
+3. Run `intelligence adapter create $ARGUMENTS`, then keep
+   `adapter_contract_$ARGUMENTS()` aligned with every path the adapter writes
+   and implement `sync_to_$ARGUMENTS()` in the scaffolded project adapter. Follow
    `<module>/references/adapters.md` and the closest built-in. Keep writes beneath
-   the configured output, make reruns idempotent, and make owned cleanup paths
-   explicit. Ignore only those owned paths; shared roots remain trackable.
+   the configured output, make reruns idempotent, distinguish exclusive
+   `owned` paths from marker-based/shared `managed` paths, and declare exact
+   legacy, preserved, dependency, ignore, and include records when applicable.
 
 4. Run `bash -n` on the project adapter, then
    `intelligence adapter enable $ARGUMENTS`. If the CLI says the adapter
    requires `agents`, enable that adapter first.
 
+   The CLI derives generated-output ignores from the adapter contract. Do not
+   edit `.gitignore` manually; correct the contract when policy is wrong, and
+   never ignore a shared output root.
+
 5. Require `IS_STATUS=ok`, inspect generated files against the researched
-   format, run the tool's validator when one exists, and finish with
+   format, deliberately fail a later test adapter to prove transactional
+   rollback when contributing a built-in, run the tool's validator when one exists, and finish with
    `intelligence status --check`. Report evidence, output paths, and any
    unsupported artifact type.

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

@@ -1,12 +1,29 @@
 ---
 name: intelligence-learn-from-context
-description: "Capture session lessons and apply to intelligence/ after approval"
-argument-hint: <optional-lesson-statement>
+description: "Capture one approved lesson from a session in an established Intelligence project"
 ---
 
 # Learn from Context
 
-Use after a session where a meaningful preference, working pattern, or recurring friction emerged that should persist into future sessions. Runs in two phases — analyze (read-only) then apply (after user approval).
+Use after repository onboarding is complete and a meaningful preference,
+working pattern, or recurring friction emerged during the current session and
+should persist. It runs analyze (read-only), then apply after approval. This
+skill extends an established project; it does not perform first-run repository
+analysis or migrate legacy instructions.
+
+## Onboarding gate
+
+1. Locate `<manifest>`, `<content-dir>`, and `<module>`, then run
+   `intelligence status --check`.
+2. If setup is missing or inconsistent, stop and ask the user to repair it with
+   `intelligence init`; then use `/intelligence-learn-from-repository`. Do not
+   reproduce CLI mechanics.
+3. If the generated header says onboarding is pending, or preserved legacy
+   evidence still has unresolved instructions, stop and route to
+   `/intelligence-learn-from-repository`. A retained
+   `<content-dir>/_backup/manifest.tsv` or converted legacy config alone does
+   not mean onboarding is incomplete; those may remain as intentionally kept
+   evidence after the transitional header and conflicts are resolved.
 
 ## Principle: positive framing
 
@@ -60,10 +77,12 @@ Present the proposal list to the user. User accepts or rejects per item. Only ac
    - `UPDATE` existing artifact → edit the file directly, applying the proposed change
    - `ARCHIVE` → move to `<content-dir>/_archive/` and update cross-references that point at it
 
-8. **Run `/intelligence-sync`** once all accepted items are applied.
+8. Run `intelligence sync` once all accepted items are applied. Require
+   `IS_STATUS=ok`, then run `intelligence status --check`.
 
 ## Related skills
 
+- `intelligence-learn-from-repository` — first-run onboarding and legacy instruction migration; use it before this skill
 - `intelligence-extract-skill` — when the lesson is a multi-step workflow to be made reusable
 - `intelligence-review-skills` — broader audit across existing intelligence/ artifacts
 - `intelligence-add-rule`, `intelligence-add-skill`, `intelligence-add-agent` — each authors one artifact; Phase B delegates to them

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

@@ -1,55 +1,107 @@
 ---
 name: intelligence-learn-from-repository
-description: "Tailor Intelligence to an initialized repository"
+description: "Recover and complete first-time Intelligence repository onboarding"
 ---
 
 # Learn from Repository
 
-Use after `intelligence init` creates or converts a project. The CLI owns the
-mechanical setup; this skill adds only repository-specific judgement.
+Use once after `intelligence init` creates or converts a project. This is the
+only skill that owns initial backup migration, interrupted-setup recovery, and
+the first repository-specific Intelligence layer. The CLI owns deterministic
+mechanics; this skill supplies repository judgement.
 
-## Analyze
+## Recover or verify setup
 
-1. Run `intelligence status --check`. If setup is missing or incomplete, stop
-   and ask the user to run `intelligence init`; do not reproduce CLI mechanics.
-2. Read `<manifest>` and resolve `<content-dir>` and the configured source
-   directories. Load `<module>/references/conventions.md` and the bundled
+1. Locate `<manifest>`, `<content-dir>`, and `<module>`. If first sync failed
+   before the slash command was installed, these instructions can be opened
+   directly from
+   `.intelligence/packages/@ainova-systems/sync/skills/intelligence-learn-from-repository/SKILL.md`.
+2. Inspect `<content-dir>/_backup/manifest.tsv`. A
+   `state<TAB>initial-onboarding` record identifies the byte-preserved state
+   from before Intelligence first wrote adapter output. Read every `path`
+   record and treat it as migration input, never generated output. A
+   `.intelligence/backup/config.yaml` file identifies a converted legacy
+   Intelligence Sync project; use the converted sources and that config as
+   migration evidence.
+3. Run `intelligence status --check`. If the project is missing, inconsistent,
+   or its first sync failed, run `intelligence init --preview`, show the exact
+   repair plan, and request approval. After approval run
+   `intelligence init --apply`. Do not reproduce manifest, package, adapter,
+   backup, or ignore-file mechanics manually.
+4. Run `intelligence sync`. Sync is transactional: a failure restores every
+   adapter-owned path. Resolve the reported cause and retry. Do not begin
+   semantic migration until `IS_STATUS=ok` and `intelligence status --check`
+   is clean.
+
+## Analyze repository evidence
+
+5. Read `<manifest>` and resolve the configured source directories. Load
+   `<module>/references/conventions.md` and the bundled
    `intelligence-add-rule`, `intelligence-add-skill`, and
-   `intelligence-add-agent` skills before proposing authored content.
-3. Inspect repository evidence: its README and contributor instructions,
-   language and package manifests, build and test entry points, source layout,
-   CI, existing agent instructions, and existing project-owned rules, agents,
-   and skills. Treat documentation as a claim and verify important behavior in
-   code or executable configuration.
-4. Inventory what initialization already preserved or installed. Do not
+   `intelligence-add-agent` skills before proposing authored content. When
+   preserved or legacy instructions exist, also read
+   `<module>/references/onboarding-migration.md` and use its inventory,
+   reverse-mapping, packaging-safety, and stale-reference procedures.
+6. Inspect the README and contributor instructions, language and package
+   manifests, build and test entry points, source layout, CI, existing agent
+   instructions, and project-owned rules, agents, and skills. Detect
+   submodules and treat them as separate repositories unless the user includes
+   them. Treat documentation as a claim and verify important behavior in code
+   or executable configuration.
+7. Inventory what initialization preserved or installed. Compare project-owned
+   rules, agents, and skills with every configured package source. Do not
    recreate package-owned content, duplicate existing instructions, or convert
-   generated target output into source content.
-5. Propose the smallest useful project-owned layer. Prefer updating an existing
-   artifact over creating a sibling. Each proposal must state:
-   - `CREATE`, `UPDATE`, or `KEEP`;
+   generated target output into source content. When a project artifact is
+   materially covered by package content, propose `REMOVE` or a smaller
+   `UPDATE`; require a content comparison, not merely a matching name.
+
+   Treat committed legacy root instructions such as `.cursorrules` and an
+   instruction-bearing `CLAUDE.md` as migration sources, not permanent parallel
+   entry points. Propose moving still-valid guidance into project-owned rules
+   and removing the legacy file after generated output is verified. Keep one
+   only for genuinely local, gitignored configuration an adapter cannot
+   represent. `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
+   still bypass newly added Git ignore rules. Treat missing managed patterns as
+   setup corrections, preserve unrelated entries, and verify actual package or
+   build contents before release.
+8. Propose the smallest useful project-owned layer. Prefer updating an existing
+   artifact over creating a sibling. Each proposal states:
+   - `CREATE`, `UPDATE`, `REMOVE`, or `KEEP`;
    - the source path;
-   - the repository evidence supporting it;
-   - the concise content or responsibility it would add.
+   - repository evidence;
+   - the concise content or responsibility it adds.
 
-Analysis is read-only. Present the proposal and request approval per change.
-It is valid to recommend no new artifacts when the repository already explains
-itself well.
+   When `targets.agents.header` is absent or generic, also propose a concise
+   manifest header with the project name, verified stack summary, and link to
+   its canonical context rule. Keep it to 3-5 lines. Replacing any
+   `onboarding is pending` backup pointer is part of completion.
+
+Analysis is read-only. Present the proposal and request approval per change. It
+is valid to recommend no authored artifacts when the repository already
+explains itself well.
 
 ## Apply after approval
 
-6. Apply only accepted proposals. Delegate new artifacts to
+9. Apply only accepted proposals. Delegate new artifacts to
    `intelligence-add-rule`, `intelligence-add-skill`, or
    `intelligence-add-agent`; update an existing project-owned artifact directly
-   when that is the smaller change. Never edit installed package content or
-   generated tool output.
-7. Run `intelligence sync`, then `intelligence status --check`. Completion
-   requires `IS_STATUS=ok` and a clean consistency check.
-8. Report what was created, updated, or deliberately left unchanged. Remind the
-   user to review and commit generated and source changes according to project
-   policy.
-
-## Related skill
-
-Use `intelligence-learn-from-context` later to preserve a lesson learned during
-a working session. This skill learns the repository's existing structure and
-workflow during onboarding.
+   when smaller, and edit an accepted manifest header directly. Never edit
+   installed package content or generated tool output.
+10. Run `intelligence sync`, then `intelligence status --check`. Inspect the
+    relevant generated `AGENTS.md`, Cursor rules, Claude rules, and any
+    packaging/build file list affected by ignore policy. Only then remove each
+    separately approved legacy root instruction file and rerun the consistency
+    check. 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
+    user to commit source, manifest, lock, `AGENTS.md`, and shared `.github/`
+    changes. Keep or remove the initial backup only by separate user approval.
+
+## Later learning
+
+After onboarding is complete, use `/intelligence-learn-from-context` to capture
+a durable lesson from a working session. It does not repeat repository
+onboarding.

package/packages/sync/skills/intelligence-review-skills/SKILL.md

@@ -82,5 +82,5 @@ The user accepts items individually; bulk-accept for low-impact tweaks is fine.
 
 ## Related skills
 
-- `intelligence-learn-from-context` — single-lesson capture; this skill's apply phase delegates to its Phase B
+- `intelligence-learn-from-context` — single-session lesson capture; this skill delegates accepted edits to its Phase B
 - `intelligence-extract-skill` — when the audit surfaces a workflow that should become a skill

package/packages/sync/skills/intelligence-sync/SKILL.md

@@ -8,7 +8,7 @@ context: fork
 # Sync intelligence
 
 1. Run `intelligence sync` (or `intelligence sync <adapter>` when one adapter
-   was requested). For v2, this command first aligns project schema/content
+   was requested). For Intelligence projects, this command first aligns project schema/content
    with the installed CLI and restores a missing package store strictly from
    `intelligence.lock`.
 2. Require final `IS_STATUS=ok`; relay per-adapter counts and any model-drift