Custom endpoint documentation gaps for new open-source users

[Apocrathia]

Summary

The documentation for connecting custom OpenAI-compatible endpoints is technically thorough but hard to discover for new users. With the project going open-source, users will want to bring their own endpoints (Ollama, vLLM, LM Studio, proxies), but the current docs bury this path and have a path discrepancy that will trip people up.

Affected documentation

• docs/models.md — config path references throughout
• docs/providers.md — "Custom Providers" section and "Auth File" section
• docs/quickstart.md — "Authenticate" section and "Next steps"
• docs/index.md — "Customization" section navigation
• README.md — "Custom providers & models" subsection

What's wrong or missing

1. Config directory name is wrong for prime-agent.

All docs reference ~/.pi/agent/models.json, but prime-agent uses ~/.prime/agent/. For example, docs/models.md opens with:

Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via ~/.pi/agent/models.json.

The README.md mentions ~/.prime/agent/models.json once in passing, but models.md and providers.md consistently use the upstream ~/.pi/agent/ path. This will trip up every new user who follows the docs.

2. The quickstart doesn't mention custom endpoints at all.

docs/quickstart.md only covers /login (subscription) and API keys for built-in providers. There's no breadcrumb from the quickstart to models.md. The "Next steps" section links to providers, settings, keybindings, sessions, and packages — but not to models.md or custom-provider.md.

3. The index page buries custom models under "Customization."

docs/index.md lists "Custom Models" and "Custom Providers" under the Customization section, below Extensions, Skills, Prompt Templates, Themes, and Packages. A user who just wants to use their own model would look under "Providers" or "Start here," not "Customization."

4. No --provider / --model CLI examples for custom providers.

docs/models.md explains how to define a provider in models.json but doesn't show how to select it from the CLI (e.g., prime-agent --model my-provider/my-model or --provider my-provider). The /model command is mentioned, but the provider/model selector syntax isn't documented.

5. No troubleshooting or "common setups" section.

The compat flags are documented as a reference table, but there's no "if you see error X, set flag Y" guide. New users hitting developer role errors or reasoning_effort errors from vLLM/Ollama have to read the full compat table and figure out which flags apply.

6. The /login flow doesn't surface custom providers in the docs.

Custom providers from models.json with an apiKey field appear in the /login provider selector, but the docs don't mention this. Users might not realize they can store their custom endpoint's API key via /login instead of putting it in models.json or an env var.

Suggested fix

In priority order:

1. Fix the config path in models.md and providers.md: ~/.pi/agent/ → ~/.prime/agent/ (or document both, explaining the fork relationship).
2. Add a "Custom endpoints" section to quickstart.md — even just 5 lines: "Want to use your own OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, etc.)? See Custom Models. Minimal example: [3-line JSON snippet]."
3. Add a link from quickstart.md "Next steps" to models.md and custom-provider.md.
4. Add CLI selection examples to models.md: prime-agent --model my-provider/my-model and prime-agent --provider my-provider.
5. Add a "Common setups" section to models.md with ready-to-copy configs for the three most popular cases (Ollama, vLLM, generic OpenAI-compatible proxy) — including the compat flags each typically needs.
6. Consider promoting "Custom Models" higher in index.md — move it from "Customization" to "Start here" or right after "Providers," since using your own model is a first-run concern, not a customization.

Additional context

The underlying models.md and custom-provider.md reference documentation is excellent — the issue is discoverability and the path discrepancy, not content quality. The compat flag reference table is comprehensive; it just needs a "common setups" shortcut for the 80% case.

Related: PR #533 adds the issue template used to file this.

[yuzzothecreator]

Working on the remaining discoverability gaps from this issue: custom-endpoint section in quickstart, index promotion, CLI selection examples, and common Ollama/vLLM setups. Config path already uses ~/.prime/agent/ on main.

[kevinjosethomas]

Hi, thanks for taking the time to report this! Since open sourcing Prime Agent, we’ve received far more Issues than we can reliably triage and maintain. Rather than leave a large backlog that we cannot meaningfully work through, we’re closing the current Issue queue and moving to a discussion-first process.

We have established new contribution guidelines to help us continue iterating on Prime Agent and better manage contributions from the community. Going forward, GitHub Issues will be our maintainer work queue rather than the initial place for public reports and requests. Bug reports, feature requests, questions, and other feedback should begin in GitHub Discussions. Please read the full process documented in our contribution guidelines. Security vulnerabilities should continue to be reported privately according to our security policy.

While we’re closing this backlog, we’re still reviewing it at a high level to identify recurring bugs, useful ideas, and important problems that we should address ourselves. Thanks again for the time you put into this!

[mcpeezy]

Contribution interest (docs)

I maintain Prime Desktop (independent macOS client for Prime Agent) and hit this while writing stranger install docs.

Happy to take a docs-only pass if maintainers want external help on this issue.

Concrete fix plan (no code behavior change)

1. Path consistency

   • Replace leftover ~/.pi/agent/ references with ~/.prime/agent/ in:
     • docs/models.md
     • docs/providers.md
     • any remaining auth-file examples
   • Keep a one-line note that older Pi paths are not used by prime-agent.

2. Discoverability

   • Add a quickstart breadcrumb from docs/quickstart.md → custom models/providers
   • Move or dual-link "Custom Models / Custom Providers" higher on docs/index.md (Start here / Providers), not only under Customization

3. Operator examples

   • Show CLI selection for a custom provider/model (provider/model selector and/or flags as actually supported on current main)
   • Add 2–3 common setups: OpenAI-compatible proxy, Ollama, LM Studio
   • Short troubleshooting bullets for auth file vs models.json mistakes

4. Validation

   • Grep the docs tree for ~/.pi/ after the edit
   • No runtime/src changes
   • Changelog fragment only if required for docs-only PRs

I will not open an unsolicited PR (read CONTRIBUTING). If this is wanted, an invite on this issue or a short maintainer note is enough and I can turn it around quickly.

— Patrick (mcpeezy) / Epiphany Dynamics