Expose every tools script as a dec-tool subcommand

[seebi]

💪 What

• Adds build-navigation, check-zensical-output and localize-bundle-assets as dec-tool subcommands, so all six build/generate/check scripts share one entry point instead of three of them being called as poetry run python tools/<script>.py
• Renames tools/build_nav.py to tools/build_navigation.py so file and command agree, as they already do for the other five
• Removes the __main__ blocks: dec-tool is now the only entry point, matching update-icons, update-di-reference and update-integrations
• Adds --check to build-navigation, which diffs the generated navigation against the -o target and exits 1 on drift, replacing the mktemp/trap/diff shell block in the Taskfile
• Renames the nav task to update:navigation and check:nav to check:navigation, grouping both with the existing update:* and check:* families
• Updates the pre-commit nav-drift hook to the new task and module names
• Rewrites tools/README.md, which said "This directory is not used at the moment", into a reference for all six subcommands and the tasks that call them
• Drops the README's tag-listing workaround section: Zensical 0.0.58 ships native listings and chip links, and the two files that section described were deleted in 1b969f4
• Adds test coverage for the navigation builder, taking it from 2 tests to 28: dir_title's acronym rule, discover_dir's MkDocs-like ordering, expand_dir's no-bare-directory behaviour, expand_item's title inheritance and inline sections, both of render_nav's error paths, and the CLI cases that were missing

The new commands follow the conventions the existing ones already set: named options with repo-relative defaults and show_default, the command writing its own output, and progress on stdout via click.echo.

🤔 Why

• Half the tooling was reachable through dec-tool and half through direct script paths, so the two halves drifted apart in argument handling, defaults and error reporting. One entry point makes dec-tool --help an accurate inventory of what this repo can do to itself.
• The navigation drift check lived as shell inside Taskfile.yml: a temp file, a trap, a diff and hand-written echo messages. Moving it into --check makes it testable, and it is now covered by unit tests rather than only by running the task.
• The navigation builder generates the whole 571-line nav.yml, and until now nothing pinned its behaviour. Its rules are the kind that break quietly: dir_title capitalises only all-lowercase names, which is what stops link-IDS-event-to-KG becoming "Link Ids Event To Kg", and expand_dir walks a .pages-less directory because a bare directory reference empties the sidebar under navigation.tabs and drops pages from the navigation. Both now have tests, and both were confirmed to fail when the rule is reverted.
• task nav gave no hint that it regenerates nav.yml, and sorted nowhere near the other regeneration tasks. update:navigation and check:navigation put both halves where you would look for them.
• The README described a tag-listing renderer and a tags.html override as features "reimplemented here", pointing at two files that no longer exist. The failure message of the check that guards tag chips named the deleted override too, which is the worst possible moment to read a stale hint.

👀 Usage

poetry run dec-tool --help                    # six subcommands
poetry run dec-tool build-navigation --help   # --docs-dir, -o/--output-file, --check

task update:navigation    # regenerate nav.yml from docs/**/.pages
task check:navigation     # fail on drift, with a diff

👩‍🔬 How to validate

1. poetry run dec-tool --help — six subcommands, three of them new.
2. Reorder two entries in any docs/**/.pages file, then task check:navigation. It prints a unified diff of exactly that change, tells you to run task update:navigation, and exits 1. The same happens on git commit via the pre-commit hook.
3. task update:navigation, then git diff nav.yml — empty, i.e. the rewritten generator reproduces the committed file byte for byte. Revert your .pages edit afterwards.
4. task build — the build ends with localize-bundle-assets rewriting the two unpkg URLs to the vendored glightbox copies.
5. task check:output — reports the tag-chip checks as PASS and social cards / revision dates as PEND.

🧹 Open issues (not addressed here)

Deliberately left for follow-up work, recorded here so they are visible at merge time:

• tasks/ is largely obsolete. tasks/spec.md carries its own verdict — "removed 2026-09-03 … Lifetime: delete the moment Zensical ships listings" — and Zensical shipped them in 0.0.58. tasks/backlog.md marks B0-B8 and C1-C4 done and describes files that were deleted. tasks/check_zensical_output.py is the copy that handoff.md T8a said to move into tools/; that happened, and the two have since diverged. All three can go once feature/zensical lands on main.
• tasks/handoff.md is stale in places. It references tools/build_nav.py and python tools/check_zensical_output.py site, both dead paths after this PR, and its section 5 still lists tag listings as deferred. Its T1–T8 are all verifiably complete — the remaining value is the record of why the migration looks the way it does.
• check-zensical-output and localize-bundle-assets have no tests. Only the navigation builder was covered here. Testing the former first needs a decision on its module-level failures/notices lists, which report() appends to: they make results accumulate across invocations in one process, so tests would have to assert on globals or the checks need to return their results instead.
• Two Zensical gaps remain open. Social cards (Support material/social plugin functionality zensical/backlog#37) and revision dates (Support mkdocs-git-revision-date-localized plugin functionality zensical/backlog#18) are still missing and still reported as PEND on every build. They are the reason the migration is not finished, and the merge decision on feature/zensical should account for them.

🔗 Related links

• Support material/social plugin functionality zensical/backlog#37
• Support mkdocs-git-revision-date-localized plugin functionality zensical/backlog#18

[github-actions]

Test Results

1 files  ±0  2 suites  ±0   0s ⏱️ ±0s
2 tests ±0  0 ✅ ±0  0 💤 ±0  2 ❌ ±0 
2 runs  ±0  -7 ✅ ±0  0 💤 ±0  9 ❌ ±0 

For more details on these failures, see this check.

Results for commit a6911b9. ± Comparison against base commit 1b969f4.

♻️ This comment has been updated with latest results.

[rpietzsch]

looks good to me, also tested and validated locally. thanks for the refinements/integration in tools 🙌