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>

scripts/debug/visualize_pagination.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""
+Test script to visualize library pagination.
+"""
+
+from pathlib import Path
+from dreader import LibraryManager
+
+def test_pagination():
+    """Test pagination with actual library"""
+    library_path = Path(__file__).parents[2] / 'tests' / 'data' / 'library-epub'
+
+    # Create library manager (default books_per_page=6)
+    library = LibraryManager(
+        library_path=str(library_path),
+        page_size=(800, 1200)
+    )
+
+    # Scan library
+    books = library.scan_library()
+    print(f"\nFound {len(books)} books")
+    print(f"Books per page: {library.books_per_page}")
+    print(f"Total pages: {library.get_total_pages()}")
+
+    # Render all pages
+    for page_num in range(library.get_total_pages()):
+        library.set_page(page_num)
+        print(f"\n=== Rendering Page {page_num + 1}/{library.get_total_pages()} ===")
+
+        library.create_library_table()
+        img = library.render_library()
+
+        output_path = f'/tmp/library_pagination_page{page_num + 1}.png'
+        img.save(output_path)
+        print(f"Saved to {output_path}")
+
+        # Show which books are on this page
+        start_idx = page_num * library.books_per_page
+        end_idx = min(start_idx + library.books_per_page, len(books))
+        page_books = books[start_idx:end_idx]
+        print(f"Books on this page ({len(page_books)}):")
+        for book in page_books:
+            print(f"  - {book['title']} by {book['author']}")
+
+    # Cleanup
+    library.cleanup()
+    print("\nPagination test complete!")
+
+if __name__ == '__main__':
+    test_pagination()