fix(cache): survive an unusable cache, and add asimov doctor

CHANGELOG.md

@@ -8,6 +8,19 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
+- `asimov doctor` checks an install rather than your projects: which `asimov` your shell
+  actually runs (and flags an older one shadowing it on `PATH`), whether a schedule is
+  installed and loaded, whether `~/.cache/asimov/` is readable and writable by you,
+  whether the config file parses, and whether `tmutil` can read exclusions at all. It is
+  read-only — it prints the fix rather than applying it — and never executes another
+  `asimov` binary it finds, reading versions out of the file instead, because v0.3.0
+  ignores every argument and would start a real scan. Exits `1` if it finds anything
+  ([#122](https://github.com/AsimovMac/asimov/issues/122)).
+- `UPGRADING.md`: a section for upgrading from v0.3.0, the version most people have,
+  covering the three leftovers that outlive it — the LaunchAgent, the old cellar, and a
+  root-owned cache — in an order that works
+  ([#122](https://github.com/AsimovMac/asimov/issues/122)).
+
 - `make test-system-bash` runs the suite under the macOS system bash (3.2), which is what
   most users get — `asimov` starts with `#!/usr/bin/env bash`, and a development machine
   usually has 5.x first on `PATH`. `make test BASH_BIN=<path>` pins any interpreter, and
@@ -35,6 +48,18 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Fixed
 
+- An unreadable or unwritable file under `~/.cache/asimov/` no longer kills the run. The
+  cache is an optimisation, but a bare `cat` on an unreadable state file failed under
+  `set -Eeu -o pipefail` and aborted immediately, printing nothing but `Permission
+  denied`. Every cache read and write is now guarded: Asimov warns once, names the reset
+  command, and continues without the cache
+  ([#122](https://github.com/AsimovMac/asimov/issues/122)).
+- A run as root no longer leaves root-owned files behind that break the next run as your
+  own user — the cause of the failure above. The cache directory was chowned to the
+  console user, but the state files written afterwards were not; they are now created
+  before the chown, and appending never changes an existing file's owner
+  ([#122](https://github.com/AsimovMac/asimov/issues/122)).
+
 ### Removed
 
 ## [0.10.0] — 2026-07-26

README.md

@@ -132,6 +132,8 @@ If `mdfind` doesn't list your projects, the run isn't reaching them. The two usu
 
 ```
 asimov [--dry-run] [--verbose] [--quiet] [--stats] [--no-read-cache] [--no-write-cache] [--help] [--version]
+asimov prune  [--quiet]
+asimov doctor [--quiet]
 ```
 
 
@@ -180,6 +182,44 @@ Asimov keeps a cache under `~/.cache/asimov/` so repeat runs are near-instant. T
 - Both together = a fully stateless run that reads and writes nothing. **`--no-cache` is an alias for this.**
 
 
+### `asimov doctor`
+
+Checks the install itself rather than your projects. Run it when something seems off, or straight after an upgrade.
+
+```
+$ asimov doctor
+
+Asimov doctor
+
+Install
+  ✓ asimov 0.10.0 (/opt/homebrew/bin/asimov)
+  ✗ typing 'asimov' runs a different binary — this one is shadowed
+      /usr/local/bin/asimov  (version 0.3.0)
+      Remove the one you don't want, or fix the order of PATH.
+
+Schedule
+  ✗ homebrew.mxcl.asimov: its program /opt/homebrew/Cellar/asimov/0.3.0/bin/asimov no longer exists
+      launchctl bootout gui/$(id -u)/homebrew.mxcl.asimov
+      rm ~/Library/LaunchAgents/homebrew.mxcl.asimov.plist
+
+Cache
+  ✗ ~/.cache/asimov/excluded is not readable and writable by you (owner: root)
+      A run as root left these behind. Clear them:
+      rm -rf ~/.cache/asimov
+
+Config
+  ✓ ~/.config/asimov/config looks valid
+
+Time Machine
+  ✓ tmutil can read exclusions
+
+3 problems found.
+```
+
+It covers five things: which `asimov` your shell actually runs, whether a schedule is installed and loaded, whether the cache is readable and writable by you, whether the config parses, and whether `tmutil` can read exclusions at all (it can't without Full Disk Access).
+
+`doctor` is **read-only** — it prints the fix rather than applying it — and it never executes another `asimov` binary it finds, reading versions out of the file instead. It exits `1` if it finds anything, so it's safe to use in a script.
+
 ## Schedule
 
 The curl and source installers set up a daily launchd job automatically. To trigger one immediately or stop the schedule:

UPGRADING.md

@@ -1,5 +1,71 @@
 # Upgrading Asimov
 
+## To v0.10.0 from v0.3.0 (the original `stevegrunwell/asimov`)
+
+Most people upgrading are coming from `0.3.0`, the version Homebrew shipped for years.
+It upgrades cleanly, but three leftovers can outlive it. Work through this in order.
+
+**Before you start: don't run `asimov` to check your version.** v0.3.0 parses no
+arguments at all — it ignores `--version`, `--help`, and every subcommand, and goes
+straight to scanning and writing Time Machine exclusions. Read the version out of the
+file instead:
+
+```sh
+grep -m1 -E '@version|ASIMOV_VERSION=' "$(command -v asimov)"
+```
+
+### 1. Stop the schedule before you uninstall
+
+Uninstalling first leaves the LaunchAgent behind with nothing to run:
+
+```sh
+brew services stop asimov
+launchctl bootout gui/$(id -u)/homebrew.mxcl.asimov 2>/dev/null
+rm -f ~/Library/LaunchAgents/homebrew.mxcl.asimov.plist
+```
+
+### 2. Replace the binary
+
+```sh
+brew uninstall asimov
+brew install asimov
+```
+
+If `brew uninstall` reports `Permission denied @ apply2files`, the old cellar files are
+owned by another user — Homebrew prints the `sudo` command to force it, and that is safe
+here.
+
+### 3. Clear the old cache
+
+v0.10.0 keeps state in `~/.cache/asimov/`. If anything ever ran Asimov as root, those
+files are root-owned and unreadable by you:
+
+```sh
+rm -rf ~/.cache/asimov
+```
+
+v0.10.0 and earlier crashed outright on this with a bare `Permission denied`. Current
+versions warn and carry on, but clearing it is still the fix.
+
+### 4. Check the result
+
+`doctor` exists only in current versions, so it comes last — there is nothing to run
+before the new binary is in place:
+
+```sh
+asimov doctor
+```
+
+It reports a shadowed binary, a leftover schedule, an unreadable cache, and a bad config,
+and exits non-zero if it finds any. If it prints usage errors or starts a scan instead,
+an old binary is still first on your `PATH` — `doctor` names the one it found.
+
+### One thing that isn't broken
+
+Asimov is a one-shot scan, not a daemon. After `brew services start asimov`, `ps aux |
+grep asimov` finding nothing is expected: it scans, excludes, and exits. To confirm it is
+actually scheduled, use `asimov doctor`.
+
 ## To v0.10.0 (from the `django23/asimov` fork)
 
 `0.10.0` folds the fork's work (v0.4.0–v0.8.0, plus a `v0.9.0-beta` round) back into