fabi/Sylpheed
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: the UI decode's own evidence images were unreachable -- 11 links repaired

Browse Source 
The brief's rule is to commit reference data beside the finding so the
port can be built without a disc. Nothing had ever checked that the docs'
cited artifacts actually exist. doc_link_check.py walks every markdown
file under docs/, resolves each relative link, and reports targets that
are missing -- and separately targets that resolve to a ZERO-BYTE file,
which looks fine in any listing.

  links resolving   1038 -> 1049
  missing targets     16 -> 5
  empty targets        0 -> 0

+11 resolving and -11 missing against 11 edits: the counts pair, which is
the confirmation the pass did what it claimed and touched nothing else.

Two of the sixteen were the evidence for the UI layout decode itself.
structures/ui-rat-layout.md is what the port is built on, and its two
figures -- backing "the tutorial PAUSE menu rebuilds pixel-accurately
from its sprites" and "the same method reproduces the main menu" -- were
written as captures/ui-layout/... from a file in structures/, one
directory too shallow. The headline evidence for the decode could not be
opened from its own document.

Eleven links had the wrong relative depth with the target present. Each
was rewritten only where exactly one candidate path resolved, so nothing
was guessed; the first pass left three alone because equivalent spellings
(captures/../captures/x) failed to collapse, and a second pass normalised
them.

Five remain genuinely absent and are left rather than invented: two point
at MEMORY.md outside the repo, one at a header in the separate
xenia-canary-native tree, and two name documents that were never written
(weapon-datasheet-runtime.md, canary-build-verified-env-confound.md).
None is port-relevant. A missing document is a different problem from a
bad path and is not something a link fix should paper over.
This commit is contained in:
Sylpheed RE agent
2026-08-29 02:34:16 +00:00
parent 3eba09aae0
commit 6c8ee2ee6a
12 changed files with 136 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
docs/re/doc-link-audit.md Normal file
View File

@@ -0,0 +1,50 @@
# ✅ Do the docs' cited artifacts exist? — 11 broken links repaired
**Status:** ✅ checked mechanically and fixed, with the count verified both ways.
The brief's rule is *"commit the reference data beside the finding, so the port
can be built without a disc in the loop"*. An answer whose evidence is not
reachable cannot be used. Nothing had ever checked that.
[`tools/re-capture/doc_link_check.py`](../../tools/re-capture/doc_link_check.py)
walks every markdown file under `docs/`, resolves each relative link, and reports
targets that do not exist — and, separately, targets that exist but are **empty**,
which is the sneakier failure since a zero-byte file looks fine in any listing.
| | before | after |
|---|---|---|
| links resolving | 1 038 | **1 049** |
| missing targets | **16** | 5 |
| empty targets | 0 | 0 |
**+11 resolving, −11 missing — the two numbers pair exactly**, which is the check
that the repair did what it claimed and nothing else.
## 🔴 Two of them were the evidence for the UI decode itself
`structures/ui-rat-layout.md` is the layout decode the port is built on. Its two
figures — the ones backing *"the tutorial PAUSE menu rebuilds pixel-accurately
from its sprites"* and *"the same method reproduces the main menu"* — were
written as `captures/ui-layout/…` from a file in `structures/`, one directory
too shallow. **The headline evidence for the decode was unreachable from its own
document.**
## What was wrong, and what still is
Eleven links had the **wrong relative depth** while their targets existed — a
missing or surplus `../`, or a missing `structures/`. Those are repaired; each
was rewritten only when exactly one candidate path resolved, so nothing was
guessed.
❔ **Five remain genuinely absent** and are left alone rather than invented:
| doc | target |
|---|---|
| `autopilot-knowledge-sources.md`, `entities-live-roster.md` | `../../MEMORY.md` — outside the repo |
| `challenge-mission-gate.md` | a header in the separate `xenia-canary-native` tree |
| `stage-drift-is-navigation-not-save.md` | `structures/weapon-datasheet-runtime.md` — never written |
| `mission-freeze-resume-spin.md` | `canary-build-verified-env-confound.md` — never written |
None is port-relevant: they are mission, entity and emulator-side documents. Two
name documents that do not exist, which is a different problem from a bad path
and is not something to paper over with a link fix.