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

package/cli/{commands/migrate.sh → internal/migrate-v1.sh}

@@ -1,9 +1,9 @@
 #!/bin/bash
-# intelligence migrate [--dry-run] [--force] — convert a vendored (v1) setup
+# Internal v1-to-v2 migration operation.
 # to the CLI setup: root intelligence.yaml, .intelligence/ store,
 # intelligence.lock, no vendored engine.
 #
-# Transactional in the migrations.sh spirit: STAGE everything next to the
+# 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.
@@ -24,7 +24,7 @@ done
 detect_project
 case "$IP_MODE" in
     legacy) ;;
-    v2) die "already on the CLI setup ($IP_ROOT/intelligence.yaml)" ;;
+    v2) die "already on the v2 setup ($IP_ROOT/intelligence.yaml)" ;;
     *) die "no vendored setup found here — 'intelligence init' starts a fresh project" ;;
 esac
 root="$IP_ROOT"
@@ -32,41 +32,101 @@ umbrella="$IP_UMBRELLA"
 module_dir="$IP_MODULE_DIR"
 config="$umbrella/config.yaml"
 module_rel="${module_dir#"$root"/}"
+umbrella_rel="${umbrella#"$root"/}"
 
-[ -f "$root/intelligence.yaml" ] && die "intelligence.yaml already exists at the root — half-migrated state; resolve it manually"
+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 v2 state; move it aside or restore the project before migrating"
+    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); migrate wants a one-commit diff you can review and revert"
     fi
 fi
 
-stamp="$(read_engine_stamp "$config")"
+# `sync_version` belongs to the archived v1 format. The v2 contract 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 v1 `packs:` block is the one v1 shape migrate still has to read, 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 v1 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 v1 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 ----------------------------------------------------------------
-stage="$root/.intelligence-migrate-stage.$$"
-[ "$dry_run" -eq 1 ] && stage="$(mktemp -d -t intelligence-migrate-XXXXXX 2>/dev/null || mktemp -d)"
+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"
 
-# A schema gap is closed by the engine's own proven chain before conversion.
-# Dry-run must preview the SAME pipeline, so it runs the chain too — against
-# a staged copy of the umbrella, leaving the project untouched.
-if [ -z "$stamp" ] || _ver_gt "$eng" "$stamp"; then
-    if [ "$dry_run" -eq 1 ]; then
-        echo "== applying the engine migration chain ($stamp -> $eng) to a staged copy =="
-        cp -R "$umbrella" "$stage/umbrella"
-        run_migrations "$stage/umbrella" "$(basename "$module_dir")" "" > "$stage/chain.log" 2>&1 \
-            || { tail -5 "$stage/chain.log" >&2; die "engine migration chain failed in the staged copy — a real migrate would fail the same way"; }
-        stamp_version "$stage/umbrella/config.yaml" "$eng"
-        config="$stage/umbrella/config.yaml"
-    else
-        echo "== applying the engine migration chain ($stamp -> $eng) =="
-        run_migrations "$umbrella" "$(basename "$module_dir")" "" || die "engine migration chain failed (IS_STATUS above) — nothing converted"
-        stamp_version "$config" "$eng"
-    fi
+# v2 carries no v1 migration chain: v1 is archived, and the archived engine is
+# what knows how to walk an old project forward. So migrate accepts only a
+# project already at the final v1 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.
+V1_FINAL_SCHEMA="0.10.0"
+if [ -z "$stamp" ] || _ver_gt "$V1_FINAL_SCHEMA" "$stamp"; then
+    echo "ERROR: project schema is ${stamp:-absent (pre-0.3.1)}, older than the final v1 schema $V1_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 =="
@@ -78,12 +138,22 @@ sync_pkg_sha="$(fetch_package "$SYNC_PKG_URL" "v$eng" "$SYNC_PKG_PATH" "$stage/$
 # 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")")"
@@ -91,6 +161,12 @@ while IFS= read -r pack; do
     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"
 
@@ -116,7 +192,7 @@ while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
         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}')"
