@ainova-systems/intelligence 0.18.1 → 0.20.0

package/cli/commands/init.sh

@@ -84,7 +84,11 @@ print_new_project_onboarding() {
     echo "    intelligence adapter disable cursor"
     echo "  Version control:"
     echo "    Generated adapter output is gitignored by CLI-owned path."
-    echo "    Commit intelligence.yaml, intelligence.lock, intelligence/, AGENTS.md, and .github/."
+    echo "    Commit intelligence.yaml, intelligence.lock, intelligence/, and AGENTS.md."
+    if [ "$(is_target_enabled "$manifest" copilot)" = "1" ]; then
+        echo "    Copilot on github.com reads the repository, not a sync: to commit its output, set"
+        echo "    targets.copilot.commit_output: true, then run intelligence init."
+    fi
     echo "    Existing .vscodeignore, .npmignore, and .dockerignore files receive packaging exclusions."
     echo "    Shared tool settings remain trackable; review the exact ownership policy:"
     echo "    https://github.com/ainova-systems/intelligence/blob/main/packages/sync/references/conventions.md#generated-output-and-version-control"
@@ -296,6 +300,7 @@ manifest="$root/intelligence.yaml"
     echo "#                                      its stack, and the constraints to respect"
     echo "#   $content_dir/agents/<name>.md      a persona (frontmatter: name, description,"
     echo "#                                      tier: frontier|heavy|standard|light,"
+    echo "#                                      effort: low|medium|high|xhigh|max|ultra,"
     echo "#                                      access: full|readonly)"
     echo "#   $content_dir/skills/<name>/SKILL.md  a procedure invoked as /<name>"
     echo "# '.intelligence/' is CLI-managed (packages + engine content) — never edit it."

package/cli/commands/package.sh

@@ -1,10 +1,10 @@
 #!/bin/bash
-# intelligence package <add|remove|list|search> ...
+# intelligence package <add|remove|alias|list|search> ...
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
 action="${1:-}"
-[ -n "$action" ] || die "usage: intelligence package <add|remove|list|search> [args]"
+[ -n "$action" ] || die "usage: intelligence package <add|remove|alias|list|search> [args]"
 shift
 
 case "$action" in
@@ -18,6 +18,11 @@ case "$action" in
         ensure_project_current "$IP_ROOT"
         exec bash "$CLI_DIR/internal/package-remove.sh" "$@"
         ;;
+    alias)
+        require_cli_project
+        ensure_project_current "$IP_ROOT"
+        exec bash "$CLI_DIR/internal/package-alias.sh" "$@"
+        ;;
     list)
         exec bash "$CLI_DIR/internal/package-list.sh" "$@"
         ;;
@@ -25,6 +30,6 @@ case "$action" in
         exec bash "$CLI_DIR/internal/package-search.sh" "$@"
         ;;
     *)
-        die "usage: intelligence package <add|remove|list|search> [args]"
+        die "usage: intelligence package <add|remove|alias|list|search> [args]"
         ;;
 esac

package/cli/commands/registry.sh

@@ -51,7 +51,7 @@ case "$sub" in
             echo "  index.yaml reachable — $n package(s):"
             qmap_keys "$index" "packages" | sed 's/^/    /'
         elif [ "$force" -eq 1 ]; then
-            echo "  WARN: no index.yaml at $url — recording anyway (--force)." >&2
+            echo "WARNING: no index.yaml at $url — recording anyway (--force)." >&2
         else
             echo "ERROR: no index.yaml found at $url — not adding it." >&2
             echo "  A registry is a git repo with index.yaml at its root, mapping names to sources:" >&2

package/cli/commands/source.sh

@@ -10,8 +10,11 @@
 # that ships it) belongs after the store entries and before the project's.
 #
 # Installed package content is NOT managed here: `.intelligence/` entries are
