chore: tidy repository layout and consolidate hardware docs

Root had grown to 30 entries, most of it generated output and one-off
scripts. It now holds 12.

Docs:
- Merge HARDWARE_SETUP, HARDWARE_PINOUT, GPIO_BUTTONS and
  ACCELEROMETER_PAGE_FLIP into a single docs/HARDWARE.md
- Move ARCHITECTURE, REQUIREMENTS and HAL_IMPLEMENTATION_SPEC to docs/,
  leaving only README.md in the root
- Update cross-references in README, setup_rpi.py and
  install_hardware_drivers.sh, and re-base ARCHITECTURE's source links

Merging surfaced three errors, reconciled against hardware_config.json:
- The power button was documented as GPIO 21 to GND with a pull-up. It is
  active high (pull_up: false); wiring it as documented reads as
  permanently pressed.
- GPIO_BUTTONS used GPIO 23 for next-page; it is GPIO 27.
- The FT5316 INT pin was routed to GPIO 27, which collides with the
  next-page button. Now documented as a conflict.

Scripts:
- Move debug_overlay_links.py and debug_previous_page.py to scripts/debug/
- Rename test_pagination_visual.py to scripts/debug/visualize_pagination.py;
  it renders output and asserts nothing, so the test_ prefix was misleading
- Fix the __file__-relative paths these three relied on
- Track update_pyweblayout.sh under scripts/

Tests:
- Reword the backward-navigation tests, which described a pyWebLayout bug
  that is now fixed, as regression tests

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tests/test_backward_nav_minimal.py

@@ -1,9 +1,12 @@
 """
-Minimal reproduction test for backward navigation bug.
+Regression test for backward navigation onto the cover page.
 
-BUG: Backward navigation cannot reach block_index=0 from block_index=1.
+Going forward off the cover and then back again must return to block_index=0.
 
-This is a pyWebLayout issue, not a dreader-application issue.
+Previously it left current_position at the first content block (1) while flagging
+the cover as displayed, so the cover had two different internal representations.
+Since current_position is what gets persisted, saving while on the cover reopened
+the book past it. Fixed in pyWebLayout's EreaderLayoutManager.previous_page().
 """
 
 import unittest
@@ -31,14 +34,12 @@ class TestBackwardNavigationBug(unittest.TestCase):
 
     def test_minimal_backward_navigation_bug(self):
         """
-        MINIMAL REPRODUCTION:
+        MINIMAL CASE:
 
         1. Start at block_index=0
         2. Go forward once (to block_index=1)
         3. Go backward once
-        4. BUG: Lands at block_index=1 instead of block_index=0
-
-        This proves backward navigation cannot reach the first block.
+        4. Should land back at block_index=0
         """
         reader = EbookReader(
             page_size=(800, 1000),
@@ -64,18 +65,13 @@ class TestBackwardNavigationBug(unittest.TestCase):
         pos_final = reader.manager.current_position.copy()
         print(f"3. After previous_page(): block_index={pos_final.block_index}")
 
-        # THE BUG: This assertion will fail
         print(f"\nEXPECTED: block_index=0")
         print(f"ACTUAL:   block_index={pos_final.block_index}")
 
-        if pos_final.block_index != 0:
-            print("\n❌ BUG CONFIRMED: Cannot navigate backward to block_index=0")
-            print("   This is a pyWebLayout bug in the previous_page() method.")
-
         self.assertEqual(
             pos_final.block_index,
             0,
-            "BUG: Backward navigation from block 1 should return to block 0"
+            "Backward navigation from block 1 should return to block 0"
         )
 
         reader.close()

tests/test_backward_navigation_detailed.py

@@ -1,12 +1,13 @@
 """
-Detailed test for backward navigation issues.
+Detailed regression tests for backward navigation.
 
-This test explores the backward navigation behavior more thoroughly
-to understand if the issue is:
+These cover the ways backward navigation has broken before:
 1. Complete failure (previous_page returns None)
 2. Imprecise positioning (lands on wrong block)
-3. Only occurs after resume
-4. Occurs during continuous navigation
+3. Failure only after resuming from a saved position
+4. Failure during continuous navigation
+
+See test_backward_nav_minimal.py for the minimal cover-page case.
 """
 
 import unittest