@ainova-systems/intelligence 0.11.0-rc.3 → 0.11.0-rc.5

package/cli/lib/cli-common.sh

@@ -24,10 +24,15 @@ source "$CLI_DIR/lib/semver.sh"
 source "$CLI_DIR/lib/registry.sh"
 source "$CLI_DIR/lib/lockfile.sh"
 
-# Meta-skills that the CLI replaces with first-class commands — staging skips
-# them so a v2 project never carries a skill telling the agent to run a flow
-# the CLI already owns.
-CLI_OBSOLETE_SKILLS="intelligence-update intelligence-sync"
+# The engine's own content as a package: OPTIONAL but auto-selected at init.
+# Package by UX (manifest entry, lockfile row, list/search/remove), bundle by
+# mechanics — at the version the CLI ships, it materializes from the npm
+# bundle without network; only a cross-version install reaches git. The pin
+# is held exactly at the bundled engine version and moved only by `upgrade`.
+SYNC_PKG_NAME="@ainova-systems/sync"
+SYNC_PKG_URL="https://github.com/ainova-systems/intelligence-sync.git"
+SYNC_PKG_PATH="intelligence/sync"
+SYNC_PKG_STORE=".intelligence/packages/@ainova-systems/sync"
 
 # --- Project detection ---------------------------------------------------
 # Sets: IP_MODE (v2|legacy|none), IP_ROOT, IP_UMBRELLA, IP_MODULE_DIR.
@@ -90,51 +95,26 @@ bundled_engine_version() {
     tr -d ' \t\r\n' < "$IS_ENGINE_DIR/scripts/VERSION"
 }
 
