@sriinnu/runic 1.0.0

package/docs/progress-bar-visual-test.swift

@@ -0,0 +1,375 @@
+import SwiftUI
+
+/// Visual test cases for the improved UsageProgressBar
+/// Copy this into a SwiftUI preview or test view to see all variants
+
+struct ProgressBarShowcase: View {
+    var body: some View {
+        VStack(alignment: .leading, spacing: 32) {
+            Text("UsageProgressBar Improvements")
+                .font(.title.bold())
+
+            // MARK: - Height Variants
+            VStack(alignment: .leading, spacing: 16) {
+                Text("Height Variants")
+                    .font(.headline)
+
+                VStack(alignment: .leading, spacing: 8) {
+                    Text("Compact (6pt) - Team member rows")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                    UsageProgressBar(
+                        percent: 75,
+                        tint: .blue,
+                        accessibilityLabel: "Compact example",
+                        height: .compact)
+
+                    Text("Regular (8pt) - Default menu cards")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                    UsageProgressBar(
+                        percent: 60,
+                        tint: .green,
+                        accessibilityLabel: "Regular example",
+                        height: .regular)
+
+                    Text("Large (10pt) - Dashboard hero sections")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                    UsageProgressBar(
+                        percent: 85,
+                        tint: .orange,
+                        accessibilityLabel: "Large example",
+                        height: .large)
+                }
+            }
+
+            Divider()
+
+            // MARK: - Percentage Variants
+            VStack(alignment: .leading, spacing: 16) {
+                Text("Different Percentages (Regular)")
+                    .font(.headline)
+
+                VStack(alignment: .leading, spacing: 8) {
+                    HStack {
+                        Text("10%")
+                            .font(.caption.monospacedDigit())
+                            .frame(width: 50, alignment: .trailing)
+                        UsageProgressBar(
+                            percent: 10,
+                            tint: .green,
+                            accessibilityLabel: "10 percent")
+                    }
+
+                    HStack {
+                        Text("25%")
+                            .font(.caption.monospacedDigit())
+                            .frame(width: 50, alignment: .trailing)
+                        UsageProgressBar(
+                            percent: 25,
+                            tint: .green,
+                            accessibilityLabel: "25 percent")
+                    }
+
+                    HStack {
+                        Text("50%")
+                            .font(.caption.monospacedDigit())
+                            .frame(width: 50, alignment: .trailing)
+                        UsageProgressBar(
+                            percent: 50,
+                            tint: .blue,
+                            accessibilityLabel: "50 percent")
+                    }
+
+                    HStack {
+                        Text("75%")
+                            .font(.caption.monospacedDigit())
+                            .frame(width: 50, alignment: .trailing)
+                        UsageProgressBar(
+                            percent: 75,
+                            tint: .orange,
+                            accessibilityLabel: "75 percent")
+                    }
+
+                    HStack {
+                        Text("90%")
+                            .font(.caption.monospacedDigit())
+                            .frame(width: 50, alignment: .trailing)
+                        UsageProgressBar(
+                            percent: 90,
+                            tint: .red,
+                            accessibilityLabel: "90 percent")
+                    }
+
+                    HStack {
+                        Text("100%")
+                            .font(.caption.monospacedDigit())
+                            .frame(width: 50, alignment: .trailing)
+                        UsageProgressBar(
+                            percent: 100,
+                            tint: .red,
+                            accessibilityLabel: "100 percent")
+                    }
+                }
+            }
+
+            Divider()
+
+            // MARK: - Color Variants
+            VStack(alignment: .leading, spacing: 16) {
+                Text("Color Variants")
+                    .font(.headline)
+
+                VStack(alignment: .leading, spacing: 8) {
+                    HStack {
+                        Text("Blue")
+                            .font(.caption)
+                            .frame(width: 80, alignment: .leading)
+                        UsageProgressBar(
+                            percent: 65,
+                            tint: .blue,
+                            accessibilityLabel: "Blue")
+                    }
+
+                    HStack {
+                        Text("Green")
+                            .font(.caption)
+                            .frame(width: 80, alignment: .leading)
+                        UsageProgressBar(
+                            percent: 45,
+                            tint: .green,
+                            accessibilityLabel: "Green")
+                    }
+
+                    HStack {
+                        Text("Orange")
+                            .font(.caption)
+                            .frame(width: 80, alignment: .leading)
+                        UsageProgressBar(
+                            percent: 75,
+                            tint: .orange,
+                            accessibilityLabel: "Orange")
+                    }
+
+                    HStack {
+                        Text("Red")
+                            .font(.caption)
+                            .frame(width: 80, alignment: .leading)
+                        UsageProgressBar(
+                            percent: 90,
+                            tint: .red,
+                            accessibilityLabel: "Red")
+                    }
+
+                    HStack {
+                        Text("Purple")
+                            .font(.caption)
+                            .frame(width: 80, alignment: .leading)
+                        UsageProgressBar(
+                            percent: 55,
+                            tint: .purple,
+                            accessibilityLabel: "Purple")
+                    }
+
+                    HStack {
+                        Text("Custom")
+                            .font(.caption)
+                            .frame(width: 80, alignment: .leading)
+                        UsageProgressBar(
+                            percent: 70,
+                            tint: Color(red: 0.3, green: 0.7, blue: 0.9),
+                            accessibilityLabel: "Custom color")
+                    }
+                }
+            }
+
+            Divider()
+
+            // MARK: - Animation Demo
+            VStack(alignment: .leading, spacing: 16) {
+                Text("Animation Test")
+                    .font(.headline)
+
+                AnimatedProgressDemo()
+            }
+
+            Divider()
+
+            // MARK: - Real-World Examples
+            VStack(alignment: .leading, spacing: 16) {
+                Text("Real-World Examples")
+                    .font(.headline)
+
+                // API Usage Card
+                VStack(alignment: .leading, spacing: 8) {
+                    HStack {
+                        Text("API Usage")
+                            .font(.body.weight(.medium))
+                        Spacer()
+                        Text("1,234 / 2,000")
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                    }
+
+                    UsageProgressBar(
+                        percent: 61.7,
+                        tint: .blue,
+                        accessibilityLabel: "API usage")
+
+                    HStack {
+                        Text("61.7% used")
+                            .font(.caption)
+                        Spacer()
+                        Text("Resets in 12 days")
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                    }
+                }
+                .padding()
+                .background(
+                    RoundedRectangle(cornerRadius: 8, style: .continuous)
+                        .fill(Color(nsColor: .controlBackgroundColor)))
+
+                // Budget Tracking
+                VStack(alignment: .leading, spacing: 8) {
+                    HStack {
+                        Text("Project Budget")
+                            .font(.body.weight(.medium))
+                        Spacer()
+                        Text("$45 / $50")
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                    }
+
+                    UsageProgressBar(
+                        percent: 90,
+                        tint: .orange,
+                        accessibilityLabel: "Budget usage")
+
+                    HStack {
+                        Text("90% spent")
+                            .font(.caption)
+                            .foregroundStyle(.orange)
+                        Spacer()
+                        Text("Near limit")
+                            .font(.caption)
+                            .foregroundStyle(.orange)
+                            .fontWeight(.medium)
+                    }
+                }
+                .padding()
+                .background(
+                    RoundedRectangle(cornerRadius: 8, style: .continuous)
+                        .fill(Color(nsColor: .controlBackgroundColor)))
+
+                // Team Member Quota
+                HStack(spacing: 12) {
+                    Circle()
+                        .fill(.blue)
+                        .frame(width: 36, height: 36)
+                        .overlay {
+                            Text("JD")
+                                .font(.footnote.weight(.semibold))
+                                .foregroundStyle(.white)
+                        }
+
+                    VStack(alignment: .leading, spacing: 4) {
+                        Text("John Doe")
+                            .font(.body.weight(.medium))
+
+                        HStack(spacing: 4) {
+                            Text("8,500 / 10,000")
+                                .font(.caption2)
+                                .foregroundStyle(.secondary)
+
+                            UsageProgressBar(
+                                percent: 85,
+                                tint: .red,
+                                accessibilityLabel: "John Doe quota",
+                                height: .compact)
+                                .frame(maxWidth: 100)
+                        }
+                    }
+                }
+                .padding()
+                .background(
+                    RoundedRectangle(cornerRadius: 8, style: .continuous)
+                        .fill(Color(nsColor: .controlBackgroundColor)))
+            }
+        }
+        .padding(32)
+        .frame(width: 500)
+    }
+}
+
+/// Demonstrates the smooth spring animation
+private struct AnimatedProgressDemo: View {
+    @State private var percent: Double = 0
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Text("Spring animation (tap to randomize)")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+
+            UsageProgressBar(
+                percent: self.percent,
+                tint: .purple,
+                accessibilityLabel: "Animation demo")
+                .onTapGesture {
+                    self.percent = Double.random(in: 10...100)
+                }
+
+            HStack {
+                Button("0%") { self.percent = 0 }
+                    .buttonStyle(.bordered)
+                    .controlSize(.mini)
+                Button("25%") { self.percent = 25 }
+                    .buttonStyle(.bordered)
+                    .controlSize(.mini)
+                Button("50%") { self.percent = 50 }
+                    .buttonStyle(.bordered)
+                    .controlSize(.mini)
+                Button("75%") { self.percent = 75 }
+                    .buttonStyle(.bordered)
+                    .controlSize(.mini)
+                Button("100%") { self.percent = 100 }
+                    .buttonStyle(.bordered)
+                    .controlSize(.mini)
+            }
+        }
+    }
+}
+
+// MARK: - Preview
+
+#Preview {
+    ProgressBarShowcase()
+}
+
+// MARK: - Usage Instructions
+
+/*
+ To test the improved progress bar:
+
+ 1. Create a new SwiftUI view in Xcode
+ 2. Copy this entire file content
+ 3. Use the #Preview to see all variants
+ 4. Test the animation by clicking buttons
+ 5. Verify VoiceOver reads percentages correctly
+
+ Key improvements to observe:
+ - Glossy top highlight (white gradient)
+ - Subtle glow/shadow around filled portion
+ - 3-color gradient for depth
+ - Smooth spring animation (natural bounce)
+ - Track border for definition
+ - Three distinct size options
+
+ Compare with the old version:
+ - Smoother, more refined appearance
+ - Better visual hierarchy
+ - More professional and modern
+ - Maintains accessibility
+ */

