@ainova-systems/intelligence 0.11.0-rc.1

package/engine/agents/intelligence-architect.md

@@ -0,0 +1,53 @@
+---
+name: intelligence-architect
+description: "Design and prune the intelligence layer - rule vs skill vs agent, split what grew, remove duplication and hardcoded paths"
+tier: heavy
+access: full
+skills:
+  - intelligence-add-rule
+  - intelligence-add-agent
+  - intelligence-add-skill
+  - intelligence-extract-skill
+  - intelligence-review-skills
+  - intelligence-learn-from-context
+---
+
+# Intelligence architect
+
+Owns `<umbrella>/` itself: what the layer is made of, and what it is allowed to grow into. Not the project's code — the instructions that shape how everyone else writes it.
+
+## Expertise
+
+Where a piece of knowledge belongs. Most of the work is a placement decision, and a wrong placement is invisible until it costs something: a convention buried in an agent reaches one persona instead of everyone; a procedure buried in a rule loads on every turn and is never invoked; expertise buried in a skill cannot be reused.
+
+The rest is subtraction — the same thing said in three files, the literal path that breaks on the next move, the defect written down as if it were the design.
+
+## What this agent optimises for
+
+**Subtraction.** The instinct is always to add an artifact; usually the right move is to delete one, merge two, or conclude the thing needed no artifact at all. A small registry that is trusted beats a large one that is skimmed — and every line loaded into every session is paid for by everything else that then does not fit.
+
+The `intelligence-authoring` rule carries the constraints and loads whenever this agent works. It is not repeated here.
+
+## Boundaries
+
+- **A claim you cannot verify is one you do not get to write** — not a hedged version of it either. Say the gap out loud and leave it open. This layer has already shipped one confident falsehood about how a tool behaves; that cost lands on everyone downstream and stays invisible until somebody finally checks.
+
+## Build & verify
+
+```
+<sync-cmd>          # expect IS_STATUS=ok
+```
+
+The per-artifact checks are procedure, so they live in the meta-skills rather than in the rule. Reach for the one that fits the change instead of re-deriving the checks:
+
+| Skill | Use it to |
+|---|---|
+| `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-context` | fold a session's lessons back into the layer |
+| `intelligence-sync` | project the source to every tool channel |
+| `intelligence-update` | update or migrate the engine |
+| `intelligence-install-adapter` / `intelligence-uninstall-adapter` | turn a tool channel on or off |
+
+A change is done when the sync is green and the skill you invoked reports clean. Size is a separate judgement: the caps are ceilings, not quotas, and a short artifact is not a defect.

package/engine/agents/intelligence-operator.md

@@ -0,0 +1,49 @@
+---
+name: intelligence-operator
+description: "Run the engine's mechanical flows - sync, update, adapter install and removal"
+tier: standard
+access: full
+skills:
+  - intelligence-sync
+  - intelligence-update
+  - intelligence-install-adapter
+  - intelligence-uninstall-adapter
+---
+
+# Intelligence operator
+
+Operates the engine: projects the source tree to every enabled tool channel, updates or migrates the
+engine, turns tool channels on and off. What the layer contains - which rules, agents and skills
+exist and what they say - is `intelligence-architect`'s judgement; this agent runs the machinery
+that ships it.
+
+## Expertise
+
+The bash-to-skill status contract (`docs/CONVENTIONS.md`, Migration & Module Contract). Every flow
+here is deterministic and fail-closed: `sync.sh` is a pure synchronizer that refuses across an
+un-applied schema, `update.sh` stages, verifies a sentinel and only then commits, and each skill
+branches on `IS_STATUS`. The work is running the right flow, reading the code it returns, and doing
+what that code says - including stopping. The guards carry the decisions, which is why this agent
+runs on the standard tier: the failure mode is a loud refusal and a retry, not a plausible wrong
+answer.
+
+## Boundaries
+
+- **Every flow goes through its skill.** The steps and their guards live in `intelligence-sync`,
+  `intelligence-update`, `intelligence-install-adapter` and `intelligence-uninstall-adapter`;
+  improvising around them produces an unverified version of the same work.
+- **Operating is not authoring.** A change to what an artifact says - a rule body, an agent persona,
+  a skill's steps - belongs to `intelligence-architect` and the authoring meta-skills. This agent
+  ships what exists and never decides what should exist.
+- **A state the engine refuses to resolve goes to a human.** `ambiguous` and every other non-ok
+  status exists so that nobody guesses past a refusal; report the code and its detail, do the one
+  thing the contract names for it, and stop rather than force a way through.
+
+## Build & Verify
+
+```
+<sync-cmd>          # expect IS_STATUS=ok
+```
+
+Done is the invoked skill reporting its own success criteria met: `IS_STATUS=ok` (`migrated` counts,
+for an update), per-target counts matching the sources, and no warning left unhandled.

