docs: highlight grounded agent architecture

Author: LEANDERANTONY

README.md

@@ -4,33 +4,71 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Live App](https://img.shields.io/badge/Live%20App-Vercel-2563eb?logo=vercel&logoColor=white)](https://job-application-copilot.xyz/)
 
-AI Job Application Agent is a Vercel-hosted Next.js workspace with a FastAPI backend for resume parsing, JD review, grounded agentic tailoring, and exportable job application documents.
+AI Job Application Agent is a grounded resume-tailoring product: a five-stage agent pipeline that turns a source resume and job description into an evidence-backed tailored resume and cover letter.
+
+The core differentiator is grounded review. The pipeline is designed to detect and correct unsupported claims before export, so tailoring can emphasize the candidate's strongest relevant evidence without inventing skills or experience.
+
+![Agentic workflow](docs/screenshots/agentic_workflow.jpg)
 
 Live landing page: https://job-application-copilot.xyz
 
 Workspace app: https://app.job-application-copilot.xyz
 
-## Product Flow
+## Agent Pipeline
+
+The workflow runs through `ApplicationOrchestrator` with progress callbacks, per-stage duration logging, JSON-contracted agent outputs, and deterministic fallback if assisted generation is unavailable.
+
+1. `FitAgent` compares the candidate profile against the job description.
+2. `TailoringAgent` rewrites the deterministic baseline into role-specific resume guidance.
+3. `ReviewAgent` checks grounding, reports unsupported claims, and returns corrected tailoring when repairs are possible.
+4. `ResumeGenerationAgent` builds the final tailored resume artifact from the reviewed output.
+5. `CoverLetterAgent` runs only after review approval and creates a role-specific cover letter.
+
+Each agent follows the same operating shape: deterministic baseline first, LLM-assisted refinement second, structured JSON output, and grounded fallback behavior when assisted execution is unavailable.
+
+## Grounding And Fallbacks
+
+- Deterministic services build the candidate profile, JD summary, fit analysis, and first-pass tailored draft before the agent layer runs.
+- `ReviewAgent` returns `grounding_issues`, `unresolved_issues`, `revision_requests`, and an optional `corrected_tailoring` payload.
+- The orchestrator uses `corrected_tailoring` as the downstream source of truth when review repairs the draft.
+- Cover-letter generation is gated on review approval.
+- The fallback review path checks whether the output references missing hard skills that are not evidenced in the source profile.
 
-1. Sign in with Google
-2. Upload a resume
-3. Search jobs, import a supported posting, or paste a JD manually
-4. Review the JD summary
-5. Run the agentic analysis
+## Prompt And Runtime Discipline
+
+- Prompt builders compact large JSON sections through escalating string and list caps before falling back to a section summary.
+- Prompt metadata records estimated input size, compacted section count, compacted labels, and budget mode.
+- The OpenAI wrapper routes by task, tracks usage, enforces quota checks, records response metadata, and retries incomplete JSON responses with a higher output budget when appropriate.
+
+## Product Surface
+
+1. Sign in with Google through Supabase-backed auth
+2. Upload a resume and build a normalized candidate profile
+3. Search Greenhouse and Lever boards, import a supported posting, or paste a JD manually
+4. Review a structured JD summary
+5. Run the grounded agentic workflow
 6. Review the tailored resume and cover letter
 7. Ask grounded follow-up questions in the workspace assistant
-8. Export Markdown or PDF documents
+8. Export Markdown or WeasyPrint-backed PDF documents
 
 ## Stack
 
 - Next.js frontend in `frontend/`
 - FastAPI backend in `backend/`
-- Shared Python workflow and builders in `src/`
+- Shared Python workflow, agents, builders, and services in `src/`
 - Supabase for Google auth, quota tracking, saved workspaces, and saved jobs
+- Greenhouse and Lever job-source clients with matching and registry layers
 - OpenAI Responses API for assisted generation
 - WeasyPrint-backed PDF export pipeline
 - Docker Compose + Caddy deployment bundle in `deploy/vps/`
 
+## Engineering Notes
+
+- 37 focused Python test files cover parsing, normalization, fitting, tailoring, orchestration, builders, exports, auth, quotas, persistence, and backend routes.
+- 12 ADRs in `docs/adr/` record product and architecture decisions, including the Streamlit-first to Next.js + FastAPI transition.
+- Architecture details live in [docs/architecture.md](docs/architecture.md).
+- Deployment notes live in [docs/next-fastapi-transition.md](docs/next-fastapi-transition.md).
+
 ## Local Development
 
 Run the backend:
@@ -78,5 +116,3 @@ LEVER_SITE_NAMES=dnb,plaid,mistral
 - `app.job-application-copilot.xyz` -> Vercel frontend
 - `api.job-application-copilot.xyz` -> VPS FastAPI backend
 - `deploy/vps/` -> Docker Compose + Caddy bundle for the backend stack
-
-Transition notes and deployment details live in [docs/next-fastapi-transition.md](docs/next-fastapi-transition.md).

docs/adr/ADR-010-single-pass-review-corrections-and-task-tuned-model-budgets.md

@@ -9,9 +9,9 @@ Accepted
 The earlier supervised workflow had grown into a more expensive sequence than the product needed:
 
 - `ProfileAgent` and `JobAgent` were generating summaries that mostly restated deterministic candidate and JD structure already available elsewhere in the system
-- the orchestrator ran a bounded revision loop that resent tailoring, strategy, and review through another full pass when review rejected the first draft
+- the orchestrator ran a bounded revision loop that resent tailoring and review through another full pass when review rejected the first draft
 - Review was functioning as both a gate and a revision trigger, but the product goal had shifted toward direct grounded correction rather than repeated full-pipeline iteration
-- real runtime logs showed that the second tailoring + strategy + review pass was one of the largest contributors to total latency
+- real runtime logs showed that the second tailoring + review pass was one of the largest contributors to total latency
 - the final high-trust stages were worth more model budget than the early summarization stages, but the routing defaults had not yet been tightened around that reality
 
 At the same time, the product still needed:
@@ -29,16 +29,16 @@ The accepted workflow is:
 
 1. `fit`
 2. `tailoring`
-3. `strategy`
-4. `review`
-5. `resume_generation`
+3. `review`
+4. `resume_generation`
+5. `cover_letter`
 
 Implementation details:
 
 1. remove live `ProfileAgent` and `JobAgent` execution from the active orchestrator path
 2. keep deterministic `CandidateProfile`, `JobDescription`, `FitAnalysis`, and `TailoredResumeDraft` as the source-of-truth inputs
-3. make Review return direct corrected tailoring and strategy outputs when repairs are straightforward
-4. stop rerunning the entire tailoring / strategy / review chain after review feedback
+3. make Review return direct corrected tailoring output when repairs are straightforward
+4. stop rerunning the entire tailoring / review chain after review feedback
 5. define review approval in terms of the final corrected state, not only the cleanliness of the incoming draft
 6. route earlier cheaper stages to cheaper reasoning levels than the final grounding stages
 7. tune output-token caps by observed usage instead of using one oversized default for every task
@@ -47,27 +47,27 @@ The current routing defaults following this decision are:
 
 - `fit`: `gpt-5-mini-2025-08-07` with `low` reasoning and a 1600-token output cap
 - `tailoring`: `gpt-5-mini-2025-08-07` with `medium` reasoning and a 3200-token output cap
-- `strategy`: `gpt-5-mini-2025-08-07` with `low` reasoning and a 1500-token output cap
 - `review`: `gpt-5.4` with `medium` reasoning and a 4000-token output cap
 - `resume_generation`: `gpt-5.4` with `medium` reasoning and a 3000-token output cap
+- `cover_letter`: `gpt-5.4` with `medium` reasoning and a 3000-token output cap
 
 ## Alternatives Considered
 
-### 1. Keep the full Profile + Job + Fit + Tailoring + Strategy + Review + Resume Generation stack
+### 1. Keep the full Profile + Job + Fit + Tailoring + Review + Resume Generation stack
 
 Rejected because Profile and Job were not adding enough unique value relative to the deterministic data they were summarizing, while still costing additional sequential model latency.
 
 ### 2. Keep the revision loop but reduce model size only
 
 Rejected because the largest avoidable cost was architectural: repeated full-pipeline passes. Model tuning alone would not remove that structural latency.
 
-### 3. Remove Review entirely and trust Tailoring / Strategy output directly
+### 3. Remove Review entirely and trust Tailoring output directly
 
 Rejected because Review is still the main grounding defense against unsupported claims, inferred tenure, and overstated tooling experience.
 
 ### 4. Lower every stage to the same cheapest reasoning tier
 
-Rejected because the stages do not have the same risk profile. Review and final resume generation justify more careful reasoning than early fit and strategy summarization.
+Rejected because the stages do not have the same risk profile. Review and final resume generation justify more careful reasoning than early fit and tailoring guidance.
 
 ## Consequences