diff --git a/README.testing.md b/README.testing.md
deleted file mode 100644
index a80abedb..00000000
--- a/README.testing.md
+++ /dev/null
@@ -1,3 +0,0 @@
-using powershell on win10 use this command to run the integration tests only in the container
-
-podman exec -i flyer-crawler-dev npm run test:integration 2>&1 | Tee-Object -FilePath test-output.txt
diff --git a/READMEv2.md b/READMEv2.md
deleted file mode 100644
index f087b0f8..00000000
--- a/READMEv2.md
+++ /dev/null
@@ -1,303 +0,0 @@
-# Flyer Crawler - Development Environment Setup
-
-Quick start guide for getting the development environment running with Podman containers.
-
-## Prerequisites
-
-- **Windows with WSL 2**: Install WSL 2 by running `wsl --install` in an administrator PowerShell
-- **Podman Desktop**: Download and install [Podman Desktop for Windows](https://podman-desktop.io/)
-- **Node.js 20+**: Required for running the application
-
-## Quick Start - Container Environment
-
-### 1. Initialize Podman
-
-```powershell
-# Start Podman machine (do this once after installing Podman Desktop)
-podman machine init
-podman machine start
-```
-
-### 2. Start Required Services
-
-Start PostgreSQL (with PostGIS) and Redis containers:
-
-```powershell
-# Navigate to project directory
-cd D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com
-
-# Start PostgreSQL with PostGIS
-podman run -d \
-  --name flyer-crawler-postgres \
-  -e POSTGRES_USER=postgres \
-  -e POSTGRES_PASSWORD=postgres \
-  -e POSTGRES_DB=flyer_crawler_dev \
-  -p 5432:5432 \
-  docker.io/postgis/postgis:15-3.3
-
-# Start Redis
-podman run -d \
-  --name flyer-crawler-redis \
-  -e REDIS_PASSWORD="" \
-  -p 6379:6379 \
-  docker.io/library/redis:alpine
-```
-
-### 3. Wait for PostgreSQL to Initialize
-
-```powershell
-# Wait a few seconds, then check if PostgreSQL is ready
-podman exec flyer-crawler-postgres pg_isready -U postgres
-# Should output: /var/run/postgresql:5432 - accepting connections
-```
-
-### 4. Install Required PostgreSQL Extensions
-
-```powershell
-podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "CREATE EXTENSION IF NOT EXISTS postgis; CREATE EXTENSION IF NOT EXISTS pg_trgm; CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";"
-```
-
-### 5. Apply Database Schema
-
-```powershell
-# Apply the complete schema with URL constraints enabled
-podman exec -i flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev < sql/master_schema_rollup.sql
-```
-
-### 6. Verify URL Constraints Are Enabled
-
-```powershell
-podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "\d public.flyers" | grep -E "(image_url|icon_url|Check)"
-```
-
-You should see:
-```
- image_url     | text                     |           | not null |
- icon_url      | text                     |           | not null |
-Check constraints:
-    "flyers_icon_url_check" CHECK (icon_url ~* '^https?://.*'::text)
-    "flyers_image_url_check" CHECK (image_url ~* '^https?://.*'::text)
-```
-
-### 7. Set Environment Variables and Start Application
-
-```powershell
-# Set required environment variables
-$env:NODE_ENV="development"
-$env:DB_HOST="localhost"
-$env:DB_USER="postgres"
-$env:DB_PASSWORD="postgres"
-$env:DB_NAME="flyer_crawler_dev"
-$env:REDIS_URL="redis://localhost:6379"
-$env:PORT="3001"
-$env:FRONTEND_URL="http://localhost:5173"
-
-# Install dependencies (first time only)
-npm install
-
-# Start the development server (runs both backend and frontend)
-npm run dev
-```
-
-The application will be available at:
-- **Frontend**: http://localhost:5173
-- **Backend API**: http://localhost:3001
-
-## Managing Containers
-
-### View Running Containers
-```powershell
-podman ps
-```
-
-### Stop Containers
-```powershell
-podman stop flyer-crawler-postgres flyer-crawler-redis
-```
-
-### Start Containers (After They've Been Created)
-```powershell
-podman start flyer-crawler-postgres flyer-crawler-redis
-```
-
-### Remove Containers (Clean Slate)
-```powershell
-podman stop flyer-crawler-postgres flyer-crawler-redis
-podman rm flyer-crawler-postgres flyer-crawler-redis
-```
-
-### View Container Logs
-```powershell
-podman logs flyer-crawler-postgres
-podman logs flyer-crawler-redis
-```
-
-## Database Management
-
-### Connect to PostgreSQL
-```powershell
-podman exec -it flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev
-```
-
-### Reset Database Schema
-```powershell
-# Drop all tables
-podman exec -i flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev < sql/drop_tables.sql
-
-# Reapply schema
-podman exec -i flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev < sql/master_schema_rollup.sql
-```
-
-### Seed Development Data
-```powershell
-npm run db:reset:dev
-```
-
-## Running Tests
-
-### Unit Tests
-```powershell
-npm run test:unit
-```
-
-### Integration Tests
-
-**IMPORTANT**: Integration tests require the PostgreSQL and Redis containers to be running.
-
-```powershell
-# Make sure containers are running
-podman ps
-
-# Run integration tests
-npm run test:integration
-```
-
-## Troubleshooting
-
-### Podman Machine Issues
-If you get "unable to connect to Podman socket" errors:
-```powershell
-podman machine start
-```
-
-### PostgreSQL Connection Refused
-Make sure PostgreSQL is ready:
-```powershell
-podman exec flyer-crawler-postgres pg_isready -U postgres
-```
-
-### Port Already in Use
-If ports 5432 or 6379 are already in use, you can either:
-1. Stop the conflicting service
-2. Change the port mapping when creating containers (e.g., `-p 5433:5432`)
-
-### URL Validation Errors
-The database now enforces URL constraints. All `image_url` and `icon_url` fields must:
-- Start with `http://` or `https://`
-- Match the regex pattern: `^https?://.*`
-
-Make sure the `FRONTEND_URL` environment variable is set correctly to avoid URL validation errors.
-
-## ADR Implementation Status
-
-This development environment implements:
-
-- **ADR-0002**: Transaction Management ✅
-  - All database operations use the `withTransaction` pattern
-  - Automatic rollback on errors
-  - No connection pool leaks
-
-- **ADR-0003**: Input Validation ✅
-  - Zod schemas for URL validation
-  - Database constraints enabled
-  - Validation at API boundaries
-
-## Development Workflow
-
-1. **Start Containers** (once per development session)
-   ```powershell
-   podman start flyer-crawler-postgres flyer-crawler-redis
-   ```
-
-2. **Start Application**
-   ```powershell
-   npm run dev
-   ```
-
-3. **Make Changes** to code (auto-reloads via `tsx watch`)
-
-4. **Run Tests** before committing
-   ```powershell
-   npm run test:unit
-   npm run test:integration
-   ```
-
-5. **Stop Application** (Ctrl+C)
-
-6. **Stop Containers** (optional, or leave running)
-   ```powershell
-   podman stop flyer-crawler-postgres flyer-crawler-redis
-   ```
-
-## PM2 Worker Setup (Production-like)
-
-To test with PM2 workers locally:
-
-```powershell
-# Install PM2 globally (once)
-npm install -g pm2
-
-# Start the worker
-pm2 start npm --name "flyer-crawler-worker" -- run worker:prod
-
-# View logs
-pm2 logs flyer-crawler-worker
-
-# Stop worker
-pm2 stop flyer-crawler-worker
-pm2 delete flyer-crawler-worker
-```
-
-## Next Steps
-
-After getting the environment running:
-
-1. Review [docs/adr/](docs/adr/) for architectural decisions
-2. Check [sql/master_schema_rollup.sql](sql/master_schema_rollup.sql) for database schema
-3. Explore [src/routes/](src/routes/) for API endpoints
-4. Review [src/types.ts](src/types.ts) for TypeScript type definitions
-
-## Common Environment Variables
-
-Create these environment variables for development:
-
-```powershell
-# Database
-$env:DB_HOST="localhost"
-$env:DB_USER="postgres"
-$env:DB_PASSWORD="postgres"
-$env:DB_NAME="flyer_crawler_dev"
-$env:DB_PORT="5432"
-
-# Redis
-$env:REDIS_URL="redis://localhost:6379"
-
-# Application
-$env:NODE_ENV="development"
-$env:PORT="3001"
-$env:FRONTEND_URL="http://localhost:5173"
-
-# Authentication (generate your own secrets)
-$env:JWT_SECRET="your-dev-jwt-secret-change-this"
-$env:SESSION_SECRET="your-dev-session-secret-change-this"
-
-# AI Services (get your own API keys)
-$env:VITE_GOOGLE_GENAI_API_KEY="your-google-genai-api-key"
-$env:GOOGLE_MAPS_API_KEY="your-google-maps-api-key"
-```
-
-## Resources
-
-- [Podman Desktop Documentation](https://podman-desktop.io/docs)
-- [PostGIS Documentation](https://postgis.net/documentation/)
-- [Original README.md](README.md) for production setup
diff --git a/AUTHENTICATION.md b/docs/architecture/AUTHENTICATION.md
similarity index 100%
rename from AUTHENTICATION.md
rename to docs/architecture/AUTHENTICATION.md
diff --git a/DATABASE.md b/docs/architecture/DATABASE.md
similarity index 100%
rename from DATABASE.md
rename to docs/architecture/DATABASE.md
diff --git a/docs/WEBSOCKET_USAGE.md b/docs/architecture/WEBSOCKET_USAGE.md
similarity index 100%
rename from docs/WEBSOCKET_USAGE.md
rename to docs/architecture/WEBSOCKET_USAGE.md
diff --git a/IMPLEMENTATION_STATUS.md b/docs/archive/IMPLEMENTATION_STATUS.md
similarity index 100%
rename from IMPLEMENTATION_STATUS.md
rename to docs/archive/IMPLEMENTATION_STATUS.md
diff --git a/STORE_ADDRESS_IMPLEMENTATION_PLAN.md b/docs/archive/plans/STORE_ADDRESS_IMPLEMENTATION_PLAN.md
similarity index 100%
rename from STORE_ADDRESS_IMPLEMENTATION_PLAN.md
rename to docs/archive/plans/STORE_ADDRESS_IMPLEMENTATION_PLAN.md
diff --git a/docs/research-category-id-migration.md b/docs/archive/research/research-category-id-migration.md
similarity index 100%
rename from docs/research-category-id-migration.md
rename to docs/archive/research/research-category-id-migration.md
diff --git a/docs/research-e2e-test-separation.md b/docs/archive/research/research-e2e-test-separation.md
similarity index 100%
rename from docs/research-e2e-test-separation.md
rename to docs/archive/research/research-e2e-test-separation.md
diff --git a/docs/TESTING_SESSION_2026-01-21.md b/docs/archive/sessions/TESTING_SESSION_2026-01-21.md
similarity index 97%
rename from docs/TESTING_SESSION_2026-01-21.md
rename to docs/archive/sessions/TESTING_SESSION_2026-01-21.md
index 6339bb54..d0502b7e 100644
--- a/docs/TESTING_SESSION_2026-01-21.md
+++ b/docs/archive/sessions/TESTING_SESSION_2026-01-21.md
@@ -42,7 +42,7 @@ podman exec -it flyer-crawler-dev npm run dev:container
 - [ ] Clear localStorage for localhost
 - [ ] Enable responsive design mode (Ctrl+Shift+M)
 
-**Browser Version**: ********\_********
+**Browser Version**: **\*\*\*\***\_**\*\*\*\***
 
 ---
 
@@ -231,7 +231,7 @@ Navigate through app and check teal color consistency:
 Use DevTools color picker on active tab:
 
 - Expected: `#14b8a6` or `rgb(20, 184, 166)`
-- Actual: ********\_\_\_********
+- Actual: **\*\*\*\***\_\_\_**\*\*\*\***
 
 **Status**: [ ] ✅ PASS [ ] ❌ FAIL
 
@@ -486,9 +486,9 @@ Attach screenshots for:
 
 ## 🔐 Sign-Off
 
-**Tester Name**: ****************\_\_\_****************
+**Tester Name**: ******\*\*\*\*******\_\_\_******\*\*\*\*******
 
-**Date/Time Completed**: ************\_\_\_************
+**Date/Time Completed**: ****\*\*\*\*****\_\_\_****\*\*\*\*****
 
 **Total Testing Time**: **\_\_** minutes
 
diff --git a/docs/UI_UX_IMPROVEMENTS_2026-01-20.md b/docs/archive/sessions/UI_UX_IMPROVEMENTS_2026-01-20.md
similarity index 100%
rename from docs/UI_UX_IMPROVEMENTS_2026-01-20.md
rename to docs/archive/sessions/UI_UX_IMPROVEMENTS_2026-01-20.md
diff --git a/docs/DESIGN_TOKENS.md b/docs/development/DESIGN_TOKENS.md
similarity index 100%
rename from docs/DESIGN_TOKENS.md
rename to docs/development/DESIGN_TOKENS.md
diff --git a/docs/TESTING.md b/docs/development/TESTING.md
similarity index 100%
rename from docs/TESTING.md
rename to docs/development/TESTING.md
diff --git a/INSTALL.md b/docs/getting-started/INSTALL.md
similarity index 100%
rename from INSTALL.md
rename to docs/getting-started/INSTALL.md
diff --git a/docs/BARE-METAL-SETUP.md b/docs/operations/BARE-METAL-SETUP.md
similarity index 100%
rename from docs/BARE-METAL-SETUP.md
rename to docs/operations/BARE-METAL-SETUP.md
diff --git a/DEPLOYMENT.md b/docs/operations/DEPLOYMENT.md
similarity index 100%
rename from DEPLOYMENT.md
rename to docs/operations/DEPLOYMENT.md
diff --git a/docs/LOGSTASH-QUICK-REF.md b/docs/operations/LOGSTASH-QUICK-REF.md
similarity index 100%
rename from docs/LOGSTASH-QUICK-REF.md
rename to docs/operations/LOGSTASH-QUICK-REF.md
diff --git a/docs/LOGSTASH-TROUBLESHOOTING.md b/docs/operations/LOGSTASH-TROUBLESHOOTING.md
similarity index 100%
rename from docs/LOGSTASH-TROUBLESHOOTING.md
rename to docs/operations/LOGSTASH-TROUBLESHOOTING.md
diff --git a/README.vscode.md b/docs/tools/VSCODE-SETUP.md
similarity index 98%
rename from README.vscode.md
rename to docs/tools/VSCODE-SETUP.md
index 2de03276..0f10b71b 100644
--- a/README.vscode.md
+++ b/docs/tools/VSCODE-SETUP.md
@@ -22,6 +22,7 @@ MCP (Model Context Protocol) allows AI assistants to interact with external tool
 Access to multiple Gitea instances for repository management, code search, issue tracking, and CI/CD workflows.
 
 #### Gitea Projectium (Primary)
+
 - **Host**: `https://gitea.projectium.com`
 - **Purpose**: Main production Gitea server
 - **Capabilities**:
@@ -31,11 +32,13 @@ Access to multiple Gitea instances for repository management, code search, issue
   - Repository cloning and management
 
 #### Gitea Torbonium
+
 - **Host**: `https://gitea.torbonium.com`
 - **Purpose**: Development/testing Gitea instance
 - **Capabilities**: Same as Gitea Projectium
 
 #### Gitea LAN
+
 - **Host**: `https://gitea.torbolan.com`
 - **Purpose**: Local network Gitea instance
 - **Status**: Disabled (requires token configuration)
@@ -43,6 +46,7 @@ Access to multiple Gitea instances for repository management, code search, issue
 **Executable Location**: `d:\gitea-mcp\gitea-mcp.exe`
 
 **Configuration Example** (Gemini Code - mcp.json):
+
 ```json
 {
   "servers": {
@@ -59,6 +63,7 @@ Access to multiple Gitea instances for repository management, code search, issue
 ```
 
 **Configuration Example** (Claude Code - settings.json):
+
 ```json
 {
   "mcpServers": {
@@ -87,10 +92,12 @@ Manages local containers via Podman Desktop (using Docker-compatible API).
   - Inspect container status and configuration
 
 **Current Containers** (for this project):
+
 - `flyer-crawler-postgres` - PostgreSQL 15 + PostGIS on port 5432
 - `flyer-crawler-redis` - Redis on port 6379
 
 **Configuration** (Gemini Code - mcp.json):
+
 ```json
 {
   "servers": {
@@ -106,6 +113,7 @@ Manages local containers via Podman Desktop (using Docker-compatible API).
 ```
 
 **Configuration** (Claude Code):
+
 ```json
 {
   "mcpServers": {
@@ -133,6 +141,7 @@ Direct file system access to the project directory.
   - Search files
 
 **Configuration** (Gemini Code - mcp.json):
+
 ```json
 {
   "servers": {
@@ -149,6 +158,7 @@ Direct file system access to the project directory.
 ```
 
 **Configuration** (Claude Code):
+
 ```json
 {
   "mcpServers": {
@@ -175,6 +185,7 @@ Web request capabilities for documentation lookups and API testing.
   - Test endpoints
 
 **Configuration** (Gemini Code - mcp.json):
+
 ```json
 {
   "servers": {
@@ -187,6 +198,7 @@ Web request capabilities for documentation lookups and API testing.
 ```
 
 **Configuration** (Claude Code):
+
 ```json
 {
   "mcpServers": {
@@ -211,6 +223,7 @@ Browser automation and debugging capabilities.
   - Network monitoring
 
 **Configuration** (when enabled):
+
 ```json
 {
   "mcpServers": {
@@ -218,9 +231,12 @@ Browser automation and debugging capabilities.
       "command": "npx",
       "args": [
         "chrome-devtools-mcp@latest",
-        "--headless", "false",
-        "--isolated", "false",
-        "--channel", "stable"
+        "--headless",
+        "false",
+        "--isolated",
+        "false",
+        "--channel",
+        "stable"
       ]
     }
   }
@@ -240,6 +256,7 @@ Document conversion capabilities.
   - Convert other document formats
 
 **Configuration** (when enabled):
+
 ```json
 {
   "mcpServers": {
@@ -254,6 +271,7 @@ Document conversion capabilities.
 ## Prerequisites
 
 ### For Podman MCP
+
 1. **Podman Desktop** installed and running
 2. Podman machine initialized and started:
    ```powershell
@@ -262,6 +280,7 @@ Document conversion capabilities.
    ```
 
 ### For Gitea MCP
+
 1. **Gitea MCP executable** at `d:\gitea-mcp\gitea-mcp.exe`
 2. **Gitea Access Tokens** with appropriate permissions:
    - `repo` - Full repository access
@@ -269,10 +288,12 @@ Document conversion capabilities.
    - `read:organization` - Organization access
 
 ### For Chrome DevTools MCP
+
 1. **Chrome browser** installed (stable channel)
 2. **Node.js 18+** for npx execution
 
 ### For Markitdown MCP
+
 1. **Python 3.8+** installed
 2. **uvx** (universal virtualenv executor):
    ```powershell
@@ -282,18 +303,21 @@ Document conversion capabilities.
 ## Testing MCP Servers
 
 ### Test Podman Connection
+
 ```powershell
 podman ps
 # Should list running containers
 ```
 
 ### Test Gitea API Access
+
 ```powershell
 curl -H "Authorization: token YOUR_TOKEN" https://gitea.projectium.com/api/v1/user
 # Should return your user information
 ```
 
 ### Test Database Container
+
 ```powershell
 podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "SELECT version();"
 # Should return PostgreSQL version
@@ -302,19 +326,23 @@ podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "SEL
 ## Security Notes
 
 ### Token Management
+
 - **Never commit tokens** to version control
 - Store tokens in environment variables or secure password managers
 - Rotate tokens periodically
 - Use minimal required permissions
 
 ### Access Tokens in Configuration Files
+
 The configuration files (`mcp.json` and `settings.json`) contain sensitive access tokens. These files should:
+
 - Be added to `.gitignore`
 - Have restricted file permissions
 - Be backed up securely
 - Be updated when tokens are rotated
 
 ### Current Security Setup
+
 - `%APPDATA%\Code\User\mcp.json` - Gitea tokens embedded
 - `%USERPROFILE%\.claude\settings.json` - Gitea tokens embedded
 - Both files are in user-specific directories with appropriate Windows ACLs
@@ -322,6 +350,7 @@ The configuration files (`mcp.json` and `settings.json`) contain sensitive acces
 ## Troubleshooting
 
 ### Podman MCP Not Working
+
 1. Check Podman machine status:
    ```powershell
    podman machine list
@@ -333,6 +362,7 @@ The configuration files (`mcp.json` and `settings.json`) contain sensitive acces
    ```
 
 ### Gitea MCP Connection Issues
+
 1. Verify token has correct permissions
 2. Check network connectivity to Gitea server:
    ```powershell
@@ -341,11 +371,13 @@ The configuration files (`mcp.json` and `settings.json`) contain sensitive acces
 3. Ensure `gitea-mcp.exe` is not blocked by antivirus/firewall
 
 ### VS Code Extension Issues
+
 1. **Reload Window**: Press `Ctrl+Shift+P` → "Developer: Reload Window"
 2. **Check Extension Logs**: View → Output → Select extension from dropdown
 3. **Verify JSON Syntax**: Ensure both config files have valid JSON
 
 ### MCP Server Not Loading
+
 1. Check config file syntax with JSON validator
 2. Verify executable paths are correct (use forward slashes or escaped backslashes)
 3. Ensure required dependencies are installed (Node.js, Python, etc.)
@@ -356,11 +388,13 @@ The configuration files (`mcp.json` and `settings.json`) contain sensitive acces
 To add a new MCP server to both Gemini Code and Claude Code:
 
 1. **Install the MCP server** (if it's an npm package):
+
    ```powershell
    npm install -g @modelcontextprotocol/server-YOUR-SERVER
    ```
 
 2. **Add to Gemini Code** (`mcp.json`):
+
    ```json
    {
      "servers": {
@@ -375,6 +409,7 @@ To add a new MCP server to both Gemini Code and Claude Code:
    ```
 
 3. **Add to Claude Code** (`settings.json`):
+
    ```json
    {
      "mcpServers": {
@@ -392,10 +427,12 @@ To add a new MCP server to both Gemini Code and Claude Code:
 ## Current Project Integration
 
 ### ADR Implementation Status
+
 - **ADR-0002**: Transaction Management ✅ Enforced
 - **ADR-0003**: Input Validation ✅ Enforced with URL validation
 
 ### Database Setup
+
 - PostgreSQL 15 + PostGIS running in container
 - 63 tables created
 - URL constraints active:
@@ -403,6 +440,7 @@ To add a new MCP server to both Gemini Code and Claude Code:
   - `flyers_icon_url_check` enforces `^https?://.*`
 
 ### Development Workflow
+
 1. Start containers: `podman start flyer-crawler-postgres flyer-crawler-redis`
 2. Use MCP servers to manage development environment
 3. AI assistants can:
@@ -421,6 +459,7 @@ To add a new MCP server to both Gemini Code and Claude Code:
 ## Maintenance
 
 ### Regular Tasks
+
 - **Monthly**: Rotate Gitea access tokens
 - **Weekly**: Update MCP server packages:
   ```powershell
@@ -429,7 +468,9 @@ To add a new MCP server to both Gemini Code and Claude Code:
 - **As Needed**: Update Gitea MCP executable when new version is released
 
 ### Backup Configuration
+
 Recommended to backup these files regularly:
+
 - `%APPDATA%\Code\User\mcp.json`
 - `%USERPROFILE%\.claude\settings.json`
 
@@ -442,6 +483,7 @@ This project uses Gitea Actions for continuous integration and deployment. The w
 #### Automated Workflows
 
 **deploy-to-test.yml** - Automated deployment to test environment
+
 - **Trigger**: Automatically on every push to `main` branch
 - **Runner**: `projectium.com` (self-hosted)
 - **Process**:
@@ -459,6 +501,7 @@ This project uses Gitea Actions for continuous integration and deployment. The w
 #### Manual Workflows
 
 **deploy-to-prod.yml** - Manual deployment to production
+
 - **Trigger**: Manual via workflow_dispatch
 - **Confirmation Required**: Must type "deploy-to-prod"
 - **Process**:
@@ -471,28 +514,34 @@ This project uses Gitea Actions for continuous integration and deployment. The w
 - **Optional**: Force PM2 reload even if version matches
 
 **manual-db-backup.yml** - Database backup workflow
+
 - Creates timestamped backup of production database
 - Stored in `/var/backups/postgres/`
 
 **manual-db-restore.yml** - Database restore workflow
+
 - Restores production database from backup file
 - Requires confirmation and backup filename
 
 **manual-db-reset-test.yml** - Reset test database
+
 - Drops and recreates test database schema
 - Used for testing schema migrations
 
 **manual-db-reset-prod.yml** - Reset production database
+
 - **DANGER**: Drops and recreates production database
 - Requires multiple confirmations
 
 **manual-deploy-major.yml** - Major version deployment
+
 - Similar to deploy-to-prod but bumps major version
 - For breaking changes or major releases
 
 ### Accessing Workflows via Gitea MCP
 
 With the Gitea MCP server configured, AI assistants can:
+
 - View workflow files
 - Monitor workflow runs
 - Check deployment status
@@ -500,6 +549,7 @@ With the Gitea MCP server configured, AI assistants can:
 - Trigger manual workflows (via API)
 
 **Example MCP Operations**:
+
 ```bash
 # Via Gitea MCP, you can:
 # - List recent workflow runs
@@ -514,6 +564,7 @@ With the Gitea MCP server configured, AI assistants can:
 The workflows use these Gitea repository secrets:
 
 **Database**:
+
 - `DB_HOST` - PostgreSQL host
 - `DB_USER` - Database user
 - `DB_PASSWORD` - Database password
@@ -521,15 +572,18 @@ The workflows use these Gitea repository secrets:
 - `DB_DATABASE_TEST` - Test database name
 
 **Redis**:
+
 - `REDIS_PASSWORD_PROD` - Production Redis password
 - `REDIS_PASSWORD_TEST` - Test Redis password
 
 **API Keys**:
+
 - `VITE_GOOGLE_GENAI_API_KEY` - Production Gemini API key
 - `VITE_GOOGLE_GENAI_API_KEY_TEST` - Test Gemini API key
 - `GOOGLE_MAPS_API_KEY` - Google Maps Geocoding API key
 
 **Authentication**:
+
 - `JWT_SECRET` - JWT signing secret
 
 ### Schema Migration Process
@@ -542,6 +596,7 @@ The workflows use a schema hash comparison system:
 4. **Protection**: Deployment fails if schemas don't match
 
 **Manual Migration Steps** (when schema changes):
+
 1. Update `sql/master_schema_rollup.sql`
 2. Run manual migration workflow or:
    ```bash
@@ -554,16 +609,19 @@ The workflows use a schema hash comparison system:
 The workflows manage three PM2 processes per environment:
 
 **Production** (`ecosystem.config.cjs --env production`):
+
 - `flyer-crawler-api` - Express API server
 - `flyer-crawler-worker` - Background job worker
 - `flyer-crawler-analytics-worker` - Analytics processor
 
 **Test** (`ecosystem.config.cjs --env test`):
+
 - `flyer-crawler-api-test` - Test Express API server
 - `flyer-crawler-worker-test` - Test background worker
 - `flyer-crawler-analytics-worker-test` - Test analytics worker
 
 **Process Cleanup**:
+
 - Workflows automatically delete errored/stopped processes
 - Version comparison prevents unnecessary reloads
 - Force reload option available for production
@@ -605,17 +663,20 @@ Using Gitea MCP, you can monitor deployments in real-time:
 With the configured MCP servers, you can:
 
 **Via Gitea MCP**:
+
 - Trigger manual workflows
 - View deployment history
 - Monitor test results
 - Access workflow logs
 
 **Via Podman MCP**:
+
 - Inspect container logs (for local testing)
 - Manage local database containers
 - Test migrations locally
 
 **Via Filesystem MCP**:
+
 - Review workflow files
 - Edit deployment scripts
 - Update ecosystem config