fix(skills): update neuledge-context with session lessons

- Fix claude mcp add scope flag: -s user for global, -s project for
  per-project --libs (--project flag does not exist)
- Project scope writes to .mcp.json (committed); not settings.local.json
- Document dual-scope pattern and expected conflict warning
- Document MCP tools not available mid-session after claude mcp add;
  require /reload-plugins or new session
- Expand context add step with llms.txt-first workflow for registry gaps
  (Anthropic, Claude Code, MCP docs not in public registry)
- Fix self-check: explicit scope flag required, context list for identifiers
- Add .mcp.json with project-scoped context serve --libs for this repo

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TP4EGbBg3XMcyF28Lx78XJ

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

@@ -42,22 +42,32 @@ allowed-tools:
    - 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.)
+3. **Register global MCP server.** (One-time per machine. Skip if already registered at user scope.)
    - Check: `claude mcp list | grep '^context '` — if output is non-empty, skip.
-   - Run: `claude mcp add context -- context serve`
+   - Run: `claude mcp add -s user context -- context serve`
    - Confirm: `claude mcp list`
+   - Note: the default scope for `claude mcp add` is `local` (machine-specific, not shared). Always pass `-s user` for global availability across all projects.
+   - Note: MCP tools (`search_packages`, `get_docs`, `download_package`) only appear in the active session after `/reload-plugins` or starting a new session — they are not immediately available mid-session after registration.
 
 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.
+   - Verify each identifier: run `context list` for already-installed packages (authoritative) or `context browse <name>` for registry packages. Do not guess identifiers.
+   - Run: `claude mcp add -s project context -- context serve --libs <verified-id1> <verified-id2> ...`
+   - This writes to `.mcp.json` in the project root — commit this file to share the scope with the team.
+   - If both user and project scopes exist for the same server name, Claude Code will warn about dual registration — this is expected. Project scope overrides user scope within the project directory.
+   - Note: with `--libs`, 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.
+   - **Browse registry:** `context browse <name>` — shows available versions. The public registry is JS/frontend-focused; key AI/agent packages (Anthropic SDK, Claude Code, MCP SDK) are absent — use `context add` for those.
    - **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`
+   - **Add from source (for registry gaps):** Many docs sites publish `llms.txt`; prefer that over cloning. Check `<url>/llms.txt` or `<url>/llms-full.txt` before falling back to GitHub. Check `git --version` first if source is a GitHub repo URL.
+     ```bash
+     context add https://docs.anthropic.com --name claude-docs          # llms.txt site
+     context add https://modelcontextprotocol.io --name mcp-docs        # llms.txt site
+     context add https://github.com/org/repo --path docs --name mylib   # GitHub repo
+     ```
+     See `references/context-cli-reference.md` for all flags.
+   - **List installed:** `context list` — use this to get the exact installed identifier for `--libs`.
    - **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.)
@@ -78,7 +88,7 @@ allowed-tools:
 
 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)
+- MCP server entry in user config (global, `-s user`) or `.mcp.json` in project root (project-scoped, `-s project`, committed to repo)
 - Downloaded `.db` packages in `~/.context/packages/`
 - Modified `~/.context/config.json` (auth entries, registry config)
 
@@ -90,7 +100,9 @@ No structured output file. The skill produces terminal confirmation of each comp
 
 - `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`
+- MCP registration fails — run `claude mcp list` to check for name conflicts; if `context` is registered with different args or at the wrong scope, remove with `claude mcp remove context -s <scope>` and re-add at the correct scope
+- MCP tools not visible after registration — `claude mcp add` mid-session does not immediately expose tools; run `/reload-plugins` or start a new session
+- Dual-scope warning after adding project scope — expected when user and project scopes both define `context`; project takes precedence in the project directory. Remove the unwanted scope with `claude mcp remove context -s <scope>`
 - `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.
 
@@ -98,7 +110,10 @@ No structured output file. The skill produces terminal confirmation of each comp
 
 - [ ] 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
+- [ ] `claude mcp list` checked before `claude mcp add` — skipped if already registered at correct scope
+- [ ] `-s user` used for global registration; `-s project` used for `--libs` project scope — never relied on default (`local`) scope
+- [ ] `context list` used to get authoritative identifiers before composing `--libs`
+- [ ] `.mcp.json` noted for commit when project scope is added
 - [ ] `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