Repo Docs Cleanup And CachyOS KDE Ricing Plan

Status: planned Reviewed: 2026-06-20 Scope: second-pass static repo review and implementation plan only

1. Current Repo State

The repo direction is clear in the current root policy files: this is a chezmoi-managed personal workstation repo for WSL, CachyOS KDE/Arch-family Linux, and native Windows PowerShell. Vibe Core is retired from this repo, ShellKit is parked, and the active agent-work surface is workstation configuration.

The starting branch check was clean:

git status --short --branch

## main...origin/main

pnpm-lock.yaml exists on the current branch, and .github/workflows/docs.yml uses pnpm install --frozen-lockfile. The first-pass lockfile finding is therefore not current for this branch.

Existing CachyOS desktop management is deliberately small. The repo currently renders CachyOS-only Ghostty and Konsole terminal profile pieces, fontconfig aliases, and mimeapps.list defaults. The smoke tests assert that WSL and Windows omit those desktop targets, and that KDE autostart remains unmanaged.

There is no tracked MacTahoe, WhiteSur, or Kvantum implementation in the repo today. The only references found are in .tmp/ review/planning material.

Current Desktop Baseline To Inventory

The failed earlier desktop ricing attempt is useful only as current-state inventory. Treat the MacTahoe/WhiteSur work as greenfield: do not carry forward the old Spectre/Breeze visual direction, old panel layout, dock indicator, clock, Breeze decoration tuning, graphite palette, wallpaper judgement, or visual acceptance criteria unless the user explicitly reselects a specific piece later.

Before any desktop apply phase, inventory and back up existing live state that may have come from that attempt:

• custom KDE color schemes, especially SpectreGraphiteDark if present;
• custom Plasma styles, especially spectre-macos-dock-polish if present;
• custom Ghostty theme overrides;
• generated launcher or grid icons;
• current Plasma panel/layout config files;
• locally installed SF Pro Text, SF Pro Display, and SF Mono fonts.

Existing custom assets should be replaced, archived, or left alone deliberately during implementation. Do not assume the live desktop is stock Breeze, and do not overwrite old custom state without backup.

Current validation note from this planning pass:

• pnpm docs:build passes.
• python3 scripts/whitespace-check.py passes.
• markdownlint-cli2 docs/plans/repo-docs-cleanup-and-cachyos-kde-ricing-plan.md --no-globs passes for this plan.
• Repo-wide just lint-markdown is blocked by pre-existing lint failures in .tmp/codex-second-pass-prompt.md and docs/adr/0007-bun-first-vibe-core.md.

2. Conflicts And Stale Docs

The main conflict is documentation drift. Root policy files say Vibe Core is out of scope and ShellKit is parked, while some docs still describe Vibe Core, just vibe, .vibe/, Bun-first Vibe work, and ShellKit as active directions.

