chore: import upstream snapshot with attribution

docs/architecture.md

@@ -0,0 +1,30 @@
+---
+summary: "Architecture overview: modules, entry points, and data flow."
+read_when:
+  - Reviewing architecture before feature work
+  - Refactoring app structure, app lifecycle, or module boundaries
+---
+
+# Architecture overview
+
+## Modules
+- `Sources/CodexBarCore`: fetch + parse (Codex RPC, PTY runner, Claude probes, OpenAI web scraping, status polling).
+- `Sources/CodexBar`: state + UI (UsageStore, SettingsStore, StatusItemController, menus, icon rendering).
+- `Sources/CodexBarWidget`: WidgetKit extension wired to the shared snapshot.
+- `Sources/CodexBarCLI`: bundled CLI for `codexbar` usage/status output.
+- `Sources/CodexBarClaudeWatchdog`: helper process for stable Claude CLI PTY sessions.
+- `Sources/CodexBarClaudeWebProbe`: CLI helper to diagnose Claude web fetches.
+
+## Entry points
+- `CodexBarApp`: SwiftUI keepalive + Settings scene.
+- `AppDelegate`: wires status controller, Sparkle updater, notifications.
+
+## Data flow
+- Background refresh → `UsageFetcher`/provider probes → `UsageStore` → menu/icon/widgets.
+- Settings toggles feed `SettingsStore` → `UsageStore` refresh cadence + feature flags.
+
+## Concurrency & platform
+- Swift 6 strict concurrency enabled; prefer Sendable state and explicit MainActor hops.
+- macOS 14+ targeting; avoid deprecated APIs when refactoring.
+
+See also: `docs/providers.md`, `docs/refresh-loop.md`, `docs/ui.md`.