all the new shiny things

CLAUDE.md

@@ -15,17 +15,24 @@ Instead, ask the user to confirm the current state before providing instructions
 
 **CRITICAL**: This application is designed to run **exclusively on Linux**. See [ADR-014](docs/adr/0014-containerization-and-deployment-strategy.md) for full details.
 
+### Environment Terminology
+
+- **Dev Container** (or just "dev"): The containerized Linux development environment (`flyer-crawler-dev`). This is where all development and testing should occur.
+- **Host**: The Windows machine running Podman/Docker and VS Code.
+
+When instructions say "run in dev" or "run in the dev container", they mean executing commands inside the `flyer-crawler-dev` container.
+
 ### Test Execution Rules
 
-1. **ALL tests MUST be executed on Linux** - either in the Dev Container or on a Linux host
-2. **NEVER run tests directly on Windows** - test results from Windows are unreliable
-3. **Always use the Dev Container for testing** when developing on Windows
+1. **ALL tests MUST be executed in the dev container** - the Linux container environment
+2. **NEVER run tests directly on Windows host** - test results from Windows are unreliable
+3. **Always use the dev container for testing** when developing on Windows
 
 ### How to Run Tests Correctly
 
 ```bash
 # If on Windows, first open VS Code and "Reopen in Container"
-# Then run tests inside the container:
+# Then run tests inside the dev container:
 npm test           # Run all unit tests
 npm run test:unit  # Run unit tests only
 npm run test:integration  # Run integration tests (requires DB/Redis)
@@ -33,13 +40,13 @@ npm run test:integration  # Run integration tests (requires DB/Redis)
 
 ### Running Tests via Podman (from Windows host)
 
-The command to run unit tests in the Linux container via podman:
+The command to run unit tests in the dev container via podman:
 
 ```bash
 podman exec -it flyer-crawler-dev npm run test:unit
 ```
 
-The command to run integration tests in the Linux container via podman:
+The command to run integration tests in the dev container via podman:
 
 ```bash
 podman exec -it flyer-crawler-dev npm run test:integration
@@ -66,10 +73,10 @@ podman exec -it flyer-crawler-dev npm test -- --run src/hooks/useAuth.test.tsx
 ## Development Workflow
 
 1. Open project in VS Code
-2. Use "Reopen in Container" (Dev Containers extension required)
-3. Wait for container initialization to complete
-4. Run `npm test` to verify environment is working
-5. Make changes and run tests inside the container
+2. Use "Reopen in Container" (Dev Containers extension required) to enter the dev environment
+3. Wait for dev container initialization to complete
+4. Run `npm test` to verify the dev environment is working
+5. Make changes and run tests inside the dev container
 
 ## Code Change Verification