@ainova-systems/intelligence 0.12.1 → 0.14.0

package/README.md

@@ -34,7 +34,8 @@ intelligence sync
 |---|---|
 | `intelligence init [--preview\|--apply]` | Create, convert, restore or align a project |
 | `intelligence sync [adapter]` | Restore locked content if needed, then render all or one enabled adapter |
-| `intelligence update [@scope/name] [--preview\|--apply]` | Plan or apply project and ranged-package updates |
+| `intelligence update [@scope/name] [--latest] [--preview\|--apply]` | Plan or apply project and ranged-package updates; `--latest` crosses one package's range |
+| `intelligence upgrade [--next] [--preview\|--apply]` | Replace the installed CLI with the newest version on its npm channel |
 | `intelligence package add\|remove\|list\|search` | Manage versioned Intelligence Packages |
 | `intelligence adapter list\|create\|enable\|disable\|remove` | Manage render adapters |
 | `intelligence status [--check]` | Inspect project state and consistency |

package/bin/intelligence.js

@@ -47,10 +47,19 @@ function findBash() {
 
 const cli = path.join(__dirname, '..', 'cli', 'intelligence').replace(/\\/g, '/');
 const pkg = require(path.join(__dirname, '..', 'package.json'));
+const binName = Object.keys(pkg.bin)[0];
 
 const result = spawnSync(findBash(), [cli].concat(process.argv.slice(2)), {
   stdio: 'inherit',
-  env: Object.assign({}, process.env, { INTELLIGENCE_NPM_VERSION: pkg.version }),
+  // What npm installed, for `update` (channel check) and `upgrade` (replace
+  // exactly this package): its version and name, the command npm linked as
+  // its shim, and this launcher's path inside the package.
+  env: Object.assign({}, process.env, {
+    INTELLIGENCE_NPM_VERSION: pkg.version,
+    INTELLIGENCE_NPM_PACKAGE: pkg.name,
+    INTELLIGENCE_NPM_BIN: binName,
+    INTELLIGENCE_NPM_LAUNCHER: pkg.bin[binName],
+  }),
 });
 if (result.error) {
   console.error('intelligence: failed to launch bash: ' + result.error.message);

package/cli/commands/update.sh

@@ -2,22 +2,28 @@
 # intelligence update [@scope/name] [--preview|--apply]
 #
 # One update surface: show the installed-CLI/project/package plan, then either
-# stop, ask interactively, or apply without a prompt. Updating the global npm
-# installation remains an explicit package-manager operation.
+# stop, ask interactively, or apply without a prompt. Replacing the global npm
+# installation is `intelligence upgrade`, which the plan names; it never
+# happens inside a project command.
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
-only="" mode="ask" preview_seen=0 apply_seen=0
+only="" mode="ask" preview_seen=0 apply_seen=0 latest=0
 while [ $# -gt 0 ]; do
     case "$1" in
         --preview) preview_seen=1; mode="preview" ;;
         --apply) apply_seen=1; mode="apply" ;;
+        --latest) latest=1 ;;
         @*) [ -z "$only" ] || die "only one package may be selected"; only="$1" ;;
-        *) die "usage: intelligence update [@scope/name] [--preview|--apply]" ;;
+        *) die "usage: intelligence update [@scope/name] [--latest] [--preview|--apply]" ;;
     esac
     shift
 done
 [ "$preview_seen" -eq 0 ] || [ "$apply_seen" -eq 0 ] || die "choose either --preview or --apply"
+# Crossing a range is one package's decision, and SemVer marks the boundary as
+# the place a changelog has to be read.
+[ "$latest" -eq 0 ] || [ -n "$only" ] \
+    || die "--latest needs the package to move: intelligence update @scope/name --latest"
 
 require_cli_project
 manifest="$IP_ROOT/intelligence.yaml"
@@ -30,18 +36,27 @@ project_change=0
 echo "Update plan"
 echo ""
 echo "CLI:"
-if [ -n "${INTELLIGENCE_NPM_VERSION:-}" ] && [ "${IS_SKIP_NPM_CHECK:-0}" != "1" ] && command -v npm >/dev/null 2>&1; then
-    channel="latest"
-    case "$INTELLIGENCE_NPM_VERSION" in *-*) channel="next" ;; esac
-    available="$(npm view "@ainova-systems/intelligence" "dist-tags.$channel" 2>/dev/null || true)"
-    if [ -z "$available" ]; then
-        echo "  installed: $INTELLIGENCE_NPM_VERSION; registry check unavailable"
-    elif [ "$available" = "$INTELLIGENCE_NPM_VERSION" ]; then
-        echo "  $INTELLIGENCE_NPM_VERSION (up to date on npm $channel)"
+if [ -n "${INTELLIGENCE_NPM_VERSION:-}" ] && [ -n "${INTELLIGENCE_NPM_PACKAGE:-}" ] \
+    && [ "${IS_SKIP_NPM_CHECK:-0}" != "1" ] && command -v npm >/dev/null 2>&1; then
+    channel="$(npm_channel_for "$INTELLIGENCE_NPM_VERSION")"
+    # Ask the way `upgrade` will install: in global mode at this tree's own
+    # prefix when npm made it, so the plan and the install read one config.
+    cli_install_classify "$(cd "$CLI_DIR/.." && pwd -P)" "$INTELLIGENCE_NPM_PACKAGE" "${INTELLIGENCE_NPM_BIN:-}"
+    npm_prefix=""
+    [ "$CLI_INSTALL_KIND" != "npm" ] || npm_prefix="$(native_path "$CLI_INSTALL_PREFIX")"
+    # An empty or non-version answer is "not checked", never a comparison.
+    if available="$(cli_registry_version "$INTELLIGENCE_NPM_PACKAGE" "$channel" "$npm_prefix")"; then
+        case "$(semver_cmp_full "$available" "$INTELLIGENCE_NPM_VERSION")" in
+            1)
+                echo "  $INTELLIGENCE_NPM_VERSION -> $available (npm $channel)"
+                echo "  run: intelligence upgrade"
+                echo "  then rerun: intelligence update --apply"
+                ;;
+            0) echo "  $INTELLIGENCE_NPM_VERSION (up to date on npm $channel)" ;;
+            *) echo "  $INTELLIGENCE_NPM_VERSION (ahead of npm $channel $available)" ;;
+        esac
     else
