vault backup: 2026-05-18 19:13:44

2026-05-18 19:13:44 +01:00 · 2026-05-18 19:13:44 +01:00 · 0c5b1d72af
commit 0c5b1d72af
parent bfd6001ac4
10 changed files with 1146 additions and 0 deletions
--- a/Projects/cinema-studio-pro-kling/DEVELOPER_MANUAL.md
+++ b/Projects/cinema-studio-pro-kling/DEVELOPER_MANUAL.md
@ -0,0 +1,121 @@
+---
+auto_generated: true
+manual_updated_at: 2026-05-18
+modified: 2026-05-18
+---
+
+# Developer Manual: Lux Studio (Cinema Studio Pro)
+
+## Architecture Overview
+
+Lux Studio is a single-page application (SPA) with a hybrid backend for file management and API proxying.
+
+- **Frontend:** React 19 app built with Vite, styled with Tailwind CSS. Handles all UI state, IndexedDB storage, and AI API interactions.
+- **Backend:** Lightweight PHP 7.4+ Apache application. Handles authentication proxying, file uploads/downloads, video streaming, and session management.
+- **Storage:** 
+  - **Client-side:** IndexedDB for project metadata and asset data (base64/images).
+  - **Server-side:** Session files for temporary uploads and large video storage, auto-cleaned every 24 hours.
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Frontend** | React 19, Vite, Tailwind CSS, Lucide-React (Icons), MSAL React (Auth) |
+| **Backend** | PHP 7.4+, Apache, Composer |
+| **AI** | Google Gemini API (Imagen 3 for images, Veo 3.1 for videos) |
+| **Auth** | @azure/msal-browser + @azure/msal-react (Optional Azure AD SSO) |
+| **Database** | IndexedDB (Dexie.js or native API) |
+| **Containerization** | Docker/Docker Compose |
+
+## Local Setup
+
+### Prerequisites
+- Node.js 18+
+- PHP 7.4+
+- Composer
+- Google Gemini API Key
+
+### Step 1: Backend Setup
+1. Install PHP dependencies:
+   ```bash
+   cd backend
+   composer install
+   ```
+2. Create `.env` file in `backend/` with your Google API key:
+   ```env
+   GEMINI_API_KEY=your_google_api_key_here
+   ```
+3. Start the PHP built-in server:
+   ```bash
+   php -S localhost:5015 -t api/
+   ```
+
+### Step 2: Frontend Setup
+1. Install dependencies:
+   ```bash
+   cd frontend
+   npm install
+   ```
+2. Create `.env` file in `frontend/`:
+   ```env
+   VITE_API_URL=http://localhost:5015
+   # Optional: Azure AD Config if SSO is enabled
+   # VITE_MSA_CLIENT_ID=...
+   # VITE_MSA_TENANT_ID=...
+   ```
+3. Start the Vite dev server:
+   ```bash
+   npm run dev
+   ```
+   The frontend will proxy API requests to `localhost:5015` automatically.
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `GEMINI_API_KEY` | Google AI Studio API Key for Imagen/Veo access | Yes (Backend) |
+| `VITE_API_URL` | Backend API URL for production | Yes (Frontend) |
+| `VITE_MSA_CLIENT_ID` | Azure AD Client ID for SSO | No |
+| `VITE_MSA_TENANT_ID` | Azure AD Tenant ID for SSO | No |
+
+## Key Services & Entry Points
+
+### Frontend Components
+- **`frontend/src/main.jsx`**: Entry point. Initializes MSAL instance before mounting the React tree. Handles SSO configuration.
+- **`frontend/src/App.jsx`**: Root component wrapper. Delegates to `AppContent`.
+- **`frontend/src/components/ProjectsTab.jsx`**: Core workspace UI. Manages project lifecycle (create, delete, rename) and asset display.
+- **`frontend/src/components/VideoGenTab.jsx`**: UI for video generation settings and status. Handles Kling/Veo engine selection.
+- **`frontend/src/components/VideoPlayer.jsx`**: Custom video player with frame extraction capabilities. Handles URL conversion for streaming videos via backend.
+- **`frontend/src/components/AdminSettings.jsx`**: Admin panel for managing Kling API keys and testing connectivity.
+
+### Backend API Endpoints
+- **`admin_api.php?action=status`**: Returns current Kling service status.
+- **`admin_api.php?action=test_kling`**: Tests Kling API keys (POST with `access_key` and `secret_key`).
+- **`admin_api.php?action=update_kling`**: Saves Kling API credentials.
+- **`stream_video.php?file=<filename>`**: Streams video files from the uploads directory.
+- **`/api/imagen/generate`**: (Proxy) Sends image generation requests to Google Imagen 3.
+- **`/api/veo/generate`**: (Proxy) Sends video generation requests to Google Veo 3.1.
+
+## Deployment
+
+### Docker Production Build
+Use `docker-compose.prod.yml` to deploy:
+1. Ensure `backend/.env.optical` contains valid environment variables.
+2. Run:
+   ```bash
+   docker-compose -f docker-compose.prod.yml up -d
+   ```
+3. The app will be available at `http://127.0.0.1:8085`.
+
+### CI/CD Notes
+- Frontend build outputs to `dist/`.
+- Backend PHP files are served directly.
+- Ensure `uploads` volume is persisted if long-term video storage is needed (currently auto-cleaned).
+
+## Known Gotchas
+
+1. **MSAL Initialization:** MSAL v3 must be fully initialized (`await msalInstance.initialize()`) before rendering components that use `useMsal()`. This is handled in `main.jsx`.
+2. **Video Streaming:** The frontend converts `/generated_videos/` paths to backend stream URLs. Ensure the backend `uploads` directory is writable and the filename encoding matches.
+3. **CORS:** During local development, use the Vite proxy (`/api/*` -> `localhost:5015`) to avoid CORS issues with the PHP backend.
+4. **IndexedDB Limits:** Storing large base64 images/videos in IndexedDB can exceed quota limits. The app should implement chunking or offloading to the backend for large assets in production.
+5. **Kling Integration:** The Kling workflow is optional. Ensure `klingWorkflow` state in `VideoGenTab.jsx` defaults correctly if Kling is not configured in `AdminSettings`.
--- a/Projects/cinema-studio-pro-kling/USER_MANUAL.md
+++ b/Projects/cinema-studio-pro-kling/USER_MANUAL.md
@ -0,0 +1,85 @@
+---
+auto_generated: true
+manual_updated_at: 2026-05-18
+modified: 2026-05-18
+---
+
+# User Manual: Lux Studio (Cinema Studio Pro)
+
+## What This Tool Does
+
+Lux Studio is an AI-powered cinematography suite designed for professional image and video generation. It combines physics-based prompt engineering with Google's Imagen 3 (for images) and Veo 3.1 (for video) APIs. 
+
+**Key Capabilities:**
+- **Cinematic Image Generation:** Create high-quality images using professional camera body profiles (sensor behavior, dynamic range, grain) and lens profiles (bokeh, flares, chromatic aberration).
+- **AI Video Production:** Generate videos from text or images, support first/last-frame interpolation, and extract frames.
+- **Project Management:** Organize all assets within persistent projects. Data is stored locally in your browser via IndexedDB, so no server account is required to start.
+- **Storyboarding:** Animate and reorder panels to create storyboards, with PDF export capabilities.
+
+## Who Uses It
+
+- **Filmmakers & Directors:** To visualize scenes before shooting.
+- **Concept Artists:** To rapidly iterate on character and environment designs.
+- **Content Creators:** To produce AI-generated video clips for social media or presentations.
+
+## How to Access
+
+### Live Web Application
+Access the live environment here: [Lux Studio Live](https://ai-sandbox.oliver.solutions/lux-studio/)
+
+### Authentication
+- **SSO:** The application supports Microsoft Azure AD Single Sign-On (SSO). If your organization has configured this, you will be prompted to log in upon first access.
+- **No Account Required for Local Dev:** If running locally without Azure AD configuration, you can use the app without external authentication.
+
+## Main Workflows
+
+### 1. Creating a Project
+1. Navigate to the **Projects** tab.
+2. Click **New Project** (Folder Plus icon).
+3. Name your project. All subsequent images and videos will be tied to this workspace.
+
+### 2. Generating Cinematic Images (Imagen 3)
+1. Go to the **Image Generation** tab.
+2. Enter a prompt describing your scene.
+3. **Refine Settings:**
+   - **Camera Body:** Select from 8 cinema camera profiles to adjust dynamic range and grain.
+   - **Lens Profile:** Choose from 10 lenses to control bokeh and flares.
+   - **Lighting:** Apply one of 40+ cinematic lighting presets.
+4. **Style Transfer:** Upload up to 14 reference images to influence the style.
+5. Click **Generate**. Once complete, you can use the **Edit Mode** to refine the image with follow-up prompts.
+
+### 3. Producing AI Videos (Veo 3.1)
+1. Go to the **Video Generation** tab.
+2. Select your **Engine** (Veo 3.1 or Kling, if configured).
+3. Enter a text description or upload a **Reference Image** (for Image-to-Video).
+4. Configure settings:
+   - **Model:** Standard (higher quality) or Fast.
+   - **Duration:** 4s, 6s, or 8s.
+   - **Mode:** Text-to-Video or Image-to-Video (First/Last frame interpolation).
+5. Click **Generate**. Wait for the processing to complete.
+6. **Playback:** Use the built-in video player to watch, scrub, or extract frames.
+7. **Save:** Click **Save to Project** to store the video in your active project workspace.
+
+### 4. Storyboarding
+1. In the **Projects** tab, open a project.
+2. Click **Create Storyboard**.
+3. Drag and drop images/videos from your project onto the storyboard panels.
+4. Reorder panels by dragging them.
+5. Export the final storyboard as a PDF.
+
+## FAQ
+
+**Q: Where is my data stored?**
+A: All projects, images, and videos are stored locally in your browser using IndexedDB. No data is sent to external servers except for the AI generation API requests.
+
+**Q: Can I edit a generated image?**
+A: Yes. In the Image Generation tab, select a generated image and use the "Edit Mode" feature to provide a new prompt that refines the existing result.
+
+**Q: How do I export my work?**
+A: In the Projects tab, you can download individual items (images/videos) or export an entire project as a package. Storyboards can be exported as PDFs.
+
+**Q: Why does my video fail to play?**
+A: Ensure your browser supports the video codec used by the API (usually H.264/MP4). If using the local dev environment, ensure the backend PHP server is running and the video files are correctly streamed via `stream_video.php`.
+
+**Q: Is my data private?**
+A: Yes. Since storage is local (IndexedDB) and AI processing happens via Google's API, no generated assets are stored on Lux Studio's servers. Authentication is handled securely via MSAL if SSO is enabled.
--- a/Projects/cinema-studio-pro/DEVELOPER_MANUAL.md
+++ b/Projects/cinema-studio-pro/DEVELOPER_MANUAL.md
@ -0,0 +1,140 @@
+---
+auto_generated: true
+manual_updated_at: 2026-05-18
+modified: 2026-05-18
+---
+
+# Lux Studio Developer Manual
+
+## Architecture Overview
+
+Lux Studio is a Single Page Application (SPA) built with React 19, leveraging Vite for fast development builds and Tailwind CSS for styling. It follows a project-first architecture where all assets (images/videos) are tied to a specific project entity managed via IndexedDB.
+
+- **Frontend**: React 19 + Vite + Tailwind CSS.
+- **State Management**: Custom hooks (`useProjects`, `useCustomPresets`) manage local state and IndexedDB interactions.
+- **Authentication**: Optional Microsoft Azure AD SSO via `@azure/msal-browser` and `@azure/msal-react`.
+- **Backend**: Minimal PHP backend (Apache) handles API proxying and file streaming. No separate backend service is required.
+- **AI Integration**: Calls to Google Gemini API for Imagen 3 (images) and Veo 3.1 (video), and potentially Kling APIs via a custom proxy.
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Frontend Framework | React 19 |
+| Build Tool | Vite |
+| Styling | Tailwind CSS |
+| State/Storage | IndexedDB (via custom hooks) |
+| Auth | MSAL (Azure AD) |
+| Backend | PHP 7.4+ (Apache) |
+| AI Providers | Google Gemini (Imagen 3, Veo 3.1), Kling (via proxy) |
+
+## Local Setup
+
+### Prerequisites
+- Node.js 18+
+- PHP 7.4+
+- Composer
+- Google Gemini API Key (available at https://aistudio.google.com/app/apikey)
+
+### Installation Steps
+
+1. **Clone the Repository**
+   ```bash
+   git clone <repo-url>
+   cd lux-studio
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Configure Environment**
+   Create `.env` files in the `frontend/` and `backend/` directories.
+   - `frontend/.env.local`:
+     ```env
+     VITE_API_URL=http://localhost:5015
+     VITE_GEMINI_API_KEY=your_gemini_key_here
+     VITE_IS_SSO_ENABLED=false
+     ```
+   - `backend/.env`:
+     ```env
+     GEMINI_API_KEY=your_gemini_key_here
+     ```
+
+4. **Start Development Servers**
+   - **Backend**: Ensure Apache is running and configured to serve the `backend/` directory. Point `VITE_API_URL` in frontend env to your Apache host (e.g., `http://localhost:5015`).
+   - **Frontend**:
+     ```bash
+     npm run dev
+     ```
+
+5. **Access the App**
+   Open http://localhost:5173 in your browser.
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `VITE_API_URL` | Backend URL for proxying API calls | Yes |
+| `VITE_GEMINI_API_KEY` | Google Gemini API Key | Yes |
+| `VITE_IS_SSO_ENABLED` | Toggle Azure AD SSO (`true`/`false`) | No |
+
+## Key Services & Entry Points
+
+### 1. Authentication (`frontend/src/authConfig.js`)
+- Manages MSAL configuration.
+- `isSSOEnabled()` checks environment variables.
+- Initialization occurs in `main.jsx` before React render.
+
+### 2. Data Persistence (`frontend/src/hooks/useProjects.js`)
+- Handles all IndexedDB interactions.
+- Exports methods: `createProject`, `deleteProject`, `addItemToProject`, `exportProject`, etc.
+- No server-side database; pure client-side storage.
+
+### 3. AI Integration
+- **Image Generation**: Uses Google Imagen 3 via Gemini API. Logic resides in components calling the backend proxy.
+- **Video Generation**: Uses Veo 3.1 or Kling. The `VideoGenTab` component handles complex state for model selection, prompt optimization, and task polling.
+
+### 4. Video Playback (`frontend/src/components/VideoPlayer.jsx`)
+- Custom video player with frame extraction capabilities.
+- Handles URL conversion for streaming via `stream_video.php`.
+- Uses canvas to extract frames as PNGs.
+
+## API Reference
+
+The backend PHP scripts act as a proxy to AI providers and handle file management.
+
+### Streaming Videos
+- **Endpoint**: `/stream_video.php?file=<filename>`
+- **Description**: Streams video files from the `generated_videos/` directory.
+- **Method**: GET
+
+### Generating Content
+- **Endpoint**: `/api/generate_image.php` or `/api/generate_video.php`
+- **Description**: Proxies requests to Google/Kling APIs.
+- **Method**: POST
+- **Payload**: JSON object containing prompt, model type, aspect ratio, and reference images.
+
+### Storyboard Export
+- **Endpoint**: `/api/export_storyboard.php`
+- **Description**: Generates a PDF from storyboard data.
+- **Method**: POST
+
+## Deployment
+
+1. **Production Build**:
+   ```bash
+   npm run build
+   ```
+2. **Configure Backend**: Ensure Apache is configured to serve the `backend/` directory and proxy requests to Google APIs securely.
+3. **Environment**: Set `VITE_IS_SSO_ENABLED=true` in production `.env` if using Azure AD.
+4. **Hosting**: Deploy the `dist/` folder to a static host and the `backend/` folder to an Apache server.
+
+## Known Gotchas
+
+1. **CORS**: In development, use the Vite proxy. In production, ensure the backend handles CORS headers correctly for AI API requests.
+2. **IndexedDB Limits**: Browser storage quotas may apply. Large projects with many high-res videos might hit limits. Encourage users to download assets regularly.
+3. **MSAL Initialization**: MSAL must be initialized before React renders. The `main.jsx` async wrapper handles this, but errors here will crash the app.
+4. **Video Formats**: The `VideoPlayer` component assumes standard MP4/MKV formats. Unsupported codecs may fail to play or extract frames.
+5. **AI Latency**: Video generation can take several minutes. Ensure the UI shows clear loading states and does not timeout prematurely.
--- a/Projects/cinema-studio-pro/USER_MANUAL.md
+++ b/Projects/cinema-studio-pro/USER_MANUAL.md
@ -0,0 +1,88 @@
+---
+auto_generated: true
+manual_updated_at: 2026-05-18
+modified: 2026-05-18
+---
+
+# Lux Studio User Manual
+
+## What This Tool Does
+
+Lux Studio is an AI-powered cinematography suite designed for professional image and video generation. It combines physics-based prompt engineering with advanced AI models (Google Imagen 3 for images and Veo 3.1/Kling for video) to help filmmakers, directors, and creators produce high-quality cinematic content.
+
+Key capabilities include:
+- **Image Generation**: Create cinematic images with professional camera bodies, lens profiles, lighting presets, and style transfer capabilities.
+- **Video Generation**: Produce AI-generated videos from text or images, with options for duration, aspect ratio, and audio generation.
+- **Project Management**: Organize all assets within a project-first workflow, with persistent storage in your browser.
+- **Storyboarding**: Animate and arrange panels, reorder them via drag-and-drop, and export to PDF.
+
+## Who Uses It
+
+- **Filmmakers & Directors**: For pre-visualization, storyboarding, and concept art.
+- **Content Creators**: For generating background visuals, transitions, and specific cinematic effects.
+- **Photographers & Designers**: For exploring lighting setups and camera profiles without physical equipment.
+
+## How to Access
+
+- **Live Application**: https://ai-sandbox.oliver.solutions/lux-studio/
+- **Authentication**: Lux Studio supports Microsoft Azure AD Single Sign-On (SSO). Ensure you are logged into your corporate or personal Microsoft account to access SSO features if enabled in your environment.
+
+## Main Workflows
+
+### 1. Creating a Project
+1. Navigate to the **Projects Tab**.
+2. Click the **New Project** icon (usually a folder with a plus sign).
+3. Name your project and save it. Assets generated within this workflow will be stored here.
+
+### 2. Generating Cinematic Images (Imagen 3)
+1. Go to the **Image Generation** tab (or project workspace if initiated from there).
+2. **Configure Settings**:
+   - Select a **Camera Body** (8 profiles available, affecting grain and dynamic range).
+   - Select a **Lens Profile** (10 profiles affecting bokeh, flares, and aberration).
+   - Choose a **Lighting Preset** (40+ cinematic lighting options).
+3. **Refine Prompt**: Use the physics-based prompt engineering tools to adjust lighting and camera behavior.
+4. **Reference Images**: Upload up to 14 reference images for style transfer or editing.
+5. Click **Generate**. Your image will appear in the project workspace.
+6. **Edit Mode**: Use follow-up prompts to refine specific aspects of the generated image.
+
+### 3. Generating Videos (Veo 3.1 / Kling)
+1. Navigate to the **Video Generation** tab.
+2. **Select Engine**: Choose between Veo 3.1 (Google) or Kling (alternative provider).
+3. **Input Method**:
+   - **Text-to-Video**: Enter a detailed scene description.
+   - **Image-to-Video**: Upload a reference image (first or last frame).
+4. **Configure Settings**:
+   - **Model**: Select Standard or Fast.
+   - **Duration**: Choose 4s, 6s, or 8s.
+   - **Aspect Ratio**: Select Landscape, Portrait, or Square.
+   - **Audio**: Toggle audio generation on/off.
+5. Click **Generate**. Monitor progress via the loading indicator.
+6. **Review & Extract**: Use the video player to watch the result. You can extract specific frames to PNG for use as storyboard panels or reference images.
+
+### 4. Storyboard Editor
+1. From the **Projects Tab**, select a project.
+2. Open the **Storyboard Editor**.
+3. **Add Panels**: Drag generated images/videos from the project list into the storyboard grid.
+4. **Reorder**: Drag panels to change the sequence.
+5. **Annotate**: Add notes or descriptions to individual panels.
+6. **Export**: Click the **PDF Export** button to download your storyboard.
+
+## FAQ
+
+**Q: Do I need to create an account?**
+A: No. Lux Studio stores all project data locally in your browser using IndexedDB. No server-side account is required for basic functionality.
+
+**Q: How is my data stored?**
+A: Your projects, images, and videos are stored locally in your browser. No data is uploaded to external servers except for the AI generation process (handled by Google/Kling APIs).
+
+**Q: Can I edit generated videos?**
+A: Currently, you can extract frames and use them as references for new generations. Direct video editing is not yet supported, but frame extraction allows for manual compositing in external tools.
+
+**Q: What happens if my browser cache is cleared?**
+A: Since data is stored in IndexedDB, clearing browser data will result in loss of your projects. Ensure you export important storyboards or download assets regularly.
+
+**Q: How do I use style transfer?**
+A: Upload reference images in the Image Generation tab. The AI will analyze the style and apply it to your new generation.
+
+**Q: Is the application mobile-friendly?**
+A: Lux Studio is optimized for desktop workflows. While it may function on tablets, the complex interface is best experienced on a large screen.
--- a/Projects/hp-prod-tracker/DEVELOPER_MANUAL.md
+++ b/Projects/hp-prod-tracker/DEVELOPER_MANUAL.md
@ -0,0 +1,172 @@
+---
+auto_generated: true
+manual_updated_at: 2026-05-18
+modified: 2026-05-18
+---
+
+# HP CG Production Tracker - Developer Manual
+
+## Architecture Overview
+
+The application is a full-stack web application built with Next.js 16 (App Router). It follows a client-server architecture with server-side rendering (SSR) and client-side hydration.
+
+- **Frontend:** React 19+ with App Router, Tailwind CSS 4, and shadcn/ui components.
+- **State Management:** TanStack Query v5 for server state, Zustand for client state.
+- **Data Layer:** Prisma 7 ORM connected to PostgreSQL 17 with pgvector for semantic search capabilities.
+- **Authentication:** Auth.js v5 integrated with Microsoft Entra ID (Azure AD) using PKCE flow for SPA.
+- **AI Integration:** Dual-provider AI setup using Anthropic (Claude) and Ollama (local/fallback) for chat and embeddings.
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Framework | Next.js 16 (App Router, Turbopack) |
+| Language | TypeScript 5.9 |
+| Styling | Tailwind CSS 4 + shadcn/ui (Radix) |
+| Database | PostgreSQL 17 + pgvector + Prisma 7 |
+| Auth | Auth.js v5 (Microsoft Entra ID SSO) |
+| State | TanStack Query v5 + Zustand |
+| Forms | React Hook Form + Zod v4 |
+| AI Chat | Claude API + Ollama (dual provider) |
+| Embeddings | Ollama (nomic-embed-text) |
+| Charts | Recharts |
+| Media | Sharp (images), FFmpeg + HLS.js (video) |
+| PDF | @react-pdf/renderer |
+| Deployment | Docker + Docker Compose |
+
+## Local Setup
+
+### Prerequisites
+- Node.js 18+
+- Docker & Docker Compose
+- PostgreSQL 17 (or use Docker compose)
+- Local Ollama instance (optional, for local AI)
+
+### Steps
+
+1. **Clone the Repository**
+   ```bash
+   git clone <repo-url>
+   cd hp-prod-tracker
+   ```
+
+2. **Environment Configuration**
+   Copy `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+   Update the following variables:
+   - `DATABASE_URL`: Connect to your local DB (default `postgresql://postgres:postgres@localhost:5432/hp_prod_tracker`)
+   - `AUTH_SECRET`: Generate with `openssl rand -base64 32`
+   - `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_REDIRECT_URI`: From your Azure AD App Registration.
+   - `ANTHROPIC_API_KEY`: For primary AI chat.
+   - `OLLAMA_HOST`: Set to `http://localhost:11434` if running Ollama locally.
+
+3. **Start Infrastructure**
+   ```bash
+   docker compose up -d db
+   ```
+   This starts PostgreSQL with pgvector enabled.
+
+4. **Install Dependencies**
+   ```bash
+   npm install
+   ```
+
+5. **Run Database Migrations**
+   ```bash
+   npx prisma migrate dev
+   ```
+
+6. **Start the Application**
+   ```bash
+   npm run dev
+   ```
+   The app will be available at `http://localhost:3000`.
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `DATABASE_URL` | PostgreSQL connection string | Yes |
+| `AUTH_SECRET` | Secret for session management | Yes |
+| `AZURE_CLIENT_ID` | Azure AD Application Client ID | Yes |
+| `AZURE_TENANT_ID` | Azure AD Tenant ID | Yes |
+| `AZURE_REDIRECT_URI` | Login page URL registered in Azure | Yes |
+| `DEV_BYPASS_AUTH` | Set to `true` to skip SSO in dev | No |
+| `ANTHROPIC_API_KEY` | API key for Claude AI | No |
+| `OLLAMA_HOST` | URL for local Ollama instance | No |
+| `CRON_SECRET` | Secret for cron job verification | No |
+
+## Key Services & Entry Points
+
+### 1. Authentication (`src/app/api/auth/[...nextauth]/route.ts`)
+- Implements Auth.js v5.
+- Uses Microsoft Entra ID provider.
+- In dev mode, if `DEV_BYPASS_AUTH=true`, it auto-logs in as `DEV_USER_ID`.
+
+### 2. Database Schema (`prisma/schema.prisma`)
+- Defines models for `Project`, `Deliverable`, `Stage`, `User`, etc.
+- Uses `pgvector` for embedding vectors in `Deliverable` for semantic search.
+
+### 3. AI Services (`src/ai/`)
+- **Embeddings:** Uses `nomic-embed-text` via Ollama.
+- **Chat:** Primary provider is Claude (Anthropic), with Ollama (`gemma4` or `qwen3`) as fallback.
+
+### 4. Pipeline Logic
+- Enforced in Prisma relations and backend middleware.
+- Critical gates (Stage 3, 5) block updates if not approved.
+
+### 5. UI Components
+- **`src/components/command-palette.tsx`**: Global command palette (`Cmd+K`).
+- **`src/components/theme-provider.tsx`**: Next-themes integration.
+- **`src/components/query-provider.tsx`**: TanStack Query client setup.
+
+## API Reference
+
+### Health Check
+- **GET** `/api/health`
+  - Returns `200 OK` if the app and DB are healthy.
+
+### Auth
+- **POST** `/api/auth/signin` (Handled by Auth.js)
+- **POST** `/api/auth/signout` (Handled by Auth.js)
+
+### Projects
+- **GET** `/api/projects`
+  - Returns list of projects (filtered by auth).
+- **POST** `/api/projects`
+  - Create a new project.
+
+### Deliverables
+- **GET** `/api/projects/[projectId]/deliverables`
+  - List deliverables for a project.
+- **PATCH** `/api/projects/[projectId]/deliverables/[deliverableId]`
+  - Update status or files.
+
+## Deployment
+
+### Docker Compose Deployment
+The `docker-compose.yml` defines:
+- `db`: PostgreSQL 17 with pgvector.
+- `app`: Next.js container.
+
+**Production Steps:**
+1. Build the Docker image:
+   ```bash
+   docker compose build
+   ```
+2. Run the stack:
+   ```bash
+   docker compose up -d
+   ```
+3. Ensure `NODE_ENV=production` and all sensitive env vars are set securely.
+4. Configure Azure AD redirect URI to point to the production domain.
+
+## Known Gotchas
+
+1. **Critical Gates:** Developers must ensure the DB triggers or Prisma middleware correctly block status updates if prerequisites are incomplete. Bypassing this logic will corrupt pipeline integrity.
+2. **AI Fallback:** If `ANTHROPIC_API_KEY` is not set, the app falls back to Ollama. Ensure Ollama is running and the model `gemma4` or `qwen3` is pulled.
+3. **PKCE Flow:** Since this is an SPA, do not use `AZURE_CLIENT_SECRET`. Ensure the Azure App Registration is set up as a "Single Page Application" with PKCE.
+4. **Vector Search:** Ensure `pgvector` is enabled in PostgreSQL. The Docker volume `./docker/db-init.sql` handles this, but verify it runs on DB restart.
+5. **File Uploads:** Media uploads are stored in `uploads_data` volume. Ensure the Docker user has write permissions to `/data/uploads`.
--- a/Projects/hp-prod-tracker/USER_MANUAL.md
+++ b/Projects/hp-prod-tracker/USER_MANUAL.md
@ -0,0 +1,112 @@
+---
+auto_generated: true
+manual_updated_at: 2026-05-18
+modified: 2026-05-18
+---
+
+# HP CG Production Tracker - User Manual
+
+## What This Tool Does
+
+The HP CG Production Tracker is a unified web application designed to replace fragmented workflows involving Workfront, Excel spreadsheets, and the OMG platform. It provides real-time visibility into the status of every deliverable across the entire Computer Graphics (CG) pipeline for the HP CG department.
+
+**Key Capabilities:**
+- **Real-time Dashboard:** Overview of active projects, deliverable counts, overdue items, and pipeline completion rates.
+- **10-Stage Pipeline Management:** Enforces a strict 10-stage workflow with dependency gates (e.g., Model Prep and Catalog Images are critical gates).
+- **Multiple Views:** Supports Table, Kanban Board, and Gantt Timeline views for flexible project management.
+- **AI Assistant:** Integrated chat assistant powered by Claude AI and Ollama for semantic search and support.
+
+## Who Uses It
+
+- **Producers:** Manage project timelines, track overdue items, and oversee the overall pipeline health.
+- **CG Artists:** Update the status of specific deliverables, upload files, and collaborate within the pipeline stages.
+- **Department Leads:** Monitor completion rates and ensure critical gates are cleared to avoid downstream blockages.
+
+## How to Access
+
+1. **Authentication:**
+   - The application uses Microsoft Entra ID (Azure AD) Single Sign-On (SSO).
+   - Navigate to the application URL (e.g., `https://your-domain.com/hp-prod-tracker`).
+   - Click the login button and select your Microsoft account to authenticate.
+
+2. **Local Development Access:**
+   - If running locally with `DEV_BYPASS_AUTH=true` in the environment, you will be automatically logged in as the `DEV_USER_ID`.
+
+## Main Workflows
+
+### 1. Overviewing the Production Dashboard
+
+**Goal:** Get a high-level view of current pipeline health.
+
+**Steps:**
+1. Upon login, you are redirected to the **Dashboard** (`/dashboard`).
+2. Review the following metrics:
+   - **Active Projects:** List of currently running productions.
+   - **Deliverable Counts:** Total items per stage.
+   - **Overdue Items:** Alerts for any deliverables past their deadlines.
+   - **Pipeline Completion Rates:** Visual charts showing progress.
+3. Click on any overdue item or project name to drill down into specific details.
+
+### 2. Managing Deliverables via the 10-Stage Pipeline
+
+**Goal:** Move a deliverable through the pipeline from Brief Intake to Final Output.
+
+**The 10 Stages:**
+1. **Brief Intake**
+2. **File Delivery**
+3. **Model Prep** *(Critical Gate)*
+4. **Early Images** *(Optional)*
+5. **Catalog Images** *(Critical Gate)*
+6. **Hero Images**
+7. **Packaging Images**
+8. **Photocomps**
+9. **360 Spin**
+10. **Dynamic Spin** *(Parallel with 360 Spin)*
+
+**Steps:**
+1. Navigate to **Projects** (`/projects`) or **My Work** (`/my-work`).
+2. Select a project and switch to the **Board View** (Kanban) or **Timeline View** (Gantt) for better visualization.
+3. To update a deliverable:
+   - Locate the card/item representing the deliverable.
+   - Ensure all **prerequisite stages** are approved. You cannot move to the next stage if prerequisites are not complete.
+   - **Critical Gates:** Note that **Model Prep** (Stage 3) and **Catalog Images** (Stage 5) are critical. All downstream work is blocked until these are approved.
+   - Update the status, upload required files, or add comments using the item detail modal.
+
+### 3. Using the Command Palette
+
+**Goal:** Quickly navigate between pages or trigger actions.
+
+**Steps:**
+1. Press `Cmd + K` (macOS) or `Ctrl + K` (Windows/Linux) anywhere in the app.
+2. Type to search for:
+   - **Pages:** Dashboard, Projects, My Work, Notifications, Settings.
+   - **Commands:** AI Assistant, Theme Toggle (Dark/Light/System).
+   - **Projects:** Search by project name to jump directly to a specific project.
+3. Click the desired item or press Enter to execute.
+
+### 4. Using the AI Assistant
+
+**Goal:** Get help, search past deliverables semantically, or clarify pipeline rules.
+
+**Steps:**
+1. Open the Command Palette (`Cmd/Ctrl + K`).
+2. Select **AI Assistant**.
+3. Type your query (e.g., "Show me all overdue catalog images for Project X").
+4. The assistant will use embedded search (via Ollama) or direct LLM calls (via Claude) to provide relevant answers or actions.
+
+## FAQ
+
+**Q: Why can't I move a deliverable to the next stage?**
+A: The pipeline enforces dependency gates. You must complete and get approval for all prerequisite stages (especially critical gates like Model Prep and Catalog Images) before proceeding.
+
+**Q: How do I change my password?**
+A: Password management is handled through your Microsoft Entra ID (Azure AD) account, not within this application.
+
+**Q: The dashboard looks empty. What’s wrong?**
+A: Ensure you have selected the correct project context. If no projects are visible, check if you have been granted access to any active projects by a department lead.
+
+**Q: Can I upload video files?**
+A: Yes. The application supports video uploads processed by FFmpeg. You can view previews via HLS.js in the deliverable details.
+
+**Q: Is the AI assistant free?**
+A: The AI assistant uses local inference via Ollama for embeddings and fallbacks, and Claude API for primary queries. Availability depends on server configuration and API limits set by the admin.
--- a/Projects/oliver-sales-ops-platform/DEVELOPER_MANUAL.md
+++ b/Projects/oliver-sales-ops-platform/DEVELOPER_MANUAL.md
@ -0,0 +1,129 @@
+---
+auto_generated: true
+manual_updated_at: 2026-05-18
+modified: 2026-05-18
+---
+
+# OLIVER Sales Ops Platform — Developer Manual
+
+## Architecture Overview
+The platform is a full-stack web application with a React frontend and a Python FastAPI backend, orchestrated via Docker Compose for local development and production.
+
+### High-Level Components
+1. **Frontend**: React SPA with TypeScript, using `@tanstack/react-query` for data fetching and `@azure/msal-react` for Azure AD authentication.
+2. **Backend**: Python FastAPI application handling business logic, AI agent orchestration (Anthropic Claude), state machine management, and API endpoints.
+3. **Database**: PostgreSQL 16 for persistent storage of opportunities, stages, artifacts, and users.
+4. **Cache/Queue**: Redis 7 for session management, caching, and potential async task queues.
+5. **AI Integration**: Anthropic API for running specialized "Claude Agents" at each stage.
+6. **Auth**: Azure AD SSO via MSAL. Supports a `DEV_AUTH_BYPASS` mode for local development.
+
+## Tech Stack
+- **Frontend**: React 18, TypeScript, React Router, Tailwind CSS (implied by styles), Axios (implied by API client).
+- **Backend**: Python 3.11+, FastAPI, SQLAlchemy (async), Pydantic, Anthropic SDK, Mailgun SDK.
+- **Infrastructure**: Docker, Docker Compose, PostgreSQL 16, Redis 7.
+
+## Local Setup
+
+### Prerequisites
+- Docker & Docker Compose
+- Node.js 18+
+- Python 3.11+
+- An Anthropic API Key
+- Azure AD App Registration (for SSO)
+
+### Steps
+1. **Clone the Repo**
+   ```bash
+   git clone <repo_url>
+   cd oliver-sales-ops-platform
+   ```
+
+2. **Environment Variables**
+   Copy `.env.example` to `.env` and configure:
+   - `POSTGRES_PASSWORD`: Set a strong password.
+   - `ANTHROPIC_API_KEY`: Your Anthropic key.
+   - `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`: From your Azure AD app registration.
+   - `DEV_AUTH_BYPASS`: Set to `true` for local dev to skip SSO. **Never set in production.**
+   - `DATA_DIR`: Directory for reference data (e.g., `./data`).
+   - `APP_PUBLIC_URL`: e.g., `http://localhost:3011`.
+   - `APP_PATH_PREFIX`: e.g., `/oliver-sales-ops-platform`.
+
+3. **Start Infrastructure**
+   ```bash
+   docker-compose up -d db redis
+   ```
+
+4. **Initialize Database**
+   Run database migrations (assuming Alembic or similar):
+   ```bash
+   docker-compose exec backend alembic upgrade head
+   ```
+
+5. **Start Backend**
+   ```bash
+   docker-compose up backend
+   ```
+
+6. **Start Frontend**
+   ```bash
+   cd frontend
+   npm install
+   npm run dev
+   ```
+
+7. **Access the App**
+   Open `http://localhost:3011` (or your configured port) in a browser.
+
+## Environment Variables
+| Variable | Required | Description |
+|---|---|---|
+| `POSTGRES_PASSWORD` | Yes | DB password |
+| `ANTHROPIC_API_KEY` | Yes | Anthropic API key |
+| `AZURE_TENANT_ID` | Yes | Azure AD Tenant ID |
+| `AZURE_CLIENT_ID` | Yes | Azure AD Client ID |
+| `DEV_AUTH_BYPASS` | No | Skip SSO in dev (set to `true`) |
+| `MAILGUN_API_KEY` | No | Email notifications |
+| `MAILGUN_DOMAIN` | No | Mailgun domain |
+| `APP_PUBLIC_URL` | No | Public URL for links |
+| `APP_PATH_PREFIX` | No | URL prefix for routing |
+| `DATA_DIR` | No | Path to reference data |
+
+## Key Services & Entry Points
+
+### Backend (`/backend`)
+- **Main Entry**: `app/main.py` (FastAPI app init).
+- **Stage Logic**: `/backend/app/stages/` contains agent definitions and state machine logic.
+- **API Routes**: `/backend/app/api/` exposes REST endpoints for opportunities, approvals, and artifacts.
+- **Auth Middleware**: Handles Azure AD token validation. Falls back to `DEV_AUTH_BYPASS` claims if enabled.
+
+### Frontend (`/frontend`)
+- **Main Entry**: `src/main.tsx` (React app bootstrapping).
+- **Routing**: `src/App.tsx` defines routes for Dashboard, Opportunities, and Approvals.
+- **Auth**: `src/auth/AuthProvider.tsx` handles MSAL login, redirect, and access control.
+- **Components**: Stage-specific components (e.g., `Stage9DeliveryModel.tsx`) handle UI for each phase.
+
+### Database Models
+- **Opportunity**: Represents a single deal/project.
+- **StageArtifact**: Stores AI-generated JSON and metadata (cost, tokens) per stage.
+- **Approval**: Tracks approval status for gated stages.
+
+## API Reference (Key Endpoints)
+- `POST /api/opportunities`: Create new opportunity.
+- `GET /api/opportunities/{id}`: Get opportunity details.
+- `POST /api/opportunities/{id}/stages/{n}/complete`: Complete stage `n`.
+- `POST /api/opportunities/{id}/delivery-model`: Trigger Stage 9 agent.
+- `GET /api/opportunities/{id}/artifacts/{n}`: Get artifacts for stage `n`.
+- `POST /api/approvals/{id}/approve`: Approve an approval gate.
+
+## Deployment
+1. **Build Docker Images**: `docker-compose build`.
+2. **Set Production Env Vars**: Ensure `DEV_AUTH_BYPASS` is **unset** or `false`. Set all secrets securely.
+3. **Deploy**: Use `docker-compose up -d` or your orchestrator (K8s, etc.).
+4. **Database**: Run migrations in the running container.
+
+## Known Gotchas
+1. **Auth Bypass**: Accidentally leaving `DEV_AUTH_BYPASS=true` in production will disable SSO and allow unauthorized access.
+2. **Path Prefixes**: Ensure `APP_PATH_PREFIX` in `.env` matches the reverse proxy configuration (e.g., Nginx/Apache) and the `basename` in `BrowserRouter`.
+3. **AI Costs**: Every AI call is logged. Monitor token usage via the UI to avoid unexpected Anthropic bills.
+4. **Stage Locking**: Stages are strictly sequential. Ensure upstream stages are complete before attempting downstream operations.
+5. **Mailgun**: If `MAILGUN_API_KEY` is empty, emails are logged only. Ensure a key is set for production notifications.
--- a/Projects/oliver-sales-ops-platform/USER_MANUAL.md
+++ b/Projects/oliver-sales-ops-platform/USER_MANUAL.md
@ -0,0 +1,77 @@
+---
+auto_generated: true
+manual_updated_at: 2026-05-18
+modified: 2026-05-18
+---
+
+# OLIVER Sales Operations Platform — User Manual
+
+## What This Tool Does
+The OLIVER Sales Ops Platform is an end-to-end pipeline tool that guides commercial opportunities through 17 specialized stages, from initial intake to post-win planning. It automates complex analysis using AI agents, manages human approval gates, and produces structured deliverables at each stage. The goal is to transform a rough brief into a defensible, data-driven proposal.
+
+## Who Uses It
+- **Commercial Team Members**: To create and manage opportunities, answer qualification questions, and review AI-generated deliverables.
+- **Sales Ops**: To monitor pipeline health, manage approvals, and ensure process adherence.
+- **Approvals/Leadership**: To review and approve critical gates (Qualification and Approval Gate stages).
+
+## How to Access
+1. Navigate to your organization's OLIVER Sales Ops Platform URL.
+2. Click **"Sign in with Microsoft"** to authenticate via Azure Active Directory.
+3. If your email is not in the allowed users list, you will see a "No Access" page. Contact your admin.
+4. Once logged in, you land on the **Dashboard** to view your active opportunities.
+
+## Main Workflows
+
+### 1. Creating a New Opportunity
+1. Click **"New Opportunity"** from the Dashboard or Navigation bar.
+2. Fill in the **Intake** details (Brief, Client Info, etc.).
+3. Click **"Save & Proceed to Stage 1"**.
+4. The **Intake Agent** automatically runs, structuring your brief into JSON.
+
+### 2. Progressing Through Stages
+The platform enforces a sequential 17-stage process. You cannot skip stages.
+
+#### General Stage Flow
+1. **View Current Stage**: The UI highlights your current stage in the Stepper.
+2. **Run AI Agent (if applicable)**: Click **"Run Agent"** for stages driven by Claude AI (e.g., Diagnosis, Asset Matching, Ratecard).
+   - The platform records AI token costs for transparency.
+   - Review the generated JSON/Artifact in the UI.
+3. **Human Input/Decision**:
+   - **Qualification (Stage 3)**: Answer TROWLS questions. Submit for Approval.
+   - **Approval Gate (Stage 14)**: Review the summary and submit for final approval.
+   - **Other Stages**: Manually edit or confirm data (e.g., Ingesting Client Answers in Stage 5).
+4. **Complete Stage**: Click **"Complete Stage"**. The system locks the stage and unlocks the next one.
+
+#### Key Gated Stages
+- **Stage 3: Qualification Assessment**
+  - Requires human input on the TROWLS scorecard.
+  - Must be approved by an authorized user before proceeding.
+- **Stage 14: Approval Gate**
+  - Final check before pitch preparation.
+  - Requires explicit approval from designated leaders.
+
+### 3. Approvals
+- **Notification**: Approvers receive in-app notifications and emails (via Mailgun) when a stage requires approval.
+- **Action**: Click the notification or go to **/approvals** to review.
+- **Decision**: Click **"Approve"** or **"Reject"**. Rejection returns the opportunity to the previous stage.
+
+### 4. Deliverables & Exports
+- Some stages generate Excel/Word packs (Q&A) or Markdown (Pitch Deck).
+- Download these directly from the respective stage UI.
+
+## FAQ
+
+**Q: Why can't I skip a stage?**
+A: The pipeline is designed to ensure comprehensive analysis and risk mitigation. Skipping stages could lead to incomplete proposals or missed critical risks.
+
+**Q: What if an AI agent fails?**
+A: You can retry the agent. If it continues to fail, contact Sales Ops support with the error details visible in the UI.
+
+**Q: Who is an "Approver"?**
+A: Only users listed in the `allowed_users.yaml` configuration with approval privileges can approve Qualification and Approval Gate stages.
+
+**Q: Can I edit AI-generated content?**
+A: Yes, most stages allow you to override or refine the AI's output before completing the stage.
+
+**Q: What happens after Stage 17?**
+A: Stage 17 (Post-Win Planning) is currently manual. Phase 2 will automate the push to Salesforce/SharePoint.
--- a/Projects/solventum-image-metadata/DEVELOPER_MANUAL.md
+++ b/Projects/solventum-image-metadata/DEVELOPER_MANUAL.md
@ -0,0 +1,123 @@
+---
+auto_generated: true
+manual_updated_at: 2026-05-18
+modified: 2026-05-18
+---
+
+# Solventum Image Metadata Tool v3.1 — Developer Manual
+
+## Architecture Overview
+
+The application is a Flask-based web service designed for both local development and Dockerized production deployment.
+
+- **Web Framework**: Flask (with Jinja2 templating).
+- **Backend Logic**: Modular services in `src/` directory.
+- **Data Persistence**: SQLite via a custom `src/database.py` wrapper.
+- **Authentication**: Microsoft Azure AD SSO (MSAL) and local session-based auth.
+- **File Handling**: ExifTool integration for reading/writing metadata across 300+ formats.
+- **AI Integration**: Optional OpenAI API integration for metadata generation.
+- **Deployment**: Docker Compose for production; `uvicorn`/Flask dev server for local dev.
+
+## Tech Stack
+
+- **Language**: Python 3.14 (required for pandas compatibility, see `venv_local/lib/python3.14/site-packages/pandas/pyproject.toml`).
+- **Web Server**: Flask (dev via `run.py`), Uvicorn (if ASGI needed, though currently Flask/Werkzeug).
+- **Database**: SQLite (`oliver_metadata.db`, `oliver_sessions.db`).
+- **External Tools**: ExifTool, Tesseract OCR (optional), Poppler (optional).
+- **Dependencies**: pandas, numpy>=2.3.3 (for Python 3.14), MSAL, Pydantic-Settings, SlowAPI (rate limiting).
+
+## Local Setup
+
+### Prerequisites
+1. Python 3.14+.
+2. ExifTool installed on the system.
+3. (Optional) Tesseract and Poppler for full OCR/PDF support.
+
+### Steps
+1. **Clone and Install**:
+   ```bash
+   git clone <repository_url>
+   cd solventum-image-metadata
+   python -m venv venv
+   source venv/bin/activate # or venv\Scripts\activate on Windows
+   pip install -r requirements.txt
+   ```
+
+2. **Environment Variables**:
+   - Copy `.env.example` to `.env`.
+   - Fill in `SECRET_KEY`, `AZURE_CLIENT_SECRET`, and other required fields.
+   - Set `DOCKER_MODE=false` for local dev.
+
+3. **Run**:
+   ```bash
+   python run.py
+   ```
+   The app will start at `http://127.0.0.1:5001`.
+
+## Environment Variables
+
+Key variables from `.env`:
+
+- `SECRET_KEY`: Flask session secret. Generate with `secrets.token_hex(32)`.
+- `DOCKER_MODE`: `true`/`false`. Determines path structures (e.g., `/app/uploads` vs local).
+- `ROOT_PATH`: Subpath prefix for reverse proxy (e.g., `/solventum-image-metadata`).
+- `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`: Azure AD SSO config.
+- `REDIRECT_URI`: Must match Azure AD App Registration exactly. For local: `http://localhost:5001/auth/callback`.
+- `SUPERADMIN_EMAIL`: Auto-created admin email.
+- `OPENAI_API_KEY`: For AI metadata generation.
+- `ENABLE_TEST_USER`: `true` to enable local test user login.
+- `HTTPS_ONLY`: `true` in production to enforce HTTPS.
+
+## Key Services & Entry Points
+
+- `app/main.py`: Entry point for the Flask app. Initializes blueprints and middleware.
+- `app/config.py`: `Settings` class using Pydantic-Settings for config management.
+- `src/auth.py`: Handles authentication logic (MSAL flow, session creation, login_required decorator).
+- `src/file_detector.py`: Detects file type and routes to appropriate extractor.
+- `src/extractors/`: Contains `PDFExtractor`, `ImageExtractor`, `OfficeExtractor`, `VideoExtractor`.
+- `src/updaters/`: Contains `PDFUpdater`, `ImageUpdater`, etc., for writing metadata.
+- `src/metadata_importer.py`: Handles CSV/Excel import and column mapping.
+- `web_app.py`: Contains Flask routes and controllers (if used as direct entry). Note: `run.py` imports `app.main:app`.
+
+## API Reference
+
+The tool provides a web UI. However, some internal JSON APIs are exposed for the frontend:
+
+- `POST /auth/callback`: Azure AD SSO callback.
+- `POST /api/import`: Process Excel/CSV import.
+- `POST /api/ai/generate`: Trigger AI metadata generation.
+- `GET /api/files`: List files.
+- `GET /api/files/<id>`: Get file details.
+- `PUT /api/files/<id>/metadata`: Update metadata.
+
+*Note: Refer to `web_app.py` for exact route definitions and request/response schemas.*
+
+## Deployment
+
+### Docker
+1. Ensure Docker and Docker Compose are installed.
+2. Configure `.env` with production values.
+3. Run:
+   ```bash
+   docker-compose up -d
+   ```
+4. The app will be available at `http://127.0.0.1:5001` (if exposed locally) or via the reverse proxy at `ROOT_PATH`.
+
+### Volumes
+- `uploads`: Persistent file uploads.
+- `database`: Persistent SQLite databases.
+- `output`: Persistent output/backups.
+
+### Reverse Proxy
+- Configure Apache/Nginx to proxy `/solventum-image-metadata` to the container port 5001.
+- Ensure `ROOT_PATH` in `.env` matches the proxy subpath.
+
+## Known Gotchas
+
+1. **Python 3.14 Requirement**: The pandas dependency in `venv_local/lib/python3.14/site-packages/pandas/pyproject.toml` explicitly requires `numpy>=2.3.3` for Python 3.14. Ensure you are using Python 3.14+ to avoid compatibility issues.
+2. **ExifTool Path**: ExifTool must be in the system PATH. In Docker, ensure the ExifTool binary is installed in the container or mounted.
+3. **Azure Redirect URI**: Must match exactly, including `/auth/callback`. Case sensitivity applies.
+4. **File Locking**: On Windows, ensure files are not locked by other processes before updating metadata.
+5. **Database Path**: In Docker mode, DB paths are hardcoded to `/app/data/`. Ensure volume mounts align.
+6. **Rate Limiting**: SlowAPI is used. Ensure `app/security.py` is properly integrated in `app/main.py` to avoid bypassing rate limits.
+7. **Unicode Filenames**: The `safe_filename` function in `web_app.py` normalizes Unicode. Ensure ExifTool supports UTF-8 input (usually does with modern versions).
--- a/Projects/solventum-image-metadata/USER_MANUAL.md
+++ b/Projects/solventum-image-metadata/USER_MANUAL.md
@ -0,0 +1,99 @@
+---
+auto_generated: true
+manual_updated_at: 2026-05-18
+modified: 2026-05-18
+---
+
+# Solventum Image Metadata Tool v3.1 Enterprise Edition — User Manual
+
+## What This Tool Does
+
+The Solventum Image Metadata Tool is a universal metadata creation and management platform designed for enterprise content workflows. It allows users to:
+
+1. **Create and Edit Metadata**: Manually or automatically generate metadata for files including PDFs, images, office documents, and videos.
+2. **Import Metadata**: Bulk import metadata from CSV, Excel, or JSON files with smart column mapping.
+3. **AI-Powered Generation**: Use OpenAI to automatically extract and generate metadata based on file content.
+4. **Batch Processing**: Update metadata for multiple files simultaneously.
+5. **Template Management**: Save and reuse metadata templates with variable substitution (e.g., `{filename}`, `{date}`).
+6. **Export Data**: Export processed metadata to CSV for downstream systems.
+
+**Supported File Formats**: 300+ types including JPEG, PNG, HEIC, TIFF, RAW, PDF, Word, Excel, PowerPoint, MP4, MOV, AVI, MKV, and more.
+
+## Who Uses It
+
+- **Content Managers**: For organizing and tagging large libraries of assets.
+- **Marketing Teams**: For ensuring consistent metadata for digital assets.
+- **IT Administrators**: For managing bulk metadata imports and exports.
+- **Superadmin**: The account `vadymsamoilenko@oliver.agency` has full administrative privileges and is auto-created on first startup.
+
+## How to Access
+
+### Prerequisites
+- Ensure you have the necessary access credentials for your organization.
+- Ensure your browser is up to date.
+
+### Login
+1. Navigate to your organization's instance of the tool (e.g., `https://[your-domain]/solventum-image-metadata`).
+2. Click **Login**.
+3. **Authentication Options**:
+   - **Microsoft SSO (Recommended)**: Click the Microsoft login button. You will be redirected to Azure AD. Ensure your redirect URI matches the Azure AD App Registration configuration.
+   - **Local User**: If enabled (`ENABLE_TEST_USER=true` in dev or configured accounts), enter your username and password.
+
+### First-Time Setup
+- On the first startup, the superadmin email (`vadymsamoilenko@oliver.agency`) is automatically created as an admin user upon their first SSO login.
+
+## Main Workflows
+
+### 1. Manual Metadata Entry
+1. Navigate to the **Upload** or **File Details** section.
+2. Upload a file or select an existing one.
+3. Click **Edit Metadata**.
+4. Modify fields such as Title, Subject, Keywords, Author, and Copyright.
+5. Click **Save** to apply changes to the file.
+
+### 2. AI-Generated Metadata
+1. Upload a file or select one from your library.
+2. Click **Generate with AI**.
+3. The system will analyze the file content (using OpenAI GPT-5.2 or configured model) and suggest metadata.
+4. Review the generated suggestions.
+5. Click **Apply** to save the metadata or **Discard** to revert.
+
+### 3. Bulk Import from Excel/CSV
+1. Navigate to the **Import** section.
+2. Upload your Excel (.xlsx) or CSV file.
+3. **Map Columns**: The system attempts to auto-detect columns. Verify or adjust the mapping for fields like "Filename", "Title", "Keywords", etc.
+4. Click **Process Import**.
+5. Review the preview of changes.
+6. Click **Confirm Import** to apply metadata to all files.
+
+### 4. Template Usage
+1. Go to **Templates** in the sidebar.
+2. **Create New**: Define variables (e.g., `{date}`, `{user}`).
+3. **Apply Template**: Select files, choose a template, and execute.
+4. The system will substitute variables and update metadata accordingly.
+
+### 5. Export Metadata
+1. Select one or more files.
+2. Click **Export**.
+3. Choose format (CSV).
+4. The file will be downloaded to your local machine.
+
+## FAQ
+
+**Q: How do I reset my password?**
+A: Contact your Superadmin (`vadymsamoilenko@oliver.agency`) to reset your local credentials. SSO users log in via Azure AD.
+
+**Q: Why is my metadata not saving?**
+A: Ensure you have write permissions for the file. Check that the file is not read-only on the server. Verify that the metadata fields are valid (no special characters that ExifTool rejects).
+
+**Q: Can I use this tool offline?**
+A: No, the tool requires a network connection for Azure SSO authentication and OpenAI API calls (if used). The core database is SQLite and hosted on the server.
+
+**Q: What happens if the AI generation fails?**
+A: The system will log an error in the Audit Log. You can retry or fall back to manual entry.
+
+**Q: How large can the files be?**
+A: The maximum upload size is 500MB. Ensure your server configuration allows this.
+
+**Q: Can I track who made changes?**
+A: Yes, all metadata changes are logged in the Audit Log under the **Audit** section.