-# written by `package add` and removed by `package remove`, and a hand-placed
-# entry under the store does not survive the next lifecycle alignment.
+# written by `package add` and removed by `package remove`, and so are the
+# entries that name a package's directory by its full name or alias
+# (`@scope/name/<dir>`, `<alias>:<dir>`, decision 0019). Any of those spellings
+# is still a valid `--before` / `--after` anchor: that is how a directory lands
+# next to a package.
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
@@ -36,11 +39,32 @@ assert_source_section() {
 # repaired — a source entry decides which artifact wins, so a path the user did
 # not type is the wrong kind of help.
 
+# assert_not_package_reference <manifest> <dir> <add|remove> — refuse an entry
+# the engine reads as a package reference: a directory of a package `packages:`
+# declares, by full name or alias, or an alias no package declares. It is
+# package territory however it is spelled.
+assert_not_package_reference() {
+    local state rendered rest pkg
+    IFS=$'\037' read -r state rendered <<< "$(sources_classify_entry "$1" "$2")"
+    rest="${rendered#.intelligence/packages/}"
+    pkg="${rest%%/*}/"
+    rest="${rest#*/}"
+    pkg="$pkg${rest%%/*}"
+    case "$state/$3" in
+        path/*) return 0 ;;
+        ok/add) die "'$2' names a directory of the installed package $pkg — 'intelligence package add' wires a package's directories into sources" ;;
+        ok/remove) die "'$2' is installed package content — remove the package instead: intelligence package remove $pkg" ;;
+        */add) die "'$2' is a package reference, not a project directory — 'intelligence package add' wires a package's directories into sources" ;;
+        *) die "'$2' is a package reference, not a project directory — 'intelligence package remove <@scope/name>' removes a package's entries" ;;
+    esac
+}
+
 # assert_valid_source_dir <root> <dir> — refuse what the engine cannot report.
 # The shape checks are `source_entry_problem`, shared with `status --check` so
 # one definition covers both the entry about to be written and the one already
