feat: make code navigation tools always available

GEMINI.md

@@ -66,13 +66,11 @@ Do not use `get_example` for:
 - Keep queries focused: 3-4 technical terms maximum
 - Submit `feedback` after every search result you use or discard
 
-## Feature-Gated Tools
+## Indexed Package/Source 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`.
+GitHits also exposes indexed dependency/package tools such as `search`,
+`search_status`, `docs_list`, `docs_read`, `pkg_info`, `pkg_vulns`,
+`pkg_deps`, `pkg_changelog`, `code_files`, `code_read`, and `code_grep`.
 
 ## License Filtering
 

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 example-search tools, and on accounts with package/source access enabled it also gets indexed dependency/package inspection tools.
+That's it. Your assistant now has GitHits example-search tools and indexed dependency/package inspection tools.
 
 ## How It Works
 
@@ -98,21 +98,21 @@ Core tools available in every authenticated session:
 
 The assistant decides when to call these tools on its own — typically when it's stuck, needs a working example for an unfamiliar API, or encounters an error it can't resolve from its training data alone.
 
-When package/source access is enabled for the current token, GitHits also exposes these capability-gated tools:
+GitHits also exposes indexed package/source tools:
 
 | 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 |
-| `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 explicitly carries the `code_navigation` feature flag.
+| `docs_list` | Browse mixed package documentation pages |
+| `docs_read` | Read a documentation page by page ID |
+| `pkg_info` | Quick package overview: version, license, downloads, quickstart, advisories |
+| `pkg_vulns` | CVE / OSV advisories for a package or specific version |
+| `pkg_deps` | Direct dependencies, dependency groups, and optional transitive graph |
+| `pkg_changelog` | Release notes / changelog entries for a package or GitHub repo |
+| `code_files` | Discover what files a dependency or repo contains |
+| `code_read` | Read a dependency file by path |
+| `code_grep` | Deterministic text grep across indexed dependency or repo files |
 
 ### License Filtering
 
@@ -162,12 +162,13 @@ githits languages      List or filter supported language names
 githits feedback       Send feedback on a returned example
 ```
 
-When the current token explicitly carries `code_navigation`, these extra commands are also available:
+These indexed package/source 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 docs ...       Package documentation: browse pages and read content
 githits code ...       Dependency source inspection: search, files, read, grep
 ```
 
@@ -178,15 +179,14 @@ githits code ...       Dependency source inspection: search, files, read, grep
 | `GITHITS_API_TOKEN` | API token for authentication | — |
 | `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 `search` / `pkg` / `code` CLI surfaces locally for development | — |
+| `GITHITS_CODE_NAV_URL` | Override package/source service URL | `https://pkgseer.dev` |
 | `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 example-search tools and, when your token carries `code_navigation`, the indexed package/source inspection tools. No separate install is required.
+The same MCP server command exposes both the core example-search tools and 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):
 

commands/help.md

@@ -33,9 +33,8 @@ This plugin connects to the GitHits MCP server and always exposes three core too
   need to force a specific language.
 - **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.
+Additional indexed dependency/package tools such as `search`, `pkg_info`,
+`code_files`, and `code_grep` are available by default.
 
 ## Authentication
 

docs/implementation/auth.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-The CLI supports two authentication methods with different capabilities. Understanding which one is active and how the OAuth flow works is essential for modifying auth-related code without breaking the login experience.
+The CLI supports two authentication methods. Understanding which one is active and how the OAuth flow works is essential for modifying auth-related code without breaking the login experience.
 
 ## Background
 
@@ -19,8 +19,6 @@ The two methods exist because OAuth provides full access but requires a browser,
 
 > **The container resolves auth at startup.** The `createContainer()` function checks for `GITHITS_API_TOKEN` first — if set, it takes precedence even when OAuth tokens are stored. If not set, it loads stored OAuth tokens and attempts auto-refresh if expired. See `src/container.ts` for the resolution logic.
 
-Some hidden package/source tooling is conditionally exposed based on the active auth context.
-
 ## OAuth PKCE Flow
 
 The login command (`src/commands/login.ts`) orchestrates a 9-step OAuth flow (matching the `// Step N:` comments in the code):
@@ -162,7 +160,6 @@ The `hasValidToken` flag is checked by `requireAuth()` in `src/commands/mcp.ts`
 | `src/services/token-manager.ts` | `TokenProvider` interface, `TokenManager` (proactive refresh, coalescing) |
 | `src/services/refreshing-githits-service.ts` | `GitHitsService` decorator with token refresh and 401 retry |
 | `src/services/execute-with-token-refresh.ts` | Shared helper for token-authenticated retry-on-refresh flows |