-        echo "  $INTELLIGENCE_NPM_VERSION -> $available (npm $channel)"
-        echo "  run: npm install -g @ainova-systems/intelligence@$channel"
-        echo "  then rerun: intelligence update --apply"
+        echo "  installed: $INTELLIGENCE_NPM_VERSION; registry check unavailable"
     fi
 else
     echo "  source checkout/registry check skipped; engine $eng"
@@ -50,7 +65,7 @@ fi
 echo ""
 echo "Project:"
 if project_stamped_ahead "$IP_ROOT"; then
-    echo "  schema $stamp is ahead of engine $eng — left as is; update the CLI to align it"
+    echo "  schema $stamp is ahead of engine $eng — left as is; update the CLI to align it: intelligence upgrade (--next when the stamp came from a prerelease line)"
 elif project_needs_upgrade "$IP_ROOT"; then
     echo "  lifecycle alignment required (stamp ${stamp:-unstamped}, engine $eng)"
     project_change=1
@@ -64,6 +79,7 @@ fi
 
 pkg_args=(--preview)
 [ -z "$only" ] || pkg_args+=("$only")
+[ "$latest" -eq 0 ] || pkg_args+=(--latest)
 pkg_plan="$(bash "$CLI_DIR/internal/package-update.sh" "${pkg_args[@]}")"
 echo ""
 echo "Packages:"
@@ -92,5 +108,6 @@ fi
 ensure_project_current "$IP_ROOT"
 apply_args=(--no-sync)
 [ -z "$only" ] || apply_args+=("$only")
+[ "$latest" -eq 0 ] || apply_args+=(--latest)
 bash "$CLI_DIR/internal/package-update.sh" "${apply_args[@]}"
 exec bash "$CLI_DIR/commands/sync.sh"

package/cli/commands/upgrade.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# intelligence upgrade [--next] [--preview|--apply]
+#
+# Replace the installed CLI with the newest version on its npm channel:
+# `next` when the running version is a prerelease or --next is given,
+# `latest` otherwise. `update` plans this step and points here; this is the
+# one command that writes to an npm prefix, and it never reads or writes a
+# project.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+mode="ask" preview_seen=0 apply_seen=0 channel=""
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --preview) preview_seen=1; mode="preview" ;;
+        --apply) apply_seen=1; mode="apply" ;;
+        --next) channel="next" ;;
+        *) die "usage: intelligence upgrade [--next] [--preview|--apply]" ;;
+    esac
+    shift
+done
+[ "$preview_seen" -eq 0 ] || [ "$apply_seen" -eq 0 ] || die "choose either --preview or --apply"
+
+pkg_dir="$(cd "$CLI_DIR/.." && pwd -P)"
+installed="${INTELLIGENCE_NPM_VERSION:-}"
+pkg="${INTELLIGENCE_NPM_PACKAGE:-}"
+bin="${INTELLIGENCE_NPM_BIN:-}"
+# All of it comes from the npm launcher; `bash cli/intelligence` in a checkout has none.
+[ -n "$installed" ] && [ -n "$pkg" ] && [ -n "$bin" ] && [ -n "${INTELLIGENCE_NPM_LAUNCHER:-}" ] \
+    || die "this CLI runs from a source checkout ($pkg_dir), not an npm installation — pull the repository instead"
+command -v npm >/dev/null 2>&1 || die "npm is not on PATH — it installed this CLI and is needed to replace it"
+[ -n "$channel" ] || channel="$(npm_channel_for "$installed")"
+
+# Where this tree lives is decided locally, before any network: a tree npm
+# did not make is refused whatever the registry would say. The hint names
+# the exact version when the registry answers and the channel otherwise.
+cli_install_classify "$pkg_dir" "$pkg" "$bin"
+if [ "$CLI_INSTALL_KIND" != "npm" ]; then
+    available="$(cli_registry_version "$pkg" "$channel" || true)"
+    die "this CLI ($pkg_dir) is not an npm global installation — $(cli_install_hint "$CLI_INSTALL_KIND" "$pkg" "${available:-$channel}")"
+fi
+prefix="$(native_path "$CLI_INSTALL_PREFIX")"
+launcher="$(native_path "$pkg_dir/$INTELLIGENCE_NPM_LAUNCHER")"
+
+available="$(cli_registry_version "$pkg" "$channel" "$prefix")" \
+    || die "npm could not report a version for $pkg dist-tag $channel — check the network or the registry and retry"
+
+case "$(semver_cmp_full "$available" "$installed")" in
+    0)
+        echo "CLI $installed is up to date (npm $channel)"
+        exit 0
+        ;;
+    -1)
+        # Never a downgrade: a channel moved back on purpose is a decision
+        # the user takes by hand, with the command that does it.
+        echo "CLI $installed is newer than npm $channel ($available); nothing to do"
+        echo "  to move back deliberately: npm install -g --prefix $(quote_for_shell "$prefix") $pkg@$available"
+        exit 0
+        ;;
+esac
+
+echo "CLI upgrade: $installed -> $available (npm $channel)"
+echo "  npm install -g --prefix $(quote_for_shell "$prefix") $pkg@$available"
+[ "$mode" != "preview" ] || exit 0
+if [ "$mode" = "ask" ]; then
+    [ -t 0 ] || die "upgrade requires confirmation — rerun with --preview or --apply"
+    printf '\nInstall %s? [Y/n] ' "$available"
+    read -r answer
+    case "$answer" in
+        ""|y|Y|yes|YES) ;;
+        *) echo "upgrade cancelled"; exit 0 ;;
+    esac
+fi
+echo ""
+
+# npm rewrites the directory this script lives in, and Windows refuses to
+# delete a file another process still holds open. `bash -c` parses its whole
+# program before running it, so the fresh shell reads nothing from the
+# package while npm replaces it, and exec leaves no old process behind.
+# The version installed is the one the plan showed, never a moving tag, and
+# success is what the new launcher reports, not what npm returned.
+exec "$BASH" -c '
+    set -euo pipefail
+    pkg="$1" from="$2" to="$3" launcher="$4" prefix="$5" bin="$6"
+    npm install -g --prefix "$prefix" "$pkg@$to"
+    echo ""
+    if [ -f "$launcher" ] && command -v node >/dev/null 2>&1; then
+        got="$(node "$launcher" version 2>/dev/null || true)"
+        case "$got" in
+            "$to"|"$to "*) echo "upgraded: $from -> $to"; echo "$got" ;;
+            *)
+                echo "ERROR: npm reported success but the installed launcher answers: ${got:-<nothing>}" >&2
+                echo "       expected $to — inspect the installation at $prefix" >&2
+                exit 1
+                ;;
+        esac
+    else
+        echo "upgraded: $from -> $to (not verified — run: $bin version)"
+    fi
+' intelligence-upgrade "$pkg" "$installed" "$available" "$launcher" "$prefix" "$bin"

