TechImmigrants · SaharPak · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026
diff --git a/.claude/skills/cv-evaluation/SKILL.md b/.claude/skills/cv-evaluation/SKILL.md
@@ -5,9 +5,10 @@ description: Evaluate a resume against the CV Builder rubric and return a scored
 
 # CV Evaluation
 
-Run a resume through the same four-step evaluation the hosted product uses,
-entirely locally. Everything you need lives in this repo — read the source, don't
-guess.
+Run a resume through the same four-step evaluation the local MVP uses,
+entirely on your machine via your own Claude Code. There is no hosted
+version of this product; everything you need lives in this repo — read
+the source, don't guess.
 
 ## Inputs
 
@@ -21,7 +22,7 @@ guess.
    text to produce a structured `Resume`.
 2. **Detect archetype.** Match the resume against the role archetypes in
    `packages/intelligence/src/archetypes/`. Pick the best fit; default to
-   Software Engineer when there's no clear signal. See [archetypes](./archetypes.md).
+   Backend Engineer when there's no clear signal. See [archetypes](./archetypes.md).
 3. **Score.** Apply `packages/prompts/prompts/score.md` with the detected
    archetype's weights and the rubric. See [rubric](./rubric.md) and
    [scoring](./scoring.md). Surface **at least 3** issues, each quoting the exact

diff --git a/README.md b/README.md
@@ -26,10 +26,10 @@ Good CV tools are expensive. Many job seekers — especially immigrants, career
 ```
 ┌──────────┐     ┌──────────────┐     ┌──────────────┐
 │  Your CV │ ──▶ │  CV Builder  │ ──▶ │ Score: 4.2/5 │
-└──────────┘     │   Engine     │     │ 3 rewrites   │
-┌──────────┐     │              │     │ 5 issues     │
-│    JD    │ ──▶ │  (6 scoring  │     │ Keywords gap │
-│(optional)│     │  dimensions) │     │ Tailored CV  │
+└──────────┘     │   Engine     │     │ Issues       │
+┌──────────┐     │              │     │ Strengths    │
+│    JD    │ ──▶ │  (6 scoring  │     │ ATS verdict  │
+│(optional)│     │  dimensions) │     │ Archetype    │
 └──────────┘     └──────────────┘     └──────────────┘
 ```
 
@@ -71,7 +71,9 @@ pnpm --filter @cv-builder/cli start archetypes
 
 ### Power User — run it with Claude Code
 
