update docs to reflect XDG_CONFIG_HOME location of config file by jdoconnor · Pull Request #1663 · asheshgoplani/agent-deck

jdoconnor · 2026-07-18T17:54:21Z

What problem does this solve?

#1660 originally stated that the config file wasn't being written. This was user error stemming from a mismatch between code and documentation. This aligns the documentation with the code (which was determined to be correct based on the discussion in that issue)

Why this change

keep documentation clear and up to date.

User impact

none expected.

Evidence

AI disclosure

AI-authored (a model wrote most of it and i reviewed it)

Model(s), if AI helped:
DeepSeek V4 Pro

Prompt / session log (optional):

based on #1660 (comment), find references in the documentation to ~/.agent-deck/config.toml and fix them

What actually bothered you

I discovered this project today and thought there was a bug and was looking forward to helping fix it. Turns out, the documentation was lagging.

Checklist

Targeted diff: one problem, no unrelated changes
Tests added or updated for new behavior
Test suite passes sandboxed: HOME=$(mktemp -d) XDG_CONFIG_HOME= XDG_DATA_HOME= XDG_CACHE_HOME= go test ./...
If this touches a hot path (list, status, session output, startup, tmux layer): before/after timing evidence included
CHANGELOG.md untouched (entries are added at landing)
AI-assisted? Disclosed above, with validation evidence, and I can answer questions about the code
"Allow edits from maintainers" is enabled

Summary by CodeRabbit

Documentation
- Updated configuration guidance to use the XDG path: ~/.config/agent-deck/config.toml.
- Corrected MCP setup, hidden tools, worktree, troubleshooting, and configuration reference instructions.
- Added clarification about legacy configuration paths and improved sanitized configuration examples.
Bug Fixes
- Corrected configuration paths shown in the Settings panel and MCP Manager empty state.

github-actions · 2026-07-18T17:54:30Z

👋 Thanks for the contribution — intake looks complete.

Your PR body carries everything the maintainer's validation pipeline reads first: the problem, the reasoning, the human intent behind it, and an AI-disclosure. It will be applied, built, and tested against main, and you'll get a structured result within about a day. Merges are always human.

_{gate marker read: ai=<human|assisted|authored> model=<name-or-unsure> intent=<yes|no>}

coderabbitai · 2026-07-18T17:54:58Z

📝 Walkthrough

Walkthrough

Configuration references across the web UI, website, and bundled documentation now use $XDG_CONFIG_HOME/agent-deck/config.toml, defaulting to ~/.config/agent-deck/config.toml, with legacy-path notes retained in sanitized-config guidance.

Changes

Configuration path alignment

Layer / File(s)	Summary
Update configuration references `internal/web/static/app/SettingsPanel.js`, `internal/web/static/app/panes/McpPane.js`, `site/index.html`, `llms-full.txt`	Interactive hints, MCP instructions, configuration documentation, troubleshooting commands, and sanitized-config examples reference the XDG-based configuration path.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: asheshgoplani

🚥 Pre-merge checks | ✅ 6 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title describes the change, but it does not use Conventional Commits format as required.	Rewrite the title to use a Conventional Commits prefix, such as `docs: update config file paths to XDG_CONFIG_HOME`.

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Remote_parity	✅ Passed	The PR only updates web/static docs; it does not change internal/ui/ or cmd/agent-deck/, so RemoteSession parity is not applicable.
Test_coverage_per_surface	✅ Passed	Diff only updates documentation/static UI copy for config-path text; no behavior or new feature surface was added, so per-surface tests are not applicable.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/web/static/app/SettingsPanel.js`:
- Line 34: Align all listed references with EffectiveConfigPath: in
internal/web/static/app/SettingsPanel.js:34 display the configurable XDG path
with the ~/.agent-deck fallback or the backend-resolved path; in
internal/web/static/app/panes/McpPane.js:224 and site/index.html:563 use the
same configurable path; and in llms-full.txt:608 and llms-full.txt:1388 resolve
custom XDG and legacy paths, including the fallback, before sanitizing or
presenting the path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 858de468-2c90-4bed-b32e-6ea049a975f3

📥 Commits

Reviewing files that changed from the base of the PR and between fb461e0 and 0bf0817.

⛔ Files ignored due to path filters (10)

conductor/conductor-claude.md is excluded by !**/*.md
docs/PER-GROUP-CLAUDE-CONFIG-SPEC.md is excluded by !**/*.md
docs/SESSION-PERSISTENCE-SPEC.md is excluded by !**/*.md
docs/rfc/PLUGIN_ATTACH.md is excluded by !**/*.md
skills/agent-deck/SKILL.md is excluded by !**/*.md
skills/agent-deck/references/cli-reference.md is excluded by !**/*.md
skills/agent-deck/references/config-reference.md is excluded by !**/*.md
skills/agent-deck/references/sandbox.md is excluded by !**/*.md
skills/agent-deck/references/troubleshooting.md is excluded by !**/*.md
skills/agent-deck/references/tui-reference.md is excluded by !**/*.md

📒 Files selected for processing (4)

internal/web/static/app/SettingsPanel.js
internal/web/static/app/panes/McpPane.js
llms-full.txt
site/index.html

coderabbitai · 2026-07-18T17:57:09Z

      <div class="kv" data-testid="settings-picker-tools"><span class="k">picker tools</span><span class="v">${(settings.pickerTools || []).join(', ') || 'loading…'}</span></div>
      <div style="font-family: var(--mono); font-size: 11px; color: var(--muted); margin-top: 8px;">
-        Edit <code>~/.agent-deck/config.toml</code> (<code>[ui] hidden_tools</code>) or use TUI Settings → Visible tools…
+        Edit <code>~/.config/agent-deck/config.toml</code> (<code>[ui] hidden_tools</code>) or use TUI Settings → Visible tools…


🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Align all references with the effective configuration path.

EffectiveConfigPath honors XDG_CONFIG_HOME and falls back to ~/.agent-deck, but these changed references either hardcode ~/.config or fail to implement the documented fallback.

internal/web/static/app/SettingsPanel.js#L34-L34: display $XDG_CONFIG_HOME/... with the default, or show the backend-resolved path.

internal/web/static/app/panes/McpPane.js#L224-L224: use the configurable XDG path.

site/index.html#L563-L563: document the configurable XDG path.

llms-full.txt#L608-L608: resolve custom XDG and legacy paths before sanitizing.

llms-full.txt#L1388-L1388: apply the same effective-path resolution.

📍 Affects 4 files

internal/web/static/app/SettingsPanel.js#L34-L34 (this comment)

internal/web/static/app/panes/McpPane.js#L224-L224

site/index.html#L563-L563

llms-full.txt#L608-L608

llms-full.txt#L1388-L1388

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@internal/web/static/app/SettingsPanel.js` at line 34, Align all listed references with EffectiveConfigPath: in internal/web/static/app/SettingsPanel.js:34 display the configurable XDG path with the ~/.agent-deck fallback or the backend-resolved path; in internal/web/static/app/panes/McpPane.js:224 and site/index.html:563 use the same configurable path; and in llms-full.txt:608 and llms-full.txt:1388 resolve custom XDG and legacy paths, including the fallback, before sanitizing or presenting the path.

