holocron/.agents/skills/neuledge-context/SKILL.md

---
name: neuledge-context
description: "Use when the user wants to install @neuledge/context, register it as a Claude Code MCP server, manage documentation packages (install, browse, add, remove, list), configure custom registries, or manage auth for private registries. Do NOT use when the user wants to install a different MCP server, wants to query docs from an already-running context server (call `get_docs` directly), or is setting up @neuledge/context for Cursor, VS Code Copilot, or Claude Desktop rather than Claude Code."
metadata:
  category: cross-cutting
allowed-tools:
  - Bash
  - Read
  - Edit
---

<requirements>

## Required inputs

- **Task type** — install / register-mcp / package-management / auth / upgrade / uninstall; inferred from user request, ask if ambiguous
- **Package name(s)** (package management only) — name(s) to install, add, or remove; ask if not stated
- **Library list** (project MCP scope only) — space-separated lib names for `--libs`; ask if not stated
- **Domain** (auth only) — domain to authenticate against; ask if not stated
- **Credential reference** (auth only) — environment variable or secret manager path holding the token or cookie; never the raw value

## Constraints

- Run `scripts/setup-neuledge-context.sh <VERSION>` for install and upgrade — never run `npm install -g @neuledge/context@latest`
- Run `scripts/secure-context-config.sh` immediately after every `context auth add` — never skip the permissions step
- Check `git --version` before running `context add` on a URL or GitHub source; skip the check for local `.db` file paths
- Never echo, repeat, or log auth token or cookie values — reference the environment variable name only
- Scope all steps to stdio mode; HTTP/Docker mode is documented in `references/http-mode.md`, not covered here
- State what you are about to do before running `setup-neuledge-context.sh` — it modifies global npm and Claude Code MCP config

</requirements>

<steps>

## Process

1. **Identify task.** Infer the task type from the user's request. If the request spans multiple tasks (e.g. install + package install), execute them in the order listed below.

2. **Install.** (Skip if `context --version` already returns the target version.)
   - State: "I will run `scripts/setup-neuledge-context.sh` from the ai-development repo root — this installs `@neuledge/context` globally at the pinned version."
   - Run: `bash scripts/setup-neuledge-context.sh` from `/root/ai-development/`
   - Verify: `context --version`
   - See `references/install-notes.md` for prerequisites and native SQLite build tool requirements.

3. **Register global MCP server.** (One-time per machine. Skip if already registered.)
   - Check: `claude mcp list | grep '^context '` — if output is non-empty, skip.
   - Run: `claude mcp add context -- context serve`
   - Confirm: `claude mcp list`

4. **Scope MCP to specific libraries (optional, per-project).** (When user wants to restrict the MCP session to pre-approved libraries for a project.)
   - Collect the library list from the user if not stated.
   - For each named library, run `context browse <name>` to confirm the exact package identifier (e.g. `react` vs `npm/react`, `next` vs `nextjs`). Use the identifier shown in the browse output — do not guess. If `context list` shows the package is already installed, that identifier is authoritative.
   - Run: `claude mcp add --project context -- context serve --libs <verified-id1> <verified-id2> ...`
   - Note: this overrides the global registration for the current project only. The `search_packages` and `download_package` MCP tools are hidden; only `get_docs` is available for the listed libraries.

5. **Manage packages.**
   - **Browse registry:** `context browse <name>` — shows available versions.
   - **Install from registry:** `context install <registry/name> [version]` — e.g. `context install npm/react`.
   - **Add from source:** Check `git --version` first if source is a URL or GitHub repo. Run: `context add <source> [--path <docs-path>] [--tag <tag>] [--name <name>]`. See `references/context-cli-reference.md` for all flags.
   - **List installed:** `context list`
   - **Remove:** `context remove <name>@<version>` to target a specific version; `context remove <name>` removes all versions — confirm with the user before removing all.

6. **Configure auth.** (Private registries or subscriber-only content.)
   - Run: `context auth add <domain> --header "Authorization: Bearer $TOKEN"` — use the environment variable name, not the value.
   - Immediately run: `bash scripts/secure-context-config.sh` from `/root/ai-development/`

7. **Configure custom registry.** (Self-hosted registry server.)
   - Read `~/.context/config.json`. Add a server entry following the schema in `references/context-cli-reference.md`.
   - Test: `context browse <package> --server <name>`

8. **Upgrade.** Run `bash scripts/setup-neuledge-context.sh <TARGET_VERSION>` from `/root/ai-development/`. The script checks the current version and skips if already at target.

9. **Uninstall.**
   - Run: `npm uninstall -g @neuledge/context`
   - Ask the user before removing downloaded packages: `rm -rf ~/.context` deletes all installed documentation and config — confirm before running.

## Output format

No structured output file. The skill produces terminal confirmation of each completed step. Artifacts:
- `@neuledge/context` installed globally at pinned version
- MCP server entry in `~/.claude/settings.json` (global) or `.claude/settings.local.json` (project)
- Downloaded `.db` packages in `~/.context/packages/`
- Modified `~/.context/config.json` (auth entries, registry config)

</steps>

<checks>

## Failure handling

- `scripts/setup-neuledge-context.sh` not found — stop; instruct user to run from `/root/ai-development/`
- `context` binary not found after install — report npm error; check `node --version` is ≥18
- MCP registration fails — run `claude mcp list` to check for name conflicts; if `context` is already registered with different args, report it and ask the user to remove it first with `claude mcp remove context`
- `context add` fails with "git not found" — advise `apt-get install git` (Debian/Ubuntu) or equivalent; re-run after install
- Native SQLite build failure — Context falls back to WASM automatically; advise installing build tools for better performance: `apt-get install -y python3 make g++` on Debian/Ubuntu. See `references/install-notes.md` for known gotchas.

## Self-check

- [ ] Task type identified before any commands run
- [ ] `setup-neuledge-context.sh` announced before execution
- [ ] `claude mcp list` checked before `claude mcp add` — skipped if already registered
- [ ] `git --version` checked before `context add` on a URL or GitHub source
- [ ] Auth step: `secure-context-config.sh` run immediately after every `context auth add`
- [ ] No credential values echoed or logged — environment variable references only
- [ ] `context remove <name>@<version>` used (not bare name) when targeting a specific version
- [ ] `rm -rf ~/.context` confirmed with user before running

</checks>