githits-com · jlitola · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "GitHits plugins for Claude Code - code examples from global open source",
-    "version": "0.1.11"
+    "version": "0.2.0"
   },
   "plugins": [
     {

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "Code examples from global open source for developers and AI assistants",
   "author": {
     "name": "GitHits"

diff --git a/.plugin/plugin.json b/.plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "Code examples from global open source for developers and AI assistants",
   "author": {
     "name": "GitHits"

diff --git a/GEMINI.md b/GEMINI.md
@@ -4,7 +4,7 @@ Code examples from global open source for developers and AI assistants.
 
 ## Available Tools
 
-### search
+### get_example
 
 Find code examples from open source repositories.
 
@@ -16,7 +16,7 @@ Find code examples from open source repositories.
 
 ### search_language
 
-Look up supported programming language names. Use this before calling `search` to get the correct language identifier.
+Look up supported programming language names. Use this before calling `get_example` to get the correct language identifier.
 
 **Parameters:**
 
@@ -34,14 +34,14 @@ Rate a search result. Submit feedback after each search to improve future result
 
 ## When to Use
 
-Use `search` when:
+Use `get_example` when:
 
 - You are stuck or blocked on an implementation problem
 - You need up-to-date examples for an API, library, or framework
 - The user mentions GitHits or asks you to search for code examples
 - You encounter an error you cannot resolve from your training data
 
-Do not use `search` for:
+Do not use `get_example` for:
 
 - General knowledge questions that do not require code examples
 - Problems you can already solve confidently
@@ -60,12 +60,20 @@ Do not use `search` for:
 
 ## How to Search Well
 
-- Call `search_language` first to confirm the correct language name before calling `search`
+- Call `search_language` first to confirm the correct language name before calling `get_example`
 - Formulate queries as natural language questions (e.g., "How to stream responses with the Vercel AI SDK in Next.js")
 - Include specific error messages, library names, or API names when relevant
 - Keep queries focused: 3-4 technical terms maximum
 - Submit `feedback` after every search result you use or discard
 
+## Feature-Gated Tools
+
+When the authenticated token carries the `code_navigation` feature flag, GitHits
+also exposes indexed dependency/package tools such as `search`,
+`search_status`, `package_summary`, `package_vulnerabilities`,
+`package_dependencies`, `package_changelog`, `list_files`, `read_file`, and
+`grep_repo`.
+
 ## License Filtering
 
 Results respect license filtering by default. Three modes:

diff --git a/README.md b/README.md
@@ -82,7 +82,7 @@ For plugin-based hosts, install from npm/GitHub using your agent's plugin workfl
 - **GitHub Copilot**: supports Open Plugin components
 - **Gemini CLI**: supports `gemini-extension.json` and `GEMINI.md`
 
-That's it. Your assistant now has GitHits search tools, and on accounts with package/source access enabled it also gets dependency inspection tools.
+That's it. Your assistant now has GitHits example-search tools, and on accounts with package/source access enabled it also gets indexed dependency/package inspection tools.
 
 ## How It Works
 
@@ -92,7 +92,7 @@ Core tools available in every authenticated session:
 
 | Tool | Purpose |
 |---|---|
-| `search` | Find code examples by describing what you need in natural language |
+| `get_example` | Find canonical code examples by describing what you need in natural language |
 | `search_language` | Look up supported programming language names |
 | `feedback` | Rate search results to improve future quality |
 
@@ -102,16 +102,17 @@ When package/source access is enabled for the current token, GitHits also expose
 
 | Tool | Purpose |
 |---|---|
+| `search` | Unified indexed search across dependency/repository code, docs, and symbols |
+| `search_status` | Follow up a prior indexed `search` by `searchRef` |
 | `package_summary` | Quick package overview: version, license, downloads, quickstart, advisories |
 | `package_vulnerabilities` | CVE / OSV advisories for a package or specific version |
 | `package_dependencies` | Direct dependencies, dependency groups, and optional transitive graph |
 | `package_changelog` | Release notes / changelog entries for a package or GitHub repo |
-| `search_symbols` | Exact-token search inside indexed dependency source |
 | `list_files` | Discover what files a dependency or repo contains |
 | `read_file` | Read a dependency file by path |
 | `grep_repo` | Deterministic text grep across indexed dependency or repo files |
 
-These advanced tools remain feature-gated. The MCP server advertises them only when the authenticated token is entitled to package/source access.
+These advanced tools remain feature-gated. The MCP server advertises them only when the authenticated token explicitly carries the `code_navigation` feature flag.
 
 ### License Filtering
 
@@ -156,11 +157,16 @@ githits logout         Remove stored credentials
 githits mcp            Show setup instructions in a terminal; starts MCP server when piped
 githits mcp start      Always start MCP server (for use in MCP config files)
 githits auth status    Show current authentication status
+githits example        Get canonical code examples from global open source
+githits languages      List or filter supported language names
+githits feedback       Send feedback on a returned example
 ```
 
-When package/source access is enabled for the current token, two extra command groups are also available:
+When the current token explicitly carries `code_navigation`, these extra commands are also available:
 
 ```
+githits search ...     Unified indexed dependency/repository search
+githits search-status  Follow up a prior indexed search
 githits pkg ...        Package metadata: overview, advisories, deps, changelog
 githits code ...       Dependency source inspection: search, files, read, grep
 ```
@@ -173,14 +179,14 @@ githits code ...       Dependency source inspection: search, files, read, grep
 | `GITHITS_MCP_URL` | Override MCP server URL | `https://mcp.githits.com` |
 | `GITHITS_API_URL` | Override REST API URL | `https://api.githits.com` |
 | `GITHITS_CODE_NAV_URL` | Override package/source service URL | environment-specific |
-| `GITHITS_CODE_NAVIGATION` | Expose hidden `pkg` / `code` command groups locally | — |
+| `GITHITS_CODE_NAVIGATION` | Expose hidden `search` / `pkg` / `code` CLI surfaces locally for development | — |
 | `GITHITS_TELEMETRY` | Emit end-of-run timing spans to stderr for local profiling | — |
 
 ## Manual Setup
 
 If your tool is not in the supported `githits init` list, configure GitHits manually.
 
-The same MCP server command exposes both the core search tools and, when your token is entitled, the package/source inspection tools. No separate install is required.
+The same MCP server command exposes both the core example-search tools and, when your token carries `code_navigation`, the indexed package/source inspection tools. No separate install is required.
 
 Use this MCP server command in your tool's MCP config (the host/agent runs this command):
 

diff --git a/commands/example.md b/commands/example.md
@@ -0,0 +1,23 @@
+---
+description: Search for canonical code examples from open source via GitHits
+---
+
+# Example
+
+Search for code examples using GitHits for the query: "$ARGUMENTS"
+
+Use the GitHits MCP `get_example` tool with the user's query. The tool requires two
+parameters:
+
+- **query**: The user's search query, formulated in natural language.
+- **language**: The programming language. If the language is unclear from
+  context, use the `search_language` tool first to find the correct language
+  name.
+
+Optional parameter:
+
+- **license_mode**: `"strict"` (default, excludes copyleft), `"yolo"` (all
+  licenses), or `"custom"` (user's blocklist).
+
+Present the results clearly. After the user has reviewed the result, use the
+`feedback` tool to report whether the example was helpful.
diff --git a/commands/help.md b/commands/help.md
@@ -16,22 +16,27 @@ context summary:
 
 ## Slash Commands
 
-- `/githits:search <query>` — Search for code examples from open source.
+- `/githits:example <query>` — Search for canonical code examples from open source.
+- `/githits:search <query>` — Legacy alias for `/githits:example`.
 - `/githits:login` — Authenticate with your GitHits account.
 - `/githits:status` — Show your current authentication status.
 - `/githits:logout` — Remove stored credentials.
 - `/githits:help` — Show this help message.
 
 ## MCP Tools
 
-This plugin connects to the GitHits MCP server and exposes three tools:
+This plugin connects to the GitHits MCP server and always exposes three core tools:
 
-- **search** — Find code examples by describing what you need in natural
+- **get_example** — Find code examples by describing what you need in natural
   language. Requires `query` and `language` parameters.
 - **search_language** — Look up supported programming language names before
   searching.
 - **feedback** — Rate a search result to improve future quality.
 
+Additional indexed dependency/package tools such as `search`, `package_summary`,
+`list_files`, and `grep_repo` stay hidden unless the authenticated token carries
+the `code_navigation` feature flag.
+
 ## Authentication
 
 Run `npx -y githits login` to authenticate via browser, or set the

diff --git a/commands/search.md b/commands/search.md
@@ -1,12 +1,14 @@
 ---
-description: Search for code examples from open source via GitHits
+description: Legacy alias for GitHits example search
 ---
 
-# Search
+# Search (Legacy Alias)
 
-Search for code examples using GitHits for the query: "$ARGUMENTS"
+Use GitHits example search for the query: "$ARGUMENTS"
 
-Use the GitHits MCP `search` tool with the user's query. The tool requires two
+This slash command is the older alias for `/githits:example`.
+
+Use the GitHits MCP `get_example` tool with the user's query. The tool requires two
 parameters:
 
 - **query**: The user's search query, formulated in natural language.

diff --git a/docs/implementation/cli-commands.md b/docs/implementation/cli-commands.md
@@ -2,7 +2,7 @@
 
 ## Purpose
 
-The CLI exposes four primary top-level commands: `example`, `languages`, and `feedback` are always available, while `search` is capability-gated and surfaces unified dependency/repository search when package/source access is open for the current session. It also has capability-gated `code` and `pkg` command groups for lower-level dependency source inspection and package intelligence. All of these commands share business logic with the MCP tools through the same service interfaces and shared utilities, but format output for terminal consumption instead of MCP tool results.
+The CLI exposes three always-on top-level commands: `example`, `languages`, and `feedback`. Indexed dependency/package surfaces are capability-gated: top-level `search` / `search-status` plus the `code` and `pkg` command groups are shown only when the startup token explicitly carries `code_navigation`, or when `GITHITS_CODE_NAVIGATION=1` is set locally for development. All of these commands share business logic with the MCP tools through the same service interfaces and shared utilities, but format output for terminal consumption instead of MCP tool results.
 
 ## Commands
 
@@ -130,7 +130,7 @@ Finds functions, classes, modules, and doc sections inside an indexed dependency
 
 **Output.** Default terminal output leads each entry with `path:startLine-endLine [kind]`, followed by the symbol name and a 3-line dedented snippet. `--json` emits the shared success/error envelope also produced by the MCP `search_symbols` tool — see [`mcp-cli-parity.md`](./mcp-cli-parity.md) for the wire contract. The command is registered as `code search` with `code search-symbols` as a Commander alias.
 
-**Capability gate.** The `code` group is registered only when package/source access is available for the current session, when `GITHITS_CODE_NAVIGATION=1` is set for local override, or when stored auth is expired and the CLI cannot reliably pre-classify access.
+**Capability gate.** The `code` group is registered only when the startup token explicitly carries `code_navigation`, or when `GITHITS_CODE_NAVIGATION=1` is set for local override.
 
 **Troubleshooting.** Set `GITHITS_DEBUG=code-nav` to emit single-line JSON diagnostics to stderr on error paths. Include the output when filing an issue. Debug payloads never contain query text, tokens, or response bodies.
 
@@ -346,8 +346,8 @@ This is still the standard `grep(1)` contract even though the output includes fi
 CLI command (src/commands/search.ts)
   └─ searchAction(query, options, deps)
        ├─ requireAuth(deps)
-       └─ deps.githitsService.search(params)
-            └─ GitHitsServiceImpl makes REST API call
+       └─ deps.codeNavigationService.search(params)
+            └─ CodeNavigationServiceImpl makes package/source API call
 ```
 
 Each command follows this pattern:
@@ -361,9 +361,9 @@ Each command follows this pattern:
 | Shared Module | Used By |
 |---|---|
 | `GitHitsService` (via container) | `example`, `languages`, `feedback`, and always-on MCP tools |
-| `CodeNavigationService` (via container) | top-level unified `search` / `search-status`, capability-gated `search` MCP tools, and `githits code search` |
+| `CodeNavigationService` (via container) | top-level unified `search` / `search-status`, capability-gated MCP indexed-search tools, and `githits code search` |
 | `filterLanguages()` from `src/shared/language-filter.ts` | `search_language` MCP tool + `languages` CLI command |
-| `requireAuth()` from `src/shared/require-auth.ts` | MCP server startup + all CLI commands |
+| `requireAuth()` from `src/shared/require-auth.ts` | all CLI commands and auth-required MCP tool handlers |
 
 ## Adding a New CLI Command
 

diff --git a/docs/implementation/config.md b/docs/implementation/config.md
@@ -14,7 +14,7 @@ GitHits separates its MCP server (which handles OAuth discovery and the MCP prot
 |---|---|---|---|
 | **MCP URL** | `https://mcp.githits.com` | `GITHITS_MCP_URL` | OAuth discovery (`.well-known`), DCR registration, auth flow |
 | **API URL** | `https://api.githits.com` | `GITHITS_API_URL` | REST endpoints (`/search`, `/languages`, `/feedbacks`) |
-| **Package/source URL** | configured per environment | `GITHITS_CODE_NAV_URL` | Package/source service endpoint used by the hidden `pkg` / `code` tooling |
+| **Package/source URL** | `https://pkgseer.dev` in the default production environment; otherwise unset | `GITHITS_CODE_NAV_URL` | Package/source service endpoint used by hidden indexed `search` / `pkg` / `code` tooling |
 
 > **These are different services.** Setting only one won't work for custom environments. Both must be overridden together when pointing to a non-production backend.
 
@@ -28,7 +28,7 @@ The container (`src/container.ts`) resolves authentication in priority order:
 
 2. **Stored OAuth JWT** — Loaded from `~/.githits/auth.json`. If expired, the container automatically attempts a refresh using the stored refresh token. If refresh fails, auth is cleared silently.
 
-3. **Unauthenticated** — No token available. The MCP server refuses to start (`requireAuth()` in `src/commands/mcp.ts`). CLI commands like `auth status` still work to help the user diagnose the issue.
+3. **Unauthenticated** — No token available. Auth-required CLI commands fail on use, and the MCP server can start but every authenticated tool call will fail. Commands like `auth status` still work to help the user diagnose the issue.
 
 ### Auth Mode Capabilities
 
@@ -40,9 +40,10 @@ The container (`src/container.ts`) resolves authentication in priority order:
 
 Package/source access is different from the REST endpoints above:
 
-- the CLI resolves the package/source service URL from `GITHITS_CODE_NAV_URL`; custom GitHits environments must set this explicitly (no default inference)
-- MCP registration and the hidden `githits code` / `githits pkg` CLI groups are only exposed when package/source access is available for the current session, or when `GITHITS_CODE_NAVIGATION=1` is set locally for development
-- if access is unavailable, those tools and command groups are omitted from the surfaced interface
+- the CLI resolves the package/source service URL from `GITHITS_CODE_NAV_URL`; in the default production environment it falls back to `https://pkgseer.dev`, but custom GitHits environments must set this explicitly
+- MCP registration for `search`, `search_status`, `package_*`, `list_files`, `read_file`, and `grep_repo` happens only when the current token explicitly carries `code_navigation`
+- CLI registration for top-level `search` / `search-status` plus the hidden `githits code` / `githits pkg` groups uses the same capability check, with one local-development escape hatch: `GITHITS_CODE_NAVIGATION=1`
+- if the capability is absent or unknown, those indexed tools and command groups are omitted from the surfaced interface
 
 ## Environment Variables
 
@@ -52,7 +53,7 @@ Package/source access is different from the REST endpoints above:
 | `GITHITS_API_URL` | Override REST API URL | `http://localhost:8000` |
 | `GITHITS_CODE_NAV_URL` | Override package/source service URL | `http://localhost:4000` |
 | `GITHITS_API_TOKEN` | API token for authentication | `ghi-abc123...` |
-| `GITHITS_CODE_NAVIGATION` | Override capability gate and expose hidden `code` / `pkg` CLI groups locally | `1` |
+| `GITHITS_CODE_NAVIGATION` | Override capability gate and expose hidden indexed `search` / `code` / `pkg` CLI surfaces locally | `1` |
 | `GITHITS_TELEMETRY` | Emit end-of-run timing spans to stderr for local profiling | `1` |
 
 ## Local Storage
@@ -98,4 +99,4 @@ Commands receive the full `Dependencies` object. Services receive only what they
 | `src/services/auth-storage.ts` | File-based token storage with secure permissions |
 | `src/services/filesystem-service.ts` | File system abstraction for testable storage |
 | `src/commands/auth-status.ts` | Diagnosing current auth state (reached via `githits auth status`) |
-| `src/commands/mcp.ts` | Auth gate (see `requireAuth`) before MCP server startup |
+| `src/commands/mcp.ts` | MCP tool registration and deferred-auth startup behavior |