# Dawid Czerwinski - Complete Architecture & Systems Specifications (llms-full.txt)

> Comprehensive technical blueprints, schemas, and specifications for all 9 systems built by Dawid Czerwinski.

---



================================================================================
SYSTEM SPECIFICATION: BUSOS (ID: busos)
Deep Link: https://czerwinskidawid.pl/#projects/busos
================================================================================

# National Transit Equity & Urban Gravity Platform (Urban Gravity Engine v9.1)

## 1. Project Mission & Analytical Scope

The primary mission of this platform is to provide an empirical, high-fidelity quantification of the causal relationship between public transport accessibility and residential property values across **30 major Polish agglomerations**. By integrating high-resolution transit data (GTFS), comprehensive infrastructure context (OpenStreetMap), transactional real estate registries (RCN/GUGiK), and demographic grids (GUS NSP 2021), the system enables advanced modeling of Transit-Oriented Development (TOD) premiums and socio-economic equity.

This platform is not merely a data aggregator; it is a **specialized spatial engineering engine** designed to eliminate "spatial noise". It solves fundamental data science challenges—such as preventing rural train stops from being evaluated like metropolitan hubs, stopping the "Gravity Fallacy" from erasing human populations, and preventing massive shopping malls from being outranked by 30 scattered park benches. 

It acts as a Digital Auditor of Urban Policy, revealing whether cities favor affluent districts or prioritize regional accessibility, while delivering completely clean, mathematically rigorous data sets (Parquet/GPKG) ready for Next.js mapping and deep econometric modeling.

---

## 2. Mathematical Architecture: Physics of the City (v13.0 - Rygor Tkanki Miejskiej)

The most critical achievement of this platform is its custom-built **Urban Gravity Engine**, which relies on strict mathematical rules to simulate how humans move, choose services, and assign value to urban spaces. This is divided into three distinct phases: **Macro-Valuation**, **Calibrated Hybrid Clustering**, and **Dynamic Micro-Gravity Distribution**.

### A. Phase I: Macro-Valuation & Spatial Dissolve (Script 14)
**1. The "Spatial Dissolve" Algorithm (v13.0):**
To prevent artificial value inflation, the system unifies fragmented OSM complexes (e.g., a hospital with 15 pavilions) into a single analytical unit.
*   **Target:** Tier T0 (Mega Hubs) and T1 (National Magnets).
*   **Logic:** Buffers objects by 10m, dissolves by `name` and `tier`, and restores geometry. 
*   **Result:** A 15-building campus is treated as **One Object** with summed area, preventing 15x weight multiplication.

**2. The Balanced Tier Matrix (Urban Fabric Rescue):**
Parks and religious sites are demoted to T6 to prioritize commercial/service density.
*   **T0 Mega Hubs:** 5,000,000 pts (Airports, Main Rail).
*   **T1 National Magnets:** 1,000,000 pts (Hospitals, University Campuses).
*   **T2 Strategic Hubs:** 250,000 pts (Malls, Commercial/Industrial Zones).
*   **T3 Local Cores:** 50,000 pts (High Schools, Theatres).
*   **T4 Daily Services:** 10,000 pts (Pharmacies, Banks, Convenience stores).
*   **T5 Specialized Gastro:** 2,500 pts (Restaurants, Hotels).
*   **T6 Micro Infra:** 100 pts (**Parks**, **Churches**, ATMs, Lockers).

### B. Phase II: Calibrated Hybrid Hub Agglomeration (Script 15)
1.  **Semantic Phase:** Group by `norm_name` (150m threshold, `complete` linkage).
2.  **Stitching Phase:** Merge different names (e.g. "Galeria Korona" and "IX Wieków") if centroids are within **100 meters**.

### C. Phase III: Dynamic Micro-Gravity Distribution (Script 15)
**1. Dynamic Diminishing Returns (The High-Street Shield):**
*   **T0 / T1 (National Hubs):** Power = `0.2`. No floor.
*   **T2 (Strategic Hubs - Malls):** Power = `1.2`. **No floor** (Penalty falls to zero).
*   **T4 / T5 (Urban Fabric - Stores/Gastro):** Power = `1.0`. **20% RETENTION FLOOR** (Protects the High Street).
*   **T6 (Micro-Infra - Parks/Spam):** Power = `2.0`. **No floor** (Aggressively hits zero).

**2. Shannon Entropy & Log-Normalized Z-Score:**
`Local_Score = Z(log1p(infra)) * 0.35 + Z(log1p(transit)) * 0.35 + Z(log1p(pop)) * 0.15 + Z(log1p(market)) * 0.15`

---

## 3. System Architecture: The "Autonomous Hub" Model

To ensure 100% scalability, data integrity, and parallel processing capabilities, the project utilizes a decentralized **City Hub** structure. Each of the 30 agglomerations is a self-contained operational unit located in `data/cities/{city_name}/`. This allows for independent processing, validation, and recovery without cross-contamination.

*   **`01_source/`**: The raw ingestion point for local GTFS feeds, regional OSM PBF extracts, and local RCN GML/WFS transactional files.
*   **`02_spatial/`**: Hardened, unified GeoPackage (GPKG) databases:
    *   `stops.gpkg`: Validated transit nodes (Smart Stops).
    *   `infrastructure.gpkg`: Multi-layer OSM data (points/polygons) strictly clipped to the city's transit zone. Preserves the full `all_tags` HSTORE.
    *   `transactions.gpkg`: Unified real estate records with normalized `price_m2` and `lok_pow_uzyt` columns.
    *   `population_250m.gpkg`: A localized, highly efficient demographic grid extracted from the massive national census file.
