githits 0.4.3 → 0.4.5

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "GitHits plugins for Claude Code - code examples from global open source",
-    "version": "0.4.3"
+    "version": "0.4.5"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Code examples from global open source for developers and AI assistants",
   "author": {
     "name": "GitHits"

package/.plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Code examples from global open source for developers and AI assistants",
   "author": {
     "name": "GitHits"

package/GEMINI.md

@@ -24,13 +24,14 @@ Look up supported programming language names. Use this before calling `get_examp
 
 ### feedback
 
-Rate a search result. Submit feedback after each search to improve future result quality.
+Submit feedback on a search result, a GitHits tool result, or the current GitHits session. Use it when a result was useful or when a tool/UX issue should be recorded.
 
 **Parameters:**
 
-- `solution_id` (string, required) - the ID of the search result
+- `solution_id` (string, optional) - ID from a `get_example` result; omit for generic session feedback
 - `accepted` (boolean, required) - whether the result was useful
 - `feedback_text` (string, optional) - additional context about why the result was or was not helpful
+- `tool_name` (string, optional) - GitHits tool or command being rated for generic feedback
 
 ## When to Use
 
@@ -64,7 +65,7 @@ Do not use `get_example` for:
 - Formulate queries as natural language questions (e.g., "How to stream responses with the Vercel AI SDK in Next.js")
 - Include specific error messages, library names, or API names when relevant
 - Keep queries focused: 3-4 technical terms maximum
-- Submit `feedback` after every search result you use or discard
+- Submit `feedback` after GitHits results you use or discard; omit `solution_id` for generic tool/session feedback
 
 ## Indexed Package/Source Tools
 

package/README.md

@@ -94,7 +94,7 @@ Core tools available in every authenticated session:
 |---|---|
 | `get_example` | Find canonical code examples by describing what you need in natural language |
 | `search_language` | Look up supported programming language names |
-| `feedback` | Rate search results to improve future quality |
+| `feedback` | Submit result or session feedback to improve future quality |
 
 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.
 
@@ -132,7 +132,7 @@ GitHits requires authentication. There are two options:
 npx githits login
 ```
 
-Opens your browser for secure OAuth authentication. Tokens are stored in the system keychain by default and refreshed automatically on next use. If a refresh fails (e.g., after an extended idle period), run `githits login` again.
+Opens your browser for secure OAuth authentication. Tokens are stored in the system keychain by default and refreshed automatically on next use. If a refresh fails (for example, after an extended idle period), run `githits login` again.
 
 Useful flags:
 
@@ -148,30 +148,54 @@ For CI or environments where browser login isn't practical, set an environment v
 export GITHITS_API_TOKEN=ghi-your-token-here
 ```
 
-For machines without a usable keychain, OAuth file storage must be explicit:
+### Keychain Prompts and File Storage
+
+GitHits uses the system keychain by default because OAuth credentials include a refresh token. On macOS this means Keychain Access; on Windows it means Credential Manager; on Linux it means the available Secret Service or keyring backend.
+
+If macOS shows a prompt such as "githits wants to access ... in your keychain", choose **Always Allow** when you trust the installed `githits` CLI. GitHits cannot customize that operating-system prompt with extra explanation; it is generated by macOS.
+
+GitHits also writes a small non-secret metadata file so recent startup checks do not need to read the keychain. The keychain is only read when GitHits actually needs the token, for example during a tool call, token refresh, `githits auth status`, or a login check after metadata is stale or expired.
+
+If your agent keeps showing keychain prompts even after **Always Allow**, switch OAuth storage to file mode:
 
 ```toml
-# ~/.config/githits/config.toml on Linux
+# macOS/Linux: ~/.config/githits/config.toml, or $XDG_CONFIG_HOME/githits/config.toml
+# Windows: %APPDATA%\githits\config.toml
 [auth]
 storage = "file"
 ```
 
-File storage is plaintext on disk. Prefer `GITHITS_API_TOKEN` for CI and automation.
+The config directory may be empty until you create `config.toml` or GitHits writes auth metadata. Older macOS installs may have used `~/Library/Application Support/githits`; GitHits still reads that location for migration, but new auth config and file storage use `~/.config/githits`.
+
+You can also opt in for one process:
+
+```sh
+GITHITS_AUTH_STORAGE=file githits login --force
+```
+
+File mode stores OAuth credentials as JSON files under the GitHits config directory. The files are written with private permissions where the platform supports it, but they are not encrypted. Any process that can read files as your operating-system user may be able to read the tokens.
 
-You can also opt in for one process with `GITHITS_AUTH_STORAGE=file`. Use file storage only on machines where local file access is trusted.
+Use file mode only on machines where you trust local user-account access. For CI and automation, prefer `GITHITS_API_TOKEN` instead of browser OAuth.
+
+To inspect the current auth setup, run:
+
+```sh
+githits auth status
+```
 
 ## Commands
 
 ```
-githits init           Authenticate and configure your coding tools with GitHits MCP
-githits login          Authenticate with your GitHits account (also runs as part of init)
-githits logout         Remove stored credentials
-githits mcp            Show setup instructions in a terminal; starts MCP server when piped
-githits mcp start      Always start MCP server (for use in MCP config files)
-githits auth status    Show current authentication status
-githits example        Get canonical code examples from global open source
-githits languages      List or filter supported language names
-githits feedback       Send feedback on a returned example
+githits init             Authenticate and configure your coding tools with GitHits MCP
+githits init uninstall   Remove GitHits MCP configuration from your coding tools
+githits login            Authenticate with your GitHits account (also runs as part of init)
+githits logout           Remove stored credentials
+githits mcp              Show setup instructions in a terminal; starts MCP server when piped
+githits mcp start        Always start MCP server (for use in MCP config files)
+githits auth status      Show current authentication status
+githits example          Get canonical code examples from global open source
+githits languages        List or filter supported language names
+githits feedback         Send feedback on a result, command, or session
 ```
 
 These indexed package/source commands are also available:
@@ -223,6 +247,8 @@ A typical MCP config looks like this (check your tool's docs for exact schema/ke
 
 If you'd like another tool to be included in `githits init` for auto-configuration, open an issue or PR.
 
+To undo automatic setup, run `githits init uninstall`. It removes only GitHits MCP/plugin configuration and preserves stored credentials; use `githits logout` separately to remove credentials.
+
 ## Development
 
 ```sh

package/commands/example.md

@@ -21,4 +21,5 @@ Optional parameters:
   licenses), or `"custom"` (user's blocklist).
 
 Present the results clearly. After the user has reviewed the result, use the
-`feedback` tool to report whether the example was helpful.
+`feedback` tool to report whether the example was helpful. Use the returned
+`solution_id` when available.

package/commands/help.md

@@ -31,7 +31,7 @@ This plugin connects to the GitHits MCP server and always exposes these core too
   language. Requires `query`; `language` is optional and inferred when omitted.
 - **search_language** — Look up supported programming language names when you
   need to force a specific language.
-- **feedback** — Rate a search result to improve future quality.
+- **feedback** — Submit result or session feedback to improve future quality.
 
 Additional indexed dependency/package tools are available by default:
 `search`, `search_status`, `docs_list`, `docs_read`, `pkg_info`, `pkg_vulns`,

package/commands/search.md

@@ -23,4 +23,5 @@ Optional parameters:
   licenses), or `"custom"` (user's blocklist).
 
 Present the results clearly. After the user has reviewed the result, use the
-`feedback` tool to report whether the example was helpful.
+`feedback` tool to report whether the result was helpful. Omit `solution_id`
+for generic session feedback about indexed search results.