plexdo 2.0.3__tar.gz → 3.0.0__tar.gz

{plexdo-2.0.3 → plexdo-3.0.0}/AI.prompt.txt

@@ -300,11 +300,21 @@ nothing to do with this version.
   the range its dependent declares. A vulnerability in a development-only
   npm dependency is fixed by upgrading the package that pulls it in. One
   that no consistent tree avoids is left, with the reason recorded here:
-  KaTeX's GHSA-238p-pmpm-9mq7 (low), reached through
-  `markdownlint -> micromark-extension-math`, whose `^0.16` range no patched
-  KaTeX release satisfies. markdownlint imports only that package's syntax
-  extension; its KaTeX renderer is loaded and never called, and plexdo
-  ships none of it.
+  - KaTeX's GHSA-238p-pmpm-9mq7 (low), reached through
+    `markdownlint -> micromark-extension-math`, whose `^0.16` range no
+    patched KaTeX release satisfies. markdownlint imports only that
+    package's syntax extension; its KaTeX renderer is loaded and never
+    called, and plexdo ships none of it.
+  - re2js's GHSA-gg6h-894w-4m9c (high), quadratic time matching a
+    lookbehind, fixed in 2.8.7. markdownlint-cli2 0.24.0 pins markdownlint
+    0.42.0, which pins re2js 2.8.6 exactly; markdownlint 0.42.1 moves to
+    2.9.1, so the fix arrives with the markdownlint-cli2 release that takes
+    it up, and is not forced in early. markdownlint's own patterns (MD011,
+    MD013, MD039, and the default front-matter pattern) have no lookbehind,
+    `.markdownlint-cli2.yaml` adds no custom rule or pattern, and the only
+    input is this repository's own Markdown, so the slow path is not
+    reached. Check for that markdownlint-cli2 release before each commit,
+    and drop this entry once it is taken.
 - A linter suppression covers one line and one rule, with a comment saying
   why the code cannot change instead.
 - One Google rule is knowingly not followed: its guide imports modules, not
@@ -378,14 +388,18 @@ src/plexdo/
     __main__.py     python -m plexdo
     cli.py          build_parser, main
     constants.py    windows_app_dir, default_paths, Paths, PATHS, CONFIG_PATH,
-                    DEFAULT_CACHE_DIR, DEFAULT_SECRETS_FILE, STORE_CHOICES,
-                    config_text, CONFIG_EXAMPLE, LOG
-    logs.py         configure_logging
+                    DEFAULT_CACHE_DIR, DEFAULT_SECRETS_FILE, session_file,
+                    DEFAULT_SESSION_FILE, STORE_CHOICES, config_text,
+                    CONFIG_EXAMPLE, SECRETS_EXAMPLE, LOG
+    logs.py         configure_logging, open_debug_log, RedactingFormatter,
+                    TimestampedFormatter
+    profiling.py    profiled, span, usage, Run, Usage
     config.py       load_config, parse_config, cached_config, config_optional,
                     user_option, configured_users, expand_environment,
                     check_file_permissions, Config
-    secret_store.py backend, open_store, load, save, describe, KeyringStore,
-                    FileStore, Store
+    secret_store.py backend, session_backend, sessions_are_apart,
+                    open_store, load, save, describe, KeyringStore,
+                    FileStore, SessionStore, Store
     tokens.py       load_store, lookup, store_token, admin_token,
                     forget_tokens, saved_password, save_password,
                     forget_logins, saved_pin, save_pin
@@ -394,7 +408,7 @@ src/plexdo/
     arguments.py    add_user_argument, add_library_argument,
                     add_m3u_argument, add_overwrite_argument,
                     add_rating_keys_argument, add_rating_key_option
-    cache.py        cache_dir, write_cache
+    cache.py        cache_dir, write_cache, cache_key, write_word_caches
     convert.py      parse_date, format_duration
     console.py      output, output_format, clean_text, table_limit,
                     print_table, print_metadata, stream_record,
@@ -402,22 +416,24 @@ src/plexdo/
     formats.py      to_json, to_yaml, to_csv, to_clixml, render
     records.py      loaded_fields, file_paths, release_date, summary_row,
                     cache_row, season_records
-    identify.py     resolve_identifier
+    identify.py     resolve_identifier, remember_words, argument_words
     accounts.py     server_for_user, account_type, resolve_user_arguments,
-                    user_roster, UserAccessError, connect_with_token,
+                    user_roster, user_rows, UserAccessError,
+                    connect_with_token,
                     connect_as_shared_user, configured_entries,
                     configured_account, configured_accounts
     sections.py     resolve_section, resolve_sections,
                     resolve_library_arguments
     titles.py       display_title, find_item, fetch_item, fetch_show,
                     non_special_episodes, shuffle_list, item_is_played,
-                    item_view_offset
+                    item_view_offset, as_rating_key
     playlists.py    resolve_playlist, finalize_playlist, copy_playlist_to,
                     existing_playlist, preview_rows, require_items,
                     create_for_user
     fanout.py       add_user_target_arguments, deliver_playlist, run_per_user,
                     report_line
-    photos.py       collect_photos, collect_library_items, photo_file_path
+    photos.py       walk_photo_albums, AlbumVisit, is_album, album_children,
+                    collect_photos, collect_library_items, photo_file_path
     sorting.py      apply_sort
     m3u.py          write_m3u
     gallery.py      write_gallery_html
@@ -426,7 +442,8 @@ src/plexdo/
     throttle.py     paced, throttle_delay
     playback.py     fetch_address, parse_ip, url_host, url_of, play_fields,
                     add_play_arguments, Candidate, IPAddress
