feat: unify MCP list tools

README.md

@@ -74,8 +74,8 @@ broader open-source ecosystem, not just model memory or local repo context:
 |---|---|---|
 | Tool orientation | `quick_start` | — |
 | Code examples | `get_example` | `githits example` |
-| Code navigation | `search`, `search_status`, `code_files`, `code_grep` | `githits search`, `githits search-status`, `githits code ...` |
-| Documentation discovery | `docs_list` | `githits docs list` |
+| Inventory browsing | `list` | `githits list` |
+| Code and documentation search | `search`, `search_status`, `code_grep` | `githits search`, `githits search-status`, `githits code grep` |
 | Read source files or documentation sections | `read` | `githits read <target> [path]` |
 | Grep source and hosted documentation together | CLI only (MCP migration pending) | `githits grep <pattern> <targets...>` |
 | Package inspection | `pkg_info`, `pkg_vulns`, `pkg_deps`, `pkg_changelog`, `pkg_upgrade_review` | `githits pkg ...` |

changes/unified-list-mcp.changed.md

@@ -0,0 +1,13 @@
+---
+"githits": minor
+"@githits/mcp": minor
+---
+
+- **Unify MCP inventory browsing** - Replace the callable `code_files` and
+  `docs_list` tools with one `list` tool for package, repository, and explicit
+  site inventories; its description retains both retired names for stale tool
+  searches, while legacy grouped CLI commands remain available. Hosts must
+  provide the now-required `McpToolServices.listService`; `ListService` and
+  `ListServiceImpl` are exported from `@githits/mcp/client`. Custom endpoints
+  must implement `Query.list` for the unified inventory service. Default text
+  includes the opaque `after` continuation when more entries are available.

docs/implementation/TOOL_GUARDRAILS.md

@@ -129,12 +129,12 @@ maintainer-controlled content:
 - `pkg_info` — registry description, repository topics and recent release notes
 - `pkg_changelog` — release-notes body
 - `pkg_upgrade_review` — release-note excerpts and package deprecation text
-- `read` and `docs_list` — repo READMEs and crawled docs
+- `list` and `read` — repository documentation paths and crawled docs pages
 - `read` and `code_grep` — repo source code (comments + strings)
 - `search` — multi-source search snippets
 - `get_example` — backend-synthesized examples
 
-Other tools (`quick_start`, `pkg_deps`, `code_files`, `search_status`) have no third-party prose surface or attacker
+Other tools (`quick_start`, `pkg_deps`, `search_status`) have no third-party prose surface or attacker
 control and need no per-tool addendum. The shared posture is available to plain
 MCP agents after they call `quick_start`; a loaded `githits-mcp` skill already
 carries the stable posture. The runtime-only local appendices are not embedded

docs/implementation/cli-commands.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-The CLI exposes setup/auth commands, `doctor`, `example`, top-level indexed `search` / `search-status`, `read`, `list`, `grep`, and the `code`, `docs`, and `pkg` command groups by default. `resolve` and `code diff` are experimental, host-config-gated commands. MCP-parity commands share business logic with the MCP tools through the same service interfaces and shared utilities. Unified search shares its presentation model and text formatter with MCP; `list` uses the shared request, result, error, and path-only text helpers, while MCP tool registration remains a later increment.
+The CLI exposes setup/auth commands, `doctor`, `example`, top-level indexed `search` / `search-status`, `read`, `list`, `grep`, and the `code`, `docs`, and `pkg` command groups by default. `resolve` and `code diff` are experimental, host-config-gated commands. MCP-parity commands share business logic with the MCP tools through the same service interfaces and shared utilities. Unified search shares its presentation model and text formatter with MCP; `list` uses the same request, result, error, and path-only text helpers on both surfaces.
 
 ## Experimental CLI commands
 
@@ -996,7 +996,8 @@ Each command follows this pattern:
 | Shared Module | Used By |
 |---|---|
 | `GitHitsService` (via container) | `example` and always-on MCP tools |
-| `CodeNavigationService` (via container) | top-level unified `search` / `search-status`, MCP indexed-search tools (`search`, `search_status`, `code_files`, `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_grep`), and the `githits code` command group |
+| `ListService` (via container) | top-level CLI and MCP `list` against package, repository, or explicit site inventories |
 | `ReadService` (via container) | compact top-level `read` and advertised MCP `read`, backed by one `Query.read` request |
 | `requireAuth()` from `packages/mcp/src/shared/require-auth.ts` | all CLI commands and auth-required MCP tool handlers |
 

docs/implementation/config.md

@@ -74,7 +74,7 @@ The container (`src/container.ts`) resolves authentication in priority order:
 | `/search` | Full access | Full access | Blocked |
 | `/functions/v1/settings/me` | Full access | Full access | Blocked |
 
