feat: portfolio architecture v2

.github/workflows/site-preflight.yml

@@ -34,6 +34,16 @@ jobs:
       - name: Prepare reports directory
         run: mkdir -p qa-results
 
+      - name: Check JavaScript syntax
+        run: |
+          set -e
+          for file in ./*.js; do
+            node --check "$file"
+          done
+
+      - name: Check portfolio architecture consistency
+        run: npm run qa:portfolio
+
       - name: Validate HTML
         continue-on-error: true
         run: npm run qa:html 2>&1 | tee qa-results/html-validation.txt

.pa11yci

@@ -3,23 +3,17 @@
     "standard": "WCAG2AA",
     "timeout": 30000,
     "wait": 750,
-    "viewport": {
-      "width": 390,
-      "height": 844
-    },
-    "chromeLaunchConfig": {
-      "args": [
-        "--no-sandbox",
-        "--disable-setuid-sandbox"
-      ]
-    }
+    "viewport": { "width": 390, "height": 844 },
+    "chromeLaunchConfig": { "args": ["--no-sandbox", "--disable-setuid-sandbox"] }
   },
   "urls": [
     "http://127.0.0.1:4173/index.html",
     "http://127.0.0.1:4173/works.html",
     "http://127.0.0.1:4173/games.html",
     "http://127.0.0.1:4173/sinama-case-study.html",
     "http://127.0.0.1:4173/merge-rush-case-study.html",
+    "http://127.0.0.1:4173/labs.html",
+    "http://127.0.0.1:4173/now.html",
     "http://127.0.0.1:4173/blog.html",
     "http://127.0.0.1:4173/single-work.html",
     "http://127.0.0.1:4173/request.html",

PORTFOLIO_ARCHITECTURE.md

@@ -0,0 +1,167 @@
+# Portfolio Architecture V2
+
+## Why this exists
+
+The portfolio grew from a static personal site into a product with Recruiter Mode, Ajoop, Command Palette, bilingual copy, case studies, games, request intake, accessibility QA and multiple active flagship products.
+
+The previous structure duplicated current project truth across HTML pages, the monolithic runtime and `flagship-copy.js`. That made drift likely whenever SINAMA, Merge Rush or career positioning changed.
+
+## Source-of-truth rule
+
+For new portfolio work, **current product facts, recruiter profiles, build status and evidence summaries live in `portfolio-data.js` first**.
+
+Do not add a new SINAMA / Merge Rush fact directly to Ajoop or Recruiter Mode without first adding it to the registry.
+
+### `portfolio-data.js`
+
+Owns:
+
+- Profile and contact truth
+- Flagship project summaries
+- Project status / stack / proof
+- Role-specific recruiter profiles
+- Build log entries
+- Labs catalog
+- Sanitized SINAMA Evidence Explorer examples
+
+### `portfolio-v2.js`
+
+Owns:
+
+- Unified EN/TR attribute copy (`data-pv2-en` / `data-pv2-tr`)
+- Runtime synchronization of Ajoop with registry facts
+- Recruiter Mode V2 rendering
+- Role-specific URLs such as `?role=applied-ai`
+- Build Log rendering
+- Labs rendering
+- SINAMA Evidence Explorer rendering
+- Browser-side request receipt note
+- Command Palette extensions for Labs, Build Log and recruiter deep links
+
+### `portfolio-v2.css`
+
+Owns UI for the V2 runtime surfaces. New V2 components should be styled here instead of growing `style.css` unless they are true global primitives.
+
+## Runtime compatibility layer
+
+The old monolithic runtime is preserved byte-for-byte as `legacy-script.js`.
+
+`script.js` is now a small bootloader.
+
+On pages explicitly migrated to V2, the HTML already declares `portfolio-data.js` before `script.js` and `portfolio-v2.js` after it. The bootloader detects that setup and synchronously inserts only `legacy-script.js`, preserving execution order.
+
+On older pages that still contain only `<script src="script.js"></script>`, the bootloader inserts:
+
+`portfolio-data.js → legacy-script.js → portfolio-v2.js`
+
+It also adds `portfolio-v2.css` when missing.
+
+This keeps current Recruiter Mode and Ajoop evidence available on older case studies, certificates, 404 and mini-game pages without forcing a risky all-at-once HTML rewrite.
+
+Future refactors can extract focused modules from `legacy-script.js`; the compatibility bootloader gives that work a stable migration boundary.
+
+## Ajoop scope
+
+Ajoop is deterministic in this release. It maps portfolio questions to curated evidence-backed answers and links.
+
+V2 improves its grounding by sourcing current SINAMA, Merge Rush, role-fit and build-status facts from the central registry, but **does not claim a live LLM, semantic retrieval or RAG backend**.
+
+A future semantic assistant should be a separate, explicit product step with source citation, safe fallbacks and clear runtime boundaries.
+
+## Role deep links
+
+Supported role ids:
+
+- `applied-ai`
+- `solution-engineering`
+- `software`
+- `game`
+
+Example:
+
+`https://kaanbalci.com/?role=applied-ai`
+
+A valid role parameter selects that evidence profile and opens Recruiter Mode.
+
+## Page hierarchy
+
+### Professional narrative
+
+1. `index.html` — concise landing page
+2. `works.html` — curated professional evidence
+3. `sinama-case-study.html` — flagship Applied AI proof
+4. `merge-rush-case-study.html` — flagship game / interactive product proof
+5. `blog.html` — professional timeline
+6. `about.html` — profile and capability map
+7. `request.html` — project inquiry
+
+### Supporting surfaces
+
+- `now.html` — living build log
+- `labs.html` — technical experiments that should not dilute the main career story
+- `games.html` — actual game / playable work
+- `project-detail.html` — dynamic archive detail route; intentionally `noindex`
+- `single-work.html` — training / certificates
+
+## Evidence policy
+
+Prefer evidence over quantity metrics.
+
+Good proof:
+
+- Implemented product behavior
+- Test suites / regression logic
+- Release-readiness rules
+- Real customer workflows
+- Responsive QA evidence
+- Architecture boundaries
+- Live product links
+
+Weak proof should not lead the homepage:
+
+- Tutorial-scale repositories
+- Calculator / weather practice apps
+- Unbuilt concepts
+- Raw certificate counts
+
+These can remain in GitHub, Labs or archive surfaces.
+
+## SINAMA Evidence Explorer
+
+The explorer uses simplified, sanitized static examples. It is not a live evaluator and must never be presented as one.
+
+Its purpose is to make the product model understandable quickly:
+
+`Conversation → Tool Trace → Deterministic Findings → Release Verdict`
+
+## Merge Rush media policy
+
+The public case study may describe verified QA states from the private development record, but it must not invent gameplay screenshots.
+
+When real public screenshots or video are approved, add them to the public portfolio `assets/` folder and reference them from the case study. Keep the private repository private.
+
+## Request-form truth
+
+The current direct request endpoint uses Google Apps Script with `no-cors` browser submission. The browser cannot verify server-side receipt.
+
+The UI may show a **browser submission reference**, but must not call it a server confirmation until the endpoint returns a verifiable response with appropriate CORS handling.
+
+## QA
+
+The Site Preflight workflow remains the release safety net and now includes JavaScript syntax validation for all root JS files. V2 adds `labs.html` and `now.html` to Pa11y and Lighthouse coverage.
+
+Before merge:
+
+1. JavaScript syntax validation
+2. HTML validation
+3. spelling
+4. mobile Pa11y
+5. Lighthouse
+6. broken-link scan
+7. interaction review for Recruiter Mode V2, language switch, Ajoop, role deep links and SINAMA Evidence Explorer
+
+## Migration note
+
+`flagship-copy.js` was removed. Its responsibilities are now handled by the registry + V2 runtime.
+
+`legacy-script.js` is compatibility code, not the preferred home for new product facts. New current-state logic should enter through the registry or focused V2 modules first.

README.md

@@ -2,53 +2,112 @@
 
 Source code for [kaanbalci.com](https://kaanbalci.com), the professional portfolio of **Kaan Balcı — AI Designer & Software Developer**.
 
-## Professional focus
+## Current positioning
 
-- Conversational AI and chatbot flow design
-- Solution engineering
-- LLM response, reasoning, code and multimodal evaluation
-- Workflow automation and n8n-style logic
-- User-centered software products
-- Python, C#/.NET, JavaScript, PHP and SQL
+The public portfolio is centered on:
 
-Game development, mobile development and interactive projects remain part of the wider portfolio, while the main public positioning is centered on AI and software roles.
+- Applied AI and AI Agent Reliability
+- AI Solutions / Solution Engineering
+- Conversational AI and workflow design
+- LLM evaluation and evidence-based QA
+- Python / FastAPI / PostgreSQL product work
+- TypeScript product and interactive systems
+
+Two current flagship products lead the portfolio:
+
+- **SINAMA — AI Agent Reliability Lab**
+- **Merge Rush: Tiny Factory**
+
+## Portfolio Architecture V2
+
+Current product truth is centralized in `portfolio-data.js` and consumed by `portfolio-v2.js`.
+
+This registry powers or synchronizes:
+
+- Recruiter Mode V2
+- Role-specific recruiter deep links
+- Ajoop evidence answers
+- Build Log
+- Kaan Labs
+- SINAMA Evidence Explorer
+- Shared bilingual V2 copy
+
+See [`PORTFOLIO_ARCHITECTURE.md`](PORTFOLIO_ARCHITECTURE.md) before adding new flagship facts or recruiter evidence.
+
+## Runtime boot sequence
+
+`script.js` is now a small compatibility bootloader rather than the monolithic application runtime.
+
+On pages already migrated to V2 it keeps parser order intact and loads the legacy runtime between the registry and the explicit V2 runtime:
+
+`portfolio-data.js → script.js bootloader → legacy-script.js → portfolio-v2.js`
+
+On older pages that still include only `script.js`, the bootloader injects the full stack automatically:
+
+`portfolio-data.js → legacy-script.js → portfolio-v2.js`
+
+It also injects `portfolio-v2.css` when a legacy page does not already include it. This keeps Recruiter Mode, Ajoop and current portfolio evidence synchronized across older case studies, certificates, 404 and mini-game pages without rewriting every HTML file at once.
 
 ## Main pages
 
-- `index.html` — Landing page, focus areas, recent experience, selected work and contact hub
-- `works.html` — Filterable project catalog
-- `games.html` — Interactive web games catalog
-- `adventure.html` — Career Adventure mini game
-- `joyday-paint.html` — Joyday Action Painting experience
-- `ai-flow-puzzle.html` — n8n-inspired chatbot workflow puzzle
-- `project-detail.html` — Dynamic project detail page
-- `blog.html` — Professional experience timeline
-- `single-work.html` — Training and course certificate gallery
-- `about.html` — Professional profile and capability map
-- `request.html` — Project request form
-- `script.js` — Navigation, EN/TR translation, Ajoop, Recruiter Mode, Command Palette and dynamic project content
-- `style.css` — Responsive site styling
+- `index.html` — concise landing page led by flagship evidence
+- `works.html` — curated professional project catalog
+- `sinama-case-study.html` — Applied AI / reliability flagship case study + evidence explorer
+- `merge-rush-case-study.html` — game / interactive flagship case study + QA evidence
+- `blog.html` — professional experience timeline
+- `about.html` — profile and capability map
+- `request.html` — structured project inquiry
+- `now.html` — living product / engineering build log
+- `labs.html` — technical experiments separated from the main professional narrative
+- `games.html` — active game product + playable browser work
+- `single-work.html` — training and certificates
+- `project-detail.html` — dynamic archive project detail route (`noindex`)
+
+## Core files
+
+- `portfolio-data.js` — source of truth for current flagship/project/recruiter/build data
+- `portfolio-v2.js` — V2 runtime and evidence surfaces
+- `portfolio-v2.css` — V2 component styling
+- `script.js` — global compatibility bootloader
+- `legacy-script.js` — preserved pre-V2 global runtime: navigation, theme, historical translations, dynamic archive details, chatbot shell, command palette, request/game utilities and other established interactions
+- `style.css` — global styling primitives and legacy component styles
+
+`flagship-copy.js` has been retired; its responsibilities moved to the registry + V2 runtime.
+
+## Recruiter deep links
+
+- `/?role=applied-ai`
+- `/?role=solution-engineering`
+- `/?role=software`
+- `/?role=game`
+
+A valid role parameter selects the matching evidence profile and opens Recruiter Mode.
+
+## Ajoop scope
+
+Ajoop remains deterministic and portfolio-focused. V2 grounds its current SINAMA, Merge Rush, role-fit and build-status answers in the central registry. It is **not** presented as a live LLM/RAG assistant in this release.
 
 ## Resume
 
-All public resume actions use one centralized resume URL in `script.js`:
+The public resume URL is mirrored in the registry and in the preserved legacy runtime:
 
-```js
-const resumeLink = "https://drive.google.com/file/d/1eERVaYoP-ICuP3xfbzpaDaCo5amwqA8u/view?usp=sharing";
-```
+`https://drive.google.com/file/d/1eERVaYoP-ICuP3xfbzpaDaCo5amwqA8u/view?usp=sharing`
 
-Public buttons use labels such as **View Resume** or **Download Resume**. Role-specific application CVs are intentionally not exposed on the website.
+Role-specific private application CVs are intentionally not exposed.
 
-## Current links
+## QA
 
-- Portfolio: [kaanbalci.com](https://kaanbalci.com)
-- Resume: [View Resume](https://drive.google.com/file/d/1eERVaYoP-ICuP3xfbzpaDaCo5amwqA8u/view?usp=sharing)
-- LinkedIn: [linkedin.com/in/balcikaan](https://www.linkedin.com/in/balcikaan/)
-- GitHub: [github.com/UAJOP](https://github.com/UAJOP)
-- Email: [kaanb8776@gmail.com](mailto:kaanb8776@gmail.com)
+GitHub Actions Site Preflight checks:
+
+- JavaScript syntax for every root `.js` file
+- HTML validation
+- spelling
+- mobile WCAG 2 AA with Pa11y
+- Lighthouse performance / accessibility / best practices / SEO
+- broken links
+
+V2 adds `labs.html` and `now.html` to automated accessibility and Lighthouse coverage.
 
 ## Deployment
 
 The repository is configured for GitHub Pages with the custom domain in `CNAME`.
-
-Keep the existing `assets` directory unchanged when replacing the updated code files, because the HTML pages reference the current portfolio images, certificates and logos from that directory.