githits 0.20.0 → 0.22.0

package/dist/shared/{chunk-4af5a8fw.js → chunk-qb8f9rr8.js}

@@ -1 +1 @@
-import{loadAutoLoginAuthSessionMetadata2,clearAutoLoginAuthSessionMetadata2,createAuthCommandDependencies2,createLogoutCommandDependencies2,createAuthStatusDependencies2,createContainer2}from"./chunk-rwag53sb.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-n1jz8phj.js";export{clearAutoLoginAuthSessionMetadata2 as clearAutoLoginAuthSessionMetadata,createAuthCommandDependencies2 as createAuthCommandDependencies,createAuthStatusDependencies2 as createAuthStatusDependencies,createContainer2 as createContainer,createLogoutCommandDependencies2 as createLogoutCommandDependencies,loadAutoLoginAuthSessionMetadata2 as loadAutoLoginAuthSessionMetadata};

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "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.20.0",
+  "version": "0.22.0",
   "mcpName": "com.githits/githits",
   "type": "module",
   "workspaces": [

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "githits",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "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.20.0",
+  "version": "0.22.0",
   "remotes": [
     {
       "type": "streamable-http",
@@ -28,7 +28,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "githits",
-      "version": "0.20.0",
+      "version": "0.22.0",
       "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,22 @@ 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 --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 `--selector <name>` when the exact indexed symbol is known; add an exact path to narrow ambiguous symbols.
+- 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

@@ -1,6 +1,6 @@
 # GitHits Code And Docs CLI Reference
 
-Package target syntax requires an explicit registry: `registry:name[@version]`, for example `npm:express@5.2.1`; omit `@version` for the latest release. Package targets inspect an indexed artifact/manifest root. Swift package targets use `swift:github.com/<owner>/<repo>` and Zig package targets use `zig:gh/<owner>/<repo>`. Use public repository targets for full repositories or sibling packages. Repository compact targets use `github:org/repo[@ref]`, `codeberg:owner/repo[@ref]`, `gitlab:group[/subgroup...]/project[@ref]`, `github.com/org/repo[@ref]`, or `https://github.com/org/repo[@ref]`; omitted refs request the backend default-branch intent. Exact standalone documentation sites use `site:<host[/path]>`. Output uses canonical `provider:path@ref` formatting so refs can contain `@` safely. `code` commands also support `--repo-url <url> [--git-ref <ref>]`.
+Package target syntax requires an explicit registry: `registry:name@version`, for example `npm:express@5.2.1`; omit `@version` for the latest release. Package targets scope to the package subpath, including within monorepos. Swift package targets use `swift:github.com/<owner>/<repo>` and Zig package targets use `zig:gh/<owner>/<repo>`. Use public repository targets for full repositories or sibling packages. Repository compact targets use `github:org/repo@ref`, `codeberg:owner/repo@ref`, `gitlab:group/subgroup/project@ref`, `github.com/org/repo@ref`, or `https://github.com/org/repo@ref`; omit `@ref` for the backend default branch. Exact standalone documentation sites use `site:<host[/path]>`. Output uses canonical `provider:path@ref` formatting so refs can contain `@` safely. `code` commands also support `--repo-url <url>` with optional `--git-ref <ref>`.
 
 ## Search
 
@@ -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> --selector <name>` reads a known indexed code symbol; add an exact `<path>` to narrow resolution to one file. 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,10 @@ 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 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,26 +21,27 @@ 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` |
 | Inspect direct dependencies or transitive footprint | `pkg_deps` |
-| Find release notes for a package or repository | `pkg_changelog` |
+| Find release notes and changelog history for a package | `pkg_changelog` |
 | Compare current and target dependency versions for an upgrade | `pkg_upgrade_review` |
 | Find canonical implementation examples across projects | `get_example` |
 | Check progress of an earlier search reference | `search_status` |
 
 For comparisons, combine relevant package/source evidence with examples as needed.
 
-Public OSS only; never send local/private/proprietary source. Packages use
-`registry:name[@version]` for an indexed artifact/manifest root; Swift uses
+Public OSS only; never send local/private/proprietary source. Package/repository
+patterns are `registry:name@version` and `github:owner/repo@ref`. Omit the
+suffix for the latest package version or repository default branch. Package
+targets scope to the package subpath, including in monorepos. Swift uses
 `swift:github.com/<owner>/<repo>`, Zig `zig:gh/<owner>/<repo>`.
 Use public repository targets for full repositories or sibling packages:
 `github:`, `codeberg:`, `gitlab:`, or a supported full URL. Never infer a provider.
-Revisions use `@ref` and may contain later `@` characters; `#` is reserved
-for semantic fragments, not revisions. Selected tools state supported forms
-and pin/ref restrictions.
+A ref may be a branch, tag, or commit and contain later `@`; `#` is for
+semantic fragments, not revisions.
 
 For a package or site docs topic, use `search` with `source:"docs"`.
 `docs_list` browses package pages, not standalone `site:` targets.
@@ -55,6 +56,8 @@ 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.
 
 Omit `wait_timeout_ms` for the default; `0` returns without waiting.
 Follow rendered continuation/recovery actions, not repeated calls to poll.

package/skills/githits-package/SKILL.md

@@ -21,7 +21,7 @@ Use GitHits package intelligence before making dependency claims from memory.
 
 - Most package commands use `<registry>:<name>[@<version>]`, for example `npm:lodash@4.17.20` or `pypi:requests`.
 - `pkg info` always reports the latest published version and does not accept a version pin.
-- `pkg changelog` accepts `<registry>:<name>` or `--repo-url <url>`; do not pass `<spec>@<version>` to changelog. Use `--to <version>` instead.
+- `pkg changelog` is package-only. Pin `@version` for one release; use `@from..to` or `--from`/`--to` for ranges. Repository and site targets are rejected.
 
 ## Core Commands
 
@@ -39,8 +39,8 @@ githits pkg deps npm:express --lifecycle all
 githits pkg deps npm:express --depth 3
 
 githits pkg changelog npm:express --limit 3
+githits pkg changelog npm:express@5.2.1
 githits pkg changelog npm:express --from 4.18.0 --to 4.19.0
-githits pkg changelog --repo-url https://github.com/expressjs/express --limit 2 --no-body
 
 githits pkg upgrade-review npm:zod@4.3.6 --to 4.4.3
 githits pkg upgrade-review --package npm:zod@4.3.6..4.4.3 --package npm:lint-staged@16.2.7..16.4.0
@@ -54,7 +54,7 @@ githits pkg upgrade-review --package npm:zod@4.3.6..4.4.3 --package npm:lint-sta
 - Need historical advisories that do not affect the inspected version: use `pkg vulns --scope non_affecting`; use `--scope all` for affected plus historical rows.
 - Need dependency footprint: start with `pkg deps`; add `--lifecycle all` for non-runtime groups and `--depth <n>` for aggregate transitive graph data.
 - Need upgrade evidence for dependency updates, outdated package bumps, or lockfile changes: prefer `pkg upgrade-review` because it compares current vs target vulnerabilities, changelog range evidence, deprecation metadata, peer changes, dependency changes, and transitive security evidence by default. It reports facts only; you still own the final assessment.
-- Need release notes without a current-to-target comparison: use `pkg changelog`; use `--from`/`--to` for ranges and `--no-body` for compact timelines.
+- Need release notes without a current-to-target comparison: use `pkg changelog`; `--no-body` for compact timelines.
 
 ## Gotchas
 

package/skills/githits-package/references/package.md

@@ -31,13 +31,11 @@ Use `--depth` to request capped transitive output. Without it, output is direct
 
 ## Changelog
 
-`githits pkg changelog <registry:name>` returns recent release notes. `--limit` caps latest mode. `--from` is the exclusive lower bound for range mode, which returns entries after `--from` through `--to` (or latest).
+`githits pkg changelog <registry:name[@version|@from..to]>` returns release notes for a package. Bare targets use latest mode. Pin `@version` for one selected release. Use `@from..to`, `@from..`, or `@..to` for interval and upper-cap forms.
 
-Flags: `--repo-url <url>`, `--from <version>`, `--to <version>`, `--limit 1-50`, `--git-ref <ref>`, `--verbose`, `--no-body`, `--json`.
+Flags: `--from <version>`, `--to <version>`, `--limit 1-50`, `--verbose`, `--no-body`, `--json`.
 
-Do not use `registry:name@version` for changelog. `--to <version>` is an upper cap, not an exact-release lookup.
-
-For repository changelogs, pass a full HTTPS URL on github.com, codeberg.org, or gitlab.com to `--repo-url`; use `--git-ref` for a branch or tag. Codeberg requires owner/repo; GitLab permits nested namespaces. Do not pass compact `github:`, `codeberg:`, or `gitlab:` targets to this URL field.
+`--from` and `--to` remain package range flags on a bare spec. Inline single-release targets reject those flags and `--limit`. Repository and site targets are not supported.
 
 ## Upgrade Review