+        sha="$(GIT_TERMINAL_PROMPT=0 git ls-remote -- "$url" "$ref" 2>/dev/null | awk '{print $1; exit}')"
     fi
     printf '%s\037%s\037%s\037%s\037%s\037%s\n' \
         "$name" "" "$url" "" "$ref" "$sha" >> "$lock_rows"
@@ -164,15 +240,26 @@ while IFS= read -r line || [ -n "$line" ]; do
             *"- "*)
                 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")\""
+                echo "$indent- \"$(rewrite_source_value "$v")\"$trail"
                 continue
                 ;;
         esac
     fi
     echo "$line"
 done < "$config" > "$manifest_stage"
-stamp_version "$manifest_stage" "$eng"
+stamp_schema_version "$manifest_stage" "$eng"
 
 # packages: entries (pin preserved — no invented ranges).
 while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
@@ -201,14 +288,24 @@ for section in rules agents skills; do
         esac
     done < <(read_yaml_list "$manifest_stage" "$section")
 done
-for adapter in agents claude cursor copilot codex pi opencode; do
+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
+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
@@ -230,45 +327,66 @@ if [ -f "$root/.gitignore" ]; then
     gitignore_existed=1
     cp "$root/.gitignore" "$stage/gitignore.orig"
 fi
-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 by 'intelligence install')"
-        echo ".intelligence/"
-    } >> "$root/.gitignore"
-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"
-    rollback
-    die "sync of the migrated state failed — rolled back"
+    die "sync of the migrated state failed"
 }
 echo "$sync_out" | grep -q '^IS_STATUS=ok' || {
     echo "$sync_out"
-    rollback
-    die "sync of the migrated state did not report ok — rolled back"
+    die "sync of the migrated 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
-    if [ -n "$mirror" ] && [ -d "$root/$mirror" ]; then
+    # 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 mirror parent (e.g. <umbrella>/external/) goes with it.
+        # An emptied v1 mirror parent (for example intelligence/external/) goes with it.
         rmdir "$(dirname "$root/$mirror")" 2>/dev/null || true
     fi
 done < "$pack_rows"
@@ -280,4 +398,5 @@ rmdir "$umbrella" 2>/dev/null || true
 
 echo ""
 echo "migrated. Review the diff, then commit. The old config.yaml is kept at .intelligence/backup/config.yaml."
-echo "From now on: intelligence sync | add | install | doctor."
+echo "From now on: intelligence sync | package | update | status."
+echo "Next: ask your agent to run /intelligence-learn-from-repository to review the migrated 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
@@ -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
                 ;;
@@ -84,7 +85,7 @@ if [ "$mode" = "registry" ]; then
         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 add github:org/repo   |   intelligence add git+<url>[@ref][#path]" >&2
+        echo "    intelligence package add github:org/repo   |   intelligence package add git+<url>[@ref][#path]" >&2
         suggest_similar "$manifest" "$name"
         exit 1
     fi
@@ -93,7 +94,7 @@ 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
+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

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

@@ -1,5 +1,5 @@
 #!/bin/bash
-# intelligence list — packages with requested / locked / installed state.
+# Internal package list operation.
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
@@ -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,10 +1,10 @@
 #!/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 force=0
 for a in "$@"; do
@@ -24,7 +24,7 @@ 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 remove $SYNC_PKG_NAME --force" >&2
+    echo "  If that is what you want: intelligence package remove $SYNC_PKG_NAME --force" >&2
     exit 1
 fi
 assert_valid_pkg_name "$name"

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

@@ -1,5 +1,5 @@
 #!/bin/bash
-# intelligence search [term] — what the registries offer, and what this project
+# 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".
 #
@@ -27,7 +27,7 @@ pkg_state() {
     elif [ -d "$IP_ROOT/.intelligence/packages/$name" ]; then
         printf 'installed %s' "$(qmap_field "$IP_ROOT/intelligence.lock" "packages" "$name" "resolved")"
     else
-        printf 'declared (run install)'
+        printf 'declared (run sync)'
     fi
 }
 
@@ -75,9 +75,9 @@ if [ "$rows" -eq 0 ]; then
     else
         echo "No trusted registries (or they offer nothing) — intelligence registry add <repo-url>."
     fi
-    echo "Explicit installs need no registry: intelligence add github:org/repo"
+    echo "Explicit installs need no registry: intelligence package add github:org/repo"
     exit 0
 fi
 
 echo ""
-echo "add one: intelligence add <name>   |   private registry: intelligence registry add <repo-url>"
+echo "add one: intelligence package add <name>   |   private registry: intelligence registry add <repo-url>"

package/cli/internal/package-update.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# Internal package range update operation.
+#
+# Re-resolve version ranges against the remotes and rewrite the lock. Pinned
+# packages (`ref:`) never move here — repin by editing the manifest or
+# re-adding. `update <name>` limits the pass to one package.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+only="" no_sync=0 preview=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --no-sync) no_sync=1 ;;
+        --preview) preview=1 ;;
+        @*) only="$1" ;;
+        *) die "unknown argument '$1'" ;;
+    esac
+    shift || true
+done
+
+require_v2
+manifest="$IP_ROOT/intelligence.yaml"
+lock="$IP_ROOT/intelligence.lock"
+
+moved=0 found=0
+while IFS= read -r name; do
+    [ -n "$name" ] || continue
+    # Manifest keys are untrusted input on their way into store paths.
+    assert_valid_pkg_name "$name"
+    [ -n "$only" ] && [ "$name" != "$only" ] && continue
+    # A named package that exists is "found" whatever happens next — a skip
+    # message followed by "not in the manifest" would contradict itself.
+    found=1
+    if [ "$name" = "$SYNC_PKG_NAME" ]; then
+        echo "  $name: engine content follows the installed CLI — skipped"
+        continue
+    fi
+    ref="$(qmap_field "$manifest" "packages" "$name" "ref")"
+    [ -n "$ref" ] && { echo "  $name: pinned to ref '$ref' — skipped"; continue; }
+    range="$(qmap_field "$manifest" "packages" "$name" "version")"
+    # An exact version is a pin, same as ref: — update never moves pins.
+    if [ -n "$range" ] && semver_is_stable "$range"; then
+        echo "  $name: pinned to $range — edit the manifest to move it"
+        continue
+    fi
+    url="$(qmap_field "$manifest" "packages" "$name" "url")"
+    path="$(qmap_field "$manifest" "packages" "$name" "path")"
+    if [ -z "$url" ]; then
+        resolve_package_source "$manifest" "$name"
+        url="$RES_URL"; path="$RES_PATH"
+    fi
+    picked="$(list_remote_versions "$url" | semver_pick_highest "$range")"
+    [ -n "$picked" ] || { echo "  $name: nothing satisfies '${range:-*}' at $url" >&2; continue; }
+    read -r tag _ <<< "$(remote_tag_for_version "$url" "$picked")"
+    current="$(qmap_field "$lock" "packages" "$name" "resolved")"
+    cur_url="$(qmap_field "$lock" "packages" "$name" "url")"
+    cur_path="$(qmap_field "$lock" "packages" "$name" "path")"
+    # Same tag is not enough: a registry may re-point a name's source while
+    # keeping the version — the move doctor warns about must be actionable
+    # here, so url/path changes refetch too.
+    if [ "$tag" = "$current" ] && [ "$url" = "$cur_url" ] && [ "$path" = "$cur_path" ]; then
+        echo "  $name: ${current:-<none>} (up to date)"
+        continue
+    fi
+    if [ "$preview" -eq 1 ]; then
+        echo "  $name: ${current:-<none>} -> $tag"
+        moved=$((moved + 1))
+        continue
+    fi
+    rel=".intelligence/packages/$name"
+    # Fetch into staging FIRST: a failed clone must leave the current install
+    # fully wired and intact. Only after success is the old shape unwired
+    # (the new version may have dropped a section dir), the store swapped,
+    # and the new shape wired.
+    staging="$IP_ROOT/.intelligence/.staging-$$"
+    rm -rf "$staging"
+    sha="$(fetch_package "$url" "$tag" "$path" "$staging")"
+    unwire_package_sources "$manifest" "$rel"
+    rm -rf "${IP_ROOT:?}/$rel"
+    mkdir -p "$(dirname "$IP_ROOT/$rel")"
+    mv "$staging" "$IP_ROOT/$rel"
+    wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
+    lock_upsert "$lock" "$name" "$range" "$url" "$path" "$tag" "$sha"
+    echo "  $name: ${current:-<none>} -> $tag"
+    moved=$((moved + 1))
+done < <(qmap_keys "$manifest" "packages")
+
+[ -n "$only" ] && [ "$found" -eq 0 ] && die "package '$only' is not in the manifest"
+if [ "$preview" -eq 1 ]; then
+    echo "updates available: $moved package(s)"
+else
+    echo "updated: $moved package(s)"
+fi
+
+if [ "$preview" -eq 0 ] && [ "$moved" -gt 0 ] && [ "$no_sync" -eq 0 ]; then
+    exec bash "$CLI_DIR/commands/sync.sh"
+fi

