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/update_pyweblayout.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Update pyWebLayout to the latest version from git
+#
+# This script updates pyWebLayout to fix compatibility issues
+
+set -e  # Exit on error
+
+echo "================================"
+echo "pyWebLayout Update Script"
+echo "================================"
+echo ""
+
+# Check if we're in a virtual environment
+if [ -z "$VIRTUAL_ENV" ]; then
+    echo "⚠️  Warning: No virtual environment detected!"
+    echo "It's recommended to activate your virtual environment first:"
+    echo "  source venv/bin/activate"
+    echo ""
+    read -p "Continue anyway? (y/N) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+fi
+
+echo "Updating pyWebLayout from git repository..."
+echo ""
+
+# Upgrade pyWebLayout from the git repository
+pip install --upgrade git+https://gitea.tourolle.paris/dtourolle/pyWebLayout@master
+
+echo ""
+echo "================================"
+echo "Update Complete!"
+echo "================================"
+echo ""
+echo "pyWebLayout has been updated to the latest version."
+echo "You can now run the application normally."
+echo ""