fix: harden resume generation and anonymize public examples

.env.example

@@ -1,2 +1,5 @@
 # Arete currently has no required secrets.
 # Future AI/provider integrations must document required variables here.
+
+# Optional: write LaTeX only (removes an older PDF at the same output path).
+# ARETE_SKIP_PDF_COMPILE=1

.github/workflows/ci.yml

@@ -15,12 +15,12 @@ jobs:
           node-version-file: .nvmrc
       - run: corepack enable
       - run: pnpm install --frozen-lockfile
+      - run: pnpm audit
       - run: pnpm format:check
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test:coverage
       - run: pnpm build
       - run: pnpm arete validate --source examples/candidate.example.md
-      - run: pnpm arete build --source examples/candidate.example.md --out dist/example
-        env:
-          ARETE_SKIP_PDF_COMPILE: "1"
+      - run: sudo apt-get update && sudo apt-get install -y poppler-utils
+      - run: pnpm test:pdf

.gitignore

@@ -6,10 +6,11 @@ coverage/
 !.env.example
 private/
 *.private.md
+/candidate.md
+*.tex
 *.aux
 *.fls
 *.fdb_latexmk
 *.log
 *.out
 *.pdf
-!examples/*.pdf

README.md

@@ -6,7 +6,7 @@ The project is CLI-first and deliberately small: no web app, account system, res
 
 ## Status
 
-Greenfield bootstrap in progress. The current implementation provides the initial CLI, Markdown candidate parsing, validation, deterministic resume composition, LaTeX rendering, and npm-managed PDF compilation.
+The CLI supports guided Markdown input, validation, deterministic resume composition, and one-page A4 LaTeX/PDF generation. See [the resume audit](docs/RESUME_AUDIT.md) for recruiting-source evidence, confirmed repairs, and limitations. No employer endorsement or universal ATS compatibility is claimed.
 
 ## Goals
 
@@ -24,12 +24,17 @@ corepack enable
 pnpm install
 pnpm build
 
-pnpm arete init --output candidate.md
-pnpm arete validate --source candidate.md
-pnpm arete build --source candidate.md --out dist/resume
+pnpm arete init --output private/candidate.md
+# Fill in your facts and remove unused placeholder sections before validation.
+pnpm arete validate --source private/candidate.md
+pnpm arete build --source private/candidate.md --out dist/resume
 ```
 
-`arete build` writes `resume.tex` and compiles `resume.pdf` through the npm-managed LaTeX compiler installed by `pnpm install`. System `latexmk` or `pdflatex` are used only as fallbacks. English is the default locale; use `--locale pt-BR` for localized section labels and dates currently supported by the MVP.
+`arete build` writes `resume.tex` and compiles `resume.pdf` through the npm-managed LaTeX compiler installed by `pnpm install`. The binary runs without a shell in an isolated temporary directory. System `tectonic`, `latexmk`, or `pdflatex` are used when the bundled binary is unavailable. English is the default locale; use `--locale pt-BR` for localized section labels and dates currently supported by the MVP.
+
+`init` refuses to overwrite an existing file. The supplied example is explicitly fictional; private sources and generated output should remain in ignored paths. This repository does not provide an automatic anonymous-resume exporter.
+
+Use the generated template's exact section names and field positions. Experience dates accept `YYYY` or `YYYY-MM`, with `Present` for an ongoing role. Put experience in reverse chronological order and list your most relevant bullets first: source order is preserved, and the CLI warns when fixed list budgets omit items. Content that still exceeds one page fails compilation. Locale changes affect labels and experience dates; they do not translate prose.
 
 ## Architecture
 
@@ -54,6 +59,9 @@ pnpm lint
 pnpm typecheck
 pnpm test:coverage
 pnpm build
+pnpm audit
+# Requires pdftotext (Poppler); builds real PDFs and tests text extraction.
+pnpm test:pdf
 ```
 
 See `docs/` for the product spec, architecture, testing strategy, security and privacy model, content policy, LaTeX constraints, and ExecPlan workflow.

docs/ARCHITECTURE.md

@@ -4,12 +4,13 @@ Arete is a Node.js TypeScript CLI with a linear compiler pipeline.
 
 ## Pipeline
 
-1. Candidate Markdown is read from disk.
+1. Candidate Markdown is read from disk; a YAML-only front-matter parser validates metadata without executable engines.
 2. The parser extracts sections and repeated entities with source references.
 3. Runtime schemas validate parsed data into a canonical candidate model.
 4. The composer creates a resume model from canonical facts and build options.
-5. The LaTeX renderer escapes all candidate text, applies deterministic one-page source-order budgeting and the A4 reference style, and writes `resume.tex`.
-6. The compiler invokes the npm-managed LaTeX compiler first, then falls back to `latexmk` or `pdflatex`, to produce `resume.pdf`.
+5. The LaTeX renderer escapes all candidate text, applies deterministic one-page source-order budgeting and the single-column A4 style, and writes `resume.tex`.
+6. The compiler resolves the npm-managed Tectonic runtime and invokes it with an argument array in a unique temporary directory. If unavailable, discovery falls back to system `tectonic`, `latexmk`, or `pdflatex`. The npm shell wrapper is never invoked.
+7. `pdf-lib` validates the resulting page tree and requires exactly one page before publishing `resume.pdf`. Compilation/skip removes stale PDF output; intermediate files are cleaned on success or failure.
 
 ## Boundaries
 
@@ -22,7 +23,7 @@ Arete is a Node.js TypeScript CLI with a linear compiler pipeline.
 
 ## Provenance
 
-Canonical facts include `SourceRef` values with file, section, and line information where practical. Resume items carry provenance references to the canonical fields they came from. This keeps generated claims inspectable and testable without a heavyweight claim database.
+Canonical facts include `SourceRef` values with file, section, and original-file line information (including front matter). Resume items carry provenance references to the canonical fields they came from. This keeps generated claims inspectable and testable without a heavyweight claim database.
 
 ## STAR Evidence
 
@@ -34,7 +35,7 @@ Candidate source files should capture STAR evidence for important work:
 - Result;
 - Evidence status.
 
-The current MVP renders only bullet lines and supported structured fields. STAR evidence notes are still valuable source material for future composition and AI-assisted editing, but they must never create a factual claim unless the underlying candidate source supports it.
+The current MVP renders only bullet lines before the STAR evidence marker and supported structured fields. Unknown/duplicate sections and malformed positional records are rejected. STAR evidence notes are still valuable source material for future composition and AI-assisted editing, but they must never create a factual claim unless the underlying candidate source supports it.
 
 ## Localization
 

docs/LATEX.md

@@ -10,19 +10,24 @@ The resume template prioritizes ATS readability, selectable text, restrained typ
 - Escape all candidate-provided text.
 - Keep generated artifacts outside source control by default.
 - Fit the generated resume on one A4 page. If rendered content exceeds one page, compilation must fail rather than silently producing a multi-page resume.
-- Follow the William Augusto reference resume style: centered name/contact header, compact black-and-white typography, section headings with thin rules, right-aligned location/date metadata, and dense ATS-readable bullets.
+- Follow the single-column resume style: centered name/contact header, compact black-and-white typography, section headings with thin rules, right-aligned location/date metadata, and dense ATS-readable bullets.
 - Apply deterministic one-page budgeting for long lists. Skills, bullets, and technology lists preserve candidate source order and may omit lower-priority overflow items, but rendered claims must never be rewritten into unsupported facts.
 
 ## Toolchain
 
-`arete build` first writes `resume.tex`, then tries:
+`arete build` writes `resume.tex`, then discovers a compiler in this order:
 
-1. the npm-managed `node-latex-compiler` dependency, which provides Tectonic through npm optional runtime packages;
-2. `latexmk -pdf -interaction=nonstopmode -halt-on-error resume.tex`;
-3. `pdflatex -interaction=nonstopmode -halt-on-error resume.tex`.
+1. Tectonic runtime binary supplied by `node-latex-compiler` optional npm packages;
+2. system `tectonic`;
+3. system `latexmk`;
+4. system `pdflatex` (two passes to resolve page references).
 
-The primary path is intentionally installed by `pnpm install` and does not require Linux distribution packages such as `texlive`, `latexmk`, or `pdflatex`. If no compiler path is available, the command reports the missing environment requirement and leaves the `.tex` artifact intact.
+Arete resolves the npm binary without invoking the dependency's shell-based compilation wrapper. All processes use argument arrays and unique temporary directories. Tectonic uses `--untrusted`; system engines disable shell escape, and `latexmk` ignores RC files. TeX file access is restricted where supported. Each process has a 120-second timeout and bounded captured diagnostics. Compilation errors remain errors; fallback discovery applies when binaries are absent, not to conceal invalid LaTeX.
+
+`pdf-lib` reads the actual page tree, including compressed objects, and requires exactly one page. Only validated output is copied to the destination. Stale PDFs are removed when compilation starts or is explicitly skipped. The `.tex` file remains for diagnosis. First-use Tectonic may download TeX support files and therefore require network access.
+
+Body text uses the declared 10pt size. List budgets preserve the first 24 skills, 4 bullets/14 technologies per experience, and 2 bullets/8 technologies per project. The CLI warns about each omitted group. These are item limits, not a measurement-based layout algorithm; long text can still exceed one page and must be edited by the candidate.
 
 ## Smoke Testing
 
-CI should run the npm-managed compiler against the example resume. When practical, use `pdftotext` as a pragmatic signal that the PDF contains extractable text.
+After `pnpm build`, run `pnpm test:pdf` with `pdftotext` from Poppler on PATH. This compiles the synthetic example concurrently in English and Portuguese, asserts one-page A4 dimensions, checks extracted contact/facts and section order, and verifies actual oversized content is rejected. CI installs Poppler and runs this command without the skip flag.

docs/PROJECT_SPEC.md

@@ -54,11 +54,21 @@ The MVP is done when the CLI can create a template, validate a sanitized example
 
 ## STAR Method
 
-Arete uses STAR because recruiters and interviewers respond better to evidence-backed achievements than generic responsibility lists.
+Arete uses STAR as a structured evidence-gathering aid for writing concrete contributions and accomplishments. This does not imply endorsement of a specific template by an employer; see `docs/RESUME_AUDIT.md` for primary recruiting sources.
 
 - Situation: the context, problem, or opportunity.
 - Task: what the candidate was responsible for.
 - Action: what the candidate personally did.
 - Result: what changed afterward.
 
 The generated resume should usually compress STAR into one concise bullet. If the Result is unknown, the bullet must still be truthful and should avoid fake metrics or inflated impact.
+
+## Source Contract And Output Limits
+
+- Front matter is YAML with `schemaVersion: 1` and optional supported locale (`en`, `pt-BR`, or the `pt` alias).
+- Section names follow the generated template exactly; unknown or duplicate sections are errors.
+- Identity requires a name and valid email. `init` never overwrites an existing file.
+- Pipe-separated fields retain empty positions. Experience uses four positions, with an optional empty location; start/end dates accept `YYYY` or `YYYY-MM`, and end also accepts `Present`.
+- Bullets after the `STAR evidence notes:` marker are notes, not resume claims.
+- Source order is preserved. Fixed list budgets may omit later items with CLI warnings; the final PDF must be one page.
+- `pt-BR` changes template labels and experience-date display; candidate prose is not translated.