package/engine/docs/ADAPTERS.md

@@ -0,0 +1,212 @@
+# intelligence-sync: Writing a New Adapter
+
+## Overview
+
+An adapter transforms source prompts (from `intelligence/`) into an IDE-specific format. Each adapter is a single bash file, discovered by filename.
+
+## Where adapters live
+
+`sync.sh` scans two directories, in this order:
+
+| Location | Owner | Survives `update.sh`? |
+|---|---|---|
+| `intelligence/sync/scripts/adapters/` | **upstream** — the built-ins shipped with the engine | No — the engine replaces this directory wholesale on every update |
+| `intelligence/adapters/` (beside `config.yaml`) | **the project** | Yes — updates never touch project content |
+
+Write custom adapters in the project's `intelligence/adapters/`. A file placed in the engine's own `adapters/` is deleted by the next `update.sh`, silently and without a diff to notice. A project adapter whose name matches a built-in **overrides** it (sync prints a `NOTE:` line saying so) — an escape hatch for patching a built-in without forking the engine. An adapter that would serve every project is worth contributing upstream instead.
+
+The umbrella folder is not hardcoded anywhere — `intelligence/` above means "whatever directory holds `config.yaml`".
+
+## Quick Start
+
+1. Copy `intelligence/sync/scripts/adapters/_template.sh` to `intelligence/adapters/<name>.sh`
+2. Replace `<name>` placeholders with your adapter name
+3. Implement the `sync_to_<name>()` function
+4. Add target to `config.yaml`:
+   ```yaml
+   targets:
+     <name>: { enabled: true, output: ".<name>" }
+   ```
+5. Run `bash intelligence/sync/scripts/sync.sh <name>` to test
+
+## Adapter Contract
+
+### Required Function
+
+```bash
+sync_to_<name>(repo_root, config_file, output_dir)
+```
+
+This is called by `sync.sh` for each enabled target.
+
+Parameters:
+- `repo_root` -- absolute path to the project root
+- `config_file` -- absolute path to `config.yaml`
+- `output_dir` -- absolute path to output directory (e.g., `/project/.cursor`)
+
+### Available Library Functions
+
+Source `lib/common.sh` for these utilities:
+
+| Function | Description |
+|----------|-------------|
+| `finalize_output_file(file)` | **Call this on every file you write.** Expands layout tokens (`<umbrella>`, `<module>`) and converts CRLF to LF |
+| `normalize_file_to_lf(file)` | LF conversion only — for intermediate files that are not adapter output |
+| `lint_frontmatter(file)` | Warn about unquoted colons, leading tabs, and literal double quotes inside unquoted values (stderr) |
+| `get_frontmatter_value(key, file)` | Extract YAML frontmatter value |
+| `has_frontmatter(file)` | Check for `---` header |
+| `has_paths(file)` | Check for `paths:` field |
+| `get_model(config, ide, tier)` | Resolve model from `models:` override or default |
+| `get_model_default(ide, tier)` | Hardcoded default for `<ide>:<tier>` |
+| `map_access_to_claude_tools(access)` | Tool string for access level |
+| `map_access_to_claude_disallowed(access)` | Disallowed tools string |
+| `read_yaml_list(config, section)` | Read list from `config.yaml` |
+| `resolve_source_dir(repo_root, src)` | Map a source entry to a local dir — `"$repo_root/$src"` for a path, or a shallow clone for a pack reference (`@<name>[/<subpath>]`) or an inline `git+<url>` spec |
+| `source_is_local_path(src)` | True (0) if a source entry is a plain repo-relative path — i.e. neither of the two below. Use this, not a negated `source_is_remote`, whenever a token is about to be pattern-matched against a real directory |
+| `source_is_pack(src)` | True (0) if a source entry references a pack declared under `packs:` (`@<name>`) |
+| `source_is_remote(src)` | True (0) if a source entry is an inline remote `git+` spec |
+| `get_target_field(config, target, field)` | Read a field from a target's config block |
+
+### Transformation Patterns
+
+Each adapter handles three prompt types. Here's how the built-in adapters approach each:
+
+**Rules:**
+
+intelligence-sync routes rule content based on **scope** (always-on vs path-scoped) and on which channels each IDE actually reads, to avoid duplicating content into multiple places.
+
+| Source | `agents` (AGENTS.md) | `claude` | `cursor` | `copilot` | `codex` | `pi` | `opencode` |
+|--------|----------------------|----------|----------|-----------|---------|------|------------|
+| Always-on (no `paths:`) | inlined as canonical | copied as-is | skipped (Cursor reads AGENTS.md) | skipped (Copilot reads AGENTS.md) | skipped (Codex reads AGENTS.md) | skipped (Pi reads AGENTS.md) | skipped (opencode reads AGENTS.md) |
+| Path-scoped (with `paths:`) | listed by name only | copied as-is | `paths:` → `globs:` in `.mdc` | `paths:` → `applyTo:` in `.instructions.md` | not supported by Codex | copied to `.pi/intelligence-sync/rules/` + surfaced by generated extension | not supported (opencode has no native scoping; users may opt in via `instructions:` globs in `opencode.json`) |
+| Listing | full table in AGENTS.md | n/a | n/a | n/a | n/a | extension prompt snippet | n/a |
+
+**Skills:**
+
+Skills follow the [Agent Skills open standard](https://agentskills.io). All supported tools read `SKILL.md` directly — no semantic transformation needed. Skill directories are copied **in full** via `copy_skill_bundle` in `lib/common.sh`: bundled resources (`references/`, `scripts/`, `assets/`) ship alongside `SKILL.md`, because skill bodies point at them by relative path and a copy without them is broken at runtime. Markdown files are LF-normalized; everything else is copied byte-for-byte.
+
+`copy_skill_bundle` also quotes free-text `SKILL.md` frontmatter (`description`, `argument-hint`) for **every** target, not just the strict-YAML ones: `argument-hint: [pr-number]` is a YAML flow *sequence* unquoted, and Claude Code rejects the skill with "argument-hint must be a string" — it vanishes from the picker with no other signal. Adapters must therefore copy skills through this helper rather than plain `cp`.
+
+| Pattern | Used by | Output location |
+|---------|---------|-----------------|
+| Copy skill dirs in full (SKILL.md + bundled resources) | Claude, Cursor, Copilot, Codex, Pi, opencode | `.claude/skills/`, `.cursor/skills/`, `.github/skills/`, `.agents/skills/` (shared by Codex, Pi, opencode) |
+
+**Agents:**
+
+| Pattern | Used by |
+|---------|---------|
+| Transform frontmatter | Claude (`tier`→`model` via `get_model`, `access`→`tools`/`disallowedTools`), Cursor (`tier`→`model` via `get_model`, `access: readonly`→`readonly: true`) |
+| Transform to `.agent.md` | Copilot (`tier`→`model`, `access: readonly`→restricted `tools` array) |
+| Transform to `.toml` | Codex (`name`, `description`, `model`, `model_reasoning_effort` from tier, `sandbox_mode` from access, `developer_instructions`) |
+| Transform to prompt template | Pi (`.pi/prompts/intelligence-agent-<name>.md`; `readonly` becomes prompt guidance, `full` stays implicit) |
+| Transform to markdown subagent | opencode (`.opencode/agents/<name>.md`; `mode: subagent`, `model` from tier via `get_model`, `permission.edit`/`permission.bash` from access) |
+
+Model names come from `get_model(config_file, ide, tier)` in `lib/common.sh`. Defaults are baked into `get_model_default()`; users override per-IDE/tier under `models:` in `config.yaml`. Sync prints a drift report when an override no longer matches the current default.
+
+### Layout tokens (required)
+
+The engine ships artifacts of its own — the `intelligence-authoring` rule and the `intelligence-architect` agent — and they cannot hardcode the umbrella's folder name, because the project chooses it. They write `<umbrella>` and `<module>` instead, and **every adapter must expand them by calling `finalize_output_file` on each file it writes** (it also does the LF normalization that `normalize_file_to_lf` used to do):
+
+| Token | Expands to |
+|---|---|
+| `<umbrella>` | repo-relative umbrella dir (e.g. `Intelligence`) |
+| `<module>` | repo-relative engine module (e.g. `Intelligence/sync`) |
+
+Values are exported by `sync.sh` (`IS_UMBRELLA_REL`, `IS_MODULE_REL`), derived from the detected layout. Expansion covers frontmatter and body, so `paths: ["<umbrella>/**"]` reaches Claude's `paths:`, Cursor's `globs:` and Copilot's `applyTo:` carrying the project's real folder name. A file written without `finalize_output_file` ships a literal `<umbrella>` into an IDE — CI fails the build if any generated output still contains a token.
+
+### Cleanup Contract
+
+Every adapter MUST follow these rules to stay safe alongside others:
+
+1. **Clean only adapter-owned subpaths.** Never `rm -rf "$output_dir"` — users hand-author siblings (`.claude/settings.json`, `.cursor/settings.json`, `.pi/settings.json`, `.opencode/opencode.json`, `.github/workflows/`, project-specific commands and extensions). Mirror `claude.sh` (deletes only `rules/`, `agents/`, and per-skill subdirs), `pi.sh` (deletes only `.pi/intelligence-sync/`, the named extension file, and `intelligence-agent-*.md` prompt files), or `opencode.sh` (deletes only `.opencode/agents/` wholesale, and inside `.opencode/commands/` only files that carry the `<!-- Generated by intelligence-sync. Do not edit manually. -->` marker — hand-authored sibling commands survive).
+2. **The cleanup block defines what the adapter owns.** It is the same set `/intelligence-uninstall-adapter` removes when the target is turned off: whatever `sync_to_<name>()` deletes on every re-sync, and nothing more. Keep it obvious in the source — an uninstall reads it.
+3. **Use shared helpers for shared dirs.** `.agents/skills/` is read by Codex, Pi, opencode, and any tool implementing the [Agent Skills open standard](https://agentskills.io). All adapters writing there must call `sync_open_skill_dirs`, which owns the full lifecycle (clean per-skill subfolders, recreate the dir, populate). Do NOT duplicate the clean / `mkdir -p` in the adapter — calling sites become divergent and one adapter inevitably drifts. It is also *shared*: an uninstall removes it only when no other open-standard target remains enabled.
+4. **Document owned paths in `.gitignore`.** Each adapter's INIT.md `.gitignore` block lists exactly the paths it writes — no broader. This lets users keep hand-authored content under the same root tracked.
+5. **The output path is validated before you run.** `sync.sh` calls `validate_output_path` for every adapter (including `agents`): the resolved output must stay inside the repo, and must not be the repo root, the intelligence source tree, or any configured source. `..` is canonicalized away first, so a config line cannot walk out of the repository. Adapters never need to re-check this — but they must not write outside the `output_dir` they are handed.
+
+## Example: Minimal Adapter
+
+```bash
+#!/bin/bash
+source "$(dirname "$0")/../lib/common.sh"
+
+sync_to_myide() {
+    local repo_root="$1"
+    local config_file="$2"
+    local output_dir="$3"
+
+    echo "=== MyIDE ==="
+    mkdir -p "$output_dir/rules"
+
+    # Copy rules, strip frontmatter
+    while IFS= read -r src; do
+        [ -z "$src" ] && continue
+        # resolve_source_dir maps a source entry to a local dir: "$repo_root/$src"
+        # for a local path, or a shallow clone for a pack reference (`@<name>`)
+        # or an inline `git+<url>` spec. A pack's url/ref/mirror are read from
+        # config.yaml, which it takes from $IS_CONFIG_FILE (exported by sync.sh)
+        # unless you pass the config as a third argument.
+        local dir
+        dir="$(resolve_source_dir "$repo_root" "$src")"
+        [ -d "$dir" ] || continue
+        for f in "$dir"/*.md; do
+            [ -f "$f" ] || continue
+            awk '
+                BEGIN { in_fm=0; past_fm=0 }
+                { sub(/\r$/, "") }
+                /^---$/ {
+                    if (!past_fm) { in_fm = !in_fm; if (!in_fm) { past_fm=1 }; next }
+                }
+                past_fm || !in_fm { print }
+            ' "$f" > "$output_dir/rules/$(basename "$f")"
+            # Every written file goes through finalize_output_file: it expands
+            # the <umbrella> / <module> layout tokens and normalizes CRLF -> LF.
+            finalize_output_file "$output_dir/rules/$(basename "$f")"
+        done
+    done < <(read_yaml_list "$config_file" "rules")
+}
+```
+
+## Testing
+
+Test your adapter by creating a temporary project with `config.yaml` and running:
+
+```bash
+REPO_ROOT=/path/to/test/project bash intelligence/sync/scripts/sync.sh <name>
+```
+
+Verify the output directory contains correctly transformed files. The sync entry point also runs `lint_frontmatter` over every source file before adapters fire — unquoted YAML colons and leading tabs surface as warnings on stderr.
+
+## Distributing changes
+
+When you ship a new adapter, downstream projects pick it up by running:
+
+```bash
+bash intelligence/sync/scripts/update.sh
+```
+
+`update.sh` clones the upstream repo into a `mktemp -d` directory, shows the diff for `intelligence/sync/scripts/` and `intelligence/sync/INIT.md`, and prompts before overwriting. Project content (`config.yaml`, `rules/`, `agents/`, `skills/`, `adapters/`) is never touched. Pass `--yes` for non-interactive runs; set `REPO_URL=<fork>` to use a fork.
+
+This is exactly why a project's own adapter belongs in `intelligence/adapters/` and not in the engine's `scripts/adapters/`: the first is project content, the second is overwritten by the command above.
+
+## Built-in Adapters Reference
+
+| Adapter | Output | Rules | Skills | Agents |
+|---------|--------|-------|--------|--------|
+| `agents.sh` | `AGENTS.md` (committed) | Always-on inlined; scoped listed | Listed in table | Listed in table |
+| `claude.sh` | `.claude/` | Copy as-is (Claude does not read AGENTS.md) | SKILL.md dirs | tier/access → model/tools |
+| `cursor.sh` | `.cursor/` | Scoped only → `.mdc` + globs | Copy as-is | tier → model |
+| `copilot.sh` | `.github/` | Scoped only → `.instructions.md` | SKILL.md dirs | `.agent.md` |
+| `codex.sh` | `.codex/` + `.agents/skills/` | None (AGENTS.md handles) | SKILL.md dirs in `.agents/skills/` | `.toml` in `.codex/agents/` |
+| `pi.sh` | `.pi/` + `.agents/skills/` | Scoped rules copied + listed by generated extension; always-on via AGENTS.md | SKILL.md dirs in `.agents/skills/` | prompt templates in `.pi/prompts/` |
+| `opencode.sh` | `.opencode/` + `.agents/skills/` | None (AGENTS.md handles always-on; opencode has no native scoping) | SKILL.md dirs in `.agents/skills/`; one slash command per skill in `.opencode/commands/<name>.md` (marker-protected) | markdown subagents in `.opencode/agents/` |
+
+### Notes on `agents.sh`
+
+Unlike IDE adapters, `agents.sh` emits a single committed markdown file intended for humans and generic LLM tooling. It reads a static `header` block from `config.yaml` (under `targets.agents.header`) and appends auto-generated tables (agents, skills) and a list of rules derived from frontmatter. The output carries a "do not edit manually" marker and is regenerated on every sync.
+
+#### Why AGENTS.md inlines always-on rules
+
+AGENTS.md is the canonical project doc — Cursor, Copilot, Codex, Pi, and opencode read it natively. Always-on rule content is inlined automatically so all five tools see the same context from one source. Path-scoped rules are NOT inlined (would balloon AGENTS.md in monorepos); they live in tool-specific channels with native scoping (`.cursor/rules/*.mdc` with `globs:`, `.github/instructions/*.instructions.md` with `applyTo:`) or, for Pi, in generated on-demand rule files surfaced by a small extension. opencode has no first-class path-scoped channel; users who need scoped rules can opt into them via `instructions:` globs in `opencode.json`.
+
+Claude Code does not read AGENTS.md natively (per [open feature request](https://github.com/anthropics/claude-code/issues/6235)) — its adapter copies all rules into `.claude/rules/`. There is no duplication because Claude does not consume AGENTS.md.

package/engine/docs/CLI.md

@@ -0,0 +1,91 @@
+# The intelligence CLI
+
+The product interface: one command owning the whole lifecycle of a project's AI intelligence. Installed from npm (`npm i -g @ainova-systems/intelligence`); implemented in bash (`cli/` in this repo) behind a small Node launcher, reusing the sync engine unchanged underneath.
+
+```bash
+cd your-project
+intelligence init
+intelligence add @ainova-systems/core
+intelligence sync
+```
+
+## The CLI (v2) project layout
+
+```
+project/
+├── intelligence.yaml      # manifest, at the repo root (like package.json)
+├── intelligence.lock      # resolved package state — commit it
+├── intelligence/          # the project's own rules/ agents/ skills/
+├── .intelligence/         # gitignored store: packages/<name>/, engine/, backup/
+├── .claude/ .cursor/ …    # generated by sync
+└── AGENTS.md
+```
+
+No engine code lives in the project. The engine ships inside the npm package; its own rules, agents, meta-skills and docs are staged into `.intelligence/engine/` (re-staged whenever the bundled engine version changes) and reach the outputs as ordinary sources. After a fresh clone, `intelligence install` restores the whole store from the lock.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `init [--targets a,b] [--no-sync]` | Detect tools by their marker dirs, write a minimal root manifest, `.gitignore` the store, skeleton `intelligence/`, first sync. `agents` + `claude` are always on. |
+| `add <spec> [--name @s/n] [--no-sync]` | Resolve → fetch → wire sources → manifest entry → lock → sync. Specs: `@scope/name[@range]`, `github:org/repo[#path]`, `git+<url>[@ref][#path]`. |
+| `remove <name>` | Inverse of add: manifest, sources, lock, store. |
+| `install [--frozen] [--force]` | Restore the store exactly from the lock; resolve manifest packages the lock lacks (`--frozen` refuses instead, and fails on sha drift). |
+| `update [name]` | Re-resolve ranges, refetch what moved, rewrite the lock. `ref:`-pinned packages never move here. |
+| `upgrade` | Bring the project to this CLI's engine: restage engine content, apply v2 schema migrations, restamp `sync_version`, sync. |
+| `sync [target]` | Run the bundled engine against the manifest. In a vendored (v1) project it delegates to that project's own engine. |
+| `list` / `status` / `doctor` | Inspect; doctor exits 1 on inconsistencies (unlocked packages, missing store, stale stamp, dead sources). |
+| `registry <list\|add @scope <url>\|remove @scope>` | Bind a scope to a registry repo — rare, once per organization. |
+| `migrate [--dry-run] [--force]` | Convert a vendored setup to the CLI setup. Transactional; see below. |
+
+## Packages
+
+**A package's name is its identity everywhere**: the `packages:` key in the manifest, the store directory (`.intelligence/packages/@scope/name/` — npm's nesting), and the lock key. What a package provides is a convention: whichever of `rules/`, `agents/`, `skills/` exist at its top level get wired into the matching `sources:` sections by `add`.
+
+**Name → repo resolution**, first hit wins:
+
+1. `registries:` in the manifest — a scope bound to a *registry repo*: any git repo holding an `index.yaml`. Private registries are therefore just private repos; git auth covers access.
+2. The bundled default index (`registry/index.yaml`) — needed exactly when a name is not a repo (monorepos: `@ainova-systems/core` → `intelligence-dev-packs` at `packs/core`).
+3. Convention: `@org/name` → `https://github.com/org/name.git`, content at the repo root. Zero infrastructure: any repo with the three dirs is already a package.
+
+**Versions are git tags.** Ranges (`^1.2.0`, `~1.2.0`, exact, `latest`) match stable `x.y.z` tags (optional `v` prefix) listed via `git ls-remote` — no clone to resolve. `add` without a range picks the highest stable tag and records `^that`. A branch or commit pin is `ref:`, the escape hatch that ranges never touch. Prerelease-suffixed tags are invisible to ranges by design.
+
+**The lock is the resolved truth.** Per package: requested range, url, path, resolved tag, commit sha. `install` never consults an index or re-resolves a range — offline restore and reproducibility come from the lock alone; `--frozen` makes any divergence fatal (CI).
+
+## Manifest shapes and ownership
+
+The engine reads what it always read (`project:`, `sync_version:`, `sources:`, `targets:`, `models:`, `ignore:`, `submodules:`) through its own parsers. Two blocks are **CLI-owned** and never touched by the engine — their keys are full quoted package names, which engine parsers deliberately cannot read:
+
+```yaml
+packages:
+  "@ainova-systems/core":
+    version: "^0.3.0"        # or: ref: main  /  url: + path: (direct git specs)
+registries:
+  "@acme": "https://github.com/acme/intelligence-registry.git"
+```
+
+`project.intelligence_dir` names the content dir when it is not `intelligence/`. `sync_version` stays the frozen schema-contract key, stamped by the CLI with the bundled engine version — an npm prerelease suffix never reaches it.
+
+## How the CLI drives the engine
+
+The engine's CLI mode is an env contract, set by the dispatcher and honored only when `IS_CLI=1` (with every variable unset the engine is byte-identical to the vendored one — CI's `legacy-golden` job proves that on every push):
+
+| Variable | Value in CLI mode |
+|---|---|
+| `CONFIG_FILE` | `<root>/intelligence.yaml` |
+| `REPO_ROOT` | the project root |
+| `IS_UMBRELLA_REL` | content dir (`intelligence`) |
+| `IS_MODULE_REL` | `.intelligence/engine` |
+| `IS_SYNC_CMD` | `intelligence sync` (expanded for the `<sync-cmd>` token) |
+| `IS_PROTECTED_DIRS` | `<content-dir>:.intelligence` — restores output-path protection for a root manifest |
+| `IS_SUPPRESS_CLI_NOTE` | set to silence the vendored-flow recommendation note |
+
+## migrate: vendored (v1) → CLI (v2)
+
+Fail-closed preconditions (clean worktree unless `--force`; no half-migrated state; project schema not newer than the engine; an older schema is first brought up by the engine's own migration chain). Then **stage** — the manifest is `config.yaml` transformed comment-preservingly (module sources → `.intelligence/engine/*`, `@pack/sub` references → store paths, `packs:` → `packages:` entries keeping their `ref:` pins), mirrored packs are *copied* from their mirrors (network untouched, sha carried from the `.pack` stamp), transient packs fetched — **verify** (staged sources exist; per-adapter `enabled`/`output` equality against the old config) — **commit**: store and manifest move in, a real sync must report `IS_STATUS=ok`, and only then are the vendored module, `config.yaml` (backed up to `.intelligence/backup/`) and the mirrors removed. Any earlier failure rolls back to an untouched project. `--dry-run` stages, verifies, prints, writes nothing.
+
+## Developing and releasing the CLI
+
+- `bash cli/tests/e2e-packages.sh` and `bash cli/tests/e2e-lifecycle.sh` — the hermetic suites CI runs (file:// fixtures).
+- `bash npm/build.sh [version]` assembles `npm/dist/` from the repo (cli + engine + registry index).
+- The `release-npm` workflow (manual dispatch) publishes `<engine>-rc.N` to dist-tag `next` from any ref, and the stable `<engine>` version to `latest` only when dispatched from the matching `v<engine>` tag. Requires the `NPM_TOKEN` secret.