From 012b4b08c7d09af3090da33ed649e80b59d0d3fa Mon Sep 17 00:00:00 2001
From: Codex <codex@infrafabric.local>
Date: Thu, 1 Jan 2026 17:30:19 +0000
Subject: [PATCH] Expand README with tree and usage guide

---
 README.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 93 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index cf493d4..b6d5a61 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,98 @@
-# Ahmet Kerem Özbay — CV Research Pack
+# Ahmet Kerem Özbay — CV Pack (Research + Final Drafts)
 
-Contents:
-- `source/` — original CV PDF provided as input.
-- `artifacts/cv_research/` — research corpus, collected job ads (JSON + HTML), debate transcript, CV bible, and drafted CV.
+This repository contains:
+- The original CV provided as input (`source/`).
+- Research notes + job ad corpus (`artifacts/cv_research/`).
+- A refined 1-page CV in **Markdown**, plus a **DOCX** export.
 
-Key files:
-- `artifacts/cv_research/Ahmet_Kerem_Ozbay_CV_EN_v2.md`
+## Quick start (what to open first)
+
+If you only read 3 things:
+- `artifacts/cv_research/Ahmet_Kerem_Ozbay_CV_EN.md` (current English CV, formatted to export to **1 PDF page**)
+- `artifacts/cv_research/Ahmet_Kerem_Ozbay_CV_EN.docx` (Word version)
+- `artifacts/cv_research/cv_bible_ahmet_kerem_ozbay.md` (rules to keep the CV consistent and easy to tailor)
+
+## How to export PDF (Forgejo)
+
+Forgejo can render Markdown as a PDF via a URL parameter.
+
+1) Open the Markdown CV:
+   - `artifacts/cv_research/Ahmet_Kerem_Ozbay_CV_EN.md`
+2) Use the “raw PDF” export:
+   - Append `?format=pdf` to the raw file URL.
+
+Note: the PDF renderer can introduce page breaks depending on line wrapping. The current CV is intentionally formatted (collapsed sections) to keep it on **one page**.
+
+## What this pack is for (honest constraints)
+
+- This is a **presentation and targeting** pack (CV + job matching).
+- It does **not** grant work authorization. If a role requires sponsorship, disclose it early and keep the story consistent.
+
+## Repository layout (file tree)
+
+```text
+.
+├── README.md
+├── artifacts
+│   └── cv_research
+│       ├── Ahmet_Kerem_Ozbay_CV_EN.docx
+│       ├── Ahmet_Kerem_Ozbay_CV_EN.md
+│       ├── cv_bible_ahmet_kerem_ozbay.md
+│       ├── cv_sector_best_practices.md
+│       ├── debate_transcript.md
+│       ├── job_ads_summary.md
+│       ├── job_ads/
+│       │   ├── *.json
+│       │   └── html/*.html
+│       └── samples/*.html
+└── source
+    └── AHMET_KEREM_OZBAY_CV.pdf
+```
+
+## What each key file does
+
+### CV drafts (the “deliverables”)
+- `artifacts/cv_research/Ahmet_Kerem_Ozbay_CV_EN.md`
+  - The current English CV.
+  - Formatted for Forgejo PDF export to stay **single-page**.
+- `artifacts/cv_research/Ahmet_Kerem_Ozbay_CV_EN.docx`
+  - Word export of the same CV content.
+
+### Guidance (how to keep improving without breaking format)
 - `artifacts/cv_research/cv_bible_ahmet_kerem_ozbay.md`
+  - Rules for structure, section ordering, wording, and tailoring.
+  - Includes a checklist for customizing per job ad.
+
+### Research + decision trail (why the CV is shaped this way)
 - `artifacts/cv_research/debate_transcript.md`
-- `artifacts/cv_research/job_ads_summary.md`
+  - A simulated but structured debate between HR, a recruiter, and 3 example employers.
+  - Used to validate which edits are realistic and which are likely to be rejected.
 - `artifacts/cv_research/cv_sector_best_practices.md`
+  - Best-practice patterns extracted from comparable warehouse/logistics CV guides.
+
+### Job ads (for tailoring and keyword mirroring)
+- `artifacts/cv_research/job_ads_summary.md`
+  - Index of collected job ads + links + local file pointers.
+- `artifacts/cv_research/job_ads/*.json`
+  - Raw structured job-ad payloads (search index hits).
+- `artifacts/cv_research/job_ads/html/*.html`
+  - Downloaded job-ad pages for offline review.
+
+### Original input
+- `source/AHMET_KEREM_OZBAY_CV.pdf`
+  - The original CV PDF that was used as the base.
+
+## How to update the CV without breaking the 1-page PDF
+
+Recommended process:
+1) Edit `artifacts/cv_research/Ahmet_Kerem_Ozbay_CV_EN.md` (keep the content truthful).
+2) Re-export PDF and confirm it remains **1 page**.
+3) If a section spills to page 2, compress by:
+   - collapsing bullets into a single line separated by `•`
+   - merging low-priority headings into a combined line (as currently done)
+4) Regenerate DOCX if needed (Word formatting can be adjusted independently).
+
+## Notes on scope and privacy
+
+- Don’t add passwords, tokens, or private IDs to this repo.
+- The job-ad HTML/JSON is included for tailoring; if you share this repo externally, consider removing `artifacts/cv_research/job_ads/` and `artifacts/cv_research/samples/`.