githits 0.21.0 → 0.22.1

package/dist/shared/{chunk-cwnsxr14.js → chunk-qjdh687v.js}

@@ -1 +1 @@
-import{loadAutoLoginAuthSessionMetadata2,clearAutoLoginAuthSessionMetadata2,createAuthCommandDependencies2,createLogoutCommandDependencies2,createAuthStatusDependencies2,createContainer2}from"./chunk-kcv6v8zb.js";export{clearAutoLoginAuthSessionMetadata2 as clearAutoLoginAuthSessionMetadata,createAuthCommandDependencies2 as createAuthCommandDependencies,createAuthStatusDependencies2 as createAuthStatusDependencies,createContainer2 as createContainer,createLogoutCommandDependencies2 as createLogoutCommandDependencies,loadAutoLoginAuthSessionMetadata2 as loadAutoLoginAuthSessionMetadata};
+import{loadAutoLoginAuthSessionMetadata2,clearAutoLoginAuthSessionMetadata2,createAuthCommandDependencies2,createLogoutCommandDependencies2,createAuthStatusDependencies2,createContainer2}from"./chunk-737pd53s.js";export{clearAutoLoginAuthSessionMetadata2 as clearAutoLoginAuthSessionMetadata,createAuthCommandDependencies2 as createAuthCommandDependencies,createAuthStatusDependencies2 as createAuthStatusDependencies,createContainer2 as createContainer,createLogoutCommandDependencies2 as createLogoutCommandDependencies,loadAutoLoginAuthSessionMetadata2 as loadAutoLoginAuthSessionMetadata};

package/dist/shared/{chunk-8nseper4.js → chunk-zged479w.js}

