Document provider access roadmap

[nodnarbnitram]

🔗 Linked Issue

Refs #1

✅ Type of Change

• ✨ New Project/Feature
• 🐞 Bug Fix
• 📚 Documentation Update
• 🔨 Refactor or Other

📝 Summary

• Clarifies provider access UX as the broader product model covering subscriptions, API tokens, credits, quotas, and cost/spend pressure.
• Adds reference adoption criteria, glossary, core state contracts, roadmap sequencing, testing expectations, secrets/privacy guidance, and boundary enforcement.
• Preserves oxmux as the headless semantic/control layer and oxidemux as the native visual/controller shell.

📐 OpenSpec Evidence

• OpenSpec change/spec: Existing specs in openspec/specs/oxmux-core/spec.md, openspec/specs/oxidemux-app-shell/spec.md, and openspec/specs/oxmux-management-lifecycle/spec.md remain the canonical behavioral requirements.
• No OpenSpec required: Documentation-only clarification of product vocabulary, roadmap sequencing, and existing boundary expectations.
• Vision/boundary impact: Strengthens the boundary by making oxmux own provider access semantics headlessly while oxidemux renders and controls those semantics without duplicating core decision logic.

📖 Documentation Checklist

• I updated README.md, CONTRIBUTING.md, or OpenSpec docs when needed.
• I updated CHANGELOG.md for notable user-facing, compatibility, security, or workflow changes, or explained why it was not applicable.
  • Not applicable: documentation intent/architecture clarification only; no released user-facing behavior changed.

✔️ Contributor Checklist

• My code follows the project's coding standards.
• I have added a .env.example file if environment variables are needed and ensured no secrets are committed.
• My pull request is focused on a single project or change.
• I preserved the oxmux shared-core and oxidemux platform-shell boundary, or documented the OpenSpec-approved reason for changing it.
• I ran mise run ci locally, or explained why it was not applicable.
  • Not applicable: docs-only change; LSP diagnostics were run for both modified markdown files.
• I ran mise run security locally for dependency policy and vulnerability changes, or explained why they were not applicable.
  • Not applicable: no dependency, policy, or vulnerability changes.
• I ran relevant hk checks with mise run hk-check, or explained why they were not applicable.
  • Not applicable: docs-only change; branch contains only markdown documentation updates.

💬 Additional Comments

PRD #1 was also updated in GitHub to use the same provider access terminology and to act as the source-of-truth roadmap index.

Release Notes:

• N/A

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

[greptile-apps]

Greptile Summary

This documentation-only PR broadens the product vocabulary from "subscription UX" to "provider access UX" across docs/architecture.md and docs/vision.md, reflecting that OxideMux must support subscription accounts, API-token accounts, credits, quotas, and pay-as-you-go providers. It also adds several new sections: Reference adoption criteria, Core state contract, Roadmap sequencing, Testing expectations, Secrets/privacy guidance, Enforcement rules, and a Glossary.

Confidence Score: 5/5

Safe to merge — documentation-only changes with no code or behavioral impact.

All findings are P2 style/readability nits. No code is changed and no behavioral contracts are altered.

No files require special attention.

Important Files Changed

Filename	Overview
docs/architecture.md	Expands architecture doc with Core state contract, Roadmap sequencing, Testing expectations, Secrets/privacy, and Enforcement sections; updates terminology from "subscription" to "provider access" throughout. Roadmap table starts at Phase 2 without explaining Phase 1.
docs/vision.md	Adds Reference adoption criteria and Glossary sections; updates "subscription UX" to "provider access UX" in most locations. One oxidemux sentence is formatted as a continuation of an oxmux bullet rather than its own list item.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[developer tool / local client] --> B[local OxideMux endpoint]
    B --> C[oxmux: protocol + request rewrite]
    C --> D[oxmux: model alias + reasoning normalization]
    D --> E[oxmux: provider access-aware routing policy]
    E --> F[provider/account execution seam]
    F --> G[compatible response stream or body]

    subgraph oxmux_core["oxmux — shared headless core"]
        C
        D
        E
        H[Core state contract: quota · cost/spend · auth · credential · routing decisions]
    end

    subgraph oxidemux_shell["oxidemux — platform shell"]
        I[GPUI views · tray · notifications · packaging]
        J[Platform credential adapters / browser/OAuth]
        K[Renders core state: quota pressure · cost/spend · account health · route]
    end

    E --> H
    H --> K
    I --> B
    J --> B

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
docs/vision.md:67-68
**`oxidemux` sentence rendered inside the `oxmux` bullet**

The `oxidemux` sentence at line 67 is indented with 2 spaces, making it a continuation paragraph of the preceding `oxmux` bullet in standard Markdown. It will render as part of the same bullet item rather than as a distinct point, which blurs the boundary between the two crates this whole doc is trying to clarify.

```suggestion
  caller or user can do next.
- `oxidemux` should make that experience visual, interactive, and
  platform-native.
```

### Issue 2 of 2
docs/architecture.md:109-114
**Roadmap table starts at Phase 2 with no Phase 1**

The newly added table lists Phases 2–5 with no mention of Phase 1. Readers encountering this table without access to the linked PRD (#1) will reasonably wonder whether Phase 1 exists, is complete, or was omitted. A brief inline note (e.g., "Phase 1 covers initial repo/toolchain bootstrap — see PRD #1") or an added row would make the table self-contained.

_{Reviews (2): Last reviewed commit: "Address provider access review comments" | Re-trigger Greptile}