package/cli/{commands/install.sh → internal/restore.sh}

@@ -1,5 +1,5 @@
 #!/bin/bash
-# intelligence install [--frozen] [--force] [--no-sync]
+# Internal locked-store restore operation.
 #
 # Restore .intelligence/ from intelligence.lock — the fresh-clone command.
 # --frozen additionally refuses any manifest/lock divergence (CI mode) and
@@ -30,7 +30,7 @@ if [ "$frozen" -eq 1 ]; then
     while IFS= read -r name; do
         [ -n "$name" ] || continue
         [ -n "$(qmap_field "$lock" "packages" "$name" "url")" ] \
-            || die "--frozen: $name is in the manifest but not in intelligence.lock"
+            || die "locked restore: $name is in the manifest but not in intelligence.lock"
         m_ver="$(qmap_field "$manifest" "packages" "$name" "version")"
         m_ref="$(qmap_field "$manifest" "packages" "$name" "ref")"
         m_url="$(qmap_field "$manifest" "packages" "$name" "url")"
@@ -40,7 +40,7 @@ if [ "$frozen" -eq 1 ]; then
         l_url="$(qmap_field "$lock" "packages" "$name" "url")"
         l_path="$(qmap_field "$lock" "packages" "$name" "path")"
         [ -z "$m_ver" ] || [ "$m_ver" = "$l_req" ] \