@@ -1,2 +1,2 @@
-var description="The code context layer for AI coding agents";var version2="0.21.0";
+var description="The code context layer for AI coding agents";var version2="0.22.1";
 export{description,version2};

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "The code context layer for AI coding agents",
   "mcpServers": {
     "githits": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "githits",
   "description": "The code context layer for AI coding agents",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "mcpName": "com.githits/githits",
   "type": "module",
   "workspaces": [
@@ -40,7 +40,7 @@
     "githits": "dist/cli.js"
   },
   "scripts": {
-    "build": "bunup && bun -e \"import { chmodSync } from 'node:fs'; chmodSync('dist/cli.js', 0o755);\"",
+    "build": "bun -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true });\" && bunup --no-clean && bun -e \"import { chmodSync } from 'node:fs'; chmodSync('dist/cli.js', 0o755);\"",
     "dev": "bun run ./src/cli.ts",
     "inspector": "npx @modelcontextprotocol/inspector bun run dev mcp",
     "smoke:cli": "bun run scripts/cli-smoke.ts",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "githits",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "The code context layer for AI coding agents",
   "author": {
     "name": "GitHits"

package/server.json

@@ -16,7 +16,7 @@
     "source": "github",
     "id": "1165453165"
   },
-  "version": "0.21.0",
+  "version": "0.22.1",
   "remotes": [
     {
       "type": "streamable-http",
@@ -28,7 +28,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "githits",
-      "version": "0.21.0",
+      "version": "0.22.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/skills/githits-code/SKILL.md

@@ -25,9 +25,9 @@ Use GitHits for evidence from real open-source code instead of guessing from mod
 - Need package metadata, vulnerability/advisory status, dependency graphs, or release notes: stop and use the `githits-package` skill instead.
 - Inspecting a known dependency or public repository: start with `githits search` scoped by `--in`.
 - Searching an exact standalone documentation site: use `githits search "<topic>" --source docs --in site:<host[/path]>`. If the result reports suggested site targets, retry one explicitly; suggestions are advisory targets, not aliases.
-- Need file/path enumeration: use `githits code files`; do not probe directories with `code read`.
+- Need file/path enumeration: use `githits code files`; do not probe directories with `githits read`.
 - Know the exact text to match: use `githits code grep` (literal by default). Pass `--regex` for RE2 syntax; lookaround and backreferences are unsupported. Use `githits search` for discovery.
-- Need documentation pages: use `githits search "<topic>" --source docs --in <target>` for topic search, or `githits docs list <spec>` to browse available pages.
+- Need documentation pages: use `githits search "<topic>" --source docs --in <target>` for topic search, or `githits docs list <spec>` to browse available pages. Read returned targets with `githits read`.
 
 ## Core Commands
 
@@ -42,20 +42,23 @@ githits search "middleware" --in site:expressjs.com --source docs
 githits search-status <searchRef>
 
 githits code files npm:express@5.2.1 lib/ --ext js --limit 100
-githits code read npm:express@5.2.1 lib/express.js --lines 1-90
+githits read npm:express@5.2.1 lib/express.js --lines 1-90
+githits read 'npm:express@5.2.1#Router'
+githits read npm:express@5.2.1 --selector Router
 githits code grep npm:express@5.2.1 "require('router')" lib/ -C 3
 githits code grep --repo-url https://github.com/expressjs/express --git-ref v5.2.1 "require('router')" lib/
 
 githits docs list npm:express --limit 20
-githits docs read <docsReadTarget>
+githits read <docsReadTarget>
+githits read <docsReadTarget> --selector <heading-id>
 ```
 
 ## Strategy
 
 - For behavioral claims, prefer source, symbols, tests, and call sites over docs prose.
 - Package targets inspect published artifacts and omitted versions resolve to the latest release; repository targets inspect repository trees. For source-layout questions, always pin and report the package version or Git ref.
-- For source work, locate symbols or matches first, then read a focused window with explicit `--lines`.
-- For docs reads, use the search snippet when sufficient; otherwise run its generated `followUp`. From text, pass the displayed `[docs page]` target unchanged; from `docs list`, pass `docsReadTarget`. Hosted/crawled HTTP(S) targets address mutable current content, so automatic follow-ups forward the exact URL or fragment without search bounds. A fragment returns its heading and full subtree through the next equal-or-higher heading. Repository docs remain snapshot-addressed and keep returned ranges. Add `--lines` only when intentionally selecting a current page range; either bound replaces fragment selection. Historical `pageId` works. Use `--json` only for required range/source metadata.
+- For source work, locate symbols or matches first, then read a focused window with explicit `--lines`. Use `target#symbol` or `--selector <name>` when the exact indexed symbol is known; add an exact path to narrow ambiguous symbols. The backend decides whether a repository fragment identifies a code symbol or a documentation heading.
+- For docs reads, use the search snippet when sufficient; otherwise run its generated `followUp`. From text, pass the displayed `[docs page]` target unchanged; from `docs list`, pass `docsReadTarget`. Hosted/crawled HTTP(S) targets address mutable current content, so automatic follow-ups forward the exact URL or fragment without search bounds. A fragment returns its heading and full subtree through the next equal-or-higher heading. Use `--selector <heading-id>` for a known logical heading ID without a URL fragment. Repository docs remain snapshot-addressed and keep returned ranges. Add `--lines` only when intentionally selecting a current page range; either bound replaces heading selection. Historical `pageId` works. Use `--json` only for required range/source metadata.
 - For multi-step code/docs investigations, keep raw CLI output out of the final answer unless it is the evidence the user needs.
 - Reuse returned targets, paths, locators, references, and ranges; never invent them. Cite the served target and report stale/provisional evidence, truncation, and coverage limits.
 - Partial and capped documentation coverage are usable published evidence. Report the disclosed limit, but infer neither indexing progress nor retryability from coverage; follow only `searchRef` and the evidence notice.

package/skills/githits-code/references/code-and-docs.md

@@ -27,15 +27,15 @@ If a missing or ambiguous site returns suggested site targets, retry one of thos
 
 ## Code Files
 
-`githits code files <spec> [path-prefix]` lists paths. Use this before `code read` when you do not know the exact file path.
+`githits code files <spec> [path-prefix]` lists paths. Use this before `githits read` when you do not know the exact file path.
 
 Useful filters: `--path`, repeatable `--glob`, repeatable `--ext`, repeatable `--file-type`, repeatable `--language`, repeatable `--file-intent`, repeatable `--exclude-intent`, `--exclude-docs`, `--exclude-tests`, `--hidden`, `--limit`, `--wait`, `--verbose`, `--json`.
 
 ## Code Read
 
-`githits code read <spec> <path>` reads one exact package-relative file. Use `--lines 10-80`, `--start`, or `--end` for focused windows. You can also append a range to the path: `src/index.js:10-80`.
+`githits read <target> <path>` reads one exact target-relative file. Use `--lines 10-80`, `--start`, or `--end` for focused windows. You can also append a range to the path: `src/index.js:10-80`. `githits code read` remains a compatibility alias.
 
-For repository addressing: `githits code read --repo-url <url> [--git-ref <ref>] <path>`.
+`githits read '<target>#<symbol>'` or `githits read <target> --selector <name>` reads a known indexed code symbol; add an exact `<path>` to narrow resolution to one file. The backend decides whether a repository fragment identifies a code symbol or a documentation heading. Ambiguous, missing, or unsupported snapshots return recovery guidance. For repository addressing, prefer a compact repository target; `githits read --repo-url <url> [--git-ref <ref>] <path>` remains a compatibility path.
 
 ## Code Grep
 
@@ -48,7 +48,7 @@ When grep returns no matches, do not repeat it unchanged. Change or shorten the
 
 `githits docs list <spec>` browses available documentation pages. It is not topic search.
 
-For `githits docs read <target>`, use the search snippet when sufficient; otherwise run its generated `followUp`. From text, pass the displayed `[docs page]` target unchanged; from `docs list`, pass `docsReadTarget`. Hosted/crawled HTTP(S) targets address mutable current content, so automatic follow-ups forward the exact URL or fragment without search bounds. A fragment returns its heading and full subtree through the next equal-or-higher heading. Repository docs remain snapshot-addressed and keep returned ranges. Add `--lines` only when intentionally selecting a current page range; either bound replaces fragment selection. Historical `pageId` values remain supported. Use `--json` only for required range/source metadata.
+For `githits read <target>`, use the search snippet when sufficient; otherwise run its generated `followUp`. From text, pass the displayed `[docs page]` target unchanged; from `docs list`, pass `docsReadTarget`. Hosted/crawled HTTP(S) targets address mutable current content, so automatic follow-ups forward the exact URL or fragment without search bounds. A fragment returns its heading and full subtree through the next equal-or-higher heading. Use `--selector <heading-id>` for a known logical heading ID without a URL fragment. Repository docs remain snapshot-addressed and keep returned ranges. Add `--lines` only when intentionally selecting a current page range; either bound replaces heading selection. Historical `pageId` values remain supported. `githits docs read` remains a compatibility alias. Use `--json` only for required range/source metadata.
 
 For topic search, use `githits search "<topic>" --source docs --in <target>`, then run its generated follow-up or pass the displayed text target.
 
@@ -61,9 +61,11 @@ Partial and capped documentation coverage are usable published evidence. Report
 - `githits search-status` maps to MCP `search_status`.
 - `githits code files` maps to MCP `code_files`.
 - `githits code grep` maps to MCP `code_grep`.
-- `githits code read` maps to MCP `read` with `target` and `path`.
+- `githits read <target> <path>` maps to MCP `read` with `target` and `path`.
+- `githits read <target> --selector <name>` maps to MCP `read` with `target` and `selector`, optionally with `path` for code.
+- `githits read '<target>#<symbol>'` maps to MCP `read` with the fragment in `target`, optionally with `path` for code.
 - `githits docs list` maps to MCP `docs_list`.
-- `githits docs read` maps to MCP `read` with `target` alone.
+- `githits read <docs-target>` maps to MCP `read` with `target` alone.
 
 Direct repository targets accept approved full HTTPS URLs on github.com, codeberg.org, and gitlab.com. Codeberg requires exactly owner/repo; GitLab allows nested namespaces. Only GitHub supports host shorthand and HTTP compatibility. Never infer a provider from bare owner/repo. Repository refs use an @ suffix and may themselves contain / and @; # is reserved for semantic fragments. Empty refs and mixed suffixes are invalid. Credentials, queries, provider web subpaths, and unsupported/self-hosted hosts are rejected. Package targets keep registry-native coordinates, including `zig:cb/owner/repo` and `swift:gitlab.com/group/project`. Changelog repo URL fields remain full HTTPS URLs.
 

package/skills/githits-mcp/SKILL.md

@@ -21,7 +21,7 @@ This guide owns shared policy; selected tools own call syntax and exceptions.
 | Find a known literal or regex in a public repository/package | `code_grep` |
 | Find relevant source, symbols, tests, or documentation for a topic | `search` |
 | List paths or browse a source directory | `code_files` |
-| Read a source file, documentation page, or focused section | `read` |
+| Read a source file, code symbol, or documentation section | `read` |
 | Browse package documentation pages | `docs_list` |
 | Assess a package's license, adoption, maintenance, or overall health | `pkg_info` |
 | Inspect vulnerabilities in a package or version | `pkg_vulns` |
@@ -56,6 +56,12 @@ Repository docs are snapshot-addressed and keep returned ranges. Add explicit
 For source, locate paths or matches, then read focused lines; never probe
 directories with `read`. Prefer source, symbols, tests, and call sites for
 behavioral claims.
+When the exact indexed code symbol or docs heading ID is known, pass it as
+`selector` to `read`; an optional exact `path` narrows code symbol lookup.
+Use compact package and repository `target#symbol` for code symbol reads;
+keep the fragment in `target` unchanged and use an exact `path` to narrow it.
+Pass HTTP(S) fragments and emitted repository docs page IDs unchanged.
+The unified read result determines whether the target resolved to code or docs.
 
 Omit `wait_timeout_ms` for the default; `0` returns without waiting.
 Follow rendered continuation/recovery actions, not repeated calls to poll.