diff --git a/README.md b/README.md
index 18098ac..0dbcf00 100644
--- a/README.md
+++ b/README.md
@@ -89,17 +89,19 @@ ahab link list                      # what the store holds for this repository
 ahab link check                     # what a sandbox can still read
 ahab link check --porcelain         # `<code> <path>`, for scripts
 ahab link check --exit-code         # exit 4 when anything is outside the store
+ahab link migrate                   # move out of the layout ahab 0.5 used
 ```
 
 Restoring is the inverse of adding: the file comes back to where it was and the
-store keeps nothing. A second checkout linking the same path is left with a
-dangling symlink, there being only ever one stored copy.
+store keeps nothing. Every checkout has a store directory of its own, so a
+second clone of the same repository links and restores its files without
+touching the first one's.
 
 Every stored path is in one of three states:
 
 ```
 $ ahab link list
-store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik
+store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik/afurnik-5f1c8e3a
 	linked:    .env
 	shadowed:  config.local.py
 	missing:   secrets/token
@@ -124,11 +126,26 @@ entries end with a NUL, and the two paths of a symlink leading elsewhere are
 separated by one as well, the way `git status -z` reports a rename.
 
 The store lives under
-`${XDG_DATA_HOME:-$HOME/.local/share}/ahab/<host>/<owner>/<repo>/`, derived
-from the Git `origin` remote, or `_local/<checkout>` when there is no remote to
-name it after. Its directories are created `0700`. A remote or checkout name
-that needed characters replacing carries a short fingerprint of the original,
-so two of them cannot share a directory.
+`${XDG_DATA_HOME:-$HOME/.local/share}/ahab/<host>/<owner>/<repo>/<dir>-<hash>/`.
+The repository part is derived from the Git `origin` remote, or
+`_local/<checkout>` when there is no remote to name it after; the last part is
+the checkout's directory name and a short hash of its full path, so two clones
+of one repository never share a directory. Its directories are created `0700`.
+A remote or checkout name that needed characters replacing carries a short
+fingerprint of the original, so two of them cannot share a directory either.
+
+Moving a checkout changes its hash. The symlinks still resolve, `check` still
+counts them as in the store and `restore <path>` still brings them back, so the
+way over is `restore` followed by `add`; `list` and `restore --all` only look
+in the new directory.
+
+### Upgrading from 0.5
+
+Before 0.6 the store had no per-checkout part, so existing links point at
+`<repo>/` directly. They keep working. `list` and `status` report them as
+`legacy`, and `ahab link migrate` moves them into the checkout's own directory
+and repoints the links. Only what the current checkout links is moved, so
+another clone's files in the same directory are left where they are.
 
 ## What ahab makes of your project
 
@@ -145,7 +162,7 @@ postgres: db (postgres:18-alpine)
 	container: 189d4d395d62
 	user:      myproject
 	database:  myproject_db
-store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik
+store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik/afurnik-5f1c8e3a
 	linked:    2
 	`ahab link check` lists what a sandbox can still read
 ```