-    security.py     scrub_password_argument
+    security.py     scrub_password_argument, redact, redact_headers,
+                    hide_in_logs, hide_request_secrets
     data/           the four completions and the man page, as package data
     commands/       one module per group (see COMMANDS)
 ```
@@ -445,14 +462,14 @@ Every module in `commands/` exposes exactly three names:
   every `add_parser` call so each inherits the global flags.
 - `COMMANDS` maps command name to handler.
 - `REQUIRES_PLEX` is the subset needing a server; `auth` has an empty
-  frozenset because `login` and `write-config-example` run before a token
-  exists, `logout` must work once the server no longer accepts one, and
-  `set-pin` only touches the secret store.
+  frozenset because `login` and the two `write-*-example` commands run
+  before a token exists, `logout` must work once the server no longer
+  accepts one, and `set-pin` only touches the secret store.
 
-`commands/__init__.py` holds a `MODULES` tuple whose order sets the order of
-subcommands in `--help`, plus `register_all(sub, parents)` and
-`build_registry()`. Adding a command means adding a module and listing it;
-`cli.py` never changes.
+`commands/__init__.py` holds a `MODULES` tuple, `register_all(sub, parents)`,
+`build_registry()`, and `GROUPS`, which is what `--help` lists the commands
+from (see COMMAND NAMES AND HELP). Adding a command means adding a module,
+listing it, and naming the command in one group; `cli.py` never changes.
 
 ## PLATFORM DEFAULTS
 
@@ -550,6 +567,37 @@ removes its entry.
 - `secret_store.backend()` is chosen once per run and works before the
   config exists, with the defaults, since the migration saves secrets
   before writing the file.
+- **With `secret_store: file` set outright, sessions are kept apart from
+  passwords.** `SESSION_KINDS` is `("tokens",)`; `session_backend()` is the
+  store for those kinds and `backend()` the store for the rest, and
+  `load`, `save`, and `describe(kind)` pick between them. Under `auto` and
+  `keyring` the two are the same store, a file `auto` fell back to
+  included. Under `file` the secrets file holds `passwords` and `pins`
+  alone, and the tokens go in a `SessionStore`, a `FileStore` at
+  `constants.DEFAULT_SESSION_FILE`: `$XDG_RUNTIME_DIR/plexdo/session.json`
+  when that variable is an absolute path, else `plexdo-UID/session.json`
+  under `tempfile.gettempdir()`, which honours `TMPDIR`, `TEMP`, and `TMP`
+  (`PlexDo/session.json` there on Windows). `session_file(is_windows, env,
+  tmpdir, uid)` takes all four as arguments so every case is testable.
+  The reasoning: that setting is for a machine with no keyring to unlock,
+  where the secrets file is all that guards a saved password, and a token,
+  which changes with every login and which plex.tv can reissue, does not
+  belong beside it or need to outlive a reboot.
+- The temporary directory is writable by other accounts, so the session
+  directory is created with mode 0700 and then checked with `lstat`: it
+  must be a real directory, not a link, owned by the user. One of the
+  user's own that is open to group or other is tightened. Otherwise
+  writing is a `sys.exit` and nothing is written, and a session file
+  found there is ignored with a warning rather than believed. Windows has
+  neither check; its temporary directory is inside the user's profile.
+- The first time the session store is opened, a `tokens` entry still in
+  the secrets file, where it was kept before, is moved to the session
+  file, a token already there winning, with a warning saying so. An
+  upgrade must not sign anyone out.
+- `login` prints one note on **stderr**, in every format, when the two
+  stores differ: where sessions are kept, that they are apart from the
+  passwords and PINs, and that a session lasts until that file is cleared,
+  as at a reboot, when `plexdo login` is needed again.
 
 `tokens.py` is the only module that knows the three kinds.
 
@@ -582,7 +630,7 @@ that finds its account early signs in no more. When all three fail, raise
 `UserAccessError` explaining that admin rights do not override per-user
 scoping and that a `users` entry signed in once with `login --username`
 would fix it. It must be an ordinary `Exception`, **not** a `sys.exit`:
-`copy-playlist-all-users` catches per-user failures and continues, and
+`playlist-copy --all` catches per-user failures and continues, and
 `SystemExit` would tear down the whole run. `cli.main` converts it to a
 clean exit for single-user commands. It carries a one-line `summary` so a
 loop reports each skip in one line.
@@ -639,9 +687,9 @@ present.
 
 ## GLOBAL FLAGS
 
-`-f/--format`, `--json`, `-v/--verbose`, `--debug`, `--dry-run`, `-W/--wide`,
-`--throttle`, `-V/--version`. They must work **either before or after the
-command name**.
+`-f/--format`, `--json`, `-v/--verbose`, `--debug`, `--debug-log PATH`,
+`--dry-run`, `-W/--wide`, `--throttle`, `-V/--version`. They must work
+**either before or after the command name**.
 
 Implement with `_add_global_flags(parser, suppress=False)` called twice: once
 on the top-level parser with ordinary defaults, and once on an
@@ -650,16 +698,92 @@ on the top-level parser with ordinary defaults, and once on an
 The SUPPRESS default is essential, not cosmetic. A subparser parses into its
 own namespace and then copies **every** attribute onto the main one, so
 ordinary defaults on the inherited copies would silently clobber a flag given
-before the subcommand: `plexdo --json list-users` would print a table.
+before the subcommand: `plexdo --json users-list` would print a table.
+
+Add them to an argument group titled `global options`, in order of their
+long names, on both parsers. argparse carries a parent's groups over by
+title, so every command's help lists them apart from its own options.
 
 `--format` writes to `dest="format"`; `--json` is a `store_const` alias
 writing to that same destination, so there is one attribute and no way for the
-two to disagree. All logging goes to stderr only.
+two to disagree. All logging goes to stderr only, or to the `--debug-log`
+file; never to stdout.
+
+### The debug log
+
+`--debug-log PATH` sends everything `--debug` would show to PATH instead,
+and stderr keeps the level it would have without `--debug`; `--debug` is
+not needed with it. `logs.open_debug_log` opens it with `os.open`,
+`O_APPEND | O_CREAT`, mode 0600, so a new file is its owner's alone and
+earlier runs are kept, and line buffered, so a killed run loses nothing it
+logged; a path that cannot be opened is a `sys.exit` naming it, before the
+command runs. Expand `~`.
+
+`TimestampedFormatter` starts **every line**, not every record, with
+`time.time_ns()` at the moment it is formatted, then `LEVEL logger:
+message`; a traceback or a cProfile table carries the stamp on each line.
+`LogRecord.created` is a float and cannot hold nanoseconds at today's epoch,
+so it is not used.
+
+`profiling.profiled(enabled, command)` is the context `cli.main` runs the
+command in, after `scrub_password_argument` so no `--password` reaches the
+run start line: a `profiling.Run` with `--debug-log`, `nullcontext()`
+without. `profiling.span(name)` times one phase - `migrate`, `connect`,
+`resolve-arguments`, `command:NAME` - and is a no-op with no Run active.
+The Run writes, as `key=value` pairs so the file is as easy to grep as to
+read:
+- `plexdo.profile: run start` - plexdo, Python, plexapi, and requests
+  versions, platform, pid, command, `json.dumps(sys.argv)`;
+- `span` lines - wall, CPU, user and system time, `cpu_percent`, memory,
+  and the HTTP calls and wait inside the span;
+- `plexdo.http: send` / `recv` / `fail` - Run replaces
+  `requests.Session.send` for the run and restores it after, so every
+  session, plexapi's included, is seen. `send` has an id, method, URL,
+  body size, and headers; `recv` the status, reason, `wait_ns` (send to
+  whole response, by `perf_counter_ns`), `headers_ns` (requests'
+  `elapsed`), body size and type, and headers; `fail` the error, before
+  re-raising. Never read the body of a `stream=True` response, which would
+  consume what `read` streams: give its Content-Length. A redirect comes
+  back through `send`; a thread-local depth keeps the nested hops out of
+  the totals, so no wait counts twice;
+- `resources` every `SAMPLE_SECONDS` (5) from a daemon thread, over the
+  interval since the last;
+- `run end` - status (`SystemExit` code, `interrupted`,
+  `exception:TYPE`), totals, the HTTP count, wait, its share of the run,
+  and the slowest request, then cProfile's top `TOP_FUNCTIONS` (40) by
+  cumulative and by own time. Python 3.12 allows one profiler at a time,
+  so `enable()` raising `ValueError` is logged and the run goes on
+  without the tables.
+CPU is `time.process_time_ns()` with `os.times()` for the user/system split.
+Memory without a dependency: current RSS from `/proc/self/statm` on Linux
+and `GetProcessMemoryInfo` through ctypes on Windows, the peak from
+`resource.getrusage` (`ru_maxrss`, KiB except bytes on macOS) or Windows;
+Linux updates the peak lazily, so report at least the current figure, and
+`None` where the platform gives nothing. psutil would be a dependency for
+one feature.
+
+Redaction is in `security`. Both handlers, stderr and file, use
+`RedactingFormatter`, which redacts the **whole formatted record**,
+traceback included, since urllib3 logs request lines with their query
+string and requests' exceptions quote URLs. `redact` replaces: the value of
+any `name=value`, `name: value`, or quoted-key pair whose name is a token,
+password, passwd, secret (as a suffix: `X-Plex-Token`, `authToken`), `pin`,
+`X-Plex-Pin`, `X-Plex-Code`, `verificationCode`, `Authorization`, or a
+cookie header, its scheme with it; the password in `scheme://user:pass@`;
+and every value `hide_in_logs` was given. That registry is fed by
+`secret_store.load` and `save`, the password prompt and
+`scrub_password_argument`, and `hide_request_secrets`, which `send` calls
+before the request goes out with the secret-named query parameters and
+headers, a Basic credential's decoded password included. Values under 8
+characters are not registered: a four-digit PIN would blank out every
+matching number; named, it is still redacted. Bodies are never logged,
+only their sizes. Name the registry what it is (`_KnownSecrets`), per the
+naming rule above.
 
 ## OUTPUT
 
 `output(data, args)` dispatches on `output_format(args)`, accepting **either**