Path	Class	Finding	Proposed action
README.md	Current	Correctly states Vibe Core retired and ShellKit parked.	Keep as root landing page.
AGENTS.md	Current	Correctly defines current repo policy, queue policy, and decision gates.	Keep authoritative for agents.
DECISIONS.md	Current	Correctly records retired Vibe workflow and parked ShellKit direction.	Keep as compact decision summary.
KNOWN_ISSUES.md	Current	Contains active host and validation caveats.	Keep in root until a troubleshooting page exists.
docs/index.md	Current	Correct docs entrypoint, but missing desktop/plan/archive navigation.	Update after new docs sections exist.
docs/reference/quality.md	Current	Correct but too flat for the number of checks.	Expand into a change-area validation matrix.
docs/tools/manifest.md	Current	Correct ownership narrative, but not enough detail for package/theme ownership.	Add or link a tool ownership matrix.
docs/workflows/terminal.md	Current	Correctly documents current minimal CachyOS KDE boundary.	Keep and link to future desktop docs.
docs/philosophy/non-goals.md	Current	Correctly forbids bulk Plasma export and accidental duplicate ownership.	Keep in active navigation.
docs/reference/todo-queue.md	Superseded	Says TODO.md is the active queue, while AGENTS.md says GitHub Issues are mandatory durable queue state and TODO.md is legacy/manual queue.	Rewrite as legacy queue migration guidance.
docs/decisions/index.md	Superseded	Lists just vibe, mandatory Vibe queue state, Bun-first Vibe Core, and ShellKit runtime work as current.	Rewrite current decision list and move old ADRs under historical/superseded grouping.
docs/design/index.md	Superseded	Links only to active-looking Personal Vibe Core design.	Replace with current/planned design targets, including CachyOS desktop ricing.
docs/design/vibe-core-target.md	Historical	Useful record of retired Vibe target, but dangerous in active design nav.	Move to docs/archive/vibe-core/ or keep with a strong superseded banner and remove from active nav.
docs/adr/0001-agentic-vibe-workflow.md	Superseded	Records just vibe, .vibe/, and old workflow state.	Mark superseded by DECISIONS.md retired Vibe workflow.
docs/adr/0002-shellkit-runtime-coordinator-first.md	Superseded	Records active ShellKit implementation direction.	Mark superseded/parked.
docs/adr/0003-managed-shell-contract.md	Planned/Historical	Some shell-contract ideas remain relevant, but ShellKit loader language is stale.	Add status header and update or archive stale ShellKit wording.
docs/adr/0004-two-binary-shellkit-architecture.md	Superseded	Records removed Rust ShellKit architecture.	Mark superseded/parked.
docs/adr/0005-profiles-lanes-bootstrap-scope.md	Current with stale notes	Host lanes remain current, but Vibe/ShellKit priority wording is stale.	Add reviewed status and amend stale sentence.
docs/adr/0006-personal-vibe-core.md	Superseded	Records Personal Vibe Core doctrine.	Mark superseded by retired Vibe workflow decision.
docs/adr/0007-bun-first-vibe-core.md	Superseded	Records Bun-first Vibe implementation direction.	Mark superseded by retired Vibe workflow decision.
docs/plans/rust_shell_runtime_helper_plan.md	Historical	Good parked ShellKit note.	Keep, but ensure nav labels it parked.
docs/plans/windows-powershell-lane-refactor.md	Historical/Archive candidate	Large plan with many already-implemented or deferred threads.	Add status banner, then archive or split current leftovers into new issues.
.tmp/ricing-plan.md	Planned source input	Correct CachyOS KDE design intent, but not tracked docs.	Convert into tracked desktop design/plan material.
TODO.md	Archive candidate/current legacy	Active tasks are mixed with long progress logs and host-blocked history.	Reduce to a short legacy pointer or active-only queue after GitHub issue migration.
TODO_COMPLETED.md	Archive candidate	Root-level completed history.	Move to docs/archive/todo-completed.md or replace with closed issue references.
GITHUBMCP_README.md	Current but misplaced	Useful GitHub MCP setup guidance, but root clutter.	Move to docs/reference/github-mcp.md or docs/workflows/codex.md.
SMOKE_TEST_PROMPT.md	Current but misplaced	Useful post-apply prompt.	Move to docs/reference/prompts/codex-smoke-test.md.

3. Target Docs Structure

The docs site should show one active story and keep history available without letting old plans drive new agent work.

Proposed navigation:

docs/
  index.md
  setup/
    index.md
    host-lanes.md
    cachyos.md
    wsl.md
    windows.md
  workflows/
    index.md
    shell.md
    terminal.md
    editors.md
    project-launcher.md
    codex.md
    git.md
    yazi.md
    maintenance.md
    cross-platform-wrappers.md
  desktop/
    index.md
    cachyos-kde.md
    cachyos-kde-ricing.md
    rollback.md
  tools/
    index.md
    manifest.md
    ownership.md
    mise.md
    windows-tools.md
  reference/
    index.md
    quality.md
    local-overrides.md
    codex-config-boundaries.md
    github-mcp.md
    rendered-path-inventory.md
    prompts/
      codex-smoke-test.md
  decisions/
    index.md
  plans/
    repo-docs-cleanup-and-cachyos-kde-ricing-plan.md
  archive/
    index.md
    vibe-core/
    shellkit/
    old-plans/
    todo-completed.md

Navigation cleanup steps:

1. Update docs/.vitepress/config.ts to add Desktop, Plans, and Archive sections only after their landing pages exist.

2. Remove the active Personal Vibe Core design link from docs/design/index.md; move that page into archive or mark it superseded.

