Reconcile docs with code across the accuracy-sweep items (closes #74)

Documentation only. Corrects the ARCHITECTURE.md chunk sizes and the fx
config type; documents the process-wide PID lock, the `ls`/`rm` aliases,
`VAULTIK_CPUPROFILE`/`VAULTIK_MEMPROFILE`, the `age_secret_key` key and
its threat-model caveat, and how zstd levels 1-19 collapse onto four
presets; narrows the output-style claim to match reality; and links
ARCHITECTURE.md and config.example.yml from the README. The two
behaviour changes the sweep surfaced are deferred to #149 (route direct
stdout through internal/ui) and #150 (scope the lock), each linked from
the text. DATAMODEL.md and REPOSTRUCTURE.md were already linked.

model: claude-opus-4-8

README.md

@@ -147,10 +147,10 @@ vaultik [--config <path>] config edit
 vaultik [--config <path>] config get <key>
 vaultik [--config <path>] config set <key> <value>
 vaultik [--config <path>] snapshot create [snapshot-names...] [--cron] [--prune] [--keep-newer-than <duration>]
-vaultik [--config <path>] snapshot list [--json]
+vaultik [--config <path>] snapshot list [--json]                  # alias: ls
 vaultik [--config <path>] snapshot verify <snapshot-id> [--deep] [--json]
 vaultik [--config <path>] snapshot purge [--keep-latest | --older-than <duration>] [--snapshot <name>...] [--force]
-vaultik [--config <path>] snapshot remove <snapshot-id> [--dry-run] [--force] [--local-only] [--json]
+vaultik [--config <path>] snapshot remove <snapshot-id> [--dry-run] [--force] [--local-only] [--json]  # alias: rm
 vaultik [--config <path>] snapshot restore <snapshot-id> <target-dir> [paths...] [--verify]
 vaultik [--config <path>] prune [--force] [--json]
 vaultik [--config <path>] info
@@ -169,6 +169,21 @@ vaultik version
 * `--quiet`, `-q`: Suppress non-error output (also suppresses startup banner)
 * `--skip-errors`: Continue past per-file errors instead of aborting (applies to `snapshot create` and `restore`)
 
+### locking
+
+Every command that opens the local index — `snapshot create`, `snapshot
+list`, `snapshot verify`, `snapshot purge`, `snapshot remove`, `snapshot
+restore`, `prune`, `info`, and `remote info`/`remote nuke` — takes a
+process-wide lock at `$XDG_DATA_HOME/vaultik/vaultik.pid`
+(`~/.local/share/vaultik/vaultik.pid` on Linux) for the whole run. Only
+one such command runs at a time: a second one exits immediately with an
+"already running" error rather than waiting. The lock is not scoped to
+mutating commands, so read-only commands are affected too — `vaultik
+snapshot list` fails while a backup is in progress; scoping it so
+read-only commands run during a backup is tracked in
+[issue #150](https://git.eeqj.de/sneak/vaultik/issues/150). `config`,
+`database delete`, `completion`, and `version` do not take the lock.
+
 ### stdout and stderr
 
 Log output — everything from `--verbose` and `--debug`, and every
@@ -203,6 +218,8 @@ and `vaultik prune --json | jq .` both work as written.
 * `VAULTIK_AGE_SECRET_KEY`: Age private key for decryption (required for `snapshot restore` and `snapshot verify --deep`)
 * `VAULTIK_CONFIG`: Path to config file (overridden by `--config`)
 * `VAULTIK_INDEX_PATH`: Override local SQLite index path
+* `VAULTIK_CPUPROFILE`: Write a CPU profile to this path for the duration of the run (development/debugging)
+* `VAULTIK_MEMPROFILE`: Write a heap profile to this path when the run exits (development/debugging)
 
 ### shell completion
 
@@ -395,6 +412,10 @@ both are set.
 
 ## architecture
 
+For an implementation-level view of the internals — the data model, the
+`fx` dependency-injection wiring, and the scanner — see
+[`ARCHITECTURE.md`](ARCHITECTURE.md).
+
 ### remote storage layout
 
 ```
@@ -472,19 +493,24 @@ derivation.
 
 ### compression
 
-* zstd compression at configurable level (1-19, default 3)
+* zstd compression at configurable level (1-19, default 3). The level is
+  accepted as 1-19 but maps onto zstd's four internal speed presets:
+  1-2 fastest, 3-5 default, 6-9 better, 10-19 best. Levels within the
+  same band compress identically.
 * Applied before encryption at the blob level
 
 ---
 
 ## configuration reference
 
-Run `vaultik config init` to generate a fully commented config file.
-Key fields:
+Run `vaultik config init` to generate a fully commented config file; a
+complete annotated example also lives in
+[`config.example.yml`](config.example.yml). Key fields:
 
 | Field | Default | Description |
 |-------|---------|-------------|
 | `age_recipients` | (required) | Age public keys for encryption |
+| `age_secret_key` | (unset) | Age private key for decryption (`snapshot restore`, `snapshot verify --deep`). Setting it in the config file places the private key on the backed-up host, defeating the public-key-only design (see "why" above). Prefer the `VAULTIK_AGE_SECRET_KEY` environment variable, supplied only on the machine you restore from. |
 | `snapshots` | (required) | Named snapshot definitions with paths and excludes |
 | `storage_url` | | Storage backend URL (`s3://`, `file://`, `rclone://`) |
 | `s3.*` | | Legacy S3 configuration (endpoint, bucket, credentials) |
@@ -600,9 +626,17 @@ priority.
 
 ## output style
 
-All user-facing output goes through helpers in `internal/ui` and conforms
-to a uniform style. Color is enabled when stdout is a TTY and the
-`NO_COLOR` environment variable is unset (https://no-color.org/).
+The operational narration of the long-running commands — the Begin,
+Complete, Progress, and status lines of `snapshot create`, `prune`,
+`snapshot restore`, and the like — goes through helpers in `internal/ui`
+and conforms to the uniform style below. Some commands instead write
+plain text straight to stdout (`version`, `info`, `config`, the
+`database delete` prompt, and the `snapshot list` table); that output is
+unstyled and does not honor `--quiet`. Routing it through `internal/ui`
+is tracked in
+[issue #149](https://git.eeqj.de/sneak/vaultik/issues/149). Color is
+enabled when stdout is a TTY and the `NO_COLOR` environment variable is
+unset (https://no-color.org/).
 
 `internal/ui` writes to stdout; it is the output the user asked for.
 Structured log records are a different thing and go through