-# in the manifest; the store rule is this command's alone, because a
-# `.intelligence/` entry is legitimate when `package add` wrote it.
+# in the manifest; the package rules are this command's alone, because a
+# package entry is legitimate when `package add` wrote it or a person spelled
+# it by the package's name.
 assert_valid_source_dir() {
     local root="$1" dir="$2" problem
     [ -n "$dir" ] || die "$USAGE"
@@ -50,26 +74,34 @@ assert_valid_source_dir() {
             die "'$dir' is inside the CLI-managed package store — install content with 'intelligence package add', and it is wired into sources automatically"
             ;;
     esac
+    assert_not_package_reference "$root/intelligence.yaml" "$dir" add
     problem="$(source_entry_problem "$root" "$dir")"
     [ -z "$problem" ] || die "invalid source '$dir': it $problem"
 }
 
 # Print one section with its override direction and the state of each entry.
 # Position is the whole point of the block, so every mutation ends by showing
-# the order it produced rather than only naming what it wrote.
+# the order it produced rather than only naming what it wrote. Entries are
+# listed as written and judged by the directory the engine renders them as.
 print_section() {
-    local manifest="$1" root="$2" section="$3" entry n=0 note
+    local manifest="$1" root="$2" section="$3" entry state dir n=0 note
     echo "sources.$section (a later entry overrides an earlier one):"
-    while IFS= read -r entry; do
+    [ -f "$manifest" ] || { echo "  (none)"; return 0; }
+    while IFS=$'\037' read -r entry state dir _; do
         [ -n "$entry" ] || continue
         n=$((n + 1))
         note=""
-        case "$entry" in
-            .intelligence/*) note="  package" ;;
+        case "$state" in
+            path|ok)
+                case "$dir" in
+                    .intelligence/*) note="  package" ;;
+                esac
+                [ -d "$root/$dir" ] || note="$note  MISSING"
+                ;;
+            *) note="  UNRESOLVED — intelligence status --check" ;;
         esac
-        [ -d "$root/$entry" ] || note="$note  MISSING"
         printf '  %d. %s%s\n' "$n" "$entry" "$note"
-    done < <(sources_list_entries "$manifest" "$section")
+    done < <(read_source_entries "$manifest" "$section")
     [ "$n" -eq 0 ] && echo "  (none)"
     return 0
 }
@@ -110,10 +142,16 @@ case "$action" in
         ensure_project_current "$IP_ROOT"
         manifest="$IP_ROOT/intelligence.yaml"
 
-        if [ -n "$anchor" ] && ! sources_has_entry "$manifest" "$section" "$anchor"; then
-            echo "ERROR: sources.$section does not list '$anchor'." >&2
-            print_section "$manifest" "$IP_ROOT" "$section" >&2
-            exit 1
+        # The anchor may be spelled differently from the entry it means — a
+        # package's store path, full name or alias — so it is matched by the
+        # directory it names and placed against the entry as written.
+        if [ -n "$anchor" ]; then
+            if ! listed="$(sources_find_entry "$manifest" "$section" "$anchor")"; then
+                echo "ERROR: sources.$section does not list '$anchor'." >&2
+                print_section "$manifest" "$IP_ROOT" "$section" >&2
+                exit 1
+            fi
+            anchor="$listed"
         fi
 
         if sources_has_entry "$manifest" "$section" "$dir"; then
@@ -130,7 +168,7 @@ case "$action" in
             echo "added: $dir"
         fi
         if [ ! -d "$IP_ROOT/$dir" ]; then
-            echo "  WARN: $dir does not exist yet — sync skips a missing source and renders it once the directory appears." >&2
+            echo "WARNING: $dir does not exist yet — sync skips a missing source and renders it once the directory appears." >&2
         fi
         print_section "$manifest" "$IP_ROOT" "$section"
         echo "Run 'intelligence sync' to render it."
@@ -149,8 +187,9 @@ case "$action" in
         esac
 
         require_cli_project
-        ensure_project_current "$IP_ROOT"
         manifest="$IP_ROOT/intelligence.yaml"
+        assert_not_package_reference "$manifest" "$dir" remove
+        ensure_project_current "$IP_ROOT"
 
         if ! sources_has_entry "$manifest" "$section" "$dir"; then
             echo "not listed: sources.$section does not hold $dir"

package/cli/commands/sync.sh

@@ -1,14 +1,27 @@
 #!/bin/bash
-# intelligence sync [target] [--compact] [--force] - render intelligence to enabled tools.
+# intelligence sync [target] [--compact] [--force] [--check] - render intelligence
+# to enabled tools, or report whether rendering would change anything.
 set -euo pipefail
 
+# Only sync_check may request a comparison from the engine.
+unset IS_SYNC_CHECK IS_SYNC_CHECK_ROOT
+
 # Print before library loading and lifecycle checks so a content verification
-# never looks idle. Compact output remains a buffered machine-readable report.
+# never looks idle. Compact output remains a buffered machine-readable report,
+# and a check prints only its verdict.
 compact=0
+check=0
 for argument in "$@"; do
-    [ "$argument" != --compact ] || compact=1
+    case "$argument" in
+        --compact) compact=1 ;;
+        --check) check=1 ;;
+    esac
 done
-[ "$compact" -ne 0 ] || echo 'Checking project...'
+[ "$compact" -ne 0 ] || [ "$check" -ne 0 ] || echo 'Checking project...'
+# The CLI's package descriptor is read in the same pass as the project's
+# manifest and lock, once this command holds the project lock.
+# shellcheck disable=SC2034  # read by cli-common.sh while it loads
+CLI_DEFER_SYNC_PKG=1
 source "$CLI_DIR/lib/cli-common.sh"
 force=0
 target=""
@@ -16,22 +29,35 @@ while [ $# -gt 0 ]; do
     case "$1" in
         --compact) compact=1 ;;
         --force) force=1 ;;
+        --check) check=1 ;;
         -*) die "unknown option '$1'" ;;
         *)
-            [ -z "$target" ] || die "usage: intelligence sync [adapter] [--compact] [--force]"
+            [ -z "$target" ] || die "usage: intelligence sync [adapter] [--compact] [--force] [--check]"
             target="$1"
             ;;
     esac
     shift
 done
 
+# Set where a check concludes that sync is needed, so a failure that happens to
+# end in the same status is never mistaken for that verdict.
+IS_CHECK_OUT_OF_DATE=0
+
+# hold_project — take the project lock, then read the package descriptor,
+# manifest and lock once for the whole preflight.
+hold_project() {
+    project_lock_hold "$IP_ROOT"
+    project_reads_preload "$IP_ROOT"
+    load_sync_package_identity
+}
+
 run_sync() {
     detect_project || return $?
     case "$IP_MODE" in
         cli)
             # One writer per project at a time: the store restore and the
             # render below both rewrite shared state (sync-lock.sh).
-            project_lock_hold "$IP_ROOT"
+            hold_project
             # `sync` is the normal fresh-clone command. A newer globally installed
             # CLI aligns the current Intelligence project first (except in CI, where a
             # tracked migration must be reviewed and committed locally), and a
@@ -42,6 +68,7 @@ run_sync() {
             sync_with_cache "$target" "$force" || return $?
             ;;
         legacy)
+            load_sync_package_identity
             [ "$force" -eq 0 ] || die "--force is unavailable for a legacy Intelligence Sync project - run 'intelligence init' to convert it first"
             [ "$compact" -eq 0 ] || die "--compact is unavailable for a legacy Intelligence Sync project - run 'intelligence init' to convert it first"
             # A vendored project syncs with its own engine: its pin is the
@@ -55,11 +82,56 @@ run_sync() {
             fi
             ;;
         *)
+            load_sync_package_identity
             die "no intelligence project found here - run 'intelligence init'"
             ;;
     esac
 }
 
+# run_check — the same preflight as sync, except that tracked alignment is never
+# applied (it is reported as needed, in CI or not) and everything but the
+# verdict goes to stderr. Restoring the ignored package store from the lock is
+# allowed: it is reproducible state, and the comparison needs it.
+run_check() {
+    local stamp
+    detect_project || return $?
+    case "$IP_MODE" in
+        cli) ;;
+        legacy)
+            load_sync_package_identity
+            die "--check is unavailable for a legacy Intelligence Sync project - run 'intelligence init' to convert it first"
+            ;;
+        *)
+            load_sync_package_identity
+            die "no intelligence project found here - run 'intelligence init'"
+            ;;
+    esac
+    hold_project
+    project_preflight "$IP_ROOT" || return $?
+    if project_needs_upgrade "$IP_ROOT"; then
+        read_schema_version_var "$IP_ROOT/intelligence.yaml"
+        stamp="$IS_SCHEMA_VERSION"
+        bundled_engine_version_var
+        IS_CHECK_OUT_OF_DATE=1
+        is_status out-of-date "the project needs alignment (stamp ${stamp:-unstamped}, engine $IS_BUNDLED_ENGINE_VERSION); run 'intelligence init --apply' locally, review and commit the diff"
+        return "$IS_RC_OUT_OF_DATE"
+    fi
+    restore_project_store_if_missing "$IP_ROOT" keep-sources >&2 || return $?
+    export_engine_env "$IP_ROOT" || return $?
+    sync_check "$target" "$force" || return $?
+}
+
+if [ "$check" -eq 1 ]; then
+    # --compact changes nothing here: the verdict is already one status line,
+    # and a failure's diagnostics already reach stderr.
+    rc=0
+    run_check || rc=$?
+    if [ "$rc" = "$IS_RC_OUT_OF_DATE" ] && [ "$IS_CHECK_OUT_OF_DATE" != 1 ]; then
+        rc=1
+    fi
+    exit "$rc"
+fi
+
 if [ "$compact" -eq 0 ]; then
     run_sync
     exit $?

package/cli/intelligence

@@ -11,7 +11,11 @@ case "$0" in
     */*) CLI_DIR="${0%/*}"; [ -n "$CLI_DIR" ] || CLI_DIR="/" ;;
     *) CLI_DIR="." ;;
 esac