3. Rework docs/decisions/index.md into two sections: current decisions and historical/superseded ADRs.

4. Add a standard status header to ADR, plan, and design pages:

   Status: current | planned | parked | superseded | archived
   Last reviewed: YYYY-MM-DD
   Superseded by: path-or-none

5. Keep README.md short and point readers to the docs site rather than copying workflow detail into root.

4. Root Cleanup

Root should expose setup, policy, quality, and package metadata. Everything else should live in docs or local ignored state.

Root file	Proposal
TODO.md	Convert to either a compact legacy/manual queue pointer or a current-only list with no progress logs. GitHub Issues stay the durable queue source. Do not erase migrated context until issues reference the legacy item.
TODO_COMPLETED.md	Move to docs/archive/todo-completed.md, or replace with a short pointer to closed GitHub Issues after migration. Keep append-only history available but out of root.
GITHUBMCP_README.md	Move to docs/reference/github-mcp.md; keep the secret-handling warnings and project-local MCP boundary.
SMOKE_TEST_PROMPT.md	Move to docs/reference/prompts/codex-smoke-test.md; link it from docs/reference/quality.md.
docs/plans/windows-powershell-lane-refactor.md	Add status header, then archive or split remaining active pieces into issues. It should not sit as an unqualified active plan.
docs/design/vibe-core-target.md	Move under docs/archive/vibe-core/ or mark superseded and remove from active design nav.
Old Vibe/ShellKit ADRs	Keep for history, but mark superseded/parked and stop listing them as current direction.

The cleanup should not delete meaningful queue history in the same pass that changes navigation. Move first, then prune or migrate to issues in small follow-up changes.

5. Validation Cleanup

just check should remain the public facade. The problem is internal size: scripts/smoke-test.sh is over 3,000 lines and scripts/smoke-test-windows.ps1 is over 2,000 lines. They are not merely smoke tests; they encode render fixtures, shell contracts, editor contracts, agent security boundaries, terminal behavior, desktop boundaries, package ownership, and project launcher behavior.

Split gradually. Do not rewrite both scripts at once.

Proposed Unix-side shape:

scripts/checks/
  source-render.sh
  shell-contract.sh
  editor-contract.py
  agent-contract.py
  terminal-contract.sh
  cachyos-desktop-contract.py
  project-launcher-contract.sh
  docs-contract.py
scripts/lib/
  dotfiles-common.sh

Proposed Windows-side shape:

scripts/windows/checks/
  SourceRender.ps1
  PowerShellContract.ps1
  EditorContract.ps1
  TerminalContract.ps1
  ToolInventoryContract.ps1
scripts/lib/
  Dotfiles.Common.psm1

Recommended extraction order:

1. Extract a read-only docs-contract check for stale active docs once status headers are introduced.
2. Extract CachyOS desktop render assertions before adding theme files, so the MacTahoe/WhiteSur/Kvantum boundary is testable.
3. Extract editor and terminal assertions after the docs cleanup, because those already have focused validators and clear file boundaries.
4. Leave project launcher and agent env parser tests in place until the smaller modules prove stable.

Each extraction PR must keep:

just check

as the command users and CI run.

6. Tool And Package Ownership Cleanup

Current ownership is spread across mise TOML, Windows windows/tools.json, bootstrap scripts, editor manifests, docs, cheatsheets, and smoke tests. That is workable, but the incoming desktop theme layer needs a clearer ownership record before it adds package-manager and upstream asset sources.

Add docs/tools/ownership.md with at least:

Column	Meaning
Tool or asset	Human-readable name.
Lane	wsl, cachyos, windows, or shared.
Owner	mise, apt, pacman, aur, scoop, winget, direct, editor, manual, or repo-script.
Install path	Where the repo expects it to land.
Upgrade path	Which command updates it.
Apply behavior	Whether install is enough or a separate apply command mutates user config.
Validation	Source and host checks.
Notes	Ownership exceptions and fallback policy.

Theme assets should be treated separately from tools:

Asset class	Preferred owner
Theme engine dependency	CachyOS/Arch package manager after current package-name verification.
MacTahoe and WhiteSur theme assets	User-local upstream install or AUR package after current source verification.
Plasma/KDE config writes	Explicit dotfiles-cachyos-theme apply-* command only.
Terminal/editor Catppuccin themes	Existing home/.chezmoidata/theme.toml; unchanged by KDE ricing.

