docs: add a short troubleshooting section for auth token resolution

[tanmayjoddar]

Why

A common failure mode is ${STAGING_TOKEN} resolving to empty, leading to 401s. We already warn in code, but docs could be clearer.

Where

• README.md

Acceptance Criteria

• Add a “Troubleshooting” section with:
  • verifying env vars are set
  • .env location expectations
  • what the auth warning means
  • example PowerShell + bash exports
• Keep it concise

[YashKrTripathi]

Hi! @tanmayjoddar I'm a GSSoC'26 contributor and I'd like to work on this issue.

My approach:

• Add a new ## Troubleshooting section to README.md following the existing documentation style.
• Cover verification of environment variables, expected .env file location, explanation of the auth warning when ${STAGING_TOKEN} resolves to empty, and concrete examples for both Bash (export STAGING_TOKEN=...) and PowerShell ($env:STAGING_TOKEN="...").
• Use clear Markdown formatting with code blocks and bullet points to keep the section concise and actionable as per acceptance criteria.
• Ensure the new section integrates naturally with existing content and improves developer onboarding without increasing overall document length significantly.

ETA: 1 day

Please assign this to me!

[Tharsiga-21]

Hi! @tanmayjoddar I'm a GSSoC'26 contributor . I would love to work on this issue!
I plan to add a concise Troubleshooting section in README.md that covers:

How to verify env vars are set correctly
.env file location expectations
What the auth warning means when ${STAGING_TOKEN} resolves to empty causing 401s
Example exports for both PowerShell and bash

The section will be clear, beginner-friendly, and consistent with the existing README style.
I have reviewed the issue carefully and I'm confident I can deliver this. Please assign this to me! /claim

[amankumar092]

🔍 Problem

New users setting up apidrift-cli frequently hit 401 errors because ${STAGING_TOKEN} resolves to an empty string when environment variables aren't set correctly. The current warning in the code is not prominently documented, leaving users confused about why auth is failing.

✅ Solution

Add a dedicated ## Troubleshooting section in README.md covering the most common auth failure — empty/missing env vars — with clear step-by-step diagnosis instructions.

✨ Features I Will Implement

• Add a ## Troubleshooting section to README.md
• Include steps to verify env vars are set (echo $STAGING_TOKEN)
• Explain .env file location expectations and how to load them
• Clarify what the 401/auth warning message means and how to fix it
• Provide example exports for both PowerShell and bash

🚀 Ways to Further Improve

• Add an inline apidrift doctor command that validates required env vars are present before running
• Add more troubleshooting entries for other common errors (SSL, network timeouts, etc.)
• Create a TROUBLESHOOTING.md file linked from the README for a longer reference

/claim

I'd love to contribute to GSSoC 2026 through this project. Please assign this issue to me! 🙏

[arunkumar-201]

Hello @tanmayjoddar,

I would like to contribute to this issue as part of GSSoC'26.

I have reviewed the requirements and understand the expected documentation updates. If the issue is available, could you please assign it to me?

Thank you for your time and consideration.