feat: add target resolution CLI dogfood surface

docs/implementation/cli-commands.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-The CLI exposes setup/auth commands, `doctor`, `example`, `languages`, `feedback`, top-level indexed `search` / `search-status`, and the `code`, `docs`, and `pkg` command groups by default. MCP-parity 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 setup/auth commands, `doctor`, `example`, `languages`, `feedback`, target `resolve`, top-level indexed `search` / `search-status`, and the `code`, `docs`, and `pkg` command groups by default. MCP-parity 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
 
@@ -17,6 +17,7 @@ The CLI exposes setup/auth commands, `doctor`, `example`, `languages`, `feedback
 | `languages [query]` | — | `--json` | List or filter supported languages |
 | `feedback [solution_id]` | `--accept` or `--reject` | `-m, --message <text>`, `--tool <name>`, `--json` | Submit solution-tied or generic session feedback |
 | `doctor` | — | `--json` | Print redacted diagnostics for GitHits runtime, environment, service URLs, config, and auth storage |
+| `resolve <name>` | package or GitHub repository name | `--query`, `--registry`, `--prefer-kind`, repeatable `--intent-hint`, `--limit`, `--json` | Resolve a human-provided name to ranked concrete targets for follow-up commands |
 | `pkg info <spec>` | package spec | `--verbose`, `--json` | Show a package overview (latest version, downloads, license, vulnerabilities) |
 | `pkg vulns <spec>` | package spec (optional `@version`) | `--severity`, `--scope`, `--include-withdrawn`, `--verbose`, `--json` | List known vulnerabilities for a package (npm/pypi/hex/crates/nuget/maven/packagist/rubygems/go/swift) |
 | `pkg deps <spec>` | package spec (optional `@version`) | `--lifecycle`, `--depth`, `--verbose`, `--json` | Analyse dependencies: direct runtime deps, structured groups, optional capped transitive graph (npm/pypi/hex/crates/vcpkg/zig/rubygems/go/swift) |
@@ -184,6 +185,54 @@ githits doctor --json
 
 Prints redacted diagnostics for comparing GitHits behavior across terminals or agents. The report includes CLI/runtime identity, selected environment variables, service URL sources, config file status, active and legacy auth storage locations, token/client/metadata presence and timestamps, and recommendations. Secret-bearing values such as tokens, client secrets, API tokens, and proxy credentials are never printed; presence is reported as `set` / `present` only. JSON output uses `schemaVersion: 1` for support tooling.
 
+### `githits resolve`
+
+```text
+githits resolve express
+githits resolve codex --prefer-kind repository
+githits resolve guava --registry maven --limit 3
+githits resolve "pi agent" --query "coding agent CLI" --json
+```
+
+Resolves a human-provided package or GitHub repository name to ranked canonical
+targets such as `npm:express` or `github:openai/codex`. The default output is a
+compact numbered `Candidates` list with ambiguity guidance when needed and
+protected exact-name matches annotated inline. It does not label any terminal
+candidate as best or top. Every candidate includes its available normalized
+description, capped at 240 characters, and cheap trust evidence: repository
+stars, monthly or total package downloads, and docs/code availability. When
+package repository popularity is unavailable, its linked repository is shown
+as a canonical `github:owner/repo` fallback. Missing evidence is omitted rather
+than shown as zero.
+
+The copyable `githits search --in` follow-up uses the resolved target only for
+non-ambiguous results. Ambiguous results use the literal `<target>` placeholder
+so the terminal does not imply that candidate 1 was selected. No candidates is
+a valid JSON/text result but exits 1 because the command did not resolve a
+target.
+
+`--registry` accepts a comma-separated package-registry list; repository
+candidates remain eligible. `--prefer-kind package|repository` is a soft
+preference, not a filter. `--intent-hint` is repeatable. `--limit` controls the
+ranked list from 1-20 (default 8); protected exact-name matches can be additional.
+`--query` and `--intent-hint` are sent to the service as ranking context and
+must not contain credentials, personal data, private code, or proprietary
+content.
+
+`--json` emits the stable compact diagnostic envelope
+`{best?, ambiguous, ambiguousReason?, candidates, protectedMatches}`. Candidate
+objects occur once; `best` and `protectedMatches` use canonical-key references.
+Detailed ranking fields are fetched only for JSON. Null fields are omitted and
+enum values are lowercase. Errors use the standard JSON envelope on stderr with
+clean stdout.
+
+The current resolver candidate contract does not propagate linked GitHub
+stars/forks/issues onto package candidates, so Maven packages can show their
+repository URL but not its popularity. The backend request is documented in
+[pkgseer-backend#1666](https://github.com/githits-com/pkgseer-backend/issues/1666);
+the CLI deliberately does not select expensive per-candidate `inspection`
+metadata.
+
 ### Proxy Support
 
 CLI-originated HTTP traffic uses `src/services/proxy-fetch.ts`. This includes OAuth discovery, client registration, token exchange/refresh, REST API calls, code/package service calls, local MCP tool calls started through `githits mcp start`, and npm update checks. The fetch factory supports `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` plus lowercase aliases; lowercase values win when both cases are set, matching undici's env proxy precedence.