@ainova-systems/intelligence 0.11.0-rc.1

package/cli/commands/migrate.sh

@@ -0,0 +1,251 @@
+#!/bin/bash
+# intelligence migrate [--dry-run] [--force] — convert a vendored (v1) setup
+# 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
+# project, VERIFY the staged state, then COMMIT in an order where every
+# destructive step happens only after a real sync of the new state reported
+# IS_STATUS=ok. Any earlier failure leaves the project untouched.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+dry_run=0 force=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --dry-run) dry_run=1 ;;
+        --force) force=1 ;;
+        *) die "unknown option '$1'" ;;
+    esac
+    shift || true
+done
+
+# ---- Preconditions (fail closed, nothing written) -------------------------
+detect_project
+case "$IP_MODE" in
+    legacy) ;;
+    v2) die "already on the CLI setup ($IP_ROOT/intelligence.yaml)" ;;
+    *) die "no vendored setup found here — 'intelligence init' starts a fresh project" ;;
+esac
+root="$IP_ROOT"
+umbrella="$IP_UMBRELLA"
+module_dir="$IP_MODULE_DIR"
+config="$umbrella/config.yaml"
+module_rel="${module_dir#"$root"/}"
+
+[ -f "$root/intelligence.yaml" ] && die "intelligence.yaml already exists at the root — half-migrated state; resolve it manually"
+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")"
+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"
+
+# A schema gap is closed by the engine's own proven chain before conversion.
+if [ "$dry_run" -eq 0 ] && { [ -z "$stamp" ] || _ver_gt "$eng" "$stamp"; }; then
+    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
+
+# ---- Stage ----------------------------------------------------------------
+stage="$root/.intelligence-migrate-stage.$$"
+[ "$dry_run" -eq 1 ] && stage="$(mktemp -d -t intelligence-migrate-XXXXXX 2>/dev/null || mktemp -d)"
+cleanup_stage() { rm -rf "$stage"; }
+trap cleanup_stage EXIT INT TERM
+mkdir -p "$stage/.intelligence/packages"
+
+echo "== staging =="
+stage_engine_content "$stage/.intelligence/engine"
+
+# Legacy pack name -> v2 package name (@org/repo derived from the url), plus
+# per-pack source facts. Recorded as rows for the config rewrite and the lock.
+pack_rows="$stage/packs.rows"
+: > "$pack_rows"
+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"
+    base="${url%.git}"; base="${base%/}"
+    repo="$(basename "$base")"
+    org="$(basename "$(dirname "$base")")"
+    case "$org" in ""|*[!A-Za-z0-9._-]*) org="local" ;; esac
+    case "$repo" in ""|*[!A-Za-z0-9._-]*) repo="$(printf '%s' "$repo" | tr -c 'A-Za-z0-9._-' '-')" ;; esac
+    name="@$org/$repo"
+    assert_valid_pkg_name "$name"
+    printf '%s\n' "$pack$LOCK_SEP$name$LOCK_SEP$url$LOCK_SEP$ref$LOCK_SEP$mirror"
+done < <(read_yaml_keys "$config" "packs") >> "$pack_rows"
+
+# Stage the store: mirrored packs are COPIED from their mirrors (content the
+# repo already holds — the network is not consulted, and the mirror is not
+# touched); transient packs are fetched.
+lock_rows="$stage/lock.rows"
+: > "$lock_rows"
+while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
+    [ -n "$pack" ] || continue
+    dest="$stage/.intelligence/packages/$name"
+    sha=""
+    if [ -n "$mirror" ] && [ -d "$root/$mirror" ]; then
+        mkdir -p "$dest"
+        cp -R "$root/$mirror/." "$dest/"
+        if [ -f "$dest/.pack" ]; then
+            sha="$(awk -F= '$1 == "sha" {print $2; exit}' "$dest/.pack")"
+            rm -f "$dest/.pack"
+        fi
+        echo "  pack '$pack' -> $name (from mirror $mirror)"
+    else
+        sha="$(fetch_package "$url" "$ref" "" "$dest")"
+        echo "  pack '$pack' -> $name (fetched)"
+    fi
+    if [ -z "$sha" ] || [ "$sha" = "unknown" ]; then
+        sha="$(GIT_TERMINAL_PROMPT=0 git ls-remote "$url" "$ref" 2>/dev/null | awk '{print $1; exit}')"
+    fi
+    printf '%s\037%s\037%s\037%s\037%s\037%s\n' \
+        "$name" "" "$url" "" "$ref" "$sha" >> "$lock_rows"
+done < "$pack_rows"
+
+# The manifest: config.yaml transformed line by line — comments and unknown
+# blocks survive verbatim; `sync_version` and `packs:` are dropped (restamped
+# / converted); sources entries are rewritten onto the store.
+manifest_stage="$stage/intelligence.yaml"
+rewrite_source_value() {
+    local v="$1" pack name rest
+    case "$v" in
+        "$module_rel"/rules|"$module_rel"/agents|"$module_rel"/skills)
+            printf '.intelligence/engine/%s' "${v##*/}"
+            return 0 ;;
+        @*)
+            rest="${v#@}"
+            pack="${rest%%/*}"
+            while IFS="$LOCK_SEP" read -r p name _ _ _; do
+                if [ "$p" = "$pack" ]; then
+                    if [ "$rest" = "$pack" ]; then
+                        printf '.intelligence/packages/%s' "$name"
+                    else
+                        printf '.intelligence/packages/%s/%s' "$name" "${rest#*/}"
+                    fi
+                    return 0
+                fi
+            done < "$pack_rows"
+            ;;
+    esac
+    printf '%s' "$v"
+}
+in_packs=0 in_sources=0
+while IFS= read -r line || [ -n "$line" ]; do
+    line="${line%$'\r'}"
+    case "$line" in
+        sync_version:*) continue ;;
+        packs:*) in_packs=1; continue ;;
+        sources:*) in_sources=1; in_packs=0; echo "$line"; continue ;;
+        [!\ \#]*) in_packs=0; in_sources=0 ;;
+    esac
+    [ "$in_packs" -eq 1 ] && continue
+    if [ "$in_sources" -eq 1 ]; then
+        case "$line" in
+            *"- "*)
+                indent="${line%%-*}"
+                v="${line#*- }"
+                v="${v%\"}"; v="${v#\"}"; v="${v%\'}"; v="${v#\'}"
+                echo "$indent- \"$(rewrite_source_value "$v")\""
+                continue
+                ;;
+        esac
+    fi
+    echo "$line"
+done < "$config" > "$manifest_stage"
+stamp_version "$manifest_stage" "$eng"
+
+# packages: entries (pin preserved — no invented ranges).
+while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
+    [ -n "$pack" ] || continue
+    qmap_set "$manifest_stage" "packages" "$name" "url" "$url"
+    [ -n "$ref" ] && qmap_set "$manifest_stage" "packages" "$name" "ref" "$ref"
+done < "$pack_rows"
+
+# ---- Verify ---------------------------------------------------------------
+echo "== verifying staged state =="
+fail=0
+for section in rules agents skills; do
+    while IFS= read -r src; do
+        [ -n "$src" ] || continue
+        case "$src" in
+            .intelligence/*) [ -d "$stage/$src" ] || { echo "  MISSING (staged): $src"; fail=1; } ;;
+            git+*|@*) echo "  UNCONVERTED source token: $src"; fail=1 ;;
+            *) [ -d "$root/$src" ] || echo "  NOTE: local source '$src' does not exist (kept — same as before)" ;;
+        esac
+    done < <(read_yaml_list "$manifest_stage" "$section")
+done
+for adapter in agents claude cursor copilot codex pi opencode; do
+    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
+[ "$fail" -eq 0 ] || die "staged state failed verification — nothing changed"
+
+if [ "$dry_run" -eq 1 ]; then
+    echo ""
+    echo "== dry run — the project is untouched. Staged manifest: =="
+    cat "$manifest_stage"
+    echo ""
+    echo "Would: write intelligence.yaml + intelligence.lock, move the store in,"
+    echo "sync, then remove $module_rel/, config.yaml and the pack mirrors."
+    exit 0
+fi
+
+# ---- Commit ---------------------------------------------------------------
+echo "== committing =="
+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
+rollback() {
+    rm -rf "$root/.intelligence" "$root/intelligence.yaml" "$root/intelligence.lock"
+    echo "rolled back — the vendored setup is untouched" >&2
+}
+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"
+}
+echo "$sync_out" | grep -q '^IS_STATUS=ok' || {
+    echo "$sync_out"
+    rollback
+    die "sync of the migrated state did not report ok — rolled back"
+}
+
+# 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
+        rm -rf "${root:?}/$mirror"
+        # An emptied mirror parent (e.g. <umbrella>/external/) goes with it.
+        rmdir "$(dirname "$root/$mirror")" 2>/dev/null || true
+    fi
+done < "$pack_rows"
+rm -rf "$module_dir"
+rm -f "$config"
+# An emptied umbrella dir (config-only setups) is dropped; one with project
+# content stays.
+rmdir "$umbrella" 2>/dev/null || true
+
+echo ""
+echo "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."

package/cli/commands/registry.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# intelligence registry <list | add @scope <registry-repo-url> | remove @scope>
+#
+# A registry binding is rare, per-scope configuration (npm's @scope:registry
+# analog): the URL of a git repo whose index.yaml maps names to sources.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+sub="${1:-list}"
+case "$sub" in
+    list)
+        detect_project
+        if [ "$IP_MODE" = "v2" ] && [ -f "$IP_ROOT/intelligence.yaml" ]; then
+            echo "Project bindings (intelligence.yaml):"
+            found=0
+            while IFS= read -r scope; do
+                [ -n "$scope" ] || continue
+                found=1
+                echo "  $scope -> $(qmap_value "$IP_ROOT/intelligence.yaml" "registries" "$scope")"
+            done < <(qmap_keys "$IP_ROOT/intelligence.yaml" "registries")
+            [ "$found" -eq 0 ] && echo "  (none)"
+        fi
+        bundled="$(default_index_file)"
+        if [ -n "$bundled" ]; then
+            echo "Bundled index:"
+            while IFS= read -r name; do
+                [ -n "$name" ] || continue
+                echo "  $name -> $(qmap_field "$bundled" "packages" "$name" "url")"
+            done < <(qmap_keys "$bundled" "packages")
+        fi
+        echo "Fallback: @org/name -> https://github.com/org/name.git"
+        ;;
+    add)
+        scope="${2:-}"; url="${3:-}"
+        { [ -n "$scope" ] && [ -n "$url" ]; } || die "usage: intelligence registry add @scope <registry-repo-url>"
+        case "$scope" in @*/*) die "bind a scope (@acme), not a package name" ;; @*) ;; *) die "scope must start with @" ;; esac
+        require_v2
+        qmap_set_value "$IP_ROOT/intelligence.yaml" "registries" "$scope" "$url"
+        echo "$scope -> $url"
+        ;;
+    remove)
+        scope="${2:-}"
+        [ -n "$scope" ] || die "usage: intelligence registry remove @scope"
+        require_v2
+        qmap_delete_key "$IP_ROOT/intelligence.yaml" "registries" "$scope"
+        echo "unbound $scope"
+        ;;
+    *)
+        die "usage: intelligence registry <list | add @scope <url> | remove @scope>"
+        ;;
+esac