Do not make the normal just upgrade path apply or re-apply desktop themes or panel layouts. Package refresh may install dependencies, but user-visible desktop mutation belongs behind an explicit CachyOS desktop command.

7. CachyOS KDE Ricing Design

Target:

• CachyOS KDE Plasma 6 on Wayland.
• MacTahoe primary.
• WhiteSur conservative fallback.
• Breeze emergency recovery.
• Kvantum for Qt app widgets.
• GTK, icon, cursor, and wallpaper assets included.
• No Latte Dock.
• No GRUB, boot splash, kernel, driver, display-manager, or initramfs changes.
• No SDDM/login theming in the first pass; reserve a later explicit optional SDDM phase with its own backup, recovery, and privilege model.
• No WSL or Windows ricing.
• Existing terminal/editor/dev Catppuccin theming remains untouched.

Data Keys

Extend the existing desktop data instead of creating an unrelated theme system. A likely source file is home/.chezmoidata/desktop.toml.

Proposed data shape:

[desktop_theme]
enabled = false
lane = "cachyos"
target = "mactahoe"
fallback = "whitesur"
emergency = "breeze"
appearance = "dark"
install_assets = false
apply_theme = false
apply_layout = false
apply_flatpak_overrides = false
apply_sddm = false
backup_dir = "~/.local/state/dotfiles/plasma-backups"

[desktop_theme.layout]
top_panel = false
bottom_dock_panel = false
left_window_buttons = true
global_menu = false

[desktop_theme.sddm]
enabled = false
theme = "mactahoe"
fallback = "breeze"
backup_dir = "~/.local/state/dotfiles/sddm-backups"

Defaults stay non-mutating. enabled = false, apply_theme = false, and apply_layout = false are important safety properties. SDDM data exists only to keep the future phase explicit; it must not make the first pass touch login screen configuration.

Command Surface

Use one explicit CachyOS command rendered only on CachyOS, or a shared command that hard-fails outside CachyOS before doing any work:

dotfiles-cachyos-theme status
dotfiles-cachyos-theme plan
dotfiles-cachyos-theme install-assets --theme mactahoe --with-fallback whitesur
dotfiles-cachyos-theme backup
dotfiles-cachyos-theme apply-theme --theme mactahoe --appearance dark
dotfiles-cachyos-theme apply-layout --macos-like-panels
dotfiles-cachyos-theme plan-sddm --theme mactahoe
dotfiles-cachyos-theme backup-sddm
dotfiles-cachyos-theme apply-sddm --theme mactahoe
dotfiles-cachyos-theme rollback-sddm --to breeze
dotfiles-cachyos-theme rollback --to whitesur
dotfiles-cachyos-theme rollback --to breeze
dotfiles-cachyos-theme restore-backup <timestamp>

Implementation layout:

home/dot_local/bin/executable_dotfiles-cachyos-theme
scripts/cachyos/theme/status.sh
scripts/cachyos/theme/install-assets.sh
scripts/cachyos/theme/backup.sh
scripts/cachyos/theme/apply-theme.sh
scripts/cachyos/theme/apply-layout.sh
scripts/cachyos/theme/backup-sddm.sh
scripts/cachyos/theme/apply-sddm.sh
scripts/cachyos/theme/rollback.sh

The implementation pass must verify current CachyOS/Arch package names and upstream install options at that time. The plan should not bake in stale AUR package assumptions.

Install Locations

Prefer user-local locations where upstream installers support them:

~/.local/share/plasma/look-and-feel/
~/.local/share/plasma/desktoptheme/
~/.local/share/aurorae/themes/
~/.local/share/color-schemes/
~/.local/share/wallpapers/
~/.config/Kvantum/
~/.themes/
~/.icons/
~/.local/share/icons/

Use system package managers only for engine/runtime dependencies where the OS is the better owner. Theme assets should not require root when user-local installation is practical.

Apply Phases

