Prototype portable UI preferences contract

[steipete]

Summary

• prototype a sparse, versioned portable UI-preference schema and file store
• keep portable preferences in a separate preferences.json beside the resolved config, with a CODEXBAR_PREFERENCES override
• document explicit-key precedence plus portable, device-local, privacy, and security boundaries
• intentionally leave SettingsStore runtime wiring out until the product choice is approved

Product decision

Recommended contract:

• separate preference file rather than the existing provider config
• opt in by creating the file; no automatic creation or migration
• explicit valid file key > local UserDefaults value > code default
• once enabled, UI changes dual-write the preference file and UserDefaults

The existing config can contain API keys, cookie headers, and other credentials. Putting UI preferences there would encourage users to sync or commit a secret-bearing file. The alternatives are a preference block inside that config (simpler, unsafe sharing affordance) or export/import only (safer, but not continuous sync).

Scope

The prototype includes presentation and behavior preferences that can safely follow a user between Macs. It excludes credentials, account routing, login items, terminal paths, window state, discovery/debug state, privacy toggles, histories, notifications, and storage policy.

Proof

• swift test --filter CodexBarPortablePreferencesTests (8 tests)
• make check
• make test (44 shards)
• ./Scripts/package_app.sh
• autoreview clean after fixing sparse-version and invalid-language handling

No screenshot: this decision branch deliberately adds no live UI or runtime behavior.

Refs #1282

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 1, 2026, 6:38 AM ET / 10:38 UTC.

Summary
The branch adds a CodexBarCore portable UI preferences schema/store, focused tests, and a decision document for a separate preferences.json with a CODEXBAR_PREFERENCES override.

Reproducibility: not applicable. this is a feature/product-contract prototype rather than a bug report. Source inspection shows the branch adds schema/store/tests/docs but no live runtime path to reproduce.

Review metrics: 2 noteworthy metrics.

• Changed surface: 3 files added, 0 existing files changed. This confirms the branch is a contract prototype rather than a runtime migration of current settings behavior.
• Runtime wiring: 0 SettingsStore files touched. Existing users should not see preference behavior changes from this branch until a follow-up wires the store into runtime settings.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #1282
Summary: This PR is the candidate/product-contract branch for the open UI preferences syncing feature request, but it intentionally does not close or fully implement runtime behavior yet.

Members:

• canonical: Support storing UI preferences in config.json/preferences.json for dotfiles syncing #1282 - The open feature request asks for dotfiles-syncable UI preferences and is explicitly referenced by this PR.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Resolve the storage and write-back product decision before adding SettingsStore runtime wiring.

Risk before merge

• [P1] The remaining risk is product-contract timing: merging the prototype would establish a public storage/API direction before the SettingsStore precedence and write-back behavior are approved.

Maintainer options:

1. Decide the mitigation before merge
   Keep the draft open until maintainers approve the storage contract, then either merge this schema/docs as the agreed contract or follow it with tested SettingsStore runtime wiring.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] This owner-authored draft needs maintainer/product approval for the storage contract rather than an automated repair PR.

Security
Cleared: The diff adds a non-secret preferences schema/store, tests, and docs without dependency, workflow, credential, or provider-auth changes.

Review details

Best possible solution:

Keep the draft open until maintainers approve the storage contract, then either merge this schema/docs as the agreed contract or follow it with tested SettingsStore runtime wiring.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature/product-contract prototype rather than a bug report. Source inspection shows the branch adds schema/store/tests/docs but no live runtime path to reproduce.

Is this the best way to solve the issue?

Yes for a prototype: separating portable UI preferences from secret-bearing provider config is the safer maintainable direction. Final runtime wiring still needs the owner/product decision documented in the PR body and docs.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 306cf96787f0.

Label changes

Label changes:

• add P3: This is a low-risk settings portability/product-contract feature prototype, not a regression or broken user workflow.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required here because this is an owner-authored draft prototype with no live UI or runtime behavior to demonstrate.

Label justifications:

• P3: This is a low-risk settings portability/product-contract feature prototype, not a regression or broken user workflow.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required here because this is an owner-authored draft prototype with no live UI or runtime behavior to demonstrate.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully and applied to the review, especially the guidance to avoid live Keychain/provider validation and prefer focused source/tests for CLI-testable settings behavior. (AGENTS.md:1, 306cf96787f0)
• PR metadata: GitHub reports this PR as an owner-authored draft with one commit, three added files, no maintainer reviews, and head SHA 72bff35. (72bff35595c0)
• Prototype source: The new source defines a sparse portable preference schema, per-key normalization/resolution, and a file store with CODEXBAR_PREFERENCES override and default path beside the resolved config. (Sources/CodexBarCore/Config/CodexBarPortablePreferences.swift:3, 72bff35595c0)
• Focused tests: The added tests cover explicit-key precedence, invalid value fallback, unknown provider IDs, excluded secret/device-local keys, opt-in store behavior, restrictive file permissions, future-version refusal, and default path override. (Tests/CodexBarTests/CodexBarPortablePreferencesTests.swift:5, 72bff35595c0)
• Decision document: The new document recommends a separate opt-in preferences.json, excludes credential/privacy/device-local state, and states runtime SettingsStore wiring is intentionally not connected until the storage and write-back choices are approved. (docs/portable-preferences.md:7, 72bff35595c0)
• Current settings boundary: Current main still loads and writes the relevant UI preferences through UserDefaults, including refresh cadence, display options, merged overview selection, provider sorting, and app language. (Sources/CodexBar/SettingsStore.swift:365, 306cf96787f0)

Likely related people:

• steipete: Authored the provider-secrets-to-config refactor and recent current-main settings/config history, and this PR is also his owner-authored decision branch. (role: settings/config area contributor; confidence: high; commits: a1b94b48df4e, f380287041b8, 72bff35595c0; files: Sources/CodexBar/SettingsStore.swift, Sources/CodexBar/SettingsStore+ConfigPersistence.swift, Sources/CodexBarCore/Config/CodexBarConfig.swift)
• Ratul Sarna: Introduced and refined the merged overview selection persistence that appears in the portable preference whitelist. (role: merged overview preference contributor; confidence: medium; commits: 549f7583156c, c6bfb61339c2; files: Sources/CodexBar/SettingsStore+Defaults.swift, Sources/CodexBar/SettingsStore.swift, Tests/CodexBarTests/SettingsStoreTests.swift)
• Zihao Qi: Recently changed SettingsStore preference/default behavior in the same area, including cost summary display style state and tests. (role: recent adjacent settings contributor; confidence: medium; commits: 8eb852493103; files: Sources/CodexBar/SettingsStore.swift, Sources/CodexBar/SettingsStore+Defaults.swift, Tests/CodexBarTests/SettingsStoreTests.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.