package/cli/intelligence

@@ -19,7 +19,7 @@ if [ -f "$CLI_DIR/../engine/sync.sh" ] && [ -f "$CLI_DIR/../engine/VERSION" ]; t
 fi
 if [ -z "$IS_ENGINE_DIR" ]; then
     echo "ERROR: bundled sync engine not found next to the CLI ($CLI_DIR)." >&2
-    echo "       Reinstall: npm i -g @ainova-systems/intelligence" >&2
+    echo "       Reinstall: npm i -g ${INTELLIGENCE_NPM_PACKAGE:-<the CLI package>}" >&2
     exit 1
 fi
 export IS_ENGINE_DIR
@@ -51,6 +51,9 @@ Usage: intelligence <command> [args]
   update [@scope/name]    Show an update plan; ask before applying it
     --preview             Show the plan without asking or writing
     --apply               Apply the plan without asking
+    --latest              Move one named package past its range to the newest version
+  upgrade [--next] [--preview|--apply]  Replace the installed CLI with the newest npm version
+    --next                Follow the prerelease line instead of the stable one
   package <command>       add | remove | list | search
   adapter <command>       list | create | enable | disable | remove
   status [--check]        Project state; --check runs deep consistency checks

package/cli/internal/check.sh

@@ -44,9 +44,9 @@ if [ -z "$stamp" ]; then
     warn "manifest has no schema_version — run 'intelligence init'"
 elif _ver_gt "$stamp" "$eng"; then
     if [ "$(_ver_major "$stamp")" -gt "$(_ver_major "$eng")" ]; then
-        warn "manifest schema $stamp is a newer major than this CLI's engine $eng — update the CLI: npm i -g @ainova-systems/intelligence@latest"
+        warn "manifest schema $stamp is a newer major than this CLI's engine $eng — update the CLI: intelligence upgrade (--next for a prerelease line)"
     else
-        note "manifest schema $stamp is newer than this CLI's engine $eng — the project uses a newer CLI; update it: npm i -g @ainova-systems/intelligence@latest"
+        note "manifest schema $stamp is newer than this CLI's engine $eng — the project uses a newer CLI; update it: intelligence upgrade (--next for a prerelease line)"
     fi
 elif _ver_gt "$eng" "$stamp"; then
     warn "manifest schema $stamp behind engine $eng — run 'intelligence init'"

package/cli/internal/package-update.sh

@@ -7,16 +7,22 @@
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
-only="" no_sync=0 preview=0
+only="" no_sync=0 preview=0 latest=0
 while [ $# -gt 0 ]; do
     case "$1" in
         --no-sync) no_sync=1 ;;
         --preview) preview=1 ;;
+        --latest) latest=1 ;;
         @*) only="$1" ;;
         *) die "unknown argument '$1'" ;;
     esac
     shift || true
 done
+# Crossing a range is per package on purpose: each boundary SemVer marks is a
+# changelog to read, so a blanket sweep would be one confirmation for several
+# unrelated decisions.
+[ "$latest" -eq 0 ] || [ -n "$only" ] \
+    || die "--latest needs the package to move: intelligence update @scope/name --latest"
 
 require_cli_project
 manifest="$IP_ROOT/intelligence.yaml"
@@ -36,7 +42,7 @@ move_label() {
     fi
 }
 
-moved=0 found=0
+moved=0 found=0 outside=0
 while IFS= read -r name; do
     [ -n "$name" ] || continue
     # Manifest keys are untrusted input on their way into store paths.
@@ -46,6 +52,8 @@ while IFS= read -r name; do
     # message followed by "not in the manifest" would contradict itself.
     found=1
     if [ "$name" = "$SYNC_PKG_NAME" ]; then
+        [ "$latest" -eq 0 ] \
+            || die "$name is the engine content package — its pin follows the installed CLI; use 'intelligence upgrade'"
         echo "  $name: engine content follows the installed CLI — skipped"
         continue
     fi
@@ -59,7 +67,9 @@ while IFS= read -r name; do
     range="$(qmap_field "$manifest" "packages" "$name" "version")"
     [ -n "$ref" ] || [ -n "$range" ] || die "$name has neither version nor ref in the manifest"
 
-    ref_moved=0 remote_sha=""
+    ref_moved=0 remote_sha="" beyond="" range_move=""
+    [ "$latest" -eq 0 ] || [ -z "$ref" ] \
+        || die "$name is pinned to ref '$ref', not a version range — a ref pin is frozen by intent; re-add the package to change it"
     if [ -n "$ref" ]; then
         tag="$ref"
         requested=""
@@ -101,27 +111,56 @@ while IFS= read -r name; do
         fi
         [ -z "$remote_sha" ] || [ "$remote_sha" = "$locked_sha" ] || ref_moved=1
     else
-        picked="$(list_remote_versions "$url" | semver_pick_highest "$range")"
+        # One remote read answers both questions: what the range selects, and
+        # what it excludes.
+        versions="$(list_remote_versions "$url")"
+        picked="$(printf '%s\n' "$versions" | semver_pick_highest "$range")"
         [ -n "$picked" ] || { echo "  $name: nothing satisfies '$range' at $url" >&2; continue; }
         read -r tag _ <<< "$(remote_tag_for_version "$url" "$picked")"
         requested="$range"
