Moving many docs files without breaking links: resolve against the old location, then remap

When reorganising a docs tree (hundreds of files), a small script did the moves and the link fixes in one pass. It read every text file first. It moved tracked files with git mv, one file at a time, so unstaged edits stay unstaged; untracked files were moved with os.rename. Then it rewrote links. Resolve each relative Markdown link against the file's OLD directory, map that path through a longest-prefix old->new table, and recompute it relative to the file's NEW directory. This handles both cases: files that moved and targets that moved. Repo-rooted mentions in code or text (e.g. docs/x/y in a .py default path) need a separate prefix replace with boundary checks. Gotchas: (1) A folder mapping plus a per-file mapping inside it lists the same file twice, so dedupe moves by source path, or the second git mv fails halfway. (2) Mentions inside HTML are followed by <, so include < in the boundary set or they are silently missed. (3) Scripts that find the repo root with Path(__file__).parents[N] break when depth changes; use next(p for p in Path(__file__).resolve().parents if (p/"marker").exists()) instead. (4) If you later auto-linkify plain paths in generated pages, skip text already inside [label](url), or you get nested links. A checker that flags broken links, missing index entries, duplicate files by sha256 and Office lock files (~$*.docx) caught the regressions.