-CLI_DIR="$(cd "$CLI_DIR" && pwd)"
+# An absolute spelling without `.` or `..` segments or doubled slashes is
+# already what `cd && pwd` prints; on Git Bash that subshell costs a fork.
+case "$CLI_DIR" in
+    */|*/./*|*/.|*/../*|*/..|*//*|[!/]*) CLI_DIR="$(cd "$CLI_DIR" && pwd)" ;;
+esac
 export CLI_DIR
 
 # Engine discovery, by role (sync.sh + VERSION). The repo and the npm package
@@ -52,16 +56,17 @@ Usage: intelligence <command> [args]
   init [--preview|--apply]  Initialize, convert, restore or align this project
     --targets a,b --dir name --bare --no-sync   New-project options
     --force               Accept a dirty worktree during legacy project conversion
-  sync [adapter] [--compact] [--force]  Restore locked content, then render enabled adapters
+  sync [adapter] [--compact] [--force] [--check]  Restore locked content, then render enabled adapters
     --compact            On success show context, warnings and final status; on failure show diagnostics
     --force              Render again and refresh discovery of unconfigured source directories
+    --check              Change no generated file; exit 0 when up to date, 2 when sync is needed
   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
+  package <command>       add | remove | alias | list | search
   source <command>        add | remove | list — the sources: block (own directories)
   adapter <command>       list | create | enable | disable | remove
   status [--check]        Project state; --check runs deep consistency checks
@@ -109,4 +114,12 @@ if [ ! -f "$cmd_file" ]; then
     echo "ERROR: unknown command '$cmd'. Run 'intelligence help'." >&2
     exit 1
 fi