+        # A range is a ceiling as much as a floor, and on a 0.x package the
+        # caret stops at the minor: a project sits on 0.4.x while 0.6.1 ships
+        # and every plan still reads "up to date". Name what the range leaves
+        # out. Crossing it edits requested intent, which is a manifest change
+        # and never this command's to make.
+        newest="$(printf '%s\n' "$versions" | semver_pick_highest "latest")"
+        if [ -n "$newest" ] && [ "$(semver_cmp "$newest" "$picked")" = "1" ]; then
+            if [ "$latest" -eq 1 ]; then
+                # Asked for by name: take the newest and widen the recorded
+                # intent to match, keeping the caret so the next boundary is
+                # still a decision. The manifest keeps saying what the project
+                # asked for — that is what makes the move reviewable.
+                picked="$newest"
+                read -r tag _ <<< "$(remote_tag_for_version "$url" "$picked")"
+                requested="^$newest"
+                range_move=" (range $range -> $requested)"
+            else
+                beyond=" — $newest available outside '$range'"
+                beyond="$beyond
+      follow it: intelligence update $name --latest"
+                outside=$((outside + 1))
+            fi
+        fi
+        # When the newest version is already inside the range there is nothing
+        # to cross: `--latest` falls through to the ordinary comparison, which
+        # still installs a move the lock is behind on and still widens nothing.
     fi
     if [ "$ref_moved" -eq 0 ] && [ "$tag" = "$current" ] && [ "$requested" != "$locked_requested" ]; then
         if [ "$preview" -eq 1 ]; then
-            echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (keeps $current)"
+            echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (keeps $current)$beyond"
         else
             lock_upsert "$lock" "$name" "$requested" "$url" "$path" "$current" "$locked_sha"
-            echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (kept $current)"
+            echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (kept $current)$beyond"
         fi
         moved=$((moved + 1))
         continue
     fi
     if [ "$ref_moved" -eq 0 ] && [ "$tag" = "$current" ]; then
-        echo "  $name: $(pin_label "$ref" "$current" "$locked_sha") (up to date)"
+        echo "  $name: $(pin_label "$ref" "$current" "$locked_sha") (up to date)$beyond"
         continue
     fi
     if [ "$preview" -eq 1 ]; then
-        echo "  $name: $(move_label "$ref" "$current" "$tag" "$locked_sha" "$remote_sha")"
+        echo "  $name: $(move_label "$ref" "$current" "$tag" "$locked_sha" "$remote_sha")$range_move$beyond"
         moved=$((moved + 1))
         continue
     fi
@@ -139,7 +178,11 @@ while IFS= read -r name; do
     mv "$staging" "$IP_ROOT/$rel"
     wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
     lock_upsert "$lock" "$name" "$requested" "$url" "$path" "$tag" "$sha"
-    echo "  $name: $(move_label "$ref" "$current" "$tag" "$locked_sha" "$sha")"
+    # The widened intent is recorded only once its content is installed and
+    # wired: a manifest saying ^0.6.1 over a failed fetch would describe a
+    # state the project never reached.
+    [ -z "$range_move" ] || qmap_set "$manifest" "packages" "$name" "version" "$requested"
+    echo "  $name: $(move_label "$ref" "$current" "$tag" "$locked_sha" "$sha")$range_move$beyond"
     moved=$((moved + 1))
 done < <(qmap_keys "$manifest" "packages")
 
@@ -149,6 +192,11 @@ if [ "$preview" -eq 1 ]; then
 else
     echo "updated: $moved package(s)"
 fi
+# Counted apart from the movable ones: no mode of this command installs these,
+# so folding them into "updates available" would promise work --apply skips.
+if [ "$outside" -gt 0 ]; then
+    echo "outside the requested range: $outside package(s) — read the changelog, then run the 'follow it' command above"
+fi
 
 if [ "$preview" -eq 0 ] && [ "$moved" -gt 0 ] && [ "$no_sync" -eq 0 ]; then
     exec bash "$CLI_DIR/commands/sync.sh"

package/cli/lib/cli-common.sh

