Implement site-wide navigation menu with caching and error logging

.vscode/settings.json

@@ -10,5 +10,16 @@
         ".specify/scripts/bash/": true,
         ".specify/scripts/powershell/": true
     },
-    "terminal.integrated.cwd": "${workspaceFolder}/src"
+    "terminal.integrated.cwd": "${workspaceFolder}/src",
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+    "python.terminal.activateEnvironment": true,
+    "python.testing.unittestEnabled": true,
+    "python.testing.unittestArgs": [
+        "-v",
+        "-s",
+        ".",
+        "-p",
+        "test*.py"
+    ],
+    "python.testing.cwd": "${workspaceFolder}/src"
 }

AGENTS.md

@@ -51,6 +51,13 @@ class HeadingBlock(blocks.StructBlock):
 
 **Security**: Use `EmbedBlock` (oEmbed) for embedded content, NEVER `RawHTMLBlock` (XSS risk).
 
+**Navigation Menu Pattern**: See `src/navigation/blocks.py` for nested block structure that enforces 2-level maximum:
+- `TopLevelMenuBlock` (StreamBlock) contains page_link, external_link, OR dropdown
+- `DropdownMenuBlock` (StructBlock) contains title and items (MenuItemBlock)
+- `MenuItemBlock` (StreamBlock) contains ONLY page_link and external_link (no nested dropdowns)
+
+This structural approach prevents 3+ level nesting at the schema level.
+
 ### 4. Translation & Locale Management
 
 - Translation UI comes from `wagtail.contrib.simple_translation` (already installed)
@@ -62,22 +69,42 @@ class HeadingBlock(blocks.StructBlock):
 
 ## Development Workflow
 
-### Essential Commands (from `src/` directory)
+### Essential Commands
+
+**IMPORTANT**: This project uses `uv` for package management. When running Python commands in terminals (especially from AI assistants or automated tools), the virtual environment may not be automatically activated. **Always prefix Python commands with `uv run`** to ensure the correct environment is used:
+
+```bash
+# ✅ CORRECT - Use uv run for all Python commands
+uv run python manage.py test
+uv run python manage.py migrate
+uv run python manage.py runserver
+
+# ❌ WRONG - May fail if virtual environment isn't activated
+python manage.py test
+```
+
+#### Package Management (from project root)
 
 ```bash
-# Package management (from project root)
 uv sync                    # Install all deps (creates .venv/)
 uv add package-name        # Add runtime dependency
 uv add --dev package-name  # Add dev dependency
+```
+
+#### Django Commands (from src/ directory)
 
-# Django (from src/ directory)
+```bash
 cd src
-python manage.py migrate
-python manage.py test                    # Run all tests (64 total)
-python manage.py test locales.tests      # Run specific app tests
-python manage.py createsuperuser         # One-time setup
+uv run python manage.py migrate
+uv run python manage.py test                    # Run all tests
+uv run python manage.py test navigation         # Run specific app tests
+uv run python manage.py createsuperuser         # One-time setup
+uv run python manage.py runserver               # Development server
+```
 
-# Code quality (from project root)
+#### Code Quality (from project root)
+
+```bash
 uv run pre-commit install              # One-time setup
 uv run pre-commit run --all-files      # Manual run
 uv run ruff check --fix .              # Lint with auto-fix
@@ -183,8 +210,9 @@ from core.constants import DEFAULT_LANGUAGE_CODE, DEFAULT_LANGUAGES
 - **curlylint** - Template linting
 
 ### Migration Best Practices
+
 1. Test migrations are auto-generated
-2.  based on model changes
+2. based on model changes
 3. Run `python manage.py makemigrations` after model changes
 4. All StreamField changes require migrations (block structure changes)
 5. Check migration files into version control

CHANGELOG.md

@@ -9,6 +9,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Navigation Menu System**: Site-wide multi-lingual navigation with WCAG 2.1 AA accessibility
+  - Site-wide navigation menu configuration via Wagtail Settings (BaseSiteSetting pattern)
+  - StreamField-based menu structure with PageLinkBlock, ExternalLinkBlock, and DropdownMenuBlock
+  - **2-level menu maximum**: Enforced at schema level - prevents nested dropdowns
+  - **Locale-aware rendering**: Automatic page translation linking with fallback to default locale
+  - **Full WCAG 2.1 AA compliance**: ARIA menubar pattern, keyboard navigation, screen reader support
+  - **DaisyUI responsive design**: Mobile hamburger drawer, desktop horizontal menu
+  - **Accessibility features**:
+    - Skip link to main content (first focusable element)
+    - ARIA attributes (role, aria-label, aria-current, aria-expanded, aria-haspopup, aria-controls)
+    - 44x44px minimum touch targets for mobile
+    - Visible focus indicators (3:1 contrast ratio)
+    - Progressive enhancement with `<details>`/`<summary>` for dropdowns
+  - **Dropdown edge detection**: JavaScript prevents viewport overflow (opens left/right/down based on space)
+  - **Keyboard support**: Tab, Enter, Space, Escape, Arrow keys for full navigation
+  - **Theme-aware**: Automatic adaptation to light/dark mode via DaisyUI
+  - **7 comprehensive tests**: ModelTests, StreamFieldTests, IntegrationTests for dropdown structure
+  - Developer documentation in `specs/002-nav-menu-system/` (plan, data model, contracts, quickstart)
+  - Template tag: `{% load navigation_tags %}{% navigation_menu %}`
 - **Tailwind CSS Integration**: Modern utility-first CSS framework with DaisyUI components
   - Tailwind CSS v4 with @source directive for automatic template scanning
   - DaisyUI plugin with semantic component classes (buttons, cards, navigation, forms, alerts)