Documentation gap
The README/install docs describe how to install cora but don't warn users that three distribution channels exist simultaneously and can conflict on the same machine:
- GitHub release binary (
~/.local/bin/cora or similar)
cargo install cora-cli (~/.cargo/bin/cora)
- npm
@codecora/cli (~/.bun/bin/cora or ~/.npm-global/bin/cora — currently v0.2.4, far behind)
Observed problem
On a real developer machine, all three were present simultaneously:
$ ls ~/.local/bin/cora ~/.cargo/bin/cora ~/.bun/bin/cora
/Users/mis-puragroup/.local/bin/cora # v0.6.0 (binary release, but killed by Gatekeeper)
/Users/mis-puragroup/.cargo/bin/cora # v0.6.0 (cargo build)
/Users/mis-puragroup/.bun/bin/cora # v0.2.4 (stale npm)
which cora resolved to whichever appeared first in $PATH, which in this case was the stale npm v0.2.4, silently — no warning, no error. The user thinks they're on the current version.
Suggested doc improvement
Add a short "Installation" section that:
- Lists all supported install methods and recommends one primary method per platform.
- Includes a "Check your install" snippet:
which cora && cora --version
# If you see anything other than the latest version (currently 0.6.0),
# remove the older binary or adjust your PATH.
- Warns that the npm package is currently stale (cross-link to the npm-staleness issue).
- Documents the macOS Gatekeeper workaround for the binary release (cross-link to the macOS-quarantine issue).
Context
Surfaced while trying to run cora scan on a downstream project and getting confusing results because v0.2.4 was silently being invoked. Cleaner install docs would have prevented a half-hour of debugging.
Documentation gap
The README/install docs describe how to install cora but don't warn users that three distribution channels exist simultaneously and can conflict on the same machine:
~/.local/bin/coraor similar)cargo install cora-cli(~/.cargo/bin/cora)@codecora/cli(~/.bun/bin/coraor~/.npm-global/bin/cora— currently v0.2.4, far behind)Observed problem
On a real developer machine, all three were present simultaneously:
which coraresolved to whichever appeared first in$PATH, which in this case was the stale npm v0.2.4, silently — no warning, no error. The user thinks they're on the current version.Suggested doc improvement
Add a short "Installation" section that:
Context
Surfaced while trying to run
cora scanon a downstream project and getting confusing results because v0.2.4 was silently being invoked. Cleaner install docs would have prevented a half-hour of debugging.