[KrasimirKralev]

What Problem This Solves

The CLI docs say stored client config always lives at ~/.config/clickclack/config.json, but the client stores it under the OS user config directory, so on macOS, on Windows and on Linux with XDG_CONFIG_HOME set, users look in the wrong place for the saved session.

• Problem: docs/cli.md:53 and docs/agent-friendly-cli.md:152 name ~/.config/clickclack/config.json; clientConfigPath() (apps/api/cmd/clickclack/client.go:476) uses os.UserConfigDir(), which is $XDG_CONFIG_HOME (default ~/.config) on Linux, ~/Library/Application Support on macOS and %AppData% on Windows.
• What did NOT change: no code, flag or config behaviour; only the two sentences that name the path, plus one CHANGELOG line.
• Requested by a maintainer? No, found by comparing the docs with clientConfigPath().

User Impact

Users who want to inspect, delete or back up the stored session token (for example after clickclack logout or when switching servers) are told the real location on every OS.

Why This Change Was Made

• What changed: both docs now name clickclack/config.json in the OS user config directory and list the Linux, macOS and Windows locations; one ## Unreleased CHANGELOG line.
• Root cause: the docs described the Linux default only, while the code follows os.UserConfigDir().

Evidence

• Behavior or issue addressed: where clickclack login stores the client config, and where later commands read it.
• Real environment tested: Linux, binary built from this branch (go build ./cmd/clickclack, docs-only change on top of fb9b931), a scratch clickclack serve --dev-bootstrap on 127.0.0.1:18431, and a magic link minted with clickclack admin magic-link create. HOME and XDG_CONFIG_HOME point at separate scratch dirs.
• Exact steps or command run after this patch: clickclack login --server http://127.0.0.1:18431 --magic-token mgt_…, then ls ~/.config/clickclack/config.json, find for config.json, clickclack whoami with the same and with another XDG_CONFIG_HOME.
• Evidence after fix:

$ export HOME=<scratch>/home XDG_CONFIG_HOME=<scratch>/xdg
$ clickclack login --server http://127.0.0.1:18431 --magic-token mgt_…
logged in as Proof
exit 0
$ ls ~/.config/clickclack/config.json
ls: cannot access '<scratch>/home/.config/clickclack/config.json': No such file or directory
$ find <scratch> -name config.json
<scratch>/xdg/clickclack/config.json
$ clickclack whoami   # reads the stored session from $XDG_CONFIG_HOME
usr_01m65spzagddjr7nqkxa8rtr07	Proof
exit 0
$ XDG_CONFIG_HOME=<scratch>/other clickclack whoami
2026/10/30 08:59:45 Get "http://localhost:8080/api/me": dial tcp 127.0.0.1:8080: connect: connection refused

• Observed result after fix: running the clickclack binary, login wrote $XDG_CONFIG_HOME/clickclack/config.json and nothing under ~/.config; whoami used the stored session only while XDG_CONFIG_HOME pointed at that directory, and fell back to the default http://localhost:8080 with another one. That is the os.UserConfigDir() behaviour the corrected docs describe.
• What was not tested: macOS and Windows paths were not run here; they come from Go's documented os.UserConfigDir() behaviour.
• Proof limitations or environment constraints: node scripts/build-docs-site.mjs builds the docs site with the change (exit 0).

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge.

What this changes

Updates both CLI guides and the changelog to describe the OS-specific location of stored client configuration.

Example: A Linux user sets XDG_CONFIG_HOME=/home/alex/settings and runs clickclack login.

• Before: The guides direct the user to /home/alex/.config/clickclack/config.json.
• After: The guides correctly identify /home/alex/settings/clickclack/config.json.

Review scores

Measure	Result	What it means
Overall readiness	🦞 diamond lobster (5/6)	A minimal, source-verified documentation correction supported by relevant shipped-CLI evidence, with no actionable findings.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (terminal): The supplied Linux terminal trace exercises the shipped login and whoami commands, showing configuration written and read under XDG_CONFIG_HOME; source verification supports the documented macOS and Windows paths.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Users on macOS, Windows, or Linux with XDG_CONFIG_HOME set are directed to the wrong saved-config location.
Reason: The wording corrects a factual mismatch without changing an owner-designed default, public API, or configuration behavior.

Merge readiness

✅ Ready for maintainer review

This PR corrects a verified documentation error still present on main; the focused patch is correct and worth merging.

Priority: P3
Reviewed head: 8b19237af9df15913d95a5402ba9832260d3cb5e

Before merge

None.

Findings

None.

Agent review details

How this fits together

CLI login saves credentials and client defaults through a shared config-path helper; later client commands read that same file.

flowchart LR
  A[OS environment] --> B[os.UserConfigDir]
  B --> C[clientConfigPath]
  D[CLI login] --> E[Save client config]
  C --> E
  E --> F[Config JSON file]
  F --> G[Load client config]
  C --> G
  G --> H[CLI commands]

Loading

Technical review

Best possible solution:

Merge the focused documentation correction so both guides describe the existing shared config-path behavior.

Do we have a high-confidence way to reproduce the issue?

The main-branch guides contradict the shared config-path implementation; the supplied Linux CLI trace independently demonstrates the XDG_CONFIG_HOME case.

Is this the best way to solve the issue?

Correcting the two descriptions is the smallest complete fix and accurately follows Go's platform behavior.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against fb9b9314bdfe.

Provenance checked

• Stored client configuration location in both CLI guides changes intended behavior with a stated reason (b925723: The original documentation described the implemented CLI but used only the Linux default path; the original client helper already delegated to os.UserConfigDir.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

• Exact introduced change: The pinned diff changes only two config-location descriptions and one Unreleased changelog entry; no executable behavior changes. (docs/cli.md:53, 8b19237af9df)
• Shared production path: clientConfigPath joins os.UserConfigDir with clickclack/config.json; both loadClientConfig and saveClientConfig use it, and login calls saveClientConfig. (apps/api/cmd/clickclack/client.go:476, fb9b9314bdfe)
• Main still needs the correction: The default-branch CLI guide still gives only ~/.config/clickclack/config.json. (docs/cli.md:53, fb9b9314bdfe)
• Original intent and ownership: The original CLI documentation commit introduced the Linux-only wording, while the earlier client implementation already used os.UserConfigDir. Local historical blob traversal was incomplete; GitHub source reads verified the original helper. (docs/cli.md:53, b925723fa643)
• Authoritative platform contract: The patch documents behavior delegated directly to Go's os.UserConfigDir: AppData on Windows, HOME/Library/Application Support on macOS, and XDG_CONFIG_HOME with HOME/.config fallback on Linux. (src/os/file.go, 6e676ab2b809)
• Contributor runtime evidence: The full PR body supplies a real CLI login/whoami trace showing config written under a separate XDG_CONFIG_HOME and subsequently read from that directory; macOS and Windows execution are explicitly excluded. (8b19237af9df)

Labels

Label changes:

• add P3: A small documentation correction helps users locate saved configuration without changing runtime behavior.
• add proof: sufficient: Contributor real behavior proof is sufficient.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

• P3: A small documentation correction helps users locate saved configuration without changing runtime behavior.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.
• proof: sufficient: Contributor real behavior proof is sufficient.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 30, 2026, 3:14 AM ET / 07:14 UTC.