docs: say what changed about names, modes and what check looks at

README.md

@@ -95,15 +95,21 @@ named anything:
 - **postgres**: the service whose image is a postgres flavour, matching
   `postg`, `timescale`, `pgvector` or `citus`
 - **django**: the service that both builds an image and sets
-  `DJANGO_SETTINGS_MODULE`. A worker sharing the same build and `env_file`
+  `DJANGO_SETTINGS_MODULE`. Where more than one does — a worker beside the web
-  matches too, so the one publishing ports wins
+  service, say — the one publishing ports wins
 
 If nothing matches, or two candidates cannot be told apart, `ahab` says so and
-lists the services it looked at rather than guessing.
+lists the services it looked at rather than guessing. Two services that both
+build and set the settings module are ambiguous unless exactly one of them
+publishes ports.
 
 `POSTGRES_USER` and `POSTGRES_DB` are read off the detected postgres service, so
 `dropdb`, `createdb`, `pg_restore` and `pg_dump` use the role and database the
-project declares, falling back to `db` when it declares neither.
+project declares, falling back to `db` when it declares neither. Both have to
+be names: `ahab` hands them to those tools as a role and a database, and libpq
+reads a database name holding an `=` or a url as a whole connection string,
+which would send a dump to whatever server it names. A value that could be read
+as something other than a name is refused rather than passed on.
 
 ## django
 
@@ -138,6 +144,10 @@ ahab postgres import <path>          # drop, create, then restore
 ahab postgres psql <args>            # psql in the database container
 ```
 
+A dump is written `0600` and under a name of its own until it is complete, then
+renamed over the target: a cluster dump carries every role's password hash, and
+the default `0644` would hand it to anyone else with an account on the machine.
+
 `psql` passes its arguments through and only asks docker for a terminal when it
 has one to hand over, so both of these work:
 
@@ -155,9 +165,14 @@ A whole cluster dump from `pg_dumpall` is recognised by its header and handled
 differently again: it creates its own databases and carries role statements, so
 the database is dropped but not recreated, the dump goes to `psql` connected to
 `postgres`, and it runs without `ON_ERROR_STOP` because roles that already exist
-report errors that are expected. Gzipped dumps are decompressed on the way in,
+report errors that are expected. Any error it does not expect is reported and
-whichever of the three they hold. A cluster that has never held the database
+fails the import, since psql without `ON_ERROR_STOP` exits 0 having applied
-yet is a valid target either way, so importing into a fresh one works.
+only part of the dump. Gzipped dumps are decompressed on the way in, whichever
+of the three they hold. A cluster that has never held the database yet is a
+valid target either way, so importing into a fresh one works.
+
+`import` stops the project before it starts, so an import that fails leaves it
+stopped and says so: `docker compose up` brings it back.
 
 ## link
 
@@ -200,10 +215,24 @@ there is nothing to undo for a path whose symlink is gone.
 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.
 
+`check` looks at tracked paths too, since git tracks symlinks and one can lead
+out of the repository without appearing in any untracked listing. `add` cannot
+externalize a tracked path, so all `check` can do is report it, under the code
+`T>`.
+
+A symlink already leading out of the repository is not something `add` will
+take: moving the link would move the pointer and leave the contents where they
+are, so the store would hold a way back out while `check`, seeing a link into
+the store, called the repository clean.
+
 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.
+name it after. Its directories are created `0700`: it exists to hold what
+should not be readable from the repository, and on a shared machine the default
+`0755` would leave that to whoever else has an account. A store path derived
+from a remote, or a checkout name, that needed characters replacing carries a
+short fingerprint of the original, so two of them cannot land on one directory.
 
 ## configuration