From 00773c61be2bc2a6216802216f2e2f97ff5785a2 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Wed, 22 Apr 2026 06:58:57 -0700
Subject: [PATCH] docs(readme): align manual uninstall with --keep-state split

The bin/gstack-uninstall script already has --keep-state, which removes
skills but preserves ~/.gstack/ (config, analytics, sessions, project
history, installation-id). The manual-removal block in README didn't
reflect that split; it dropped rm -rf ~/.gstack inline as step 4 alongside
the skill cleanup, so users following the manual path always lost their
state even when the scripted path lets them keep it.

Labels the numbered block as the --keep-state equivalent and moves the
~/.gstack purge into an "Also purge gstack data (optional)" subsection.
Same behaviour available, just documented as two choices.

No script changes.

Fixes #1131
---
 README.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 05001dce2..d6dd40cb4 100644
--- a/README.md
+++ b/README.md
@@ -312,6 +312,8 @@ This handles skills, symlinks, global state (`~/.gstack/`), project-local state,
 
 If you don't have the repo cloned (e.g. you installed via a Claude Code paste and later deleted the clone):
 
+Mirrors `gstack-uninstall --keep-state` (preserves `~/.gstack/` data):
+
 ```bash
 # 1. Stop browse daemons
 pkill -f "gstack.*browse" 2>/dev/null || true
@@ -324,23 +326,28 @@ done
 # 3. Remove gstack
 rm -rf ~/.claude/skills/gstack
 
-# 4. Remove global state
-rm -rf ~/.gstack
-
-# 5. Remove integrations (skip any you never installed)
+# 4. Remove integrations (skip any you never installed)
 rm -rf ~/.codex/skills/gstack* 2>/dev/null
 rm -rf ~/.factory/skills/gstack* 2>/dev/null
 rm -rf ~/.kiro/skills/gstack* 2>/dev/null
 rm -rf ~/.openclaw/skills/gstack* 2>/dev/null
 
-# 6. Remove temp files
+# 5. Remove temp files
 rm -f /tmp/gstack-* 2>/dev/null
 
-# 7. Per-project cleanup (run from each project root)
+# 6. Per-project cleanup (run from each project root)
 rm -rf .gstack .gstack-worktrees .claude/skills/gstack 2>/dev/null
 rm -rf .agents/skills/gstack* .factory/skills/gstack* 2>/dev/null
 ```
 
+#### Also purge gstack data (optional)
+
+`~/.gstack/` holds config, analytics, sessions, project history, and the installation-id. Run this only if you want a clean slate (equivalent to `gstack-uninstall` without `--keep-state`):
+
+```bash
+rm -rf ~/.gstack
+```
+
 ### Clean up CLAUDE.md
 
 The uninstall script does not edit CLAUDE.md. In each project where gstack was added, remove the `## gstack` and `## Skill routing` sections.