-# --- Engine content staging ----------------------------------------------
-# The v2 project vendors no engine code; the engine's own rules / agents /
-# meta-skills / docs are staged into the package store so sources can reach
-# them as ordinary repo-relative dirs. Re-staged whenever the bundled engine
-# version differs from the `.version` stamp.
-# stage_engine_content <dest-dir> — unconditional copy of the engine's own
-# content into <dest-dir> plus the `.version` stamp.
-stage_engine_content() {
-    local store="$1"
-    rm -rf "$store"
-    mkdir -p "$store"
-    local d s name skip
-    # `scripts` travels too: engine-shipped skills reference `<module>/scripts/…`
-    # (adapters, docs) and `<module>` resolves here, so the paths they hand an
-    # agent must exist. Running that sync.sh directly is harmless — outside CLI
-    # mode it fails closed rather than generating against the wrong layout.
-    for d in rules agents docs scripts; do
-        [ -d "$IS_ENGINE_DIR/$d" ] && cp -R "$IS_ENGINE_DIR/$d" "$store/$d"
-    done
-    if [ -d "$IS_ENGINE_DIR/skills" ]; then
-        mkdir -p "$store/skills"
-        for s in "$IS_ENGINE_DIR"/skills/*/; do
-            [ -d "$s" ] || continue
-            name="$(basename "$s")"
-            skip=0
-            for d in $CLI_OBSOLETE_SKILLS; do
-                [ "$name" = "$d" ] && skip=1
-            done
-            [ "$skip" = "1" ] && continue
-            cp -R "$s" "$store/skills/$name"
-        done
-    fi
-    bundled_engine_version > "$store/.version"
+# --- The sync package's manifest/lock plumbing ---------------------------
+# sync_pkg_entry <manifest> — write/refresh the package's manifest entry:
+# name + exact pin + explicit url/path, so resolution never depends on any
+# registry (a project registry shadowing the name cannot brick the engine).
+sync_pkg_entry() {
+    local manifest="$1"
+    qmap_set "$manifest" "packages" "$SYNC_PKG_NAME" "version" "$(bundled_engine_version)"
+    qmap_set "$manifest" "packages" "$SYNC_PKG_NAME" "url" "$SYNC_PKG_URL"
+    qmap_set "$manifest" "packages" "$SYNC_PKG_NAME" "path" "$SYNC_PKG_PATH"
 }
 
-ensure_engine_staged() {
-    local root="$1"
-    local store="$root/.intelligence/engine"
-    local bundled_ver staged_ver
-    bundled_ver="$(bundled_engine_version)"
-    staged_ver=""
-    [ -f "$store/.version" ] && staged_ver="$(tr -d ' \t\r\n' < "$store/.version")"
-    [ "$staged_ver" = "$bundled_ver" ] && return 0
-    stage_engine_content "$store"
-    echo "  engine content staged: .intelligence/engine ($bundled_ver)"
+# sync_pkg_install <root> — materialize the package into the store and lock
+# it (offline at the bundled version — fetch_package's bundle-seed guard).
+sync_pkg_install() {
+    local root="$1" ver sha
+    ver="$(bundled_engine_version)"
+    sha="$(fetch_package "$SYNC_PKG_URL" "v$ver" "$SYNC_PKG_PATH" "$root/$SYNC_PKG_STORE")"
+    wire_package_sources "$root/intelligence.yaml" "$SYNC_PKG_NAME" "$SYNC_PKG_STORE" "$root"
+    lock_upsert "$root/intelligence.lock" "$SYNC_PKG_NAME" "$ver" "$SYNC_PKG_URL" "$SYNC_PKG_PATH" "v$ver" "$sha"
+    echo "  engine content installed: $SYNC_PKG_STORE (v$ver)"
 }
 
 # --- The engine env contract ---------------------------------------------
@@ -149,5 +129,6 @@ export_engine_env() {
     export IS_UMBRELLA_REL="$umbrella"
     export IS_MODULE_REL=".intelligence/engine"
     export IS_SYNC_CMD="intelligence sync"
+    export IS_MANIFEST_NAME="intelligence.yaml"
     export IS_PROTECTED_DIRS="$umbrella:.intelligence"
 }

package/cli/lib/manifest.sh

@@ -194,6 +194,85 @@ qmap_delete_key() {
     '
 }
 
+# --- registries: a trust LIST, not a scope map -----------------------------
+# The block holds registry repo URLs in trust order. Two shapes are read so
+# early manifests keep working: the list form (`- "url"`) and the retired
+# flat-map form (`"@scope": "url"` — the scope label is ignored, the URL is
+# simply another registry).
+
+# registries_list <file> — registry URLs, one per line, manifest order.
+registries_list() {
+    [ -f "$1" ] || return 0
+    awk '
+        { sub(/\r$/, "") }
+        /^registries:[ \t]*$/ { inb = 1; next }
+        inb && /^[^ #]/ { inb = 0 }
+        inb {
+            line = $0
+            if (line ~ /^[ \t]*-[ \t]*/) {
+                sub(/^[ \t]*-[ \t]*/, "", line)
+            } else if (line ~ /^  "/) {
+                c = index(line, ":")
+                if (c == 0) next
+                line = substr(line, c + 1)
+            } else next
+            sub(/^[ \t]+/, "", line)
+            gsub(/["\x27]/, "", line)
+            sub(/[ \t]+#.*$/, "", line)
+            sub(/[ \t]+$/, "", line)
+            if (line != "") print line
+        }
+    ' "$1"
+}
+
+# registries_add <file> <url> — idempotent append in list form.
+registries_add() {
+    local file="$1" url="$2" existing
+    while IFS= read -r existing; do
+        [ "$existing" = "$url" ] && return 0
+    done < <(registries_list "$file")
+    _qmap_stage "$file" -v url="$url" '
+        function entry() { return "  - \"" url "\"" }
+        { sub(/\r$/, "") }
+        /^registries:[ \t]*$/ { blockseen = 1; inb = 1; print; next }
+        inb && /^[^ #]/ { if (!done) { print entry(); done = 1 }; inb = 0 }
+        { last = $0; print }
+        END {
+            if (inb && !done) { print entry(); done = 1 }
+            if (!blockseen) {
+                if (last != "") print ""
+                print "registries:"
+                print entry()
+            }
+        }
+    '
+}
+
+# registries_remove <file> <url> — drop the entry, either shape.
+registries_remove() {
+    local file="$1" url="$2"
+    [ -f "$file" ] || return 0
+    _qmap_stage "$file" -v url="$url" '
+        { sub(/\r$/, "") }
+        /^registries:[ \t]*$/ { inb = 1; print; next }
+        inb && /^[^ #]/ { inb = 0 }
+        inb {
+            line = $0
+            v = ""
+            if (line ~ /^[ \t]*-[ \t]*/) { v = line; sub(/^[ \t]*-[ \t]*/, "", v) }
+            else if (line ~ /^  "/) { c = index(line, ":"); if (c > 0) v = substr(line, c + 1) }
+            if (v != "") {
+                sub(/^[ \t]+/, "", v)
+                gsub(/["\x27]/, "", v)
+                sub(/[ \t]+#.*$/, "", v)
+                sub(/[ \t]+$/, "", v)
+                if (v == url) next
+            }
+        }
+        { print }
+    '
+}
+
 # sources_remove_entry <file> <section> <entry> — remove `- "entry"` from
 # sources.<section>. Inverse of the engine-side _mig_add_source.
 sources_remove_entry() {

package/cli/lib/registry.sh

@@ -1,13 +1,19 @@
 #!/bin/bash
 # Name -> source resolution and package fetching.
 #
-# Resolution order (first hit wins):
-#   1. project `registries:` — a scope bound to a registry repo (a git repo
-#      holding index.yaml); private orgs override anything shipped
+# Resolution order (first registry to DECLARE the name wins):
+#   1. project `registries:` — a trust LIST of registry repos (git repos
+#      holding index.yaml), consulted in manifest order; adding one is an
+#      explicit, committed act of trust in the names it declares
 #   2. the bundled default index (registry/index.yaml next to the CLI)
 #   3. convention: @org/name -> https://github.com/org/name.git, content at
 #      the repo root — the zero-infrastructure default
 #
+# The NAME is the trust anchor a developer reasons with; source integrity is
+# a separate mechanism: the lock pins url+sha, a project-registry hit that
+# shadows a bundled name with a different url warns loudly, and doctor flags
+# resolution/lock url drift.
+#
 # An index is itself fetched with git (never curl): auth, proxies and private
 # hosting all come for free, and the CLI keeps the engine's bash+awk+git-only
 # dependency footprint.
@@ -46,22 +52,33 @@ resolve_package_source() {
     local scope="${name%%/*}" short="${name#*/}"
     RES_URL=""; RES_PATH=""; RES_VIA=""
 
+    local reg_url index bundled burl
+    bundled="$(default_index_file)"
     if [ -n "$manifest" ] && [ -f "$manifest" ]; then
-        local reg_url index
-        reg_url="$(qmap_value "$manifest" "registries" "$scope")"
-        if [ -n "$reg_url" ]; then
+        while IFS= read -r reg_url; do
+            [ -n "$reg_url" ] || continue
             index="$(_fetch_index "${reg_url#git+}")"
-            [ -n "$index" ] || die "registry for scope '$scope' is unreachable or has no index.yaml: $reg_url"
+            if [ -z "$index" ]; then
+                echo "  WARN: registry unreachable or missing index.yaml, skipped: $reg_url" >&2
+                continue
+            fi
             RES_URL="$(qmap_field "$index" "packages" "$name" "url")"
-            RES_PATH="$(qmap_field "$index" "packages" "$name" "path")"
-            [ -n "$RES_URL" ] || die "package '$name' not found in the '$scope' registry ($reg_url)"
-            RES_VIA="registry:$reg_url"
-            return 0
-        fi
+            if [ -n "$RES_URL" ]; then
+                RES_PATH="$(qmap_field "$index" "packages" "$name" "path")"
+                RES_VIA="registry:$reg_url"
+                # Shadowing a bundled name with a DIFFERENT source is legal
+                # (that is what overriding means) but never silent.
+                if [ -n "$bundled" ]; then
+                    burl="$(qmap_field "$bundled" "packages" "$name" "url")"
+                    if [ -n "$burl" ] && [ "$burl" != "$RES_URL" ]; then
+                        echo "  WARN: $name from this registry overrides the bundled source ($burl)" >&2
+                    fi
+                fi
+                return 0
+            fi
+        done < <(registries_list "$manifest")
     fi
 
-    local bundled
-    bundled="$(default_index_file)"
     if [ -n "$bundled" ]; then
         RES_URL="$(qmap_field "$bundled" "packages" "$name" "url")"
         if [ -n "$RES_URL" ]; then
@@ -77,6 +94,36 @@ resolve_package_source() {
     return 0
 }
 
+# suggest_similar <manifest-or-empty> <@scope/name> — "Did you mean" lines to
+# stderr, matched on the short name (singular/plural tolerant) across every
+# project registry and the bundled index.
+suggest_similar() {
+    local manifest="$1" name="$2"
+    local want cand cshort reg_url index seen=" "
+    want="${name#*/}"; want="${want%s}"
+    _suggest_from() {
+        local idx="$1"
+        [ -n "$idx" ] && [ -f "$idx" ] || return 0
+        while IFS= read -r cand; do
+            [ -n "$cand" ] || continue
+            case "$seen" in *" $cand "*) continue ;; esac
+            cshort="${cand#*/}"; cshort="${cshort%s}"
+            if [ "$cshort" = "$want" ] && [ "$cand" != "$name" ]; then
+                seen="$seen$cand "
+                echo "  Did you mean: intelligence add $cand" >&2
+            fi
+        done < <(qmap_keys "$idx" "packages")
+    }
+    if [ -n "$manifest" ] && [ -f "$manifest" ]; then
+        while IFS= read -r reg_url; do
+            [ -n "$reg_url" ] || continue
+            index="$(_fetch_index "${reg_url#git+}")"
+            _suggest_from "$index"
+        done < <(registries_list "$manifest")
+    fi
+    _suggest_from "$(default_index_file)"
+}
+
 # fetch_package <url> <ref> <subpath> <dest-dir>
 # Shallow-clones url@ref (tag, branch, or SHA fallback), copies <subpath>
 # (or the repo root) into <dest-dir>, prints the resolved commit sha.
@@ -84,6 +131,22 @@ resolve_package_source() {
 # store holds the bytes the package published.
 fetch_package() {
     local url="$1" ref="$2" subpath="$3" dest="$4"
+    # Bundle seed: the engine-content package at the CLI's own version copies
+    # from the npm bundle — no network, which keeps init / fresh-clone install
+    # / migrate offline exactly like the staging they replace. Keyed on the
+    # full (url, path, ref) triple; any other version or source falls through
+    # to the normal clone.
+    if [ "$url" = "$SYNC_PKG_URL" ] && [ "$subpath" = "$SYNC_PKG_PATH" ] \
+        && [ "${ref#v}" = "$(bundled_engine_version)" ]; then
+        rm -rf "$dest"
+        mkdir -p "$dest"
+        cp -R "$IS_ENGINE_DIR/." "$dest/"
+        rm -rf "$dest/.git"
+        if [ -f "$IS_ENGINE_DIR/scripts/ENGINE_SHA" ]; then
+            tr -d ' \t\r\n' < "$IS_ENGINE_DIR/scripts/ENGINE_SHA"
+        fi
+        return 0
+    fi
     local tmp sha src
     local -a branch_arg=()
     [ -n "$ref" ] && branch_arg=(--branch "$ref")

package/cli/lib/semver.sh

@@ -75,7 +75,10 @@ semver_match() {
 # onto their tag.
 list_remote_versions() {
     local url="$1"
-    GIT_TERMINAL_PROMPT=0 git ls-remote --tags "$url" 2>/dev/null \
+    # `|| true` inside the pipeline: an unreachable repo must read as "no
+    # versions", not kill a pipefail caller mid-command-substitution —
+    # reachability is the CALLER's question (add probes it explicitly).
+    { GIT_TERMINAL_PROMPT=0 git ls-remote --tags "$url" 2>/dev/null || true; } \
         | awk '{
             sub(/\r$/, "")
             ref = $2
@@ -92,7 +95,7 @@ list_remote_versions() {
 # prints "<tag> <sha>". Peeled sha (the commit a tag object points at) wins.
 remote_tag_for_version() {
     local url="$1" ver="${2#v}"
-    GIT_TERMINAL_PROMPT=0 git ls-remote --tags "$url" 2>/dev/null \
+    { GIT_TERMINAL_PROMPT=0 git ls-remote --tags "$url" 2>/dev/null || true; } \
         | awk -v want="$ver" '
             {
                 sub(/\r$/, "")

package/engine/agents/intelligence-operator.md

@@ -19,10 +19,10 @@ 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
+The status contract (`<module>/docs/CONVENTIONS.md`, Migration & Module Contract). Every flow
+here is deterministic and fail-closed: the sync is a pure synchronizer that refuses across an
+un-applied schema, the update flow stages, verifies and only then commits, and every flow
+reports `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.

package/engine/docs/ADAPTERS.md

@@ -110,7 +110,8 @@ The engine ships artifacts of its own — the `intelligence-authoring` rule and
 | Token | Expands to |
 |---|---|
 | `<umbrella>` | repo-relative umbrella dir (e.g. `Intelligence`) |
-| `<module>` | repo-relative engine module (e.g. `Intelligence/sync`; CLI setup: `.intelligence/engine`) |
+| `<module>` | repo-relative engine module (e.g. `Intelligence/sync`; CLI setup: `.intelligence/packages/@ainova-systems/sync`) |
+| `<manifest>` | the project's config file name — vendored: `config.yaml`, CLI setup: `intelligence.yaml` (`IS_MANIFEST_NAME`) |
 | `<sync-cmd>` | the sync invocation — vendored: `bash <module>/scripts/sync.sh`, CLI setup: `intelligence sync` (`IS_SYNC_CMD`) |
 
 Values are exported by `sync.sh` (`IS_UMBRELLA_REL`, `IS_MODULE_REL`; `IS_SYNC_CMD` comes from the CLI in CLI mode), 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.

package/engine/docs/CLI.md

@@ -16,35 +16,37 @@ 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/
+├── .intelligence/         # gitignored store: packages/<name>/, 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.
+No engine code lives in the project. The engine's *scripts* ship inside the npm package; the engine's *content* — the authoring rule, both engine agents, every `intelligence-*` meta-skill and the docs — is the package **`@ainova-systems/sync`**: auto-added by `init` (opt out with `--bare`), visible in `list`/`search`, pinned exactly to the bundled engine version, and materialized from the npm bundle without network whenever the pin matches (only a cross-version install reaches git). `intelligence update` never moves it — `intelligence upgrade` does, together with the schema stamp. Removing it (`remove @ainova-systems/sync --force`) drops the meta-content from the outputs while the sync engine itself keeps working. 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. |
+| `init [--targets a,b] [--dir d] [--bare] [--no-sync]` | Detect tools by their marker dirs, write a minimal self-documenting root manifest, `.gitignore` the store, install `@ainova-systems/sync` (unless `--bare`), first sync. No dirs are created — authoring one later needs no config edit. |
 | `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. |
+| `remove <name> [--force]` | 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. |
+| `upgrade` | Bring the project to this CLI's engine: apply v2 schema migrations, move the `@ainova-systems/sync` pin to the bundled version and reinstall it, 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. |
+| `registry <list\|add <url> [--force]\|remove <url>>` | Manage the trust list of registries — rare, once per organization. `add` fails closed on a URL with no `index.yaml` (`--force` records it anyway). |
 | `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:
+**Names are global.** The name is the trust anchor a developer reasons with — the same `@scope/name` means the same package in every project, every lock and every conversation. A registry never renames anything, and two versions of one name cannot coexist in a project: intelligence artifacts land in each tool's flat namespace (`.claude/skills/<name>/`, the `AGENTS.md` tables), so duplicates would collide file-by-file. Need pieces of two versions? That is a different package — fork it under a different name. Need to override one artifact? Put a same-named file in your own content dir; project sources are listed after package sources.
 
-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.
+**Name → repo resolution** — the first registry to *declare* the name wins:
+
+1. `registries:` in the manifest — a **trust list** of registry repos (git repos holding an `index.yaml`), consulted in order. Adding one is an explicit, committed, reviewable act of trust in the names it declares; private registries are just private repos, git auth covers access. A project-registry hit that shadows a bundled name with a *different* source warns loudly, and `doctor` flags a name whose current resolution url no longer matches the lock.
 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.
 
@@ -61,7 +63,7 @@ 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"
+  - "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.
@@ -75,14 +77,15 @@ The engine's CLI mode is an env contract, set by the dispatcher and honored only
 | `CONFIG_FILE` | `<root>/intelligence.yaml` |
 | `REPO_ROOT` | the project root |
 | `IS_UMBRELLA_REL` | content dir (`intelligence`) |
-| `IS_MODULE_REL` | `.intelligence/engine` |
+| `IS_MODULE_REL` | `.intelligence/packages/@ainova-systems/sync` |
+| `IS_MANIFEST_NAME` | `intelligence.yaml` (feeds the `<manifest>` token; vendored default `config.yaml`) |
 | `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.
+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 → the `@ainova-systems/sync` package store, `@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
 

package/engine/docs/CONVENTIONS.md

@@ -56,7 +56,8 @@ An artifact shipped *by the engine* cannot write the umbrella's name down — th
 | Token | Expands to | Example |
 |---|---|---|
 | `<umbrella>` | repo-relative umbrella dir | `Intelligence` |
-| `<module>` | repo-relative engine module | `Intelligence/sync` (CLI setup: `.intelligence/engine`) |
+| `<module>` | repo-relative engine module | `Intelligence/sync` (CLI setup: `.intelligence/packages/@ainova-systems/sync`) |
+| `<manifest>` | the project's config file, by name | vendored: `config.yaml`; CLI setup: `intelligence.yaml` |
 | `<sync-cmd>` | how a reader re-runs the sync | vendored: `bash Intelligence/sync/scripts/sync.sh`; CLI setup: `intelligence sync` |
 
 Expansion covers frontmatter and body alike, so `paths: ["<umbrella>/**"]` reaches Claude's `paths:`, Cursor's `globs:` and Copilot's `applyTo:` already carrying the project's real folder name. Project-authored artifacts may use the tokens too, but they have no reason to — they can simply name their own folders. `<sync-cmd>` exists because "run a sync" is spelled differently per setup: engine content says the token, and `IS_SYNC_CMD` (set by the CLI) picks the spelling; unset, it reproduces the vendored command string exactly.
@@ -408,12 +409,13 @@ Bash emits `IS_STATUS=<code> [IS_DETAIL=...]` on stdout and exits with the match
 |---|---|
 | `CONFIG_FILE` | `<root>/intelligence.yaml` (the root manifest) |
 | `REPO_ROOT` | project root |
-| `IS_UMBRELLA_REL` / `IS_MODULE_REL` | content dir (default `intelligence`) / `.intelligence/engine` |
+| `IS_UMBRELLA_REL` / `IS_MODULE_REL` | content dir (default `intelligence`) / `.intelligence/packages/@ainova-systems/sync` |
+| `IS_MANIFEST_NAME` | `intelligence.yaml` — feeds the `<manifest>` token (vendored default: `config.yaml`) |
 | `IS_SYNC_CMD` | `intelligence sync` (feeds the `<sync-cmd>` token) |
 | `IS_PROTECTED_DIRS` | colon-separated dirs `validate_output_path` must refuse — restores the source-tree protection a root manifest would otherwise disable |
 | `IS_SUPPRESS_CLI_NOTE` | silences the vendored-flow recommendation NOTE (stderr-only either way) |
 
-In CLI projects the `intelligence-sync` and `intelligence-update` meta-skills are not installed — `intelligence sync` / `intelligence update` replace them; the other meta-skills ship unchanged and reach outputs from `.intelligence/engine/skills`. `sync.sh` in CLI mode still never migrates: an outdated stamp exits `needs-update` and the CLI's own `upgrade` closes the gap. See `docs/CLI.md` for the full CLI surface.
+In CLI projects the engine's content is the `@ainova-systems/sync` package (auto-added by `init`, pinned to the engine version, moved only by `intelligence upgrade`), so **every** meta-skill ships in both modes: `intelligence-sync` runs `<sync-cmd>` wherever it lands, and `intelligence-update` self-redirects to `intelligence upgrade` when it finds a root `intelligence.yaml`. `sync.sh` in CLI mode still never migrates: an outdated stamp exits `needs-update` and the CLI's own `upgrade` closes the gap. See `docs/CLI.md` for the full CLI surface.
 
 ## .gitignore Pattern
 

package/engine/rules/intelligence-authoring.md

@@ -25,9 +25,9 @@ Three ways to shorten, in order of what they are worth:
 
 ## Source of truth
 
-Edit the sources listed in `config.yaml` — the `rules/`, `agents/` and `skills/` directories it names — and `config.yaml` itself. Everything else is derived: `.claude/`, `.cursor/`, `.github/{instructions,agents,skills}/`, `.codex/`, `.agents/skills/`, `.pi/`, `.opencode/` and `AGENTS.md` are **generated output**, and a hand edit there survives exactly until the next sync.
+Edit the sources listed in `<manifest>` — the `rules/`, `agents/` and `skills/` directories it names — and `<manifest>` itself. A source that arrived from the engine or an installed package is not yours to edit either — it is replaced on the next update or install; change it in its own repository. Everything else is derived: `.claude/`, `.cursor/`, `.github/{instructions,agents,skills}/`, `.codex/`, `.agents/skills/`, `.pi/`, `.opencode/` and `AGENTS.md` are **generated output**, and a hand edit there survives exactly until the next sync.
 
-`<module>/` is the vendored engine. It owns its own rules, agents and meta-skills; `update.sh` replaces them wholesale, so a local edit there is lost at the next update. Fix it upstream instead.
+`<module>/` is the engine's own content. It owns its own rules, agents and meta-skills, and every engine update replaces it wholesale, so a local edit there is lost. Fix it upstream instead.
 
 After any change: `<sync-cmd>`. A change that was not synced does not exist for any tool.
 
@@ -84,11 +84,11 @@ The verb just names the action — `add-`, `run-`, `review-`, `extract-`, `plan-
 
 Two verbs are told apart by what already exists. **`add-` puts one new member into a set that is already there** — a field on an existing type, a record among records, a component in the inventory the project keeps — so the noun names the member, and the number of files it takes to land is not the point. **`create-` brings the container itself into existence**, where nothing hosted it before. Neither verb describes how a skill is factored inside, so splitting a skill's internals never renames it.
 
-`intelligence-` is **reserved** for the engine's own artifacts. A project skill carrying that prefix is pruned by the updater — rename it.
+`intelligence-` is **reserved** for the engine's own artifacts. A project skill carrying that prefix collides with engine ownership — everything under the prefix is the engine's to replace or remove on update — rename it.
 
 ### Shape
 
-- **A skill is executed, so it must not hardcode what can move.** Its steps are followed literally: a path, a command or a project name baked into a procedure breaks the moment the layout moves. Resolve them from a rule or from `config.yaml` instead. This does **not** apply to rules and agents — a rule's job is to *describe* the repository, so naming a path in prose is exactly right. Naming a path is description; baking one into a procedure is a defect waiting to fire.
+- **A skill is executed, so it must not hardcode what can move.** Its steps are followed literally: a path, a command or a project name baked into a procedure breaks the moment the layout moves. Resolve them from a rule or from `<manifest>` instead. This does **not** apply to rules and agents — a rule's job is to *describe* the repository, so naming a path in prose is exactly right. Naming a path is description; baking one into a procedure is a defect waiting to fire.
 - **Keep everything the skill needs inside the skill's own folder.** The Agent Skills standard lets a skill ship `scripts/`, `references/` and `assets/` beside `SKILL.md`, and sync copies the whole directory, so a bundled helper travels with the skill to every tool. That is the default.
 - **Promote a helper out of the skill folder only when a second skill needs it** — then it belongs beside the source groups, and every skill resolves it the same way. The dividing line is reuse, not repetition: one skill's helper stays with that skill however often it runs.
 - **A helper is code.** It gets what code gets — a test, and a way to run it that does not assume one person's machine.

package/engine/scripts/ENGINE_SHA

@@ -0,0 +1 @@
+40b7d3a7dd936c5ffb854f9e5f553720c48ef494

package/engine/scripts/lib/common.sh

@@ -42,13 +42,16 @@ finalize_output_file() {
     # `<sync-cmd>` is how engine content says "run a sync": vendored setups
     # expand it to the script invocation (built from $mod, so it reproduces the
     # exact pre-token string), the CLI overrides it via IS_SYNC_CMD
-    # (`intelligence sync`).
+    # (`intelligence sync`). `<manifest>` names the project's config file the
+    # same way: `config.yaml` vendored, `intelligence.yaml` under the CLI
+    # (IS_MANIFEST_NAME).
     local sc="${IS_SYNC_CMD:-bash $mod/scripts/sync.sh}"
+    local mf="${IS_MANIFEST_NAME:-config.yaml}"
     local tmp_file="$target.tmp"
     # Literal (index-based) substitution, not gsub: a regex replacement would
     # give `&` in a path its special meaning, and POSIX awk has no way to pass a
     # replacement string verbatim.
-    awk -v umb="$umb" -v mod="$mod" -v sc="$sc" '
+    awk -v umb="$umb" -v mod="$mod" -v sc="$sc" -v mf="$mf" '
         function repl(s, from, to,   out, i) {
             out = ""
             while ((i = index(s, from)) > 0) {
@@ -60,6 +63,7 @@ finalize_output_file() {
         {
             sub(/\r$/, "")
             $0 = repl($0, "<sync-cmd>", sc)
+            $0 = repl($0, "<manifest>", mf)
             $0 = repl($0, "<module>", mod)
             $0 = repl($0, "<umbrella>", umb)
             print

package/engine/skills/intelligence-add-agent/SKILL.md

@@ -9,19 +9,19 @@ argument-hint: <domain> [description]
 ## Steps
 
 1. **Determine domain prefix** (the scope is required):
-   - **Reuse the existing domain when one fits**: list `intelligence/agents/` and `intelligence/skills/`. If a domain prefix is already established for the target area (`backend-`, `frontend-`, `devops-`), use it. Introduce a new domain only when the scope is materially different from all existing ones.
+   - **Reuse the existing domain when one fits**: list `<umbrella>/agents/` and `<umbrella>/skills/`. If a domain prefix is already established for the target area (`backend-`, `frontend-`, `devops-`), use it. Introduce a new domain only when the scope is materially different from all existing ones.
    - **When no existing domain fits**, derive from repo structure:
-     - Single / root project → use the project codename from `intelligence/config.yaml` → `project.name`
+     - Single / root project → use the project codename from `<manifest>` → `project.name`
      - Backend service / API component → `backend-`
      - Frontend / web / UI component → `frontend-`
      - Infrastructure, IaC, CI/CD, deployment → `devops-`
      - Shared library / common / cross-cutting code → `core-`
      - Test suites (e2e, integration) → `tests-`
-     - Tool-internal (intelligence-sync itself) → `intelligence-`
+     - Tool-internal (intelligence-sync itself) → `intelligence-` (only inside the intelligence-sync repo — downstream projects must not use this prefix)
    - If the repo is a monorepo with named components (e.g., `apps/billing`, `services/auth`), prefer the component name as the domain (`billing-`, `auth-`).
    - **Every agent needs a domain prefix.** If the scope is unclear, ask the user before proceeding.
 
-2. **Check existing agents**: Read `intelligence/agents/` to avoid duplicates. If an agent for this domain exists, ask user whether to update it instead.
+2. **Check existing agents**: Read `<umbrella>/agents/` to avoid duplicates. If an agent for this domain exists, ask user whether to update it instead.
 
 3. **Determine tier and access**:
    - Developer agents: `tier: heavy`, `access: full`
@@ -36,7 +36,7 @@ argument-hint: <domain> [description]
    - Build and test commands
    - Key conventions and forbidden patterns
 
-5. **Create agent**: Write `intelligence/agents/<domain>-<role>.md` with frontmatter:
+5. **Create agent**: Write `<umbrella>/agents/<domain>-<role>.md` (create the directory if missing) with frontmatter:
    ```yaml
    ---
    name: <domain>-<role>
@@ -52,11 +52,11 @@ argument-hint: <domain> [description]
 
 6. **Write body** with sections: **Expertise** -> **Boundaries** -> **Build & Verify**
    - An agent is **thin**: who it is, where it stops, how it verifies. Everything else already reaches it.
-   - **Do not tell the agent to read the rules.** Rules load on their own: Claude Code loads `.claude/rules/` into every custom subagent's startup context alongside `CLAUDE.md` (*Subagents → What loads at startup*), and Cursor / Copilot / Codex / Pi / opencode receive always-on rules inlined in `AGENTS.md`. A `Read intelligence/rules/<domain>.md before starting` line duplicates content the agent already has — double the tokens, and a second copy that drifts from the rule it copied.
+   - **Do not tell the agent to read the rules.** Rules load on their own: Claude Code loads `.claude/rules/` into every custom subagent's startup context alongside `CLAUDE.md` (*Subagents → What loads at startup*), and Cursor / Copilot / Codex / Pi / opencode receive always-on rules inlined in `AGENTS.md`. A `Read <umbrella>/rules/<domain>.md before starting` line duplicates content the agent already has — double the tokens, and a second copy that drifts from the rule it copied.
    - **Point at a rule, never restate it.** If you want to copy a rule into the agent, the rule is in the wrong place — move it, do not clone it.
    - **Do carry** what is genuinely the agent's own: its boundaries ("if the app is not running, stop — do not hand-write the output"), its verification commands, its definition of done.
    - All content must come from actual codebase analysis.
 
-7. **Link existing skills**: Find skills in `intelligence/skills/` matching this domain prefix and add them to the agent's `skills:` frontmatter.
+7. **Link existing skills**: Find skills in `<umbrella>/skills/` matching this domain prefix and add them to the agent's `skills:` frontmatter.
 
 8. **Run `/intelligence-sync`** to distribute to all enabled IDE targets.

package/engine/skills/intelligence-add-rule/SKILL.md

@@ -9,9 +9,9 @@ argument-hint: <name> [paths-glob]
 ## Steps
 
 1. **Determine rule name from domain** (the scope is required):
-   - **Reuse the existing domain when one fits**: list `intelligence/rules/`. If a rule file covers the target area (e.g., `backend.md`, `frontend.md`), extend it. Introduce a new domain only when the scope is materially different from all existing rules.
+   - **Reuse the existing domain when one fits**: list `<umbrella>/rules/`. If a rule file covers the target area (e.g., `backend.md`, `frontend.md`), extend it. Introduce a new domain only when the scope is materially different from all existing rules.
    - **When no existing rule fits**, derive the filename from repo structure:
-     - Single / root project → use the project codename from `intelligence/config.yaml` → `project.name` (e.g., `<codename>.md`)
+     - Single / root project → use the project codename from `<manifest>` → `project.name` (e.g., `<codename>.md`)
      - Backend service / API component → `backend.md`
      - Frontend / web / UI component → `frontend.md`
      - Infrastructure, IaC, CI/CD, deployment → `devops.md`
@@ -21,7 +21,7 @@ argument-hint: <name> [paths-glob]
    - If the repo is a monorepo with named components (e.g., `apps/billing`, `services/auth`), prefer the component name as the rule name (`billing.md`, `auth.md`).
    - **Rule filenames match the domain used by skills/agents.** If the scope is unclear, ask the user before proceeding.
 
-2. **Check existing rules**: Read `intelligence/rules/` to detect overlapping scope — favor extending an existing rule over creating a new one.
+2. **Check existing rules**: Read `<umbrella>/rules/` to detect overlapping scope — favor extending an existing rule over creating a new one.
 
 3. **Determine scope**:
    - If paths glob provided — scoped rule with `paths:` frontmatter
@@ -34,7 +34,7 @@ argument-hint: <name> [paths-glob]
    - Build and test commands specific to this scope
    - Anti-patterns observed in code, each paired with the positive replacement that should adopt instead
 
-5. **Create rule**: Write `intelligence/rules/<name>.md`:
+5. **Create rule**: Write `<umbrella>/rules/<name>.md` (create the directory if it does not exist — the sources list already covers it):
    ```yaml
    ---
    paths:
@@ -49,6 +49,6 @@ argument-hint: <name> [paths-glob]
    - Examples come from the actual codebase — reference real files
    - Every REQUIRED / Invariant / Pattern is backed by observed code
 
-7. **Update config.yaml** if needed: Add source path to `sources.rules` if rule is in a new directory not yet listed.
+7. **Update `<manifest>` only when needed**: add the path to `sources.rules` only if the rule lives in a directory not already listed there — creating a pre-listed directory is enough.
 
 8. **Run `/intelligence-sync`** to distribute to all enabled IDE targets.