…aseline (#1674) Root cause of #1674, two independent problems: 1. Stale baseline: PR #1663 intentionally changed the settings drawer hint text from "Edit ~/.agent-deck/config.toml" to "Edit ~/.config/agent-deck/config.toml" (XDG alignment), but the committed visual baseline was never regenerated, so the weekly run correctly flagged a 726-pixel diff. Baseline regenerated on the CI runner via workflow_dispatch update_baselines=true (run 29690306661) per the documented procedure; only this one PNG changed. 2. Report bug: the issue-filing script walked only top-level data.suites[].specs, but Playwright's JSON reporter nests specs in suites-inside-suites (file suite -> describe suite -> specs), so the issue body said "No detailed results available." despite a full report. Extracted the rendering into .github/scripts/render-visual-details.js with a recursive suite walk, covered by tests/ci/render-visual-details.test.sh. Also hardened the no-data path: a visual step failure with a missing, empty, or unparseable Playwright report is now reported as "NO DATA (skipped)", does not count toward the failure total, and files no issue on its own; a real diff still files. The format validator accepts the new status. Committed by Ashesh Goplani

…tings-drawer baseline (#1678, closes #1674) Root cause of #1674, two independent problems: 1. Stale baseline: PR #1663 intentionally changed the settings drawer hint text from "Edit ~/.agent-deck/config.toml" to "Edit ~/.config/agent-deck/config.toml" (XDG alignment), but the committed visual baseline was never regenerated, so the weekly run correctly flagged a 726-pixel diff. Baseline regenerated on the CI runner via workflow_dispatch update_baselines=true (run 29690306661) per the documented procedure; only this one PNG changed. 2. Report bug: the issue-filing script walked only top-level data.suites[].specs, but Playwright's JSON reporter nests specs in suites-inside-suites (file suite -> describe suite -> specs), so the issue body said "No detailed results available." despite a full report. Extracted the rendering into .github/scripts/render-visual-details.js with a recursive suite walk, covered by tests/ci/render-visual-details.test.sh. Also hardened the no-data path: a visual step failure with a missing, empty, or unparseable Playwright report is now reported as "NO DATA (skipped)", does not count toward the failure total, and files no issue on its own; a real diff still files. The format validator accepts the new status. Committed by Ashesh Goplani

update docs to reflect XDG_CONFIG_HOME location of config file

0bf0817

jdoconnor requested a review from asheshgoplani as a code owner July 18, 2026 17:54

github-actions Bot added intake:clean PR/issue passed the intake contract ai-authored Primarily authored by an AI agent labels Jul 18, 2026

jdoconnor mentioned this pull request Jul 18, 2026

[bug] ~/.agent-deck/config.toml not created #1660

Closed

coderabbitai Bot reviewed Jul 18, 2026

View reviewed changes

asheshgoplani merged commit e46eca9 into asheshgoplani:main Jul 18, 2026
3 checks passed

asheshgoplani mentioned this pull request Jul 19, 2026

fix(ci): weekly regression report details + refresh settings-drawer baseline (#1674) #1678

Merged

asheshgoplani mentioned this pull request Jul 19, 2026

Weekly regression check: 1 failure(s) detected [2026-07-19] #1674

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

update docs to reflect XDG_CONFIG_HOME location of config file#1663

update docs to reflect XDG_CONFIG_HOME location of config file#1663
asheshgoplani merged 1 commit into
asheshgoplani:mainfrom
jdoconnor:fix-docs

jdoconnor commented Jul 18, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

github-actions Bot commented Jul 18, 2026

Uh oh!

coderabbitai Bot commented Jul 18, 2026 •

edited

Loading

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot Jul 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jdoconnor commented Jul 18, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What problem does this solve?

Why this change

User impact

Evidence

AI disclosure

What actually bothered you

Checklist

Summary by CodeRabbit

Uh oh!

github-actions Bot commented Jul 18, 2026

Uh oh!

coderabbitai Bot commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jdoconnor commented Jul 18, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 18, 2026 •

edited

Loading