Repository navigation
Personal squad docs reference ~/.squad/ instead of platform-specific paths #343
Description
Problem
The SDK correctly resolves the personal squad path using platform-specific directories via resolveGlobalSquadPath():
| Platform | Actual Path |
|---|---|
| Linux | $XDG_CONFIG_HOME/squad/.squad/ (default ~/.config/squad/.squad/) |
| macOS | ~/Library/Application Support/squad/.squad/ |
| Windows | %APPDATA%\squad\.squad\ |
However, documentation and code comments throughout the codebase refer to ~/.squad/ as the personal squad path, which is incorrect on all platforms.
Affected Files
Documentation (21+ references)
docs/src/content/docs/guide/personal-squad.md— Lines 21, 54, 68, 88, 103, 108, 123, 132, 139, 254, 262, 267, 295, 306, 309 all reference~/.squad/- Example (line 21): "Your team identity — agents, charters, skills, casting history — moves to a global directory (
~/.squad/)"
- Example (line 21): "Your team identity — agents, charters, skills, casting history — moves to a global directory (
Code Comments
packages/squad-sdk/src/sharing/consult.ts— Lines 898, 1009, 1010, 1038, 1056 have comments saying "Routes to~/.squad/"
Correct Implementation (no code change needed)
The actual path resolution is correct:
// packages/squad-sdk/src/resolution.ts:232-255
export function resolveGlobalSquadPath(): string {
// Returns platform-specific path (Linux: ~/.config/squad/)
}
// packages/squad-sdk/src/sharing/consult.ts:315-316
export function getPersonalSquadRoot(): string {
return path.resolve(resolveGlobalSquadPath(), '.squad');
}Fix
Update all ~/.squad/ references in docs and comments to either:
- Use a platform-agnostic description (e.g., "your personal squad directory")
- Show all three platform paths in a table
- Reference the function name (
resolveGlobalSquadPath()) in code comments
Files
- Docs:
docs/src/content/docs/guide/personal-squad.md - Code comments:
packages/squad-sdk/src/sharing/consult.ts - Correct implementation:
packages/squad-sdk/src/resolution.ts
Reacted by Alex C. Huber
Activity
fix(docs): replace ~/.squad/ with platform-specific path references
fix(docs): replace ~/.squad/ with platform-specific path references
feat: dual-mode OTel telemetry for CLI and Copilot agent (github#352)
github-actions commentedon Mar 13, 2026
🏗️ Squad Triage — Flight (Lead)
Issue: #343 — Personal squad docs reference ~/.squad/ instead of platform-specific paths
Assigned to: FIDO (Quality Owner)
Reason: Issue relates to testing/quality work
@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.
Team roster:
squad:flightsquad:proceduressquad:eecomsquad:fidosquad:paosquad:capcomsquad:controlsquad:surgeonsquad:boostersquad:gncsquad:networksquad:retrosquad:incosquad:guidosquad:telemetrysquad:voxsquad:dskysquad:simssquad:handbooksquad:ralphsquad:copilotgithub-actions commentedon Mar 13, 2026
squad:mcmanus. Check.squad/team.md(or.ai-team/team.md) for valid member names.bradygaster commentedon Mar 13, 2026
📌 Brady requested this issue be assigned to @diberry (docs/UX triage). Pending collaborator invite to complete assignment.
fix(docs): replace ~/.squad/ with platform-specific path references
fix(docs): replace ~/.squad/ with platform-specific path references
fix(docs): replace ~/.squad/ with platform-specific path references
docs: agent anatomy and hiring checklist (#439)