Updated AGENTS and CLAUDE files.

AGENTS.md

@@ -22,13 +22,13 @@ This document is intentionally explicit so tasks can be completed with minimal r
 
 ## 3) Environment and Setup Commands
 
-- Create venv: `python -m venv .venv`
+- Create venv: `.venv/bin/python -m venv .venv`
 - Activate venv (bash): `source .venv/bin/activate`
 - Install deps: `pip install -r requirements.txt`
-- Apply migrations: `python manage.py migrate`
-- Run server: `python manage.py runserver`
+- Apply migrations: `.venv/bin/python manage.py migrate`
+- Run server: `.venv/bin/python manage.py runserver`
 
-Local configuration is loaded from `.env` via `python-dotenv`.
+Local configuration is loaded from `.env` via `.venv/bin/python-dotenv`.
 
 Use this minimum `.env` content for gallery paths:
 
@@ -49,30 +49,30 @@ There is no dedicated linter or formatter config in-repo (no `ruff`, `flake8`, `
 
 Use these commands as the standard validation set:
 
-- Django system checks: `python manage.py check`
-- Migration consistency check: `python manage.py makemigrations --check --dry-run`
-- Python syntax sanity: `python -m compileall NibasaViewer viewer`
-- Run Django tests (all): `python manage.py test`
+- Django system checks: `.venv/bin/python manage.py check`
+- Migration consistency check: `.venv/bin/python manage.py makemigrations --check --dry-run`
+- Python syntax sanity: `.venv/bin/python -m compileall NibasaViewer viewer`
+- Run Django tests (all): `.venv/bin/python manage.py test`
 
 Single-test execution patterns (important for fast iteration):
 
-- Single test module: `python manage.py test viewer.test`
-- Single test class: `python manage.py test viewer.test.GalleryViewTests`
-- Single test method: `python manage.py test viewer.test.GalleryViewTests.test_search_action_url_uses_nested_path`
+- Single test module: `.venv/bin/python manage.py test viewer.test`
+- Single test class: `.venv/bin/python manage.py test viewer.test.GalleryViewTests`
+- Single test method: `.venv/bin/python manage.py test viewer.test.GalleryViewTests.test_search_action_url_uses_nested_path`
 
 Notes:
 
 - If there are currently no tests, add focused tests near the changed behavior before large refactors.
-- Prefer `python manage.py test ...` style labels over introducing a second test runner.
+- Prefer `.venv/bin/python manage.py test ...` style labels over introducing a second test runner.
 
 ## 5) Operational Commands
 
-- Pre-generate thumbnails: `python manage.py makethumbnails`
+- Pre-generate thumbnails: `.venv/bin/python manage.py makethumbnails`
 - Create auth user (shell):
-  - `python manage.py shell`
+  - `.venv/bin/python manage.py shell`
   - `from django.contrib.auth.models import User`
   - `User.objects.create_user('<USERNAME>', '<EMAIL>', '<PASSWORD>')`
-- Collect static files (deploy-time): `python manage.py collectstatic`
+- Collect static files (deploy-time): `.venv/bin/python manage.py collectstatic`
 
 ## 6) Architecture and Change Boundaries
 
@@ -90,6 +90,10 @@ Notes:
 - `_render_image` in `viewer/views.py` now exposes additional context keys used by the template and tests: `prev_url`, `next_url`, `prev_thumb`, `next_thumb`, `back_url`, `back_thumb`, `home_url`, `home_thumb`, and `image_meta` (dictionary with `filename`, `width`, `height`, `filesize`, `created`, `modified`). Agents modifying image-view behavior should update tests in `viewer/test.py` as well.
 - The top-bar sort button for the image view was replaced by an Info button (`fa-circle-info`) which shows a dropdown containing image metadata. The dropdown is vertically scrollable for long content.
 - The displayed main image now uses the same drop shadow and rounded corners as thumbnails (styles added to `viewer/static/css/styles.css`).
+ - The gallery view and image view were split into focused modules: `viewer/directory.py` handles directory browsing and search, `viewer/image.py` handles single-image rendering and metadata, `viewer/common.py` contains shared helpers (URL/query builders, sort helpers, breadcrumbs), and `viewer/utils.py` contains thumbnail helpers (`THUMB_SIZE`, `is_image_file`, `make_thumbnail`). `viewer/views.py` is now a thin delegating layer that routes requests to those modules.
+ - The image view (`viewer/image.py`) exposes richer context keys used by the template and tests: `prev_url`, `next_url`, `prev_thumb`, `next_thumb`, `back_url`, `back_thumb`, `home_url`, `home_thumb`, and `image_meta` (dictionary with `filename`, `width`, `height`, `filesize`, `created`, `modified`). Agents modifying image-view behavior should update tests in `viewer/test.py` as well.
+ - The top-bar sort button for the gallery view remains; the image view uses an Info button (`fa-circle-info`) which shows a dropdown containing image metadata. The dropdown is vertically scrollable for long content.
+ - Thumbnails are 128×128 (`THUMB_SIZE`) and generated lazily on-demand in `viewer/utils.py`; `IMAGE_EXTENSIONS` provides fast extension-based filtering. A management command `.venv/bin/python manage.py makethumbnails` exists for batch pre-generation.
 
 ## 7) Code Style Guidelines (Repository-Specific)
 
@@ -169,8 +173,8 @@ When implementing a change, follow this minimum loop:
 
 Suggested pre-handoff command bundle:
 
-- `python manage.py check`
-- `python manage.py test` (or a targeted test label)
-- `python -m compileall NibasaViewer viewer`
+- `.venv/bin/python manage.py check`
+- `.venv/bin/python manage.py test` (or a targeted test label)
+- `.venv/bin/python -m compileall NibasaViewer viewer`
 
 This repository values stability, compatibility, and straightforward Django patterns over novelty.

CLAUDE.md

@@ -49,6 +49,13 @@ The project has one Django app: **`viewer`**. All gallery functionality is conso
 - `utils.py` - Thumbnail generation helpers
 - `templates/` - Pure HTML templates (no JavaScript)
 - `static/` - CSS styling and navigation icons
+ - `views.py` - Thin delegating entry points that route to `viewer/directory.py` and `viewer/image.py` (see `gallery_view` in `viewer/views.py`).
+ - `directory.py` - Directory browsing, search, and list rendering helpers.
+ - `image.py` - Single-image rendering and metadata helpers.
+ - `common.py` - Shared helpers: URL/query builders, sorting, breadcrumbs, thumbnail utilities.
+ - `utils.py` - Thumbnail generation helpers.
+ - `templates/` - HTML templates (minimal JS via Bootstrap where needed).
+ - `static/` - CSS styling and navigation icons
 
 ### Gallery Data Flow
 
@@ -77,20 +84,22 @@ Uses Django's built-in `django.contrib.auth` system:
 
 1. **Directory browsing** when path points to folder:
     - Lists subdirectories and images
-   - Supports search with recursive directory scanning (viewer/views.py:32-52)
-   - Paginates images at 28 per page (7 columns × 4 rows)
-   - Converts flat image lists to table rows for HTML rendering
+    - Supports search with recursive directory scanning (`viewer/directory.py:do_recursive_search`)
+    - Does not use server-side pagination; the gallery returns full image lists and templates render them in a grid
+    - Converts image lists to structured context used by templates
 
 2. **Image viewing** when path points to file:
     - Displays single image with prev/next navigation
     - Finds sibling images in same directory
     - Links to full-resolution image
 
+The image view logic now lives in `viewer/image.py` and exposes additional context keys used by templates and tests (see `viewer/test.py`): `prev_url`, `next_url`, `prev_thumb`, `next_thumb`, `back_url`, `back_thumb`, `home_url`, `home_thumb`, and `image_meta` (filename/width/height/filesize/created/modified).
+
 ### Thumbnail Generation
 
 **Lazy generation approach** (viewer/utils.py):
 - Thumbnails created on-demand when viewing gallery
-- 128×128 pixel size (hardcoded)
+ - 128×128 pixel size (`THUMB_SIZE`) and cached under `THUMBNAILS_ROOT`
 - Uses Pillow for image processing
 - Fast extension-based image detection (no MIME-type I/O)