-a single record or a list so `show-metadata` and `list-titles` share the path.
+a single record or a list so `show-metadata` and `library-list` share the path.
 No command reaches for `json.dumps` directly.
 
 ### Formats
@@ -721,11 +845,12 @@ no benefit. Announce once at info level with the expected duration and how to
 turn it off.
 
 Apply wherever a loop makes one request per element and the count can exceed
-50: the seasons walk in `list-titles`, `find-missing -A`, applying watched
-state in `copy-watched`, removing entries in `clean-playlist`, reading each
-source in `build-concatenated`, `collect_photos`, and the per-user loop in
-`fanout.run_per_user`, which serves `copy-playlist-all-users` and every build
-command given `-a`. Functions needing it take an optional `args`.
+50: the seasons walk in `library-list`, `missing-find -A`, applying watched
+state in `show-watched-cp`, removing entries in `playlist-clean`, reading each
+source in `merge-build`, `collect_photos`, the walk of a show library in
+`collect_library_items`, and the per-user loop in
+`fanout.run_per_user`, which serves `playlist-copy --all`, and
+`playlist-build` and `merge-build` given `-a`. Functions needing it take an optional `args`.
 
 ## RECORDS
 
@@ -768,12 +893,15 @@ content.
 
 Every argument naming an **existing** playlist accepts a title or a ratingKey
 through `resolve_playlist`; no command may call `plex.playlist(name)`
-directly. A numeric value that is no item at all is a clean `sys.exit`, not
+directly. What counts as a ratingKey is decided by `titles.as_rating_key`,
+**ASCII digits and nothing else**: `int()` is too generous a test, taking
+`1_000`, `+7`, ` 12 `, and digits of other scripts, any of which may be what
+a playlist is called. A numeric value that is no item at all is a clean `sys.exit`, not
 plexapi's `NotFound` escaping as a traceback: look it up with
 `titles.find_item`, which returns None, and `fetch_item` wraps that for every
 other fatal lookup, `fetch_show` included. Nothing calls `fetchItem` bare.
 
-Every build command constructs the list fully in memory, validates it is
+Every command that creates a playlist constructs the list fully in memory, validates it is
 non-empty, prints a numbered preview, and makes exactly one `createPlaylist`
 call. `finalize_playlist` enforces this and returns `"created"` or
 `"replaced"`.
@@ -799,32 +927,151 @@ Without `--overwrite`, a taken name falls back to appending `" admin copy"`;
 if that is taken too the target is skipped with a warning and nothing is
 touched.
 
+## COMMAND NAMES AND HELP
+
+A command is named `<object>-<action>`: what it acts on, then what it does
+to it (`playlist-list`, `playlist-export`, `libraries-list`). Plural objects
+list many (`playlists-list USER`), singular ones show one (`playlist-list
+USER PLAYLIST`). The exceptions are fixed names, kept exactly:
+`merge-build`, `show-watched-cp`, `missing-find`, `titles-export`, the
+single words (`search`, `read`, `rescan`, `status`, `wait`, `login`,
+`logout`), and `show-metadata`, `player-remote-play`, `set-pin`,
+`write-config-example`, and `write-secrets-example`. There are no aliases:
+one command, one name, so `COMMANDS` has exactly one entry per command.
+
+Releases up to 2.1.0-rc.1 named commands `<action>-<object>`. 3.0.0 renamed
+them, an incompatible change and so a MAJOR one, and also
+folded `build-interleaved`, `build-chronological`, `build-randomize`, and
+`append-playlist` into `playlist-build`, and `copy-playlist-all-users` and
+`copy-playlist-to-user` into `playlist-copy`, and removed
+`build-concatenated` and `list-titles` (whose alias `list-library` became
+`library-list`). None of the old names is accepted.
+
+`plexdo --help` lists the commands under five headings, in this order, and
+sorted by name within each. `commands.GROUPS` is that list, and every
+command must be in exactly one group (a test holds it to the registry):
+
+| Group | Commands |
+| --- | --- |
+| libraries and titles | `album-list`, `albums-list`, `libraries-list`, `library-list`, `missing-find`, `search`, `show-list`, `show-metadata`, `titles-export` |
+| playlists | `merge-build`, `playlist-build`, `playlist-clean`, `playlist-copy`, `playlist-export`, `playlist-list`, `playlist-remove`, `playlists-list` |
+| playback and watched state | `player-remote-play`, `read`, `show-watched-cp`, `wait` |
+| server | `rescan`, `status`, `users-list` |
+| account and configuration | `login`, `logout`, `set-pin`, `write-config-example`, `write-secrets-example` |
+
+argparse can only print subcommands as one flat list in registration order,
+so pass `help=argparse.SUPPRESS` to `add_subparsers` and build the grouped
+list into the parser's description, with `RawDescriptionHelpFormatter`:
+the name padded to the longest, then the summary each `add_parser(help=...)`
+gave, wrapped to 79 columns with a hanging indent. Give `add_subparsers`
+`prog="plexdo"` and the parser `usage="%(prog)s [global options] <command>
+[arguments]"`; without the first, every command's usage line repeats the
+top-level usage. Summaries are one sentence, in the imperative, short
+enough to fit their line. Positional metavars are upper case (`USER`,
+`LIBRARY`, `PLAYLIST`, `NAME`, `QUERY`, `PATH`) except `ratingKey`, which is
+spelled as Plex spells it.
+
+After registration, `cli._tidy_command_help` goes over every command: it
+sorts the `global options` group last, since a parent's groups otherwise
+come before the groups a command adds, and, where a command set no `usage`
+of its own, formats one from the command's own actions and appends
+`[global options]`, so nine inherited flags do not bury the two that
+matter. Both reach into argparse's protected attributes, which has no
+public way to do either; keep that in the one function.
+
+`playlist-build` and `playlist-copy` take a flag that decides what their
+positional arguments mean, which argparse cannot express. They collect the
+positionals unnamed, set `check_arguments` with `set_defaults` to a
+callable taking the namespace, and `cli.parse_arguments(parser, argv)`,
+which `main` uses in place of `parse_args`, runs it: the callable names the
+arguments for the mode (`args.user_id`, `args.name`, `args.rating_keys`,
+...) or calls `parser.error`, exit 2. That happens before anything connects
+and before user titles are resolved, so `resolve_user_arguments` finds
+`user_id` where it expects it. Each has a hand-written multi-line `usage`
+and a description saying what each mode takes.
+
 ## COMMANDS
 
 ### Listing and searching
 