package/cli/commands/remove.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# intelligence remove <@scope/name> [--no-sync]
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+name="${1:-}"
+[ -n "$name" ] || die "usage: intelligence remove <@scope/name>"
+shift || true
+no_sync=0
+for a in "$@"; do
+    case "$a" in
+        --no-sync) no_sync=1 ;;
+        *) die "unknown option '$a'" ;;
+    esac
+done
+
+require_v2
+assert_valid_pkg_name "$name"
+manifest="$IP_ROOT/intelligence.yaml"
+lock="$IP_ROOT/intelligence.lock"
+rel=".intelligence/packages/$name"
+
+known=0
+while IFS= read -r k; do
+    [ "$k" = "$name" ] && known=1
+done < <(qmap_keys "$manifest" "packages")
+[ "$known" -eq 1 ] || die "package '$name' is not in the manifest"
+
+unwire_package_sources "$manifest" "$rel"
+qmap_delete_key "$manifest" "packages" "$name"
+lock_remove "$lock" "$name"
+rm -rf "${IP_ROOT:?}/$rel"
+# Drop the now-empty scope dir so the store stays tidy.
+rmdir "$IP_ROOT/.intelligence/packages/${name%%/*}" 2>/dev/null || true
+echo "- $name"
+
+if [ "$no_sync" -eq 0 ]; then
+    exec bash "$CLI_DIR/commands/sync.sh"
+fi