package/docs/provider.md

@@ -0,0 +1,202 @@
+---
+summary: "Provider authoring guide: shared host APIs, provider boundaries, and how to add a new provider."
+read_when:
+  - Adding a new provider (usage + status + identity)
+  - Refactoring provider architecture or shared host APIs
+  - Reviewing provider boundaries (no identity leakage)
+---
+
+# Provider authoring guide
+
+Goal: adding a provider should feel like:
+- add one folder
+- define one descriptor + strategies
+- add one implementation (UI hooks only)
+- done (tests + docs)
+
+This doc describes the **current provider architecture** (post-macro registry) and the exact steps to add a new provider.
+
+## Terms
+- **Provider**: a source of usage/quota/status data (Codex, Claude, Gemini, Antigravity, Cursor, …).
+- **Descriptor**: the single source of truth for labels, URLs, defaults, and fetch strategies.
+- **Fetch strategy**: one concrete way to obtain usage (CLI, web cookies, OAuth API, local probe, etc.).
+- **Host APIs**: shared capabilities we provide to providers (Keychain, browser cookies, PTY, HTTP, WebView scrape, token-cost).
+- **Identity fields**: email/org/plan/loginMethod. Must stay **siloed per provider**.
+
+## Architecture overview (now)
+- `Sources/RunicCore`: provider descriptors + fetch strategies + probes + parsing + shared utilities.
+- `Sources/Runic`: UI/state + provider implementations (settings/login/menu hooks only).
+- Provider IDs are compile-time: `UsageProvider` enum (used for persistence + widgets).
+- Provider wiring is descriptor-driven:
+  - `ProviderDescriptor` owns labels, URLs, default enablement, and fetch pipeline.
+  - `ProviderFetchStrategy` objects implement concrete fetch paths.
+  - CLI + app both call the same descriptor/fetch pipeline.
+
+Common building blocks already exist:
+- PTY: `TTYCommandRunner`
+- subprocess: `SubprocessRunner`
+- cookie import: `BrowserCookieImporter` (Safari/Chrome/Firefox adapters)
+- OpenAI dashboard web scrape: `OpenAIDashboardFetcher` (WKWebView + JS)
+- cost usage: local log scanner (Codex + Claude)
+
+The old “switch provider” wiring is gone. Everything should be driven by the descriptor and its strategies.
+
+## Provider descriptor (source of truth)
+
+Introduce a single descriptor per provider:
+- `id` (stable `UsageProvider`)
+- display/labels/URLs (menu title, dashboard URL, status URL)
+- UI branding (icon name, primary color)
+- capabilities (supportsCredits, supportsTokenCost, supportsStatusPolling, supportsLogin)
+- fetch plan (allowed `--source` modes + ordered strategy pipeline)
+- CLI metadata (cliName, aliases, version provider)
+- account behavior (e.g., `usesAccountFallback` for Codex auth.json)
+
+UI and settings should become descriptor-driven:
+- no provider-specific branching for labels/links/toggle titles
+- minimal provider-specific UI (only when a provider truly needs bespoke UX)
+
+## Fetch strategies
+
+A provider declares a pipeline of strategies, in priority order. Each strategy:
+- advertises a `kind` (cli, web cookies, oauth, api token, local probe, web dashboard)
+- declares availability (checks settings, cookies, env vars, installed CLI)
+- fetches `UsageSnapshot` (and optional credits/dashboard)
+- can be filtered by CLI `--source` or app settings
+
+The pipeline resolves to the best available strategy, and falls back on failure when allowed.
+Each run returns a `ProviderFetchOutcome` with **attempts + errors** for debug UI and CLI `--verbose`.
+
+## Host APIs are explicit, small, testable
+Expose a narrow set of protocols/structs that provider implementations can use:
+- `KeychainAPI`: read-only, allowlisted service/account pairs
+- `BrowserCookieAPI`: import cookies by domain list; returns cookie header + diagnostics
+- `PTYAPI`: run CLI interactions with timeouts + “send on substring” + stop rules
+- `HTTPAPI`: URLSession wrapper with domain allowlist + standard headers + tracing
+- `WebViewScrapeAPI`: WKWebView lease + `evaluateJavaScript` + snapshot dumping
+- `TokenCostAPI`: Cost Usage local-log integration (Codex/Claude today; extend later)
+- `StatusAPI`: status polling helpers (Statuspage + Workspace incidents)
+- `LoggerAPI`: scoped logger + redaction helpers
+
+Rule: providers do not talk to `FileManager`, `Security`, or “browser internals” directly unless they *are* the host API implementation.
+
+## Provider-specific code layout
+- `Sources/RunicCore/Providers/<ProviderID>/`
+  - `<ProviderID>Descriptor.swift` (descriptor + strategy pipeline)
+  - `<ProviderID>Strategies.swift` (strategy implementations)
+  - `<ProviderID>Probe.swift` / `<ProviderID>Fetcher.swift`
+  - `<ProviderID>Models.swift`
+  - `<ProviderID>Parser.swift` (if text/HTML parsing)
+- `Sources/Runic/Providers/<ProviderID>/`
+  - `<ProviderID>ProviderImplementation.swift` (settings/login UI hooks only)
+
+## Minimal provider example (copy-paste)
+
+```swift
+import RunicMacroSupport
+import Foundation
+
+@ProviderDescriptorRegistration
+@ProviderDescriptorDefinition
+public enum ExampleProviderDescriptor {
+    static func makeDescriptor() -> ProviderDescriptor {
+        ProviderDescriptor(
+            id: .example,
+            metadata: ProviderMetadata(
+                id: .example,
+                displayName: "Example",
+                sessionLabel: "Session",
+                weeklyLabel: "Weekly",
+                opusLabel: nil,
+                supportsOpus: false,
+                supportsCredits: false,
+                creditsHint: "",
+                toggleTitle: "Show Example usage",
+                cliName: "example",
+                defaultEnabled: false,
+                isPrimaryProvider: false,
+                usesAccountFallback: false,
+                dashboardURL: nil,
+                statusPageURL: nil),
+            branding: ProviderBranding(
+                iconStyle: .codex,
+                iconResourceName: "ProviderIcon-example",
+                color: ProviderColor(red: 0.2, green: 0.6, blue: 0.8)),
+            tokenCost: ProviderTokenCostConfig(
+                supportsTokenCost: false,
+                noDataMessage: { "Example cost summary is not supported." }),
+            fetchPlan: ProviderFetchPlan(
+                sourceModes: [.auto, .cli],
+                pipeline: ProviderFetchPipeline(resolveStrategies: { _ in [ExampleFetchStrategy()] })),
+            cli: ProviderCLIConfig(
+                name: "example",
+                versionDetector: nil))
+    }
+}
+
+struct ExampleFetchStrategy: ProviderFetchStrategy {
+    let id: String = "example.cli"
+    let kind: ProviderFetchKind = .cli
+
+    func isAvailable(_: ProviderFetchContext) async -> Bool { true }
+
+    func fetch(_: ProviderFetchContext) async throws -> ProviderFetchResult {
+        let usage = UsageSnapshot(
+            primary: .init(usedPercent: 0, windowMinutes: nil, resetsAt: nil, resetDescription: nil),
+            secondary: nil,
+            updatedAt: Date(),
+            identity: nil)
+        return self.makeResult(usage: usage, sourceLabel: "cli")
+    }
+
+    func shouldFallback(on _: Error, context _: ProviderFetchContext) -> Bool { false }
+}
+```
+
+## Guardrails (non-negotiable)
+- Identity silo: never display identity/plan fields from provider A inside provider B UI.
+- Privacy: default to on-device parsing; browser cookies are opt-in and never persisted by us beyond WebKit stores.
+- Reliability: providers must be timeout-bounded; no unbounded waits on network/PTY/UI.
+- Degradation: prefer cached data over flapping; show clear errors when stale.
+
+## Adding a new provider (current flow)
+
+Checklist:
+- Add `UsageProvider` case in `Sources/RunicCore/Providers/Providers.swift`.
+- Create `Sources/RunicCore/Providers/<ProviderID>/`:
+  - `<ProviderID>Descriptor.swift`: define `ProviderDescriptor` + fetch pipeline.
+  - `<ProviderID>Strategies.swift`: implement one or more `ProviderFetchStrategy`.
+  - `<ProviderID>Probe.swift` / `<ProviderID>Fetcher.swift`: concrete fetcher logic.
+  - `<ProviderID>Models.swift`: snapshot structs.
+  - `<ProviderID>Parser.swift` (if needed).
+- Attach `@ProviderDescriptorRegistration` + `@ProviderDescriptorDefinition` to the descriptor type.
+  Implement `static func makeDescriptor() -> ProviderDescriptor`.
+- Attach `@ProviderImplementationRegistration` to the implementation type (macros auto-register).
+  - No manual list edits.
+- Add `Sources/Runic/Providers/<ProviderID>/<ProviderID>ProviderImplementation.swift`:
+  - `ProviderImplementation` only for settings/login UI hooks.
+- Add icons + color in descriptor:
+  - `iconName` must match `ProviderIcon-<id>` asset.
+  - Color used in menu cards + switcher.
+- If CLI-specific behavior is needed:
+  - add `cliName`, `cliAliases`, `sourceModes`, `versionProvider` in descriptor.
+  - strategies decide which `--source` modes apply.
+- Tests:
+  - `UsageSnapshot` mapping unit tests
+  - strategy availability + fallback tests
+  - CLI provider parsing (aliases + --source validation)
+- Docs:
+  - add provider section in `docs/providers.md` with data source + auth notes
+  - update `docs/provider.md` if the pipeline model changes
+
+## UI notes (Providers settings)
+Current: checkboxes per provider.
+
+Preferred direction: table/list rows (like a “sessions” table):
+- Provider (name + short auth hint)
+- Enabled toggle
+- Status (ok/stale/error + last updated)
+- Auth source (CLI / cookies / web / oauth) when applicable
+- Actions (Login / Diagnose / Copy debug log)
+
+This keeps the pane scannable once we have >5 providers.

