Tighten status language and diagnostics for TestFlight

[cbusillo]

Objective

Make the app and widget status language calm, plain, and diagnosable so beta users understand whether data is available, close to limit, limited, stale, unknown, refreshing, or failed.

Finish Line

User-facing copy avoids scary/raw technical messages in primary UI, while diagnostics preserve enough detail to debug provider failures and runtime issues.

Current Status

State: Active
Next action: Audit visible status strings across app, widget, provider rows, and settings.
Blocked by: None.
Last verified: 2026-05-13 burn pace reset-boundary behavior changed to measuring burn instead of false over pace.

Scope

• In: user-facing status copy, forecast/burn language, diagnostics surface, last refresh health, and provider failure wording.
• Out: detailed charting/history and notifications.

Acceptance Criteria

• Primary UI uses plain states: available, close to limit, limited, unknown, stale, refreshing, refresh failed.
• Raw 401/403/429 details do not appear as the primary explanation unless diagnostics are open.
• Burn-rate/forecast language does not show red/over-pace when the ratio cannot be computed.
• Diagnostics show last refresh time, last successful provider refresh, stale/failure provider reports, and runtime baseline guidance.
• Widget empty/setup state stays simple and does not become a dashboard.

Relationships

Parent: #76
Related: #65

Validation

Use UI review/screenshots where possible plus focused tests for forecast/status copy.

Decisions

• Prefer calm uncertainty over false precision.
• Keep raw provider details behind diagnostics/troubleshooting.

Open Questions

• Should diagnostics live in Settings, provider detail, or a dedicated Troubleshooting page for beta?

[cbusillo]

2026-05-14 burn-rate/forecast note:

Investigated the false deep-red burn-rate concern. The risky edge case is when reset time is at or just behind now: the required burn denominator can collapse to zero/unknown, and UI copy must treat that as measuring/unknown rather than over pace.

Current expectation for this issue:

• If burnPaceRatio cannot be computed or is non-finite, primary UI should show calm measuring/unknown language, not red over-pace language.
• Add/keep tests around reset-passed, near-reset, and plenty-of-capacity cases so stale reset boundaries do not scare testers.
• Keep raw provider details like 401 in diagnostics, while primary UI explains expired auth/rate-limit/stale states plainly.

[cbusillo]

Status after today’s runtime/setup work:

Already improved:

• Primary refresh path no longer exposes raw permission failures for the normal background-agent path; auth JSON is imported into shared Keychain and the installed snapshot is healthy for OpenAI/Gemini.
• Claude stale is expected when the local statusline/cache has not changed, and should be phrased as stale local source rather than a broken account.
• Forecast/burn-rate edge cases have tests from the earlier burn-rate pass.

Remaining work for this issue:

• Replace raw enum labels like healthy/stale/failure in app diagnostics with friendlier labels: available, stale, refresh failed, unknown, refreshing.
• Add a real diagnostics/troubleshooting surface with last refresh time, current snapshot savedAt, stale provider reports, failed provider reports, and runtime-baseline guidance.
• Keep raw provider details such as 401/403/429 in diagnostics, not primary app/widget copy.
• Review widget strings for Data stale/Data unknown/Refresh failed once the app diagnostics wording is settled.

Blocker: needs a focused UI pass with screenshots from /Applications/Context Panel.app. I am leaving this open intentionally rather than closing it on runtime evidence alone.

[cbusillo]

2026-05-14 progress update:

Implemented a focused status/diagnostics pass:

• Primary overview no longer shows raw/redacted provider error text inline; it now shows calm status copy such as Refresh failed; see Settings.
• Settings account rows no longer append detailed provider failure messages; failed rows say to see Diagnostics.
• Settings Diagnostics now shows runtime, status, last refresh, last successful provider refresh, and stale/failed provider reports with diagnostic details.
• Diagnostics now explicitly reminds maintainers to validate with scripts/context-panel-runtime-baseline.sh check before ready-to-test handoff.
• Widget setup/status copy was audited and left unchanged; it is already simple and status-only.

Validation:

• Full swift test passed: 156 tests.
• scripts/context-panel-runtime-baseline.sh install --launch passed with baseline=OK.
• Installed runtime fingerprint: cdb6e86804168e1f8563e56acfee42003e342bd1882344ae4ee033d742a984c7.
• Runtime receipt shows app, widget extension, URL handler, and refresh login item all pointing to /Applications/Context Panel.app.

Remaining #80 work: manual visual check of Settings/overview copy in the installed runtime, then decide whether to close this issue or split any remaining polish into post-TestFlight follow-ups.

[cbusillo]

2026-05-14 follow-up:

Tightened Settings diagnostics after live UI feedback:

• Removed maintainer-only runtime-baseline command copy from the normal Settings UI.
• Replaced the raw app-group/config path with user-facing Local app storage wording.
• Kept useful diagnostics: installed app path, status, last refresh, last provider success, provider reports, and details when needed.

Also made the Reset Primer section honest while #75 remains open: it now says primer requests are planned for a later build and disables the controls.

[cbusillo]

2026-05-14 polish audit update:

Agent + local review found a few remaining beta-copy issues worth discussing before implementation:

Do-now candidates:

• Replace implementation-shaped dashboard tags like accounts folded and raw status enum chips with user-facing copy or remove them when healthy.
• Simplify/reset the disabled Reset Primer UI so it reads as a deferred capability rather than a half-configurable feature.
• Soften widget fallback text: measuring burn, not observed, no data, allowance unknown, Data unknown.
• Remove or hide low-value Diagnostics rows (Storage, Installed app) from normal Settings unless we add an Advanced/System Info affordance.

Discuss-before-change candidates:

• Whether to keep Diagnostics always visible for beta testers or collapse it behind an advanced disclosure.
• Whether the Accounts section should stay dense for beta diagnostics or get a calmer visual hierarchy before TestFlight.
• Whether Fast Mode copy should remain precise (1.5x throughput for 2x limit spend) or become plainer (work faster, use limits about twice as quickly).

[cbusillo]

2026-05-14 implementation update:

Applied the agreed TestFlight copy polish:

• Replaced implementation-shaped dashboard tags (accounts folded, raw status enum chips) with user-facing copy and hid healthy status chips.
• Kept Reset Primer visible but changed it to a coming-soon capability with calmer copy and disabled controls.
• Softened widget fallback/problem text (Update failed, Old data, Awaiting data, calibrating, no reset data, limit unknown).
• Removed low-value Diagnostics rows (Storage, Installed app) and renamed Last provider success to Last successful refresh.
• Simplified background refresh and Code auth-file instructions.
• Updated the widget picker description to avoid implementation wording.

Validation: swift test passed 156 tests, git diff --check clean, and scripts/context-panel-runtime-baseline.sh install --launch passed with baseline=OK for /Applications/Context Panel.app.

[cbusillo]

2026-05-14 final copy tweak:

Updated the Fast Mode explanatory copy to the agreed wording: Fast mode works 50% faster, but uses limits about twice as quickly.

Validation after the tweak:

• swift test passed 156 tests.
• git diff --check clean.
• scripts/context-panel-runtime-baseline.sh install --launch passed with baseline=OK for /Applications/Context Panel.app.