Summary

Route every all-smi cache writer — record output, energy WAL, and the users-tab CSV export — through a single platform-aware helper built on dirs::cache_dir(). Retires the three hard-coded ~/.cache/all-smi/... literals and the hand-rolled cache_dir_for_all_smi() reimplementation, so the cache layer is finally as platform-correct as the config layer (config_dir() already was). Builds on #227 (Scope A of #223).

What changed

• New helper. crate::common::paths::cache_dir() mirrors config_dir(): dirs::cache_dir().map(|d| d.join(APP_DIR_NAME)). Returns Option<PathBuf> so callers can downgrade gracefully on bare CI shells / containers without $HOME.
• record.output_dir and energy.wal_path are now Option<String>. None (the new compiled default) means "use the platform helper"; Some(s) is an explicit operator override resolved through expand_tilde. The CLI flag surface and the TOML key names are unchanged; ALL_SMI_ENERGY_WAL_PATH / ALL_SMI_RECORD_OUTPUT_DIR continue to work.
• Consumers updated. record::RecorderOptions::from_args_with_settings now layers -o flag → config output_dir (expand_tilde) → paths::cache_dir().join("records") → CWD fallback. api::server::run_api_mode resolves the WAL path through a new metrics::energy_wal::resolve_wal_path(...) helper that follows the same precedence. view::event_handler::export_users_csv calls paths::cache_dir() directly. The hand-rolled cache_dir_for_all_smi() in event_handler.rs is deleted.
• Energy-WAL signatures cleaned up. spawn_wal_flush_task / flush_cycle / compact_wal now take PathBuf / &Path instead of String / &str, dropping the per-cycle to_string() and Path::new(...) re-wrapping.
• Best-effort one-time migration. New src/common/cache_migration.rs is called once from main() before any subcommand touches the cache. Linux without $XDG_CACHE_HOME is a no-op (old == new). On macOS, Windows, and Linux with $XDG_CACHE_HOME set it moves ~/.cache/all-smi/records and ~/.cache/all-smi/energy-wal.bin into the new root only when the destination is empty (never overwrites) and refuses to follow a pre-planted symlink at the source (same threat model as the writer-side O_NOFOLLOW defences). The users-CSV exports are deliberately not migrated — they carry per-second timestamps and bulk-renaming hundreds of files would be more disruptive than helpful.
• config print shows the resolved on-disk path when no override is set, both in TOML and JSON outputs, so operators can confirm at a glance where data will land.
• Docs. README updates the [energy] wal_path, [record] output_dir, --output and users-CSV export rows + the WAL persistence paragraph + the security note about the users-CSV export; manpage updates the FILES and ENERGY ACCOUNTING sections; RecordArgs::output long_help and the example config.toml text spell out the per-platform cache locations. The v0.21.0 changelog entry gets a closing sentence describing the unification and the migration.

Migration

• Linux without $XDG_CACHE_HOME (the common case): dirs::cache_dir() == ~/.cache, so the old path and the new path are identical and the migration helper is a no-op.
• macOS, Windows, and Linux with $XDG_CACHE_HOME set: the cache root relocates. Operators will see one-time all-smi: migrated legacy cache <old> -> <new> lines on stderr at startup as records/ and energy-wal.bin are moved into the new root. The migration never overwrites an existing destination — if you have data at both the old and the new path, the old data is left in place for manual reconciliation.
• Symlink-planted sources are refused with a warning on stderr (all-smi: skipping cache migration of <path> (is a symlink)), matching the writer-side O_NOFOLLOW rationale.
• Cross-filesystem moves are not silently doubled — if $XDG_CACHE_HOME points at a tmpfs while ~ is on persistent disk, std::fs::rename will return EXDEV, the helper logs the error, and recordings stay where they were. Operators can move them by hand.

New tests

• paths::tests::cache_dir_ends_with_app_name — sanity for the new helper.
• record::tests::resolve_output_no_cli_no_config_uses_platform_cache_dir — guards the issue-cache: unify record/energy-WAL/users-CSV paths via platform-aware dirs::cache_dir() (Scope B from #223) #229 promise that record output flows through paths::cache_dir() (skipped on hosts where cache_dir() returns None, same pattern as config_dir_ends_with_app_name).
• cache_migration::tests (5 tests): try_move_skips_when_source_missing, try_move_renames_file_when_dst_missing, try_move_renames_directory_when_dst_missing, try_move_no_op_when_dst_exists, try_move_refuses_symlink_source (Unix-only — symlink creation requires it).
• Existing record::tests resolver tests rewritten for the Option<String> shape; config::tests::energy_config_defaults_match_issue_spec and the ALL_SMI_ENERGY_WAL_PATH env test now assert None / Some(...).

Security hardening preserved

The writer-side O_NOFOLLOW + mode 0600 defences in src/record/writer.rs, src/metrics/energy_wal.rs::open_secure_append, and src/view/event_handler.rs::open_export_secure apply unchanged to the new resolved paths — only the resolver tier changes. The migration helper has its own defence: it refuses to rename through a symlink at the source.

Test plan

• cargo check --bin all-smi --tests
• RUSTFLAGS="-L /tmp/drmlinks" cargo test --bin all-smi paths::tests::
• RUSTFLAGS="-L /tmp/drmlinks" cargo test --bin all-smi record::tests::
• RUSTFLAGS="-L /tmp/drmlinks" cargo test --bin all-smi cache_migration::tests::
• RUSTFLAGS="-L /tmp/drmlinks" cargo test --bin all-smi config::tests::
• RUSTFLAGS="-L /tmp/drmlinks" cargo test --bin all-smi config_file::tests::
• RUSTFLAGS="-L /tmp/drmlinks" cargo test --bin all-smi metrics::energy_wal::
• RUSTFLAGS="-L /tmp/drmlinks" cargo test --bin all-smi --test config_file_integration_test (14/14)
• RUSTFLAGS="-L /tmp/drmlinks" cargo clippy --bin all-smi --tests -- -D warnings
• cargo fmt --check

References #223 and #227. Closes #229.