-- `list-libraries` - columns `id`, `type`, `title`; writes the libraries cache.
-- `list-titles LIBRARY [--album A]` - registered with
-  `aliases=["list-library"]`. argparse reports whichever spelling was typed,
-  so `COMMANDS` needs an entry for both, giving 30 registry entries for 29
-  commands; the smoke test floor must allow for it. Table columns are
+- `libraries-list` - columns `id`, `type`, `title`; writes the libraries cache.
+- `library-list LIBRARY [--album A]` - table columns are
   `ratingKey`, `title`, `releaseDate`, `rating`, `studio`; a machine-readable
   format carries every listed field and, for a show library, nests each show's
   episodes under a `seasons` object keyed by season name. Always cache the
   minimal `ratingKey`/`title` rows whatever the caller asked to see.
-- `list-show RATINGKEY [--m3u P] [-p PREFIX]` - fails fast if not a `Show`.
-- `list-users` - `id`, `type`, `title`, `username`, `email`. `account_type`
+- `albums-list LIBRARY` (`commands/albums.py`) - the albums of a music
+  (section type `artist`) or photo library; any other type exits 1. Music
+  albums come from `section.albums()`. A photo library is walked depth
+  first from `section.all()`, opening each album with one
+  `fetchItems(f"{album.key}/children")` and splitting the children by
+  `TAG == "Directory"` into nested albums, walked next so they follow their
+  parent, and contents; a ratingKey met twice is listed once. Table
+  columns are `ratingKey`, `artist` (music only), `title`, `year`, `items`,
+  `played`; a music table reads `leafCount`/`viewedLeafCount` from the
+  listing and opens no album. Every other format, and every photo listing,
+  opens each album through `paced`. A machine-readable record carries
+  `ratingKey`, `artist`, `title`, `year`, `items`, `duration`, `state`,
+  `played`, `playedItems`, `inProgressItems`, `lastViewedAt`, `progress`,
+  and `contents`; each content record `index`, `ratingKey`, `type`, `disc`,
+  `track`, `title`, `artist`, `duration`, `state`, `played`, `viewCount`,
+  `lastViewedAt`, `viewOffset`, `progress`, `files`. Every key is always
+  present, null where it does not apply. Fields are read from `vars()`, so
+  nothing reloads. An item has a state only if it carries `viewCount`
+  (tracks and clips; photos do not): `in progress` when `viewOffset > 0`,
+  even if played before, else `played` when `viewCount > 0`, else
+  `unplayed`. An album is `in progress` if any item is, `played` if every
+  playable item is, `unplayed` if none is, else `in progress`; null with no
+  playable item. `progress` is a percentage to one decimal, null unless the
+  state is `in progress`: an item's resume point over its duration; an
+  album's played running time (played items in full, items in progress up
+  to their resume point) over the total of its playable items. `viewOffset`
+  is likewise null unless in progress.
+- `album-list RATINGKEY` (also `commands/albums.py`) - one album, by
+  `fetch_item` and one `/children` fetch. Refused with exit 1 unless the
+  item is a Directory whose `type` is `album` (music) or `photo` (a photo
+  album; a photo shares the type but not the TAG), since shows, seasons,
+  and artists are Directories too. Nested photo albums are split off,
+  logged at INFO, and counted in the table summary as `nested albums`, not
+  listed. JSON and YAML output the same `album_record` as `albums-list`;
+  CSV and CLIXML output its `contents` alone. A table prints the album as a
+  metadata block with only the keys that apply (`ratingKey`, `artist`,
+  `title`, `year`, `items`, `nested albums`, `length`, `state`, `played` as
+  "N of M", `in progress`, `progress` as "P%", `last played`), a blank
+  line, then one row per item: `#`, `ratingKey`, `track` (as `2-03` when
+  the album spans several discs; music only), `title`, `artist` (only when
+  some track's artist differs from the album's), `length`, then, unless the
+  album holds photos alone, `state`, `progress` ("3:20 / 9:46 (34.1%)" for
+  an item in progress, else empty), and `last played` as a date.
+- `show-list RATINGKEY [--m3u P] [-p PREFIX]` - fails fast if not a `Show`.
+- `users-list` - `id`, `type`, `title`, `username`, `email`, from
+  `accounts.user_rows`, which the `users` section of `status` shows too, so
+  the two cannot come to differ; the command once printed three of the
+  five while its documentation promised all of them. `account_type`
   returns managed/home/friend/shared. plexapi exposes `restricted` as the raw
   XML **string**, so `"0"` is truthy and a naive check labels every account
   managed.
-- `list-playlists USER`, `list-playlist USER PLAYLIST [--m3u P] [-p PREFIX]`.
+- `playlists-list USER`, `playlist-list USER PLAYLIST [--m3u P] [-p PREFIX]`.
 - `show-metadata RATINGKEY` - type-specific builders via `_METADATA_BUILDERS`
   keyed on `item.type`, plus the file paths. A table names a lone file `file`
   and numbers several `file 1`, `file 2`; other formats carry a `files` list.
-- `search USER QUERY [--media-type T] [--library-id L]` - per-library failures
-  log a warning and continue.
-- `find-missing SHOW [-l LIBRARY] [-A] [-s SEASONS] [--include-specials]` -
-  names one show by default, resolved through `resolve_identifier`. `-A`
+- `search USER QUERY [--media-type T] [--library-id L]` - with
+  `--media-type`, search only the libraries whose section type can hold it
+  (`episode` in `show`, `track` and `album` in `artist`): asked for a type
+  it cannot hold, plexapi raises "Unknown libtype", once per library. A
+  library named with `--library-id` that cannot hold the type is a
+  `sys.exit`. A library whose search raises is skipped, logged at DEBUG,
+  and the rest are searched; the failures are reported, as **one** warning
+  starting `Search failed in`, **only when no result came back at all**.
+  With results in hand a library that could not be searched is noise.
+- `missing-find SHOW [-l LIBRARY] [-A] [-s SEASONS] [--include-specials]` -
+  names one show by default, resolved through `resolve_identifier`. A SHOW
+  written as a ratingKey is fetched outright first, and used if it is a
+  show: listing every show of every library to look up a number was the
+  slow part. One `section.search(title=..., libtype="show")` per show
+  library is still made, to give the usual warning when another show is
+  *titled* that number ("24", "1923"). A number that is no show's key falls
+  through to the roster, where it may be a title. `-A`
   sweeps every show and refuses a SHOW argument; `-s` takes one number or a
   comma list and applies only to a single show. For each season the run starts
   at 0 when an episode 0 exists and otherwise at 1, ending at the highest
@@ -837,41 +1084,81 @@ touched.
 
 ### Building and copying
 