+# `sync` runs on every save hook and CI check, so it runs in this process: a
+# second bash start is a large share of an unchanged sync on Git Bash. It
+# exits on every path and reads nothing of this script but the exports.
+if [ "$cmd" = sync ]; then
+    # shellcheck source=commands/sync.sh
+    source "$cmd_file"
+    exit $?
+fi
 exec bash "$cmd_file" "$@"

package/cli/internal/check.sh

@@ -119,6 +119,18 @@ while IFS= read -r name; do
     fi
 done < <(qmap_keys "$manifest" "packages")
 
+# Aliases name packages in sources: (decision 0019). One the engine would not
+# resolve, or one two packages state, leaves every <alias>:<dir> entry naming
+# nothing. An invalid alias is never echoed: it is manifest input that may hold
+# anything.
+while IFS=$'\037' read -r name alias verdict; do
+    [ -n "$name" ] || continue
+    case "$verdict" in
+        invalid) warn "$name declares an alias that is not one — expected $IS_PKG_ALIAS_RULE: intelligence package alias $name <alias>" ;;
+        ambiguous) warn "$name declares alias '$alias', which another package declares too — an alias names one package" ;;
+    esac
+done < <(read_package_aliases "$manifest")
+
 # Adapter contracts are the shared source of truth for dependencies, rollback,
 # onboarding backup and Git policy. Validate every declared target, including
 # disabled ones, so a later enable cannot reveal a stale custom adapter.
@@ -135,7 +147,7 @@ while IFS= read -r target; do
         warn "adapter '$target' is declared but its implementation is missing"
         continue
     fi
-    records="$(adapter_contract_records "$target" "$adapter_file" "$output" 2>/dev/null || true)"
+    records="$(adapter_contract_records "$target" "$adapter_file" "$output" "$manifest" 2>/dev/null || true)"
     if ! printf '%s\n' "$records" | grep -Fqx $'version\t1'; then
         warn "adapter '$target' has an invalid ownership contract"
         continue
@@ -150,18 +162,29 @@ while IFS= read -r target; do
             && [ "$(is_target_enabled "$manifest" "$value")" != "1" ]; then
             warn "enabled adapter '$target' requires enabled adapter '$value'"
         fi
+        # Presence is the writer's own test: a line `init` treats as present
+        # and leaves alone must not be reported missing here, or the warning
+        # can never clear — a CRLF .gitignore on Linux and macOS did exactly that.
         if [ "$(is_target_enabled "$manifest" "$target")" = "1" ]; then
             case "$kind" in
                 ignore)
-                    grep -Fqx -- "$value" "$IP_ROOT/.gitignore" 2>/dev/null \
-                        || warn "adapter '$target' Git policy is missing '$value'"
+                    ignore_file_has_line "$IP_ROOT/.gitignore" "$value" \
+                        || warn "adapter '$target' Git policy is missing '$value' — run 'intelligence init'"
+                    ;;
+                unignore)
+                    if gitignore_managed_has_line "$IP_ROOT" "$value"; then
+                        warn "adapter '$target' Git policy keeps '$value' tracked, but .gitignore still ignores it — run 'intelligence init'"
+                    fi
                     ;;
                 include)
-                    if ! grep -Fqx -- "!$value" "$IP_ROOT/.gitignore" 2>/dev/null; then
-                        warn "adapter '$target' Git policy is missing '!$value'"
+                    if ! ignore_file_has_line "$IP_ROOT/.gitignore" "!$value"; then
+                        warn "adapter '$target' Git policy is missing '!$value' — run 'intelligence init'"
                     elif git -C "$IP_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+                        # init moves the negation chain last, which beats any
+                        # later rule in .gitignore; a deeper .gitignore still
+                        # wins, so the finding also says how to find it.
                         if git -C "$IP_ROOT" check-ignore -q --no-index -- "$value"; then
-                            warn "adapter '$target' Git policy cannot re-include '$value' because another ignore rule still wins"
+                            warn "adapter '$target' Git policy cannot re-include '$value' because another ignore rule still wins — run 'intelligence init'; if it still wins, 'git check-ignore -v --no-index -- $value' names the rule"
                         else
                             ignore_rc=$?
                             [ "$ignore_rc" -eq 1 ] \
@@ -188,22 +211,50 @@ if [ "$lock_valid" -eq 1 ] && [ -f "$lock" ]; then
 fi
 
 # Sources must exist (a missing dir is silently skipped by the engine, which
