@ainova-systems/intelligence 0.12.0 → 0.13.0

package/README.md

@@ -35,6 +35,7 @@ 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 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,8 +2,9 @@
 # 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"
 
@@ -30,18 +31,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 +60,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

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,8 @@ 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
+  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/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/gitignore.sh

@@ -15,34 +15,60 @@ gitignore_path_is_ignored() {
     git -C "$root" check-ignore -q --no-index -- "$path"
 }
 
-# Git cannot re-include a child of an excluded directory. Add explicit parent
-# reinclusions, then make sure both parent and child negations occur after any
-# pre-existing rule that still wins. The check-ignore probe also catches broad
-# patterns such as an old `.claude/` or `.cursor/**`, not just exact matches.
+# True when the file's last lines are exactly these, in order.
+gitignore_tail_is() {
+    local file="$1"; shift
+    [ -f "$file" ] || return 1
+    local want tail_lines
+    want="$(printf '%s\n' "$@")"
+    tail_lines="$(tail -n "$#" -- "$file")"
+    [ "$tail_lines" = "$want" ]
+}
+
+# Git cannot re-include a child of an excluded directory, so an include needs an
+# explicit negation for every parent. A negation only wins when it comes after
+# the rule excluding the parent, and the only repair an append can make is to
+# move the whole chain last — so the repair runs when, and only when, the chain
+# is not already there.
+#
+# Probe the include TARGET, never a parent with a trailing slash: `dir/*` — the
+# ignore this very policy writes — matches `dir/` because `*` matches the empty
+# string, so a parent probe answers "still ignored" in the healthy end state.
+# Keyed on that, the repair re-appended a line already last, which cannot change
+# the answer, and the file grew by one line on every run.
 gitignore_add_effective_include() {
-    local root="$1" value="${2#./}" dir parent="" part rc
+    local root="$1" value="${2#./}" dir parent="" part line rc
+    local -a negations=()
     dir="${value%/*}"
     if [ "$dir" != "$value" ]; then
         while IFS= read -r part; do
             [ -n "$part" ] || continue
             if [ -n "$parent" ]; then parent="$parent/$part"; else parent="$part"; fi
-            gitignore_add_line "$root" "!$parent/"
-            if gitignore_path_is_ignored "$root" "$parent/"; then
-                printf '!%s/\n' "$parent" >> "$root/.gitignore"
-            else
-                rc=$?
-                [ "$rc" -eq 1 ] || [ "$rc" -eq 2 ] || return "$rc"
-            fi
+            negations+=("!$parent/")
         done < <(printf '%s\n' "$dir" | tr '/' '\n')
     fi
+    negations+=("!$value")
 
-    gitignore_add_line "$root" "!$value"
-    if gitignore_path_is_ignored "$root" "$value"; then
-        printf '!%s\n' "$value" >> "$root/.gitignore"
-    else
-        rc=$?
-        [ "$rc" -eq 1 ] || [ "$rc" -eq 2 ] || return "$rc"
-    fi
+    for line in "${negations[@]}"; do
+        gitignore_add_line "$root" "$line"
+    done
+
+    # `|| rc=$?` keeps the probe out of `set -e`'s reach: its honest "not
+    # ignored" is exit 1, and a bare call would abort the whole command there.
+    rc=0
+    gitignore_path_is_ignored "$root" "$value" || rc=$?
+    case "$rc" in
+        0) ;;
+        1|2) return 0 ;;
+        *) return "$rc" ;;
+    esac
+
+    # Still ignored: an earlier negation is shadowed by a later rule. Move the
+    # chain last. Already last means appending cannot help — leave it, and let
+    # `status --check` report the re-inclusion this policy could not make
+    # effective rather than growing the file forever.
+    gitignore_tail_is "$root/.gitignore" "${negations[@]}" && return 0
+    printf '%s\n' "${negations[@]}" >> "$root/.gitignore"
 }
 
 ensure_gitignore_header() {

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 @@
-b1242a74527d0295e9017fcd6b13ebfe00892710
+012f75bfb3c3036df3df9e914597ba937ab75400

package/engine/VERSION

@@ -1 +1 @@
-0.12.0
+0.13.0

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.0",
+  "version": "0.13.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

@@ -392,6 +392,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