docs: add a Troubleshooting how-to guide

[Abdul-Moiz31]

Summary

The docs currently have no troubleshooting / common-errors page. Every existing How-to Guide (Docker Compose, Kubernetes, Hybrid Gateway) walks a forward path — install, configure, expose — but nothing helps a user who hits an error along the way.

For a product whose setup spans CLI auth, OAuth, OIDC, hybrid gateways, secrets and elicitation flows, this is a real friction point.

Why this matters

A few concrete places in the existing docs where users will predictably get stuck without a page to land on:

• reshapr login callback port. login opens the browser at http://localhost:5556 (getting-started.md L83). If that port is in use, or the browser blocks the callback, the docs don't say what the failure looks like or how to recover.
• Linux + host.docker.internal. docker-compose.md L141-154 uses --add-host=host.docker.internal:host-gateway but never explains why — Linux users who omit the flag will see the proxy fail to reach the control plane and have no signpost to follow.
• Default local creds. docker-compose.md L78 gives admin / password as the local defaults — easy to miss when scanning, and there's no page that consolidates "first-run gotchas."
• Hybrid gateway registration. deploy-hybrid-gateway.md L34-49 details the registration → health-check → streaming lifecycle, but doesn't say what failure modes look like on the gateway side or in the control plane logs.
• OAuth setup. config create-oauth (cli-commands.md L519-535) has many moving parts (oauth2ClientID, JWKS URI, scopes). The docs don't describe how to validate the setup or what a misconfigured token rejection looks like.

Proposal

Add a new page at docs/how-to-guides/troubleshooting.md, wired into sidebars.js under How-to Guides.

The structure I have in mind (open to your shaping):

• CLI & authentication — login callback, expired tokens, wrong server URL
• Local Docker Compose — Linux host.docker.internal, port conflicts, default credentials, container restarts
• Hybrid gateways — registration failures, health-check timeouts, API token issues
• Security & secrets — OAuth misconfiguration, elicitation flows, backend secret resolution
• Each entry follows a tight pattern: Symptom → Likely cause → Fix → Where to look (log line / command)

Where I need your input

I'd rather not seed this page with my guesses — for it to be useful, it needs to reflect the failures you actually see from real users. Could you share:

1. The top 3–5 setup failures you see on try.reshapr.io or in support channels?
2. Any error messages or log lines that you wish users would search for and land on a doc?
3. Whether there's anything you'd explicitly not want documented (private endpoints, internal-only flows, etc.)?

Once I have that, I'm happy to open a PR with a structured first version that you can extend.

Out of scope for this issue

• Detailed runbooks for production incidents (different audience — operations rather than first-time users).
• Anything that needs server-side changes (e.g. adding a --debug flag to the CLI).

[Abdul-Moiz31]

Hi @yada as you mentioned in the last PR that i should check and open any issue if something needs to be done or fix in the docs

Please have look on this proposal

thankyou !! Looking forward

[yada]

Thanks, @Abdul-Moiz31, Those are very valuable questions and suggestions. As you said, it can definitely help, but it’s also not easy to determine how far we should go in the troubleshooting sections and details. I think we should focus on the most important and common issues while avoiding documenting too many generic problems that are not directly related to the project itself.

That being said, regarding your questions:

“The top 3–5 setup failures you see on try.reshapr.io or in support channels?”

We currently do not log or trace activities on try.reshapr.io. Maybe we should at least capture errors only; that’s actually a very good point, but for now we don’t have usable data that could help on this topic.

“Any error messages or log lines that you wish users would search for and land on a doc?”

Same situation here, unfortunately, no records yet 😕 For both points 1 and 2, we mostly rely on user feedback and requests, and this issue is certainly a good opportunity to gather more input from the community.

“Whether there's anything you'd explicitly not want documented (private endpoints, internal-only flows, etc.)?”

I don’t have any concrete examples in mind right now, but let’s see how things evolve.

For now, please consider starting small on this, add the help wanted label, and later on (no rush in my opinion), feel free to submit a PR with the most relevant points based on your experience 😉