Docs: FAQ and CLI guidance gaps — community feedback from @jmservera #398

Summary

Community feedback from Juan Manuel Servera Bondroit (@jmservera) — shared in Squad Teams channel. Content may need an update to sync with all the new things, plus an FAQ for common issues.

💬 Credit: This issue captures feedback from @jmservera. Thank you for taking the time to share detailed pain points — this is exactly the kind of feedback that makes the docs better.

Feedback items

1. gh issue edit --add-assignee "@copilot" doesn't work locally

The command gh issue edit 40 --add-assignee "@copilot" (or any other variant of copilot-swe-agent[bot]) does not work on my local environment, but adding the labels and letting the action assign copilot does, so, Ralph and assigning tasks to copilot works well on Copilot CLI, but I cannot use the squad CLI for issues or Ralph because it tries to run the command and doesn't work. (I've found some clues on the internet, but I still don't really understand why it doesn't work even using a PAT locally).

Current docs coverage: docs/src/content/docs/features/copilot-coding-agent.md covers COPILOT_ASSIGN_TOKEN setup and the auto-assign workflow, but doesn't explicitly address why gh issue edit --add-assignee fails locally or provide a troubleshooting path for this specific error.

Gap: Add a troubleshooting entry explaining:

• Why direct gh issue edit --add-assignee "@copilot" fails (bot accounts can't be assigned via CLI the same way)
• The recommended workaround (label-based assignment via the workflow)
• PAT scope requirements for the auto-assign workflow

2. When to use Squad CLI vs Copilot CLI (GHCP CLI)

I still don't know when to use the squad CLI and when to use Copilot CLI, and the documentation starts by using squad, but I learnt in the Twitch that using the GHCP CLI was easier. I don't know which one is the best practice, can I stick to GHCP CLI and let it figure out when to call triage/loop/hire/etc...? should I run loop in a window and steer the squad in another one by running commands? or is there any other best practice?

Current docs coverage: docs/src/content/docs/scenarios/client-compatibility.md has a feature matrix and decision tree. docs/src/content/docs/guide.md mentions CLI as "primary platform." Blog post 028 says GHCP CLI is the recommended interface.

Gap: Despite having content in multiple places, the guidance is hard to find and potentially contradictory (guide.md says Squad CLI is primary, blog says GHCP CLI is recommended). Need:

• A clear, prominent "Which CLI should I use?" section in the getting-started flow
• Best practice patterns: "Use GHCP CLI for day-to-day work, Squad CLI for setup and diagnostics"
• Common workflow patterns (e.g., "run squad watch in one terminal, use GHCP CLI in another")

3. Aspire dashboard is Squad CLI only

Aspire only works for squad CLI, not for GHCP CLI, which is understandable, but can be confusing at the beginning. So a "I don't see anything on the Aspire dashboard" question would be useful.

Current docs coverage: docs/src/content/docs/scenarios/aspire-dashboard.md is comprehensive but does NOT explicitly state it's Squad CLI only.

Gap:

• Add a callout at the top of the Aspire docs: "Aspire dashboard requires the Squad CLI (squad aspire). It is not available when using GitHub Copilot CLI directly."
• Add FAQ entry: "I don't see anything on the Aspire dashboard" with troubleshooting steps

4. squad doctor complains about absolute path for teamroot

Doctor always complains about absolute path for teamroot, but I don't know how to make it relative (relative to what? to the .squad folder or to the project root?)

Current docs coverage: docs/src/content/docs/reference/cli.md documents squad doctor checks. docs/src/content/docs/guide/personal-squad.md explains teamRoot and resolution.

Gap:

• Add a troubleshooting entry for the "absolute path" warning
• Clarify what "relative" means in this context (relative to project root)
• Show before/after example of fixing the config

Proposed actions

• Add FAQ/troubleshooting entries for items 1, 3, and 4
• Clarify "Which CLI should I use?" in the getting-started flow (item 2)
• Add platform availability callouts to Aspire and Ralph/Watch docs
• Reconcile contradictory guidance about Squad CLI vs GHCP CLI across guide.md and blog posts
• Consider a dedicated "Common questions" or "FAQ" page

Labels

squad, squad:pao, type:docs