[docs][desktop][agent] User-facing docs for AI provider configuration (included / BYOK / local / subscription)

[softmarshmallow]

Problem

We ship a full AI provider configuration surface in Grida Desktop — a signed-in user can run the agent on Grida-included AI, paste their own key, point at a local model, or drive their own Claude/Codex subscription — but the only user-facing documentation we have is docs/editor/desktop/local-models.md ("Local Models (Ollama)").

That page frames the whole story around one path (local / Ollama). Every other path — the default included AI, bring-your-own-key, and your-own-subscription — is documented only through in-app card copy and picker labels. New users have no page to land on that answers "how does Grida decide which AI to use, and how do I change it?"

This issue is to open the gap for later pickup: propose a docs home and the set of pages, framed as "AI provider configuration" (the umbrella), with local models as one facet rather than the entry point.

Scope note: this is a docs issue only. The features already exist and ship — nothing here asks to build or change provider behavior.

What actually exists today (grounding)

The agent resolves one of four provider kinds (packages/grida-ai-agent/src/providers/, id contract in src/protocol/provider-ids.ts). Resolver precedence: BYOK keys → included (gg) → configured endpoints.

Kind	User-facing name	What the user does	Documented?
gg	Grida — included	Nothing — signed in, spends org credit (Grida Gateway, GRIDA-SEC-006)	❌ in-app copy only
byok	AI Provider Keys	Paste a key: OpenRouter, Vercel (AI Gateway), fal — unlocks text / image / video	❌ in-app copy only
endpoint	Local Models	Ollama preset or any OpenAI-compatible base URL (LiteLLM, vLLM), optional key	✅ local-models.md
agent-provider	Claude Code / subscription	Drive an external agent on your own subscription (detected, no key) — #813, #961	❌ undocumented

All of it is surfaced through one screen — editor/app/desktop/settings/page.tsx (Account · Credits · AI Provider Keys · Local Models · Image/Video models · About) — plus the per-composer model picker and the "Choose your AI" onboarding step. The onboarding link "Use your own key or a local model" points into Settings with no companion doc page.

Approach

Organize the docs around a "how do I connect a model" taxonomy: a single hub page that presents the choice (included vs your key vs local vs your subscription) and routes to one leaf page per path. The critical move — the entry point is the hub ("choose a path"), not any single provider. Local models becomes a leaf, not the front door.

The four provider kinds collapse cleanly into user paths, because our BYOK slots (OpenRouter, Vercel) are already gateway-shaped — there are no per-vendor direct-key providers to document separately. Provider auth is deliberately "host territory," out of scope for docs/wg/ai, so these belong in product docs, not WG.

Prior art worth studying for the hub-plus-leaf shape: Zed's AI docs (BYOK + hosted-gateway + local, organized under a "Model Access" chooser).

Proposed docs route

Home: a new docs/editor/desktop/ai/ folder — a dedicated AI section. The Editor sidebar is autogenerated, so this needs only a _category_.json — no sidebars.js edit. Base URL: https://grida.co/docs/editor/desktop/ai/....

The existing local-models.md moves into this folder and gets a redirect from its current URL (docs/editor/desktop/local-models → .../ai/local-models).

Alternative if the agent goes cross-surface (web daemon): promote to a top-level docs/editor/ai/ instead of nesting under desktop/. Recommend staying under desktop/ for now — the agent is Desktop-only for users today, and it sits beside the existing page.

Docs needed

#	Page	Path	Covers
1	AI providers (hub)	ai/index.md	The chooser + one comparison table: included vs your key vs local vs your subscription; the precedence rule; links out to each leaf. The new front door.
2	Included AI (Grida Gateway)	ai/included.md	The zero-config default: signed in, no key, org credit; what "Grida — included" means; cross-link Models & Pricing and the Credits card. User-facing counterpart to hosted-ai.md.
3	Bring your own key	ai/provider-keys.md	OpenRouter · Vercel · fal; what each unlocks (text / image / video); keys stored server-side, precedence over included; where to get each key.
4	Local models	ai/local-models.md (moved)	Existing content, re-slotted under the hub; keep Ollama as the flagship but frame as one path among four. Clears its doc_tasks: [update] flag.
5	Your own subscription	ai/subscription.md	The agent-provider path — Claude Code / Codex on your existing plan, auto-detected, no key (#813, #961). Ship when that provider lands.
6	(optional) Privacy & where prompts go	ai/privacy.md	Per-path data boundary: local never leaves the machine; included goes to Grida; BYOK goes to your provider.

Don't duplicate docs/models (Models & Pricing) — cross-link it as the "which models exist / what they cost" reference; the ai/ family is "how to connect."

Suggested order

1. Hub (#1) + move Local Models (#4) with redirect — immediately fixes the "local is the front door" framing.
2. Included AI (#2) + BYOK (#3) — the two undocumented paths most users hit.
3. Subscription (#5) once #813/#961 ship; Privacy (#6) as polish.

Related

• #806 — local LLM support (shipped; the one documented path)
• #813, #961 — subscription / ACP provider (drives page #5)
• #908, #910 — BYOK image/video (feeds page #3)
• #942 — default to included (gg) model (context for page #2)
• Spec (internal): docs/wg/platform/hosted-ai.md — the GG design doc these user pages sit on top of.