*   **`03_config/`**: Local intelligence layer containing `poi_valuation.json` (the city's specific "Gravity Price List" calculated by the Engine).
*   **`04_results/`**: Final analytical outputs, including the Stop DNA profiles (GPKG), raw Parquet matrices for frontend API delivery, and equity reports.

---

## 4. The Master Pipeline: 16 Steps to Perfection

The system is fully automated and orchestrated via `orchestrator.py` (The "Pancerny" fault-tolerant runner). To rebuild the national dataset from scratch, the Orchestrator executes these numbered scripts sequentially from `scripts/pipeline/`.

### Phase 1: Environment & Spatial Isolation
*   **`00_init_environment.py`**: Validates the global directory structure, verifies CRS integrity across the workspace, and prepares the operational grid.
*   **`01_fetch_gtfs.py`**: Multi-threaded sync of 85+ Polish transit operators (ZTM, MPK, PKP).
*   **`02_collect_stops.py`**: Unifies Urban and Rail stops. Applies the crucial `normalize_name` regex function (stripping strings to raw alphanumeric core) to ensure perfect Agglomerative Clustering later. Identifies massive transport radii.
*   **`03_download_osm_pbf.py`**: Downloads the 2GB+ National OpenStreetMap binary (Geofabrik).
*   **`04_download_population.py`**: Ingests the National Census (GUS) 250m demographic grid and converts it to EPSG:2180.
*   **`05_extract_infrastructure.py`**: C++ Osmium + OGR high-performance pipeline. Clips the massive Poland PBF strictly to the 1.5km walking buffers of transit stops, saving massive amounts of RAM and disk space.
*   **`06_identify_rcn_teryt.py`**: Spatial intersection mapping transit hubs to specific administrative TERYT codes for real estate querying.

### Phase 2: Real Estate Hardening (RCN)
*   **`07_harvest_rcn_omnibus.py`**: Connects to the national WFS (GUGiK) to download vast XML troves of local real estate transactions.
*   **`08_fix_relational_data.py`**: Reconstructs broken, nested GML relationships (handling complex XLink pointers specific to Polish county databases like Łódź).
*   **`09_fix_suwalki_geometry.py`**: Global fallback algorithm restoring valid Point geometries for non-standard real estate multipolygons.
*   **`10_unify_schemas.py`**: Aggressive standardization of thousands of disjointed local RCN columns into a strict, unified economic format (price, area, date).
*   **`11_build_master_db.py`**: Concatenates all verified property records into the National Master Database (over 220,000 transactions).

### Phase 3: Urban Intelligence & The Gravity Engine
*   **`12_audit_data_quality.py`**: Mid-flight validation. Verifies coordinate validity, eliminates teleporting stops (0,0 coords), and audits schema compliance.
*   **`13_isolate_city_data.py`**: The "Splinter" process. Cuts the National Master DB and National Population grid into autonomous, localized GeoPackages per city, moving operations to the decentralized `data/cities/` architecture.
*   **`14_build_isc_valuation.py`**: **The Urban Intelligence Engine.** Parses the complex `all_tags` HSTORE of every building. Assigns Tiers (T0-T6) based on structural taxonomy (e.g., recognizing `uic_ref` to designate a National Rail Hub instead of just a generic station). Incorporates base city population logs and physical volume metrics to calculate the definitive Monetary Weight of every POI category in the city (`poi_valuation.json`).
*   **`15_compute_stop_dna.py`**: **The Grand Integrator.** 
    *   Merges Stops into Logical Hubs (`linkage='single'`, 150m).
    *   Computes exact GTFS unique departures per hour without heavy drop_duplicate cloning (`nunique()`).
    *   Dynamically maps the intelligence of Step 14 onto physical buildings.
    *   Calculates highly optimized C-GEOS vectorized Euclidean distances to POIs.
    *   Solves Huff Models strictly in-place (`.transform('sum')`) to prevent RAM Cartesian explosions (OOM).
    *   Applies Tier-based Diminishing Returns and extracts 100% of the demographic grid.
    *   Generates the unflattened, linear Local and National Z-Scores.
    *   Exports ultra-lightweight `.parquet` matrices for Next.js UI integration and the final `stop_dna.gpkg` vectors.

---

## 5. Tooling & Auditing Suite (`scripts/tools/`)

The platform enforces a "Verify, Then Trust" standard via rigorous auditing tools:

*   **`100_percent_dna_validator.py` (The Golden Auditor):** A massive, multi-threaded validation engine. It traverses the final `stop_dna.gpkg` for all cities, deduplicates logic hubs so reports reflect truth, validates statistical standard deviations (Z-Scores), audits population drift, and generates the massive `GOLDEN_DNA_AUDIT` Markdown reports. It ensures the Math is perfect before any map is rendered.
*   **`orchestrator.py`**: Not just a script, but the master commander of the pipeline. It handles parallel process streaming (running multiple cities on multiple CPU cores simultaneously), state management (`.pipeline_state.json`), failure resuming, and parameter parsing (e.g., `--cities kielce,krakow`).
*   **Utility Auditors:** `verify_isolation.py`, `generate_full_inventory.py`, `verify_final_pipeline.py`.

---

## 6. Technical Stack & Engineering Directives

### Stack:
*   **Language**: Python 3.12+ 
*   **Core Libraries**: GeoPandas (C-GEOS), Pandas (NumPy vectorization), Shapely, scikit-learn (AgglomerativeClustering), pyarrow/fastparquet.
*   **Spatial Engines**: Osmium Tool (C++) for PBF clipping, GDAL/OGR 3.8+ (C++) for relational mapping.
*   **Databases / Formats**: OGC GeoPackage (GPKG) with R-Tree Spatial Indexing, Apache Parquet (for extreme frontend IO speed), H3 Hexagons.
*   **Coordinate Reference System**: EPSG:2180 (Poland CS92) strictly enforced for all distance and area physics. Exported to WGS84 (EPSG:4326) strictly at the end of the pipeline for Mapbox/Leaflet UI rendering.

### Development Directives (Senior Engineering Standard):
1.  **C-Level Vectorization First**: Python `apply(lambda)` loops over massive spatial frames are banned. Distance calculations and gravity models must be reduced to flat arrays (e.g., `x.values`, `y.values`) or utilize native C bindings (`geometry.distance()`).
2.  **No RAM Cartesian Explosions**: Complex `groupby.sum()` followed by `merge()` on multi-million row DataFrames are banned. Memory must be preserved using in-place operations like `.transform('sum')` and pre-join duplication pruning.
3.  **Absolute RCA**: Every implementation failure undergoes a rigorous Root Cause Analysis. Solutions address the source of the problem (e.g., normalizing names in Step 02), rather than patching the symptoms downstream (in Step 15).
4.  **Idempotency**: Pipeline scripts are designed to skip existing, valid data to ensure rapid recovery and low resource waste. Force updates are managed explicitly by the Orchestrator.

---


================================================================================
SYSTEM SPECIFICATION: JOBHUNT (ID: jobhunt)
Deep Link: https://czerwinskidawid.pl/#projects/jobhunt
================================================================================

# JobHunt — Universal Multi-Profile Recruitment Pipeline & Automation Monorepo

[![Architecture: Monorepo](https://img.shields.io/badge/Architecture-Monorepo%20Local--First-blue.svg)](file:///home/gzyms/Dev%20Projects/JobHunt)
[![Stack: Node.js / Python / Docker / Next.js](https://img.shields.io/badge/Stack-Node.js%20%7C%20Python%20%7C%20Docker%20%7C%20Next.js-emerald.svg)](file:///home/gzyms/Dev%20Projects/JobHunt)
[![AI Engine: Local-First Ollama & OpenRouter](https://img.shields.io/badge/AI%20Engine-Local--First%20Ollama%20%7C%20OpenRouter-orange.svg)](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/ai-provider.mjs)
[![Diagnostics: 7-Tab Suite & E2E Trace](https://img.shields.io/badge/Diagnostics-7--Tab%20Suite%20%26%20E2E%20Trace-blueviolet.svg)](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/diagnostics/page.tsx)
[![Maintenance: 1-Click Cleanup Suite](https://img.shields.io/badge/Maintenance-1--Click%20Cleanup-crimson.svg)](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/cleanup.mjs)
[![Test Suite: 1570 Tests Passing](https://img.shields.io/badge/Tests-1570%20Passing-success.svg)](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/test-all.mjs)
[![Typesetting: LaTeX pdflatex UTF-8](https://img.shields.io/badge/Typesetting-LaTeX%20pdflatex%20UTF--8-purple.svg)](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/templates/cv-template.tex)
[![Providers: 28 Active Portals](https://img.shields.io/badge/Providers-28%20Active%20Portals-success.svg)](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/portals.yml)

**JobHunt** is an enterprise-grade, privacy-first, multi-candidate automated recruitment operating system and monorepo. It manages the entire lifecycle of high-scale job application campaigns: from multithreaded portal scraping across 28 global and domestic providers with stealth WAF evasion, through local/cloud LLM evaluation and scoring rubrics, down to dynamic LaTeX CV tailoring with 3-tier caching, automated LinkedIn Easy Apply browser orchestration, 1-click maintenance cleanup, and Dockerized Gmail SLA status tracking.

---

## 1. Executive TL;DR & System Overview

### 1.1 What is JobHunt?
JobHunt solves the friction, fatigue, and latency of running high-volume, hyper-targeted job application campaigns. Instead of relying on manual form submissions, generic untailored resumes, or slow manual scraping, JobHunt treats job hunting as a **distributed, deterministic data pipeline**.

```
[28 Job Portals / ATS Feeds] ──► [Stealth WAF Scraper] ──► [Pipeline Queue (data/pipeline.md)]
                                                                     │
                                                                     ▼
[Docker Gmail SLA Monitor]  ◄── [Selenium Easy Apply]  ◄── [AI Evaluator & Scorecard (0-5)]
            │                              ▲                         │
            ▼                              │                         ▼
     [SQLite jobs.db]             [Tailored LaTeX PDFs] ◄── [3-Tier Cache (L1/L2/L3)]
```

### 1.2 Core Architectural Philosophies
1. **Local-First & Privacy Isolation:** All candidate identity profiles, master resumes (`cv.md`), evaluation reports, compiled PDFs, and database records live on local disk. No candidate data is shared across profiles or uploaded to proprietary third-party servers.
2. **Zero-AI for Metadata (Deterministic Data Flow Mandate):** URLs, company IDs, contract types, raw salary numbers (`__NEXT_DATA__` React Query dehydrated states), and job IDs are handled **100% deterministically** via structured parsers. AI is strictly isolated to qualitative analysis (matching experience against requirements, scorecard computation, and keyword rewriting).
3. **Anti-Fabrication & CV-First Prompting:** Resumes and cover letters are generated *exclusively* by reformulating verified achievements from candidate source-of-truth files (`cv.md`, `profile.yml`, `story-bank.md`). Skills and tech stacks outside the candidate's authentic background are strictly forbidden.
4. **Multi-Candidate & Dual-Track Separation:** Multiple job seekers and dual career tracks (e.g. IT Fullstack/AI vs Logistics/Operations) operate independently through isolated configuration directories in `profiles/<candidate_name>/` with instantaneous bidirectional write-back sync.
5. **Resilient AI Waterfall & 3-Tier Cache:** Seamless fallback from local Ollama instances (`gemma4:latest`) to cloud LLMs (OpenRouter) on HTTP 429 rate limits, backed by L1 (per-job), L2 (archetype), and L3 (component) caches enabling $<1\text{s}$ zero-shot PDF re-compilations.
6. **1-Click Maintenance & Zero Zombie Footprint:** Granular and bulk maintenance operations prune orphan processes, stale pipeline listings, temporary LaTeX junk, and cache drift with dark-mode native confirm modals.

---

### 1.3 Monorepo Subsystem Matrix

| Subsystem / Module | Directory / Path | Tech Stack | Runtime / Port | Core Responsibilities |
| :--- | :--- | :--- | :--- | :--- |
| **`career-ops` Engine** | [`career-ops/`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops) | Node.js (ESM), Playwright Chromium | CLI / Node 18+ | 28 portal providers, deduplicated scanning, LLM scorecard evaluation, LaTeX building, ATS repair engine. |
| **`career-ops/web`** | [`career-ops/web/`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web) | Next.js 14 (App Router), React, Tailwind | HTTP `:3000` | Full command center UI: 11 views (`/`, `/pipeline`, `/jobs`, `/apply`, `/inbox`, `/cv`, `/profiles`, `/diagnostics`, `/explorer`, `/config`, `/jobs/[id]`). |
| **AI Subsystem Core** | [`career-ops/ai-provider.mjs`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/ai-provider.mjs) | OpenRouter REST, Ollama REST | Local / Cloud | Universal AI provider with local-first priority, fallback waterfall, JSON validation, and circuit breakers. |
| **Diagnostics & Testing Suite** | [`career-ops/web/src/app/diagnostics`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/diagnostics) | TypeScript, Node.js Test Harness | HTTP `:3000` & CLI | 7-tab diagnostics center (Portals, E2E Trace, CV Matrix, AI Providers, System, Suite Runner with 1570 tests, Maintenance & Storage). |
| **1-Click Cleanup & Maintenance** | [`career-ops/cleanup.mjs`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/cleanup.mjs) | Node.js, Next.js API, ConfirmModal | CLI & Web UI | Granular and bulk cleanup of runs, pipeline purge, LaTeX artifacts, orphaned cache, and Docker log rotation. |
| **`Auto_job_applier_linkedIn`** | [`Auto_job_applier_linkedIn/`](file:///home/gzyms/Dev%20Projects/JobHunt/Auto_job_applier_linkedIn) | Python 3.10+, Selenium, BeautifulSoup | Python CLI | Automated LinkedIn Easy Apply application bot, answers database, session cookie handling, safety gate `pause_before_submit`. |
| **`job-ops`** | [`job-ops/`](file:///home/gzyms/Dev%20Projects/JobHunt/job-ops) | Docker Compose, Node.js, SQLite | HTTP `:3005` (mapped from `:3001`) | Background container tracking recruiter emails, Gmail SLA compliance monitoring, and SQLite database `jobs.db`. |
| **`profiles/` Engine** | [`profiles/`](file:///home/gzyms/Dev%20Projects/JobHunt/profiles) | Bash, YAML, Node.js | Local Filesystem | Dual-track candidate profile store (`dawid_czerwinski`, `dawid_czerwinski_logistics`), deployment scripts, and write-back sync. |
| **Behavioral Intelligence** | [`ai-job-search/`](file:///home/gzyms/Dev%20Projects/JobHunt/ai-job-search) | Markdown, Python, LaTeX | Local Filesystem | 7-layer framework: candidate narrative, behavioral profile, writing style DNA, salary lookup, negotiation scripts, STAR story bank. |
| **Root Orchestrator** | [`dev.sh`](file:///home/gzyms/Dev%20Projects/JobHunt/dev.sh) | Bash | Native CLI | Single unified command-line entrypoint to start, stop, monitor, and manage the entire monorepo process tree. |

---

### 1.4 60-Second Quickstart

```bash
# 1. Start Next.js Command Center on http://localhost:3000
./dev.sh start

# 2. Start Docker Gmail SLA tracking container
./dev.sh docker-up

# 3. Check system health and active profiles
./dev.sh status

# 4. Run multi-threaded scraper across all 28 portals
cd career-ops && npm run scan

# 5. Evaluate pending listings with local Ollama LLM
npm run ollama:eval -- --pipeline --limit 10

# 6. Compile tailored LaTeX CV variant for job #046
node notifications/cv-generator.mjs --job 46 --mode light

# 7. Run automated test suite (1570 tests)
npm test

# 8. Run 1-click maintenance cleanup
node cleanup.mjs --all
```

---

### 1.5 Performance & Reliability Benchmarks

* **LLM Evaluation Latency:** Reduced from **~45s to ~9.26s per job** (65% speedup) by prioritizing `cv.md` at the prompt start, moving machine-readable `---SCORE_SUMMARY---` blocks to the very top of output generation, and setting `repeat_penalty: 1.15` to eliminate generation loops.
* **Zero-Shot PDF Re-compilation:** Re-rendering tailored PDFs from L1/L2 cache takes **$<1.0\text{s}$** without invoking AI models.
* **Typesetting Stability:** Strict LaTeX preamble with `[utf8]{inputenc}`, `[T1]{fontenc}`, and explicit `\nopagebreak[4]` tags ensures **0 orphan headers, 0 page-break widows**, and 100% support for Polish diacritics (`ę`, `ą`, `ł`, `ó`, `ś`, `ć`, `ż`, `ź`, `ń`).
* **Scraper Resiliency:** 28 active portal providers operating with `0 skipped — no provider matched` across domestic (Pracuj.pl, JustJoin.it, NoFluffJobs, SolidJobs) and international boards (Himalayas, Arbeitnow, WeWorkRemotely, RemoteOK, 4DayWeek, Arbeitsagentur, The Hub).
* **Test Suite Coverage:** 1570 automated assertions executing across CV matrix tests, E2E pipeline simulation, system integration probes, and documentation integrity.

---

## 2. End-to-End System Topology & Data Flow

### 2.1 Master Architecture Topology

```mermaid
graph TD
    %% LAYER 1: PROFILES & IDENTITY
    subgraph L1 ["1. Candidate Identity & Profiles Layer"]
        P_Dir["Candidate Profiles Store<br/>(profiles/dawid_czerwinski/ & logistics/)"]
        P_UI["Web Profiles Hub<br/>(/profiles)"]
        P_Sync["Profile Sync Engine<br/>(profiles.ts / load-profile.sh)"]
        P_Active["Active Workspace Identity<br/>(career-ops/cv.md & config/profile.yml)"]
        
        P_UI <-->|Bidirectional Write-Back| P_Dir
        P_Sync -->|Deploys to Workspace| P_Active
    end

    %% LAYER 2: SCRAPING & STEALTH WAF
    subgraph L2 ["2. Multithreaded Scraper & Stealth Engine (28 Providers)"]
        Scan_CLI["Scanner CLI<br/>(scan.mjs)"]
        Portals_YAML["Portal Config & Geo Filters<br/>(portals.yml)"]
        Providers["28 Native Providers<br/>(providers/*.mjs)"]
        Playwright_WAF["Chromium Stealth Engine<br/>(browser-extract.mjs)"]
        Dedupe_TSV["Deduplication History<br/>(data/scan-history.tsv)"]
        Pipe_MD["Unprocessed Queue<br/>(data/pipeline.md)"]
        
        Portals_YAML --> Scan_CLI
        P_Active -.->|Title/Geo Rules| Scan_CLI
        Scan_CLI --> Providers
        Providers --> Playwright_WAF
        Playwright_WAF -->|Check Seen URLs| Dedupe_TSV
        Playwright_WAF -->|Append Valid Listings| Pipe_MD
    end

    %% LAYER 3: AI EVALUATION & 3-TIER CACHE
    subgraph L3 ["3. AI Evaluation Waterfall & 3-Tier Cache"]
        Eval_CLI["Evaluator CLI<br/>(ollama-eval.mjs / openrouter-runner.mjs)"]
        AI_Water["AI Waterfall Engine<br/>(ai-provider.mjs)"]
        OpenRouter["Cloud Provider<br/>(OpenRouter REST API)"]
        Ollama_Local["Local Engine<br/>(Ollama gemma4:latest)"]
        Reports_MD["Markdown Reports<br/>(reports/###-company-date.md)"]
        Debug_JSON["Raw Diagnostic Dumps<br/>(reports/debug/###-dump.json)"]
        App_Tracker["Master Tracker<br/>(data/applications.md)"]
        Cache_Store["3-Tier Cache Storage<br/>(output/cv-cache/)"]
        
        Pipe_MD --> Eval_CLI
        P_Active --> Eval_CLI
        Eval_CLI --> AI_Water
        AI_Water -->|Primary Call| OpenRouter
        OpenRouter -.->|Fallback on HTTP 429/Timeout| Ollama_Local
        AI_Water --> Reports_MD
        AI_Water --> Debug_JSON
        AI_Water --> App_Tracker
        AI_Water --> Cache_Store
    end

    %% LAYER 4: AGENTIC CV GENERATION & LATEX
    subgraph L4 ["4. Agentic CV Generation & LaTeX Compilation"]
        CV_Engine["CV Generator Engine<br/>(notifications/cv-generator.mjs)"]
        LaTeX_Tpl["A4 UTF-8 Template<br/>(templates/cv-template.tex)"]
        LaTeX_Build["LaTeX Assembler & Compiler<br/>(build-cv-latex.mjs / generate-latex.mjs)"]
        PDF_Out["Multi-Variant PDF Artifacts<br/>(output/cv-###-company-mode.pdf)"]
        
        Cache_Store --> CV_Engine
        P_Active --> CV_Engine
        CV_Engine --> LaTeX_Tpl
        LaTeX_Tpl --> LaTeX_Build
        LaTeX_Build -->|pdflatex execution| PDF_Out
    end

    %% LAYER 5: INTERFACES, MAINTENANCE & AUTOMATION
    subgraph L5 ["5. Web Command Center, Maintenance, Easy Apply & SLA Tracking"]
        Web_Hub["Next.js Web UI<br/>(http://localhost:3000)"]
        CV_Hub["Resume Hub (/cv)<br/>Live PDF iFrame & Diffs"]
        Diag_Hub["Diagnostics Hub (/diagnostics)<br/>7-Tab Testing Suite A-Z"]
        Jobs_Hub["Applications Tracker (/jobs)<br/>Multi-Select & Batch Deletion"]
        Inbox_Hub["Inbox SLA Triage (/inbox)<br/>Gmail Recruiter Matcher"]
        Cleanup_Suite["1-Click Cleanup Engine<br/>(cleanup.mjs & ConfirmModal)"]
        LinkedIn_Bot["Selenium Easy Apply Bot<br/>(Auto_job_applier_linkedIn)"]
        Docker_SLA["Docker Gmail SLA Monitor<br/>(job-ops on :3005)"]
        SQLite_DB["Recruitment Database<br/>(job-ops/jobs.db)"]
        
        PDF_Out --> CV_Hub
        Web_Hub --> CV_Hub
        Web_Hub --> Diag_Hub
        Web_Hub --> Jobs_Hub
        Web_Hub --> Inbox_Hub
        Web_Hub --> Cleanup_Suite
        Web_Hub --> LinkedIn_Bot
        LinkedIn_Bot -->|Submits Application| PDF_Out
        Docker_SLA --> SQLite_DB
        Web_Hub <-->|Live Query| SQLite_DB
    end
```

---

### 2.2 Sub-Diagram 1: Multi-Provider Scraping & Anti-Bot Evasion

```mermaid
sequenceDiagram
    autonumber
    participant CLI as Scanner (scan.mjs)
    participant Provider as Provider (e.g. pracuj.mjs)
    participant WAF as Playwright Chromium Stealth
    participant Target as Job Portal / ATS Server
    participant Pipe as Storage (pipeline.md)

    CLI->>Provider: Execute scan with location & keyword filters
    Provider->>WAF: Launch headless browser (--disable-blink-features=AutomationControlled)
    WAF->>Target: GET /praca with desktop Chrome headers (sec-ch-ua, accept-language)
    Target-->>WAF: Return HTML payload (with Cloudflare WAF clear)
    
    alt Dehydrated React Query State (__NEXT_DATA__)
        WAF->>Provider: Extract <script id="__NEXT_DATA__"> JSON
        Provider->>Provider: Parse structured salary (B2B/UoP), remote status, location, tags
    else Standard DOM Extraction
        WAF->>WAF: DOM Cleaning (remove [data-test*="similar"], recommendations)
        WAF->>Provider: Return clean job description text
    end

    Provider->>CLI: Return normalized JobListing object
    CLI->>CLI: Check deduplication hash in scan-history.tsv
    alt New Unique Offer
        CLI->>Pipe: Append offer with metadata (📍 Location, 🏠 Mode, 💰 Salary)
    else Duplicate
        CLI->>CLI: Skip offer (record duplicate count)
    end
```

---

### 2.3 Sub-Diagram 2: AI Waterfall Evaluation & 3-Tier Cache Architecture

```mermaid
stateDiagram-v2
    [*] --> IngestJob: Read job from data/pipeline.md
    
    IngestJob --> CheckCache: Query output/cv-cache/
    state CheckCache {
        [*] --> CheckL1: Query L1 (num-company.json)
        CheckL1 --> L1Hit: Cache fresh (mtime > report.mtime)
        CheckL1 --> CheckL2: L1 Miss or Stale
        CheckL2 --> L2Hit: L2 Archetype Found (archetype/slug.json)
        CheckL2 --> L3Check: L2 Miss
        L3Check --> L3Hit: Components Found (components/type/name/variant.json)
        L3Check --> FullAIRequired: L3 Miss
    }

    CheckCache --> AIWaterfall: Cache Miss / Full Generation Needed
    
    state AIWaterfall {
        [*] --> TryOpenRouter: POST openrouter.ai/v1/chat/completions
        TryOpenRouter --> ValidateJSON: HTTP 200 OK
        TryOpenRouter --> FallbackOllama: HTTP 429 / Timeout / Network Error
        FallbackOllama --> ValidateJSON: Local Ollama HTTP 200 OK
        FallbackOllama --> StaticFallback: Ollama Unreachable
    }

    AIWaterfall --> GenerateArtifacts: Valid Output Received
    state GenerateArtifacts {
        [*] --> WriteReport: Save reports/###-company-date.md
        WriteReport --> WriteDebugDump: Save reports/debug/###-dump.json
        WriteDebugDump --> UpdateTracker: Append data/applications.md (file:/// URLs)
        UpdateTracker --> PersistCache: Write L1, L2, and L3 cache entries
    }

    GenerateArtifacts --> [*]: Ready for LaTeX CV Generation
```

---

### 2.4 Sub-Diagram 3: Agentic CV Pipeline & LaTeX Compilation

```mermaid
flowchart TD
    A["Job Target (#NUM & Company)"] --> B["cv-generator.mjs (ensureTailoredPdf)"]
    C["Candidate Master CV (cv.md)"] --> B
    D["Config & Archetypes (profile.yml)"] --> B
    
    B --> E{"Select AI Mode"}
    E -->|none| F["Static Payload (getAuthenticCvPayload)"]
    E -->|light| G["Single Consolidated AI Call (~10-20s)"]
    E -->|full| H["5-Step Sequential Pipeline (extract -> tailor -> select -> rank)"]
    E -->|custom| I["User-defined pipeline steps from profile.yml"]
    
    F --> J["Merge Tailored Payload onto Base"]
    G --> J
    H --> J
    I --> J
    
    J --> K["Inject Variables into templates/cv-template.tex"]
    K --> L["Enforce Typesetting Constraints<br/>(A4 Paper, UTF-8, T1 fontenc, \nopagebreak)"]
    L --> M["Compile via pdflatex (generate-latex.mjs)"]
    M --> N["Disk Artifact: output/cv-{num}-{company}-{mode}.pdf"]
    N --> O["Web UI /cv 4-Tab Hub (Live PDF iFrame Preview)"]
```

---

### 2.5 Sub-Diagram 4: LinkedIn Easy Apply State Machine

```mermaid
stateDiagram-v2
    [*] --> Initialize: Launch Python Selenium Driver
    Initialize --> LoadCookies: Restore session cookies from profile
    LoadCookies --> CheckAuth: Verify LinkedIn login state
    
    state CheckAuth {
        [*] --> LoggedIn: Valid session
        [*] --> PromptLogin: Session expired / 2FA required
    }
    
    CheckAuth --> ExecuteSearch: Load search queries from search.py
    ExecuteSearch --> IterateJobs: Fetch Easy Apply job listings
    
    state IterateJobs {
        [*] --> OpenModal: Click "Easy Apply"
        OpenModal --> PopulateFields: Fill phone, city, salary from personals.py
        PopulateFields --> AnswerCustomQuestions: Match questions.py rules
        AnswerCustomQuestions --> AttachResume: Upload output/cv-###-company.pdf
        AttachResume --> SafetyGate: Review step reached
    }
    
    state SafetyGate {
        [*] --> CheckPauseFlag: pause_before_submit == True?
        CheckPauseFlag --> WaitUserConsent: YES -> Halt & prompt operator
        CheckPauseFlag --> AutoSubmit: NO -> Programmatic click Submit
    }
    
    SafetyGate --> RecordHistory: Log submission in CSV & SQLite
    RecordHistory --> IterateJobs: Next job offer
    IterateJobs --> [*]: Batch completed
```

---

## 3. AI Subsystem Architecture & Implementation Matrix

JobHunt implements an enterprise-grade, privacy-first Artificial Intelligence architecture designed to maximize qualitative accuracy while strictly eliminating hallucination risks and vendor lock-in.

```mermaid
graph TD
    subgraph AI_Layers ["AI Subsystem Layers in JobHunt"]
        AIP["1. Universal AI Provider (ai-provider.mjs)<br/>Waterfall: OpenRouter -> Ollama (gemma4) -> Static"]
        OLL["2. Local Evaluation Engine (ollama-eval.mjs)<br/>CV-First Prompt, Chronological ---SCORE_SUMMARY--- (9.26s)"]
        CVG["3. Agentic CV Pipeline (cv-generator.mjs)<br/>4 Modes (none, light, full 5-step, custom) + 3-Tier Cache"]
        AST["4. In-App Web Assistant (api/assistant/route.ts)<br/>Action Envelopes <<act:ACTION_ID>> & System Integration"]
        RUN["5. Autonomous CLI Agent Harness (api/run/route.ts)<br/>8 CLI Runtimes: agy, claude, gemini, qwen, copilot, opencode, codex"]
        BEH["6. Behavioral Intelligence Framework (ai-job-search/)<br/>7-Layer Matrix, STAR Story Bank & Salary Intelligence"]
        CFG["7. Dynamic AI Config & Probing (/config)<br/>Live Model Switcher, OpenRouter Fetch, Ollama Latency Probe"]
    end
    
    subgraph AI_Rules ["Ironclad AI Mandates"]
        R1["Zero-AI for Metadata Mandate<br/>(Deterministic URLs, B2B/UoP, IDs)"]
        R2["CV-First & Anti-Fabrication<br/>(Keywords reformulated, never fabricated)"]
        R3["Privacy-First & Local-First<br/>(100% Offline Capability via Ollama)"]
    end
    
    AI_Rules -.-> AI_Layers
```

### 3.1 AI Implementation Matrix

| AI Subsystem | Implementation File | Primary Models | Fallback Path | Core Functionality |
| :--- | :--- | :--- | :--- | :--- |
| **Universal AI Provider** | [`ai-provider.mjs`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/ai-provider.mjs) | Local Ollama `gemma4:latest` (9B) | OpenRouter (Gemini 2.5, Claude) $\to$ Static | Local-first cascading waterfall, JSON validation, retry loops. |
| **Local Job Evaluator** | [`ollama-eval.mjs`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/ollama-eval.mjs) | Ollama `gemma4:latest` (9B) / `llama3.3` | OpenRouter (`gemini-eval.mjs`) | CV-first prompt, chronological scorecard generation, 0.0–5.0 rubric. |
| **Agentic CV Generator** | [`notifications/cv-generator.mjs`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/notifications/cv-generator.mjs) | Local Ollama / OpenRouter | Base Candidate Payload | 4 AI tailoring modes (`none`, `light`, `full`, `custom`), L1/L2/L3 caching, multilingual RODO. |
| **In-App Web Assistant** | [`api/assistant/route.ts`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/api/assistant/route.ts) | Local / CLI Agent | Local memory | Chat assistant emitting `<<act:ACTION_ID>>` envelopes to drive Web UI. |
| **Autonomous CLI Runner** | [`api/run/route.ts`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/api/run/route.ts) | `agy`, `claude`, `gemini`, `qwen`, `copilot` | System CLI resolution | Headless evaluation, PDF rendering, autonomous portal repair. |
| **Behavioral Intelligence** | [`ai-job-search/`](file:///home/gzyms/Dev%20Projects/JobHunt/ai-job-search) | LLM Guided Markdown | `story-bank.md` | 7-part matrix: voice DNA, behavioral traits, negotiation scripts. |
| **Dynamic AI Config** | [`api/config/env/route.ts`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/api/config/env/route.ts) | OpenRouter API / Ollama API | `.env` / `profile.yml` | AI Waterfall Visualizer, Step Builder, Compliance & Unified Test-Agent. |

---

### 3.2 Ironclad AI Mandates & Anti-Hallucination Protocols

1. **The Deterministic Metadata Mandate (Zero-AI for Metadata):**
   * URLs, company IDs, contract types (B2B vs UoP), location tags, and exact salary ranges (extracted from `<script id="__NEXT_DATA__">`) **MUST NEVER be parsed, extracted, or modified by LLMs**.
   * All metadata flows 100% deterministically via structured JSON parameters (`--json`, `--job-url`). AI is strictly confined to qualitative evaluation, scorecard matching, and resume keyword alignment.
2. **Anti-Fabrication & CV-First Prompting:**
   * In all evaluation and tailoring prompts, candidate resume data (`cv.md` & `article-digest.md`) is injected at the very top of the prompt context to eliminate the LLM "lost in the middle" effect.
   * *Rule:* "Keywords get reformulated, never fabricated." The AI is explicitly forbidden from inventing tools, frameworks, degrees, or certifications outside the candidate's authentic profile.
3. **Privacy-First & Local-First Guarantee:**
   * JobHunt operates completely offline without internet connectivity or cloud API keys by prioritizing local Ollama models (`gemma4:latest` or `llama3.3`). Candidate data never leaves the host machine unless cloud inference is explicitly enabled.

---

### 3.3 Universal AI Provider & Fallback Waterfall (`ai-provider.mjs`)

The AI engine in [`career-ops/ai-provider.mjs`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/ai-provider.mjs) provides a unified interface `callAI(taskName, systemPrompt, userPrompt, options)` with configurable task chains:

```javascript
// Example: Task-specific waterfall execution in ai-provider.mjs
const result = await callAI('cv_tailoring', systemPrompt, userPrompt, {
  json: true,
  retries: 2,
  timeoutMs: 90000,
});
```

* **Waterfall Progression (Local-First Priority):**
  1. **Tier 1 (Local-First):** Local Ollama HTTP REST endpoint (`http://localhost:11434/api/generate`) running `gemma4:latest` for zero-latency, private, zero-token-cost evaluation and tailoring.
  2. **Tier 2 (Cloud Fallback / Multi-Model):** OpenRouter REST API (`https://openrouter.ai/api/v1/chat/completions`) for cloud fallback on model unavailability or when high-capacity models are requested.
  3. **Tier 3 (Static SSOT Fallback):** If all AI models are unreachable, deterministic rule-based assembly constructs an authentic valid payload from `cv.md` and `article-digest.md` without failing the campaign run.

---

### 3.4 Local AI Evaluation Engine & Scoring Rubric (`ollama-eval.mjs`)

The evaluator in [`career-ops/ollama-eval.mjs`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/ollama-eval.mjs) scores job descriptions against candidate profiles:

* **Chronological Generation Optimization:** The system prompt forces the LLM to output the machine-readable summary block at the very top of its response:
  ```markdown
  ---SCORE_SUMMARY---
  SCORE: 4.5
  ARCHETYPE: python-backend
  VERDICT: High priority target with strong technical overlap.
  ---END_SUMMARY---
  
  # Detailed Qualitative Report...
  ```
  This eliminates regex extraction misses, avoids second-pass fallback calls, and dropped latency from **~45s to ~9.26s per offer**.
* **Generation Parameters:** `temperature: 0.25`, `repeat_penalty: 1.15` (prevents loop degeneration on repetitive job posting sections).
* **Scoring Rubric (0.0 to 5.0):**
  * `4.5 – 5.0`: Immediate High Priority (Strong stack overlap, target compensation, verified legitimacy).
  * `3.5 – 4.4`: Viable Application (Good overlap, standard target).
  * `< 3.5`: Marginal / Mismatched (Flagged technical gaps or unverified legitimacy).

---

### 3.5 Agentic CV Personalization Pipeline & 4 AI Modes (`cv-generator.mjs`)

Located in [`career-ops/notifications/cv-generator.mjs`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/notifications/cv-generator.mjs), this module personalizes candidate resumes for target jobs:

* **The 4 AI Operation Modes:**
  1. `none`: Zero AI calls. Instant compilation using authentic candidate base payload.
  2. `light`: Single consolidated AI prompt (~10–20s) personalizing the professional summary, 6–8 ATS competencies, and matching top project bullet points.
  3. `full`: 5-step sequential multi-agent style pipeline:
     $$\text{extract\_keywords} \to \text{tailor\_summary} \to \text{select\_competencies} \to \text{rank\_experience} \to \text{select\_projects}$$
  4. `custom`: User-defined pipeline step sequence configured in `config/profile.yml` or the Web UI Step Builder.
* **Multilingual RODO / GDPR Engine (`RODO_CLAUSES`):**
  - Automates compliance injection based on language detection (`detectLanguage`):
    - **PL:** *Wyrażam zgodę na przetwarzanie moich danych osobowych... (Dz. U. 2018 poz. 1000)*
    - **EN:** *I hereby consent to the processing of my personal data... (GDPR Art. 6(1)(a))*
    - **DE:** *Ich willige in die Verarbeitung meiner personenbezogenen Daten... (DSGVO)*
    - **FR:** *J'accepte le traitement de mes données personnelles... (RGPD)*
* **2-Page Strict LaTeX Typesetting (`cv-template.tex`):**
  - Page 1: Header, Summary, ATS Competencies, 4 Google XYZ Projects.
  - Page 2 (`\newpage`): Professional Experience, Education, Technical Skills, Dynamic RODO footer.
  - Columnar header `p{0.86\textwidth}@{\extracolsep{\fill}}r` preventing date overlap and margin overflow.
* **3-Tier Cache Integration:** Payloads are cached across L1 (per-job), L2 (archetype), and L3 (component library), enabling $<1.0\text{s}$ zero-shot re-compilations.

---

### 3.6 In-App Web AI Assistant & Action Envelopes (`api/assistant/route.ts`)
The Next.js Command Center embeds a local AI chat assistant in [`career-ops/web/src/app/api/assistant/route.ts`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/api/assistant/route.ts). The assistant interacts with the dashboard via **Action Envelopes** (`<<act:ACTION_ID {"arg":"val"}>>`):

* `navigate {"path":"/pipeline?tab=OFFER"}`: Navigates the operator to any Web UI tab.
* `filterPipeline {"tab":"EVALUATED","min":4.0}`: Filters the live application table in place.
* `evaluate {"url":"https://..."}`: Dispatches a background evaluation worker.
* `evaluateCompany {"company":"State Street"}`: Evaluates all pending inbox offers for a company.
* `generatePdf {"n":"046"}`: Dispatches LaTeX CV generation for job #046.
* `setStatus {"n":"046","status":"Applied"}`: Updates recruitment state in `applications.md`.
* `remember {"fact":"pref"}`: Persists user career preferences into durable long-term memory.
* `setProfile {"roles":[...]}`: Proposes structured profile updates with native user confirmation.

---

### 3.7 Autonomous CLI Agent Execution Harness (`api/run/route.ts` & `src/lib/clis.ts`)

JobHunt orchestrates autonomous background engineering and recruitment tasks via local CLI agent runtimes:

* **Supported CLI Agents:** Antigravity CLI (`agy`), Claude Code (`claude`), Gemini CLI (`gemini`), Qwen (`qwen`), GitHub Copilot (`copilot`), OpenCode (`opencode`), Codex (`codex`).
* **Autonomous Tasks:**
  * `evaluate`: Headless JD evaluation and canonical tracker persistence.
  * `pdf`: Headless ATS CV tailoring and rendering.
  * `fix-portal`: Autonomous agentic debugging of broken career URLs/scrapers with write, edit, bash, and search toolkits.
  * `research`: Portfolio and target company deep-dive investigation.

---

### 3.8 Behavioral Intelligence 7-Layer Framework (`ai-job-search/`)

The [`ai-job-search/`](file:///home/gzyms/Dev%20Projects/JobHunt/ai-job-search) directory structures candidate intelligence into a 7-layer framework:
1. `01-candidate-profile.md`: Master career narrative and verified technical background.
2. `02-behavioral-profile.md`: Communication style, leadership traits, and problem-solving methodologies.
3. `03-writing-style.md`: Voice DNA ensuring all generated communications match the candidate's authentic writing style.
4. `04-salary-lookup.py`: Real-time market compensation intelligence and benchmark calculations.
5. `05-negotiation-scripts.md`: Tactical salary counter-offer scripts and contract clause responses.
6. `06-red-flags.md`: Toxic culture detector and employer risk analysis matrix.
7. `07-interview-prep.md` / `story-bank.md`: Structured repository of STAR+R (Situation, Task, Action, Result + Reflection) interview stories.

---

### 3.9 Dynamic AI Configuration Dashboard (`/config`)

The redesigned Web UI view at [`/config`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/config/page.tsx) provides a full control center:
* **AI Waterfall Visualizer:** Real-time visual display of the active multi-tier AI resolution cascade (Local Ollama $\to$ OpenRouter $\to$ Static Fallback).
* **Custom Pipeline Step Builder:** Drag-and-drop / toggle interface to customize the multi-step CV personalization flow.
* **Compliance & RODO Language Selector:** Configures default legal clause language (PL, EN, DE, FR) for compiled PDF resumes.
* **Unified Diagnostics Test-Agent:** Universal tester allowing one-click prompt verification across any configured LLM model or CLI agent (`agy`, `gemini`, `claude`, etc.) with millisecond response timers.
* **Bidirectional SSOT Sync:** Real-time synchronization across `career-ops/.env` and `config/profile.yml`.

---

## 4. Deep Dive Subsystem Architecture

### 4.1 `career-ops` Node.js Execution Engine
The `career-ops` folder contains the core automation scripts, scrapers, evaluators, and test suites written in modern Node.js (ES Modules).

```
career-ops/
├── ai-provider.mjs               # Universal AI provider with per-task fallback waterfall
├── browser-extract.mjs           # Playwright Chromium scraper with React Query extraction
├── build-cv-latex.mjs            # LaTeX payload merger and TeX document builder
├── cleanup.mjs                   # 1-Click cleanup & maintenance CLI engine
├── generate-latex.mjs            # pdflatex execution and PDF compiler wrapper
├── ollama-eval.mjs               # Local Ollama evaluation engine with scorecard format
├── openrouter-runner.mjs         # OpenRouter multi-mode CLI runner (scan, eval, pipeline, apply)
├── repair-portal.mjs             # Interactive CLI/Web engine for repairing broken career URLs
├── run-polish-test.mjs           # Polish diacritics & UTF-8 character encoding test harness
├── scan.mjs                      # Multithreaded crawler iterating through 28 providers
├── test-all.mjs                  # Master test runner (executes full 1570-test suite)
├── test-cv-matrix.mjs            # CV matrix 4-mode generation and LaTeX test runner
├── test-e2e.mjs                  # End-to-end sandbox pipeline simulator test runner
├── test-system-integrations.mjs  # Subsystem integration probe test runner
├── validate-docs.mjs             # Automated documentation consistency validator
├── portals.yml                   # Master configuration of tracked job portals & filters
├── profile.yml                   # Active candidate profile settings, AI models & thresholds
├── providers/                    # 28 modular portal crawlers (pracuj.mjs, justjoin.mjs, etc.)
├── notifications/
│   ├── cv-generator.mjs          # Agentic CV generation pipeline library core
│   └── dispatcher.mjs            # Telegram & Email alert dispatcher
├── templates/
│   └── cv-template.tex           # Master LaTeX CV template with UTF-8 & orphan protection
├── tests/                        # Automated unit and integration test suites
│   ├── cleanup.test.mjs          # Unit tests for cleanup & maintenance engine
│   ├── cv-matrix.test.mjs        # Tests for CV generation modes and LaTeX outputs
│   ├── e2e-pipeline.test.mjs     # Tests for end-to-end pipeline execution
│   └── system-integrations.test.mjs # Tests for Docker, SQLite, and profile integrations
├── data/
│   ├── applications.md           # Master tracker markdown database
│   ├── pipeline.md               # Unprocessed scraped jobs queue
│   └── scan-history.tsv          # Scraper URL & title deduplication store
└── reports/                      # Evaluation reports (###-company-date.md)
    └── debug/                    # Raw JSON diagnostic dumps (###-dump.json)
```

#### Core Providers in `providers/*.mjs`
The scraper engine includes **28 native providers**, each tailored to the target portal's specific API or DOM structure:
1. `pracuj.mjs` (Pracuj.pl IT & General — Playwright headless Chromium + React Query `__NEXT_DATA__` parsing)
2. `justjoin.mjs` (JustJoin.it REST API v2)
3. `nofluffjobs.mjs` (NoFluffJobs JSON API)
4. `solidjobs.mjs` (Solid.Jobs IT & Engineering APIs)
5. `weworkremotely.mjs` (We Work Remotely RSS/API)
6. `himalayas.mjs` (Himalayas API with TLS JA3/JA4 header consistency & RSS fallback)
7. `remotive.mjs` (Remotive API)
8. `anthropic.mjs` (Greenhouse Boards API)
9. `arbeitnow.mjs` (Arbeitnow API)
10. `thehub.mjs` (The Hub API)
11. `jobicy.mjs` (Jobicy API)
12. `nodesk.mjs` (Nodesk API)
13. `remoteok.mjs` (RemoteOK JSON Feed)
14. `workingnomads.mjs` (Working Nomads API)
15. `4dayweek.mjs` (4DayWeek API)
16. `arbeitsagentur.mjs` (German Federal Employment Agency API v6)
17. `echojobs.mjs` (EchoJobs API)
18. `getonbrd.mjs` (Get on Board API)
19. `glints.mjs` (Glints API)
20. `hackernews.mjs` (Hacker News Jobs Feed)
21. `higheredjobs.mjs` (HigherEdJobs Scraper)
22. `jobspresso.mjs` (Jobspresso Scraper)
23. `jobstreet.mjs` (JobStreet Scraper)
24. `landingjobs.mjs` (Landing.jobs API)
25. `larajobs.mjs` (LaraJobs Feed)
26. `themuse.mjs` (The Muse API)
27. `ashby.mjs` (Direct Ashby ATS parser)
28. `lever.mjs` (Direct Lever ATS parser)

---

### 4.2 `Auto_job_applier_linkedIn` (Python Selenium Bot)
Located in [`Auto_job_applier_linkedIn/`](file:///home/gzyms/Dev%20Projects/JobHunt/Auto_job_applier_linkedIn), this module provides automated execution for LinkedIn Easy Apply postings.

* **Main Entrypoint:** `python runAiBot.py` (or initiated via Web UI `/linkedin`).
* **Configuration Layer (`config/`):**
  * `personals.py`: Candidate demographic variables (First/Last name, phone, city, state, zip, ethnicity, disability, veteran status).
  * `search.py`: Search queries, target job titles, location filters, distance radius, and experience levels.
  * `questions.py`: Answer mapping for common recruiter questions (years of experience, visa requirements, salary expectations, notice period, portfolio links) and the safety flag `pause_before_submit = True`.
* **Application History:** Logs every submitted application into `data/applied_jobs.csv` and SQLite to ensure zero duplicate submissions.

---

### 4.3 `job-ops` (Dockerized Gmail SLA Tracking Service)
Located in [`job-ops/`](file:///home/gzyms/Dev%20Projects/JobHunt/job-ops), this containerized service monitors incoming recruiter correspondence.

* **Container Architecture:** `docker-compose.yml` exposing port `3005:3001`.
* **Database Engine:** SQLite database [`job-ops/data/jobs.db`](file:///home/gzyms/Dev%20Projects/JobHunt/job-ops) tracking application lifecycle states:
  * `APPLIED` $\to$ `SCREENING` $\to$ `INTERVIEW_SCHEDULED` $\to$ `OFFER` / `REJECTED`.
* **Gmail SLA Monitor:** Periodically scans mailbox via IMAP/API for recruiter interview invitations, rejection notices, or test assignments, calculating time-to-response SLA metrics.

---

### 4.4 `profiles/` Candidate Identity Engine (Dual-Track Architecture)
The [`profiles/`](file:///home/gzyms/Dev%20Projects/JobHunt/profiles) directory decouples candidate identities and targeting strategies from the shared execution machinery.

```
profiles/
├── dawid_czerwinski/                # IT Track: Fullstack, AI Engineering, Python, React
│   ├── career-ops/
│   │   ├── cv.md                    # Master IT resume
│   │   ├── profile.yml              # IT compensation targets & AI models
│   │   └── portals.yml              # IT portal keywords & filters
│   ├── linkedin/
│   │   ├── personals.py
│   │   ├── questions.py
│   │   └── search.py
│   └── ai-job-search/               # IT behavioral profiling & STAR stories
├── dawid_czerwinski_logistics/      # Logistics Track: Operations, SLA, Dispatch, Fleet
│   ├── career-ops/
│   │   ├── cv.md                    # Master Logistics resume
│   │   ├── profile.yml
│   │   └── portals.yml
│   ├── linkedin/
│   │   ├── personals.py
│   │   ├── questions.py
│   │   └── search.py
│   └── ai-job-search/
└── load-profile.sh                  # CLI profile deployment script
```

* **Bidirectional Write-Back Sync:** When an operator edits CV text or demographic forms in the Web UI (`/profiles`), changes are immediately written back to `profiles/<name>/` and synced to the active workspace.

---

### 4.5 `career-ops/web` (Next.js 14 App Router Command Center)
The Web UI in [`career-ops/web/`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web) provides a unified graphical control center running on `http://localhost:3000`.

* **Frontend Framework:** Next.js 14 with TypeScript, Tailwind CSS, Lucide icons, and server-sent events for streaming terminal consoles.
* **Key Navigation Views (11 Routes):**
  * **Today (`/`):** Campaign overview, LinkedIn bot status, Docker services health, and SLA tracker cards.
  * **Pipeline Queue (`/pipeline`):** Visual table of pending job listings with one-click evaluation triggers and clean actions.
  * **Applications Tracker (`/jobs`):** Tabbed tracker table (`ALL`, `EVALUATED`, `APPLIED`, `RESPONDED`, `INTERVIEW`, `OFFER`, `REJECTED`, `DISCARDED`, `SKIP`) with multi-select checkboxes, floating batch action bar, and inline deletion.
  * **Apply Assistant (`/apply`):** Guided application workflow and profile matcher.
  * **Inbox SLA Triage (`/inbox`):** Recruiter correspondence triage, Gmail SLA matching, and response SLA countdown timers.
  * **CV Hub (`/cv`):** 4-tab resume workstation (Job & Variant Explorer with live PDF iframe, L1/L2/L3 Cache Manager, Base CV Markdown Editor, LaTeX Compiler).
  * **Profiles (`/profiles`):** Visual and raw form editor for candidate configurations with instant sync.
  * **Diagnostics Hub (`/diagnostics`):** 7-tab testing center (Portals, E2E Trace Sandbox, CV Matrix, AI Providers, System Integrations, Suite Runner, Maintenance & Storage).
  * **Explorer (`/explorer`):** Monorepo file tree explorer with built-in Markdown editor and native PDF iframe preview.
  * **Config (`/config`):** Dynamic AI engine switcher (Local-First Ollama / OpenRouter), AI Waterfall visualizer, Custom Step Builder, and Unified Test-Agent.
  * **Job Detail (`/jobs/[id]`):** In-depth job inspection with **interactive streaming terminal console** (`/api/run/input` connected directly to `child.stdin`).

---

### 4.6 1-Click Cleanup & Maintenance Engine (`cleanup.mjs`)
Located in [`career-ops/cleanup.mjs`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/cleanup.mjs) and integrated into the Web UI via [`career-ops/web/src/lib/cleanup.ts`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/lib/cleanup.ts) and `/api/cleanup`:

* **Maintenance Operations:**
  1. `clean-runs`: Terminates zombie background processes and clears stale task log files (`.career-ops-web/runs/*.md`).
  2. `clean-pipeline`: Purges un-evaluated and expired job offers from `data/pipeline.md`.
  3. `clean-latex`: Removes temporary LaTeX compilation junk (`output/*.aux`, `output/*.log`, `output/*.out`, `output/*.fls`).
  4. `clean-cache`: Prunes orphaned L1/L2/L3 JSON cache files from `output/cv-cache/`.
  5. `clean-debug`: Rotates and cleans diagnostic dumps from `reports/debug/`.
  6. `polish-test`: Executes the Polish UTF-8 encoding verification test suite (`run-polish-test.mjs`).
* **Dark Native Confirm Modal:** All destructive operations in the Web UI utilize the dark-themed [`confirm-modal.tsx`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/components/ui/confirm-modal.tsx), replacing disruptive browser `window.confirm()` popups.

---

### 4.7 Comprehensive 7-Tab Diagnostics & Testing Suite (`/diagnostics`)
The Diagnostics Command Center provides full A-to-Z system verification:

* **Tab 1 (Portals & Scrapers):** Real-time HTTP/API status probing for all 28 portal providers with one-click ATS repair.
* **Tab 2 (E2E Pipeline Trace):** Interactive sandbox simulating the full recruitment flow (Scrape $\to$ Pre-filter $\to$ AI Eval $\to$ CV Tailor $\to$ LaTeX Build $\to$ Dispatch) with step-by-step JSON inspection.
* **Tab 3 (CV Matrix & Variants):** Multi-mode CV generator validator (`none`, `light`, `full`, `custom`) measuring keyword density, compilation time, and PDF output integrity.
* **Tab 4 (AI Models & Providers):** Latency benchmarking for OpenRouter cloud models, local Ollama instances, and CLI agent discovery.
* **Tab 5 (System & Integrations):** Health probes for Docker daemon, SQLite `jobs.db`, active candidate profile SSOT, Telegram alerts, and Gmail SLA monitoring.
* **Tab 6 (Automated Test Suite Runner):** In-browser test runner executing all 1570 assertions with real-time ANSI log streaming.
* **Tab 7 (Maintenance & Storage Hub):** Visual storage breakdown (L1/L2/L3 cache, LaTeX tmp, debug dumps, task logs) with granular and bulk 1-click cleanup actions.

---

## 5. The 5-Stage Operational Pipeline

```mermaid
graph LR
    S1["1. Scanning & Scraping<br/>(28 Portals)"] --> S2["2. AI Evaluation<br/>(Scorecard 0-5)"]
    S2 --> S3["3. CV Personalization<br/>(LaTeX pdflatex)"]
    S3 --> S4["4. Easy Apply Automation<br/>(Selenium Bot)"]
    S4 --> S5["5. Status & SLA Tracking<br/>(Docker Gmail)"]
```

### Stage 1: Scanning & Scraping (28 Portal Providers)
1. **Trigger:** Execute `npm run scan` inside `career-ops/` or click **Run Scan** in the Web UI `/explore` tab.
2. **Filtering Logic:** Filters out non-matching geographic locations and unwanted technologies (`.NET`, `Java `, `iOS`, `Android`, `PHP`, `Ruby`, `COBOL`, `Salesforce Admin`) as configured in `portals.yml`.
3. **Output:** Appends matching listings to `career-ops/data/pipeline.md` with structured metadata tags (📍 Location, 🏠 Mode, 💰 Salary) and registers URLs in `scan-history.tsv`.

### Stage 2: Local AI Evaluation & Tracker Merging (Ewaluacja)
1. **Trigger:** Execute `npm run ollama:eval -- --pipeline --limit 10` or click **Evaluate** in the Web UI `/pipeline`.
2. **Scoring Rubric (0.0 to 5.0):**
   * **Score 4.5 – 5.0:** Immediate High Priority (Strong stack overlap, excellent salary, verified legitimacy).
   * **Score 3.5 – 4.4:** Viable Application (Moderate overlap, good target).
   * **Score < 3.5:** Marginal / Mismatched (Flagged gaps, low fit).
3. **Artifact Generation:**
   * Markdown Report: Saved to `career-ops/reports/{num}-{company}-{date}.md`.
   * Diagnostic Dump: Saved to `career-ops/reports/debug/{num}-{company}-{date}-dump.json`.
   * Tracker Entry: Appended to `career-ops/data/applications.md` with absolute `file:///` URLs.

### Stage 3: Agentic CV Personalization & LaTeX Compilation
1. **Trigger:** Run `node notifications/cv-generator.mjs --job <NUM> --mode none|light|full|custom` or click **Generate CV** in the Web UI `/cv`.
2. **AI & Deterministic Personalization Modes:**
   * `none`: **Archetype-Aware Deterministic Selection** (0 AI calls, 0 tokens, $<1.0\text{s}$ latency, 100% deterministic). Automatically classifies the role into canonical archetypes (`l3-support`, `gis-spatial`, `python-backend`, `fullstack-web`, `qa-automation`, `general`) and languages (**PL, EN, DE, FR**), deterministically selecting Google XYZ Professional Summaries, 8-tag ATS grids, and tailored project hierarchies. See [CV Modes Benchmark Report](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/docs/CV_MODES_BENCHMARK.md) for full empirical benchmark data.
   * `light`: Single consolidated AI call (~10–20s). Personalizes summary, 6–8 ATS competency tags, and project context.
   * `full`: 5-step sequential pipeline (`extract_keywords` $\to$ `tailor_summary` $\to$ `select_competencies` $\to$ `rank_experience` $\to$ `select_projects`).
   * `custom`: User-defined step sequence configured in `profile.yml` (preserves core work experience 100% untouched).
3. **Output:** Produces multi-variant PDFs in `career-ops/output/cv-{num}-{company}-{mode}.pdf` (strictly 2 pages, 0 overfull boxes) and populates L1/L2/L3 JSON cache entries.

### Stage 4: Easy Apply Automation & Safety Gates
1. **Trigger:** Run `python runAiBot.py` inside `Auto_job_applier_linkedIn/` or click **Run Bot** in the Web UI `/linkedin`.
2. **Execution:** Restores LinkedIn session cookies, iterates through search terms from `search.py`, fills out Easy Apply forms, and attaches the tailored PDF from `output/`.
3. **Safety Gate:** The flag `pause_before_submit = True` pauses the browser on the final review step, requiring human operator confirmation before clicking submit.

### Stage 5: System Diagnostics, Automated Testing & Maintenance Cleanup
1. **Trigger:** Open `http://localhost:3000/diagnostics` or run `npm test`.
2. **Verification & Maintenance:**
   * Probes all 28 portal providers, OpenRouter API, and local Ollama instance.
   * Executes 1570 unit/integration tests across CV matrix, E2E pipeline, and system integrations.
   * Executes 1-click cleanup to purge dead runs, stale pipeline offers, and temporary compilation artifacts.

---

## 6. Data Contracts, Storage Schemas & Caching

### 6.1 Markdown Tracker Contract (`data/applications.md`)
The master tracker in [`career-ops/data/applications.md`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/data/applications.md) records all evaluated jobs in a tabular markdown structure:

| # | Status | Company | Role | Score | Compensation | Archetype | Report | Tailored CV | Date |
| :-: | :--- | :--- | :--- | :-: | :--- | :--- | :--- | :--- | :--- | :--- |
| 046 | APPLIED | State Street | App Support L3 | 4.2/5 | 12000-16000 PLN | `l3-support` | [Report](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/reports/046-state-street-2026-08-03.md) | [CV PDF](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/output/cv-046-state-street-light.pdf) | 2026-08-03 |

* **Recruitment Lifecycle Statuses:** `EVALUATED`, `APPLIED`, `RESPONDED`, `INTERVIEW`, `OFFER`, `REJECTED`, `DISCARDED`, `SKIP`.
* **Batch Operations:** Handled via `POST /api/tracker/delete` supporting single row deletion, array deletions (`{ numbers: ["046", "047"] }`), or status-wide purge (`{ status: "DISCARDED" }`).

---

### 6.2 3-Tier JSON Cache Specification (`output/cv-cache/`)

```
output/cv-cache/
├── 046-state-street.json                   # L1: Per-job cache (invalidated if report is newer)
├── archetype/
│   ├── l3-support.json                    # L2: Archetype cache (reusable across similar roles)
│   ├── python-backend.json
│   └── fullstack-web.json
└── components/                             # L3: Component library for zero-shot assembly
    ├── experience/
    │   ├── fedex/
    │   │   ├── l3-support.json
    │   │   └── operations-sla.json
    │   └── giganci-programowania/
    │       └── code-review.json
    └── project/
        ├── busos/
        │   ├── data-engineering.json
        │   └── gis-spatial.json
        └── wikigraph-lab/
            └── graph-ai.json
```

---

## 7. Next.js Command Center & REST API Reference

### 7.1 Web UI Route Map

* [`/`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/page.tsx) — **Today Dashboard:** Live campaign summary, worker status pills, LinkedIn bot widget, Docker Gmail SLA status.
* [`/pipeline`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/pipeline/page.tsx) — **Pipeline Queue:** Visual table of pending job listings with one-click evaluation triggers and clean actions.
* [`/jobs`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/jobs/page.tsx) — **Applications Tracker:** Tabbed tracker table with multi-select checkboxes, floating batch action bar, and inline deletion.
* [`/apply`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/apply/page.tsx) — **Apply Assistant:** Guided application workflow and candidate profile tailoring.
* [`/inbox`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/inbox/page.tsx) — **Inbox SLA Triage:** Recruiter correspondence triage, Gmail SLA matching, and response countdown timers.
* [`/cv`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/cv/page.tsx) — **Resume Hub:** 4 tabs (Job Explorer with live PDF iframe, Cache L1/L2/L3 Manager, Base CV Editor, LaTeX Template Compiler).
* [`/profiles`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/profiles/page.tsx) — **Candidate Profiles:** Visual form and code editor for candidate configurations with bidirectional sync.
* [`/diagnostics`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/diagnostics/page.tsx) — **Diagnostics Suite:** 7 tabs (Portals, E2E Trace, CV Matrix, AI Providers, System, Suite Runner, Maintenance & Storage).
* [`/explorer`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/explorer/page.tsx) — **Monorepo File Explorer:** Full file tree with built-in Markdown editor and native PDF viewer.
* [`/config`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/config/page.tsx) — **Configuration Center:** Dynamic AI engine switcher (Local-First Ollama / OpenRouter), Waterfall visualizer, Custom Step Builder, and Unified Test-Agent.
* [`/jobs/[id]`](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/web/src/app/jobs/[id]/page.tsx) — **Job Detail & Terminal:** Deep dive inspection for a specific job offer with interactive streaming terminal.

---

### 7.2 Complete REST API Endpoints Reference

| Endpoint | Method | Description | Key Request Parameters |
| :--- | :--- | :--- | :--- |
| `/api/cv/variants` | `GET` | List all compiled PDF variants & cache entries for a job | `?job=046` |
| `/api/cv/variants` | `DELETE` | Delete single PDF variant, all PDFs for job, or all generated PDFs | `?file=...` \| `?jobNum=46` \| `?all=true` |
| `/api/cv/generate` | `POST` | Trigger agentic CV generation pipeline | `{ jobNum: 46, mode: "light", forceRegen: true }` |
| `/api/cv/cache` | `GET`, `POST` | Read or update L1/L2/L3 cache JSON payload | `{ jobNum: 46, payload: { ... } }` |
| `/api/cv/cache` | `DELETE` | Delete specific JSON cache file from `output/cv-cache/` | `?file=046-state-street.json&type=l1` |
| `/api/cv-pdf` | `GET` | Stream raw PDF file for live browser iframe viewing | `?file=cv-046-state-street-light.pdf` |
| `/api/tracker/delete` | `POST` | Delete single row, multiple rows, or full status tab from `applications.md` | `{ n: "046" }` \| `{ numbers: ["046","047"] }` \| `{ status: "DISCARDED" }` |
| `/api/cleanup` | `POST` | Execute 1-click maintenance cleanup operations | `{ action: "clean-runs" \| "clean-pipeline" \| "clean-latex" \| "clean-cache" \| "clean-debug" \| "all" }` |
| `/api/pipeline/clean` | `POST` | Purge un-evaluated or stale listings from `data/pipeline.md` | None |
| `/api/runs/clean` | `POST` | Terminate zombie background processes and clean task logs | None |
| `/api/diagnostics` | `GET` | Execute health checks for scrapers, AI models, and LaTeX | `?type=portals` \| `?type=ai` \| `?type=latex` |
| `/api/diagnostics/e2e-trace` | `GET` | Retrieve step-by-step JSON traces from sandbox pipeline simulator | `?id=...` |
| `/api/diagnostics/run-suite` | `POST` | Execute full automated test suite runner (1570 tests) | `{ filter: "all" \| "cv" \| "system" \| "e2e" }` |
| `/api/profiles` | `GET`, `POST`, `DELETE` | List, switch, create, or delete candidate profiles | `{ profile: "dawid_czerwinski", mode: "visual" }` |
| `/api/portals/verify` | `POST` | Execute live probing of all 28 portal providers | None |
| `/api/run/input` | `POST` | Send user stdin keystrokes directly to child process PID | `{ pid: 1234, input: "\n" }` |

---

## 8. Installation, Prerequisites & Testing Harness

### 8.1 System Requirements
* **OS:** Linux (Ubuntu 22.04+ / Debian 12 / Arch Linux recommended) or macOS.
* **Node.js:** `v18.0.0+` (managed via NVM recommended).
* **Python:** `v3.10+` with `pip` and virtual environment support (`venv`).
* **Docker:** Docker Engine 24.0+ and Docker Compose v2.
* **LaTeX:** TeX Live distribution with `pdflatex` and font packages (`texlive-latex-extra`, `texlive-fonts-recommended`, `texlive-lang-polish`).
* **Ollama (Optional for Local AI):** Ollama installed with `gemma4:latest` or `llama3.3:latest`.

---

### 8.2 Step-by-Step Setup

```bash
# 1. Clone repository
git clone https://github.com/Gzyms69/JobHunt.git
cd JobHunt

# 2. Install Node.js dependencies
cd career-ops && npm install
cd web && npm install
cd ../..

# 3. Install Python environment for LinkedIn bot
cd Auto_job_applier_linkedIn
python3 -m venv venv
source venv/bin/activate
pip install -r setup/requirements.txt
cd ..

# 4. Install Playwright browser binaries for scrapers
cd career-ops && npx playwright install chromium
cd ..

# 5. Configure environment variables
cp career-ops/.env.example career-ops/.env
# Edit career-ops/.env and add your OPENROUTER_API_KEY (if using cloud AI)

# 6. Deploy active candidate profile
./profiles/load-profile.sh dawid_czerwinski

# 7. Start full environment
./dev.sh start
./dev.sh docker-up
```

---

### 8.3 Operational Testing & Verification Harness

JobHunt includes a comprehensive suite of 1570 automated unit, integration, and documentation tests:

| Test Command | Scope / Module | Description |
| :--- | :--- | :--- |
| `npm test` | Core Suite | Executes CV matrix tests, system integration probes, and E2E pipeline tests. |
| `npm run test:all` | Full Suite (1570 Tests) | Executes the entire automated test suite with summary reporting. |
| `npm run test:cv` | CV Generation Matrix | Validates all 4 AI modes (`none`, `light`, `full`, `custom`) and LaTeX compilation. |
| `npm run test:system` | System Integrations | Tests Docker daemon, SQLite `jobs.db`, profile SSOT, and alert dispatchers. |
| `npm run test:e2e` | E2E Pipeline Simulator | Simulates complete recruitment pipeline from scraping to delivery in a sandbox. |
| `npm run test:cleanup` | Maintenance Suite | Tests 1-click cleanup actions, zombie process pruning, and cache purging. |
| `npm run test:portals` | 28 Portal Providers | Probes HTTP/API endpoints and WAF bypass across all 28 scrapers. |
| `npm run test:docs` | Documentation Integrity | Validates consistency across `DEVLOG.md`, `MAP.md`, `README.md`, `PLAN.md`. |
| `npm run polish:test` | Polish Language Engine | Validates UTF-8 encoding and typesetting for all Polish diacritics. |

---

## 9. Reliability, Diagnostics & Anti-Bot Stealth Protocols

### 9.1 Playwright Anti-Bot Stealth Evasion
Web scrapers targeting modern employment portals (Pracuj.pl, JustJoin.it) must evade Cloudflare Turnstile and Web Application Firewalls (WAF).

* **Browser Flags:** Headless Chromium is launched with `--disable-blink-features=AutomationControlled` to strip automated browser flags.
* **Navigator Spoofing:** Injected script removes `window.navigator.webdriver` and emulates authentic desktop Chrome plugin architectures.
* **JA3/JA4 Fingerprint Consistency:** In `_http.mjs`, Node.js `fetch` requests use structured `DEFAULT_API_HEADERS` rather than browser headers to prevent TLS signature mismatches on cloud endpoints like Himalayas.

---

### 9.2 AI Fallback Waterfall & Circuit Breakers
The AI subsystem in `ai-provider.mjs` enforces a zero-downtime fallback chain:
1. **Primary Cloud Model:** OpenRouter API (e.g. `google/gemini-2.5-flash` or `CAREER_OPS_MODEL`).
2. **Local Fallback on HTTP 429 / Rate Limit:** Automatically transitions to local Ollama HTTP REST API on `http://localhost:11434` (`gemma4:latest`).
3. **Static Rule-Based Fallback:** If both cloud and local AI fail, the pipeline falls back to authentic static CV data without crashing the pipeline.

---

### 9.3 Interactive & Agentic Portal Repair Engine (`repair-portal.mjs` & `api/run/route.ts`)
When an ATS carrier URL changes or becomes obsolete:
* **Interactive CLI Repair:** Run `node career-ops/repair-portal.mjs --company "Company Name"`. Probes standard ATS subdomains (Greenhouse, Lever, Ashby, Workable, SmartRecruiters, Workday) and allows live URL override with automatic backup (`portals.yml.bak`).
* **Autonomous Agentic Repair:** Triggered via Web UI (`/api/run` with kind `fix-portal`). An autonomous AI CLI agent inspects provider code, searches for active career pages, updates configurations, and verifies liveness before exiting.

---

## 10. License & Contributing

* **License:** MIT License — see [LICENSE](file:///home/gzyms/Dev%20Projects/JobHunt/career-ops/LICENSE) for details.
* **Author:** Dawid Czerwiński ([kontakt@czerwinskidawid.pl](mailto:kontakt@czerwinskidawid.pl) | [GitHub](https://github.com/Gzyms69)).


---


================================================================================
SYSTEM SPECIFICATION: WIKIGRAPH (ID: wikigraph)
Deep Link: https://czerwinskidawid.pl/#projects/wikigraph
================================================================================

# WikiGraph

WikiGraph is a language-agnostic Knowledge Graph engine designed to process Wikipedia database dumps into a unified structure. It utilizes Neo4j for topological analysis and traversal, combined with SQLite for metadata storage and high-performance full-text search.

## System Architecture

The project employs a hybrid database architecture optimized for large-scale graph operations:

### 1. Unified Backend API (FastAPI)
The backend acts as a virtual bridge, federating queries across isolated language containers. It provides a standard REST interface for pathfinding, similarity scoring, and metadata retrieval.

### 2. Neo4j (Topology Engine)
Each language operates in an isolated Neo4j instance.
- **Topology Only:** To minimize memory footprint, Neo4j stores only the Wikidata ID (QID) and the link structure.
- **Similarity Implementation:** Jaccard similarity is implemented via the Neo4j Graph Data Science (GDS) library (`gds.nodeSimilarity.filtered.stream`) for parallel execution. Resource Allocation and Adamic Adar use optimized Cypher queries with a safety valve to handle hub nodes.

### 3. SQLite (Metadata and Content)
Article titles, infoboxes, and pre-computed global metrics are stored in language-specific SQLite databases.
- **Search Implementation:** Utilizes SQLite FTS5 for sub-millisecond keyword and prefix matching.
- **Metrics Implementation:** Global metrics like PageRank and Louvain communities are pre-computed using GDS and stored in a Key-Value `node_metrics` table for O(1) retrieval at runtime.

### 4. 3D Visualization (Next.js)
A high-performance React-based frontend using `react-force-graph-3d` to visualize the knowledge nebula in real-time. The visualizer is fully language-agnostic and dynamically adapts to available backend data.

### 5. JIT Configuration System
WikiGraph supports all Wikipedia languages through a Just-In-Time (JIT) configuration system. If a language configuration is missing, the system dynamically fetches site information from the Wikimedia API to generate parsing rules. (Enable via `WIKIGRAPH_JIT_ENABLED=true`).

---

## Installation & Setup

Follow these steps to set up a production-ready environment from scratch.

### 1. Prerequisites
Ensure your system meets these requirements:
*   **OS:** Linux (Ubuntu 22.04+ recommended) or macOS.
*   **RAM:** 16GB minimum (32GB+ recommended for English/German graphs).
*   **Storage:** 20GB+ HDD space.
*   **Software:**
    *   `python3` (3.10+)
    *   `node` (v18+) & `npm`
    *   `docker` & `docker-compose`
    *   `curl`, `jq`, `unzip`

### 2. Initial Setup
Clone the repository and initialize the environment. The setup script will create a Python virtual environment (`venv`), install dependencies, and prepare the frontend.

```bash
git clone https://github.com/Gzyms69/WikiGraph.git
cd WikiGraph
chmod +x setup_environment.sh dev.sh
./setup_environment.sh
```

### 3. AI Configuration (Optional)
To enable AI summaries and "Analyze with AI" features:
1.  Obtain a **Gemini API Key** from Google AI Studio.
2.  Edit your `.env` file:
    ```bash
    nano .env
    # Set GEMINI_API_KEY=your_key_here
    ```

---

## The Data Pipeline (Ingestion)

WikiGraph processes raw Wikipedia SQL/XML dumps. You must run this pipeline to populate your local database. Replace `pl` (Polish) with your desired language code (`en`, `de`, `es`).

### Phase 1: Download & Parsing (Offline)
This step downloads raw dumps, loads metadata into SQLite, and generates CSVs for Neo4j.

```bash
# Activate python environment
source venv/bin/activate

# Run the Master Ingestor (Downloads dumps automatically)
python3 core/pipeline/ingest.py --lang pl --download
```
*Time Estimate: 10-30 mins (depending on download speed).*

Sequence:
1. `fetch_sql_dumps.py`: Downloads `page`, `pagelinks`, `redirect`, and `page_props` dumps.
2. `sqlite_loader.py`: Initializes SQLite schema and loads SQL dumps.
3. `extract_infoboxes.py`: Parses the XML `pages-articles` dump to extract structured JSON metadata.
4. `prepare_neo4j_csv.py`: Generates the node and edge CSV files for Neo4j.

### Phase 2: Graph Import (Neo4j)
Import the generated CSVs into a fresh Neo4j container.

```bash
./core/pipeline/run_neo4j_import.sh pl
```
*Time Estimate: 5-15 mins.*

### Phase 3: Analytical Metrics (The "Intelligence")
Calculate global graph metrics (PageRank, HITS, Louvain Communities) and store them in SQLite for the dashboard.

```bash
# 1. Start the Neo4j container
./dev.sh start pl

# 2. Compute metrics (PageRank, Louvain, Leiden, HITS, Clustering)
# Note: Ensure you have enough RAM.
python3 tools/analytics/compute_global_metrics.py --lang pl --algorithms pagerank,hits,louvain,leiden,triangleCount
```
*Time Estimate: 20-60 mins (Memory Intensive).*

### Phase 4: Runtime Warmup (Jaccard Similarity)
To enable the **Jaccard Similarity** feature (which uses GDS in-memory graphs), you must project the graph into memory.

```bash
python3 tools/ops/warmup_gds.py --lang pl
```
*Note: This consumes additional RAM (~2GB for Polish).*

---

## Running the Application

Once data is loaded, launch the full stack.

```bash
# Start everything (Database + Backend + Frontend)
./dev.sh start all
```

*   **Frontend:** [http://localhost:3000](http://localhost:3000) - 3D Graph Explorer.
*   **Backend API:** [http://localhost:8000/docs](http://localhost:8000/docs) - Swagger UI.

### Managing Services
The `dev.sh` controller is the command center for the entire stack. It manages Docker containers, the Python backend, the Node.js frontend, and ensures memory safety.

| Command | Target | Description |
| :--- | :--- | :--- |
| `start` | `all` | Launches Databases, Backend, and Frontend. |
| `start` | `pl`, `de`, `es` | Starts the specific Neo4j language container. |
| `start` | `backend` | Starts the FastAPI server (Port 8000). |
| `start` | `frontend` | Starts Next.js (Port 3000) with **2GB Memory Limit**. |
| `stop` | `all` | Stops all services *and* kills any running ingestion pipelines. |
| `restart` | `backend` | Fast restart for API code changes. |
| `status` | - | Shows health of Containers, API, and Frontend. |

**Example:**
```bash
./dev.sh restart backend  # Apply Python changes
./dev.sh status           # Check if everything is running
```

---

## AI Features

*   **Graph-Grounded Insight:** The `/api/v1/ai/analyze` endpoint generates node summaries grounded in mathematical metrics (e.g., "This node is central because its PageRank is X...").
*   **Resilience:** Automatically falls back to "Mock" insights if the API quota is exceeded.
*   **Caching:** Frontend caches insights per session to prevent redundant API calls.

---

## API Usage Guide

The API is served at `/api/v1`.

### 1. Discovery and Metadata

#### Discover Active Languages
Lists languages with active containers and configurations.
- **Endpoint:** `GET /graph/languages`
- **Example:** `curl "http://localhost:8000/api/v1/graph/languages"`

#### Global Nebula View
Returns a sample of high-importance nodes (PageRank) and their links.
- **Endpoint:** `GET /graph/nebula/{lang}?limit=150`
- **Example:** `curl "http://localhost:8000/api/v1/graph/nebula/pl"`

#### Search Entities
Find QIDs using title-based full-text search.
- **Endpoint:** `GET /search/{lang}?q={query}`
- **Example:** `curl "http://localhost:8000/api/v1/search/pl?q=Douglas"`

#### Resolve Entity Details
Get metadata (title, infobox) and a sample of topological neighbors.
- **Endpoint:** `GET /entity/{lang}/{qid}`
- **Example:** `curl "http://localhost:8000/api/v1/entity/pl/Q42"`

#### Cross-Language Comparison
Compare metadata for a single entity across multiple databases in parallel.
- **Endpoint:** `GET /compare/{qid}?langs={code1,code2}`
- **Example:** `curl "http://localhost:8000/api/v1/compare/Q42?langs=pl,de"`

### 2. Graph Algorithms

#### Pathfinding (Shortest Path)
Find the shortest unweighted path (BFS) between two concepts.
- **Endpoint:** `GET /graph/path/shortest/{lang}?from_qid={q1}&to_qid={q2}&max_depth=6`
- **Example:** `curl "http://localhost:8000/api/v1/graph/path/shortest/pl?from_qid=Q42&to_qid=Q64"`

#### Scored Neighbors (Similarity)
Find entities similar to a target node based on graph topology.
- **Supported Metrics:** `jaccard`, `resource_allocation`, `adamic_adar`.
- **Endpoint:** `GET /graph/neighbors/scored/{lang}/{qid}?metric={metric}&limit=20`
- **Example:** `curl "http://localhost:8000/api/v1/graph/neighbors/scored/pl/Q42?metric=jaccard"`

#### Node Metrics (Global Analytics)
Retrieve pre-computed metrics for a node.
- **Options:** Fetch all metrics or filter by a specific key using `?key=`.
- **Endpoint:** `GET /graph/metrics/{lang}/{qid}?key={key}`
- **Example (All):** `curl "http://localhost:8000/api/v1/graph/metrics/pl/Q42"`
- **Example (Single):** `curl "http://localhost:8000/api/v1/graph/metrics/pl/Q42?key=pagerank"`

#### AI Analysis
Generate a structural analysis of a node using Gemini 2.5 Flash.
- **Endpoint:** `POST /api/v1/ai/analyze/{lang}/{qid}`
- **Example:** `curl -X POST "http://localhost:8000/api/v1/ai/analyze/pl/Q42"`

---

## Operational Guidelines

### 1. Memory Management
The system requires careful allocation of physical and virtual memory.
- **Heap Allocation:** Individual containers are limited to 4GB.
- **GDS Projections:** Graph projections reside in off-heap memory. 
- **Cleanup Requirement:** GDS projections must be dropped after use:
  `CALL gds.graph.drop('similarity-graph')`

### 2. Development Control
Manage the stack using the `dev.sh` controller:
- `./dev.sh start <lang>`: Initialize a specific database.
- `./dev.sh stop all`: Terminate services and reclaim memory.
- `./dev.sh status`: Review active services.

---

## Graph Theory & Metrics Guide

WikiGraph computes several classical graph metrics to help understand the structure of knowledge. Here is what they measure and why they matter.

### 1. Importance (Centrality)
Who are the "VIPs" of the network?

*   **PageRank:**
    *   **Concept:** A node is important if other important nodes link to it. It measures long-term, global influence.
    *   **Analogy:** A voting system where a vote from the President counts more than a vote from a random citizen.
    *   **Use Case:** Finding the most influential articles in Wikipedia (e.g., "United States", "Biology").

*   **HITS Authority:**
    *   **Concept:** Identifies high-quality information sources ("Authorities") and the lists that point to them ("Hubs").
    *   **Analogy:** In a library, the "Authorities" are the best books on a topic, and the "Hubs" are the best bibliographies that list those books.
    *   **Use Case:** distinguishing between a "List of Physicists" (Hub) and "Albert Einstein" (Authority).

### 2. Similarity (Relatedness)
How related are two concepts based on their connections?

*   **Jaccard Similarity:**
    *   **Concept:** Measures the overlap between two nodes' neighborhoods relative to their total size.
    *   **Formula:** `Intersection / Union`.
    *   **Analogy:** If you and I have 10 friends, and 8 of them are the same people, we are socially similar.
    *   **Use Case:** Finding broadly related broad topics (e.g., "Physics" and "Chemistry").

*   **Adamic Adar & Resource Allocation:**
    *   **Concept:** Similar to Jaccard, but gives more weight to **rare** shared neighbors. Sharing a common friend who knows *everyone* (like "United States") is less meaningful than sharing a friend who only knows a few people (like a specific "1995 Jazz Album").
    *   **Analogy:** Two people who both like "Breathing" aren't special. Two people who both like "Underwater Basket Weaving" definitely have a connection.
    *   **Use Case:** Finding specific, niche connections between entities.

### 3. Community Detection
*   **Louvain / Leiden:**
    *   **Concept:** Groups nodes that are more densely connected to each other than to the rest of the network.
    *   **Analogy:** Identifying social circles (family, work colleagues, bowling club) within a person's life.
    *   **Use Case:** Auto-categorizing articles into topics like " WWII Battles," "French Cities," or "Marvel Movies" without reading the text.

---

## Troubleshooting

*   **Neo4j Out of Memory (OOM):**
    *   If the import fails or Neo4j crashes, check your Docker memory settings.
    *   Edit `config/infrastructure.yaml` to adjust heap sizes (`neo4j_heap: 4G`).
*   **Frontend "Build Loop":**
    *   Ensure the root `package.json` is renamed to `.root_backup` (handled automatically) to prevent Next.js from scanning the entire drive.
    *   `dev.sh` enforces a 2GB memory limit on the frontend process.

---

## Project Roadmap

### Phase 7: The Visualizer (Completed)
*   **Language-Agnostic Frontend:** Modernized Next.js frontend with high-performance 3D graph explorer.
*   **Unified Bridge:** Visualization engine now fully powered by verified multi-language Graph Engine (FastAPI).
*   **Dynamic Discovery:** UI automatically adapts to active language containers.

### Phase 8: Hybrid AI Engine (Completed)
*   **Provider Pattern:** Modular AI service capable of switching between Cloud and Local backends.
*   **Generative Insights:** Real-time relationship summarization using the Gemini 2.5 Flash API.
*   **Analytic Grounding:** AI narratives are based on rigorous metrics (PageRank, Adamic-Adar) rather than hallucinated context.

### Future: Vector Search (Phase 9)
*   **ChromaDB Integration:** Implement a vector database to store semantic embeddings of Wikipedia articles.
*   **Semantic Search:** Extend the search API to support concept-based queries.

## License
GPLv3


---


================================================================================
SYSTEM SPECIFICATION: KATALOG (ID: katalog)
Deep Link: https://czerwinskidawid.pl/#projects/katalog
================================================================================

# Dawid Czerwiński 2026 | Professional Template Marketplace

**Mission:** To transform a collection of legacy website templates into a professional, high-performance "Template Marketplace" using Next.js 16. This project focuses on porting legacy designs while upgrading their technical performance, interactivity, and sales conversion potential.

## Project Ecosystem

This application is part of a unified professional identity hosted at `czerwinskidawid.pl`:
- **Main Catalog (/katalog):** This project. A commercial exhibition of industry-specific templates.

## Tech Stack & Architecture

Ten projekt to wysoce zoptymalizowane monorepo zbudowane na nowoczesnym stosie (zoptymalizowane pod kątem wydajności FCP):

*   **Core:** Next.js 16.1.6 (App Router), React 19.2.3, TypeScript, Turborepo, pnpm 9.
*   **Styling & UI:** Tailwind CSS v4, Framer Motion, `@katalog/ui` (współdzielony design system oparty m.in. o Shadcn, MagicUI), Lenis (Smooth Scroll).
*   **Headless Ecosystem (dla projektów flagowych):** 
    *   Sanity.io (Session-Scoped CMS z ochroną danych)
    *   Shopify Storefront API (backend e-commerce)
    *   n8n (własne webhooki, Fakturownia.pl, InPost Geowidget)
*   **State Management & Persistence:** Zustand (z logiką `persist`), IndexedDB (szybki zapis plików binarnych offline pod testy użytkowników), SWR.

## Dynamic Sales Architecture (DSA) & Live Previews

System implementuje autorski mechanizm "Magic Links", pozwalający na dynamiczną podmianę treści w locie za pomocą parametrów URL, bez jakiejkolwiek ingerencji w kod źródłowy na żądanie handlowca.

| Parametr | Działanie w szablonie |
| :--- | :--- |
| `name` | **Nazwa Firmy:** Podmienia główne nagłówki (H1), logotypy tekstowe, stopki i tagi OpenGraph. |
| `city` | **Miasto:** Aktualizuje teksty geolokalizacyjne ("Liderzy w mieście [city]") i mapy Google. |
| `address` | **Adres:** Precyzuje dokładną lokalizację w sekcjach kontaktowych i koordynatach. |
| `phone` | **Numer:** Podmienia telefony we wszystkich paskach akcji i przyciskach szybkiego wybierania. |

### Gotowe Linki Demonstracyjne (Live Previews)

Obecnie w systemie funkcjonuje 7 zaawansowanych, interaktywnych projektów:

**1. Miodowy Zakątek (Pasieka Premium - Flagship PoC)**
Elitarny sklep headless dla pasieki z pełną integracją Shopify, Sanity, n8n i własną piaskownicą dla każdego klienta.
[Live Preview (Miodowy Zakątek)](https://katalog.czerwinskidawid.pl/templates/miodowy-zakatek?name=Pasieka%20Testowa&city=Krak%C3%B3w)

**2. Sklep Premium (E-Commerce PoC)**
Gotowy, kompletny sklep internetowy z własnym katalogiem, stronami poszczególnych produktów oraz autoryzacją JWT.
[Live Preview (Sklep Premium)](https://katalog.czerwinskidawid.pl/templates/sklep-premium/store?name=Super%20Sklep)

**3. Warsztat Samochodowy (Warsztat Pro)**
Szablon dla branży mechanicznej wyposażony w skomplikowane karty usług i wyliczanie kwot.
[Live Preview (Warsztat Pro)](https://katalog.czerwinskidawid.pl/templates/warsztat-pro?name=Auto-Serwis%20Wroc%C5%82aw&city=Wroc%C5%82aw&phone=%2B48%20600%20111%20222)

**4. Doradztwo Strategiczne (Helios Advise)**
Design klasy korporacyjnej dla doradców B2B, prawników, kancelarii. Skupia się na powadze i osiach czasu.
[Live Preview (Helios Advise)](https://katalog.czerwinskidawid.pl/templates/helios-advise?name=Kancelaria%20Lex&city=Pozna%C5%84)

**5. Agencja Kreatywna**
Nowoczesne portfolio agencji z modułem case studies i formularzami kontaktowymi.
[Live Preview (Agencja Kreatywna)](https://katalog.czerwinskidawid.pl/templates/agencja-kreatywna?name=NeonMedia%20Group&city=Krak%C3%B3w)

**6. Nowoczesna Restauracja (Bistro Modern)**
Szablon dla gastronomii z wydzielonymi kategoriami menu w locie i galerią potraw.
[Live Preview (Bistro Modern)](https://katalog.czerwinskidawid.pl/templates/bistro-modern?name=Bistro%20Pod%20R%C3%B3%C5%BC%C4%85&city=Warszawa)

**7. Landing Page Aplikacji SaaS (FitPlaner)**
Kompaktowy, wysoce responsywny landing pod kampanie pobrań aplikacji na iOS i Androida.
[Live Preview (FitPlaner)](https://katalog.czerwinskidawid.pl/templates/landing-aplikacji?name=CloudSync%20Pro&city=Gda%C5%84sk)

---

## Performance & Architecture (Best Practices)

Projekt implementuje rygorystyczne wzorce optymalizacyjne, które należy utrzymać w trakcie prac deweloperskich:

1.  **Interaction-gated WebGL:** Ciężkie efekty wizualne (np. `BackgroundEffects.tsx` bazujące na Three.js) inicjalizują się **tylko** po interakcji użytkownika (scroll/hover/mousemove). Zapobiega to długim blokadom głównego wątku (Main Thread) podczas FCP. Ekran zawsze najpierw wyświetla lekki natychmiastowy fallback CSS.
2.  **Lazy Loading (Wrappers):** Komponenty niewidoczne w pierwszej sekcji (above-the-fold) viewportu ładujemy w React 19 za pomocą asynchronicznych wrapperów (np. `SectionArchitectureLazy`, `TemplateGalleryLazy`) opartych na dynamicznych importach z glassmorphic skeletonem. Minimalizuje to początkowy bundle size i blokuje wczytywanie skryptów do momentu zescrollowania w ich okolicę.
3.  **Server Actions Gatekeeper:** Wszelkie mutacje danych (wysyłka formularzy, zapisy do CMS) realizowane są przez "bezpieczną bramkę" Next.js Server Actions. Wrażliwe instancje klientów (np. Stripe, Sanity API) chronione są przed wyciekiem na klienta za pomocą znacznika modułu `server-only`, a dane zawsze rygorystycznie walidowane na wejściu parserem schematów Zod.
4.  **Cookie-based CLS Prevention:** Stan widoczności dla powiadomień i bannerów informacyjnych jest resolwowany w locie server-side z ciasteczek użytkownika. Zapobiega to wstrząsom układu strony (Cumulative Layout Shift), charakterystycznym dla ładowania tego stanu klasycznie po stronie klienta (useEffect).
5.  **Offline Piaskownica (Sandbox Engine):** Sklep demonstracyjny bazuje na wirtualnej maszynie klienta - koszyk i modyfikacje produktów operują na połączeniu stanu `Zustand` (persist) oraz bazy `IndexedDB` za pomocą hooka agregującego (zapisującego ciężkie bloby obrazów na maszynie klienta bez uderzania w prawdziwe serwery CDN).

---

## Quick Start (Środowisko Lokalne)

Z uwagi na rozbudowaną architekturę bazującą na wielu headless APIs, projekt ma wysokie wymagania co do środowiska przed uruchomieniem kompilacji.

### 1. Zmienne Środowiskowe (.env)

Stwórz plik `.env.local` na poziomie głównym projektu. Monorepo (a przede wszystkim Miodowy Zakątek i globalne formularze) nie zbuduje się poprawnie, dopóki aplikacja nie otrzyma niezbędnych kluczy dostępowych. Najważniejsze, wymagane absolutnie to:

*   `NEXT_PUBLIC_SANITY_PROJECT_ID`, `NEXT_PUBLIC_SANITY_DATASET` i `SANITY_API_TOKEN` (Dostęp write do CMS)
*   `NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN` i `NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN` (Klucze dostępowe e-commerce)
*   `STRIPE_SECRET_KEY` i `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` (Płatności)
*   `RESEND_API_KEY` (Dostawca dla transakcyjnych i powitalnych e-maili)
*   `NEXT_PUBLIC_TURNSTILE_SITE_KEY` i `TURNSTILE_SECRET_KEY` (Ochrona CAPTCHA w formularzach przed botami)
*   `JWT_SECRET_KEY` (Odpowiada za szyfrowanie uwierzytelnień dla panelu Sklepu Premium)

*(Pełna konfiguracja jest objęta wewnętrznym sekretem projektu)*

### 2. Budowanie i Uruchomienie

```bash
# 1. Pobierz wszystkie zależności w obszarze workspace monorepo
pnpm install

# 2. Uruchom serwer developerski Next.js (Domyślnie zasilany przez Turbopack)
pnpm dev
```

*(Uwaga: PrismaClient została uznana za martwy kod legacy. Nie wymaga generowania `prisma generate` do codziennej pracy nad platformą UI).*

---

### Deployment na Vercel

Dla środowisk produkcyjnych (Platforma Vercel) należy pamiętać o rygorystycznym ustawieniu konfiguracji:

*   **Root Directory:** Ponieważ to monorepo, "Root Directory" w projekcie na Vercelu bezwzględnie musi wskazywać na folder `apps/webstore`. Inaczej mechanizm nie skompresuje frameworka.
*   **Remote Patterns (Images):** Usługi proxy Image Next.js wyrzucą wyjątek bezpieczeństwa w Runtime, jeżeli ich odpowiednio nie dopuścisz do renderowania. Zadbaj w `next.config.ts`, by domeny `cdn.sanity.io` oraz `cdn.shopify.com` figurowały w tabeli `images.remotePatterns`.
*   **Safety Check:** Next.js jest bezlitosny pod kątem Non-Null Assertions w locie. Upewnij się, że przeniosłeś **wszystkie** zmienne środowiskowe z `.env.local` do panelu "Environment Variables" projektu w Vercelu. Brak klucza nałożonego obostrzeniem `!` (np. w plikach dostępowych Shopify API) zcrashuje na twardo całe budowanie gałęzi.

---

## License

Copyright (c) 2026 Dawid Czerwiński. All rights reserved.

Commercial use, reproduction, or distribution of this system, its source code, or its specific architectural patterns without explicit written permission from the author is strictly prohibited. This includes, but is not limited to, using this marketplace system to sell website templates or as a base for a competing template service.


---


================================================================================
SYSTEM SPECIFICATION: DAWIDCZERWINSKI.PL (ID: portfolio)
Deep Link: https://czerwinskidawid.pl/#projects/portfolio
================================================================================

# dawidczerwinski.pl — Horyzontalny Hub Architektury Systemowej & CyberPlexus 2.5D

[![TypeScript](https://img.shields.io/badge/TypeScript-5.x_Strict-3178c6.svg?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18-61dafb.svg?style=flat-square&logo=react&logoColor=black)](https://reactjs.org/)
[![Vite](https://img.shields.io/badge/Vite-7-646cff.svg?style=flat-square&logo=vite&logoColor=white)](https://vitejs.dev/)
[![D3-Force](https://img.shields.io/badge/D3--Force-Simulation-f9a03c.svg?style=flat-square&logo=d3.js&logoColor=white)](https://d3js.org/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-v3.4-38bdf8.svg?style=flat-square&logo=tailwind-css&logoColor=white)](https://tailwindcss.com/)
[![GSAP](https://img.shields.io/badge/GSAP-3.x_Timelines-88ce02.svg?style=flat-square&logo=greensock&logoColor=white)](https://greensock.com/)
[![Lighthouse Desktop](https://img.shields.io/badge/Lighthouse_Desktop-100%2F100-00c853.svg?style=flat-square&logo=lighthouse&logoColor=white)](https://pagespeed.web.dev/)
[![Core Web Vitals](https://img.shields.io/badge/Core_Web_Vitals-Passing_CLS_0.000-00c853.svg?style=flat-square&logo=googlechrome&logoColor=white)](https://pagespeed.web.dev/)
[![Vitest](https://img.shields.io/badge/Vitest-49%2F49_Passing-729b1b.svg?style=flat-square&logo=vitest&logoColor=white)](https://vitest.dev/)
[![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-Daily_Sync_Cron-2088ff.svg?style=flat-square&logo=github-actions&logoColor=white)](https://github.com/Gzyms69/czerwinskidawid.pl-landing/actions)

> **Live Production URL:** [https://czerwinskidawid.pl](https://czerwinskidawid.pl)  
> **Source Repository:** [https://github.com/Gzyms69/czerwinskidawid.pl-landing](https://github.com/Gzyms69/czerwinskidawid.pl-landing)

---

## 1. Manifest Architektoniczny: Nieliniowe Portfolio Inżynierskie

Tradycyjne witryny portfolio opierają się na statycznych, pionowych siatkach kart i powtarzalnych listach bibliotek. **`dawidczerwinski.pl`** zostało zaprojektowane i zbudowane od podstaw jako **horyzontalny, 4-poziomowy hub architektoniczny (100vw / 100dvh scroll-snap)**. Łączy on przestrzenny graf powiązań technologicznych **`CyberPlexus 2.5D`** na pojedynczym elemencie `<canvas>`, pełnoekranowy czytnik dokumentacji technicznej z diagramami SVG Mermaid i wzorami KaTeX, z rygorystyczną inżynierią wydajności (Lighthouse Desktop 100/100, CLS = 0.000, rygor typograficzny Swiss Design).

```mermaid
flowchart TD
    subgraph Viewport_Core["Horyzontalny Viewport (100vw / 100dvh Scroll-Snap)"]
        H1["01 Hero Cockpit (#hero)"]
        H2["02 Cockpit Showcase (#showcase)"]
        H3["03 CyberPlexus 2.5D (#graph)"]
        H4["04 Timeline (#experience)"]
    end

    subgraph Navigation_Engine["Inteligentny Silnik Nawigacji"]
        ScrollHook["useSmartHorizontalScroll (Macierz Intencji Kółka)"]
        HashRouter["hash-router.ts (Dwukierunkowy PopState)"]
        DOMGuard["findScrollableAncestor (Ochrona Kontenerów DOM)"]
    end

    subgraph Canvas_Engine["Silnik CyberPlexus 2.5D Canvas"]
        D3Physics["D3-Force (4-Kwadrantowy Orbital Clustering)"]
        Simplex3D["3D Simplex Noise (Perturbacja Przestrzenna)"]
        AmbientParticles["Cząsteczki Ambientu (Flares, Streaks, Crosshairs)"]
        DirectDOM["Direct DOM Pipeline (translate3d 60/120 FPS)"]
        BatterySaver["RAF Battery Saver (Pauza poza widokiem grafu)"]
    end

    subgraph Showcase_Module["Moduł Cockpit Showcase"]
        TwoStageNav["2-Stopniowa Nawigacja (Kategorie + Pigułki)"]
        MotionTabs["Sprężynowa Animacja Tabs (motion layoutId)"]
        Simulators["9 Dedykowanych Symulatorów Wizualnych"]
    end

    subgraph Doc_Engine["Pełnoekranowy Czytnik Dokumentacji"]
        MermaidViewer["SVG Mermaid z Pan, Zoom i Pełnym Ekranem"]
        KaTeXMath["Renderowanie Wzorów Matematycznych KaTeX"]
        Callouts["Parsowanie GitHub Callouts ([!NOTE], [!TIP], etc.)"]
        SearchTOC["Wyszukiwarka In-Doc i Spis Treści"]
    end

    Viewport_Core --> Navigation_Engine
    H3 --> Canvas_Engine
    H2 --> Showcase_Module
    H2 & H3 --> Doc_Engine
```

---

## 2. Inżynieria Interfejsu & Swiss Design System

### A. Płynna Typografia & Reguła Bringhursta
Zamiast skokowych breakpointów CSS, typografia wykorzystuje płynne skale oparte na matematycznej funkcji `clamp()`:
- **`--text-display-fluid`:** `clamp(2.1rem, 1.6rem + 2.5vw, 3.75rem)` — nagłówki hero.
- **`--text-headline-fluid`:** `clamp(1.5rem, 1.2rem + 1.4vw, 2.25rem)` — tytuły sekcji i kokpitu.
- **`--text-body-fluid`:** `clamp(0.875rem, 0.82rem + 0.25vw, 1rem)` — czytelny tekst ciągły.
- **Reguła Bringhursta (`.measure-bringhurst`):** Twarde ograniczenie długości wiersza do optymalnego przedziału **55–68 znaków** (`max-width: 68ch`), zapobiegające zmęczeniu wzroku podczas czytania zaawansowanych opisów architektonicznych.

### B. Dotykowy Glassmorphism & Fizyka Światła (1px Chamfer)
Klasyczne, płaskie karty zastąpiono wielowarstwową fizyką światła:
- **`.card-tactile`:** Tło `rgba(9, 9, 11, 0.82)` z rozmyciem `backdrop-filter: blur(20px)` oraz **wewnętrznym fazowaniem krawędzi** `box-shadow: inset 0 1px 0 0 rgba(255, 255, 255, 0.12)`.
- **Proceduralny Szum SVG Grain:** Nakładka `feTurbulence` (częstotliwość `0.80`, 3 oktawy) eliminująca efekt cyfrowej sterylności i nadająca interfejsowi dotykową, matową fakturę.
- **Eliminacja AI Clichés:** Całkowite odrzucenie sztucznych kontrolek okna macOS, pustych gradientów i ozdobników — każdy element prezentuje autentyczną rolę inżynierską, twarde liczby i metryki biznesowe.

---

## 3. Głęboka Dekonstrukcja Modułów i Silników

### A. Minimalistyczny Hero Cockpit (`CinematicHero.tsx`)
Strefa pierwszego kontaktu skupiona na maksymalnej konwersji i przejrzystości:
- **Status Dostępności:** Wskaźnik dostępności projektowej z bezpośrednią rolą inżynierską (*Software & Systems Engineer*).
- **Trio Akcji Głównych:**
  - `[Eksploruj Projekty]` — płynne przesunięcie do sekcji Showcase.
  - `[Pobierz CV (PDF)]` — dedykowany plik PDF przygotowany pod kątem systemów ATS (Harvard Tech standard).
  - `[Stos Technologiczny]` — modal z zestawieniem technologii pogrupowanych w 4 domeny.
- **Przycisk E-mail:** Kopiowanie adresu `kontakt@czerwinskidawid.pl` do schowka jednym kliknięciem z informacją zwrotną w czasie rzeczywistym.

---

### B. Inteligentny Silnik Nawigacji Horyzontalnej (`useSmartHorizontalScroll.ts`)
Nawigacja pomiędzy 4 głównymi poziomami horyzontalnymi (`#hero`, `#showcase`, `#graph`, `#experience`) realizowana jest za pomocą dedykowanego algorytmu ewaluacji intencji kółka myszy (`evaluateWheelIntent`):
- **Macierz Intencji Kółka:**
  - `ignore-modal`: Blokada nawigacji horyzontalnej, gdy aktywny jest czytnik dokumentacji lub modal profilu.
  - `cooldown`: Ochrona przed wielokrotnym przewijaniem przy szybkim ruchu kółka (blokada na 600ms).
  - `canvas-zoom`: Przekazanie zdarzenia `wheel` do silnika 2.5D w celu zbliżania/oddalania grafu bez przełączania sekcji.
  - `inner-scroll`: Detekcja wewnętrznego przewijania elementów tekstowych.
  - `accumulate` & `navigate`: Akumulacja pionowej delty (`threshold = 45px`) — dopiero po jej przekroczeniu inicjowane jest płynne przejście do kolejnej lub poprzedniej karty.
- **Wspinaczka po Drzewie DOM (`findScrollableAncestor`):**
  - Funkcja rekurencyjnie sprawdza style CSS (`overflowY: auto / scroll`, `scrollHeight > clientHeight`) elementów nadrzędnych. Chroni to zagnieżdżone bloki kodu, listy i drawery przed blokowaniem scrolla strony.

---

### C. Żywy Silnik CyberPlexus 2.5D & Battery Saver (`CyberPlexusGraph.tsx` & `PlexusHudCard.tsx`)
Interaktywny graf relacji renderowany na pojedynczym elemencie `<canvas>` przy 60/120 FPS:
- **Symulacja D3-Force & Simplex Noise:**
  - Siła odpychania `forceManyBody().strength(-160)` zapobiegająca zlewaniu się węzłów.
  - Dynamiczny promień kolizji `forceCollide()` uwzględniający rzeczywiste wymiary etykiet tekstowych.
  - 4-kwadrantowy orbital clustering grupujący węzły według domen (`data-graph`, `automation`, `frontend`, `systems`).
  - Ciągła perturbacja 3D Simplex Noise (`createNoise3D`) nadająca konstelacji organiczny ruch w osi Z.
- **Wielowarstwowy System Cząsteczek:**
  - Ambientowe cząsteczki tła o 3 typach (`flare`, `streak`, `crosshair`) z dynamicznym pulsowaniem przezroczystości, prędkością 3D i rotacją.
  - Cząsteczki kinetyczne przemieszczające się wzdłuż aktywnych krawędzi grafu (`PulseParticle`).
- **Direct DOM Pipeline (60 FPS Tooltip Tracking):**
  - Współrzędne ekranowe węzła są bezpośrednio rzutowane do `tooltipRef.current.style.transform = translate3d(...)`, całkowicie omijając cykl renderowania Reacta.
- **Optymalizacja Baterii (RAF Battery Saver):**
  - Monitorowanie stanu widoku (`activeView !== "graph"`) oraz zdarzenia `document.hidden`.
  - Pętla `requestAnimationFrame` oraz kalkulacje D3 są natychmiast wstrzymywane, gdy użytkownik nie znajduje się na karcie grafu, redukując zużycie CPU do 0%.
- **HUD Kontrolny (`PlexusHudCard.tsx`):**
  - Wbudowane kontrolki zbliżenia/oddalenia, resetu kamery, wyboru kategorii oraz podglądu powiązań.

---

### D. Cockpit Flagowych Projektów (`ProjectsShowcase.tsx`)
Moduł prezentacji systemów inżynierskich z 2-stopniową architekturą nawigacji:
- **2-Stopniowa Nawigacja:**
  - **Krok 1 (Filtr Kategorii):** `Wszystko (9)`, `Dane i Grafy (2)`, `Automatyzacja (2)`, `Frontend (3)`, `Systemy & AI (2)`.
  - **Krok 2 (Pigułki Projektów):** Wybór projektów ze sprężynową animacją wyboru (`motion.div layoutId="activeShowcaseTab"`).
- **9 Dedykowanych Symulatorów Wizualnych:**
  - **WikiGraph Lab:** Architektura Split-Storage (Neo4j GDS + SQLite FTS5) z zapytaniami $<2.4$ms i wizualizacją chmury punktów 3D.
  - **BusOS:** 16-etapowy potok ETL danych przestrzennych (GTFS + OSM), model grawitacyjny Huffa ($K=0.005$) i wektoryzacja C-GEOS (-60% RAM).
  - **JobHunt:** Rozproszony potok scrapingu 28 portali z omijaniem WAF (JA3/JA4) i deterministyczną kompilacją LaTeX w $<0.85$s (0 tokenów AI).
  - **LeadFinder:** Asynchroniczny worker FastAPI 202 + UUID, ewazja NASK Jitter (1.5-3.5s) i generator linków B2B.
  - **Katalog:** Monorepo Turborepo z Next.js 16 App Router, bezdyskowy potok WebM FFmpeg i zerowy CLS (0.000).
  - **Portfolio Hub:** Graf 2.5D na Canvasie z fizyką D3-Force, Simplex Noise i wynikiem 100/100 Lighthouse.
  - **ROMHub N64:** Port rdzenia C++ Mupen64Plus do WebAssembly, WebGL 60 FPS, AudioWorklet (100% Client-Side).
  - **DeepSeek Organizer:** Userscript DOM Injection, 100% prywatności w pamięci LocalStorage.
  - **Agent Setup Bundle:** Deterministyczny harness agentowy (PRAR, Zero-Speculation), 30+ skilli i 11 serwerów MCP.

---

### E. Pełnoekranowy Czytnik Dokumentacji (`ProjectDocViewerModal.tsx`)
- **Silnik SVG Mermaid z Pan & Zoom:** Renderowanie diagramów architektury na żywo z obsługą powiększania, przesuwania i trybu pełnoekranowego.
- **Formuły Matematyczne KaTeX:** Integracja `remark-math` oraz `rehype-katex` do renderowania wzorów naukowych i inżynierskich.
- **Formatowanie Calloutów GitHub:** Dedykowana stylistyka dla bloków `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`.
- **Wyszukiwarka Wewnątrzdokumentowa:** Błyskawiczne przeszukiwanie i filtrowanie sekcji specyfikacji na żywo.

---

### F. Akcelerowany Sprzętowo Marquee GSAP (`TechStackFooterMarquee.tsx`)
- Płynny ruch nieskończony z deceleracją po najechaniu kursorem.
- Natychmiastowe przeciąganie 1:1 z obsługą dotyku i myszy.
- Dedykowane, wektorowe ikony technologiczne (`TechBrandIcon.tsx`).

---

### G. Routing Hash & PopState (`hash-router.ts`)
- **Struktura Adresów URL:** `#hero`, `#showcase`, `#showcase/{projectId}`, `#graph`, `#graph/{projectId}`, `#experience`.
- **Obsługa Historii:** Pełna integracja ze zdarzeniem `window.onpopstate` — przyciski Wstecz/Dalej w przeglądarce precyzyjnie przywracają stan kart, aktywne filtry oraz otwarte czytniki dokumentacji.

---

## 4. Zautomatyzowany Potok CI/CD & Hybrydowa Synchronizacja

Landing page utrzymuje pełną spójność dokumentacji i metadanych z zewnętrznymi repozytoriami poprzez architekturę potoku CI/CD:

```mermaid
flowchart LR
    subgraph Cron_Job["GitHub Actions (Codziennie 03:00 UTC)"]
        Trigger["Cron / workflow_dispatch"]
        Checkout["actions/checkout@v4"]
        NodeSetup["actions/setup-node@v4 (Node 22)"]
    end

    subgraph Scripts_Execution["Wykonanie Skryptów"]
        S1["node scripts/sync-readmes.mjs"]
        S2["node scripts/fetch-github-stats.mjs"]
    end

    subgraph Outputs["Modyfikowane Pliki"]
        F1["public/readmes/*.md"]
        F2["public/llms-full.txt"]
        F3["client/data/generated-github-stats.json"]
    end

    subgraph Git_Commit["Weryfikacja Diff & Commit"]
        DiffCheck{"Czy wykryto zmiany?"}
        Commit["git commit 'chore(sync): automated daily update...'"]
        Push["git push origin main"]
        Deploy["Vercel Auto-Deployment"]
        CleanWorktree["Clean Worktree (Brak zmian)"]
    end

    Trigger --> Checkout --> NodeSetup
    NodeSetup --> S1 & S2
    S1 --> F1 & F2
    S2 --> F3
    F1 & F2 & F3 --> DiffCheck
    DiffCheck -- "Tak" --> Commit --> Push --> Deploy
    DiffCheck -- "Nie" --> CleanWorktree
```

### Co dokładnie wykonuje potok GitHub Actions (`.github/workflows/daily-readme-sync.yml`)?

1. **`node scripts/sync-readmes.mjs`:**
   - Sprawdza zdefiniowane repozytoria projektów.
   - W środowisku lokalnym pobiera pliki `README.md` bezpośrednio ze ścieżek dyskowych maszyny deweloperskiej.
   - W środowisku CI (GitHub Actions) łączy się z GitHub REST API (`https://api.github.com/repos/Gzyms69/{repo}/readme`) z nagłówkiem `Accept: application/vnd.github.raw+json` i autoryzacją `Bearer ${GITHUB_TOKEN}`.
   - Zapisuje pobrane pliki specyfikacji do katalogu `public/readmes/{id}.md`.
   - Łączy wszystkie specyfikacje w jeden spójny plik kompendium dla modeli AI: **`public/llms-full.txt`** (ponad 160 KB wiedzy).

2. **`node scripts/fetch-github-stats.mjs`:**
   - Odpytuje GitHub API o aktualne statystyki każdego repozytorium: liczbę gwiazdek (`stargazers_count`), liczbę forków (`forks_count`), datę ostatniego pusha (`pushed_at`) oraz całkowitą liczbę commitów (poprzez nagłówek Link pagination `per_page=1`).
   - Zapisuje zagregowany stan do pliku **`client/data/generated-github-stats.json`**, zasilającego liczniki w interfejsie witryny.

3. **Weryfikacja i Commit:**
   - Wykonuje `git add public/readmes/ public/llms-full.txt client/data/generated-github-stats.json`.
   - Jeśli pojawiły się jakiekolwiek zmiany, wykonuje commit z podpisem `github-actions[bot]` i wypycha zmiany do gałęzi `main`.
   - Wypchnięcie zmian do `main` automatycznie inicjuje deployment produkcyjny na platformie Vercel.

---

## 5. Topologia 9 Flagowych Projektów Inżynierskich

| ID                   | Nazwa Projektu         | Kategoria    | Główny Stos Technologiczny                      | Kluczowe Wyzwania Inżynierskie & Architektura                                                                                                 |
| -------------------- | ---------------------- | ------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `busos`              | **BusOS**              | `data-graph` | Python, GeoPandas, Uber H3, SQLite WAL          | 16-etapowy potok ETL, 85+ źródeł GTFS, wektoryzacja C-GEOS, model Huffa ($K=0.005$), entropia Shannona, eliminacja Cartesian OOM (-60% RAM). |
| `jobhunt`            | **JobHunt**            | `automation` | Next.js 14, Playwright, pdflatex, Docker        | Scraping 28 portali, omijanie WAF (JA3/JA4), 3-poziomowy cache, kompilacja LaTeX <0.85s (0 tokenów AI), monitor SLA Gmail w Docker Compose.  |
| `wikigraph`          | **WikiGraph Lab**      | `data-graph` | Neo4j GDS, FastAPI, Three.js, SQLite FTS5       | Architektura Split-Storage (Neo4j topologia + SQLite BM25 O(1)), 3D Nebula Golden Angle ($\theta = \pi(3-\sqrt{5})$), Dossier AI Prompting.   |
| `katalog`            | **Katalog**            | `frontend`   | Turborepo, Next.js 16, Shopify, Sanity, Zustand | Monorepo Turborepo, Next.js 16 App Router, generator wideo WebM Puppeteer->FFmpeg, Cookie-based Hydration Skeletons (CLS = 0.000).          |
| `portfolio`          | **dawidczerwinski.pl** | `frontend`   | React 18, Vite 7, D3-Force, Simplex Noise, GSAP | 4-kartowy layout horyzontalny, żywy graf 2.5D, 60 FPS Direct DOM tooltip tracking, PopState Hash Router, zero CLS (100/100 Lighthouse).       |
| `leadfinder`         | **LeadFinder**         | `automation` | FastAPI, Playwright Go, Docker, AsyncIO         | Asynchroniczny worker 202 Accepted z UUID, ewazja botów NASK Jitter (1.5-3.5s), Event Loop safety (asyncio.to_thread), generowanie linków B2B.|
| `romhub`             | **ROMHub N64**         | `systems`    | WebAssembly (WASM), C++, WebGL, AudioWorklet    | 100% Client-Side emulator N64 w C++/WASM, buforowanie WebGL 60 FPS, synchronizacja dźwięku AudioWorklet, stany gry w IndexedDB.             |
| `deepseek-organizer` | **DeepSeek Organizer** | `frontend`   | TypeScript, Tampermonkey, DOM Injection         | Rozszerzenie Userscript wstrzykujące drzewo folderów i kolorowe tagi w DOM aplikacji DeepSeek AI, 100% prywatności w LocalStorage.           |
| `agent-setup-bundle` | **Agent Setup Bundle** | `systems`    | Bash, TypeScript, Docker, MCP, Markdown         | Deterministyczny framework orkiestracji AI (PRAR, Zero-Speculation), 30+ modułowych skilli i 11 serwerów MCP dla Gemini, Claude i Cursor.     |

---

## 6. Zweryfikowane Metryki Wydajności & Dostępności (Lighthouse & Core Web Vitals)

Poniższe wyniki pochodzą z rzeczywistego audytu produkcyjnego (Google Lighthouse v13):

| Kategoria Audytu | Desktop Broadband | Mobile (4G + 4x CPU Throttling) | Standard / Uwagi Inżynierskie |
| :--- | :---: | :---: | :--- |
| **Performance** | **100 / 100** | **88–92 / 100** | FCP = 0.6s, LCP = 0.7s (Desktop); FCP = 2.3s, LCP = 3.4s (Mobile) |
| **Accessibility** | **100 / 100** | **100 / 100** | Pełna zgodność z WCAG 2.1 AA (kontrast $\ge 4.5:1$, Label in Name) |
| **SEO** | **100 / 100** | **100 / 100** | Kompletne metadane Open Graph, JSON-LD Schema.org, semantyczny HTML |
| **Best Practices** | **81 / 100** | **81 / 100** | Obniżone przez skrypty Cloudflare Challenge (`cdn-cgi/challenge-platform`) |
| **Cumulative Layout Shift (CLS)** | **0.000** | **0.001** | Zero przesunięć layoutu podczas renderowania |
| **Total Blocking Time (TBT)** | **10–20 ms** | **110 ms** | Optymalny budżet głównego wątku przeglądarki ($<200ms$) |

---

## 7. Bezpieczny Moduł Kontaktu & Serverless API (Resend & Cloudflare Turnstile)

Serwis implementuje dedykowaną funkcję bezserwerową **`api/contact.ts`** (Vercel Serverless Function) z wielowarstwową ochroną przed botami i spływem fałszywych leadów:

```mermaid
flowchart LR
    Client["ContactModal.tsx (#contact)"] --> Turnstile["Cloudflare Turnstile"]
    Turnstile --> API["api/contact.ts"]
    API --> Security["Rate Limiter + Honeypot + Zod + XSS Sanitizer"]
    Security --> Resend["Resend API (SDK)"]
    Resend --> Admin["Alert: kontakt@czerwinskidawid.pl + Gmail"]
    Resend --> Autoresponder["HTML Autoresponder do Klienta"]
```

- **Wielowarstwowa ochrona antyspamowa:**
  - **In-Memory Rate Limiter:** Blokada 429 po przekroczeniu 5 zapytań / 15 min z danego adresu IP.
  - **Honeypot Trap:** Niewidoczne pole `honeypot` zwracające natychmiastowy, cichy kod 200 OK dla botów bez wywoływania API Resend.
  - **Cloudflare Turnstile:** Weryfikacja challenge po stronie serwera (`challenges.cloudflare.com/turnstile/v0/siteverify`).
  - **Sanityzacja XSS (`escapeHtml`):** Oczyszczanie wszystkich pól formularza przed wstrzyknięciem do szablonów HTML e-mail.
  - **Walidacja Zod:** Ścisła kontrola typów, długości znaków i formatów danych (`name`, `email`, `phone`, `topic`, `message`).
- **Podwójna wysyłka transakcyjna (Resend):**
  - **Powiadomienie dla Właściciela:** E-mail ze szczegółami leada i nagłówkiem `replyTo` skierowanym na adres klienta.
  - **Markowy Autoresponder HTML:** Automatyczna, profesjonalna wiadomość potwierdzająca dostarczenie zapytania z danymi kontaktowymi Dawida.
- **Deep Linking:** Bezpośrednie wywołanie modala przez parametr URL `#/contact` lub `#kontakt`.

---

## 8. Lokalne Środowisko & Bramki Jakościowe (Quality Gates)

```bash
# 1. Instalacja zależności projektowych
npm install

# 2. Uruchomienie lokalnego serwera deweloperskiego Vite
npm run dev

# 3. Uruchomienie pełnego zestawu testów jednostkowych Vitest (64/64 passing)
npm test

# 4. Ścisła weryfikacja typów TypeScript (Krytyczna Bramka Jakościowa: 0 błędów)
npm run typecheck

# 5. Hybrydowa synchronizacja specyfikacji technicznych z repozytoriami
npm run sync:readmes

# 6. Odpytanie metryk GitHub API (gwiazdki, commity, daty aktualizacji)
npm run fetch:stats

# 7. Kompilacja produkcyjna
npm run build
```

---

## 9. Licencja i Prawa Autorskie

Zaprojektowane i zaimplementowane przez **Dawida Czerwińskiego**.  
Kod i architektura podlegają ścisłym regułom Clean Architecture, Single Source of Truth (SSOT) oraz Zero-Hallucination Engineering.



---


================================================================================
SYSTEM SPECIFICATION: LEADFINDER (ID: leadfinder)
Deep Link: https://czerwinskidawid.pl/#projects/leadfinder
================================================================================

# LeadFinder: Google Maps Lead Generator API

Automated tool to identify businesses with a digital gap on Google Maps. It acts as a FastAPI backend that orchestrates a custom Google Maps scraper (via Docker), filters out businesses that already have websites or too many reviews, enriches the data with domain availability checks, and generates personalized demo links.

## Table of Contents
1. [Architecture & Flow](#architecture--flow)
2. [Prerequisites](#prerequisites)
3. [Setup & Installation](#setup--installation)
4. [Running the API](#running-the-api)
5. [API Documentation](#api-documentation)

---

## Architecture & Flow

The system is built as an asynchronous API to prevent long-running HTTP requests from timing out while the scraper processes data.

### Core Components

1. **`src/api.py` (The Entry Point)**
   - A FastAPI application that exposes the `/api/v1/leads/generate` endpoint.
   - It validates incoming JSON payloads using Pydantic (`ScrapeRequest`).
   - It offloads the heavy lifting (scraping and filtering) to a FastAPI `BackgroundTask` (`run_scrape_background`) and immediately returns a `202 Accepted` response.

2. **The Docker Scraper Engine (`gosom/google-maps-scraper`)**
   - Triggered via `subprocess.run()` inside the background task.
   - It connects to Google Maps, performs the search, scrolls the results, and writes raw CSV data to the `raw_data/` directory.
   - *Note: We use a custom, patched fork of the scraper to bypass bot detection and properly handle asynchronous DOM loading for reviews.*

3. **`src/filter_leads.py` (The Data Pipeline)**
   - Once the scraper finishes, this script reads the raw CSVs.
   - **Filtering:** Drops permanently closed businesses, businesses with a website, and businesses exceeding the `max_reviews` threshold.
   - **Enrichment:** Calculates a "Digital Score" (0-3 scale based on phone and social media presence) and formats a unified "Contact Profile".
   - **Domain Check:** Uses the `whois` library to check if `.pl` and `.com` domains matching the business name are available.

4. **`src/template_matcher.py` (The Magic Link Generator)**
   - Called by the filter script for every valid lead.
   - It analyzes the business name and search keyword against a dictionary of industries to assign the best landing page template (e.g., `warsztat-pro`, `bistro-modern`).
   - Generates a "Magic Link" for instant tailored demos.

---

## Prerequisites
- **Python 3.10+**
- **Docker** (Required for the scraper engine)
- **Linux/macOS Environment** (The docker execution commands are optimized for Unix paths)

---

## Setup & Installation

1. **Clone the repository:**
   ```bash
   git clone https://github.com/Gzyms69/LeadFinder.git
   cd LeadFinder
   ```

2. **Set up the virtual environment:**
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   ```

3. **Pull the scraper image:**
   ```bash
   docker pull gosom/google-maps-scraper:latest
   ```

---

## Running the API

Start the FastAPI server using Uvicorn:

```bash
source venv/bin/activate
uvicorn src.api:app --host 0.0.0.1 --port 8000 --reload
```

The API will be available at `http://127.0.0.1:8000`.
You can access the interactive Swagger UI documentation at `http://127.0.0.1:8000/docs`.

---

## Production Cloud Deployment (Oracle Cloud Infrastructure)

LeadFinder is deployed as a 24/7 background service on an **Oracle Cloud Infrastructure (OCI) Compute Instance** (Ampere A1 Flex, Ubuntu Linux):

### 1. Systemd Service Daemon (`leadfinder.service`)
The API runs under `systemd` with automatic restart on failure and integration with the Docker group socket:

```ini
[Unit]
Description=LeadFinder FastAPI Service
After=network.target docker.service
Requires=docker.service

[Service]
User=ubuntu
Group=docker
WorkingDirectory=/home/ubuntu/LeadFinder
EnvironmentFile=/home/ubuntu/LeadFinder/.env
ExecStart=/home/ubuntu/LeadFinder/venv/bin/uvicorn src.api:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

### 2. Service Management Commands
```bash
# Register and start the background service
sudo cp leadfinder.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now leadfinder

# Monitor service status and logs
sudo systemctl status leadfinder
journalctl -u leadfinder -f
```

---

## API Documentation

For detailed information on the available endpoints, JSON payloads, and response formats, please refer to the dedicated API Reference:

[👉 Read the API Reference (`docs/API_REFERENCE.md`)](docs/API_REFERENCE.md)



---


================================================================================
SYSTEM SPECIFICATION: ROMHUB (ID: romhub)
Deep Link: https://czerwinskidawid.pl/#projects/romhub
================================================================================

# ROMHub

ROMHub is a client-side Nintendo 64 emulation platform built on WebAssembly and WebRTC. It executes retro titles inside desktop and mobile browsers at 60 FPS without requiring native plugins, backend compute servers, or game installation.

---

## Technical Overview

ROMHub compiles the Mupen64Plus emulation core to WebAssembly via Emscripten, rendering frames directly to an HTML5 WebGL canvas and outputting PCM audio through the Web Audio API. 

Peer-to-peer multiplayer is implemented over WebRTC DataChannels using a deterministic lockstep input pipeline. When a multiplayer session starts, the host transmits ROM data to connected clients in 32KB chunks. Once verified via CRC32 checksums, both instances boot the title locally and exchange 7-byte binary controller frames at 60 Hz with sub-frame input latency.

```
+-----------------------------------------------------------------------+
|                              Browser UI                               |
|   [ PPSSPP Touch HUD ]   [ HTML5 Gamepad ]   [ Keyboard Remapper ]    |
+-----------------------------------+-----------------------------------+
                                    |
                                    v
+-----------------------------------------------------------------------+
|                         ROMHub Netplay Engine                         |
|   - 7-byte Binary Input Serializer / Deserializer                     |
|   - W3C Gamepad Proxy (Slots 0 to 3)                                  |
|   - WebRTC DataChannel (P2P Input Sync, CRC32 ROM Transfer)           |
|   - Periodic State Desync Guard (Module._neil_serialize)              |
+-----------------------------------+-----------------------------------+
                                    |
                                    v
+-----------------------------------------------------------------------+
|                    WebAssembly & Emscripten Bridge                    |
|   - Emscripten Runtime Bridge (ccall, cwrap, Module._*)               |
|   - SDL2 Joystick & Event Subsystem (navigator.getGamepads)           |
|   - Web Audio Ring Buffer Resampling                                  |
+-----------------------------------+-----------------------------------+
                                    |
                                    v
+-----------------------------------------------------------------------+
|                   Mupen64Plus Core Engine (C / C++)                   |
|   - MIPS R4300i Dynamic Recompiler / Interpreter                      |
|   - Reality Co-Processor (RSP Vector DSP / RDP Rasterizer)            |
|   - 4-Player Serial Interface (SI) Controller Management              |
+-----------------------------------------------------------------------+
```

---

## Key Subsystems

### 1. WebAssembly Emulation Core
- **MIPS R4300i CPU Simulation:** Compiles M64P core logic to WebAssembly, executing cycle-accurate instruction sets.
- **Reality Coprocessor (RSP / RDP):** Hardware rasterization translated into WebGL 1.0 / 2.0 shader draw calls.
- **Audio Dynamic Resampling:** Web Audio ring buffer synchronizes emulation time with host audio hardware clock, preventing underflows.
- **Save State Persistence:** IndexedDB stores cartridge battery RAM (SRAM, FlashRAM, EEPROM 4k/16k) and memory snapshots (`/savestate.gz`).

### 2. Dual-Mode WebRTC Multiplayer

#### Mode A: Local WebGL ROM & Input Sync (Default)
1. **Lobby & Chunk Transfer:** The host opens a room code (e.g. `ROM-TEST`). When a guest joins, the host transmits the ROM over WebRTC DataChannel in 32KB slices.
2. **CRC32 Verification:** The guest reassembles the binary in memory and verifies its CRC32 checksum against the host manifest.
3. **Synchronized Launch:** The host issues a `LAUNCH_SYNC` command. Both machines execute a synchronized 3-2-1 countdown and boot WebAssembly simultaneously.
4. **Deterministic Lockstep:** Every 16 ms, peers exchange 7-byte input states. The `NetplayManager` injects incoming packets into virtual slots in `navigator.getGamepads()`.
5. **Desync Guard:** The host periodically exports save states via `Module._neil_serialize()` and verifies state integrity. If desynchronization occurs, the state snapshot is sent to guests and restored with `Module._neil_unserialize()`.

#### Mode B: Remote Canvas Video Stream
The host captures the active WebGL canvas via `canvas.captureStream(60)` and streams video/audio over a WebRTC MediaStream call. The guest transmits input events back to the host via DataChannel.

### 3. PPSSPP-Grade Glassmorphic Virtual Gamepad
- **Dynamic Floating 360 Analog Stick:** Spawns anywhere within the left thumb area upon touch, providing variable analog deflection.
- **Ergonomic N64 Layout:** Dedicated Z-trigger button below the analog stick, action buttons A and B, four C-buttons (C-Up, C-Down, C-Left, C-Right), and upper shoulder buttons (L, R, Start).
- **Multi-Touch Engine:** Distinct touch identifier tracking allows simultaneous stick movement, trigger holds, and button taps.
- **Haptic Feedback:** Optional micro-vibrations via `navigator.vibrate`.

---

## 7-Byte Binary Input Protocol Specification

Input frames are transmitted over unordered WebRTC DataChannels at 60 Hz.

### Packet Byte Structure

```
+--------+------------+-------------------+------------------+---------------+---------------+-------------------+
| Byte 0 |   Byte 1   |      Byte 2       |      Byte 3      |    Byte 4     |    Byte 5     |      Byte 6       |
+--------+------------+-------------------+------------------+---------------+---------------+-------------------+
|  0x01  | PlayerSlot | Buttons High Byte | Buttons Low Byte | Analog StickX | Analog StickY | Sequence ID (0-255)|
+--------+------------+-------------------+------------------+---------------+---------------+-------------------+
```

### Bitmask Mapping Table

| Bit Index | Controller Input | W3C Gamepad Standard Index | N64 Mapping Target |
|:---------:|:-----------------|:--------------------------:|:-------------------|
| 0 | Action A | Button 0 | Joy_Mapping_Action_A (0) |
| 1 | Alt B | Button 1 | Unused |
| 2 | Action B | Button 2 | Joy_Mapping_Action_B (2) |
| 3 | Button Y | Button 3 | Unused |
| 4 | Z Trigger | Button 4 | Joy_Mapping_Action_Z (4) |
| 5 | R Trigger | Button 5 | Joy_Mapping_Action_R (5) |
| 6 | L Trigger | Button 6 | Joy_Mapping_Action_L (6) |
| 7 | ZR / R2 | Button 7 | Unused |
| 8 | Select | Button 8 | Unused |
| 9 | Start | Button 9 | Joy_Mapping_Action_Start (9) |
| 10 | Stick Click | Button 10 | Unused |
| 11 | Menu | Button 11 | Joy_Mapping_Menu (11) |
| 12 | D-Pad Up / C-Up | Button 12 | Joy_Mapping_Up (12) |
| 13 | D-Pad Down / C-Down | Button 13 | Joy_Mapping_Down (13) |
| 14 | D-Pad Left / C-Left | Button 14 | Joy_Mapping_Left (14) |
| 15 | D-Pad Right / C-Right | Button 15 | Joy_Mapping_Right (15) |

- **Analog Stick Coordinates:** Encoded in Bytes 4 and 5 as unsigned integers `[0, 255]`, where `128` represents center neutral, `0` is full negative, and `255` is full positive.

---

## File Structure

```
ROMHub/
|-- css/
|   `-- style.css           # Glassmorphism styling, responsive canvas viewport, PPSSPP HUD
|
|-- js/
|   |-- FileSaver.min.js    # Client-side file saving utility
|   |-- nipplejs.min.js     # Legacy touch fallback library
|   `-- peerjs.min.js       # WebRTC signaling and DataChannel client
|
|-- scripts/
|   `-- test_netplay_e2e.js # Automated multi-client Puppeteer WebRTC E2E test harness
|
|-- index.html              # Main application entry point, viewport layout, modals
|-- netplay.js              # WebRTC engine, Gamepad proxy, CRC32 streaming, Desync Guard
|-- script.js               # Application lifecycle coordinator and Emscripten bindings
|-- touch_controller.js     # PPSSPP-style virtual multi-touch gamepad
|-- input_controller.js     # Keyboard, Gamepad API, and button remapping
|-- logger.js               # Diagnostic logger, binary packet filter, telemetry collector
|-- n64wasm.js              # Emscripten compiled JavaScript runtime
|-- n64wasm.wasm            # Compiled Mupen64Plus WebAssembly binary
|-- assets.zip              # Shaders, ROM catalog assets, and system configurations
|-- package.json            # Node.js dependencies for automated testing
|-- GEMINI.md               # AI agent operating guide and single source of truth
`-- README.md               # Project documentation
```

---

## Development Setup

ROMHub runs as a static web application and requires an HTTP/HTTPS server due to WebAssembly cross-origin isolation and WebRTC security constraints.

### 1. Run Local Development Server
Using Python:
```bash
python3 -m http.server 8080
```

Or using Node.js:
```bash
npx serve . -p 8080
```

Open `http://localhost:8080` in Chrome, Firefox, Safari, or Edge.

---

## Automated Multi-Client E2E Testing

The project includes an end-to-end test harness using Puppeteer to simulate real-world multiplayer sessions between desktop and mobile clients.

### Test Execution
```bash
node scripts/test_netplay_e2e.js
```

### Verified Test Sequence:
1. Spawns an internal HTTP server and launches two headless Chromium browser instances.
2. Configures Browser 1 as Desktop Host (1920x1080) and Browser 2 as Mobile Guest (Pixel 7 viewport with touch emulation).
3. Host stages a synthetic ROM and initializes a WebRTC room.
4. Guest connects via DataChannel, receives 32KB ROM slices, reassembles data, and verifies CRC32 checksums.
5. Host acknowledges Player 2 readiness and triggers a synchronized countdown.
6. Guest simulates touch stick deflection and button presses; Host verifies reception of 7-byte binary packets in slot P2.
7. Host simulates Player 1 controls; Guest verifies reception in slot P1.

---

## Diagnostics & Telemetry

Open the in-app debug terminal by clicking the diagnostics button in the floating HUD. The diagnostic suite provides:
- WebRTC broker status, ICE candidate states, and DataChannel status.
- Real-time round-trip latency (RTT) and frame transmission rate (PPS).
- Controller visualizer showing real-time button states and analog stick coordinates for both players.
- Diagnostic report generator exportable to clipboard for troubleshooting.

---

## License & Compliance

- **Client-Side Execution:** All emulation logic and ROM decoding execute strictly in browser memory on the user's hardware.
- **Cartridge Rights:** Users must provide their own legitimately acquired ROM backups.
- **P2P Encryption:** Netplay sessions communicate over DTLS-encrypted WebRTC channels directly between peers.


---


================================================================================
SYSTEM SPECIFICATION: DEEPSEEK FOLDER ORGANIZER (ID: deepseek-organizer)
Deep Link: https://czerwinskidawid.pl/#projects/deepseek-organizer
================================================================================

# DeepSeek Folder Organizer

A Tampermonkey userscript that adds advanced folder organization capabilities to DeepSeek chat conversations. Organize your conversations into custom folders with icons and colors for better productivity and workflow management.

## Features

- **Custom Folders**: Create unlimited folders with custom names, icons, and colors
- **Visual Organization**: See folder tags directly next to conversation titles
- **Conversation Filtering**: Filter conversations by folder to focus on specific topics
- **Easy Management**: Add, rename, customize, and delete folders as needed
- **Persistent Storage**: All data stored locally in your browser
- **Search Functionality**: Search through conversations when managing folders
- **Intuitive Interface**: Clean, user-friendly interface that integrates seamlessly with DeepSeek

## Installation

1. Install the [Tampermonkey](https://www.tampermonkey.net/) browser extension for your browser
2. Click on the [DeepSeek Folder Organizer script](https://raw.githubusercontent.com/Gzyms69/DeepSeek-Folder-Organizer/main/DeepSeek%20Folder%20Organizer-3.0.user.js) to install the userscript
3. Allow the installation in Tampermonkey
4. Navigate to [DeepSeek Chat](https://chat.deepseek.com/) to start using the organizer

## Usage

### Getting Started
1. Once installed, visit DeepSeek Chat
2. You'll see a "Folders" button appear in the sidebar
3. Click the "Folders" button to open the folder management panel

### Creating Folders
1. Click the "+" button in the folder panel header
2. Enter a name for your folder
3. Choose an icon and color for the folder
4. Click "Create"

### Organizing Conversations
1. Open the folder panel by clicking the "Folders" button
2. Right-click on any folder to open the context menu
3. Select "Manage Conversations"
4. Check the boxes next to conversations you want to add to the folder
5. Uncheck boxes to remove conversations from the folder
6. Click "Save Changes"

### Filtering Conversations
- Click on any folder name in the folder panel to filter conversations
- Click "All Conversations" to see all conversations again
- The folder panel can be toggled on/off using the "Folders" button

### Customizing Folders
- Right-click on any folder to access options:
  - Rename: Change the folder name
  - Customize: Change icon and color
  - Manage Conversations: Add/remove conversations from the folder
  - Delete: Remove the folder (conversations become unassigned)

## Supported Icons

The script includes a variety of icons for folder customization:
- Folder and file icons
- Category and organization icons
- Code and technology icons
- Star and favorite icons
- Learning and education icons
- Personal and work icons
- Miscellaneous icons

## Privacy

All data is stored locally in your browser using Tampermonkey's storage API. No conversation data is sent to external servers.

## Compatibility

- Works with all modern browsers that support Tampermonkey (Chrome, Firefox, Edge, Safari)
- Compatible with the current DeepSeek Chat interface
- Automatically updates conversation lists when new conversations are created

## Troubleshooting

If you experience issues:
1. Refresh the DeepSeek Chat page
2. Check that Tampermonkey is enabled
3. Ensure the script is properly installed and enabled in Tampermonkey
4. Disable and re-enable the script if needed

## Contributing

Feel free to fork this repository and submit pull requests for improvements. Bug reports and feature suggestions are welcome through the GitHub Issues section.

## License

This project is released under the MIT License. See the LICENSE file for more details.

---


================================================================================
SYSTEM SPECIFICATION: AGENT SETUP BUNDLE (ID: agent-setup-bundle)
Deep Link: https://czerwinskidawid.pl/#projects/agent-setup-bundle
================================================================================

# Multi-Platform Agentic AI Engineering Operating System & Skill Suite

> Production-ready, cross-platform configuration framework, system rules (Prime Directives), 33 modular skills (`agentskills.io` standard), repository blueprints (`AGENTS.md`), and Model Context Protocol (MCP) configurations for **OpenAI Codex**, **Antigravity / Gemini CLI**, **Claude Code**, and **Modern Cursor IDE (.mdc)** across **Windows**, **macOS**, and **Linux**.

---

##  1-Prompt Autonomous AI Installation

If you are using an AI coding assistant (Claude Code, OpenAI Codex, Cursor Composer, Gemini CLI, Cline, Roo Code, OpenCode, Aider), simply paste this prompt:

### English:
```text
Clone https://github.com/Gzyms69/agent-setup-bundle.git and install the full AI engineering operating system for me following AGENTS.md in the repo.
```

### Polski:
```text
Sklonuj https://github.com/Gzyms69/agent-setup-bundle.git i zainstaluj całe środowisko inżynieryjne według instrukcji w AGENTS.md.
```

Your AI assistant will read [AGENTS.md](AGENTS.md), auto-detect your operating system (Windows, macOS, or Linux), run the appropriate native installer, validate suite integrity, and immediately adopt the **Senior AI Pair Programmer** persona.

---

## 1. Executive Summary & Philosophy

Traditional approaches to AI pair programming ("Just write this feature") fail consistently on non-trivial codebases due to four core traps:
1. **Simulation & Mocking Traps:** Writing fake stubs or untested boilerplate without running verification suites.
2. **Context Window Flooding:** Inefficiently dumping thousands of prompt lines instead of on-demand skill discovery.
3. **Monolithic Spaghetti Code:** Creating giant "god files" (>150 lines) that mix state, presentation, networking, and styles.
4. **Hardware & Version Hallucinations:** Speculating about hardware capabilities, compiler flags, or package versions without live verification.

**`agent-setup-bundle`** solves this by establishing a deterministic, multi-platform engineering operating system across all major coding assistants.

```mermaid
flowchart TD
    subgraph Core_Directives["12 Żelaznych Reguł Architektonicznych"]
        PRAR["Protokół PRAR (Perceive -> Reason -> Act -> Refine)"]
        ZeroSpec["Zero-Speculation Protocol (Zakaz Zgadywania)"]
        TSGate["Critical TypeScript Safety Gate (npx tsc --noEmit)"]
    end

    subgraph Skills_Matrix["Baza 25 Modułowych Umiejętności (~/.agents/skills)"]
        Dev["Inżynieria (Frontend, Backend, GIS, Low-Level)"]
        QA["Jakość & Review (Doubt-Driven, Code-Review)"]
        Design["Art Direction (Swiss, OKLCH, Design Engineering)"]
    end

    subgraph MCP_Servers["11 Natywnych Serwerów Narzędziowych (MCP)"]
        Tools["GitHub API, Chrome DevTools, MemPalace, Puppeteer, OCI"]
    end

    Core_Directives --> Skills_Matrix --> MCP_Servers
```

---

## 2. Core Engineering Mandates (The Laws of Robotics)

Every agent configured with this suite strictly adheres to the following non-negotiable protocols:

1. **PRAR Workflow (Perceive, Reason, Act, Refine):**
   - Agents never write code blindly. Every task begins with environmental analysis (Perceive), architectural design (Reason), surgical modifications (Act), and verification (Refine).
2. **Mandatory 4-Phase Pre-Flight Skill Gate:**
   - Before executing file discovery (`grep`, `find`, `cat`) or modifying code, agents must evaluate and load domain skills in a strict 4-phase sequence.
3. **The Wait-For-GO Mandate:**
   - On tasks requiring architectural decisions, touching >3 files, or introducing new dependencies, agents must present a detailed implementation plan and wait for an explicit user approval ("GO") before mutating files.
4. **Zero Speculation Protocol:**
   - Total ban on guessing hardware specs, software versions, API endpoints, error causes, or compiler flags. Technical facts must be verified using live terminal commands or documentation lookup.
5. **Root Cause Only & Anti-Workaround:**
   - Ban on temporary workarounds, path symlinks, or defensive `try/catch` wrappers that mask failures. Bugs must be resolved at the lowest architectural layer (`Kernel > Driver > OS Config > Runtime > Framework > Application Code`).
6. **Critical TypeScript Safety Gate:**
   - After modifying any `.ts`/`.tsx` file, agents must run `npx tsc --noEmit`. Deleting business logic to bypass type errors is strictly forbidden.
7. **Single Source of Truth (SSOT) & Anti-Duplication:**
   - Duplicate helpers, parallel endpoints, or competing schemas are forbidden. Existing implementations must be reused or refactored in-place.
8. **Anti-Destruction Protocol:**
   - Strict ban on `git clean`, blind mass search-and-replace, or destructive workspace operations without explicit user confirmation.

---

## 3. The 4-Phase Pre-Flight Skill Gate

To prevent context window bloat and eliminate architectural guessing, skills are activated through a gated hierarchy:

```
[Level 0: Metadata & Cartography] ──→ [Level 1: Planning & Spec] ──→ [Level 2: Domain Specialists]
                                                                                │
                                      [Level 3: QA & Verification Gate] ◀───────┘
```

```mermaid
graph TD
    A[User Request] --> B{Phase 0: Workspace Cartography}
    B -->|Unmapped Repo| B1[skill-codebase-onboarding / spec-miner / AGENTS.md]
    B --> C{Phase 1: Planning & Architecture}
    C -->|>15 min / >3 files / /plan| C1[spec-driven-development / monorepo / plugin]
    C --> D{Phase 2: Domain Specialists}
    D -->|Frontend| D1[skill-frontend-architect / design-engineering / creative-design]
    D -->|Backend/Systems| D2[skill-backend-architect / c-cpp-systems / wasm-emscripten]
    D -->|AI / Data| D3[skill-ai-ml / skill-data-science / skill-graph-analytics]
    D -->|Specialized| D4[skill-stealth-scraping / skill-system-diagnostics / research]
    D --> E{Phase 3: QA & Verification}
    E -->|On Code Execution| E1[skill-qa-engineer: TDD & TSC / skill-code-review: 5-Axis]
```

---

## 4. Project-Level Configuration Standard (`AGENTS.md`)

Global rules in `~/.agents/` define **agent behavior**, but individual repositories require **project-level context**.

This bundle provides the standardized [templates/AGENTS.md](templates/AGENTS.md) blueprint based on the Agentic AI Foundation (AAIF) specification.

### How to use `AGENTS.md` in your projects:
1. Copy the blueprint to your project root:
   - **Linux / macOS:** `cp ~/.agents/templates/AGENTS.md ~/Dev/MyProject/AGENTS.md`
   - **Windows:** `Copy-Item $env:USERPROFILE\.agents\templates\AGENTS.md C:\Dev\MyProject\AGENTS.md`
2. Fill in the 4 core sections:
   - **Project Identity & Stack Architecture:** Language, runtime, framework versions, database ORM, styling system.
   - **Mandatory Commands (Executable Truth):** Exact commands with flags for `install`, `dev`, `build`, `test`, `tsc`, and `lint` (agents will NEVER guess CLI flags).
   - **Directory Topography & Module Boundaries:** Explicit directory layout and boundaries (e.g. `src/domain/`, `src/adapters/`, `src/components/`).
   - **Invariants & Guardrails (Never-Do Rules):** Strict project invariants (e.g. "Never import DB models in client components", "Files must remain under 150 lines").

When OpenAI Codex, Claude Code, Gemini CLI, or Cursor opens your project, it reads `AGENTS.md` as the primary Source of Truth.

---

## 5. 16 Operational Core Rules (`~/.agents/rules/`)

| Rule | File | Purpose & Key Mandate |
|---|---|---|
| **Skill Orchestration** | `skill-orchestration.md` | Mandates the 4-Phase Pre-Flight Skill Gate before file discovery or code modifications. |
| **Planning & Document Integrity** | `planning-and-document-integrity.md` | Multi-turn `/plan` lifecycle, `Iteration Delta`, Discovered Facts Lock, and Active SSOT (anti-zombie context). |
| **Context Engineering** | `context-engineering.md` | Attention budget preservation, scratchpad offloading (>100 lines/5KB), and context poisoning circuit breaker. |
| **Zero Speculation** | `zero-speculation.md` | Total ban on guessing versions, APIs, or system specs without live diagnostic verification. |
| **Modular Architecture** | `modular-architecture.md` | Anti-Monolith constraint (max ~150-200 lines), Clean/Hexagonal boundaries, typed contracts. |
| **Systemic Excellence** | `systemic-excellence.md` | Anti-workaround protocol, root-cause fixes, DRY, and Single Source of Truth (SSOT). |
| **System Identity** | `system-identity.md` | Hardware & OS baseline template with auto-discovery commands to prevent hallucinations. |
| **Command Verification** | `command-verification.md` | Mandatory secondary read-only check after any state-modifying command. |
| **Subagent Economy** | `subagent-economy.md` | Dynamic LLM model tiering, Zero Context Bleed mandate, workspace isolation, and barrier sync. |
| **Problem Isolation** | `problem-isolation.md` | Strict scope containment; zero unrequested refactors or global OS alterations. |
| **Environment Integrity** | `env-integrity.md` | Sanity checks on workspace, lockfiles, and dependencies before modifying files. |
| **Error Triage** | `error-triage.md` | Deterministic diagnostic priority order: Documentation -> Web Search -> Code Inspection. |
| **Full Log Reporting** | `full-log-reporting.md` | Ban on truncated, summarized, or paraphrased error reporting. |
| **MemPalace Discovery** | `mempalace-discovery.md` | Absolute priority of MemPalace memory retrieval before broad filesystem searches. |
| **MCP Master Playbook** | `mcp-master-playbook.md` | 11-server MCP execution matrix, permission boundaries, and synergy workflows. |
| **Session Handoff** | `session-handoff.md` | Lossless context transfer, Lean SSOT enforcement, and standardized bootstrap prompts. |

---

## 6. 36 Production-Grade Skills (`~/.agents/skills/`)

All skills adhere to the `agentskills.io` standard with YAML frontmatter, progressive disclosure, and anti-rationalization verification gates:

### Domain A: Cartography, Planning, Context & Orchestration (7 Skills)
- **`skill-codebase-onboarding`**: Systematic 5-phase repository cartography, entrypoint discovery, and command extraction.
- **`spec-miner`**: Reverse-engineering engine for extracting specifications and dataflows from legacy/undocumented code.
- **`spec-driven-development`**: Gated SDLC workflow (Specify -> Plan -> Tasks -> Implement) with verification matrices.
- **`skill-context-engineering`**: Production context engineering, Attention U-Curve defense, Anchored Iterative Summarization, and Artifact Trail tracking.
- **`skill-master-orchestrator`**: Master agent orchestration, multi-agent swarm coordination, Task DAG decomposition, and model economy routing.
- **`skill-monorepo-architect`**: Polyglot monorepo management (`uv` Python workspaces, `pnpm` workspaces, Turborepo).
- **`skill-plugin-architecture`**: Microkernel architecture, dynamic plugin discovery, lifecycle hooks, and error boundaries.

### Domain B: Frontend & UI/UX Craftsmanship (5 Skills)
- **`skill-frontend-architect`**: Next.js 15+ App Router, React Server Components (RSC), Client Island boundaries, WCAG 2.2 AA.
- **`skill-design-engineering`**: Creative frontend engineering, Motion.dev spring animations, CSS Subgrid, Container Queries, 21st.dev UI components.
- **`skill-creative-design`**: Art direction, Swiss/Bauhaus aesthetics, Fontjoy typography math, and OKLCH color physics.
- **`skill-web-performance`**: Core Web Vitals optimization (LCP, INP, CLS), Lighthouse 100/100 audits, and runtime tracing.
- **`seo-optimization-and-audit`**: Search engine ranking optimization, structured metadata, semantic HTML, and head audits.

### Domain C: Backend, Systems & MCP (8 Skills)
- **`skill-backend-architect`**: Contract-first API design, database schemas, query optimization (`EXPLAIN ANALYZE`), indexing, and Expand/Contract migrations.
- **`skill-mcp-builder`**: Architecture, implementation, and debugging of Model Context Protocol (MCP) servers (FastMCP, TypeScript SDK, stdio/SSE).
- **`skill-web-architecture`**: Full-stack architectural standards, module boundaries, and end-to-end API contracts.
- **`c-cpp-systems`**: Memory safety, struct packing (`#pragma pack`), manual RAII, bitwise math, and sanitizers (`ASan`/`UBSan`).
- **`skill-low-level-programming`**: Low-level systems programming, Assembly, byte manipulation, memory layout, and endianness handling.
- **`wasm-emscripten`**: WebAssembly compilation via Emscripten, `ccall`/`cwrap` FFI bindings, virtual FS, and HEAP views.
- **`retro-emulation-engineering`**: Retro hardware simulation (CPU/RSP/RDP), frame timing, dynamic audio resampling, and ROM validation.
- **`skill-emulator-wasm`**: WebAssembly retro emulation engineering, Emscripten bridge lifecycle, WebGL rendering, and cartridge saves.

### Domain D: AI, Data Science & Intelligence (7 Skills)
- **`skill-ai-ml`**: LLM model integrations, embeddings, vector databases (Redis, ChromaDB), and agentic workflows.
- **`skill-data-science`**: Data ingestion pipelines, exploratory data analysis (EDA), dataframes (Polars/Pandas), and validation.
- **`skill-data-analysis`**: Statistical analysis, hypothesis testing, anomaly detection, and scientific claim verification.
- **`skill-graph-analytics`**: Graph databases (Neo4j), Cypher queries, topology analysis, and Graph Data Science (GDS).
- **`skill-stealth-scraping`**: Anti-bot evasion (Cloudflare/DataDome), TLS fingerprint spoofing, and browser automation.
- **`skill-osint-engineering`**: Open Source Intelligence gathering, Pydantic entity graphs, pivoting engines, and OPSEC.
- **`skill-research`**: Academic and technical literature research, arXiv paper analysis, and multi-source fact checking.

### Domain E: QA, Systems Diagnostics & Conversion (9 Skills)
- **`skill-qa-engineer`**: Test-Driven Development (TDD Red-Green), TypeScript compilation safety gates (`npx tsc --noEmit`).
- **`skill-code-review`**: Systematic 5-axis code review (Correctness, Readability, Architecture, Security OWASP Top 10, Performance).
- **`doubt-driven-development`**: Adversarial verification gate to challenge false confidence and prevent silent failures.
- **`skill-system-diagnostics`**: Hardware, OS, driver, kernel panic diagnostics, and log analysis.
- **`skill-devops-cloud`**: Docker containers, Docker MCP inspection, CI/CD pipelines, and cloud deployments.
- **`skill-resume-tailor`**: ATS-optimized resume, CV, and cover letter tailoring following the Google XYZ formula.
- **`marketing-copywriting`**: Conversion-focused technical copywriting and value proposition design.
- **`avoid-ai-writing`**: Detection and elimination of AI writing clichés, robotic cadence, and filler words.
- **`mempalace` / `mempalace-recall`**: Long-term memory palace management and historical knowledge retrieval.

---

## 7. Cross-Platform Quickstart & Installation

Clone and run the installer for your operating system:

```bash
git clone https://github.com/Gzyms69/agent-setup-bundle.git
cd agent-setup-bundle
```

### Option A: Windows (PowerShell)
```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1 -All
```
*Platform options:* `.\install.ps1 -Codex`, `.\install.ps1 -Gemini`, `.\install.ps1 -Claude`, `.\install.ps1 -Cursor`

### Option B: Linux & macOS (Bash / zsh)
```bash
chmod +x install.sh
./install.sh --all
```
*Platform options:* `./install.sh --codex`, `./install.sh --gemini`, `./install.sh --claude`, `./install.sh --cursor`

### Option C: Universal Python Installer (Any OS)
```bash
python install.py --all
```
*Platform options:* `python install.py --codex`, `python install.py --gemini`, `python install.py --claude`, `python install.py --cursor`

---

## 8. Supported Environments & Platform Matrix

| Platform | Manifest / Rule Location | Config Location | Skill Discovery Path |
|---|---|---|---|
| **OpenAI Codex** | `~/.codex/AGENTS.md` & `instructions.md` | `~/.codex/config.toml` | `~/.codex/skills/custom` -> `~/.agents/skills` |
| **Antigravity / Gemini CLI** | `~/.gemini/GEMINI.md` | `~/.gemini/settings.json` | `~/.agents/skills/` |
| **Claude Code** | `~/.claude/CLAUDE.md` + `.claude/agents/` | `~/.claude/mcp.json` | `~/.claude/skills` -> `~/.agents/skills` |
| **Cursor IDE** | `~/.cursor/rules/*.mdc` | `~/.cursor/mcp.json` | On-demand referencing |

---

## 9. Repository File Structure

```
agent_setup_bundle/
├── AGENTS.md                        # Master repository blueprint & AI installer instructions
├── README.md                        # Master technical documentation & cross-platform guide
├── PROMPT_FOR_AI.md                 # Universal bootstrap prompts
├── llms.txt                         # Semantic summary for web-enabled LLM agents
├── install.sh                       # Native Bash installer (Linux / macOS)
├── install.ps1                      # Native PowerShell installer (Windows)
├── install.py                       # Universal Python 3 installer (All OSes)
├── core/                            # Platform manifests (CODEX.md, GEMINI.md, CLAUDE.md, cursor)
├── rules/                           # 16 Universal Rules (~/.agents/rules/)
├── skills/                          # 36 Modular Skills (~/.agents/skills/)
├── templates/
│   └── AGENTS.md                    # Project-level starter template
├── config/                          # Configuration & MCP templates (codex, gemini, cursor)
├── policies/                        # MCP tool planning policies
└── scripts/
    └── validate_suite.py            # Quality assurance test suite
```

---

## 10. License

This project is licensed under the [MIT License](LICENSE).


---