-Package/source access uses the OSS service URL selected by `GITHITS_ENV` unless `GITHITS_CODE_NAV_URL` overrides it. MCP registration for `search`, `search_status`, `docs_*`, `pkg_*`, `code_files`, `read`, and `code_grep` is always on; CLI registration for top-level `search` / `search-status` / `read` / `list` / `grep` plus the `githits code`, `githits pkg`, and `githits docs` groups is also always on.
+Package/source access uses the OSS service URL selected by `GITHITS_ENV` unless `GITHITS_CODE_NAV_URL` overrides it. MCP registration for `search`, `search_status`, `list`, `read`, `code_grep`, and `pkg_*` is always on; CLI registration for top-level `search` / `search-status` / `read` / `list` / `grep` plus the legacy-compatible `githits code`, `githits pkg`, and `githits docs` groups is also always on.
 
 ## Environment Variables
 

docs/implementation/mcp-cli-parity.md

@@ -47,15 +47,14 @@ The dual-surface tools today are:
 - `get_example` ↔ `githits example`
 - `search` ↔ `githits search`
 - `search_status` ↔ `githits search-status`
-- `code_files` ↔ `githits code files`
+- `list` ↔ `githits list`
 - `read` with a path ↔ `githits read <target> <path>` (legacy `code read` retained)
 - `code_grep` ↔ `githits code grep`
 - `pkg_info` ↔ `githits pkg info`
 - `pkg_vulns` ↔ `githits pkg vulns`
 - `pkg_deps` ↔ `githits pkg deps`
 - `pkg_changelog` ↔ `githits pkg changelog`
 - `pkg_upgrade_review` ↔ `githits pkg upgrade-review`
-- `docs_list` ↔ `githits docs list`
 - `read` without a path ↔ `githits read <target>` (legacy `docs read` retained)
 - `resolve_target` ↔ `githits resolve` *(config-gated, local-only)*
 - `code_diff` ↔ `githits code diff` *(config-gated, local-only)*
@@ -528,34 +527,35 @@ When a new tool lands with both MCP and CLI surfaces:
 | `packages/mcp/src/shared/package-dependencies-response.ts` | Lean JSON envelope builder and shared text/terminal formatter for `pkg_deps`. |
 | `packages/mcp/src/shared/package-changelog-request.ts` | Shared request builder for `pkg_changelog`. |
 | `packages/mcp/src/shared/package-changelog-response.ts` | JSON envelope builder and shared text/terminal formatter for `pkg_changelog`. |
-| `packages/mcp/src/shared/list-files-request.ts` | Shared request builder for `code_files`. |
-| `packages/mcp/src/shared/list-files-response.ts` | JSON envelope builder for `code_files`. |
+| `packages/mcp/src/shared/list-request.ts` | Shared request builder for unified `list`. |
+| `packages/mcp/src/shared/list-response.ts` | Lossless selected-field JSON projection for unified `list`. |
+| `packages/mcp/src/shared/list-text.ts` | Shared token-efficient CLI/MCP path formatter. |
 | `packages/mcp/src/shared/read-file-request.ts` | Shared request builder for `read`. |
-| `packages/mcp/src/shared/read-file-response.ts` | JSON envelope builder for `read`. Normalises envelope key to `path` (not `filePath`) so `code_files` -> `read` chains without renames. |
+| `packages/mcp/src/shared/read-file-response.ts` | JSON envelope builder for `read`. Normalises envelope key to `path` (not `filePath`) for exact-file follow-ups. |
 | `packages/mcp/src/shared/grep-repo-request.ts` | Shared request builder for `code_grep`. Exports `GREP_REPO_PATTERN_NOTE` referenced by MCP description, MCP `pattern` describe, and CLI help. |
 | `packages/mcp/src/shared/grep-repo-response.ts` | JSON envelope builder for `code_grep`. |
-| `packages/mcp/src/shared/list-package-docs-request.ts` / `list-package-docs-response.ts` | Shared request and envelope for `docs_list`. |
+| `packages/mcp/src/shared/list-files-request.ts` / `list-files-response.ts` | Legacy grouped CLI file-list compatibility helpers. |
+| `packages/mcp/src/shared/list-package-docs-request.ts` / `list-package-docs-response.ts` | Legacy grouped CLI documentation-list compatibility helpers. |
 | `packages/mcp/src/shared/read-package-doc-request.ts` / `read-package-doc-response.ts` | Shared request and envelope for `read`. |
 | `packages/mcp/src/shared/code-navigation-error-map.ts` | Owns the `INDEXING`, target/file-not-found, and exact-path authority codes shared across all code-nav tools. |
 | `packages/mcp/src/shared/package-intelligence-error-map.ts` | `mapPackageIntelligenceError` classifier using the shared `MappedError` contract. |
 | `packages/core-internal/src/services/promote-version-not-found.ts` | Shared helper that promotes generic backend errors with "no matching version" messages into typed `VERSION_NOT_FOUND`. |
