holocron/.agents/skills/neuledge-context/references/install-notes.md

Install Notes

Prerequisites

• Node.js LTS (≥18)
• npm — pnpm/yarn also work

No other system dependencies are required. The package uses a WASM SQLite fallback (sql.js-fts5) if the native better-sqlite3 module fails to build — but native mode is significantly faster.

For native SQLite (recommended on Linux servers):

apt-get install -y python3 make g++   # Debian/Ubuntu

---

File Locations

Path	Purpose
~/.context/packages/	Downloaded/built SQLite package files (name@version.db)
~/.context/config.json	Server configuration (registries, auth credentials)

Both directories are created automatically on first use.

---

Self-Hosted Registry Server

Anyone can operate a compatible registry implementing the Download Server API:

• GET /search?registry=<r>&name=<n>[&version=<v>] — search packages
• GET /packages/<registry>/<name>/<version> — package metadata
• GET /packages/<registry>/<name>/<version>/download — download .db file
• POST /packages/<registry>/<name>/<version> — publish (requires Bearer token)

Register a custom server in ~/.context/config.json and reference it with --server <name>.

---

Upgrade / Uninstall

# Upgrade — pass the target version to the install script
bash scripts/setup-neuledge-context.sh <VERSION>

# Uninstall binary
npm uninstall -g @neuledge/context

# Remove all downloaded packages and config (optional — confirm with user first)
rm -rf ~/.context

No migration needed on upgrade — .db package files are not affected by CLI version changes.

---

Known Gotchas

1. Native build failure — If better-sqlite3 fails to compile (missing Python/g++), Context falls back to WASM automatically. Queries still work but are slower. Install build tools to fix.

2. Package naming — context remove next removes all versions of next. Use next@v16.2.0 to target a specific version.

3. context add for git repos — Requires git to be installed. Clones the full repo; use --path to limit to a docs subdirectory and --tag to pin a version.

4. Registry package IDs — Registry identifiers follow <ecosystem>/<name> format (e.g. npm/react, pip/fastapi, cargo/tokio). The browse command accepts bare names (react) and infers the registry.

5. --libs restriction — When context serve --libs react next, the search_packages and download_package MCP tools are hidden from the agent. Only get_docs is available, scoped to the listed libraries.

6. No releases on GitHub — The project publishes via npm directly. Check npm view @neuledge/context version for the current version.

7. Auth cookies/headers — Stored in ~/.context/config.json as plain JSON. File permissions matter — always run scripts/secure-context-config.sh after context auth add.