@@ -80,6 +80,7 @@ pin_label() {
 
 source "$CLI_DIR/lib/manifest.sh"
 source "$CLI_DIR/lib/semver.sh"
+source "$CLI_DIR/lib/cli-install.sh"
 source "$CLI_DIR/lib/registry.sh"
 source "$CLI_DIR/lib/lockfile.sh"
 source "$CLI_DIR/lib/adapter-lifecycle.sh"

package/cli/lib/cli-install.sh

@@ -0,0 +1,131 @@
+#!/bin/bash
+# The installed CLI's own npm installation — shared by `upgrade`, which
+# replaces the tree it runs from, and `update`, which plans that step.
+#
+# npm is never asked where its global root is: `npm root -g` answers for the
+# current configuration rather than for the running tree (nvm, a custom
+# prefix), and npm redacts UUID-like path segments from everything it prints.
+# The tree's own location and the shim npm linked for it say where it lives.
+
+cli_on_windows() {
+    case "${OSTYPE:-}" in msys*|cygwin*) return 0 ;; esac
+    return 1
+}
+
+# native_path <posix-path> — the spelling a native program (npm, node) needs:
+# Windows form under Git Bash, unchanged elsewhere.
+native_path() {
+    if cli_on_windows; then cygpath -w "$1"; else printf '%s' "$1"; fi
+}
+
+# quote_for_shell <string> — one shell word for a command printed to be
+# copied. Windows paths carry no `$` or backtick and cmd.exe reads single
+# quotes literally, so they get double quotes; elsewhere single quotes with
+# an embedded quote as '\''. sed rather than ${var//…}: Bash 3.2 (macOS)
+# expands a backslash-quote replacement differently.
+quote_for_shell() {
+    if cli_on_windows; then
+        printf '"%s"' "$1"
+    else
+        printf "'%s'" "$(printf '%s' "$1" | sed "s/'/'\\\\''/g")"
+    fi
+}
+
+# cli_install_classify <pkg_dir> <pkg> <bin> — where the running tree lives.
+# Sets CLI_INSTALL_KIND to npm | npx | volta | pnpm | bun | yarn | nix |
+# dependency | unknown, and CLI_INSTALL_PREFIX (POSIX spelling) for npm only.
+#
+# npm's global layout is `<prefix>/lib/node_modules/<pkg>` on POSIX and
+# `<prefix>/node_modules/<pkg>` on Windows, and a project's own node_modules
+# looks exactly like the latter. The shim npm links at the prefix root is
+# what proves a prefix: `<prefix>/bin/<bin>` pointing into this tree, or
+# `<prefix>/<bin>.cmd` naming it. Known foreign stores are named first
+# because Volta's package images are laid out like an npm prefix without
+# being one.
+cli_install_classify() {
+    local pkg_dir="$1" pkg="$2" bin="$3" prefix="" kind="unknown" shim target pkg_bs
+    CLI_INSTALL_KIND=""; CLI_INSTALL_PREFIX=""
+    case "$pkg_dir" in
+        */_npx/*) kind="npx" ;;
+        */.volta/*|*/Volta/*) kind="volta" ;;
+        */.pnpm/*) kind="pnpm" ;;
+        */.bun/install/global/*) kind="bun" ;;
+        */yarn/global/*|*/Yarn/Data/global/*) kind="yarn" ;;
+        /nix/store/*|/gnu/store/*) kind="nix" ;;
+        *)
+            if cli_on_windows; then
+                case "$pkg_dir" in
+                    */node_modules/"$pkg")
+                        prefix="${pkg_dir%/node_modules/"$pkg"}"
+                        prefix="${prefix:-/}"
+                        shim="$prefix/$bin.cmd"
+                        # The cmd shim spells its target with backslashes.
+                        pkg_bs="$(printf '%s' "$pkg" | tr '/' '\\')"
+                        if [ ! -f "$shim" ] || ! grep -Fq "node_modules\\$pkg_bs\\bin\\" "$shim"; then
+                            prefix=""
+                        fi
+                        ;;
+                esac
+            else
+                case "$pkg_dir" in
+                    */lib/node_modules/"$pkg")
+                        prefix="${pkg_dir%/lib/node_modules/"$pkg"}"
+                        prefix="${prefix:-/}"
+                        shim="$prefix/bin/$bin"
+                        target=""
+                        if [ -L "$shim" ]; then
+                            target="$(readlink "$shim")"
+                            case "$target" in /*) ;; *) target="$prefix/bin/$target" ;; esac
+                            target="$(cd "$(dirname "$target")" 2>/dev/null && pwd -P || true)"
+                        fi
+                        [ "$target" = "$pkg_dir/bin" ] || prefix=""
+                        ;;
+                esac
+            fi
+            if [ -n "$prefix" ]; then
+                kind="npm"
+            else
+                case "$pkg_dir" in */node_modules/"$pkg") kind="dependency" ;; esac
+            fi
+            ;;
+    esac
+    # Read by upgrade and update after the call — per-file shellcheck cannot see that.
+    # shellcheck disable=SC2034
+    CLI_INSTALL_KIND="$kind"
+    # shellcheck disable=SC2034
+    CLI_INSTALL_PREFIX="$prefix"
+}
+
+# cli_install_hint <kind> <pkg> <version-or-channel> — the command that
+# upgrades a tree npm did not make, for the refusal message.
+cli_install_hint() {
+    local kind="$1" spec="$2@$3"
+    case "$kind" in
+        npx) printf 'nothing is installed globally (this run came through npx) — install it: npm install -g %s' "$spec" ;;
+        volta) printf 'volta install %s' "$spec" ;;
+        pnpm) printf 'pnpm add -g %s' "$spec" ;;
+        bun) printf 'bun add -g %s' "$spec" ;;
+        yarn) printf 'yarn global add %s' "$spec" ;;
+        nix) printf 'this tree is a Nix/Guix store path — upgrade it with that package manager (%s)' "$spec" ;;
+        dependency) printf 'this is a project dependency — move it in package.json: npm install -D %s' "$spec" ;;
+        *) printf 'upgrade it with the tool that installed it (ask for %s), or pull it if it is a checkout' "$spec" ;;
+    esac
+}
+
+# cli_registry_version <pkg> <channel> [native-prefix] — the version the
+# registry serves on that dist-tag, validated; prints nothing and fails when
+# npm does not answer with one. With a prefix the lookup runs in global mode
+# at that prefix — the configuration `npm install -g --prefix` will use, so
+# the plan and the install cannot read different registries. `--no-json`
+# overrides a `json=true` in any npmrc, which would quote the answer.
+cli_registry_version() {
+    local pkg="$1" channel="$2" prefix="${3:-}" out
+    if [ -n "$prefix" ]; then
+        out="$(npm view --global --prefix "$prefix" --no-json "$pkg" "dist-tags.$channel" 2>/dev/null || true)"
+    else
+        out="$(npm view --no-json "$pkg" "dist-tags.$channel" 2>/dev/null || true)"
+    fi
+    out="${out//[$' \t\r\n']/}"
+    is_npm_version "$out" || return 1
+    printf '%s' "$out"
+}

package/cli/lib/registry.sh

@@ -136,7 +136,7 @@ fetch_package() {
     if is_bundle_source "$url" "$ref" "$subpath" \
         && { [ -z "$locked_sha" ] || [ -z "$bundle_sha" ] || [ "$locked_sha" = "$bundle_sha" ]; }; then
         [ -n "${IS_BUNDLED_PKG_DIR:-}" ] && [ -d "$IS_BUNDLED_PKG_DIR" ] \
-            || die "bundled engine content not found next to the CLI — reinstall @ainova-systems/intelligence"
+            || die "bundled engine content not found next to the CLI — reinstall ${INTELLIGENCE_NPM_PACKAGE:-the CLI package}"
         rm -rf "$dest"
         mkdir -p "$dest"
         cp -R "$IS_BUNDLED_PKG_DIR/." "$dest/"

package/cli/lib/semver.sh

@@ -21,6 +21,72 @@ semver_cmp() {
         }'
 }
 