package/cli/commands/status.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# intelligence status — project state at a glance.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+detect_project
+case "$IP_MODE" in
+    v2)
+        echo "Project:  $IP_ROOT (CLI setup)"
+        echo "Manifest: intelligence.yaml (sync_version $(read_engine_stamp "$IP_ROOT/intelligence.yaml"))"
+        if [ -f "$IP_ROOT/intelligence.lock" ]; then
+            echo "Lockfile: intelligence.lock"
+        else
+            echo "Lockfile: none (no packages added yet)"
+        fi
+        if [ -f "$IP_ROOT/.intelligence/engine/.version" ]; then
+            echo "Store:    .intelligence/engine at $(tr -d ' \t\r\n' < "$IP_ROOT/.intelligence/engine/.version")"
+        else
+            echo "Store:    not staged — run 'intelligence install'"
+        fi
+        echo "Engine:   $(bundled_engine_version) (bundled)"
+        ;;
+    legacy)
+        echo "Project:  $IP_ROOT (vendored v1 setup)"
+        echo "Umbrella: $IP_UMBRELLA"
+        echo "Engine:   $(tr -d ' \t\r\n' < "$IP_MODULE_DIR/scripts/VERSION") (vendored at $IP_MODULE_DIR)"
+        echo "Stamp:    $(read_engine_stamp "$IP_UMBRELLA/config.yaml")"
+        echo ""
+        echo "Convert to the CLI setup: intelligence migrate"
+        ;;
+    *)
+        echo "No intelligence project here. Start one: intelligence init"
+        ;;
+esac

