Merge pull request 'Document the Wayland icon-cache-needs-relogin gotcha' (#45 ) from docs/wayland-icon-cache-note into main

Document the Wayland icon-cache-needs-relogin gotcha
A user hit this after installing the new Arch/CachyOS package (triple-c#34): icon missing in the app menu, taskbar, and titlebar alike, with no error in the app's own log. Root cause has nothing to do with the app or its packaging — GNOME/KDE cache the installed-app list and resolved icons in the shell process's memory at startup, and Wayland has no equivalent to X11's soft shell-restart trick to force a live reload. Logging out and back in fixed it for them.
2026-08-27 23:15:00 +00:00 · 2026-08-27 15:53:19 -07:00 · 2026-08-27 22:37:19 +00:00 · 2026-08-27 15:06:43 -07:00
1 changed files with 24 additions and 0 deletions
@@ -6,6 +6,7 @@ Triple-C (Claude-Code-Container) is a desktop application that runs Claude Code

 ## Table of Contents

+- [Installation](#installation)
 - [Prerequisites](#prerequisites)
 - [First Launch](#first-launch)
 - [The Interface](#the-interface)
@@ -32,6 +33,23 @@ Triple-C (Claude-Code-Container) is a desktop application that runs Claude Code

 ---

+## Installation
+
+Download the build for your platform from [GitHub Releases](https://github.com/shadowdao/triple-c/releases/latest).
+
+| Platform | File | Install |
+|----------|------|---------|
+| **Windows** | `Triple-C_<version>_x64-setup.exe` or `.msi` | Run the installer. |
+| **macOS** | `Triple-C_<version>_universal.dmg` | Open the `.dmg` and drag Triple-C to Applications. |
+| **Debian / Ubuntu** | `Triple-C_<version>_amd64.deb` | `sudo apt install ./Triple-C_<version>_amd64.deb` |
+| **Fedora / RHEL** | `Triple-C-<version>-1.x86_64.rpm` | `sudo dnf install ./Triple-C-<version>-1.x86_64.rpm` |
+| **Arch / CachyOS** | `triple-c-bin-<version>-1-x86_64.pkg.tar.zst` | `sudo pacman -U ./triple-c-bin-<version>-1-x86_64.pkg.tar.zst` |
+| **Other Linux** | `Triple-C_<version>_amd64.AppImage` | `chmod +x` it, then run it directly. |
+
+> **macOS note:** The app is not signed or notarized. On first launch, macOS Gatekeeper may block it — right-click the app and select "Open" to bypass, or remove the quarantine attribute: `xattr -cr /Applications/Triple-C.app`.
+
+> **Arch / CachyOS note:** This package is not on the AUR — it's a `pacman`-installable file built and attached to each GitHub release by a maintainer-triggered step (`.gitea/workflows/publish-arch-package.yml`), so it can lag behind the very latest release by a bit. See [`packaging/arch/README.md`](packaging/arch/README.md) for details, including why "-bin" and what's verified about it.
+
 ## Prerequisites

 ### Docker
@@ -1536,3 +1554,9 @@ cp ~/.claude.json ~/.claude.json.bak && jq 'with_entries(select(.key | startswit
 ```

 This backs up your config and removes the corrupted marketplace entries. Claude Code will re-download them cleanly on the next startup.
+
+### App Icon Missing After Installing (Linux)
+
+If Triple-C's icon shows as generic or blank right after installing — in the app menu, taskbar, and window titlebar alike — **log out and back in.**
+
+Desktop shells (GNOME Shell, KDE Plasma) cache the list of installed apps and their resolved icons in memory when the shell starts, for performance. A freshly installed package's icon files land on disk correctly and its install hooks do rebuild the on-disk icon cache, but an already-running shell doesn't always notice — on X11 there used to be a way to soft-restart just the shell (GNOME's Alt+F2 → `r`) to force a reload, but under Wayland the shell *is* the compositor, so restarting it means ending the session. Logging out and back in starts a fresh shell that reads the current on-disk state, which picks the icon up.
Author	SHA1	Message	Date
jknapp	88d6bed6db	Merge pull request 'Document the Wayland icon-cache-needs-relogin gotcha' (#45 ) from docs/wayland-icon-cache-note into main Secret Scan / scan (push) Successful in 6s Details	2026-08-27 23:15:00 +00:00
shadow-test	6cc48b3266	Document the Wayland icon-cache-needs-relogin gotcha Secret Scan / scan (push) Successful in 4s Details Secret Scan / scan (pull_request) Successful in 4s Details A user hit this after installing the new Arch/CachyOS package (triple-c#34): icon missing in the app menu, taskbar, and titlebar alike, with no error in the app's own log. Root cause has nothing to do with the app or its packaging — GNOME/KDE cache the installed-app list and resolved icons in the shell process's memory at startup, and Wayland has no equivalent to X11's soft shell-restart trick to force a live reload. Logging out and back in fixed it for them.	2026-08-27 15:53:19 -07:00
jknapp	0fad306c25	Merge pull request 'Add an Installation section to HOW-TO-USE.md' (#43 ) from docs/installation-instructions into main Secret Scan / scan (push) Successful in 6s Details	2026-08-27 22:37:19 +00:00
shadow-test	99c9dd3cc2	Add an Installation section — nothing told a new user how to get the app Secret Scan / scan (push) Successful in 4s Details Secret Scan / scan (pull_request) Successful in 4s Details HOW-TO-USE.md's Prerequisites jumped straight to Docker and a Claude Code account, assuming Triple-C was already installed; the app itself had no download/install instructions anywhere in the docs. Covers all six release assets, including the new Arch/CachyOS .pkg.tar.zst (triple-c#34) that publish-arch-package.yml now attaches to each release.	2026-08-27 15:06:43 -07:00