package/docs/providers.md

@@ -0,0 +1,86 @@
+---
+summary: "Provider data sources and parsing overview (Codex, Claude, Gemini, Antigravity, Cursor, Droid/Factory, MiniMax, z.ai, Copilot)."
+read_when:
+  - Adding or modifying provider fetch/parsing
+  - Adjusting provider labels, toggles, or metadata
+  - Reviewing data sources for providers
+---
+
+# Providers
+
+## Fetch strategies (current)
+Legend: web (browser cookies/WebView), cli (RPC/PTy), oauth (API), api token, local probe, web dashboard.
+Source labels (CLI/header): `openai-web`, `web`, `oauth`, `api`, `local`, plus provider-specific CLI labels (e.g. `codex-cli`, `claude`).
+
+| Provider | Strategies (ordered for auto) |
+| --- | --- |
+| Codex | Web dashboard (`openai-web`) → CLI RPC/PTy (`codex-cli`); app uses CLI usage + optional dashboard scrape. |
+| Claude | OAuth API (`oauth`) → Web API (`web`) → CLI PTY (`claude`). |
+| Gemini | OAuth API via Gemini CLI credentials (`api`). |
+| Antigravity | Local LSP/HTTP probe (`local`). |
+| Cursor | Web API via cookies → stored WebKit session (`web`). |
+| Droid/Factory | Web cookies → stored tokens → local storage → WorkOS cookies (`web`). |
+| MiniMax | Web cookies + Chromium local storage token (`web`). |
+| z.ai | API token (Keychain/env) → quota API (`api`). |
+| Copilot | API token (device flow/env) → copilot_internal API (`api`). |
+
+## Codex
+- Web dashboard (when enabled): `https://chatgpt.com/codex/settings/usage` via WebView + browser cookies.
+- CLI RPC default: `codex ... app-server` JSON-RPC (`account/read`, `account/rateLimits/read`).
+- CLI PTY fallback: `/status` scrape.
+- Local cost usage: scans `~/.codex/sessions/**/*.jsonl` (last 30 days).
+- Status: Statuspage.io (OpenAI).
+- Details: `docs/codex.md`.
+
+## Claude
+- OAuth API (preferred when CLI credentials exist).
+- Web API (browser cookies) fallback when OAuth missing.
+- CLI PTY fallback when OAuth + web are unavailable.
+- Local cost usage: scans `~/.config/claude/projects/**/*.jsonl` (last 30 days).
+- Status: Statuspage.io (Anthropic).
+- Details: `docs/claude.md`.
+
+## z.ai
+- API token from Keychain or `Z_AI_API_KEY` env var.
+- `GET https://api.z.ai/api/monitor/usage/quota/limit`.
+- Status: none yet.
+- Details: `docs/zai.md`.
+
+## Gemini
+- OAuth-backed quota API (`retrieveUserQuota`) using Gemini CLI credentials.
+- Token refresh via Google OAuth if expired.
+- Tier detection via `loadCodeAssist`.
+- Status: Google Workspace incidents (Gemini product).
+- Details: `docs/gemini.md`.
+
+## Antigravity
+- Local Antigravity language server (internal protocol, HTTPS on localhost).
+- `GetUserStatus` primary; `GetCommandModelConfigs` fallback.
+- Status: Google Workspace incidents (Gemini product).
+- Details: `docs/antigravity.md`.
+
+## Cursor
+- Web API via browser cookies (`cursor.com` + `cursor.sh`).
+- Fallback: stored WebKit session.
+- Status: Statuspage.io (Cursor).
+- Details: `docs/cursor.md`.
+
+## Droid (Factory)
+- Web API via Factory cookies, bearer tokens, and WorkOS refresh tokens.
+- Multiple fallback strategies (cookies → stored tokens → local storage → WorkOS cookies).
+- Status: `https://status.factory.ai`.
+- Details: `docs/factory.md`.
+
+## MiniMax
+- Web-only. Uses browser cookies plus a Chromium local storage access token.
+- Primary endpoint: `https://platform.minimax.io/user-center/payment/coding-plan` (HTML parse).
+- Fallback endpoint: `https://platform.minimax.io/v1/api/openplatform/coding_plan/remains`.
+- Status: none yet.
+- Details: `docs/minimax.md`.
+
+## Copilot
+- GitHub device flow OAuth token + `api.github.com/copilot_internal/user`.
+- Status: Statuspage.io (GitHub).
+- Details: `docs/copilot.md`.
+
+See also: `docs/provider.md` for architecture notes.