aicx 0.9.2

Operator CLI + MCP server: canonical corpus first, optional semantic index second (Claude Code, Codex, Gemini)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# AICX Install Paths

This document maps the supported binary install channels and the shadow checks
that keep `PATH` from resolving an older `aicx`.

## Install Surface

```text
release bundle / install.sh
  -> ~/.local/bin/aicx
  -> ~/.local/bin/aicx-mcp

local source / install.sh
  -> ${CARGO_INSTALL_ROOT:-~/.cargo}/bin/aicx
  -> ${CARGO_INSTALL_ROOT:-~/.cargo}/bin/aicx-mcp

make install-bin
  -> ${CARGO_INSTALL_ROOT:-~/.cargo}/bin/aicx
  -> ${CARGO_INSTALL_ROOT:-~/.cargo}/bin/aicx-mcp

npm @loctree/aicx
  -> npm global bin shim for aicx
  -> npm global bin shim for aicx-mcp
  -> node_modules/@loctree/aicx-<platform>/aicx
  -> node_modules/@loctree/aicx-<platform>/aicx-mcp
```

## Channels

| Channel | Trigger | Target | Shadow behavior |
|---|---|---|---|
| Release bundle | `bash install.sh` from a release archive | `~/.local/bin` | removes older/equal cargo-bin and npm-bin shadows |
| Release download | `AICX_INSTALL_MODE=release bash install.sh` | `~/.local/bin` | delegates to bundle mode after checksum verification |
| Local source | `bash install.sh` in a checkout | cargo bin dir | removes older/equal `~/.local/bin` and npm-bin shadows |
| Make source | `make install-bin` | cargo bin dir | runs the same shell shadow check before `cargo install` and PATH check after |
| npm package | `npm install -g @loctree/aicx` | npm global package/bin surface | warns by default; removes older/equal local/cargo shadows only with `AICX_NPM_REPLACE_LOCAL=1` |

## Pre-install Scan

Shell installers run a preflight inventory:

```bash
which -a aicx
```

Each path is probed with `--version` when executable. If multiple binaries are
visible, or the current `PATH` winner is not the target install path, interactive
installs ask for confirmation. Automation can set:

```bash
AICX_INSTALL_FORCE=1 bash install.sh
```

Dry-run mode is available for audits:

```bash
bash install.sh --dry-run
AICX_INSTALL_MODE=local bash install.sh --dry-run
```

## Cleanup Rules

Cleanup is conservative and version-aware:

1. The candidate path must contain `aicx`.
2. The candidate and target versions must parse as `major.minor.patch`.
3. The candidate version must be older than or equal to the target version.
4. `aicx` and `aicx-mcp` are removed together from that directory.

Newer shadows are retained and reported. Unknown-version shadows are retained
because the installer cannot prove that removal is safe.

## Post-install Sanity

After shell installs, `install.sh` compares:

```bash
<target>/aicx --version
command -v aicx
aicx --version
```

If the versions or paths differ, the installer prints a warning with the target
path, the `PATH`-resolved path, and all other `which -a aicx` entries. The fix is
to move the target directory earlier in `PATH` or remove the older channel.

## npm Opt-in Replacement

npm postinstall cannot safely prompt, so it warns by default. To let npm remove
older or equal local shadows during installation:

```bash
AICX_NPM_REPLACE_LOCAL=1 npm install -g @loctree/aicx
```

The npm cleanup only targets:

- `~/.local/bin/aicx`
- `~/.local/bin/aicx-mcp`
- `~/.cargo/bin/aicx`
- `~/.cargo/bin/aicx-mcp`

It does not uninstall other npm packages or rewrite shell startup files.

## Release Version Gate

Before release, run:

```bash
bash tools/release-channel-check.sh
```

The script compares `Cargo.toml`, the root npm package, all platform package
versions, and root npm optional dependency pins. Release CI runs the same check
before publishing artifacts.