-| `packages/mcp/src/tools/code-navigation-shared.ts` | Compact-string `codeTargetSchema` + `resolveCodeTarget` for `code_files`, `code_grep`, and the code branch of `read`; `search` has a related string schema that also accepts exact documentation sites. |
+| `packages/mcp/src/tools/code-navigation-shared.ts` | Compact-string target parsing retained by `code_grep` and legacy code navigation; `search`, `list`, and `read` use their transport-neutral request boundaries. |
 | `packages/mcp/src/tools/search.ts` | MCP tool definition for unified `search`. |
 | `packages/mcp/src/tools/search-status.ts` | MCP tool definition for `search_status`. |
 | `packages/mcp/src/tools/package-summary.ts` | MCP tool definition for `pkg_info`. |
 | `packages/mcp/src/tools/package-vulnerabilities.ts` | MCP tool definition for `pkg_vulns`. |
 | `packages/mcp/src/tools/package-dependencies.ts` | MCP tool definition for `pkg_deps`. |
 | `packages/mcp/src/tools/package-changelog.ts` | MCP tool definition for `pkg_changelog`. |
-| `packages/mcp/src/tools/list-files.ts` | MCP tool definition for `code_files`. |
+| `packages/mcp/src/tools/list.ts` | Stable MCP tool definition for unified `list`. |
 | `packages/mcp/src/tools/read-file.ts` | Code branch of unified `read`; `tools/read.ts` owns the advertised definition. |
 | `packages/mcp/src/tools/grep-repo.ts` | MCP tool definition for `code_grep`. |
-| `packages/mcp/src/tools/list-package-docs.ts` / `read-package-doc.ts` | MCP tool definitions for the docs surface. |
 | `src/commands/search.ts` | Top-level CLI commands for unified `search` and `search-status`. |
-| `src/commands/list.ts` | Top-level CLI `list` command; currently CLI-only until Phase 2 MCP consolidation. |
+| `src/commands/list.ts` | Top-level CLI `list` command sharing its contract and formatter with MCP. |
 | `src/commands/pkg/info.ts` / `vulns.ts` / `deps.ts` / `changelog.ts` | CLI commands for the `pkg` group. |
 | `src/commands/code/files.ts` / `read.ts` / `grep.ts` | CLI commands for the `code` group. |
 | `src/commands/docs/list.ts` / `read.ts` | CLI commands for the `docs` group. |
-| `src/tools/*-parity.test.ts` | Parity tests; each cites the rule IDs it enforces. |
+| `scripts/cli-smoke.ts` | Live CLI/MCP JSON-shape parity fixtures, including package and site `list`. |
 
 ## Per-tool notes
 
@@ -747,22 +747,20 @@ section labels remain plain; only the matched keyword and excerpt marker are
 yellow. Evidence detail and locators remain plain. Words remain sufficient
 without color, authored punctuation is ASCII, and backend Unicode is preserved.
 
-### `code_files` / `read` / `code_grep` (file-exploration bundle)
+### `list` / `read` / `code_grep` (inventory and file-exploration bundle)
 
-`code_files` and `code_grep` reuse `codeTargetSchema` + `resolveCodeTarget` from
-`packages/mcp/src/tools/code-navigation-shared.ts`; the code branch of `read`
-accepts compact strings only and uses the same resolver. The indexing lifecycle is
-shared (see `tools.md` "Indexing lifecycle" section). Parity tests
-cover dual addressing, default + explicit filter echoes, INDEXING
-error envelope, NOT_FOUND envelope, and INVALID_ARGUMENT with full
-envelope shape.
+`list` uses the transport-neutral `ListService` and shared request, response,
+error, and text helpers. `read` uses `ReadService`; `code_grep` retains compact
+target parsing through the code-navigation service. Live parity fixtures cover
+package and explicit-site list JSON shapes, while focused tests cover request
+normalization, pagination, actions, errors, and text output.
 
-- **`code_files`**: `filter.path_prefix` / `filter.limit` echo only
-  when explicit. Default `limit: 200` never round-trips. Backend
-  returns `total` capped at returned count when `hasMore: true`;
-  terminal formatter renders `N+`.
+- **`list`**: literal paths and globs form a union. Selected directories expose
+  immediate children unless `recursive` expands them; glob depth is
+  independent. JSON returns backend-authored read/browse actions and an opaque
+  continuation cursor. Text returns only the source line and paths.
 - **`read` code branch**: envelope uses `path` (not `filePath`) to match
-  `code_files.files[].path`. Binary files: `isBinary: true` +
+  returned list action/path. Binary files: `isBinary: true` +
   `content` omitted (not `null`). INDEXING details may carry
   `indexingRef`, `indexingEstimate`, and any backend-provided
   indexed refs/versions; callers must branch on whichever retry

docs/implementation/mcp-tool-annotations.md

@@ -26,8 +26,7 @@ These annotation choices do not change request or response behavior.
 | `quick_start` | Return GitHits usage guidance. |
 | `get_example` | Find canonical examples. |
 | `search`, `search_status` | Discover indexed evidence and retrieve search progress/results. |
-| `code_files`, `code_grep`, `read` | Navigate and read public source. |
-| `docs_list`, `read` | Discover and retrieve public documentation. |
+| `list`, `code_grep`, `read` | Browse, search, and read public source or documentation inventories. |
 | `pkg_info`, `pkg_vulns`, `pkg_deps`, `pkg_changelog`, `pkg_upgrade_review` | Retrieve and compute package facts and upgrade evidence. |
 | Local experimental `research`, `resolve_target`, `code_diff` | Generate cited answers, resolve targets, and compare source versions. |