+# semver_cmp_full <a> <b> — prints -1 / 0 / 1 with SemVer prerelease
+# precedence: 1.0.0-rc.1 < 1.0.0-rc.2 < 1.0.0; build metadata is ignored.
+# Package ranges never see prereleases, so semver_cmp stays digits-only; this
+# one is for the CLI's own npm versions, whose `next` channel is a prerelease
+# line.
+semver_cmp_full() {
+    awk -v a="${1#v}" -v b="${2#v}" '
+        # Numeric identifiers compare as numbers (no leading zeros, so length
+        # then digits — exact beyond what a double holds) and sort before
+        # alphanumeric ones; those compare as ASCII strings, never as numbers
+        # awk might read into them (1e5).
+        function idcmp(x, y,    xn, yn) {
+            xn = (x ~ /^[0-9]+$/); yn = (y ~ /^[0-9]+$/)
+            if (xn && yn) {
+                if (length(x) != length(y)) return (length(x) < length(y)) ? -1 : 1
+                return (x "" < y "") ? -1 : (x "" > y "") ? 1 : 0
+            }
+            if (xn) return -1
+            if (yn) return 1
+            return (x "" < y "") ? -1 : (x "" > y "") ? 1 : 0
+        }
+        BEGIN {
+            sub(/\+.*$/, "", a); sub(/\+.*$/, "", b)
+            pa = ""; pb = ""
+            if (i = index(a, "-")) { pa = substr(a, i + 1); a = substr(a, 1, i - 1) }
+            if (i = index(b, "-")) { pb = substr(b, i + 1); b = substr(b, 1, i - 1) }
+            na = split(a, A, "."); nb = split(b, B, ".")
+            for (i = 1; i <= 3; i++) {
+                x = (i <= na) ? A[i] + 0 : 0
+                y = (i <= nb) ? B[i] + 0 : 0
+                if (x < y) { print -1; exit }
+                if (x > y) { print 1; exit }
+            }
+            # A release outranks every prerelease of the same core.
+            if (pa == "" && pb == "") { print 0; exit }
+            if (pa == "") { print 1; exit }
+            if (pb == "") { print -1; exit }
+            na = split(pa, PA, "."); nb = split(pb, PB, ".")
+            n = (na < nb) ? na : nb
+            for (i = 1; i <= n; i++) {
+                c = idcmp(PA[i], PB[i])
+                if (c != 0) { print c; exit }
+            }
+            r = (na < nb) ? -1 : (na > nb) ? 1 : 0
+            print r
+        }'
+}
+
+# npm_channel_for <version> — the npm dist-tag a CLI version came from:
+# `next` for a prerelease, `latest` otherwise. `update` and `upgrade` both
+# derive the channel from the running version; one rule here keeps them equal.
+npm_channel_for() {
+    case "$1" in
+        *-*) printf 'next' ;;
+        *) printf 'latest' ;;
+    esac
+}
+
+# is_npm_version <string> — 0 iff the string is a version as npm publishes
+# it: `x.y.z`, an optional `-prerelease`, an optional `+build`, nothing else.
+# A registry answer becomes an npm argument, so anything else is refused.
+is_npm_version() {
+    local re='^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$'
+    [[ "$1" =~ $re ]]
+}
+
 # semver_is_stable <version> — 0 iff `[v]x.y.z` with nothing else.
 semver_is_stable() {
     case "${1#v}" in

package/engine/ENGINE_SHA

@@ -1 +1 @@
-9a4af90d8c755b5486a4a67af7c53c1be23f4641
+a9cf448bc3f2944c988ce57581822df081195ca2

package/engine/VERSION

@@ -1 +1 @@
-0.12.1
+0.14.0

package/engine/adapters/agents.sh

@@ -58,11 +58,9 @@ agents_md_append_agents_table() {
     local rows=""
     local count=0
 
-    local f
     local -a files=()
-    while IFS= read -r f; do
-        [ -n "$f" ] && files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "agents")
+    read_source_artifact_files "$repo_root" "$config_file" "agents"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || files=("${IS_SOURCE_FILES[@]}")
 
     if [ "${#files[@]}" -gt 0 ]; then
         local path tier access desc name
@@ -101,11 +99,10 @@ agents_md_append_skills_table() {
     local rows=""
     local count=0
 
-    local f dirname
+    local dirname
     local -a skill_files=()
-    while IFS= read -r f; do
-        [ -n "$f" ] && skill_files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "skills")
+    read_source_artifact_files "$repo_root" "$config_file" "skills"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || skill_files=("${IS_SOURCE_FILES[@]}")
 
     if [ "${#skill_files[@]}" -gt 0 ]; then
         local path desc
@@ -145,11 +142,9 @@ agents_md_append_rules_list() {
     local count=0
     local global_rule_files=()
 
-    local f
     local -a files=()
-    while IFS= read -r f; do
-        [ -n "$f" ] && files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "rules")
+    read_source_artifact_files "$repo_root" "$config_file" "rules"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || files=("${IS_SOURCE_FILES[@]}")
 
     if [ "${#files[@]}" -gt 0 ]; then
         local path hp name scope

package/engine/lib/common.sh

@@ -643,14 +643,20 @@ sync_open_skill_dirs() {
 
     local count=0 log="" d skill_file skill_name
     local -a skill_dirs=()
-    while IFS= read -r skill_file; do
-        [ -n "$skill_file" ] || continue
-        d="${skill_file%/SKILL.md}"
-        skill_name="${d##*/}"
-        skill_dirs+=("$d/")
-        count=$((count + 1))
-        log+="  skill: $skill_name"$'\n'
-    done < <(source_artifact_files "$repo_root" "$config_file" "skills")
+    read_source_artifact_files "$repo_root" "$config_file" "skills"
+    # Guard on the count, then expand quoted: Bash 3.2 (macOS) errors on an
+    # empty array under `set -u`, and quoting keeps a path with a space or a
+    # glob character intact.
+    if [ "${#IS_SOURCE_FILES[@]}" -gt 0 ]; then
+        for skill_file in "${IS_SOURCE_FILES[@]}"; do
+            [ -n "$skill_file" ] || continue
+            d="${skill_file%/SKILL.md}"
+            skill_name="${d##*/}"
+            skill_dirs+=("$d/")
+            count=$((count + 1))
+            log+="  skill: $skill_name"$'\n'
+        done
+    fi
     # copy_skill_bundle_dirs owns the frontmatter-quoting pass, so every
     # target gets it — not just this open-standard dir.
     if [ "$count" -gt 0 ]; then
@@ -1335,29 +1341,58 @@ warn_unsynced() {
 
 # Enumerate one manifest source kind using the same depth and ordering
 # everywhere. Source-list order is significant; entries inside each directory
-# use byte-order sorting for cross-platform determinism.
-source_artifact_files() {
+# use byte-order sorting for cross-platform determinism. The result lands in
+# IS_SOURCE_FILES; callers read that array.
+#
+# It is deliberately not streamed out of a subshell. This list decides what
+# every adapter renders, and a truncated one is indistinguishable from a
+# smaller project: a short list renders an incomplete file and the run still
+# reports IS_STATUS=ok. Streaming had two ways to truncate silently — a pipe
+# write cut short (bash's printf surfaces EINTR as `write error: Interrupted
+# system call` and drops the line) and a process substitution, which discards
+# its writer's exit status entirely. Assembling in the caller's shell leaves no
+# writer whose failure can be lost, and the remaining pipeline is checked. An
+# enumeration that cannot answer must stop the run, never shorten the answer.
+read_source_artifact_files() {
     local repo_root="$1"
     local config_file="$2"
     local section="$3"
-    local src f dir
+    local src f dir listing
 
+    IS_SOURCE_FILES=()
     load_yaml_list "$config_file" "$section"
     while IFS= read -r src; do
         [ -n "$src" ] || continue
         dir="$repo_root/$src"
         [ -d "$dir" ] || continue
+        # Command substitution, so the pipeline's status is the assignment's:
+        # `find` or `sort` failing aborts here instead of yielding a short list.
         case "$section" in
             rules|agents)
-                find "$dir" -maxdepth 1 -type f -name '*.md' -print | LC_ALL=C sort
+                listing="$(find "$dir" -maxdepth 1 -type f -name '*.md' -print | LC_ALL=C sort)" || {
+                    echo "ERROR: cannot enumerate $section under '$dir' — refusing to render a partial list." >&2
+                    exit 1
+                }
                 ;;
             skills)
-                while IFS= read -r f; do
-                    [ -n "$f" ] || continue
-                    [ -f "$f/SKILL.md" ] && printf '%s\n' "$f/SKILL.md"
-                done < <(find "$dir" -mindepth 1 -maxdepth 1 -type d -print | LC_ALL=C sort)
+                listing="$(find "$dir" -mindepth 1 -maxdepth 1 -type d -print | LC_ALL=C sort)" || {
+                    echo "ERROR: cannot enumerate $section under '$dir' — refusing to render a partial list." >&2
+                    exit 1
+                }
                 ;;
+            *) continue ;;
         esac
+        [ -n "$listing" ] || continue
+        # A here-string redirect keeps this loop in the current shell, so the
+        # array it fills survives and any failure inside it is this shell's.
+        while IFS= read -r f; do
+            [ -n "$f" ] || continue
+            if [ "$section" = "skills" ]; then
+                [ -f "$f/SKILL.md" ] || continue
+                f="$f/SKILL.md"
+            fi
+            IS_SOURCE_FILES+=("$f")
+        done <<< "$listing"
     done <<< "$IS_YAML_LIST"
 }
 
@@ -1391,9 +1426,8 @@ report_context_source_sizes() {
     local f path has_paths
     local -a rule_files=() always_on_rules=() scoped_rules=() agent_files=() skill_files=()
 
-    while IFS= read -r f; do
-        [ -n "$f" ] && rule_files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "rules")
+    read_source_artifact_files "$repo_root" "$config_file" "rules"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || rule_files=("${IS_SOURCE_FILES[@]}")
     if [ "${#rule_files[@]}" -gt 0 ]; then
         while IFS=$'\x1f' read -r path has_paths; do
             [ -n "$path" ] || continue
@@ -1405,13 +1439,11 @@ report_context_source_sizes() {
         done < <(frontmatter_index "paths#" "${rule_files[@]}")
     fi
 
-    while IFS= read -r f; do
-        [ -n "$f" ] && agent_files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "agents")
+    read_source_artifact_files "$repo_root" "$config_file" "agents"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || agent_files=("${IS_SOURCE_FILES[@]}")
 
-    while IFS= read -r f; do
-        [ -n "$f" ] && skill_files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "skills")
+    read_source_artifact_files "$repo_root" "$config_file" "skills"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || skill_files=("${IS_SOURCE_FILES[@]}")
 
     local always_bytes custom_bytes agents_output agents_bytes=0 agents_status="disabled"
     always_bytes="$(context_files_bytes "${always_on_rules[@]+"${always_on_rules[@]}"}")"