package/cli/commands/sync.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# intelligence sync [target] — render intelligence to every enabled tool.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+detect_project
+case "$IP_MODE" in
+    v2)
+        ensure_engine_staged "$IP_ROOT"
+        export_engine_env "$IP_ROOT"
+        exec bash "$IS_ENGINE_DIR/scripts/sync.sh" "$@"
+        ;;
+    legacy)
+        # A vendored project syncs with ITS engine — its pin is the contract,
+        # and a newer bundled engine must not generate against an older schema.
+        echo "NOTE: vendored (v1) setup — delegating to its own engine. 'intelligence migrate' converts it to the CLI setup." >&2
+        exec bash "$IP_MODULE_DIR/scripts/sync.sh" "$@"
+        ;;
+    *)
+        die "no intelligence project found here — run 'intelligence init'"
+        ;;
+esac

package/cli/commands/update.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# intelligence update [name] [--no-sync]
+#
+# 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
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --no-sync) no_sync=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 checked=0
+while IFS= read -r name; do
+    [ -n "$name" ] || continue
+    [ -n "$only" ] && [ "$name" != "$only" ] && continue
+    ref="$(qmap_field "$manifest" "packages" "$name" "ref")"
+    [ -n "$ref" ] && { echo "  $name: pinned to ref '$ref' — skipped"; continue; }
+    range="$(qmap_field "$manifest" "packages" "$name" "version")"
+    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
+    checked=$((checked + 1))
+    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")"
+    if [ "$tag" = "$current" ]; then
+        echo "  $name: ${current:-<none>} (up to date)"
+        continue
+    fi
+    rel=".intelligence/packages/$name"
+    sha="$(fetch_package "$url" "$tag" "$path" "$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" ] && [ "$checked" -eq 0 ] && die "package '$only' is not in the manifest"
+echo "updated: $moved package(s)"
+
+if [ "$moved" -gt 0 ] && [ "$no_sync" -eq 0 ]; then
+    exec bash "$CLI_DIR/commands/sync.sh"
+fi