-# is exactly why doctor names it).
+# is exactly why doctor names it). Each entry is judged by the directory the
+# engine renders it as, read through the same parser: a package reference by
+# its store path, one that resolves to nothing by why.
 for section in rules agents skills; do
-    while IFS= read -r src; do
+    seen=$'\n'
+    while IFS=$'\037' read -r src state dir alias holders; do
         [ -n "$src" ] || continue
+        case "$state" in
+            unknown|ambiguous|invalid)
+                source_reference_problem_var "$state" "$alias" "$holders"
+                case "$state" in
+                    unknown) warn "sources.$section '$src' $IS_SOURCE_PROBLEM — declare it with 'intelligence package alias <@scope/name> $alias', or correct the entry" ;;
+                    *) warn "sources.$section '$src' $IS_SOURCE_PROBLEM" ;;
+                esac
+                continue
+                ;;
+        esac
+        # One package directory under two spellings is listed twice, and the
+        # later one moves the package past every entry between them.
+        case "$dir" in
+            .intelligence/packages/*)
+                case "$seen" in
+                    *$'\n'"$dir"$'\037'*)
+                        first="${seen#*$'\n'"$dir"$'\037'}"
+                        first="${first%%$'\n'*}"
+                        [ "$first" = "$src" ] \
+                            || warn "sources.$section names $dir twice, as '$first' and as '$src' — keep one: where it stands decides which artifacts win"
+                        ;;
+                    *) seen="$seen$dir"$'\037'"$src"$'\n' ;;
+                esac
+                ;;
+        esac
         case "$src" in
-            git+*|@*) continue ;;
+            git+*) continue ;;
         esac
         # A hand-edited entry the engine cannot render is worse than a missing
         # one: it is skipped without a word and the sync still reports ok.
-        problem="$(source_entry_problem "$IP_ROOT" "$src")"
+        problem="$(source_entry_problem "$IP_ROOT" "$dir")"
         if [ -n "$problem" ]; then
             warn "sources.$section '$src' $problem"
             continue
         fi
-        if [ ! -d "$IP_ROOT/$src" ]; then
-            case "$src" in
+        if [ ! -d "$IP_ROOT/$dir" ]; then
+            case "$dir" in
                 # Store content is restorable state: absent means un-installed.
                 .intelligence/*)
                     if [ "$lock_valid" -eq 1 ]; then
@@ -219,7 +270,7 @@ for section in rules agents skills; do
                 *) ok "sources.$section '$src' — not created yet (optional)" ;;
             esac
         fi
-    done < <(read_yaml_list "$manifest" "$section")
+    done < <(read_source_entries "$manifest" "$section")
 done
 
 if [ "$problems" -eq 0 ]; then

package/cli/internal/convert-legacy.sh

@@ -435,7 +435,7 @@ while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
     # Containment before deletion: a mirror value is config input, and rm -rf
     # must never follow it out of the repository.
     case "$mirror" in
-        ""|/*|*..*) [ -n "$mirror" ] && echo "  WARN: mirror '$mirror' not repo-contained — left in place" >&2; continue ;;
+        ""|/*|*..*) [ -n "$mirror" ] && echo "WARNING: mirror '$mirror' not repo-contained — left in place" >&2; continue ;;
     esac
     if [ -d "$root/$mirror" ]; then
         rm -rf "${root:?}/$mirror"

package/cli/internal/package-add.sh

@@ -9,15 +9,18 @@ set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
 spec="${1:-}"
-[ -n "$spec" ] || die "usage: intelligence package add <@scope/name[@range] | github:org/repo[#path] | git+<url>[@ref][#path]>"
+[ -n "$spec" ] || die "usage: intelligence package add <@scope/name[@range] | github:org/repo[#path] | git+<url>[@ref][#path]> [--name @scope/name] [--alias <alias>] [--no-sync]"
 shift || true
 
 no_sync=0
 name_override=""
+alias_given=0
+alias_req=""
 while [ $# -gt 0 ]; do
     case "$1" in
         --no-sync) no_sync=1 ;;
         --name) shift; name_override="${1:-}" ;;
+        --alias) shift; alias_given=1; alias_req="${1:-}" ;;
         *) die "unknown option '$1'" ;;
     esac
     shift || true
@@ -77,6 +80,20 @@ esac
 [ -n "$name_override" ] && name="$name_override"
 assert_valid_pkg_name "$name"
 
+# The alias is settled before anything is fetched or written: a refusal leaves
+# the manifest, the lock and the store as they were. Re-adding a package keeps
+# the alias it declares unless --alias names another one, and never takes away
+# an alias `sources:` still spells entries with.
+alias="$(package_alias_of "$manifest" "$name")"
+if [ "$alias_given" -eq 1 ]; then
+    assert_valid_alias "$alias_req"
+    assert_alias_free "$manifest" "$name" "$alias_req"
+    if [ -n "$alias" ] && [ "$alias" != "$alias_req" ]; then
+        assert_alias_unused "$manifest" "$name" "$alias" replace
+    fi
+    alias="$alias_req"
+fi
+
 if [ "$mode" = "registry" ]; then
     resolve_package_source "$manifest" "$name"
     url="$RES_URL"; path="$RES_PATH"
@@ -129,8 +146,6 @@ rel=".intelligence/packages/$name"
 store_record_remove "$IP_ROOT" "$name"
 sha="$(fetch_package "$url" "${ref:-$resolved_tag}" "$path" "$IP_ROOT/$rel")"
 
-wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
-
 # The manifest records requested intent only. The resolved source URL/path,
 # tag/ref and SHA live in the required lock. Re-adding a package is the
 # explicit operation for changing its trusted source.
@@ -142,6 +157,12 @@ elif [ -n "$requested" ]; then
 else
     die "internal: package '$name' has neither a requested version nor ref"
 fi
+[ -z "$alias" ] || qmap_set "$manifest" "packages" "$name" "alias" "$alias"
+
+# Wired once the package and its alias are declared, so a section that already
+# names one of its directories as @scope/name/<dir> or <alias>:<dir> is left as
+# it stands instead of gaining the store path beside it.
+wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
 
 lock_upsert "$lock" "$name" "$requested" "$url" "$path" "${ref:-$resolved_tag}" "$sha"
 store_record_set "$IP_ROOT" "$name" "$url" "$path" "${ref:-$resolved_tag}" "$sha"
@@ -150,7 +171,7 @@ sections=""
 for s in rules agents skills; do
     [ -d "$IP_ROOT/$rel/$s" ] && sections="$sections $s"
 done
-echo "+ $name@${resolved_tag:-${ref:-HEAD}} (${sections# })"
+echo "+ $name@${resolved_tag:-${ref:-HEAD}} (${sections# })${alias:+ alias $alias}"
 
 if [ "$no_sync" -eq 0 ]; then
     exec bash "$CLI_DIR/commands/sync.sh"

package/cli/internal/package-alias.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Internal package alias operation: set, replace or remove the alias a package
+# declares in `packages:`. `sources:` spells that package's directories as
+# <alias>:<dir> (decision 0019); the alias is the CLI's to write, like the rest
+# of the block, and one alias names exactly one package.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+USAGE="usage: intelligence package alias <@scope/name> <alias>
+       intelligence package alias <@scope/name> --remove"
+
+[ $# -eq 2 ] || die "$USAGE"
+name="$1"
+want="$2"
+
+require_cli_project
+project_lock_hold "$IP_ROOT"
+manifest="$IP_ROOT/intelligence.yaml"
+assert_valid_pkg_name "$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 — 'intelligence package list' shows the declared ones"
+
+current="$(package_alias_of "$manifest" "$name")"
+
+if [ "$want" = "--remove" ]; then
+    # An entry can only spell a well-formed alias, so only a well-formed one can
+    # still be in use; a malformed one is dropped like any other.
+    [ -z "$current" ] || assert_alias_unused "$manifest" "$name" "$current" remove
+    if [ -z "$(qmap_field "$manifest" "packages" "$name" "alias")" ]; then
+        echo "$name declares no alias"
+        exit 0
+    fi
+    qmap_delete_field "$manifest" "packages" "$name" "alias"
+    echo "$name: alias removed"
+    exit 0
+fi
+
+case "$want" in -*) die "$USAGE" ;; esac
+assert_valid_alias "$want"
+if [ "$current" = "$want" ]; then
+    echo "$name: alias $want (unchanged)"
+    exit 0
+fi
+assert_alias_free "$manifest" "$name" "$want"
+[ -z "$current" ] || assert_alias_unused "$manifest" "$name" "$current" replace
+qmap_set "$manifest" "packages" "$name" "alias" "$want"
+echo "$name: alias $want — sources: may name its directories $want:<dir>"