-| `src/services/code-navigation-capability.ts` | Local package/source access gating helpers |
 | `src/services/code-navigation-service.ts` | Package/source service client using the shared refresh helper |
 | `src/services/auth-service.ts` | OAuth operations (DCR, PKCE, token exchange, callback server) |
 | `src/services/auth-storage.ts` | `AuthStorage` interface and file-based implementation |

docs/implementation/cli-commands.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-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.
+The CLI exposes `example`, `languages`, `feedback`, top-level indexed `search` / `search-status`, and the `code`, `docs`, and `pkg` command groups by default. 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
 
@@ -18,6 +18,8 @@ The CLI exposes three always-on top-level commands: `example`, `languages`, and
 | `pkg vulns <spec>` | package spec (optional `@version`) | `--severity`, `--include-withdrawn`, `--verbose`, `--json` | List known vulnerabilities for a package (npm/pypi/hex/crates) |
 | `pkg deps <spec>` | package spec (optional `@version`) | `--groups`, `--lifecycle`, `--transitive`, `--depth`, `--verbose`, `--json` | Analyse dependencies: direct runtime deps, structured groups, optional transitive graph (npm/pypi/hex/crates/vcpkg/zig) |
 | `pkg changelog [spec]` | package spec OR `--repo-url` | `--from`, `--to`, `--limit`, `--git-ref`, `--no-body`, `--verbose`, `--json` | Release notes / changelog entries for a package or GitHub repo (GitHub Releases, CHANGELOG.md, or HexDocs). Default shows each entry with a 10-line body preview; `--verbose` uncaps, `--no-body` drops. |
+| `docs list <spec>` | package spec (optional `@version`) | `--limit`, `--after`, `--verbose`, `--json` | List hosted/crawled and repository-backed documentation pages for a package. Entries include page IDs for `docs read`; JSON includes exact repo-file follow-up metadata when available. |
+| `docs read <page-id>` | page ID from `docs list` or search results | `--lines`, `--verbose`, `--json` | Read a documentation page by page ID. Default output is content-only; `--lines` fetches a bounded range for long pages. |
 | `code files [spec] [path-prefix]` | package spec OR `--repo-url` + `--git-ref`; optional `[path-prefix]` | `--limit`, `--wait`, `--verbose`, `--json` | List files in an indexed dependency. `[path-prefix]` is a literal directory prefix (not a glob). Plain output is one path per line; `--verbose` adds language / type / size annotations. Indexing-retry via `--wait` or the `availableVersions` hint in the error envelope. |
 | `code read <spec?> <path>` | package spec OR `--repo-url` + `--git-ref`; plus `<path>` | `--lines`, `--start`, `--end`, `--wait`, `--verbose`, `--json` | Read a file's contents. Plain output is the raw file bytes (pipe-friendly); `--verbose` adds a header and a line-number gutter. `--lines 10-40` concise form; `--start`/`--end` equivalent. Binary files show a sentinel line. |
 | `code grep [spec] <pattern> [path-prefix]` | package spec OR `--repo-url` + `--git-ref`; plus `<pattern>` and optional `[path-prefix]` | `--path`, repeatable `--glob`, repeatable `--ext`, `--regex`, `--case-sensitive`, `-C/-A/-B`, `--exclude-docs`, `--exclude-tests`, `--limit`, `--per-file-limit`, `--cursor`, `--symbol-field`, `--wait`, `--verbose`, `--json` | Deterministic text grep over indexed dependency or repository source. Defaults to whole-target, literal, ASCII case-insensitive matching; non-ASCII letters match case-sensitively. Narrow with `[path-prefix]`, `--path`, `--glob`, or `--ext`. Plain output is `file:line:text`; `--verbose` groups matches by file. |
@@ -130,8 +132,6 @@ Shows a concise overview for a single package: latest version, license, descript
 
 **Output envelope.** Success payload is hand-crafted for agent token efficiency: `{registry, name, version, description?, license?, homepage?, repository?, publishedAt?, downloads?, github?, install?, usage?, vulnerabilities?, recentChanges?}`. Omitted fields reflect backend nulls, not dropped data. Error envelope: `{error, code, retryable, details?}` — shared classifier family. Under `--json` the error envelope is written to **stderr** so stdout stays clean for `jq`.
 
-**Capability gate.** Same as `code`.
-
 **Troubleshooting.** `GITHITS_DEBUG=pkg-intel` emits PII-safe classified-error diagnostics (area, event, code, error class, detail keys). Use `GITHITS_DEBUG=*` to enable all non-sensitive package/source diagnostics.
 
 ### `githits pkg vulns`
