docs: add install-debugging and uninstall guides for CLI and Coven Codes

content/docs/cli/install-debugging.mdx

@@ -0,0 +1,177 @@
+---
+title: "Install Debugging"
+summary: "Diagnose a failed or broken Coven CLI install: coven not found, wrong platform package, PATH gaps, stale npx cache, and source-build failures."
+description: "Debugging guide for Coven CLI installation problems across npm, native platform packages, and Cargo/source builds."
+read_when:
+  - The coven command is not found after install
+  - npm reports a missing optional platform dependency
+  - A source build of the CLI fails
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Use this page when installing the Coven CLI did not produce a working `coven` command. For runtime failures after a successful install (daemon, harness, or session problems), see [Troubleshooting](/docs/reference/troubleshooting) and [Harness Troubleshooting](/docs/harnesses/troubleshooting).
+
+## Start With Doctor
+
+If `coven` runs at all, run it first:
+
+```sh
+coven doctor
+```
+
+`doctor` reports store, project, daemon, socket, and harness readiness. If `coven doctor` fails because the command is not found, work through the sections below.
+
+If `coven` is not on `PATH` yet, you can still exercise the published package without a global install:
+
+```sh
+npx @opencoven/cli doctor
+pnpm dlx @opencoven/cli doctor
+```
+
+## Install Decision Flow
+
+```mermaid
+flowchart LR
+  Start([coven install broken?]) --> Runs{coven runs at all?}
+  Runs -- no --> Found["`coven` not found\ncheck install method + PATH"]
+  Runs -- yes --> Version{correct version?}
+  Version -- no --> Stale["Stale npx cache or old global\nreinstall @latest"]
+  Version -- yes --> Native{native package resolved?}
+  Native -- no --> Platform["Missing optional platform dep\nreinstall from target OS/CPU"]
+  Native -- yes --> Doctor["coven doctor"]
+
+  Found --> Method{how installed?}
+  Method -- npm global --> NpmFix["npm root -g on PATH?"]
+  Method -- source --> CargoFix["~/.cargo/bin on PATH?"]
+  Method -- native binary --> BinFix["binary dir on PATH?"]
+  NpmFix --> Doctor
+  CargoFix --> Doctor
+  BinFix --> Doctor
+  Stale --> Doctor
+  Platform --> Doctor
+```
+
+## Fast Triage
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `coven: command not found` | Install dir not on `PATH`, or global install failed | Confirm install method, then add its bin dir to `PATH`. |
+| `coven` runs an old version | Stale `npx` cache or an old global install shadows the new one | Clear the cache / reinstall `@latest`; check `which -a coven`. |
+| npm warns about a missing optional dependency | The native platform package did not resolve for your OS/CPU | Reinstall `@opencoven/cli` from the environment where you run it. |
+| `Unsupported platform` on install | OS/CPU is not covered by a published native package | Build from source, or use a supported platform / WSL2. |
+| Source build fails to compile | Toolchain or dependency mismatch | Update Rust stable and retry a clean `cargo build`. |
+
+## `coven` Command Not Found
+
+The fix depends on how you installed.
+
+### npm global install
+
+Confirm npm's global bin directory and that it is on `PATH`:
+
+```sh
+npm root -g
+npm bin -g
+echo "$PATH" | tr ':' '\n' | grep -F "$(npm bin -g)"
+```
+
+If the global bin directory is missing from `PATH`, add it in your shell profile, open a new terminal, and retry:
+
+```sh
+coven doctor
+```
+
+If the global install itself failed (for example, permission errors writing to the global prefix), prefer a user-writable npm prefix or a version manager over `sudo npm install -g`.
+
+### Native binary
+
+If you downloaded a native binary directly, make sure its directory is on `PATH`:
+
+```sh
+which -a coven
+echo "$PATH" | tr ':' '\n'
+```
+
+### Source build
+
+If you built with Cargo, make sure Cargo's bin directory is on `PATH`:
+
+```sh
+echo "$PATH" | tr ':' '\n' | grep "$HOME/.cargo/bin"
+```
+
+## Wrong Or Stale Version
+
+`npx` caches packages, so a one-off invocation can run an older CLI than you expect. Confirm what is actually running:
+
+```sh
+which -a coven
+coven --version
+```
+
+Reinstall the latest global build, or clear the `npx` cache and rerun:
+
+```sh
+npm install -g @opencoven/cli@latest
+coven doctor
+```
+
+If more than one `coven` appears in `which -a coven`, an earlier install is shadowing the new one on `PATH`. Remove the stale copy or reorder `PATH` so the intended install wins.
+
+## Missing Native Platform Package
+
+The npm wrapper `@opencoven/cli` resolves a matching native package (`@opencoven/cli-macos`, `@opencoven/cli-linux-x64`, `@opencoven/cli-windows`) as an optional dependency. If npm cannot resolve one for your OS/CPU pair, `coven` will not run even though the wrapper installed.
+
+<Callout type="warn" title="Reinstall from the environment where you run Coven">
+Installing on one platform and copying `node_modules` to another skips the native package for the target. Reinstall `@opencoven/cli` from the same OS/CPU where you plan to run `coven`.
+</Callout>
+
+Check what npm published and what resolved:
+
+```sh
+npm view @opencoven/cli version dist-tags
+npm view @opencoven/cli-macos version dist-tags
+npm view @opencoven/cli-linux-x64 version dist-tags
+npm view @opencoven/cli-windows version dist-tags
+```
+
+The published wrapper currently targets `darwin-arm64`, `linux-x64`, and `win32-x64`. Alpine/musl is not covered by the published wrapper today. On an unsupported platform, build from source or use the WSL2 path — see [Install Coven](/docs/guide/install#platform-notes).
+
+## Source Build Failures
+
+Build from source when you are contributing, testing unreleased behavior, or running on an unsupported npm platform:
+
+```sh
+git clone https://github.com/OpenCoven/coven.git
+cd coven
+cargo build --workspace
+cargo run -p coven-cli -- doctor
+```
+
+If the build fails to compile, update the Rust toolchain and retry from a clean state:
+
+```sh
+rustup update stable
+cargo clean
+cargo build --workspace
+```
+
+To install the built binary onto your Cargo bin path:
+
+```sh
+cargo install --path crates/coven-cli
+coven doctor
+```
+
+## Evidence To Collect
+
+When an install problem needs a support report, include:
+
+- The install method (`npx`, global npm, native binary, or source build).
+- The output of `coven --version` and `which -a coven`.
+- Your OS and CPU architecture.
+- For npm installs, the output of the `npm view` commands above and any missing-optional-dependency warning.
+- For source builds, the failing `cargo build` output.
+
+Do not paste secrets or private paths into a report. Once `coven` runs, continue with [Doctor](/docs/cli/doctor).

content/docs/cli/meta.json

@@ -6,6 +6,8 @@
   "pages": [
     "index",
     "install",
+    "install-debugging",
+    "uninstall",
     "interactive",
     "doctor",
     "daemon",

content/docs/cli/uninstall.mdx

@@ -0,0 +1,93 @@
+---
+title: "Uninstall"
+summary: "Remove the Coven CLI cleanly: stop the daemon, remove the install, and decide whether to delete local Coven state."
+description: "Uninstall reference for the Coven CLI across npm global installs, Cargo/source builds, and local state under COVEN_HOME."
+read_when:
+  - You want to remove the coven command
+  - You are deciding whether to delete local session state
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Use this page to remove the Coven CLI. Removing the CLI and deleting local state are separate steps — do the first for a routine uninstall, and the second only when you intentionally want to erase session history.
+
+## Stop The Daemon First
+
+The daemon holds the local socket and owns running sessions. Stop it before removing the CLI so nothing is left listening:
+
+```sh
+coven sessions --all --plain
+coven daemon status
+coven daemon stop
+```
+
+If sessions are still running, let them finish, kill them, or archive them first. Removing the CLI does not clean up a daemon that is already running.
+
+## Remove The Install
+
+Remove the CLI using the same method you installed with.
+
+### npm global install
+
+```sh
+npm uninstall -g @opencoven/cli
+```
+
+If you used `npx`/`pnpm dlx` for one-off runs, there is nothing to uninstall — clearing your package manager cache is enough to drop the downloaded copy.
+
+### Cargo / source build
+
+If you installed the Rust binary with `cargo install`:
+
+```sh
+cargo uninstall coven-cli
+```
+
+If you only ran `cargo build`/`cargo run` from a cloned checkout, deleting the checkout removes the build:
+
+```sh
+rm -rf coven   # the cloned OpenCoven/coven directory
+```
+
+### Native binary
+
+If you placed a native binary on `PATH` yourself, delete that file. Confirm nothing remains:
+
+```sh
+which -a coven
+```
+
+## Verify Removal
+
+```sh
+which -a coven
+```
+
+No output means the command is gone. If a path still prints, another install is still present — remove it with the matching method above.
+
+## Local State
+
+Coven keeps local state under `COVEN_HOME` (default `~/.coven`), including session history, events, and the daemon socket. Uninstalling the CLI does **not** delete this directory.
+
+<Callout type="warn" title="Deleting local state is irreversible">
+`rm -rf ~/.coven` permanently deletes your local session history and events. Do this only when you intend to erase all local Coven data, not as a routine uninstall or update step.
+</Callout>
+
+Remove local state only when you deliberately want it gone:
+
+```sh
+rm -rf ~/.coven
+```
+
+If you set a custom `COVEN_HOME`, remove that path instead of `~/.coven`.
+
+## Reinstalling Later
+
+Removing the CLI while keeping `~/.coven` lets you reinstall later and pick up your existing sessions:
+
+```sh
+npm install -g @opencoven/cli@latest
+coven doctor
+```
+
+See [Install Coven](/docs/guide/install) for full install paths and [Install Debugging](/docs/cli/install-debugging) if the reinstall does not produce a working `coven` command.

content/docs/coven-codes/install-debugging.mdx

@@ -0,0 +1,116 @@
+---
+title: "Install Debugging"
+summary: "Diagnose a failed Coven Codes desktop install: blocked installers, an app that will not launch, and a client that cannot reach the local daemon."
+description: "Debugging guide for the Coven Codes desktop application across macOS, Linux, and Windows installs."
+read_when:
+  - The Coven Codes app will not install or open
+  - The app opens but cannot reach the Coven daemon
+  - You need to confirm which release you installed
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Coven Codes is a first-party desktop application, distributed as a published build rather than an npm package. Use this page when installing or opening the app did not produce a working workspace.
+
+<Callout type="info" title="Verify the current release channel">
+Coven Codes ships from [`OpenCoven/coven-codes` releases](https://github.com/OpenCoven/coven-codes/releases). Download the build that matches your OS and CPU, and confirm the current channel there before relying on any version-specific behavior.
+</Callout>
+
+Coven Codes is a client. It talks to the local `coven` daemon over the Unix socket at `~/.coven/coven.sock`, the same boundary every other client uses. It does not bypass daemon validation, and it should stay useful with clear fallback states even when Coven is not installed. Two failure classes matter here: the **app itself** will not install or launch, and the app launches but **cannot reach the daemon**.
+
+## Install Decision Flow
+
+```mermaid
+flowchart LR
+  Start([Coven Codes broken?]) --> Installs{installer runs?}
+  Installs -- no --> Blocked["OS blocked the installer\nGatekeeper / SmartScreen / exec bit"]
+  Installs -- yes --> Opens{app opens?}
+  Opens -- no --> Launch["App will not launch\ncheck arch + quarantine + logs"]
+  Opens -- yes --> Daemon{reaches daemon?}
+  Daemon -- no --> Socket["Client cannot connect\ncheck coven daemon + COVEN_HOME"]
+  Daemon -- yes --> Version{versions compatible?}
+  Version -- no --> Compat["Update app or Coven\nso API versions overlap"]
+  Version -- yes --> Done([Working])
+
+  Blocked --> Opens
+  Launch --> Daemon
+  Socket --> Daemon
+  Compat --> Done
+```
+
+## Fast Triage
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Installer is blocked or "damaged" | OS gatekeeping on an unsigned/quarantined download | Allow the app in OS security settings; re-download over HTTPS from Releases. |
+| App icon appears but nothing opens | Wrong CPU build, or the download is quarantined | Install the build for your architecture; clear the quarantine attribute. |
+| App opens but shows no sessions / "daemon unavailable" | The `coven` daemon is stopped, or the app uses a different `COVEN_HOME` | `coven daemon start`; make sure the app and CLI share the same `COVEN_HOME`. |
+| App works but launch/kill/input is refused | Expected — the daemon is the authority | Check session liveness with `coven sessions --all`; the daemon validates every sensitive request. |
+| Features missing or API errors | App and daemon expose non-overlapping API versions | Update Coven Codes or the CLI so supported versions overlap. |
+
+## Installer Is Blocked
+
+Because the app is downloaded rather than installed from a package registry, the OS may gate the first launch.
+
+### macOS
+
+If macOS reports the app is damaged or from an unidentified developer, it is quarantined. Open it once from Finder with **Control-click → Open**, or allow it under **System Settings → Privacy & Security**. Re-download over HTTPS if the file may be corrupted.
+
+### Windows
+
+If SmartScreen blocks the installer, choose **More info → Run anyway** for a build you downloaded yourself from Releases. Prefer the signed installer when one is published.
+
+### Linux
+
+For an `AppImage`, make it executable before running it:
+
+```sh
+chmod +x CovenCodes-*.AppImage
+./CovenCodes-*.AppImage
+```
+
+If the AppImage will not start, confirm FUSE is available on your distribution, or extract and run it with `--appimage-extract`. For a `.deb`/`.rpm`, install it with your system package manager instead.
+
+## App Will Not Launch
+
+If the installer succeeded but the app does not open:
+
+- Confirm you installed the build for your CPU architecture (for example, Apple Silicon vs Intel on macOS).
+- On macOS, clear a stuck quarantine attribute on the installed app bundle:
+
+  ```sh
+  xattr -dr com.apple.quarantine "/Applications/Coven Codes.app"
+  ```
+
+- Re-download from Releases if the file may be truncated or corrupted, and reinstall.
+
+## App Cannot Reach The Daemon
+
+If Coven Codes opens but shows no sessions or reports the daemon is unavailable, the problem is the client-to-daemon link, not the install. Verify the daemon from a terminal:
+
+```sh
+coven doctor
+coven daemon status
+coven daemon start
+```
+
+<Callout type="warn" title="The app and CLI must share COVEN_HOME">
+Coven Codes connects to the socket under `COVEN_HOME` (default `~/.coven`, socket `~/.coven/coven.sock`). If the CLI uses a custom `COVEN_HOME` that the app does not, they will not see the same daemon or sessions. Point both at the same path.
+</Callout>
+
+Coven Codes is designed to stay useful when Coven is not installed — it should present a clear "install Coven" state rather than failing silently. If you see that state, the app is working; install or start Coven to connect. See [Install Coven](/docs/guide/install).
+
+## Version Or API Mismatch
+
+Clients and the daemon negotiate a supported API version (`/api/v1`). If the app is much newer or older than the installed CLI/daemon, some features can be rejected. Update whichever side is behind so their supported versions overlap. See [API Version Rejected](/docs/reference/troubleshooting#api-version-rejected).
+
+## Evidence To Collect
+
+For a support report, include:
+
+- The Coven Codes version and the release you downloaded, plus your OS and CPU architecture.
+- Whether the failure is install, launch, or daemon connectivity.
+- The output of `coven doctor` and `coven daemon status`.
+- Whether the app and CLI use the same `COVEN_HOME`.
+
+Do not paste secrets or private paths into a report. To remove the app, see [Uninstall](/docs/coven-codes/uninstall).