-- `build-interleaved NAME RATINGKEY...` - round-robin across shows.
-- `build-chronological NAME RATINGKEY...` - sorted by air date. A missing date
-  is estimated from neighbours in the same season: collect up to 6 either
-  side, require at least 3 known dates (so at least 2 intervals), take the
-  median interval, estimate from latest-previous `+median` and earliest-next
-  `-median`, averaging when both exist, and prompt only when that is
-  impossible. A film with no date has no neighbours, so it is prompted for
-  directly. `prompt_for_date` takes **any** item: name an episode by show,
-  season, and episode, with `??` for a number Plex lacks rather than `00`,
-  which would read as a real episode 0, and anything else by title and year.
-  It once read episode-only attributes and crashed on every undated film.
-  Running out of input is a `sys.exit` naming the item, not an `EOFError`.
-- `build-randomize USER SOURCE DEST` - Fisher-Yates via `secrets.randbelow`.
-- `build-concatenated USER NAME PLAYLIST... [--unique]` - joins the sources
-  end to end, keeping the order within each and the order they were named in.
-  Read **every** source before writing anything, so naming a source as the
-  destination works under `--overwrite`: the items are already in memory when
-  the old playlist goes. Duplicates are kept by default - a concatenation is
-  faithful, and Plex permits a repeat - while `--unique` keeps only an item's
-  first appearance, matched on ratingKey rather than title, and reports how
-  many it skipped. Warn about an empty source rather than passing over it: a
-  typo that resolved to the wrong playlist looks exactly like a playlist that
-  happens to be empty.
-- `copy-playlist-all-users USER PLAYLIST` - skips the source user, prints the
-  item list **once** before the loop and passes `preview=False` thereafter,
-  then one line per user (`created`, `replaced`, `skipped`, `failed`) printed
-  as it completes. Because the caller surfaces the skip reason, the message
-  inside `copy_playlist_to` is `LOG.info`, not a warning that would duplicate
-  every skip on stderr.
-- `copy-playlist-to-user USER PLAYLIST USER DEST` - a table shows the item
-  list then the outcome line; a machine-readable format shows the outcome
-  record **alone**, as `copy-playlist-all-users` does, because two documents
-  on one stream parse as neither.
-- `append-playlist USER PLAYLIST RATINGKEY...`, `remove-playlist USER PLAYLIST`.
-- `clean-playlist USER PLAYLIST [--include-partial]` - removes the watched
+- `playlist-build (-I | -C) NAME RATINGKEY...`,
+  `playlist-build -R USER SOURCE DEST`,
+  `playlist-build -A USER PLAYLIST RATINGKEY...` - one command, four modes,
+  as a required mutually exclusive group of `store_const` flags writing
+  `dest="mode"`. The positionals are `first` and `rest` (`nargs="+"`), both
+  shown as `ARG`, so that an option between the first argument and the
+  others still parses; `_check_build` names them for the mode. The wrong
+  count for the mode, or a ratingKey that is not an integer, is a usage
+  error, exit 2, as is `-A` with any of `-o`, `-u`, `-a`, `--m3u`, and
+  `-p`, which only make sense for a playlist being created. With too few
+  arguments for `first` and `rest` at all, argparse reports only "the
+  following arguments are required: ARG", before any flag is looked at;
+  the parser's `error` is wrapped to say instead what each mode takes,
+  naming together the modes that take the same ("-I and -C take ..."). `-A` is
+  `--append`; `-a` stays `--all-users`.
+  - `-I/--interleaved` - round-robin across shows.
+  - `-C/--chronological` - sorted by air date. A missing date
+    is estimated from neighbours in the same season: collect up to 6 either
+    side, require at least 3 known dates (so at least 2 intervals), take the
+    median interval, estimate from latest-previous `+median` and
+    earliest-next `-median`, averaging when both exist, and prompt only when
+    that is impossible. A film with no date has no neighbours, so it is
+    prompted for directly. `prompt_for_date` takes **any** item: name an
+    episode by show, season, and episode, with `??` for a number Plex lacks
+    rather than `00`, which would read as a real episode 0, and anything
+    else by title and year. It once read episode-only attributes and crashed
+    on every undated film. Running out of input is a `sys.exit` naming the
+    item, not an `EOFError`.
+  - `-R/--randomize` - Fisher-Yates via `secrets.randbelow`.
+  - `-A/--append` - fetches every ratingKey as the user sees the server,
+    exits 1 if any is not found, previews, then adds them in one call.
+    Refuse a smart playlist before fetching anything, as `playlist-clean`
+    does: plexapi raises `BadRequest` from `addItems`, which is also
+    caught there and turned into a `sys.exit`.
+- `merge-build USER NAME FIRST SECOND [--ratio A:B] [-s] [-U]` - mixes two
+  playlists in turn, A items from FIRST then B from SECOND, default 1:1,
+  each keeping its own order. Parse the ratio in argparse (`type=`), so a
+  bad one is a usage error, exit 2: two ASCII whole numbers above 0 joined
+  by `:`. A side has run out on the first turn it has nothing to give; a
+  turn cut short because fewer items were left still counts. From that turn
+  the rest of the other follows by default, rather than being dropped, and
+  `--verbose` reports how many items follow unmixed; `-s/--stop-short`
+  leaves them out instead, the turn included, and reports how many. Sizes
+  that match the ratio run out together, with no tail, so `-s` changes
+  nothing. Repeats are kept; `-U/--unique` passes over an item already
+  taken, by ratingKey, and the next item of the same side takes its place,
+  so the ratio holds, and under `-s` a side left with only repeats has run
+  out. `-U`, not `-u`: `-u` is `--user`, as on `playlist-build`. Read both
+  sources before writing anything, so either may be the destination under
+  `--overwrite`: the items are already in memory when the old playlist
+  goes. Warn about an empty side rather than passing over it: a typo that
+  resolved to the wrong playlist looks exactly like a playlist that happens
+  to be empty.
+- `playlist-copy -A USER PLAYLIST [-o]`,
+  `playlist-copy -T USER PLAYLIST TO_USER DEST [-o]` - one command, two
+  modes, as a required mutually exclusive group writing `dest="copy_to"`.
+  The positionals are `source_user_id`, `source_playlist`, and `target`
+  (`nargs="*"`); `_check_copy` requires none for `-A` and exactly two for
+  `-T`, naming them `user_id` and `dest`, and anything else is a usage
+  error, exit 2.
+  - `-A/--all` - skips the source user, prints the
+    item list **once** before the loop and passes `preview=False`
+    thereafter, then one line per user (`created`, `replaced`, `skipped`,
+    `failed`) printed as it completes. Because the caller surfaces the skip
+    reason, the message inside `copy_playlist_to` is `LOG.info`, not a
+    warning that would duplicate every skip on stderr.
+  - `-T/--to` - a table shows the item list then the outcome line; a
+    machine-readable format shows the outcome record **alone**, as `-A`
+    does, because two documents on one stream parse as neither.
+- `playlist-remove USER PLAYLIST` - names the playlist by its title in what
+  it prints, however it was given. `--dry-run` says on stderr which
+  playlist would be deleted, by title and ratingKey: a rehearsal that
+  prints nothing cannot be told from one that found nothing to do, and
+  every `--dry-run` must say what it would have done without `--verbose`.
+- `playlist-clean USER PLAYLIST [--include-partial]` - removes the watched
   entries and leaves the rest in their existing order. Preview first, then one
   `removeItems` call per entry so the loop is paced like any other per-item
   loop; the playlist item IDs come from the listing plexapi already holds, so
@@ -880,26 +1167,29 @@ touched.
   the removal list, so it lines up with what Plex shows. A part-played item is
   **kept** by default - it is the one being watched right now, not a watched
   one - and `--include-partial` drops it, labelled `partial` rather than