-            || die "--frozen: $name requests '$m_ver' but the lock recorded '$l_req' — run 'intelligence install' without --frozen"
+            || die "locked restore: $name requests '$m_ver' but the lock recorded '$l_req' — reconcile the manifest and lock"
         [ -z "$m_ref" ] || [ "$m_ref" = "$l_res" ] \
             || die "--frozen: $name pins ref '$m_ref' but the lock resolved '$l_res'"
         [ -z "$m_url" ] || [ "$m_url" = "$l_url" ] \
@@ -63,6 +63,7 @@ fi
 missing=""
 while IFS= read -r name; do
     [ -n "$name" ] || continue
+    assert_valid_pkg_name "$name"
     if [ ! -f "$lock" ] || [ -z "$(qmap_field "$lock" "packages" "$name" "url")" ]; then
         missing="$missing $name"
     fi
@@ -101,8 +102,14 @@ fi
 if [ -f "$lock" ]; then
     while IFS="$LOCK_SEP" read -r name requested url path resolved sha; do
         [ -n "$name" ] || continue
+        # The lock arrives with a cloned repo — its keys are untrusted input
+        # on their way into rm -rf paths, and its urls into git argv.
+        assert_valid_pkg_name "$name"
         rel=".intelligence/packages/$name"
-        if [ -d "$IP_ROOT/$rel" ] && [ "$force" -eq 0 ]; then
+        # --frozen never trusts what is already on disk: a pre-existing
+        # (possibly substituted) store dir would otherwise be synced with no
+        # sha verification at all.
+        if [ -d "$IP_ROOT/$rel" ] && [ "$force" -eq 0 ] && [ "$frozen" -eq 0 ]; then
             continue
         fi
         # Fetch into staging and commit to the store only after the integrity