@ainova-systems/intelligence 0.11.0-rc.1 → 0.11.0-rc.11

package/cli/internal/convert-legacy.sh

@@ -0,0 +1,400 @@
+#!/bin/bash
+# Internal conversion from legacy Intelligence Sync to Intelligence CLI.
+# to an Intelligence project: root intelligence.yaml, .intelligence/ store,
+# intelligence.lock, no vendored engine.
+#
+# Transactional: STAGE everything next to the
+# project, VERIFY the staged state, then COMMIT in an order where every
+# destructive step happens only after a real sync of the new state reported
+# IS_STATUS=ok. Any earlier failure leaves the project untouched.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+dry_run=0 force=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --dry-run) dry_run=1 ;;
+        --force) force=1 ;;
+        *) die "unknown option '$1'" ;;
+    esac
+    shift || true
+done
+
+# ---- Preconditions (fail closed, nothing written) -------------------------
+detect_project
+case "$IP_MODE" in
+    legacy) ;;
+    cli) die "already an Intelligence project ($IP_ROOT/intelligence.yaml)" ;;
+    *) die "no legacy Intelligence Sync project found here — 'intelligence init' starts a fresh project" ;;
+esac
+root="$IP_ROOT"
+umbrella="$IP_UMBRELLA"
+module_dir="$IP_MODULE_DIR"
+config="$umbrella/config.yaml"
+module_rel="${module_dir#"$root"/}"
+umbrella_rel="${umbrella#"$root"/}"
+
+for existing in intelligence.yaml intelligence.lock .intelligence; do
+    if [ -e "$root/$existing" ] || [ -L "$root/$existing" ]; then
+        die "$existing already exists at the root — conflicting Intelligence CLI state; move it aside or restore the project before converting"
+    fi
+done
+if [ "$dry_run" -eq 0 ] && [ "$force" -eq 0 ]; then
+    if [ -n "$(git -C "$root" status --porcelain 2>/dev/null)" ]; then
+        die "working tree is not clean — commit or stash first (or --force); conversion produces a one-commit diff you can review and revert"
+    fi
+fi
+
+# `sync_version` belongs to the legacy Intelligence Sync format. Intelligence uses
+# `schema_version`, so conversion reads the legacy scalar explicitly.
+stamp="$(top_scalar "$config" "sync_version")"
+eng="$(bundled_engine_version)"
+[ -n "$stamp" ] && _ver_gt "$stamp" "$eng" && die "project schema $stamp is newer than this CLI's engine $eng — update the CLI first"
+
+# The legacy `packs:` block is the one Intelligence Sync shape conversion still reads, and the
+# engine no longer knows it — the reader lives here, with its only consumer.
+get_pack_field() {
+    get_nested_yaml_value "$1" "packs" "$2" "$3"
+}
+
+paths_overlap() {
+    case "$1" in "$2"|"$2"/*) return 0 ;; esac
+    case "$2" in "$1"|"$1"/*) return 0 ;; esac
+    return 1
+}
+
+validate_mirror_path() {
+    local pack="$1" mirror="$2" canon rel src src_canon src_rel target output protected mirror_phys
+    [ -n "$mirror" ] || return 0
+    case "$mirror" in
+        .|/*|*..*|*\\*|[A-Za-z]:*) die "pack '$pack' has unsafe mirror path '$mirror'" ;;
+    esac
+    canon="$(normalize_path "$root/$mirror")"
+    case "$canon" in "$root"/*) ;; *) die "pack '$pack' mirror escapes the repository: '$mirror'" ;; esac
+    rel="${canon#"$root"/}"
+
+    # A legacy mirror may live below the content directory (the normal location is
+    # intelligence/external/<pack>), but it must never own the directory itself,
+    # the vendored module, CLI state, authored sources, or generated outputs.
+    case "$umbrella_rel" in "$rel"|"$rel"/*) die "pack '$pack' mirror '$mirror' contains the legacy content directory" ;; esac
+    for protected in .git .intelligence "$module_rel"; do
+        paths_overlap "$rel" "$protected" && die "pack '$pack' mirror '$mirror' overlaps protected path '$protected'"
+    done
+    for section in rules agents skills; do
+        while IFS= read -r src; do
+            case "$src" in ""|git+*|@*) continue ;; esac
+            src_canon="$(normalize_path "$root/$src")"
+            case "$src_canon" in "$root"/*) src_rel="${src_canon#"$root"/}" ;; *) continue ;; esac
+            paths_overlap "$rel" "$src_rel" \
+                && die "pack '$pack' mirror '$mirror' overlaps configured source '$src'"
+        done < <(read_yaml_list "$config" "$section")
+    done
+    while IFS= read -r target; do
+        [ -n "$target" ] || continue
+        output="$(get_target_output "$config" "$target")"
+        [ -n "$output" ] || continue
+        case "$output" in /*|*..*) continue ;; esac
+        paths_overlap "$rel" "${output%/}" \
+            && die "pack '$pack' mirror '$mirror' overlaps target '$target' output '$output'"
+    done < <(read_yaml_keys "$config" "targets")
+
+    if [ -d "$canon" ]; then
+        mirror_phys="$(cd "$canon" && pwd -P)"
+        case "$mirror_phys" in "$root"|"$root"/*) ;; *) die "pack '$pack' mirror resolves outside the repository: '$mirror'" ;; esac
+        [ -f "$canon/.pack" ] || die "pack '$pack' mirror '$mirror' has no .pack ownership stamp — refusing to copy or delete project-owned content"
+    fi
+}
+
+# ---- Stage ----------------------------------------------------------------
+if [ "$dry_run" -eq 1 ]; then
+    stage="$(mktemp -d -t intelligence-migrate-XXXXXX 2>/dev/null || mktemp -d)"
+else
+    stage="$(mktemp -d "$root/.intelligence-migrate-stage.XXXXXX")"
+fi
+cleanup_stage() { rm -rf "$stage"; }
+trap cleanup_stage EXIT INT TERM
+mkdir -p "$stage/.intelligence/packages"
+
+# Intelligence carries no legacy migration chain: the archived Intelligence Sync
+# engine knows how to walk an old project forward. Conversion accepts only a
+# project already at the final legacy schema and names the exact remedy otherwise —
+# a remedy that keeps working indefinitely, because the archive stays at the
+# URL the project's own update.sh already clones.
+LEGACY_FINAL_SCHEMA="0.10.0"
+if [ -z "$stamp" ] || _ver_gt "$LEGACY_FINAL_SCHEMA" "$stamp"; then
+    echo "ERROR: project schema is ${stamp:-absent (pre-0.3.1)}, older than the final legacy Intelligence Sync schema $LEGACY_FINAL_SCHEMA." >&2
+    echo "       Bring it forward with its own engine first — that still works:" >&2
+    echo "         bash $module_rel/scripts/update.sh --yes" >&2
+    echo "       then re-run: intelligence init" >&2
+    exit 1
+fi
+
+echo "== staging =="
+# Engine content arrives as the @ainova-systems/sync package, seeded from the
+# bundle (fetch_package's guard — no network).
+sync_pkg_sha="$(fetch_package "$SYNC_PKG_URL" "v$eng" "$SYNC_PKG_PATH" "$stage/$SYNC_PKG_STORE")"
+
+# Legacy pack name -> Intelligence package name (@org/repo derived from the url), plus
+# per-pack source facts. Recorded as rows for the config rewrite and the lock.
+pack_rows="$stage/packs.rows"
+: > "$pack_rows"
+seen_names=" "
+seen_mirrors=" "
+while IFS= read -r pack; do
+    [ -n "$pack" ] || continue
+    url="$(get_pack_field "$config" "$pack" "url")"
+    ref="$(get_pack_field "$config" "$pack" "ref")"
+    mirror="$(get_pack_field "$config" "$pack" "mirror")"
+    [ -n "$url" ] || die "pack '$pack' has no url in config.yaml"
+    assert_safe_source_url "$url"
+    assert_safe_ref "$ref"
+    validate_mirror_path "$pack" "$mirror"
+    if [ -n "$mirror" ]; then
+        mirror_key="$(normalize_path "$root/$mirror")"
+        case "$seen_mirrors" in *" $mirror_key "*) die "pack '$pack' shares mirror '$mirror' with another pack" ;; esac
+        seen_mirrors="$seen_mirrors$mirror_key "
+    fi
+    base="${url%.git}"; base="${base%/}"
+    repo="$(basename "$base")"
+    org="$(basename "$(dirname "$base")")"
+    case "$org" in ""|*[!A-Za-z0-9._-]*) org="local" ;; esac
+    case "$repo" in ""|*[!A-Za-z0-9._-]*) repo="$(printf '%s' "$repo" | tr -c 'A-Za-z0-9._-' '-')" ;; esac
+    name="@$org/$repo"
+    assert_valid_pkg_name "$name"
+    # Two packs deriving the same @org/repo would overwrite one store dir and
+    # duplicate the lock key — fail closed, the user renames a source.
+    case "$seen_names" in
+        *" $name "*) die "packs '$pack' and another both derive package name '$name' — sources must map to distinct names" ;;
+    esac
+    seen_names="$seen_names $name "
+    printf '%s\n' "$pack$LOCK_SEP$name$LOCK_SEP$url$LOCK_SEP$ref$LOCK_SEP$mirror"
+done < <(read_yaml_keys "$config" "packs") >> "$pack_rows"
+
+# Stage the store: mirrored packs are COPIED from their mirrors (content the
+# repo already holds — the network is not consulted, and the mirror is not
+# touched); transient packs are fetched.
+lock_rows="$stage/lock.rows"
+: > "$lock_rows"
+while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
+    [ -n "$pack" ] || continue
+    dest="$stage/.intelligence/packages/$name"
+    sha=""
+    if [ -n "$mirror" ] && [ -d "$root/$mirror" ]; then
+        mkdir -p "$dest"
+        cp -R "$root/$mirror/." "$dest/"
+        if [ -f "$dest/.pack" ]; then
+            sha="$(awk -F= '$1 == "sha" {print $2; exit}' "$dest/.pack")"
+            rm -f "$dest/.pack"
+        fi
+        echo "  pack '$pack' -> $name (from mirror $mirror)"
+    else
+        sha="$(fetch_package "$url" "$ref" "" "$dest")"
+        echo "  pack '$pack' -> $name (fetched)"
+    fi
+    if [ -z "$sha" ] || [ "$sha" = "unknown" ]; then
+        sha="$(GIT_TERMINAL_PROMPT=0 git ls-remote -- "$url" "$ref" 2>/dev/null | awk '{print $1; exit}')"
+    fi
+    [ -n "$ref" ] || ref="HEAD"
+    printf '%s\037%s\037%s\037%s\037%s\037%s\n' \
+        "$name" "" "$url" "" "$ref" "$sha" >> "$lock_rows"
+done < "$pack_rows"
+
+# The manifest: config.yaml transformed line by line — comments and unknown
+# blocks survive verbatim; `sync_version` and `packs:` are dropped (restamped
+# / converted); sources entries are rewritten onto the store.
+manifest_stage="$stage/intelligence.yaml"
+rewrite_source_value() {
+    local v="$1" pack name rest
+    case "$v" in
+        "$module_rel"/rules|"$module_rel"/agents|"$module_rel"/skills)
+            printf '%s/%s' "$SYNC_PKG_STORE" "${v##*/}"
+            return 0 ;;
+        @*)
+            rest="${v#@}"
+            pack="${rest%%/*}"
+            while IFS="$LOCK_SEP" read -r p name _ _ _; do
+                if [ "$p" = "$pack" ]; then
+                    if [ "$rest" = "$pack" ]; then
+                        printf '.intelligence/packages/%s' "$name"
+                    else
+                        printf '.intelligence/packages/%s/%s' "$name" "${rest#*/}"
+                    fi
+                    return 0
+                fi
+            done < "$pack_rows"
+            ;;
+    esac
+    printf '%s' "$v"
+}
+in_packs=0 in_sources=0
+while IFS= read -r line || [ -n "$line" ]; do
+    line="${line%$'\r'}"
+    case "$line" in
+        sync_version:*) continue ;;
+        packs:*) in_packs=1; continue ;;
+        sources:*) in_sources=1; in_packs=0; echo "$line"; continue ;;
+        [!\ \#]*) in_packs=0; in_sources=0 ;;
+    esac
+    [ "$in_packs" -eq 1 ] && continue
+    if [ "$in_sources" -eq 1 ]; then
+        case "$line" in
+            *"- "*)
+                indent="${line%%-*}"
+                v="${line#*- }"
+                # A trailing inline comment survives the rewrite — split it
+                # off before touching quotes, or it would be mangled into the
+                # value.
+                trail=""
+                case "$v" in
+                    *[[:space:]]"#"*)
+                        trail=" #${v#*[[:space:]]#}"
+                        v="${v%%[[:space:]]#*}"
+                        ;;
+                esac
+                v="${v%"${v##*[![:space:]]}"}"
+                v="${v%\"}"; v="${v#\"}"; v="${v%\'}"; v="${v#\'}"
+                echo "$indent- \"$(rewrite_source_value "$v")\"$trail"
+                continue
+                ;;
+        esac
+    fi
+    echo "$line"
+done < "$config" > "$manifest_stage"
+stamp_schema_version "$manifest_stage" "$eng"
+
+# packages: requested pins only; resolved source details live in the lock.
+while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
+    [ -n "$pack" ] || continue
+    qmap_set "$manifest_stage" "packages" "$name" "ref" "${ref:-HEAD}"
+done < "$pack_rows"
+
+# The engine's own content rides along as a package, pinned to the engine.
+qmap_set "$manifest_stage" "packages" "$SYNC_PKG_NAME" "version" "$eng"
+printf '%s\037%s\037%s\037%s\037%s\037%s\n' \
+    "$SYNC_PKG_NAME" "$eng" "$SYNC_PKG_URL" "$SYNC_PKG_PATH" "v$eng" "$sync_pkg_sha" >> "$lock_rows"
+
+# ---- Verify ---------------------------------------------------------------
+echo "== verifying staged state =="
+fail=0
+for section in rules agents skills; do
+    while IFS= read -r src; do
+        [ -n "$src" ] || continue
+        case "$src" in
+            .intelligence/*) [ -d "$stage/$src" ] || { echo "  MISSING (staged): $src"; fail=1; } ;;
+            git+*|@*) echo "  UNCONVERTED source token: $src"; fail=1 ;;
+            *) [ -d "$root/$src" ] || echo "  NOTE: local source '$src' does not exist (kept — same as before)" ;;
+        esac
+    done < <(read_yaml_list "$manifest_stage" "$section")
+done
+target_keys() {
+    awk '
+        /^targets:[[:space:]]*$/ { in_targets=1; next }
+        in_targets && /^[^[:space:]#]/ { exit }
+        in_targets && /^  [A-Za-z_][A-Za-z0-9_]*:/ {
+            line=$0; sub(/^  /, "", line); sub(/:.*/, "", line); print line
+        }
+    ' "$1"
+}
+while IFS= read -r adapter; do
+    [ -n "$adapter" ] || continue
+    old_e="$(is_target_enabled "$config" "$adapter")"
+    new_e="$(is_target_enabled "$manifest_stage" "$adapter")"
+    [ "$old_e" = "$new_e" ] || { echo "  TARGET DRIFT: $adapter enabled '$old_e' -> '$new_e'"; fail=1; }
+    old_o="$(get_target_output "$config" "$adapter")"
+    new_o="$(get_target_output "$manifest_stage" "$adapter")"
+    [ "$old_o" = "$new_o" ] || { echo "  TARGET DRIFT: $adapter output '$old_o' -> '$new_o'"; fail=1; }
+done < <({ target_keys "$config"; target_keys "$manifest_stage"; } | sort -u)
+[ "$fail" -eq 0 ] || die "staged state failed verification — nothing changed"
+
+if [ "$dry_run" -eq 1 ]; then
+    echo ""
+    echo "== dry run — the project is untouched. Staged manifest: =="
+    cat "$manifest_stage"
+    echo ""
+    echo "Would: write intelligence.yaml + intelligence.lock, move the store in,"
+    echo "sync, then remove $module_rel/, config.yaml and the pack mirrors."
+    exit 0
+fi
+
+# ---- Commit ---------------------------------------------------------------
+echo "== committing =="
+# .gitignore is part of the transaction: rollback must leave it exactly as
+# found, absent included.
+gitignore_existed=0
+if [ -f "$root/.gitignore" ]; then
+    gitignore_existed=1
+    cp "$root/.gitignore" "$stage/gitignore.orig"
+fi
+commit_active=1
+rollback() {
+    [ "$commit_active" -eq 1 ] || return 0
+    commit_active=0
+    set +e
+    rm -rf "$root/.intelligence" "$root/intelligence.yaml" "$root/intelligence.lock"
+    if [ "$gitignore_existed" -eq 1 ]; then
+        cp "$stage/gitignore.orig" "$root/.gitignore"
+    else
+        rm -f "$root/.gitignore"
+    fi
+    rm -rf "$stage"
+    echo "rolled back — the vendored setup is untouched" >&2
+}
+rollback_on_exit() {
+    local rc=$?
+    rollback
+    exit "$rc"
+}
+# Every live write through verified sync is covered by rollback, including a
+# plain set -e/EXIT failure rather than only an explicit sync refusal.
+trap rollback_on_exit EXIT
+trap 'rollback; exit 130' INT TERM
+if [ ! -f "$root/.gitignore" ] || ! grep -q '^\.intelligence/' "$root/.gitignore"; then
+    {
+        [ -f "$root/.gitignore" ] && [ -n "$(tail -c 1 "$root/.gitignore" 2>/dev/null)" ] && echo ""
+        echo "# intelligence CLI package store (restored automatically by 'intelligence sync')"
+        echo ".intelligence/"
+    } >> "$root/.gitignore"
+fi
+mv "$stage/.intelligence" "$root/.intelligence"
+cp "$manifest_stage" "$root/intelligence.yaml"
+lock_write_from_tsv "$root/intelligence.lock" "$lock_rows"
+
+sync_out="$(cd "$root" && IS_SUPPRESS_CLI_NOTE=1 bash "$CLI_DIR/commands/sync.sh" 2>&1)" || {
+    echo "$sync_out"
+    die "sync of the converted state failed"
+}
+echo "$sync_out" | grep -q '^IS_STATUS=ok' || {
+    echo "$sync_out"
+    die "sync of the converted state did not report ok"
+}
+# Point of no return: the new state is verified. From here an interrupt must
+# NOT roll back (the old setup is being removed) — only clean the stage.
+commit_active=0
+trap cleanup_stage EXIT INT TERM
+
+# Only now is anything of the old setup removed — and config.yaml is kept as
+# a reviewable backup inside the store.
+mkdir -p "$root/.intelligence/backup"
+cp "$config" "$root/.intelligence/backup/config.yaml"
+while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
+    # Containment before deletion: a mirror value is config input, and rm -rf
+    # must never follow it out of the repository.
+    case "$mirror" in
+        ""|/*|*..*) [ -n "$mirror" ] && echo "  WARN: mirror '$mirror' not repo-contained — left in place" >&2; continue ;;
+    esac
+    if [ -d "$root/$mirror" ]; then
+        rm -rf "${root:?}/$mirror"
+        # An emptied legacy mirror parent (for example intelligence/external/) goes with it.
+        rmdir "$(dirname "$root/$mirror")" 2>/dev/null || true
+    fi
+done < "$pack_rows"
+rm -rf "$module_dir"
+rm -f "$config"
+# An emptied umbrella dir (config-only setups) is dropped; one with project
+# content stays.
+rmdir "$umbrella" 2>/dev/null || true
+
+echo ""
+echo "converted. Review the diff, then commit. The old config.yaml is kept at .intelligence/backup/config.yaml."
+echo "From now on: intelligence sync | package | update | status."
+echo "Next: ask your agent to run /intelligence-learn-from-repository to review the converted project context."

package/cli/{commands/add.sh → internal/package-add.sh}

@@ -1,15 +1,15 @@
 #!/bin/bash
-# intelligence add <spec> [--name @scope/name] [--no-sync]
+# Internal package add operation.
 #
 # Specs:
-#   @scope/name[@range]            resolved via registries / index / convention
-#   github:org/repo[#path]         direct from GitHub, no registry involved
-#   git+<url>[@ref][#path]         direct from any git host
+#   @scope/name[@range]            resolved ONLY through the manifest's trusted registries
+#   github:org/repo[#path]         explicit source: direct from GitHub, no registry involved
+#   git+<url>[@ref][#path]         explicit source: direct from any git host
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
 spec="${1:-}"
-[ -n "$spec" ] || die "usage: intelligence add <@scope/name[@range] | github:org/repo[#path] | git+<url>[@ref][#path]>"
+[ -n "$spec" ] || die "usage: intelligence package add <@scope/name[@range] | github:org/repo[#path] | git+<url>[@ref][#path]>"
 shift || true
 
 no_sync=0
@@ -23,7 +23,7 @@ while [ $# -gt 0 ]; do
     shift || true
 done
 
-require_v2
+require_cli_project
 manifest="$IP_ROOT/intelligence.yaml"
 lock="$IP_ROOT/intelligence.lock"
 
@@ -43,14 +43,15 @@ case "$spec" in
         rest="${spec#git+}"
         case "$rest" in *#*) path="${rest#*#}"; rest="${rest%%#*}" ;; esac
         # ref = the part after the last `@` in the post-scheme URL, unless it
-        # contains `/` (then it is a user@host, not a ref) — the engine's own
-        # git+ grammar.
+        # contains `/` or `:` — either marks a user@host part (scp-like
+        # `git@host:repo.git` included), not a ref. A branch name containing
+        # `/` cannot be expressed here; pin it via `ref:` in the manifest.
         base="${rest#*://}"
         case "$base" in
             *@*)
                 tail="${base##*@}"
                 case "$tail" in
-                    */*) ;;
+                    */*|*:*) ;;
                     *) ref="$tail"; rest="${rest%@"$tail"}" ;;
                 esac
                 ;;
@@ -78,9 +79,27 @@ assert_valid_pkg_name "$name"
 if [ "$mode" = "registry" ]; then
     resolve_package_source "$manifest" "$name"
     url="$RES_URL"; path="$RES_PATH"
+    if [ -z "$url" ]; then
+        echo "ERROR: no trusted registry declares '$name'." >&2
+        echo "  A name installs only through a registry this project added explicitly" >&2
+        echo "  ('intelligence registry list' shows them). Either add its registry:" >&2
+        echo "    intelligence registry add <registry-repo-url>" >&2
+        echo "  or install from an explicit source you name yourself:" >&2
+        echo "    intelligence package add github:org/repo   |   intelligence package add git+<url>[@ref][#path]" >&2
+        suggest_similar "$manifest" "$name"
+        exit 1
+    fi
     echo "  resolving $name via $RES_VIA -> $url${path:+ ($path)}"
 fi
 
+# The source must exist before anything else is attempted — never die
+# mid-pipeline with no message.
+if ! GIT_TERMINAL_PROMPT=0 git ls-remote -- "$url" >/dev/null 2>&1; then
+    echo "ERROR: no reachable repository at $url" >&2
+    echo "  Declared by ${RES_VIA:-the spec} — check the URL and your git access." >&2
+    exit 1
+fi
+
 # Pick the version: an explicit ref pins; otherwise the highest stable tag
 # matching the range (npm's behaviour, `^highest` becoming the requested range
 # when none was given).
@@ -98,6 +117,7 @@ if [ -z "$ref" ]; then
             die "'$name' has no stable version tags at $url — a registry package must be versioned; use github:/git+ with @<ref> to pin a branch or commit"
         fi
         echo "  NOTE: no version tags at $url — pinning the default branch head" >&2
+        ref="HEAD"
     fi
 fi
 
@@ -106,18 +126,16 @@ sha="$(fetch_package "$url" "${ref:-$resolved_tag}" "$path" "$IP_ROOT/$rel")"
 
 wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
 
-# Manifest entry: a registry package records its range; a direct one records
-# its source so resolution never has to guess it again.
-if [ "$mode" = "registry" ]; then
+# The manifest records requested intent only. The resolved source URL/path,
+# tag/ref and SHA live in the required lock. Re-adding a package is the
+# explicit operation for changing its trusted source.
+qmap_delete_key "$manifest" "packages" "$name"
+if [ -n "$ref" ]; then
+    qmap_set "$manifest" "packages" "$name" "ref" "$ref"
+elif [ -n "$requested" ]; then
     qmap_set "$manifest" "packages" "$name" "version" "$requested"
 else
-    qmap_set "$manifest" "packages" "$name" "url" "$url"
-    [ -n "$path" ] && qmap_set "$manifest" "packages" "$name" "path" "$path"
-    if [ -n "$ref" ]; then
-        qmap_set "$manifest" "packages" "$name" "ref" "$ref"
-    elif [ -n "$requested" ]; then
-        qmap_set "$manifest" "packages" "$name" "version" "$requested"
-    fi
+    die "internal: package '$name' has neither a requested version nor ref"
 fi
 
 lock_upsert "$lock" "$name" "$requested" "$url" "$path" "${ref:-$resolved_tag}" "$sha"

package/cli/{commands/list.sh → internal/package-list.sh}

@@ -1,9 +1,9 @@
 #!/bin/bash
-# intelligence list — packages with requested / locked / installed state.
+# Internal package list operation.
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
-require_v2
+require_cli_project
 manifest="$IP_ROOT/intelligence.yaml"
 lock="$IP_ROOT/intelligence.lock"
 
@@ -14,8 +14,13 @@ while IFS= read -r name; do
     range="$(qmap_field "$manifest" "packages" "$name" "version")"
     ref="$(qmap_field "$manifest" "packages" "$name" "ref")"
     resolved="$(qmap_field "$lock" "packages" "$name" "resolved")"
-    state="missing — run 'intelligence install'"
-    [ -d "$IP_ROOT/.intelligence/packages/$name" ] && state="installed"
+    if [ ! -f "$lock" ]; then
+        state="lock missing — restore committed intelligence.lock"
+    elif [ -d "$IP_ROOT/.intelligence/packages/$name" ]; then
+        state="installed"
+    else
+        state="store missing — run 'intelligence sync'"
+    fi
     printf '%s  %s  locked:%s  %s\n' \
         "$name" \
         "${ref:+ref:$ref}${ref:-${range:-*}}" \
@@ -24,5 +29,5 @@ while IFS= read -r name; do
 done < <(qmap_keys "$manifest" "packages")
 
 if [ "$count" -eq 0 ]; then
-    echo "No packages. Add one: intelligence add @ainova-systems/core"
+    echo "No packages. Add one: intelligence package add @ainova-systems/core"
 fi

package/cli/{commands/remove.sh → internal/package-remove.sh}

@@ -1,20 +1,32 @@
 #!/bin/bash
-# intelligence remove <@scope/name> [--no-sync]
+# Internal package remove operation.
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
 name="${1:-}"
-[ -n "$name" ] || die "usage: intelligence remove <@scope/name>"
+[ -n "$name" ] || die "usage: intelligence package remove <@scope/name>"
 shift || true
-no_sync=0
+no_sync=0 force=0
 for a in "$@"; do
     case "$a" in
         --no-sync) no_sync=1 ;;
+        --force) force=1 ;;
         *) die "unknown option '$a'" ;;
     esac
 done
 
-require_v2
+require_cli_project
+
+# Removing the engine-content package guts the outputs (meta-skills, the
+# authoring rule, both engine agents disappear) while everything still
+# reports ok — legal, but never by accident.
+if [ "$name" = "$SYNC_PKG_NAME" ] && [ "$force" -eq 0 ]; then
+    echo "ERROR: $SYNC_PKG_NAME is the engine's own content — removing it drops every" >&2
+    echo "  intelligence-* meta-skill, the authoring rule and the engine agents from" >&2
+    echo "  the outputs. The sync engine itself keeps working (it ships with the CLI)." >&2
+    echo "  If that is what you want: intelligence package remove $SYNC_PKG_NAME --force" >&2
+    exit 1
+fi
 assert_valid_pkg_name "$name"
 manifest="$IP_ROOT/intelligence.yaml"
 lock="$IP_ROOT/intelligence.lock"

package/cli/internal/package-search.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Internal package search operation: what the registries offer and what this project
+# already has. The catalogue view `list` deliberately is not: `list` answers
+# "what does this project depend on", `search` answers "what could it".
+#
+# Sources, in resolution order (a name found earlier wins, exactly as `add`
+# resolves it): the manifest's trusted registries, in order.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+term="${1:-}"
+
+detect_project
+manifest=""
+[ "$IP_MODE" = "cli" ] && manifest="$IP_ROOT/intelligence.yaml"
+
+# State of one package name in this project: installed / declared / available.
+pkg_state() {
+    local name="$1"
+    [ -n "$manifest" ] || { printf 'available'; return 0; }
+    local declared=0 k
+    while IFS= read -r k; do
+        [ "$k" = "$name" ] && declared=1
+    done < <(qmap_keys "$manifest" "packages")
+    if [ "$declared" -eq 0 ]; then
+        printf 'available'
+    elif [ -d "$IP_ROOT/.intelligence/packages/$name" ]; then
+        printf 'installed %s' "$(qmap_field "$IP_ROOT/intelligence.lock" "packages" "$name" "resolved")"
+    else
+        printf 'declared (run sync)'
+    fi
+}
+
+seen=" "
+rows=0
+# emit_index <index-file> <origin-label>
+# Registries are consulted in trust order; the first to declare a name wins,
+# so a name already seen is not repeated (that IS the resolution order).
+emit_index() {
+    local index="$1" origin="$2" name desc state
+    [ -n "$index" ] && [ -f "$index" ] || return 0
+    while IFS= read -r name; do
+        [ -n "$name" ] || continue
+        case "$seen" in *" $name "*) continue ;; esac
+        if [ -n "$term" ]; then
+            desc="$(qmap_field "$index" "packages" "$name" "description")"
+            case "$name$desc" in
+                *"$term"*) ;;
+                *) continue ;;
+            esac
+        fi
+        seen="$seen$name "
+        desc="$(qmap_field "$index" "packages" "$name" "description")"
+        state="$(pkg_state "$name")"
+        printf '%-34s %-22s %s\n' "$name" "$state" "${desc:-$(qmap_field "$index" "packages" "$name" "url")}"
+        [ "$origin" = "bundled" ] || printf '%-34s %s\n' "" "  via $origin"
+        rows=$((rows + 1))
+    done < <(qmap_keys "$index" "packages")
+}
+
+if [ -n "$manifest" ]; then
+    while IFS= read -r url; do
+        [ -n "$url" ] || continue
+        index="$(_fetch_index "${url#git+}")"
+        if [ -z "$index" ]; then
+            echo "  WARN: registry unreachable or missing index.yaml: $url" >&2
+            continue
+        fi
+        emit_index "$index" "$url"
+    done < <(registries_list "$manifest")
+fi
+if [ "$rows" -eq 0 ]; then
+    if [ -n "$term" ]; then
+        echo "Nothing matching '$term' in this project's trusted registries."
+    else
+        echo "No trusted registries (or they offer nothing) — intelligence registry add <repo-url>."
+    fi
+    echo "Explicit installs need no registry: intelligence package add github:org/repo"
+    exit 0
+fi
+
+echo ""
+echo "add one: intelligence package add <name>   |   private registry: intelligence registry add <repo-url>"