-  `played`. Refuse a smart playlist: its contents come from a filter, and Plex
+  `played`. **The resume point is looked at first**: an item played before
+  and part way through again has a view count and a resume point, and it is
+  the second that says the user is in the middle of it. Refuse a smart playlist: its contents come from a filter, and Plex
   answers a delete on one of its entries with a 400. Warn when every entry is
   going, since Plex drops a playlist that loses its last item.
 
 #### Who a built playlist is for
 
-All four build commands take `-u/--user` and `-a/--all-users`, registered
-through `fanout.add_user_target_arguments` as a mutually exclusive group -
-writing the pair out on each parser is what trips `duplicate-code`. Without
-either, the playlist goes where it always did: the account the items came
-from, which is the admin server for the two that take rating keys and the
-source user's server for the two that take playlists. `deliver_playlist` takes
-both servers for exactly that reason. `-a` targets `accounts.user_roster`,
-which **includes the admin** at id 0, because the admin is a user of the
-server too.
+`playlist-build`, except under `-A`, and `merge-build` take `-u/--user` and
+`-a/--all-users`, registered through `fanout.add_user_target_arguments` as a
+mutually exclusive group - writing the pair out on each parser is what trips
+`duplicate-code`. Without either, the playlist goes to the account the items
+came from, which is the admin server for `-I` and `-C`, which take rating
+keys, and the source user's server for `-R` and `merge-build`, which take
+playlists. `deliver_playlist`
+takes both servers for exactly that reason. `-a` targets
+`accounts.user_roster`, which **includes the admin** at id 0, because the
+admin is a user of the server too.
 
 `fanout.run_per_user` holds the loop: print the item list once, then run a
 per-user action and print its one-line outcome as it completes, so a long run
 shows progress; in a machine-readable format emit one record per user instead,
-since one document cannot carry both. `copy-playlist-all-users` uses the same
+since one document cannot carry both. `playlist-copy --all` uses the same
 loop with its own action and its own target list - the accounts a playlist is
 shared with rather than the roster - so the loop is not written twice.
 
@@ -911,7 +1201,7 @@ others left.
 
 ### Watched state
 
-`copy-watched USER USER [-1] [-l LIBRARY] [-t KEY] [--unwatch]`.
+`show-watched-cp USER USER [-1] [-l LIBRARY] [-t KEY] [--unwatch]`.
 `_select_winner(first, second, unwatch)` returns `(winner, loser)` or None:
 
 | situation | default | `--unwatch` |
@@ -924,13 +1214,38 @@ A `lastViewedAt` of `None` must never win: map it to `datetime.min` when the
 latest wins and `datetime.max` when the earliest does. Plex rewrites
 `viewOffset` continuously during playback, so treat offsets within
 `_OFFSET_TOLERANCE_MS` (10s) as identical, or every run reports spurious
-changes. Two fully played states need no sync at all.
+changes.
+
+A state is two things, **the played flag and the resume point, and both are
+copied as they stand**; the view count is used only to tell played from
+not, and is never copied. So two states match when the flags are equal and
+the offsets are within tolerance, whether or not the item is played: an item
+played before and part way through again differs from one simply played.
+Two fully played states with no resume point need no sync at all.
+
+`_planned_steps(winner, loser)` gives the calls that bring the loser to the
+winner's state, and the plan's `action` is those steps joined by `+`:
+`markPlayed` or `markUnplayed` when the flags differ; else `clearProgress`
+when the winner has no resume point and the loser has one; then
+`setProgress` when the winner has one. Marking played or unplayed clears
+the resume point on the server, so it comes **before** `updateProgress`,
+and `clearProgress` is done by marking the item what it already is. It was
+once applied only when the loser was fully played, so `--unwatch` planned
+`markUnplayed` for an item one user was part way through, called nothing,
+and reported the same change on every run.
+
+`-t KEY` names what to compare. A movie, episode, track, or clip is
+compared by itself. A show or season stands for its `episodes()`, an artist
+or album for its `tracks()`, each member compared on its own: a
+container's own played flag only says whether **every** member is played,
+so comparing containers found two users at different points in a show
+identical. Any other type is a `sys.exit` saying it has no watched state.
 
 plexapi renamed these methods, so call through a helper trying both spellings
 (`markPlayed`/`markWatched`, `markUnplayed`/`markUnwatched`) and read played
 state from `isPlayed`, then `isWatched`, then `viewCount`. That read and the
 resume-point read are `titles.item_is_played` and `titles.item_view_offset`,
-because `clean-playlist` needs the same two and the rules must not be written
+because `playlist-clean` needs the same two and the rules must not be written
 twice. All three attributes default to a bool or a number rather than None, so
 reading them does not satisfy plexapi's reload condition.
 
@@ -940,13 +1255,18 @@ Watch state lives on leaf items: map `movie`->`movie`, `show`->`episode`,
 
 ### Exporting
 
-- `export-playlist USER PLAYLIST PATH`, `export-titles LIBRARY PATH
+- `playlist-export` and `playlist-list --m3u` are two ways to the same
+  file, kept on purpose; both write through the one
+  `commands.playlists._export_m3u`, so neither can write it differently.
+- `playlist-export USER PLAYLIST PATH`, `titles-export LIBRARY PATH
   [--sort alpha|date|random] [--album A]`.
 - M3U carries Plex server filesystem paths, `#EXTINF` seconds from
   `duration`/1000 with `-1` fallback, and skips items with no path.
 - Photo libraries export a self-contained Spotlight.js gallery. **No Plex HTTP
   URLs anywhere in it**: both `href` and `src` are server filesystem paths.
-- `-p/--prefix` on all eight export commands, registered through
+- `-p/--prefix` on every command that exports (`playlist-list`, `show-list`,
+  `playlist-export`, `titles-export`, `playlist-build`, `merge-build`),
+  registered through
   `paths.add_prefix_argument` - repeating the help text inline trips
   `duplicate-code`. `mapper_for(plex, args)` returns `identity` without a
   prefix, so the default costs no extra call. The prefix replaces the
@@ -957,24 +1277,57 @@ Watch state lives on leaf items: map `movie`->`movie`, `show`->`episode`,
 
 ### Photos
 
-`collect_photos` walks `section.all()` (albums) then `palbum.photos()`.
+`photos.walk_photo_albums(section, args)` is the one walk of a photo
+library, used by `albums-list`, `library-list`, and `titles-export`. It
+starts from `section.all()` and opens each album with one
+`fetchItems(f"{album.key}/children")`, splitting the children by
+`TAG == "Directory"` into nested albums, walked next so they follow their
+parent, and contents. It returns an `AlbumVisit` per album: the album, its
+contents, and the titles of the albums around it ending with its own. The
+photos of an album inside another are in neither the library listing nor
+the outer album's own children, so a walk that stops at the top level
+loses them, as `collect_photos` once did.
+
+Two guards, both needed. A ratingKey met twice is passed over: that lists
+once an album the server shows at the top level as well as nested, and
+stops albums that contain one another from being walked for ever. And
+nesting is followed `MAX_ALBUM_DEPTH` (16) albums deep, since a loop check
+cannot stop a server that keeps producing new albums; what lies deeper is
+left out with **one** warning naming where the walk stopped.
+
+`collect_photos` takes the `type == "photo"` contents of each visit,
+leaving clips out. `--album` matches a title, ignoring case, against every
+title in the visit's path, so naming an album takes the albums inside it
+too, and an album nested anywhere can be named. A name matching no album
+is a `sys.exit`; an album that exists and is empty is not.
 **Never** `section.search(libtype="photo")`: Plex requires a non-empty query
 string and returns nothing for an empty one, so the library appears empty.
 
 ### Streaming and server management
 
