Clarify provider setup and permission repair for TestFlight

[cbusillo]

Objective

Make first-run and Settings setup clear enough that a TestFlight user knows exactly which local file/source to authorize for Code/OpenAI, Gemini, and Claude, and knows whether setup succeeded.

Finish Line

A tester can open Settings, authorize each supported provider without guessing, repair missing permissions, and understand any provider that remains stale, unknown, or failed.

Current Status

State: Active
Next action: Audit current Settings copy and provider rows against the real file/source each connector expects.
Blocked by: None.
Last verified: 2026-05-13 runtime baseline OK after install.

Scope

• In: Settings/onboarding copy, authorize/repair button text, provider setup status, file/source hints, and permission repair affordances.
• Out: new providers, reset priming, and redesigning the whole app shell.

Acceptance Criteria

• Code/OpenAI setup clearly names auth_accounts.json and explains multiple accounts are read from that file.
• Codex remains available as an option for users who use Codex rather than Code.
• Gemini setup clearly names oauth_creds.json and reports metadata discovery/configuration failures plainly.
• Claude setup points to the statusline/usage cache source currently supported by the app, not the wrong folder.
• Settings distinguishes authorized, missing permission, stale source, refresh failed, and disabled.
• File picker behavior is documented in UI expectations: JSON-only selection is enough; Finder may not visually preselect the file.

Relationships

Parent: #76
Related: #67, #68, #18

Validation

Run focused settings/account tests and canonical runtime baseline before ready-to-test.

Decisions

• Keep setup plain and local-first.
• Prefer exact file/source names over generic “authorize provider” language.

Open Questions

• Should setup live only in Settings for beta, or should the main empty state deep-link to each missing provider row?

[cbusillo]

2026-05-14 progress update:

Verified in the canonical /Applications runtime:

• Code/OpenAI setup reads auth_accounts.json and multiple OpenAI accounts are visible in the app snapshot.
• Codex has been restored as a configurable account option for people who use Codex instead of Code.
• Gemini setup is constrained to JSON files and the signed runtime successfully refreshed from oauth_creds.json.
• The false red 'File access needs repair' state after selecting a valid file was fixed by returning provider auth-file bookmarks to app-scoped storage and removing the unreachable broken-authorization UI branch.
• Finder/file-picker behavior: JSON filtering works; macOS does not reliably visually pre-highlight the target file, so the UI expectation should be that selecting the correct JSON file is enough.

Still open:

• Audit final Settings copy so it explicitly names auth_accounts.json, oauth_creds.json, and the supported Claude status/cache source.
• Make sure Settings status language cleanly distinguishes authorized, disabled, stale, refresh failed, and missing/needs-update without sounding like a permission failure when refresh simply has not run yet.

[cbusillo]

Update from the refresh/login-item hardening pass:

• File selection now has a runtime consequence beyond the foreground Settings UI: selected Code/Codex/Gemini auth JSON is imported into the shared provider credential Keychain for background refresh.
• The file picker is JSON-only. Finder may not visually pre-highlight the existing JSON file in the picker; that is an OS/file-picker behavior and not, by itself, a failed authorization signal.
• The latest installed snapshot proves the selected files are being consumed by the app/agent path: both OpenAI accounts are healthy and Gemini is healthy.
• Remaining work here is UI clarity: make the provider rows/status copy less confusing immediately after selection/repair, keep exact file names visible, and make Claude setup wording point at the statusline/cache flow instead of implying a normal JSON auth file.

[cbusillo]

Implemented a small setup-state fix:

• Settings now treats imported auth credentials in the shared provider credential Keychain as a successful saved state for Code/Codex/Gemini rows, instead of relying only on current bookmark prefix state.
• Missing/legacy path classification now only applies to providers that actually require user-selected auth JSON, so Claude is not treated like a file-selection provider.
• Claude setup copy now says it reads Context Panel statusline cache and does not need auth file selection.
• Kept the JSON-only picker behavior intentionally; this matches the current decision that only JSON files should be selectable, and Finder may still not visually pre-highlight the target file.

Validation:

• Focused Swift tests passed: AccountConfigurationStoreTests, ReleaseEntitlementsTests, SnapshotStoreTests; 37 tests.
• scripts/context-panel-runtime-baseline.sh install --launch passed with baseline=OK.
• Installed runtime fingerprint: 4ba8627d55aa690ef2497d4c9fc519cbfa541ee15e1133829712350076481503.
• Current snapshot savedAt 2026-05-14T16:31:43Z with both OpenAI accounts healthy, Gemini healthy, Claude stale.

Remaining #77 work: final visual/copy pass in Settings, especially making provider row states and any diagnostics text feel less surprising during selection/repair.

[cbusillo]

Correction after auto-review:

Fixed two follow-up regressions from the setup/keychain work:

• Keychain read failures now fall back to the existing bookmark/direct file path instead of making the provider refresh fail immediately.
• Legacy document-scoped bookmark payloads are again resolved relative to the bookmark store URL; current app-scoped payloads remain resolved without a relative base.

Added regression coverage:

• sandboxedAuthLoaderFallsBackWhenCredentialStoreThrows verifies a broken credential cache does not prevent fallback to the auth file path.

Validation after the correction:

• Focused suite passed: AccountConfigurationStoreTests, ReleaseEntitlementsTests, SnapshotStoreTests; 38 tests.
• scripts/context-panel-runtime-baseline.sh install --launch passed with baseline=OK.
• Installed runtime fingerprint: 53aa1dd72278f1d6b1e290595392c61f4c73489d0f6f93ab5cc935318d9eada6.
• Current snapshot savedAt 2026-05-14T16:47:22Z with both OpenAI accounts healthy, Gemini healthy, Claude stale.

[cbusillo]

2026-05-14 settings trust polish update:

Implemented a small Settings UI clarification pass:

• Account setup state now says File saved for Code/Codex/Gemini and Connected for Claude OAuth, so saved credentials are not confused with provider refresh health.
• Each enabled, configured provider row now shows a separate last-refresh summary from the stored provider reports: healthy, stale, unknown, failed, or no report yet.
• OpenAI/Code refresh summaries explicitly say OpenAI refresh and summarize multiple accounts from auth_accounts.json when present, instead of implying the single settings row is one provider account.
• Claude OAuth setup copy now says automatic background refresh, matching the new supported path.

Validation:

• Focused AccountConfigurationStoreTests passed: 16 tests.
• Full swift test passed: 156 tests.
• git diff --check passed.
• scripts/context-panel-runtime-baseline.sh install --launch passed with baseline=OK.
• Installed runtime fingerprint: 98d30dc1f6aaf5c4ab6b9b82c35616efb8463a4f58a008e2417111f447b05518.
• Runtime receipt shows app, widget extension, URL handler, and refresh login item all pointing to /Applications/Context Panel.app; current snapshot savedAt 2026-05-14T23:00:28Z.

Remaining #77 work: visual/manual check of the Settings pane in the installed runtime and deciding whether the issue is ready to close after Chris confirms the row copy feels clear in use.