diff --git a/docs/REBRAND.md b/docs/REBRAND.md
index 4ce7c9ba2..76d841b67 100644
--- a/docs/REBRAND.md
+++ b/docs/REBRAND.md
@@ -23,8 +23,10 @@ codewhale doctor
 codewhale
 ```
 
-Your `~/.deepseek/config.toml`, `~/.deepseek/sessions/`, `~/.deepseek/skills/`,
-`~/.deepseek/tasks/`, and `~/.deepseek/mcp.json` are untouched. Existing
+Your existing `~/.deepseek/config.toml`, `~/.deepseek/sessions/`,
+`~/.deepseek/skills/`, `~/.deepseek/tasks/`, and `~/.deepseek/mcp.json` are
+not deleted. New CodeWhale installs prefer `~/.codewhale/`, and legacy
+`~/.deepseek/` state remains a read fallback while you migrate. Existing
 `DEEPSEEK_*` environment variables continue to work.
 
 ## What got renamed
@@ -38,6 +40,13 @@ Your `~/.deepseek/config.toml`, `~/.deepseek/sessions/`, `~/.deepseek/skills/`,
 | Release assets | `deepseek-<platform>` / `deepseek-tui-<platform>` | `codewhale-<platform>` / `codewhale-tui-<platform>` |
 | Checksum manifest | `deepseek-artifacts-sha256.txt` | `codewhale-artifacts-sha256.txt` |
 
+## What changed for local state
+
+New installs write product-owned state under `~/.codewhale/`. Existing
+`~/.deepseek/` config, sessions, skills, tasks, MCP config, memory, and notes
+remain readable as legacy fallbacks while you migrate. CodeWhale never deletes
+the legacy directory automatically.
+
 ## What did NOT change
 
 Anything that targets the DeepSeek provider API stays exactly as it was:
@@ -52,9 +61,6 @@ Anything that targets the DeepSeek provider API stays exactly as it was:
   aliases `deepseek-chat` and `deepseek-reasoner`.
 - **Hosts**: `api.deepseek.com` (global) and `api.deepseeki.com` (China
   fallback).
-- **Config directory**: `~/.deepseek/`. Renaming this would invalidate
-  every existing install's saved API key, sessions, skills, MCP config,
-  and audit log.
 - **GitHub repository URL**: `https://github.com/Hmbown/CodeWhale`.
   The old `Hmbown/DeepSeek-TUI` URL redirects there during the transition.
 - **Homebrew tap and formula** (`Hmbown/homebrew-deepseek-tui`): still
@@ -117,6 +123,39 @@ A second checksum manifest, `deepseek-artifacts-sha256.txt`, is attached as
 an alias of `codewhale-artifacts-sha256.txt` so v0.8.40's hardcoded lookup
 still verifies.
 
+### Sessions, skills, and manual workspaces
+
+Renaming the binary does not require starting over:
+
+- **Config**: on first launch, CodeWhale copies `~/.deepseek/config.toml` to
+  `~/.codewhale/config.toml` if the CodeWhale file does not already exist.
+  It never overwrites a newer CodeWhale config. You can inspect the active path
+  with `codewhale doctor`.
+- **Sessions and tasks**: managed state is read from `~/.codewhale/...` when
+  present, with `~/.deepseek/...` used as the legacy fallback when only the old
+  directory exists. Existing saved sessions still appear in `codewhale sessions`
+  and the TUI resume picker.
+- **Skills**: CodeWhale discovers workspace skills first, then global skills,
+  including both `~/.codewhale/skills` and legacy `~/.deepseek/skills`. Existing
+  skill directories with `SKILL.md` do not need to be rewritten.
+- **MCP config**: the default path is `~/.codewhale/mcp.json`. If that file is
+  absent, CodeWhale still reads legacy `~/.deepseek/mcp.json`. To use a custom
+  MCP config file, set `mcp_config_path` in `config.toml` or
+  `DEEPSEEK_MCP_CONFIG`.
+- **Manual binary installs**: keep the dispatcher and TUI binaries as siblings
+  on your `PATH`: `codewhale` plus `codewhale-tui`. On Windows, the recommended
+  user-local location is `%LOCALAPPDATA%\Programs\CodeWhale\bin`. On Unix-like
+  systems, any user-writable `PATH` directory is fine as long as both binaries
+  are present.
+- **Specified work directories**: running `codewhale` from a project directory,
+  or launching it with a specific workspace path, does not move project files.
+  CodeWhale reads `<workspace>/.codewhale/config.toml` first and falls back to
+  legacy `<workspace>/.deepseek/config.toml` when the new path is absent.
+
+If both `~/.codewhale/...` and `~/.deepseek/...` copies exist, the CodeWhale
+path wins. Keep the legacy directory until you have confirmed `codewhale
+doctor`, `codewhale sessions`, and your expected skills all show the same state.
+
 ## Why the name change
 
 CodeWhale is a shorter, terminal-friendlier handle for the same terminal