package/engine/lib/contract.sh

@@ -126,14 +126,14 @@ check_version_compat() {
     if [ "$(_ver_major "$stamp")" -gt "$(_ver_major "$eng")" ]; then
         is_status ahead-of-engine "stamp=$stamp engine=$eng"
         echo "  ERROR: project stamped $stamp but this engine is $eng — a newer major schema; refusing." >&2
-        echo "         Update the CLI first: npm i -g @ainova-systems/intelligence@latest" >&2
+        echo "         Update the CLI first: intelligence upgrade (--next for a prerelease line)" >&2
         return "$IS_RC_AHEAD"
     fi
     # One warning per command, however many processes re-check on the way to
     # the engine (CLI preflight first, then the engine itself). The line has
     # no indent on purpose: `sync --compact` keeps `WARNING:` lines.
     if [ "${IS_SCHEMA_AHEAD_WARNED:-}" != "$stamp" ]; then
-        echo "WARNING: project schema $stamp is newer than this CLI's engine $eng — the project uses a newer CLI; update it: npm i -g @ainova-systems/intelligence@latest" >&2
+        echo "WARNING: project schema $stamp is newer than this CLI's engine $eng — the project uses a newer CLI; update it: intelligence upgrade (--next for a prerelease line)" >&2
         export IS_SCHEMA_AHEAD_WARNED="$stamp"
     fi
     return 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Build, version and distribute AI agent intelligence across your organization — one CLI, versioned Intelligence Packages, and a sync engine for Claude Code, Cursor, Copilot, Codex, Pi and OpenCode.",
   "bin": {
     "intelligence": "bin/intelligence.js"

package/packages/sync/references/conventions.md

@@ -96,6 +96,29 @@ Registries are an ordered trust list and the only resolver for a package name. T
 
 Stable Git tags provide package versions. Semver ranges select the highest matching stable tag; a `ref:` pin names a branch or commit and does not move during `intelligence update`. One package name has one version per project.
 
+### Choosing a range
+
+`package add` without an explicit range writes `^<the version it installed>`, npm's caret. The caret holds the **leftmost non-zero** component, and that is the whole story:
+
+| Requested | Follows automatically | Stops at |
+|---|---|---|
+| `^1.4.0` | every later `1.x` | `2.0.0` |
+| `^0.4.0` | every later `0.4.x` | `0.5.0` |
+| `~1.4.0` | every later `1.4.x` | `1.5.0` |
+| `1.4.0` | nothing | it is a pin |
+| `latest` | every stable tag | nothing |
+
+**A pre-1.0 package therefore follows patches only.** SemVer treats a `0.x` minor as a major, so `^0.4.0` is a ceiling at `0.5.0` and the project stays on `0.4.x` while `0.5`, `0.6` and later ship. That is the correct reading of the range, not a defect — but it is the single most common surprise, because the same spelling behaves differently once the package reaches `1.0.0`.
+
+Practice:
+
+- **Keep the caret.** It is the right default at both stages: automatic patches, and a deliberate decision at every boundary that SemVer says may break.
+- **Read `intelligence update --preview` as two answers.** The move is what the range allows; the `available outside '<range>'` note is what it excludes, and it prints the command that follows it. That note never joins the counter, because no ordinary mode of `update` installs it.
+- **Cross a boundary deliberately, one at a time.** Read the package's changelog for every version crossed, then `intelligence update @scope/name --latest`: it takes the newest stable version and rewrites the requested range to `^<that version>`, so the manifest still records what the project asked for and the next boundary is still a decision. The flag needs the package named — one confirmation must not cover several unrelated changelogs — and it refuses a `ref:` pin, which is frozen by intent. Without it `update` never widens a range, because a command that granted itself permission to install would make the range meaningless.
+- **Review the generated diff, not just the lock.** A package minor may rename or drop an artifact. A renamed skill breaks every `/skill-name` that invoked it, and a renamed artifact silently ends the override relationship a same-named project artifact had, so the project's version stops winning and the package's content appears instead.
+- **`latest` and `*` are for a package you own and release in lockstep.** Anywhere else they hand an upstream author write access to your agents' behavior between two syncs.
+- **Never pin a range to dodge a broken release.** Pin the exact version (`1.4.2`), record why, and remove the pin when the fix ships — a narrowed range hides the reason and outlives the incident.
+
 Commit `intelligence.lock`. It records requested versions, source URLs and paths, resolved refs and commit SHAs. After cloning, `intelligence sync` restores a missing store strictly from that lock before rendering; manifest/lock or SHA drift is refused. Re-run `package add` when deliberately changing a source.
 
 `@ainova-systems/sync` is ordinary package content exact-pinned to the bundled engine version. `intelligence init` installs it unless `--bare` is used. Lifecycle preflight keeps that pin and `schema_version` aligned with the installed CLI; package-range updates never move it independently.
@@ -392,6 +415,7 @@ The public lifecycle is deliberately compact:
 - `intelligence init [--preview|--apply]` is universal: it creates a new setup, aligns an existing Intelligence project, or plans/applies conversion of an eligible legacy Intelligence Sync project.
 - `intelligence sync [adapter] [--compact]` first aligns an existing Intelligence project with the installed CLI, restores a missing store strictly from `intelligence.lock`, then renders. Compact mode shows context sizes, actionable warnings and final status on success, and all diagnostics on failure. In CI it refuses an alignment that would change tracked files and points to a local `intelligence init --apply` plus review/commit.
 - `intelligence update [@scope/name] [--preview|--apply]` is the only update surface. It prints the CLI/project/package plan; default mode prompts, `--preview` never writes, and `--apply` does not prompt. It never moves `ref:` pins.
+- `intelligence upgrade [--next] [--preview|--apply]` replaces the installed CLI with the newest version on its npm channel (`next` for a prerelease or with `--next`, otherwise `latest`) with the same modes. It touches no project, never downgrades, and refuses an installation that npm did not make.
 - `intelligence package add|remove|list|search` owns package inventory.
 - `intelligence adapter list|create|enable|disable|remove` owns adapter inventory and target state.
 - `intelligence status [--check]` reports state; `--check` runs deep consistency checks.

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

@@ -28,10 +28,15 @@ result.
    mode also shows the plan and prompts; after approval, use `--apply` for an
    unambiguous non-interactive execution.
 
-4. If the plan reports a newer global CLI, run exactly the npm command it
-   prints after approval, then rerun `intelligence update --preview` with the
-   new executable. Apply the resulting plan with `intelligence update --apply`,
-   or `intelligence update $ARGUMENTS --apply` when one package was requested.
+4. If the plan reports a newer global CLI, run `intelligence upgrade --apply`
+   after approval — it installs exactly the version the plan showed — then
+   rerun `intelligence update --preview` with the new executable. When the
+   project section reports a schema stamped ahead of the stable line, the CLI
+   that stamped it was a prerelease: use `intelligence upgrade --next --apply`.
+   If `upgrade` refuses because npm did not make this installation, run the
+   command its message names instead. Apply the resulting plan with
+   `intelligence update --apply`, or `intelligence update $ARGUMENTS --apply`
+   when one package was requested.
 
 5. An applied update that renders must finish with `IS_STATUS=ok`; preserve and
    stop on any other status. Then run `intelligence status --check`. Do not run