Clarify install.sh / update.sh / uninstall.sh usage — when to use which

[edheltzel]

Problem

The three lifecycle scripts (install.sh, update.sh, uninstall.sh) overlap enough that it's not obvious which one to run when. Users hit this in practice:

• Fresh install vs. re-install — should you run install.sh again on an existing install, or update.sh?
• Local branch vs. released version — update.sh does git pull --ff-only origin main + a GitHub-release version check. If you're on a feature branch (or working from local commits not yet on main), update.sh either bails on the version check or refuses to pull. install.sh builds from whatever's in the working tree. Not stated anywhere.
• DB at a non-default path — there's no obvious way to "I have a DB at X, install everything to use it" without also knowing about RECALL_DB_PATH / --db-path.
• Custom locations entirely — install.sh --db-path exists; the equivalent post-install relocation is mem migrate --to; no overview anywhere ties these together.
• Stop conditions — neither install nor update asks the user to stop Claude Code first; the user has to know to pkill -f mem-mcp (or just exit Claude).
• Recovery story — install.sh restore exists; update.sh writes a ROLLBACK.txt; uninstall.sh --purge has a snapshot path. These need a single reference doc.

What to add

A short "Which script do I run?" decision table at the top of docs/installation.md and mirrored into the --help output of each script. Rough sketch:

Situation	Command
Fresh install on a clean machine	./install.sh
Re-install (idempotent, repairs symlinks)	./install.sh
Upgrade to the latest GitHub release	./update.sh
Custom DB path	./install.sh --db-path /path/to/recall.db
Move an existing DB	mem migrate --to /new/path/recall.db
Repair drifted symlinks without re-installing	mem doctor --fix
Roll back a failed install	./install.sh restore
Remove Recall (preserve data)	./uninstall.sh
Wipe everything including the DB	./uninstall.sh --purge

Plus:

• Pre-flight checklist in each script's --help: "Exit Claude Code / OpenCode / Pi first."
• Distinct --help output per script, not just the existing header comment.
• Cross-references in script comments — e.g. update.sh should explicitly say in --help: "Use install.sh if you want to install from the current working tree without a release version check."
• README's Quick Start should point at the new section.

Bonus

mem path already prints the install root + DB path + symlink state. Surfacing it in the install / update success banner ("Run `mem path` to confirm where things live") would close the loop.

Related:

• install.sh
• update.sh
• uninstall.sh
• docs/installation.md
• docs/upgrading.md