-- `read LIBRARY RATINGKEY` - streams to `sys.stdout.buffer` in 64KB chunks via
-  `requests.get(stream=True)`. Validate the item's `librarySectionID` matches.
+- `read RATINGKEY` - streams to `sys.stdout.buffer` in 64KB chunks via
+  `requests.get(stream=True)`. It takes no library: a ratingKey is unique
+  on the server, and an argument that only existed to be checked against
+  the item was one more thing to look up and type.
   Catch `BrokenPipeError` silently and `os.dup2` the null device onto stdout,
   so the interpreter's final flush does not print "BrokenPipeError ignored"
   when the user quits the player. The epilog shows worked examples including
-  `plexdo read 3 12345 | mpv --vo=drm -` for **Linux with a display attached
+  `plexdo read 12345 | mpv --vo=drm -` for **Linux with a display attached
   but no desktop environment** - describe the condition, not the machine:
   "headless" contradicts having a screen, and the hardware could be a Pi, a
   kiosk, a sign, or an old laptop.
-- `rescan [LIBRARY] [-s] [-n]` - `plex.activities` is a **property**, not a
-  method. `section.update()` scans for files; `refresh()` only re-fetches
-  metadata.
+- `rescan LIBRARY [-n]`, `rescan -a [-n]`, `rescan -s` - `plex.activities`
+  is a **property**, not a method. `section.update()` scans for files;
+  `refresh()` only re-fetches metadata. `-a/--all` scans every library with
+  the one `plex.library.update()` call. Exactly one of LIBRARY and `-a` is
+  required without `-s`, checked by a `check_arguments` hook so it is a
+  usage error, exit 2, before anything connects: with neither, the message
+  says to name a library **or use `--all` to rescan every library**, so a
+  library left off by mistake does not set the whole server scanning.
+  `--dry-run` says on stderr what would be scanned, and whether pending
+  scans would be cancelled first. `-s` with no activity prints
+  `No active scan jobs.` on stderr as a table and an **empty list** in a
+  machine-readable format.
 - `status [--section S]` - the sessions table carries `sessionKey`, `user`,
   `library`, `ratingKey`, `title`, `state`, `player`, `platform`, `address`,
   `progress`, and `file`; `sessionKey` is what `wait --session` takes. `records.playing_file` reports the file in use: a session marks
@@ -1174,8 +1527,9 @@ command would not repeat them and trip `duplicate-code`.
   none), and `--save-password` saves the password beside it so plexdo can
   sign in again by itself once the token stops working. `--dry-run`
   authenticates and saves nothing. The table says where the token went
-  (`secret_store.describe()`); other formats give `user`, `store`,
-  `verified`, and `passwordSaved`. `--password` on the command line is
+  (`secret_store.describe("tokens")`); other formats give `user`, `store`,
+  `passwordStore` (`describe("passwords")`), `verified`, and
+  `passwordSaved`. `--password` on the command line is
   scrubbed from the process title via `ctypes.pythonapi.Py_GetArgcArgv`
   (`sys.argv` is only a copy; `ps` reads the original buffer) and redacted
   from `sys.argv`, with a warning that is blunt about what cannot be fixed:
@@ -1205,6 +1559,30 @@ command would not repeat them and trip `duplicate-code`.
   prints the exact template, which needs `RawDescriptionHelpFormatter` for the
   epilog's newlines; that same formatter stops argparse wrapping the
   description, so pre-wrap it with `textwrap.fill(..., width=78)`.
+- `write-secrets-example [-o]` - writes `constants.SECRETS_EXAMPLE` to the
+  path `plex: secrets_file` names, after `expanduser`, creating its
+  directory. **When `secrets_file` is not set, write nothing**: say so on
+  stderr, naming the config path, and print the example to stdout, exit 0.
+  A missing config file sets nothing, so it takes that path too rather than
+  the "Config not found" exit; read the file with `parse_config` directly,
+  not `load_config`. The default secrets path is deliberately not used:
+  only a path the user chose is written to. An existing file is refused
+  without `-o/--overwrite`, before `--dry-run` as for the config, because
+  it may hold the only copy of a saved password or PIN. Create the file
+  with `os.open(..., O_CREAT | O_EXCL, 0o600)`, unlinking an old one first
+  under `-o`, so it is never readable by anyone else, even for a moment,
+  and an overwritten file does not keep looser permissions. The example is
+  the **password store**, the secrets file as `secret_store: file` keeps
+  it: JSON as `FileStore` writes it (`indent=2`, sorted keys), with
+  `passwords` and `pins`, each with one placeholder entry, and a
+  `_comment` entry, a list of short lines, saying every value is a
+  placeholder and that session tokens are not kept there. It must hold no
+  `tokens`: a placeholder token beside a real one made the store hold
+  two, so `admin_token` no longer took "the only one" and every command
+  reported no admin token. JSON has no comments; `FileStore` reads only the kinds it
+  is asked for and writes back every entry it loaded, so the note is
+  harmless and survives a later save. Its `--help` prints the exact
+  example in the epilog. Needs no server.
 
 ## ERROR HANDLING
 
@@ -1219,7 +1597,21 @@ or where no player answers. A
 command line argparse cannot parse exits 2, its own convention. An
 interrupted `wait` exits 130. No bare
 `except`; the broad ones are in `_cancel_all_scans`, the per-user copy loop,
-and per-section collection, each with a `# pylint: disable=broad-except`.
+the per-library search, and per-section collection, each with a
+`# pylint: disable=broad-except`.
+
+**A request that fails must not reach the user as a traceback.** `cli.main`
+wraps `_run` and catches `requests.exceptions.RequestException` and
+`plexapi.exceptions.PlexApiException`, the two families everything raised
+by a request to the server or to plex.tv belongs to, and exits 1 with one
+or two lines chosen by kind: the server could not be reached (check it is
+running, and `plex: url`), it did not answer in time, it refused the saved
+token (run `plexdo login`), or it refused the request. Only the **first
+line** of the error is shown, since plexapi attaches the server's whole
+HTML error page to some, and it goes through `security.redact`, since a
+URL in a requests error can carry a token. The traceback is logged at
+DEBUG. Handlers closer to the request, such as the per-user loops and
+`UserAccessError`, still take precedence; this is the net under them.
 
 ## PLATFORM SUPPORT
 
@@ -1247,6 +1639,40 @@ data. All cover the same values, read a 15-minute cache under the platform
 cache directory (honouring `cache_dir`), and refresh a stale cache in the
 background so completion never blocks.
 
