@sriinnu/runic 2.0.0 → 2.11.1

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

@@ -1,375 +0,0 @@
-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

@@ -1,202 +0,0 @@
----
-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

@@ -1,86 +0,0 @@
----
-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.