@@ -168,8 +168,6 @@ Lists known CVE / OSV advisories for a package: severity, affected version range
 
 **Exit codes.** 0 on success including zero-vulns; 1 on any error. Under `--json`, the error envelope is written to **stderr**.
 
-**Capability gate.** Same as `pkg info`.
-
 **Troubleshooting.** Same debug areas as `pkg info`.
 
 ### `githits pkg deps`
@@ -204,8 +202,6 @@ Analyses dependencies for a package on npm, PyPI, Hex, Crates, vcpkg, or Zig. De
 
 **Exit codes.** 0 on success including zero-dep packages; 1 on any error. Under `--json`, the error envelope is written to **stderr**.
 
-**Capability gate.** Same as `pkg info` / `pkg vulns`.
-
 **Troubleshooting.** Same debug areas as `pkg info` / `pkg vulns`.
 
 ### `githits pkg changelog`
@@ -241,10 +237,41 @@ Fetches release notes or changelog entries for a package or GitHub repository. O
 
 **Errors.** `NOT_FOUND` covers both the backend's "package not found" case and the distinct "package exists but no changelog source resolved" case (typed `PackageIntelligenceChangelogSourceNotFoundError`; message names the sources that were tried). `VERSION_NOT_FOUND` enriches with structured `package` / `requested` / `available` detail lines from the shared `promoteGenericVersionNotFound` helper — which was extended in this PR to recognise `--from` and `--to` as promotable version inputs.
 
-**Capability gate.** Same as the rest of the `pkg` family.
-
 **Troubleshooting.** Same debug areas as the rest of the `pkg` family.
 
+### `githits docs list`
+
+```
+githits docs list npm:express
+githits docs list npm:express --limit 20
+githits docs list npm:express --json
+```
+
+Lists hosted/crawled and repository-backed documentation pages for a package. Each row includes a stable page ID for `docs read`, a source badge, and the source location. JSON output also includes repo URL / git ref / file path for repository-backed docs so callers can follow up with `code read` when source context is needed.
+
+**Pagination.** `--limit <n>` accepts 1-500. When `hasMore` is true, pass the returned `nextCursor` to `--after`.
+
+**Output envelope.** `{registry, name, version?, pages, total?, hasMore, nextCursor?, stale?, filter?}`. Each page has `{pageId, title, sourceKind, sourceUrl?, linkName?, repoUrl?, gitRef?, filePath?, lastUpdatedAt?}`.
+
+**Troubleshooting.** Same debug areas as the `pkg` family.
+
+### `githits docs read`
+
+```
+githits docs read <page-id>
+githits docs read <page-id> --lines 10-80
+githits docs read <page-id> --verbose
+githits docs read <page-id> --json
+```
+
+Reads a documentation page returned by `docs list` or search results. Default output is content-only for easy piping; `--verbose` adds a metadata header.
+
+**Line ranges.** `--lines 10-40`, `--lines 10-`, and `--lines -40` are supported. Use ranges to inspect long pages incrementally.
+
+**Output envelope.** `{pageId, title?, sourceKind?, sourceUrl?, repoUrl?, gitRef?, filePath?, totalLines?, startLine?, endLine?, content}`. Repo-backed docs include exact source metadata for `code read` follow-up.
+
+**Troubleshooting.** Same debug areas as the `pkg` family.
+
 ### `githits code files`
 
 ```
@@ -338,7 +365,7 @@ 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` plus capability-gated MCP indexed-search tools (`search`, `search_status`, `code_files`, `code_read`, `code_grep`) and the `githits code` command group |
+| `CodeNavigationService` (via container) | top-level unified `search` / `search-status`, MCP indexed-search tools (`search`, `search_status`, `code_files`, `code_read`, `code_grep`), and the `githits code` command group |
 | `filterLanguages()` from `src/shared/language-filter.ts` | `search_language` MCP tool + `languages` CLI command |
 | `requireAuth()` from `src/shared/require-auth.ts` | all CLI commands and auth-required MCP tool handlers |
 
@@ -371,7 +398,7 @@ All commands support two output modes:
 
 ## Runtime Diagnostics
 
-- **`GITHITS_TELEMETRY=1`** — Emits an end-of-run timing summary to stderr without polluting normal stdout. Current spans cover gated command registration, startup auth lookup, container creation, token loading/refresh, and the outbound API/package-intelligence request.
+- **`GITHITS_TELEMETRY=1`** — Emits an end-of-run timing summary to stderr without polluting normal stdout. Current spans cover command registration, container creation, token loading/refresh, and the outbound API/package-intelligence request.
 
 ## Key Reference Files