+**Each script finds the cache as plexdo does**, or completion silently
+offers nothing: `plex: cache_dir` from `config.yaml`, in
+`$XDG_CONFIG_HOME/plexdo` or `~/.config/plexdo` (`%LOCALAPPDATA%\PlexDo` on
+Windows), with environment variables and a leading `~` expanded; else
+`$XDG_CACHE_HOME/plexdo`, by default `~/.cache/plexdo`. An XDG variable
+counts only when absolute. They once read the 1.x INI file and a
+hard-coded `~/.cache`, long after both had moved. PyYAML may not be
+importable by whichever python the script finds, and PowerShell has no
+YAML reader, so each reads the one scalar it needs a line at a time: a
+`cache_dir:` line indented under the top-level `plex:` key, skipping
+blank and comment lines, unquoting a double-quoted value as a JSON string
+and a single-quoted one by its doubled quotes, and cutting a trailing
+` #` comment from a plain one. bash, zsh, and fish share one python
+snippet, which must contain **no single quote and no backslash**, because
+fish holds it in a single-quoted string.
+
+**The cache is kept twice, by ID and by word.** `titles.LIBRARY.json` and
+`playlists.USER.json` are named for the numeric ID, but a script holds
+whatever is on the command line, which may be a title, and cannot resolve
+it as plexdo does. So `cache.write_word_caches` files the same rows as
+`titles-by-word.WORD.json` and `playlists-by-word.WORD.json`, once for
+each spelling: the ID, the title, and the word as typed.
+`identify.remember_words` records the three while the argument is
+resolved, on `args.argument_words`, since resolution replaces what was
+typed with the ID; `argument_words(args, name)` reads them back. Both
+caches are written whenever a result is handled, so they cannot drift. In
+a file name `cache.cache_key` replaces each of `/ \ : * ? " < > |` and
+the control characters with `_`, chosen so every shell can make the same
+name with one substitution of its own; each script has that function and
+a test compares them. Playlist and album-name completion read the by-word
+cache for the word typed, dequoted; ratingKey completion still gathers
+every `titles.*.json`, which the by-word names do not match, so no key is
+offered twice.
+
 Numeric IDs are shown with their titles. Distinguish what is *insertable* from
 what is merely *shown*: user and library titles are insertable because those
 arguments accept them, but an item title is not, since `fetchItem` needs a
@@ -1268,7 +1694,19 @@ numeric ratingKey.
   skipping options that consume a value. Guard the background refresh on the
   binary existing: fish reports an unknown command *before* redirection
   applies, scribbling on the prompt mid-completion.
-- **PowerShell** - `Register-ArgumentCompleter -Native`. Needs no external
+- For `playlist-build` and `playlist-copy`, every script first finds the mode
+  flag among the words already typed, and completes each positional as that
+  mode defines it: with `-I` or `-C` a name then rating keys; with `-R` a
+  user, then that user's playlists; with `-A` on `playlist-build` a user,
+  that user's playlists, then rating keys; with `-T` on `playlist-copy` the
+  receiving user third. With no mode typed yet, nothing says what an
+  argument is, so bash offers the mode flags and the others offer only
+  options. In zsh, hold option specs that use `{-o,--overwrite}` braces in
+  **arrays**: a scalar assignment does not expand the braces, and the spec
+  reaches `_arguments` malformed and is silently never offered.
+- **PowerShell** - `Register-ArgumentCompleter -Native`. Compare the mode
+  flags with `-cin`: PowerShell's `-in` ignores case, and `-a` and `-A` are
+  different options. Needs no external
   interpreter: `ConvertFrom-Json` reads the cache. Return `CompletionResult`
   objects so the ID is inserted and the title shows as a tooltip. Two traps
   that parse cleanly and fail at runtime: a range of `0..-1` **wraps** and
@@ -1278,7 +1716,8 @@ numeric ratingKey.
 ## MAN PAGE
 
 `man/plexdo.1`, in roff, mirrored into `src/plexdo/data/`. Documents every
-command, the configuration and token formats, exit status, environment, files,
+command, under the same five headings and in the same order as `--help`,
+and the configuration and token formats, exit status, environment, files,
 and worked examples, and passes `groff -man -Tutf8 -ww -z` with no warnings.
 
 Escapes that silently corrupt copy-pasteable examples: a literal backslash is
@@ -1305,9 +1744,16 @@ double-width characters, the ASCII fallback, and fitting to a budget;
 identifier resolution including the ID-versus-title collision; the overwrite
 guard performing **no** server calls when it refuses; watched-state selection
 in both directions and that an undated state never wins; which playlist entries
-`clean-playlist` drops, and that it numbers them by their place in the
-playlist rather than within the removal list; that concatenation preserves the
-order given and that `--unique` matches on ratingKey; that a per-user create
+`playlist-clean` drops, and that it numbers them by their place in the
+playlist rather than within the removal list; that a merge keeps each side's
+order and that `--unique` matches on ratingKey; that every command is in
+exactly one help group, that `--help` lists them grouped and sorted, and that
+the old names are refused; that each `playlist-build` and `playlist-copy`
+mode names its arguments, and that the wrong count, a missing or second mode
+flag, and `--append` with a creating option all exit 2; that
+`write-secrets-example` prints rather than writes when `secrets_file` is not
+set, refuses an existing file, writes mode 0600, and that its example loads
+through `FileStore` with its note surviving a save; that a per-user create
 reports a taken name instead of exiting and performs no call when it does, and
 that a fan-out records an unreachable user and an unexpected failure and keeps
 going; where `wait` puts its end point for every combination of marker,
@@ -1359,9 +1805,10 @@ because unknown and zero are different things.
   packaged mirrors, and that no source file contains non-ASCII. Editing the
   source copy and forgetting the mirror ships a stale asset in the wheel.
 - `smoke` imports the package, builds the full parser, and asserts every
-  module in `MODULES` still exposes `register()` and `COMMANDS`. pylint scores
+  module in `MODULES` still exposes `register()` and `COMMANDS`, and that
+  the commands registered are exactly those in `GROUPS`. pylint scores
   a module 10.00/10 even when an edit has truncated that tail, which breaks
-  every command in it.
+  every command in it; a count to compare against would only go stale.
 
 The Makefile also provides `install`, `uninstall`, `develop`, `reinstall`,
 `install-man`, `uninstall-man`, `install-completion` and its four per-shell
@@ -1408,8 +1855,9 @@ version cannot be undone. Strip a leading `v` before comparing.
 ## COMMAND PAGES
 
 Beside the roff overview, every command has a detailed page in scdoc source
-format: `man/plexdo-COMMAND.1.scd`, one per command, with `list-library`
-documented in the `list-titles` page as the alias it is, and
+format: `man/plexdo-COMMAND.1.scd`, one per command, so `playlist-build`
+and `playlist-copy` each have one page covering every mode, with a `MODES`
+section and each argument marked with the modes that take it, and
 `man/plexdo-conventions.7.scd` for what every command shares - the global
 options, how users, libraries, playlists, items, and sessions are named,
 output formats, path rewriting, pacing, exit status, files, and
@@ -1448,7 +1896,7 @@ and SEE ALSO. GLOBAL OPTIONS says what **each** global flag does for that
 particular command - "no effect" is an answer, and `--dry-run` writing a
 file anyway is worth saying. OPTION INTERACTIONS covers every conflict and
 dependency, whether argparse enforces it (`-u`/`-a`) or the handler does
-(`find-missing -A` with SHOW, `wait --now` without `-r`). Document what the
+(`missing-find -A` with SHOW, `wait --now` without `-r`). Document what the
 code does, checked against it, not what a help string implies. Sample tables
 are real output from `print_table` with an ASCII console, never hand-drawn.