[#534] Custom endpoint docs: selecting models, common setups, quickstart breadcrumb

[FekyBaz]

Hi, following up on #534 (custom endpoint documentation gaps). I checked each of the six suggested fixes against current main and implemented what's still missing. Per CONTRIBUTING.md I'm posting here first instead of opening a PR, and would like an implementation invite if the approach looks good.

What I found

• Point 1 (config path) is already fixed: models.md and providers.md consistently use ~/.prime/agent/ — no ~/.pi/agent/ references remain in packages/coding-agent/docs/. No change needed.
• Points 2–6 are still open, and I addressed them all in docs-only edits (4 files, +115/−2, no code, so no changelog fragment per the fragment rule).

Changes (branch FekyBaz/prime-agent@docs/custom-endpoints-534, not a PR)

• models.md: new Selecting Custom Models section with CLI examples verified against src/cli/args.ts + resolveCliModel (--provider ollama --model llama3.1:8b and --model ollama/llama3.1:8b), /model picker note, and a /login key-storage note verified against getLoginProviderOptions/isApiKeyLoginProvider in auth-flows.ts (models.json custom providers do appear in the /login selector). New Common Setups section with copy-paste vLLM, LM Studio, and generic-proxy configs plus an error→compat-flag troubleshooting table built only from mappings already documented in the file (developer role → supportsDeveloperRole: false, reasoning_effort → supportsReasoningEffort: false, Anthropic-proxy tool streaming → supportsEagerToolInputStreaming: false). ToC updated.
• quickstart.md: new Option 3: Custom Endpoint under Authenticate (5 lines + minimal Ollama JSON + link to models.md), and Next steps now links models.md and custom-provider.md.
• index.md: the Start Here Providers entry now cross-links Custom models and Custom providers (minimal discoverability fix; left the Customization section structure untouched).
• providers.md: the Via models.json bullet now notes that custom providers appear in /login for key storage.

Validation

• Every added statement was checked against source (args.ts, model-resolver.ts, auth-flows.ts) or existing documented tables — no new factual claims.
• All added links/anchors verified present (usage.md, custom-provider.md, #selecting-custom-models, #common-setups, #value-resolution, #openai-compatibility, #anthropic-messages-compatibility).
• No code touched, so vitest/tsgo/biome scope is unaffected (I ran those suites for my earlier Non-worker draft discard: unobserved closeSession rejection can exit the process; pendingAttaches window discards a draft mid-attach #1922/fix: handle empty env vars in config (prevent relative path bug) #1811 patches on this machine).

Happy to adjust scope or wording before opening a PR. Thanks!

[K0nigsberg]

Independent verification on current main

Verified against main at 3484f06a (2026-09-04). Same conclusion as @FekyBaz on points 1–6:

#534 item	Status on main
1. ~/.pi/agent/ path	Already fixed — no ~/.pi/agent/ left under packages/coding-agent/docs/
2. Quickstart custom-endpoint breadcrumb	Still missing
3. Index / nav buries Custom Models under Customization	Still true (index.md + docs.json)
4. CLI --provider / --model provider/id examples in models.md	Still missing (examples live in usage.md / providers.md for built-ins only)
5. Common setups + error→compat shortcut	Still missing as a dedicated section
6. /login surfaces models.json providers	Still undocumented; confirmed in source via getLoginProviderOptions → modelRegistry.getAll() providers in auth-flows.ts

Also checked prior cold PR #976 (same scope, auto-closed) — so Discussion-first is the right path.

Ready branch (docs-only, rebased on current main)

Branch: docs/534-custom-endpoint-discoverability (local; will push when invited).

Same core fix set as @FekyBaz's fork branch, plus three small deltas after re-reading the files in full:

1. Section order — Selecting Custom Models / Common Setups now sit after Minimal Example and before Full Example (matches the ToC; the earlier patch had body order inverted).
2. Common setups include typical compat — Ollama / vLLM / LM Studio / generic proxy snippets ship with supportsDeveloperRole + supportsReasoningEffort set to false, matching what Custom endpoint documentation gaps for new open-source users #534 asked for and what the Minimal Example already teaches.
3. Nav promotion — Custom Models + Custom Providers moved into Start Here in both index.md and docs.json (not only an inline cross-link on the Providers bullet).

Happy to stay second author / fold into @FekyBaz's branch if maintainers prefer a single PR author. Not opening a PR until invited (per CONTRIBUTING.md).

[FekyBaz]

Thanks for the independent verification, @Kornisburg — glad we converged on all six points, and good catch on the cold PR #976 history; Discussion-first it is.

On your three deltas, all accepted:

1. Section order — you're right, my ToC reads Minimal → Selecting → Common → Full but the body has Full before Selecting/Common. I'll reorder the body to match the ToC (Selecting + Common right after Minimal Example). Genuine bug in my draft, thanks for catching it.
2. Compat flags in the snippets — agree. The Minimal Example already teaches supportsDeveloperRole: false + supportsReasoningEffort: false for exactly this server class, so shipping the vLLM/LM-Studio/proxy snippets without them contradicts the file's own guidance. I'll add both flags.
3. Nav promotion — agree as a move (not a duplicate): Custom Models + Custom Providers into Start Here in both index.md and docs.json, removed from under Customization. Paths and anchors stay identical so no links break; it directly serves Custom endpoint documentation gaps for new open-source users #534's discoverability goal.

On process: one PR is better than two for the maintainers here since our core sets are identical. Proposal — I'll apply the three deltas above to my branch (FekyBaz/prime-agent@docs/custom-endpoints-534) with you as co-author (Co-authored-by), unless you'd rather I pull from your branch instead. If you push docs/534-custom-endpoint-discoverability somewhere fetchable I'll diff to make sure I take your versions verbatim rather than re-typing them. Let me know which direction you prefer, and I'll hold off on opening the PR until we're aligned.

[K0nigsberg]

@FekyBaz Yes, Happy to fold everything into your branch as the co-author.

[FekyBaz]

@Kornisburg @koenigs — thank you both for the independent verification, and yes, let's fold everything into docs/custom-endpoints-534 as a single branch with co-authors.

I accept all three deltas:

1. Section order (Selecting/Custom Setups after Minimal Example, matching the ToC) — good catch, let's fix the inversion.
2. Typical compat flags in Common Setups — matches the Custom endpoint documentation gaps for new open-source users #534 ask; supportsDeveloperRole / supportsReasoningEffort: false for Ollama / vLLM / LM Studio / generic proxy is consistent with what the Minimal Example already teaches.
3. Nav promotion into Start Here (index.md + docs.json) — slightly broader than my minimal cross-link, but it's docs-only and directly serves the discoverability goal, so I'm fine with it.

Next step: please push your branch to your fork and open a PR targeting FekyBaz/prime-agent@docs/custom-endpoints-534 (or paste a patch here if you prefer). I'll review and merge, keeping your authorship on the commits, then we go to the maintainers for the implementation invite as one proposal per CONTRIBUTING.md.

[K0nigsberg]

@FekyBaz — PR is open as you asked: FekyBaz/prime-agent#1 (K0nigsberg:docs/534-custom-endpoint-discoverability → docs/custom-endpoints-534), commit re-auth'd to my K0nigsberg account so authorship is preserved.

Thanks for the careful guidance here — pairing the independent verification, the three deltas, and folding everything into a single branch was a much cleaner path than two competing PRs. Appreciate you carrying this through to the maintainers.

[FekyBaz]

@koenigs @Kornisburg — folded and cleaned up:

New branch: docs/534-final (on this fork, 1 commit ahead of current upstream main, 0 behind): aca ae9c — docs(coding-agent): improve custom endpoint discoverability (#534), co-authored by @K0nigsberg.

What I did with your PR #1: it couldn't merge as-is — the head branch carried the full upstream history with it, which would have polluted docs/custom-endpoints-534 with unrelated code. So instead I:

• Verified line-by-line that K0nigsberg's version is a superset of my original patch (same sections repositioned per ToC, plus Ollama snippet, per-snippet compat flags, nav promotion; nothing of mine dropped except superseded phrasing).
• Rebased the merged content onto current upstream main (which moved 33 commits since Sept 4, including a providers.md intro rewrite — I kept the new intro and applied only the /login sentence, so nothing upstream got reverted).
• Verified all new anchors/ToC entries/links resolve.

I closed #1 as superseded (nothing lost — authorship preserved via Co-authored-by). The branch is ready whenever maintainers invite the PR per CONTRIBUTING.md. Thanks again for the careful verification work — the section-order catch especially.