Bugfix/general

.agents/skills/code-review/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: code-review
+description: Performs a comprehensive code review to identify bad practices, bad smells, and breaking architecture rules, and generates a report.
+version: 1.0.0
+---
+
+# Code Review Skill
+
+Use this skill when the user asks you to "review the code", "do a code review", or "check for bad smells".
+
+## Instructions
+
+1. **Understand the Scope**: If the user doesn't specify a file or folder, ask them which part of the codebase they want reviewed (e.g., the whole backend, a specific feature branch, or recently changed files).
+2. **Read the Rules**: Review the `/.agent/RULES.md` and `SERVICE_MAP.md` (and related architecture files) to understand the project's strict architecture requirements.
+3. **Analyze the Code**: Use your `grep_search` and `view_file` tools to analyze the target files. Look specifically for:
+   - **Architecture Violations**: Code that violates the `Route → Controller → Service → Repository` pattern. For example, controllers directly calling the database instead of a service, or services dealing with HTTP `req`/`res` objects.
+   - **Error Handling**: Using `throw new Error()` instead of the standard `AppError(message, statusCode)`.
+   - **Bad Smells**: 
+     - **God Classes/Files**: Files that are far too large and do too many things.
+     - **Duplicated Code**: Logic that is copy-pasted across multiple places instead of being extracted into a utility or shared service.
+     - **Missing Async Wrappers**: Controllers missing `asyncHandler`.
+   - **Security**: Hardcoded secrets or unvalidated inputs.
+4. **Generate the Report**: Create a markdown artifact named `code_review_report.md` (or similar) using the `write_to_file` tool.
+   - Structure the report with:
+     - 🚀 **Summary of Findings**
+     - 🏗 **Architecture Violations** (with file links and line numbers)
+     - 👃 **Bad Smells & Tech Debt**
+     - 💡 **Actionable Recommendations**
+5. **Present**: Inform the user that the review is complete and point them to the artifact. Ask if they want you to automatically fix any of the found issues.

.agents/skills/run-local-dev/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: run-local-dev
+description: >-
+  Use this skill to run the node backend, python AI service, and frontend locally and open the browser to check the current feature being worked on.
+---
+
+# Run Local Development Environment
+
+Follow these steps to run the node backend, python AI service, and frontend locally and check the application.
+
+## Steps
+
+1. **Start the Backend:**
+   Use the `run_command` tool to start the backend server as a daemon.
+   - **Command:** `npm run dev`
+   - **Cwd:** `<workspace_root>\backend`
+   - **IsDaemon:** `true`
+   - **WaitMsBeforeAsync:** `2000` (to ensure it starts successfully and you can see any initial errors)
+
+2. **Start the AI Microservice:**
+   Use the `run_command` tool to start the Python FastAPI server as a daemon.
+   - **Command:** `python main.py`
+   - **Cwd:** `<workspace_root>\backend\ai_service`
+   - **IsDaemon:** `true`
+   - **WaitMsBeforeAsync:** `2000`
+
+3. **Start the Frontend:**
+   Use the `run_command` tool to start the frontend development server as a daemon.
+   - **Command:** `npm run dev`
+   - **Cwd:** `<workspace_root>\frontend`
+   - **IsDaemon:** `true`
+   - **WaitMsBeforeAsync:** `2000`
+
+   *(Note: The frontend Vite config has `server.open: true`, which should automatically open a browser window for the user.)*
+
+4. **Check the Application:**
+   - **If the user wants YOU (the agent) to verify the feature:** Use the `browser_subagent` tool to navigate to `http://localhost:3000` and perform the requested checks. Provide a descriptive `Task` and `RecordingName` (e.g., `feature_verification`).
+   - **If the user wants to check it themselves:** Inform them that the backend services and frontend are running, and the browser should have opened automatically to `http://localhost:3000`. If they report the browser didn't open, you can run the command `Start-Process "http://localhost:3000"` (Windows) using the `run_command` tool to explicitly open it for them.
+
+## Cleanup
+
+If the user asks to stop the local environment later, use the `manage_task` tool with action `list` to find the task IDs, and then `kill` to terminate all the background tasks (Node backend, AI service, and frontend).

