docs: update keychain docs to reflect securityCLI as default (#15)

Update CLAUDE.md, CHANGELOG.md, KEYCHAIN_FIX.md, and
DEVELOPMENT_SETUP.md to reflect that /usr/bin/security CLI is now
the default keychain read strategy, eliminating prompt issues.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: johnlarkin1

CHANGELOG.md

@@ -36,8 +36,9 @@
 - Menu: hide contextual provider actions while Overview is selected and rebuild switcher state when overview availability changes (#416).
 
 ### Claude OAuth & Keychain
+- **Default to `/usr/bin/security` CLI for Claude keychain reads**, eliminating recurring macOS keychain password prompts after rebuilds/updates. Security.framework remains available as a user override.
 - Use a `claude-code/<version>` User-Agent for OAuth usage requests instead of a generic identifier.
-- Add an experimental Claude OAuth Security-CLI reader path and option in settings.
+- Rename `.securityCLIExperimental` → `.securityCLI` (now the production default).
 - Apply stored prompt mode and fallback policy to silent/noninteractive keychain probes.
 - Add cooldown for background OAuth keychain retries.
 - Disable experimental toggle when keychain access is disabled.

CLAUDE.md

@@ -70,7 +70,7 @@ Macro support types live in `Sources/CodexBarMacroSupport/`, implementations use
 ### Authentication Chain
 
 Providers authenticate via a fallback chain configured in their descriptor's `supportedSourceModes`:
-1. **OAuth** — Token from macOS Keychain (Claude, Codex, VertexAI)
+1. **OAuth** — Token from macOS Keychain (Claude, Codex, VertexAI). Claude defaults to `/usr/bin/security` CLI reader (avoids keychain prompts on rebuild); Security.framework available as user override.
 2. **Web/Cookies** — Browser cookie extraction via SweetCookieKit (Cursor, Copilot, Gemini). Default to Chrome-only to avoid other browser prompts.
 3. **CLI** — Parse stdout from CLI tools via PTY (Claude, Codex, Augment)
 4. **API** — Direct API calls with stored token

docs/DEVELOPMENT_SETUP.md

@@ -8,21 +8,15 @@ read_when:
 
 # Development Setup Guide
 
-## Reducing Keychain Permission Prompts
+## Keychain Permission Prompts
 
-When developing CodexBar, you may see frequent keychain permission prompts like:
+As of v0.18.0-beta.3-jl.2, CodexBar defaults to reading Claude credentials via `/usr/bin/security` CLI, which **does not trigger keychain prompts**. No special setup is needed.
 
-> **CodexBar wants to access key "Claude Code-credentials" in your keychain.**
-
-This happens because each rebuild creates a new code signature, and macOS treats it as a "different" app.
-
-### Quick Fix (Temporary)
+If you've switched to the Security.framework reader (via Preferences), you may see prompts like:
 
-When the prompt appears, click **"Always Allow"** instead of just "Allow". This grants access to the current build.
-
-### Permanent Fix (Recommended)
+> **CodexBar wants to access key "Claude Code-credentials" in your keychain.**
 
-Use a stable development certificate that doesn't change between rebuilds:
+This happens because each rebuild creates a new code signature, and macOS treats it as a "different" app. To reduce these prompts with the Security.framework reader:
 
 #### 1. Create Development Certificate
 
@@ -135,7 +129,7 @@ pkill -x CodexBar || pkill -f CodexBar.app || true
 
 ### "Permission denied" when accessing keychain
 
-Make sure you clicked **"Always Allow"** or set up the development certificate (see above).
+With the default `/usr/bin/security` CLI reader, this should not happen. If using the Security.framework reader, make sure you clicked **"Always Allow"** or set up the development certificate (see above).
 
 ### Multiple app bundles keep appearing
 

docs/KEYCHAIN_FIX.md

@@ -45,9 +45,14 @@ Load order for credentials:
 2. In-memory cache.
 3. CodexBar keychain cache (`com.steipete.codexbar.cache`, account `oauth.claude`).
 4. `~/.claude/.credentials.json`.
-5. Claude CLI keychain service: `Claude Code-credentials` (promptable fallback).
+5. Claude CLI keychain service: `Claude Code-credentials` — read via `/usr/bin/security` CLI by default (prompt-free), with Security.framework as fallback.
 
-Prompt mitigation:
+Keychain read strategy:
+- **Default: `/usr/bin/security` CLI** (`ClaudeOAuthKeychainReadStrategy.securityCLI`). The CLI binary is permanently in the keychain item's ACL (added by Claude Code during login), so reads never trigger macOS keychain prompts — even after app rebuilds or updates.
+- **Override: Security.framework** (`ClaudeOAuthKeychainReadStrategy.securityFramework`). Available via user preference. Uses `SecItemCopyMatching`, which requires the calling binary to be in the keychain ACL — invalidated on every rebuild, causing recurring prompts.
+- Strategy is stored in UserDefaults key `claudeOAuthKeychainReadStrategy`.
+
+Prompt mitigation (Security.framework fallback path only):
 - Non-interactive keychain probes use `KeychainNoUIQuery` (`LAContext.interactionNotAllowed` + `kSecUseAuthenticationUIFail`).
 - Pre-alert is shown only when preflight suggests interaction may be required.
 - Denials are cooled down in the background via `claudeOAuthKeychainDeniedUntil`
@@ -56,11 +61,14 @@ Prompt mitigation:
 - Background cache-sync-on-change also performs non-interactive Claude keychain probes (`syncWithClaudeKeychainIfChanged`)
   and can update cached OAuth data when the token changes.
 
-### Why two Claude keychain prompts can still happen on startup
+### Why two Claude keychain prompts could happen on startup (Security.framework path only)
+> **Note:** With the default `/usr/bin/security` CLI reader, keychain prompts do not occur. This section only applies
+> when the user has explicitly switched to the Security.framework reader.
+
 When CodexBar does not have usable OAuth credentials in its own cache (`com.steipete.codexbar.cache` / `oauth.claude`),
 bootstrap falls through to Claude CLI keychain reads.
 
-Current flow can perform up to two interactive reads in one bootstrap call:
+Under the Security.framework path, the flow can perform up to two interactive reads in one bootstrap call:
 1. Interactive read of the newest discovered keychain candidate.
 2. If that does not return usable data, interactive legacy service-level fallback read.