# 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):**
```bash
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](https://github.com/neuledge/context/blob/main/SERVER_SPEC.md):

- `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

```bash
# 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`.