.agents/skills/run-local-tests/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: run-local-tests
+description: >-
+  Use this skill to run tests for the local environment, including frontend, backend, AI service, or end-to-end (e2e) tests.
+---
+
+# Run Local Tests
+
+Use the `run_command` tool to execute the appropriate testing commands based on the user's request. Always ensure you run the command in the correct working directory (`Cwd`).
+
+## 1. Frontend Tests
+
+Set **Cwd** to `<workspace_root>\frontend`.
+
+- **Unit/Component Tests:** `npm run test`
+- **End-to-End (E2E) Tests:** `npm run e2e` (Uses Playwright)
+- **Coverage Report:** `npm run coverage`
+- **UI Mode for Tests:** `npm run test:ui`
+
+## 2. Node Backend Tests
+
+Set **Cwd** to `<workspace_root>\backend`.
+
+- **All Tests:** `npm run test`
+- **Unit Tests:** `npm run test:unit`
+- **Integration Tests:** `npm run test:integration`
+- **Integration (Live AI):** `npm run test:integration:live`
+- **Coverage Report:** `npm run test:coverage`
+
+## 3. AI Service Tests
+
+Set **Cwd** to `<workspace_root>\backend\ai_service`.
+
+- **All Tests:** `pytest`
+- **Security Tests:** `pytest -m security`
+- **Schema Tests:** `pytest -m schema`
+- **Integration Tests:** `pytest -m integration`
+
+## 4. Run All Tests
+
+If the user asks to "run all tests" across the entire project, execute the core test suites sequentially. Run them synchronously (do not set `IsDaemon=true`) so you can capture the output and report the results to the user.
+
+1. `<workspace_root>\frontend` -> `npm run test`
+2. `<workspace_root>\backend` -> `npm run test`
+3. `<workspace_root>\backend\ai_service` -> `pytest`
+
+### Important Notes:
+- **E2E Tests:** `npm run e2e` in the frontend might require the frontend and backend servers to be running locally first. If the user wants to run E2E tests, you might need to use the `run-local-dev` skill to start the servers before executing the E2E tests.
+- **Reporting:** After running tests, summarize the results for the user (e.g., how many passed/failed) and provide the relevant logs if there are failures.

.agents/skills/update-ai-models/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: update-ai-models
+description: Fetch current available models from all LLM provider APIs and update the centralized model registry.
+---
+
+# Update AI Models
+
+## When to Use
+- When an AI feature returns a 500 error related to model availability
+- After a provider announces model deprecations
+- Periodically, to keep the registry fresh
+- When you see a `⚠️ AI Model Registry has stale/deprecated models` GitHub Issue
+
+## Prerequisites
+At least one provider API key must be available as an environment variable:
+- `GROQ_API_KEY`
+- `OPENAI_API_KEY`  
+- `ANTHROPIC_API_KEY`
+- `GEMINI_API_KEY`
+
+## Steps
+
+### 1. Run the Validation Script
+```bash
+cd backend/ai_service
+python scripts/validate_models.py
+```
+
+### 2. Review the Output
+- ✅ = Model is available and current
+- ⚠️ = Model is NOT FOUND on the provider (deprecated or decommissioned)
+- 🆕 = Model is available on the provider but not in our registry
+
+### 3. Update the Registry
+Edit `backend/ai_service/providers/model_registry.py`:
+
+1. **Remove stale models** from `available` and `fallbacks` lists
+2. **Add new models** you want to support to `available` 
+3. **Update `default`** if the current default is stale — pick the best general-purpose model
+4. **Update `fallbacks`** — list 2-3 alternatives in priority order
+5. Keep model display names human-readable (e.g., `"GPT-6 Astra"`)
+
+### 4. Test the AI Service
+```bash
+# Restart the AI service and check boot logs for the registry summary
+pm2 restart jobpilot
+# or
+cd backend/ai_service && python main.py
+```
+
+Verify at least one feature works:
+- Mail Creator: generate a message
+- Role Fit: analyze an application
+- classify-job: trigger an RSS poll
+
+### 5. Commit and Push
+```bash
+git add backend/ai_service/providers/model_registry.py
+git commit -m "chore: update AI model registry — replace deprecated models"
+git push
+```
+
+## Important Notes
+- The `model_registry.py` file is the **single source of truth**. All 4 provider files read from it.
+- The `LLMRouter.get_model_with_fallback()` mechanism provides runtime protection — if a model is deprecated, it automatically tries the next fallback and logs a warning.
+- Groq models change most frequently. Prioritize checking Groq first.
+- The weekly GitHub Action (`validate-models.yml`) will auto-open an Issue if stale models are detected.
+
+## Provider API Reference
+| Provider | List Models Endpoint |
+|:---------|:---------------------|
+| Groq | `GET https://api.groq.com/openai/v1/models` |
+| OpenAI | `GET https://api.openai.com/v1/models` |
+| Anthropic | `GET https://api.anthropic.com/v1/models` |
+| Gemini | `GET https://generativelanguage.googleapis.com/v1beta/models` |