Phase	Work	Risk	Review boundary
0	Docs, data keys, status/plan command only.	Low	No desktop mutation.
1	Install or verify theme engine and theme assets.	Low/medium	No Plasma config writes except asset install.
2	Apply Kvantum, color scheme, icons, cursor, GTK settings.	Medium	Backup required first.
3	Apply Aurorae/window decoration and left-side window buttons.	Medium	Backup required first.
4	Add optional top panel and bottom dock-like Plasma panel.	Medium/high	Separate opt-in command.
5	Document or optionally apply Flatpak GTK theme overrides.	Medium	Prefer docs-only first.
6	Optional SDDM/login theme.	High	Later explicit command with root/elevation, backup, and recovery docs.

Underlying KDE command names should be discovered and verified during implementation on the target host. Prefer KDE-provided CLI/config tools where available, and use direct config writes only when the key ownership is stable and covered by backup/rollback.

Later Layout Foundation

The panel layout phase is expected work, not an afterthought. It stays out of the first implementation only because panel state has a larger blast radius than theme selection.

The later apply-layout design should include:

• A read-only plan output that describes the intended top panel, bottom dock-like panel, widgets, launchers, and task manager behavior before changing anything.
• Backup of plasma-org.kde.plasma.desktop-appletsrc, plasmashellrc, and any other touched Plasma shell files before mutation.
• A rollback path that restores the previous panel layout from backup.
• A Breeze-safe recovery note that explains how to open KRunner, System Settings, and a terminal if the panel layout is wrong.
• Plasma-native panels and task manager widgets only; no Latte Dock.
• No layout work from chezmoi apply, just upgrade, or the main apply-theme command.

Later SDDM Foundation

The SDDM/login phase is also expected later work, but it must be isolated from the normal desktop theming path. Login theming has a higher recovery cost and usually requires root-owned files or package-manager state.

The later apply-sddm design should include:

• A read-only plan-sddm output that reports the active SDDM config path, current theme, candidate MacTahoe/WhiteSur/Breeze/default themes, and every file it would write.
• A separate backup-sddm command before any write.
• Backups for /etc/sddm.conf, /etc/sddm.conf.d/*.conf, and any repo-touched SDDM theme config under the chosen install location.
• A clear privilege model: if root is required, fail with the exact command to rerun instead of silently trying broad workarounds.
• A rollback path to Breeze or the previously backed-up default theme.
• No display-manager service changes, no autologin changes, no GPU/session changes, no boot splash work, and no GRUB work.
• Manual validation after logout/login, with a documented TTY recovery path before the command is considered done.

8. Rollback And Safety Model

Before any command writes Plasma, KWin, Kvantum, GTK, or panel layout config, create a timestamped backup under:

~/.local/state/dotfiles/plasma-backups/YYYYMMDD-HHMMSS/

Candidate backup files:

~/.config/kdeglobals
~/.config/kwinrc
~/.config/plasmarc
~/.config/plasmashellrc
~/.config/plasma-org.kde.plasma.desktop-appletsrc
~/.config/kcminputrc
~/.config/Kvantum/kvantum.kvconfig
~/.config/gtk-3.0/settings.ini
~/.config/gtk-4.0/settings.ini
~/.config/mimeapps.list

Safety rules:

1. status and plan are read-only.
2. install-assets may install files or packages, but must not apply the desktop theme or panel layout.
3. apply-theme refuses to run without a successful backup unless explicitly overridden by a narrow emergency flag.
4. apply-layout is separate from apply-theme.
5. rollback --to whitesur switches to the fallback family when installed.
6. rollback --to breeze restores KDE's boring recovery path.
7. restore-backup <timestamp> restores backed-up files and tells the user whether logout/login or Plasma shell restart is needed.
8. SDDM is not touched until its later explicit phase, and even then must avoid display-manager service, autologin, GPU, boot splash, GRUB, kernel, initramfs, and driver changes.

9. Phased Implementation Plan

Keep each phase PR-sized and reviewable.

Phase	Task	Files likely touched	Validation
1	Add status headers and fix active docs navigation around Vibe/ShellKit.	docs/decisions/index.md, docs/design/index.md, selected ADRs, docs/.vitepress/config.ts	pnpm docs:build, just lint-markdown
2	Move misplaced root docs into docs/reference/ and add archive landing pages.	GITHUBMCP_README.md, SMOKE_TEST_PROMPT.md, docs/reference/**, docs/archive/**	pnpm docs:build, just docs-check
3	Rewrite queue docs so GitHub Issues are durable state and TODO.md is legacy/manual.	docs/reference/todo-queue.md, TODO.md	pnpm docs:build, just lint-markdown
4	Add tracked CachyOS KDE ricing design docs from this plan and .tmp/ricing-plan.md.	docs/desktop/**, docs/.vitepress/config.ts	pnpm docs:build, just lint-markdown
5	Add tool ownership matrix without changing packages.	docs/tools/ownership.md, docs/tools/index.md, docs/tools/manifest.md	pnpm docs:build, just docs-check
6	Extract the smallest CachyOS desktop render assertions from the Unix smoke script.	scripts/smoke-test.sh, scripts/checks/cachyos-desktop-contract.*	scripts/smoke-test.sh --source-only, just check
7	Add non-mutating dotfiles-cachyos-theme status and plan.	home/dot_local/bin/**, scripts/cachyos/theme/**, home/.chezmoiignore	scripts/smoke-test.sh --source-only, just check
8	Add backup and asset-install phases.	scripts/cachyos/theme/**, docs	Source checks plus CachyOS host dry-run/status.
9	Add apply-theme for non-layout KDE/Qt/GTK/icon/cursor settings.	scripts/cachyos/theme/**, smoke checks	CachyOS GUI validation and rollback test.
10	Add optional panel layout apply.	scripts/cachyos/theme/apply-layout.sh, docs	Manual CachyOS session validation; separate PR.
11	Add optional SDDM/login theming apply.	scripts/cachyos/theme/backup-sddm.sh, scripts/cachyos/theme/apply-sddm.sh, docs	Privilege-gated CachyOS GUI/login validation; separate PR after desktop theme and layout are stable.

10. Validation Matrix

Docs-only change, minimum:

pnpm docs:build

Docs-only change, stronger:

just lint-markdown
just docs-check
python3 scripts/whitespace-check.py

General source validation before packaging or committing:

just check

Validation for a future CachyOS desktop source change:

bash -n scripts/smoke-test.sh scripts/install-prereqs-cachyos.sh
shfmt -d scripts/*.sh home/dot_local/bin/executable_*
shellcheck scripts/*.sh home/dot_local/bin/executable_*
scripts/smoke-test.sh --source-only
just check

Validation for a future CachyOS theme command before live apply:

dotfiles-cachyos-theme status
dotfiles-cachyos-theme plan
dotfiles-cachyos-theme backup
dotfiles-cachyos-theme install-assets --theme mactahoe --with-fallback whitesur
dotfiles-cachyos-theme status

Validation for a future CachyOS live theme apply:

chezmoi diff
chezmoi apply
~/.local/bin/dotfiles-smoke-test --fast
dotfiles-cachyos-theme backup
dotfiles-cachyos-theme apply-theme --theme mactahoe --appearance dark
dotfiles-cachyos-theme status
dotfiles-cachyos-theme rollback --to breeze
dotfiles-cachyos-theme restore-backup <timestamp>

Validation for future optional panel layout and SDDM phases:

dotfiles-cachyos-theme plan
dotfiles-cachyos-theme backup
dotfiles-cachyos-theme apply-layout --macos-like-panels
dotfiles-cachyos-theme status
dotfiles-cachyos-theme plan-sddm --theme mactahoe
dotfiles-cachyos-theme backup-sddm
dotfiles-cachyos-theme apply-sddm --theme mactahoe
dotfiles-cachyos-theme rollback-sddm --to breeze

Manual GUI checks for later desktop implementation:

• Confirm MacTahoe assets are installed and selectable.
• Confirm WhiteSur assets are installed or available as fallback.
• Confirm Breeze rollback is available.
• Confirm Kvantum theme selection works for common Qt apps.
• Open Dolphin, System Settings or Kate, one GTK app, and one browser or Electron-style app.
• Confirm window buttons are on the left only after the relevant phase.
• Confirm top panel and bottom dock-like panel only after the layout phase.
• Confirm SDDM/login theming only after the explicit later SDDM phase, with a tested rollback to Breeze or the previous default.
• Logout/login and confirm the desktop remains usable.
• Confirm WSL and Windows renders remain unchanged.

11. Risks

Risk	Impact	Mitigation
Active docs keep pointing agents at Vibe Core or ShellKit.	Agents may reintroduce retired systems.	Status headers, archive move, current decisions index rewrite.
GitHub Issues vs TODO.md remains contradictory.	Work queue state splits again.	Make GitHub Issues the durable queue in docs; keep TODO legacy/manual until migrated.
Validation split loses coverage.	False confidence from just check.	Extract one domain at a time and keep old just check facade unchanged.
Theme package names or upstream install flags drift.	Install scripts fail or install wrong assets.	Resolve current package/source names during implementation, not in this plan.
Normal upgrade path applies desktop theme accidentally.	Surprise visible desktop mutation.	Keep theme apply behind explicit dotfiles-cachyos-theme apply-* commands.
Bulk Plasma config export captures transient state.	Fragile, hard-to-review desktop config.	Manage stable keys and command phases only; no bulk export.
Panel layout apply breaks launcher/task access.	User loses easy desktop recovery.	Separate layout phase, mandatory backup, Breeze rollback, manual GUI validation.
SDDM/login theming breaks session entry.	High recovery cost.	Later optional phase only, with explicit privilege handling, SDDM-specific backup, rollback to Breeze/default, and documented TTY recovery.
Boot/session infrastructure is changed while theming.	High recovery cost.	No GRUB, boot splash, display-manager service, autologin, GPU, kernel, driver, or initramfs changes in any theme phase.
WSL or Windows receive CachyOS theme files.	Host lane pollution.	.chezmoiignore gates and render smoke assertions.
Catppuccin terminal/editor/dev themes get overwritten by desktop rice.	Existing daily workflow changes unexpectedly.	Explicit boundary: KDE/Qt/GTK/icon/cursor only unless user decides otherwise.
Flatpak/GTK4/libadwaita theming is inconsistent.	Visual mismatch remains.	Treat Flatpak overrides as optional phase, docs-first.
Root cleanup loses historical context.	Harder to understand previous choices.	Move/archive first, then migrate/prune in later issues.

12. Open Questions And User Decisions

These should be answered before live CachyOS desktop mutation:

Locked Decisions

Decision	Locked choice	Rationale
MacTahoe appearance	Dark-first	Preserves the current dark workstation feel while allowing light assets to be installed where practical.
First implementation scope	No layout first	Keeps the first desktop PR focused on theme assets and app/window/icon/cursor settings without higher-risk Plasma panel mutation.
Panel layout policy	Optional upstream-first layout phase	Panel layout remains behind an explicit dotfiles-cachyos-theme apply-layout style command and never runs from theme apply, chezmoi apply, just upgrade, or asset install. MacTahoe upstream layout templates and settings are the first source of truth before personal tweaks.
Better Blur and rounded corners	Manual/read-only recommendation	Upstream recommends Better Blur/force blur and rounded corners, but effect packages and KWin effect settings stay out of normal theme/layout automation until a separate guarded phase exists.
Flatpak/GTK edge cases	Automate later	First pass documents Flatpak/GTK4/libadwaita caveats; any Flatpak overrides belong in a later guarded, reversible command.
SDDM/login theming	Later optional SDDM phase	SDDM is expected future work, but it needs separate planning, backup, root/elevation handling, rollback, and login recovery validation after the normal desktop theme is stable.
Theme asset source	Decide at implementation, tentatively lean upstream Git	Verify current CachyOS/AUR/upstream state during implementation; tentatively prefer upstream Git for freshness and treat upstream installers as source material for repo-owned install logic rather than blindly executing them.
Apple branding	No Apple branding	Use MacTahoe/WhiteSur visual language without Apple-logo launcher icons or branding requirements.
Greenfield theming	Treat the old Spectre/Breeze attempt as inventory only	Do not preserve old panel layout, graphite palette, Breeze tuning, dock/clock choices, or old visual acceptance criteria as the new MacTahoe target.
Apple fonts	Use local SF fonts when present	Prefer SF Pro Text, SF Pro Display, and SF Mono if already installed locally; never commit Apple font binaries, and fall back to the managed font stack when absent.

Remaining Questions

None. All currently known desktop ricing decisions from this plan are locked.

Reopen decisions only if implementation discovers a concrete technical blocker or a new design choice with long-term consequences.