-Clone the repo, open [Claude Code](https://claude.com/claude-code) at the root, and run `/evaluate-cv ./your-resume.pdf`. The evaluation runs entirely on your machine with your own agent — no server, no account, nothing leaves your computer. No build needed.
+Clone the repo, open [Claude Code](https://claude.com/claude-code) at the root, and run `/evaluate-cv ./your-resume.md`. The evaluation runs entirely on your machine with your own agent — no server, no account, nothing leaves your computer. No build needed.
+
+Claude Code can also read PDF and DOCX inputs natively, so `/evaluate-cv ./your-resume.pdf` works as long as the file is on your machine.
 
 See [apps/cli/README.md](apps/cli/README.md) for the full guide.
 

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -5,6 +5,19 @@ open for grabs**. For the **vision** (v0.1, v0.2, v0.3), see the
 [README Roadmap section](README.md#roadmap). This file is the **current state**
 — what maintainers and contributors are doing this week and next.
 
+> **Status note — partially stale.** As of the post-PR #87 release, all v0.1
+> MVP sprint items have shipped on `main` (see
+> [`docs/MVP_RELEASE_STATUS.md`](docs/MVP_RELEASE_STATUS.md) for the
+> current MVP snapshot). The "🚧 In progress" list below was last
+> refreshed before that release; the items labelled as open have either
+> merged already or are no longer accurate. Treat this file as a planning
+> draft for the **next** sprint, not a description of today's state.
+> Before picking up an item, search the issue tracker — it may already
+> be shipped.
+>
+> *Last refreshed: 2026-06-22. Next refresh: after the next planning
+> call.*
+
 ## How to read this
 
 - 🚧 **In progress** — assigned, being worked on, has an ETA. Don't pick up
@@ -23,19 +36,18 @@ an acceptance bar reachable in a single sitting (1–4 hours).
 
 | Item | Owner | ETA | Notes |
 |---|---|---|---|
-| **Merge Phase-1 stack** — PRs [#68](https://github.com/TechImmigrants/cv-builder/pull/68), [#69](https://github.com/TechImmigrants/cv-builder/pull/69), [#70](https://github.com/TechImmigrants/cv-builder/pull/70), [#71](https://github.com/TechImmigrants/cv-builder/pull/71), [#72](https://github.com/TechImmigrants/cv-builder/pull/72), [#73](https://github.com/TechImmigrants/cv-builder/pull/73) | @saharpak | **ASAP** | Open since 2026-06-07. Currently the single biggest contributor-experience blocker — new contributors cloning `main` get a different product than what's documented. **Reviewer help urgently wanted — see below.** |
-| CV/JD input screen with file upload — PR [#76](https://github.com/TechImmigrants/cv-builder/pull/76) | unassigned | TBD | Two-column input screen. Depends on Phase-1 merge. |
-| CodeRabbit config expansion — PR [#75](https://github.com/TechImmigrants/cv-builder/pull/75) | unassigned | TBD | Per-package review guidance. |
-| Rule: flag outdated technologies — PR [#74](https://github.com/TechImmigrants/cv-builder/pull/74) | unassigned | TBD | Resolves issue [#53](https://github.com/TechImmigrants/cv-builder/issues/53). |
-| CI: web UI deploy previews on Cloudflare Pages — PR [#78](https://github.com/TechImmigrants/cv-builder/pull/78) | unassigned | TBD | Path-filtered workflow. |
+| **CI: web UI deploy previews to Cloudflare Pages** — PR [#78](https://github.com/TechImmigrants/cv-builder/pull/78) | unassigned | TBD | Path-filtered workflow. Requires `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` repo secrets. Tracked but out of this audit's scope. |
+| **CLI: color output** — PR [#37](https://github.com/TechImmigrants/cv-builder/pull/37) | unassigned | TBD | Author needs to rebase against post-merge `main`; CLI was refactored after PR #37 opened. Tracked but out of this audit's scope. |
 
-> ### ⚠️ Reviewer help wanted on Phase-1 PRs
+> ### ✅ Recently shipped (post-merge on `main`)
 >
-> The bottleneck isn't writing code — it's review bandwidth. If you have
-> **TypeScript + zod** experience and can review one of #68–#73, comment on
-> the PR. A 30-minute review from someone other than the maintainer unblocks
-> the entire stack and signals to the rest of the contributor base that the
-> project is moving.
+> Phase-1 stack (PRs [#68](https://github.com/TechImmigrants/cv-builder/pull/68)–[#73](https://github.com/TechImmigrants/cv-builder/pull/73)),
+> CV/JD input screen (PR [#76](https://github.com/TechImmigrants/cv-builder/pull/76)),
+> CodeRabbit config expansion (PR [#75](https://github.com/TechImmigrants/cv-builder/pull/75)),
+> outdated-technology rule (PR [#74](https://github.com/TechImmigrants/cv-builder/pull/74)),
+> no-code contribution paths and the MVP demo polish (PR [#85](https://github.com/TechImmigrants/cv-builder/pull/85),
+> PR [#87](https://github.com/TechImmigrants/cv-builder/pull/87)).
+> Full validation in [`docs/MVP_RELEASE_STATUS.md`](docs/MVP_RELEASE_STATUS.md).
 
 ---
 
@@ -55,9 +67,9 @@ scope. **Comment "I'll take this" on the issue to claim.**
 | Rule: flag outdated technologies | S | [#53](https://github.com/TechImmigrants/cv-builder/issues/53) | `good first issue`, `rules`. **PR #74 already in flight — check before starting.** |
 | Add per-dimension feedback strings to evaluator | S | [#48](https://github.com/TechImmigrants/cv-builder/issues/48) | `enhancement`, `core`. |
 | Fix: flag missing contact information | S | [#55](https://github.com/TechImmigrants/cv-builder/pull/55) | `core`. PR already open — needs review. |
-| New archetype: **AI Engineer** | M | (open issue) | Use the [New Archetype template](.github/ISSUE_TEMPLATE/new_archetype.md). Top priority for the 2026 market. |
-| New archetype: **AI Product Manager** | M | (open issue) | Top priority for the 2026 market. |
-| New archetypes: Backend / Frontend / DevOps | M each | (open issue) | Currently advertised in README but unimplemented. |
+| New archetype: **AI Engineer** | M | (open issue) | **Already shipped** as of the MVP — see README "Supported Role Archetypes". Use the [New Archetype template](.github/ISSUE_TEMPLATE/new_archetype.md) to suggest more roles. |
+| New archetype: **AI Product Manager** | M | (open issue) | **Already shipped** as of the MVP — see README "Supported Role Archetypes". |
+| New archetypes: Backend / Frontend / DevOps / QA / Data Engineer | M each | (open issue) | **Already shipped** as of the MVP. README lists eight built-in roles. |
 | Land CONTRIBUTING.md "no-code" section | S | (open issue) | The draft this file came from. |
 | Write `docs/faq.md` ("I got a bad score, what now?") | S | (open issue) | |
 | Write `docs/cli-troubleshooting.md` | S | (open issue) | |
@@ -85,9 +97,10 @@ scope. **Comment "I'll take this" on the issue to claim.**
 - **Suggest new items** — open an issue with the relevant label.
 - **Push a 🅿️ Parked item** — if you think something should be un-parked,
   open an issue with the `roadmap` label and the rationale.
-- **Help review Phase-1 PRs** — the single highest-leverage thing a
-  TypeScript-comfortable contributor can do this week.
+- **Help with the v0.2 backlog** — that's where the meaningful contributor
+  work lives now that v0.1 has shipped.
 
 ---
 
-*Last updated: 2026-06-22*
+*Last updated: 2026-07-02 (post-MVP release). The previous "Last updated"
+date of 2026-06-22 predates the MVP release and is no longer accurate.*
diff --git a/apps/cli/README.md b/apps/cli/README.md
@@ -19,15 +19,17 @@ tests or the web app.)
 Then, inside Claude Code:
 
 ```text
-/evaluate-cv ./my-resume.pdf
+/evaluate-cv ./my-resume.md
 ```
 
 Optionally add a job description as keyword context:
 
 ```text
-/evaluate-cv ./my-resume.pdf --jd ./job.md
+/evaluate-cv ./my-resume.md --jd ./job.md
 ```
 
+Claude Code can read PDF and DOCX inputs natively, so `/evaluate-cv ./my-resume.pdf` also works as long as the file is on your machine. The local web UI and CLI in this repo parse `.md` and `.txt` only — see [docs/LOCAL_DEMO.md](../../docs/LOCAL_DEMO.md).
+
 No resume handy? Run `/setup-profile` and it'll help you assemble one.
 
 ## What you get

diff --git a/apps/web-ui/README.md b/apps/web-ui/README.md
@@ -1,9 +1,18 @@
 # CV Builder Web
 
-This package contains the Next.js web app for **CV Builder**.
+This package contains the Next.js web app for **CV Builder** — a privacy-first
+local-only CV evaluator. The web UI runs the deterministic evaluator
+(`@cv-builder/core`) entirely in the browser; nothing is sent to a server.
 
-The current homepage is a simple landing screen for the product and replaces the
-default generated Next.js starter content.
+This is the **community MVP**: it scores an existing resume, it does not
+generate, tailor, or rewrite one. PDF parsing, hosted deployment, and rewrite
+suggestions are out of scope for this surface and tracked on the roadmap.
+
+## Routes (static export)
+
+- `/` — paste a CV (and optional JD), click Evaluate
+- `/results` — score, per-dimension bars, archetype, ATS verdict, issues, strengths
+- `/feedback` — community feedback guide with an anonymisation checklist
 
 ## Local development
 
@@ -20,12 +29,14 @@ Then open [http://localhost:3000](http://localhost:3000).
 | Command      | Purpose                    |
 | ------------ | -------------------------- |
 | `pnpm dev`   | Start the local dev server |
-| `pnpm build` | Build the production app   |
+| `pnpm build` | Build the production app (static export) |
 | `pnpm start` | Run the production build   |
 | `pnpm lint`  | Run lint checks            |
 
 ## Main files
 
-- `src/app/layout.tsx` - app shell and metadata
-- `src/app/page.tsx` - homepage
+- `src/app/layout.tsx` - app shell, theme provider, and metadata
+- `src/app/page.tsx` - homepage (paste form)
+- `src/app/results/page.tsx` - evaluation results view
+- `src/app/feedback/page.tsx` - feedback guide
 - `src/app/globals.css` - global styles
diff --git a/apps/web-ui/src/app/layout.tsx b/apps/web-ui/src/app/layout.tsx
@@ -14,8 +14,9 @@ const geistMono = Geist_Mono({
 });
 
 export const metadata: Metadata = {
-  title: "CV Builder",
-  description: "Build a tailored resume...",
+  title: "CV Builder — local MVP",
+  description:
+    "Privacy-first CV evaluator for tech professionals. Paste a resume, get a 0–5 score across six dimensions with prioritised fixes. Runs entirely in your browser; nothing is uploaded.",
 };
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -1,5 +1,20 @@
 # Architecture
 
+> **Status note — historical / aspirational document.** This file describes
+> the proposed v2 architecture (Fastify server, Telegram bot, LLM adapter
+> package, ingestion package, templates package, Tolgee i18n). It pre-dates
+> the MVP shipped on `main` as of the post-PR #87 release.
+>
+> The current MVP is a **deterministic, locally-running CV evaluator**. It
+> ships `packages/{schemas,intelligence,prompts,core,cli,eval}` and
+> `apps/{cli,web-ui}` only — no `server`, no `telegram` app, no `llm`,
+> `ingestion`, or `templates` package. PDF parsing, hosted deployment, and
+> rewriting are explicitly out of scope for this MVP.
+>
+> For the **current** product status, validation results, what is and is not
+> ready, read [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). Treat
+> this file as design context, not a description of the deployed product.
+
 ## Layout
 
 ```

diff --git a/docs/MVP_DEMO_PLAN.md b/docs/MVP_DEMO_PLAN.md
@@ -3,6 +3,18 @@
 > Goal: prepare the current CV Builder for a simple public demo.
 > Source: post-merge `main` at `6170aef`. PRs #37 and #78 not in scope.
 
+> **Status note — historical document.** This was the demo-readiness audit
+> written before the polish in PR #87 landed. Some items in the
+> "Current limitations" section below (misleading home copy, results page
+> missing issues, empty-state, FileUpload alert, visual bars, Node version
+> drift) were fixed in PR #87 and follow-up commits. The "demo is
+> local-only ready / cannot be shared publicly without deploying" verdict
+> still holds for the v0.1 release.
+>
+> For the **current** product status, validation results, and what is and
+> is not ready, read
+> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md).
+
 ## What currently works
 
 ### Web UI (`apps/web-ui/`)
@@ -51,8 +63,9 @@
 
 ### Prereqs
 
-- Node 22+ (matches the GitHub Actions workflow)
-- pnpm 9.15+ (`npm install -g pnpm@9.15.0`)
+See [docs/LOCAL_DEMO.md](./LOCAL_DEMO.md) for the current setup guide.
+Quick version: Node.js 20 or newer (matches `package.json`), pnpm 9.15+,
+`pnpm install`, then `pnpm dev`.
 
 ### One-time setup
 

diff --git a/docs/PHASE-1.md b/docs/PHASE-1.md
@@ -4,6 +4,25 @@
 **Target:** Ship MVP within 3 weeks of team alignment call
 **Status:** Planning
 
+> **Status note — historical document.** This is the original Phase 1 plan.
+> It was written before the MVP shipped. It describes `packages/llm`,
+> `packages/ingestion`, `packages/templates`, an `apps/server` (Fastify), an
+> `apps/telegram` bot, Tolgee i18n, and a hosted mode with rate limits —
+> none of which exist in the MVP that actually shipped on `main`.
+>
+> The shipped MVP is a **deterministic, locally-running CV evaluator** with
+> `packages/{schemas,intelligence,prompts,core,cli,eval}` and
+> `apps/{cli,web-ui}` only. The success criteria in this doc (Telegram bot,
+> hosted public URL, EN + FA locales, 3 evaluations/day rate limit) were
+> deferred. PDF parsing, hosted deployment, and rewriting are explicitly
+> out of scope.
+>
+> For the **current** product status, validation results, and what is and
+> is not ready, read
+> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). Treat this file
+> as the original planning document, not a description of the deployed
+> product.
+
 ---
 
 ## What We're Building

diff --git a/docs/POST_MERGE_VALIDATION.md b/docs/POST_MERGE_VALIDATION.md
@@ -3,6 +3,12 @@
 > Generated immediately after PR #85 merged into `main`.
 > All validation was run on the post-merge `main` branch.
 
+> **Status note — historical document.** This is the post-merge validation
+> report from PR #85, the 14-PR integration that put MVP foundations on
+> `main`. For the **current** post-merge status and validation results
+> after PR #87, read
+> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md).
+
 ## Merge commit
 
 | Item | Value |

diff --git a/docs/PR85_ROLLBACK_PLAN.md b/docs/PR85_ROLLBACK_PLAN.md
@@ -1,5 +1,15 @@
 # PR #85 Rollback Plan
 
+> **Status note — historical document.** This is the rollback plan drafted
+> before PR #85 (the 14-PR MVP integration) merged into `main`. The merge
+> was successful and permanent — every subsequent release-readiness check
+> passed. The safety tag `pre-pr85-main-backup-20260702` remains on
+> `origin` as a permanent rollback point. You do not need to act on this
+> doc unless you spot a regression pointing to that merge.
+>
+> For the **current** product status, read
+> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md).
+
 ## Pre-merge state captured
 
 - Tag: `pre-pr85-main-backup-20260702`

diff --git a/docs/PROPOSAL.md b/docs/PROPOSAL.md
@@ -1,5 +1,21 @@
 # Proposal — CV Builder v2
 
+> **Status note — historical / aspirational document.** This file is the
+> original v2 proposal written before the MVP shipped. It describes
+> `packages/llm`, `packages/ingestion`, `packages/templates`, an
+> `apps/server` (Fastify), an `apps/telegram` bot, and Tolgee i18n — none
+> of which exist in the current MVP on `main`.
+>
+> The current MVP is a **deterministic, locally-running CV evaluator** that
+> ships `packages/{schemas,intelligence,prompts,core,cli,eval}` and
+> `apps/{cli,web-ui}` only. There is no hosted tier, no Telegram surface,
+> and no LLM adapter in this repo.
+>
+> For the **current** product status, validation results, and what is and
+> is not ready, read
+> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). Treat this file
+> as a historical design note, not a description of the deployed product.
+
 ## Goal
 
 A TypeScript-only, monorepo CV evaluator and builder. v1 ships **evaluation**: paste a resume + JD, get a typed, evidence-grounded score against a role archetype.

diff --git a/docs/PR_CLEANUP_HANDOFF.md b/docs/PR_CLEANUP_HANDOFF.md
@@ -4,6 +4,12 @@
 > This document is the single source of truth for what happened, why, and
 > what the next maintainer should know.
 
+> **Status note — historical document.** This is the report from the
+> post-PR #85 cleanup phase (the 14-PR integration that landed MVP
+> foundations on `main` and was finalised by PR #87's MVP release
+> polish). It is kept for context. For the **current** product status,
+> read [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md).
+
 ## TL;DR
 
 - 20 open PRs reviewed

diff --git a/docs/REMAINING_PRS_PLAN.md b/docs/REMAINING_PRS_PLAN.md
@@ -4,6 +4,14 @@
 > Sourced from `gh pr view`, `gh pr diff`, and test merges against the
 > post-merge `main` at `5b59014`.
 
+> **Status note — historical document.** This is the action plan for
+> PR #37 (CLI color) and PR #78 (Cloudflare Pages previews) drafted
+> immediately after PR #85 merged. The factual state of those two PRs as
+> of today is the same — both remain OPEN and are intentionally
+> untouched. For the **current** product status and what's still tracked
+> as out-of-scope (hosted deployment, CLI cosmetic enhancements), read
+> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md).
+
 ## TL;DR
 
 | PR  | Title                                 | State       | Verdict                                                                    | Handled by                |