Add inline comments throughout the codebase

[Copilot]

Every function had a docstring describing its purpose, but function bodies contained no comments explaining non-obvious logic, design decisions, or subtle edge cases.

slot.py

• Timestamp padding rationale (lexicographic = chronological sort), symlink-first detection order, exist_ok=False atomicity, incomplete-slot filtering in list_slots

restore.py

• Dangling symlink detection via os.path.islink, dir vs. file removal path, newest-first search semantics in find_latest_slot_for_path

index.py

• Added missing docstrings to _db_path, _file_mtime, _meta_hash, _flags_summary
• SQL upsert semantics, staleness check logic, entries-replacement strategy, hash truncation caveat (change detection, not cryptographic)

cli/tomb_cmd.py

• Added missing docstrings to all seven private command functions
• Refresh-then-reopen pattern in _cmd_list, TTY guard in _cmd_purge, non-zero return convention in _cmd_verify

cli/rm_cmd.py

• -- end-of-options handling, combined short flag parsing, mutable-list counter pattern, interactive prompt scope (top-level non-dirs here; dir contents in _walk_entries)

cli/unrm_cmd.py

• Both --to forms, combined flag parsing, path-vs-latest dispatch, TTY confirmation flow

Example — before/after in _delete_target:

# Before
if flags["interactive"] and not os.path.isdir(target):

# After
# Prompt only for non-directories here; in interactive mode, each item inside a
# directory tree is prompted individually by _walk_entries when it is walked below.
if flags["interactive"] and not os.path.isdir(target):

Original prompt

There are barely any meaningful comments in this code base. Each function has a starting docstring that indicates its purpose, but there are no other comments throughout the code

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.