package/cli/commands/upgrade.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# intelligence upgrade — bring the project to this CLI's engine: restage the
+# engine content, apply v2 schema migrations (none yet — the chain starts
+# empty by design), restamp sync_version, sync.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+require_v2
+manifest="$IP_ROOT/intelligence.yaml"
+
+stamp="$(read_engine_stamp "$manifest")"
+eng="$(bundled_engine_version)"
+if [ -n "$stamp" ] && _ver_gt "$stamp" "$eng"; then
+    die "manifest schema $stamp is newer than this CLI's engine $eng — update the CLI first: npm i -g @ainova-systems/intelligence@latest"
+fi
+
+# v2 schema migrations live HERE, not in the engine's chain (that one owns
+# vendored layouts). Same discipline: ascending, append-only, each migration
+# self-detects and no-ops when already applied.
+# V2_MIGRATIONS=( )  — first entry arrives with the first breaking v2 change.
+
+stage_engine_content "$IP_ROOT/.intelligence/engine"
+echo "  engine content restaged ($eng)"
+stamp_version "$manifest" "$eng"
+echo "  sync_version -> $eng"
+
+exec bash "$CLI_DIR/commands/sync.sh"

package/cli/intelligence

@@ -0,0 +1,71 @@
+#!/bin/bash
+# intelligence — the CLI for Intelligence Packages and the sync engine.
+#
+# Dispatcher only: each command lives in commands/<name>.sh so commands can be
+# ported to Node one at a time without touching the others. The engine is the
+# vendored bash engine bundled next to the CLI (npm package) or, when running
+# from the intelligence-sync repo itself, the repo's own module.
+
+set -euo pipefail
+
+CLI_DIR="$(cd "$(dirname "$0")" && pwd)"
+export CLI_DIR
+
+# Engine discovery, by role (scripts/sync.sh + scripts/VERSION), never by
+# guessing names beyond the two shipped layouts:
+#   1. npm package:  <pkg>/cli/intelligence + <pkg>/engine/scripts/
+#   2. this repo:    <repo>/cli/intelligence + <repo>/intelligence/sync/scripts/
+IS_ENGINE_DIR=""
+for _cand in "$CLI_DIR/../engine" "$CLI_DIR/../intelligence/sync"; do
+    if [ -f "$_cand/scripts/sync.sh" ] && [ -f "$_cand/scripts/VERSION" ]; then
+        IS_ENGINE_DIR="$(cd "$_cand" && pwd)"
+        break
+    fi
+done
+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
+    exit 1
+fi
+export IS_ENGINE_DIR
+
+cmd="${1:-}"
+case "$cmd" in
+    ""|help|-h|--help)
+        engine_ver="$(tr -d ' \t\r\n' < "$IS_ENGINE_DIR/scripts/VERSION")"
+        cat <<EOF
+intelligence — build, version and distribute AI agent intelligence
+(engine $engine_ver${INTELLIGENCE_NPM_VERSION:+, package $INTELLIGENCE_NPM_VERSION})
+
+Usage: intelligence <command> [args]
+
+  init                    Set up this project (manifest, content skeleton, targets)
+  add <spec>              Add a package: @scope/name[@range] | github:org/repo[#path] | git+<url>[@ref][#path]
+  remove <name>           Remove a package
+  install [--frozen]      Restore .intelligence/ exactly from intelligence.lock
+  update [name]           Re-resolve version ranges and rewrite the lockfile
+  upgrade                 Upgrade the project to this CLI's engine (restage + restamp)
+  list                    Installed packages with requested/locked versions
+  sync [target]           Render intelligence to every enabled tool (.claude, AGENTS.md, ...)
+  registry <list|add|remove>  Bind a scope to a registry index
+  migrate [--dry-run]     Convert a vendored (v1) setup to the CLI setup
+  doctor                  Check manifest, lockfile, store and engine consistency
+  status                  Project state at a glance
+  version                 Print CLI and engine versions
+EOF
+        exit 0
+        ;;
+    version|-v|--version)
+        engine_ver="$(tr -d ' \t\r\n' < "$IS_ENGINE_DIR/scripts/VERSION")"
+        echo "${INTELLIGENCE_NPM_VERSION:-$engine_ver} (engine $engine_ver)"
+        exit 0
+        ;;
+esac
+shift
+
+cmd_file="$CLI_DIR/commands/$cmd.sh"
+if [ ! -f "$cmd_file" ]; then
+    echo "ERROR: unknown command '$cmd'. Run 'intelligence help'." >&2
+    exit 1
+fi
+exec bash "$cmd_file" "$@"