linting docs + some fixes go claude and gemini

INSTALL.md

@@ -0,0 +1,167 @@
+# Installation Guide
+
+This guide covers setting up a local development environment for Flyer Crawler.
+
+## Prerequisites
+
+- Node.js 20.x or later
+- Access to a PostgreSQL database (local or remote)
+- Redis instance (for session management)
+- Google Gemini API key
+- Google Maps API key (for geocoding)
+
+## Quick Start
+
+If you already have PostgreSQL and Redis configured:
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+```
+
+---
+
+## Development Environment with Podman (Recommended for Windows)
+
+This approach uses Podman with an Ubuntu container for a consistent development environment.
+
+### Step 1: Install Prerequisites on Windows
+
+1. **Install WSL 2**: Podman on Windows relies on the Windows Subsystem for Linux.
+
+   ```powershell
+   wsl --install
+   ```
+
+   Run this in an administrator PowerShell.
+
+2. **Install Podman Desktop**: Download and install [Podman Desktop for Windows](https://podman-desktop.io/).
+
+### Step 2: Set Up Podman
+
+1. **Initialize Podman**: Launch Podman Desktop. It will automatically set up its WSL 2 machine.
+2. **Start Podman**: Ensure the Podman machine is running from the Podman Desktop interface.
+
+### Step 3: Set Up the Ubuntu Container
+
+1. **Pull Ubuntu Image**:
+
+   ```bash
+   podman pull ubuntu:latest
+   ```
+
+2. **Create a Podman Volume** (persists node_modules between container restarts):
+
+   ```bash
+   podman volume create node_modules_cache
+   ```
+
+3. **Run the Ubuntu Container**:
+
+   Open a terminal in your project's root directory and run:
+
+   ```bash
+   podman run -it -p 3001:3001 -p 5173:5173 --name flyer-dev \
+     -v "$(pwd):/app" \
+     -v "node_modules_cache:/app/node_modules" \
+     ubuntu:latest
+   ```
+
+   | Flag                                        | Purpose                                          |
+   | ------------------------------------------- | ------------------------------------------------ |
+   | `-p 3001:3001`                              | Forwards the backend server port                 |
+   | `-p 5173:5173`                              | Forwards the Vite frontend server port           |
+   | `--name flyer-dev`                          | Names the container for easy reference           |
+   | `-v "...:/app"`                             | Mounts your project directory into the container |
+   | `-v "node_modules_cache:/app/node_modules"` | Mounts the named volume for node_modules         |
+
+### Step 4: Configure the Ubuntu Environment
+
+You are now inside the Ubuntu container's shell.
+
+1. **Update Package Lists**:
+
+   ```bash
+   apt-get update
+   ```
+
+2. **Install Dependencies**:
+
+   ```bash
+   apt-get install -y curl git
+   curl -sL https://deb.nodesource.com/setup_20.x | bash -
+   apt-get install -y nodejs
+   ```
+
+3. **Navigate to Project Directory**:
+
+   ```bash
+   cd /app
+   ```
+
+4. **Install Project Dependencies**:
+   ```bash
+   npm install
+   ```
+
+### Step 5: Run the Development Server
+
+```bash
+npm run dev
+```
+
+### Step 6: Access the Application
+
+- **Frontend**: http://localhost:5173
+- **Backend API**: http://localhost:3001
+
+### Managing the Container
+
+| Action                | Command                          |
+| --------------------- | -------------------------------- |
+| Stop the container    | Press `Ctrl+C`, then type `exit` |
+| Restart the container | `podman start -a -i flyer-dev`   |
+| Remove the container  | `podman rm flyer-dev`            |
+
+---
+
+## Environment Variables
+
+This project is configured to run in a CI/CD environment and does not use `.env` files. All configuration must be provided as environment variables.
+
+For local development, you can export these in your shell or use your IDE's environment configuration:
+
+| Variable                    | Description                           |
+| --------------------------- | ------------------------------------- |
+| `DB_HOST`                   | PostgreSQL server hostname            |
+| `DB_USER`                   | PostgreSQL username                   |
+| `DB_PASSWORD`               | PostgreSQL password                   |
+| `DB_DATABASE_PROD`          | Production database name              |
+| `JWT_SECRET`                | Secret string for signing auth tokens |
+| `VITE_GOOGLE_GENAI_API_KEY` | Google Gemini API key                 |
+| `GOOGLE_MAPS_API_KEY`       | Google Maps Geocoding API key         |
+| `REDIS_PASSWORD_PROD`       | Production Redis password             |
+| `REDIS_PASSWORD_TEST`       | Test Redis password                   |
+
+---
+
+## Seeding Development Users
+
+To create initial test accounts (`admin@example.com` and `user@example.com`):
+
+```bash
+npm run seed
+```
+
+After running, you may need to restart your IDE's TypeScript server to pick up any generated types.
+
+---
+
+## Next Steps
+
+- [Database Setup](DATABASE.md) - Set up PostgreSQL with required extensions
+- [Authentication Setup](AUTHENTICATION.md) - Configure OAuth providers
+- [Deployment Guide](DEPLOYMENT.md) - Deploy to production