.agents/skills/validate-changes/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: validate-changes
+description: Runs a comprehensive pre-commit validation suite including frontend/backend tests, lint checks, AI service tests, and E2E tests to ensure changes won't break the CI/CD pipeline on GitHub Actions.
+version: 1.0.0
+---
+
+# Validate Changes Skill
+
+Use this skill when the user asks to "validate changes", "run all checks", "make sure this won't break github actions", or "run validation".
+
+## Instructions
+
+This skill ensures that all layers of the application are fully tested and linted before the user commits or pushes their code. You must execute these checks sequentially.
+
+1. **Check 1: Frontend Linting**
+   - Run `npm run lint` in the `/frontend` directory using the `run_command` tool.
+   - Wait for it to finish. Warnings are acceptable, but errors must be fixed.
+2. **Check 2: Frontend Tests**
+   - Run `npm run test -- --run` in the `/frontend` directory.
+   - Ensure all tests pass.
+3. **Check 3: Backend Tests**
+   - Run `npm run test` in the `/backend` directory.
+   - Ensure all tests pass.
+4. **Check 4: AI Service Tests**
+   - Run `pytest` (or the equivalent test command) in the `/ai-service` (or Python AI service) directory.
+   - Ensure all tests pass.
+5. **Check 5: E2E Tests (If applicable)**
+   - If the project has an E2E testing suite (e.g., Playwright in `/frontend` via `npm run e2e`), run it.
+
+## Handling Failures
+
+- **Minor Failures:** If a linting error or a minor, obvious test failure occurs (e.g., a text mismatch in a React test because the UI text was updated), attempt to fix it automatically using your code editing tools (`replace_file_content`), then re-run the specific failing check.
+- **Complex Failures:** If a backend test or complex logic test fails, halt the validation process. Create a short artifact or respond directly to the user explaining the exact failure, showing the logs, and providing a recommendation on how to fix it. Ask the user for permission to attempt the fix.
+
+## Completion
+If all checks pass successfully, inform the user that the codebase is fully validated and safe to push to GitHub Actions!

.github/workflows/validate-models.yml

@@ -0,0 +1,61 @@
+name: Validate AI Model Registry
+
+on:
+  schedule:
+    - cron: '0 8 * * 1'  # Every Monday at 8 AM UTC
+  workflow_dispatch:       # Manual trigger from GitHub UI
+
+jobs:
+  validate-models:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Dependencies
+        run: pip install requests
+
+      - name: Run Model Validation
+        working-directory: ./backend/ai_service
+        env:
+          GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+        run: python scripts/validate_models.py --ci
+
+      - name: Create Issue on Stale Models
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const existing = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: 'ai-model-stale',
+              state: 'open'
+            });
+            if (existing.data.length > 0) {
+              console.log('Stale model issue already exists, skipping creation.');
+              return;
+            }
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: '⚠️ AI Model Registry has stale/deprecated models',
+              body: [
+                'The weekly model validation check found deprecated or unavailable models in `providers/model_registry.py`.',
+                '',
+                '### How to fix',
+                '1. Run `python backend/ai_service/scripts/validate_models.py` locally to see which models are stale.',
+                '2. Update `backend/ai_service/providers/model_registry.py` with current model IDs.',
+                '3. Test the AI service to ensure the new defaults work.',
+                '',
+                '*This issue was auto-created by the `validate-models` workflow.*'
+              ].join('\n'),
+              labels: ['bug', 'ai-service', 'ai-model-stale']
+            });

.gitignore

@@ -21,4 +21,7 @@ test-results/
 
 # Linting
 .eslintcache
-lint-results.txt
+lint-results.txt
+
+# Local one-off refactoring scripts
+scripts/