resumectl 0.0.0-stage → 0.1.0

package/GLOSSARY.md

@@ -0,0 +1,19 @@
+# Glossary
+
+resumectl has one domain context: authoring, rendering and checking a résumé from verified career evidence.
+
+| Term | Meaning | Owner |
+|---|---|---|
+| Source | The `.tex` document and recursively included `.tex` content | `src/content/tex.ts` |
+| Section | A normalized heading used to match content with its editing/checking policy | `src/content/tex.ts` |
+| Entry | One measured list item, prose paragraph, or table description; may contain several paragraphs | `src/rendering/measurements.ts` |
+| Bullet | A list entry; legacy API names also use `Bullet` for other measured entries | `src/rendering/measurements.ts` |
+| Effective config | Values resolved in order: CLI/API overrides > YAML > documentclass > defaults | `src/project/config.ts` |
+| Editing policy | A section's `editable` guidance for an agent; distinct from whether length checks run | `src/project/config.ts` |
+| Layout | Style, paper, margins, spacing and font settings used for compilation | `src/project/config.ts` |
+| Render manifest | `<name>.resumectl.json`: actual geometry, layout, source/PDF hashes and overflow findings | `src/rendering/measurements.ts` |
+| Last-line fill | Final paragraph's rendered text width divided by its available line width | `src/rendering/measurements.ts` |
+| Quality gate | A pass/fail rule for content length/overflow, page budget or PDF private-use mappings | `src/quality/gates.ts` |
+| Writing evidence | User-supplied facts supporting ownership, mechanisms and outcomes; not inferred from layout scores | `skills/resumectl/SKILL.md` |
+
+See [the architecture decision](docs/adr/0001-domain-first-organization.md) for module boundaries.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Huo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# resumectl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A harness for agent-written résumés.**
+
+Paste in a job description and your background. Your coding agent (Claude Code, Codex, Cursor and similar) writes a tailored one-page résumé in LaTeX, renders it, and keeps revising until the PDF passes every check: it fits the page, has no ragged last lines, and parses cleanly in an ATS. Every claim comes from facts you gave it, so it can't invent metrics.
+
+| Sans (recommended) | Serif |
+|---|---|
+| ![Sans example](docs/sans.png) | ![Serif example](docs/serif.png) |
+
+<sub>Example people, schools and companies are fictional.</sub>
+
+## Why
+
+- **LaTeX, not Word.** Typesetting is far better, and you never fight Word's interface.
+- **LaTeX suits agents, with a harness to keep them in line.** A `.tex` file is plain text, so an agent can edit it precisely. Left alone, though, it overflows the page and pads bullets. resumectl measures the rendered PDF and makes the build fail until the content fits.
+- **Plain by design.** No icons, colour bars or two-column gimmicks. There are two typefaces with carefully tuned sizes and weights. I prefer the sans because it's easier to read on screen, where résumés are actually read. Both styles are single-column, real text and ATS-friendly.
+
+## Get started
+
+You need [Bun](https://bun.sh) ≥ 1.3. Everything else is set up by your agent.
+
+**1. Install the skill:**
+
+```bash
+npx skills add nickhuo/resumectl
+```
+
+It works with Claude Code, Codex, Cursor, Copilot and [other agents](https://skills.sh).
+
+**2. Ask your agent:**
+
+> Make me a résumé for this job.
+>
+> Job description: *(paste)*
+>
+> My background: *(paste your old résumé, LinkedIn, notes, project write-ups)*
+
+On the first run the agent checks your setup. If you have no TeX installed, it asks before installing [Tectonic](https://tectonic-typesetting.github.io), a 16 MB typesetter. The first build then downloads about 45 MB of packages, which takes a couple of minutes; later builds take seconds.
+
+The agent then maps the job's requirements to your evidence and asks about gaps instead of guessing. It writes the résumé, builds the PDF, and revises until every check passes.
+
+## What the build checks
+
+| Check | Default |
+|---|---|
+| Page budget | 1 page |
+| Entry length | Up to 2 lines per bullet, last line at least 80% full, no overflow |
+| Copyable text | Text copied out of the PDF matches the page (phone numbers, names, brackets) |
+
+You can change any limit per section in `resume.config.yaml`, and mark sections such as Education as off-limits to the agent. See [configuration](docs/configuration.md).
+
+## Editing by hand
+
+```bash
+bunx resumectl init ./my-resume --style sans  # starter resume.tex + config
+bunx resumectl build ./my-resume/resume.tex   # PDF in my-resume/output/, all checks
+```
+
+Fonts, sizes, margins and LaTeX commands are documented in [rendering](docs/rendering.md).
+
+## License
+
+[MIT](LICENSE). Inter is bundled under the [SIL Open Font License](template/fonts/OFL-Inter.txt). TeX Gyre Termes comes from your TeX distribution.

package/docs/adr/0001-domain-first-organization.md

@@ -0,0 +1,32 @@
+# 0001 — Organize by résumé capabilities
+
+- Status: Accepted
+- Date: 2026-10-16
+
+## Context
+
+The project already renders LaTeX, resolves configuration, measures entries and checks PDFs. A flat `src/` obscured those responsibilities, and the writing workflow lived in a personal Career repository. The product needs a short path from career evidence to a checked résumé without introducing separate services or multiple executables.
+
+## Decision
+
+Keep one domain context and one package. Group code by capability:
+
+- `content`: interpret source, included files, section keys and visible text. Depends only on shared input errors and platform APIs.
+- `project`: resolve configuration, create starter projects and diagnose toolchain availability. Uses content parsing and rendering asset paths; does not compile or invoke quality gates.
+- `rendering`: compile via XeLaTeX, capture actual geometry, manage manifests and own font utilities. Uses effective project configuration and source expansion.
+- `quality`: evaluate rendered measurements and PDF facts. Uses content parsing, project policy validation and rendering manifests; does not invoke the compiler.
+- `cli`: parse arguments, compose the capabilities, select human/JSON output and map outcomes to exit codes.
+
+These are capability modules within one context, not separate bounded contexts. Project and rendering share configuration/asset contracts, but no cyclic file imports are required. Do not add repository/service/controller layers just for symmetry. Common errors remain at `src/errors.ts`; package consumers use `src/index.ts`.
+
+Retain `src/cli.ts`, root API exports, `template/`, the config schema and existing command names. Move legacy width estimation to rendering; quality gates continue to use measured geometry.
+
+Expose only the essential workflow through `resumectl`: `init`, `doctor`, `config init/show`, `build`, `check`. Add `bun run resumectl` for repository use and `bun run verify` for development checks. `init` refuses overwrites; `doctor` diagnoses without installing dependencies. All workflow commands support JSON. Keep font metric regeneration as a maintenance script.
+
+Store writing instructions in `skills/resumectl/SKILL.md` and include `skills/` in the package. Adapt the local methodology to verified candidate facts, per-section edit policy and current rendered quality gates. Remove hard-coded personal claims and obsolete character-count gates. Do not create a second résumé data format.
+
+## Consequences
+
+Tests mirror capabilities; integration tests still compile both styles and check output. Documentation uses one root glossary and root ADR directory, with separate rendering, quality and configuration references. Moving internal source paths is intentional; root package exports remain the supported API.
+
+A split into multiple packages, a generic DDD framework and independent CLIs would add coordination without a separate lifecycle or data owner, so they are deferred until an actual requirement appears.

package/docs/agents/domain.md

@@ -0,0 +1,12 @@
+# Domain documentation
+
+This is a single-context project. Maintain vocabulary in [`GLOSSARY.md`](../../GLOSSARY.md) and decisions in [`docs/adr/`](../adr/).
+
+- Follow [ADR 0001](../adr/0001-domain-first-organization.md) when placing code.
+- Put behavior and its tests with the owning capability. `src/cli/main.ts` composes commands; it does not own configuration, measurement or writing rules.
+- Use actual rendered geometry for quality decisions. Keep legacy font-width utilities out of the gate calculation.
+- Keep `.tex` as the source of résumé content and the manifest as generated evidence, not editable content.
+- Keep root package exports stable when moving internal files.
+- Run `bun run verify`; rendering tests require the environment described in [`setup.md`](../setup.md).
+
+The [writing skill](../../skills/resumectl/SKILL.md) owns résumé-writing guidance, not the TypeScript compiler/checker implementation.

package/docs/agents/issue-tracker.md

@@ -0,0 +1,10 @@
+# Issue tracker
+
+Use GitHub Issues for `nickhuo/resumectl` via `gh`.
+
+```bash
+gh issue list --repo nickhuo/resumectl
+gh issue view <number> --repo nickhuo/resumectl
+```
+
+Use the existing issue when one is supplied. Issue descriptions should identify the affected domain, expected behavior and a verifiable acceptance condition. See [triage labels](triage-labels.md) for readiness. Do not mirror issues into another tracker.

package/docs/agents/triage-labels.md

@@ -0,0 +1,11 @@
+# Triage labels
+
+| Label | Meaning |
+|---|---|
+| `needs-triage` | Scope and ownership have not been assessed |
+| `needs-info` | Required facts or reproduction details are missing |
+| `ready-for-agent` | Work is concrete and has a verifiable acceptance condition |
+| `ready-for-human` | A human decision or action is required |
+| `wontfix` | The project will not implement the request |
+
+Use these existing names rather than introducing synonymous labels. Confirm issue context before changing its status.

package/docs/api.md

@@ -0,0 +1,16 @@
+# Library API
+
+```ts
+import { compile, runGates, formatReport, resolveConfig } from "resumectl";
+
+const { config } = await resolveConfig({ texPath: "resume.tex" });
+const { pdfPath } = await compile("resume.tex", {
+  layout: config.layout, outDir: config.build.outDir,
+});
+const report = await runGates("resume.tex", pdfPath, {
+  ...config.checks, sections: config.sections,
+}, config.layout);
+console.log(formatReport(report));
+```
+
+The package root (`src/index.ts`) is the public API. Internal files are grouped by domain and are not stable deep-import paths. Existing root exports remain supported; project setup also exposes `initProject`, `initConfig` and `doctor`.

package/docs/configuration.md

@@ -0,0 +1,83 @@
+# Configuration
+
+This repository includes [resume.config.yaml](../resume.config.yaml); edit it to configure both examples. Leave `layout.style` commented out to keep their individual styles.
+
+Create a YAML configuration and inspect the effective values:
+
+```bash
+bunx resumectl config init
+bunx resumectl config show resume.tex --json
+bunx resumectl build resume.tex
+```
+
+A complete example of `resume.config.yaml`:
+
+```yaml
+version: 1
+layout:
+  style: sans
+  paper: a4
+  scale: 0.86       # Sans only
+  tracking: -1.5   # Sans only, percent of an em
+  ratio: 1.125     # Sans only, type scale
+  margins:
+    top: 0.4in
+    bottom: 0.3in
+    left: 0.35in
+    right: 0.35in
+  bulletSpacing: 0.15em
+  bulletIndent: 1.5pc
+  sectionSpacing:
+    before: "*2"   # Quote * multipliers in YAML; lengths such as 2ex also work
+    after: "*0.8"
+checks:
+  bullets:
+    maxLines: 2
+    minLastLineFill: 0.8
+  maxPages: 1
+sections:
+  WORK EXPERIENCE:
+    editable: true
+    checks:
+      maxLines: 2
+      minLastLineFill: 0.8
+  PROJECTS:
+    editable: true
+    checks:
+      maxLines: 2
+      minLastLineFill: 0.65
+  EDUCATION:
+    editable: false
+    checks:
+      maxLines: 1
+      minLastLineFill: 0
+build:
+  outDir: ./output
+  keepLogs: false
+```
+
+Every field is optional; omit `layout.style` to preserve the style in each source. `scale`, `tracking` and `ratio` affect only the sans style. Default section spacing is `*1`/`*1` for serif and `*2`/`*0.8` for sans. Margins accept `pt`, `mm`, `cm`, `in` and `pc`; spacing also accepts `em` and `ex`. Values must be non-negative. The nominal body size remains 11pt.
+
+Precedence is **CLI > YAML > documentclass > defaults**, merged field by field. Discovery starts beside the input source (or in the current directory for `config show` without a source) and searches upward to the repository root. Both `resume.config.yaml` and `resume.config.yml` are supported; if both exist, select one explicitly. Use `--config path/to/config.yaml` for another configuration. Relative `build.outDir` paths are based on the YAML file; CLI `--out-dir` paths are based on the current directory. Without an output setting, the PDF goes beside the source.
+
+`config init` creates a starter file in the current directory and refuses to overwrite an existing file. It includes a YAML language-server schema comment pointing to [resume.config.schema.json](../resume.config.schema.json) for editor completion. Unknown keys, invalid types, unsupported versions and invalid lengths are rejected. `config show` outputs effective values plus the source of each field, without compiling.
+
+`checks.bullets` supplies shared defaults. Each `sections.<title>.checks` overrides them field by field. `maxLines` is the maximum actual rendered lines **per entry**, not a total section budget. `minLastLineFill` is a fraction between 0 and 1: `0.8` means 80%, for either a single-line entry or the last line of a multi-line entry; `0` disables the minimum fill requirement. This is useful for facts such as skills and degrees, which should not be padded just to fill a line. `maxLines` and `maxPages` are positive integers.
+
+Section keys match rendered titles, ignoring case, LaTeX formatting and repeated whitespace (`TALKS & AWARDS` matches `\section{TALKS \& AWARDS}`). Only listed sections are checked. Set `checks: false` on a section to skip its length checks; page count, text mappings and overfull-box checks still run. Without a sections map, the checker retains the original `WORK EXPERIENCE` default. The old `checks.section` selector and `--section` still work, narrowing checking to one section. CLI `--max-lines` and `--min-last-line-fill` override the selected sections' individual limits, or all configured sections when no selector is given.
+
+`editable: true` tells the coding agent it may rewrite that section's body entries while preserving facts. `false` (the default) means leave them unchanged unless the user explicitly authorizes an edit. This policy is independent of checking: a section can be read-only and still fail its length limits. It is guidance exposed in `config show` and reports, not an enforced file lock or an automatic rewriting feature. Unlisted sections carry no editing permission. A coding agent should read `config show resume.tex --json`, revise the permitted entries, then build and use the per-section feedback. Changing thresholds or editing policy does not require rebuilding; changing content or layout does.
+
+For a summary or table description, mark each checkable entry explicitly:
+
+```latex
+\section{SUMMARY}
+\resumeentry{Your summary paragraph.}
+
+\section{PROJECTS}
+\begin{tabularx}{\textwidth}{@{} l X @{}}
+\projectlink{https://example.com}{Project} & \resumeentry{Your project description.} \\
+\end{tabularx}
+```
+
+Do not wrap list items in `\resumeentry`; they are already measured. Unwrapped prose and table text are not automatically checked. The repository example marks all six sections and checks 27 entries.

package/docs/quality.md

@@ -0,0 +1,36 @@
+# Quality gates
+
+### The checker
+
+**Gate 1 — rendered content length.** During compilation, the class records TeX’s actual paragraph line counts, available line widths, and the positions of each paragraph’s start and end. For each configured section, the checker sums the lines in each entry and divides the final paragraph’s rendered end position minus its left edge by its available width. Both single-line and multi-line entries must meet that section's final-line fill threshold. Reports include the section, entry number, text, measured length, effective limits and AI editing policy. Overfull horizontal or vertical boxes also fail this gate, including overflow on earlier lines and in sections with length checking disabled.
+
+Measurements are saved next to the PDF as `<name>.resumectl.json`, together with the effective layout and hashes of the source (including `\input` files) and PDF. Keep this file with the PDF for `check`; it survives log cleanup. Missing or mismatched measurements require a rebuild. Flat `itemize` and `plainlist` items are measured automatically. Wrap standalone prose and each `tabularx` X-column description in `\resumeentry{...}` to measure them, using the column's actual available width. Inline formatting, links, manual breaks and multiple paragraphs are supported; nested lists and nested entries are not. Headings, job titles, dates, locations and table labels are not measured as body entries. A configured, enabled section with no measured entries is an input error rather than a silent pass.
+
+**Gate 2 — page count.** The checker reads the page count from the PDF itself and inflates compressed object streams to find the page tree. If that fails, it falls back to the TeX log.
+
+**Gate 3 — copyable text.** The checker parses every ToUnicode CMap in the PDF and fails if any glyph maps to a private-use code point (U+E000–U+F8FF or the supplementary private-use planes). That is how OpenType alternates without a Unicode mapping show up. The report names the code points.
+
+### Checker options
+
+```
+resumectl build <resume.tex> [options]   compile with XeLaTeX or Tectonic, then run the gates
+resumectl check <resume.tex> [options]   run the gates on an existing PDF
+```
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--config <path>` | discovered YAML | Configuration file |
+| `--section <name>` | all configured sections; otherwise `WORK EXPERIENCE` | Check only this section |
+| `--max-lines <n>` | per-section config, shared default `2` | Override maximum rendered lines per entry in selected sections |
+| `--min-last-line-fill <0–1>` | per-section config, shared default `0.8` | Override minimum fraction occupied on the last line |
+| `--max-pages <n>` | `1` | Page limit |
+| `--style <serif\|sans>` | from YAML or class | Override the rendered font style |
+| `--paper <a4\|letter>` | from YAML or class | Override paper size |
+| `--pdf <path>` | PDF in the effective output directory | Existing PDF to check |
+| `--out-dir <dir>` | from YAML, otherwise beside source | Output directory |
+| `--keep-logs` / `--no-keep-logs` | from YAML, otherwise off | Keep or remove compiler intermediates after a passing build |
+| `--json` | off | Report with effective config, parameter sources and per-bullet measurements |
+
+The old `--min-chars` and `--max-width` flags are replaced by the line-count and fill controls. `check` requires a PDF built with the current CLI and its matching `.resumectl.json` file. Use the same layout config/overrides as the build; changing layout or source requires rebuilding. Checking thresholds can change without a rebuild.
+
+Exit codes: `0` means every gate passed. `1` means a gate failed, the compile failed, or doctor found a missing dependency. `2` means a usage or input error.

package/docs/rendering.md

@@ -0,0 +1,68 @@
+# Rendering and typography
+
+### Typography
+
+- **Serif — TeX Gyre Termes.** A free Times clone: traditional, compact, and familiar to every reader and parser. It keeps italics for job titles and taglines, and bold for names of organisations and roles.
+- **Sans — Inter**, at its text optical size (`opsz=14`). Inter is the closest open-source match to the system UI fonts people read all day (SF Pro on macOS, which is what GitHub renders on a Mac). Three choices follow from that:
+  - **Upright only.** Sans italics look slanted and nervous at résumé sizes, so `\textit` and `\emph` render upright. Hierarchy comes from size, weight and case.
+  - **Body at 430, bold at 600.** Scaling to 0.86 thins the strokes, and 430 restores the colour of the text without reading as bold. For emphasis, 600 is used instead of Bold, which reads heavy at 9–10pt; 600 is also the weight GitHub uses for bold text.
+  - **Scaled to 0.86 with −1.5% tracking.** Inter is much wider than Times. Without the scale the same content runs two pages; the slight negative tracking matches SF Pro's tighter text setting.
+  - **Contextual alternates off.** Inter's `calt` feature swaps `( ) - +` next to capitals and digits for raised "case" glyphs. Those glyphs have no Unicode code point, so `ALEX (AJ) CHEN` or `(555) 010-0142` copied as private-use garbage. Gate 3 exists because this bug can't be seen on the page.
+- **Static font instances.** XeTeX ignores variable-font axes and silently falls back to the default instance, which for some fonts is the lightest weight. `template/fonts/` therefore ships static 430, 500 and 600 files cut from Inter's variable font.
+
+### Type scale (sans)
+
+Every size sits on one modular scale, `size(n) = 10.95pt × ratio^n`, rendered at the `scale` factor. With the defaults (ratio 1.125, a "major second"; scale 0.86) that gives four sizes:
+
+| Level | Step | Size | Weight | Tracking | Why |
+|---|---|---|---|---|---|
+| Name | +5 | 16.9pt | 500 | +2% | Large text reads heavier, so the weight drops; all caps need a little air |
+| Organisation / school | +1 | 10.6pt | 600 | −1.5% | The anchor a skimming eye lands on |
+| Body, role, dates, contact | 0 | 9.4pt | 430 / 600 | −1.5% | Dates use tabular figures so the right-hand column lines up |
+| Section label | −1 | 8.4pt | 600 | +8% | Navigation, not content: small letter-spaced caps instead of competing on size |
+
+Two checks keep the hierarchy honest:
+
+- **Darkness falls monotonically down the levels.** Darkness is measured as size × stem width of `l`, which approximates how dark a line looks: name 1.82pt > organisation 1.35pt > role 1.20pt > label 1.06pt > body 0.88pt.
+- **The body is big enough.** Inter's x-height is 0.546 em against Times' 0.45, so 9.4pt Inter has the same x-height as 11.4pt Times, within the 10–12pt that print body text usually uses.
+
+The serif style keeps the classic sizes (`\huge` name, `\large` headings, 11pt body).
+
+### Layout
+
+- **Single column, no icons, no colour.** It prints cleanly in black and white, the PDF text layer reads in order, and ATS parsers have little to trip on.
+- **Rows with dates and places on the right.** Each organisation sits in a `\datedsubsection` row with its dates flush right, followed by a `\datedline` row for the role with its location flush right.
+- **Links look like links without looking like 2004.** Project names carry a small `↗` inside the link. There's no underline and no blue: the arrow reads as "clickable" on screen and as decoration on paper. Inter has the glyph; Termes doesn't, so the serif style draws the arrow with TikZ.
+
+### Class options
+
+```latex
+\documentclass[style=sans, paper=letter, scale=0.9, tracking=-1]{resume}
+```
+
+| Option | Values | Default | Effect |
+|---|---|---|---|
+| `style` | `serif`, `sans` | `serif` | Termes with italics, or Inter upright-only |
+| `paper` | `a4`, `letter` | `a4` | Page size; rendered line measurements follow automatically |
+| `scale` | number | `0.86` | Sans only: Inter's size relative to the 11pt body |
+| `tracking` | number | `-1.5` | Sans only: letter spacing in % of the em |
+| `ratio` | number | `1.125` | Sans only: type-scale ratio between levels, e.g. `1.2` for a stronger hierarchy |
+
+Class options remain supported. The CLI applies the effective layout after reading them, so YAML and command-line overrides change both the PDF and its measurements. Additional class options are `marginTop`, `marginBottom`, `marginLeft`, `marginRight`, `bulletSpacing`, `bulletIndent`, `sectionBefore` and `sectionAfter`.
+
+### Commands
+
+| Command | Use |
+|---|---|
+| `\name{NAME}` | Centered header |
+| `\basicInfo{…}` | Centered contact line; separate items with `\sep` |
+| `\datedsubsection{left}{dates}` | Organisation or school row, with dates flush right |
+| `\datedline{left}{right}` | Role row, with location flush right |
+| `\role{title}` | Bold job title. Italic in serif, upright in sans |
+| `\projectlink{url}{name}` | Bold project name with a clickable `↗` |
+| `plainlist` environment | Bullet-less list, used for education details |
+| `\resumeentry{body}` | Checkable prose paragraph or X-column description; no visual styling |
+
+### Swapping a font
+
+Custom fonts require changing `template/resume.cls` and providing the corresponding font files. The layout gate measures the compiled result, so it needs no width-table regeneration. `typographicWidth` and `bun run gen-metrics` remain available as legacy estimation utilities; they are not used by the gates.

package/docs/setup.md

@@ -0,0 +1,31 @@
+# Toolchain setup
+
+resumectl needs **Bun ≥ 1.3** and one TeX engine. When both XeLaTeX and Tectonic are installed, it uses XeLaTeX. Set `RESUMECTL_ENGINE=tectonic` or `RESUMECTL_ENGINE=xelatex` to choose one explicitly.
+
+## Tectonic (recommended)
+
+[Tectonic](https://tectonic-typesetting.github.io) is a single 16 MB program built on XeTeX. It downloads only the TeX packages a document needs.
+
+```bash
+brew install tectonic                                                       # macOS
+curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net | sh  # Linux and others
+```
+
+The first build downloads about 45 MB of packages and takes a couple of minutes. `build` says so on stderr. Later builds take seconds and work offline.
+
+Tectonic ships an older LaTeX format (2021). `resume.cls` backports the two newer features it relies on, so both styles render identically to XeLaTeX. The test suite checks this whenever both engines are installed.
+
+## XeLaTeX
+
+Use this if you already have TeX Live or MacTeX, or prefer a full distribution. [TinyTeX-1](https://github.com/rstudio/tinytex-releases#installation) is the lightest option, at about 287 MiB with the packages below:
+
+```bash
+tlmgr update --self
+tlmgr install titlesec enumitem pgf tex-gyre
+```
+
+TinyTeX-1 already includes `fontspec`, `kvoptions`, `geometry`, `hyperref`, `url` and `tools` (which supplies `tabularx`). `pgf` supplies TikZ, and `tex-gyre` supplies the serif font. Inter ships with resumectl. Neither style requires installing fonts in the operating system.
+
+## Check
+
+Run `bunx resumectl doctor` (or `bun run resumectl doctor` in this repository). It reports a missing Bun, TeX engine, TeX package or bundled asset without installing anything. A passing doctor confirms availability; `build` is the end-to-end check.

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "resumectl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Clean LaTeX résumé templates and PDF quality checks for coding-agent workflows.",
+  "license": "MIT",
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./template/*": "./template/*",
+    "./config-schema": "./resume.config.schema.json"
+  },
+  "bin": {
+    "resumectl": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "template",
+    "docs",
+    "GLOSSARY.md",
+    "resume.config.yaml",
+    "resume.config.schema.json",
+    "README.md",
+    "LICENSE",
+    "skills"
+  ],
+  "keywords": [
+    "resume",
+    "cv",
+    "latex",
+    "xelatex",
+    "bun",
+    "coding-agent"
+  ],
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "scripts": {
+    "resumectl": "bun src/cli.ts",
+    "example": "bun src/cli.ts build examples/serif.tex && bun src/cli.ts build examples/sans.tex",
+    "gen-metrics": "bun scripts/gen-metrics.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "verify": "bun run typecheck && bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  }
+}

package/resume.config.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "resumectl configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string", "minLength": 1 },
+    "version": { "const": 1, "default": 1 },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "style": { "enum": ["serif", "sans"], "default": "serif" },
+        "paper": { "enum": ["a4", "letter"], "default": "a4" },
+        "scale": { "type": "number", "minimum": 0.1, "maximum": 4, "default": 0.86, "description": "Sans only: font scale relative to the body size." },
+        "tracking": { "type": "number", "minimum": -10, "maximum": 20, "default": -1.5, "description": "Sans only: letter spacing in percent of an em." },
+        "ratio": { "type": "number", "minimum": 1, "maximum": 2, "default": 1.125, "description": "Sans only: type scale ratio." },
+        "margins": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "top": { "$ref": "#/$defs/absoluteLength", "default": "0.4in" },
+            "bottom": { "$ref": "#/$defs/absoluteLength", "default": "0.3in" },
+            "left": { "$ref": "#/$defs/absoluteLength", "default": "0.35in" },
+            "right": { "$ref": "#/$defs/absoluteLength", "default": "0.35in" }
+          }
+        },
+        "bulletSpacing": { "$ref": "#/$defs/length", "default": "0.15em" },
+        "bulletIndent": { "$ref": "#/$defs/length", "default": "1.5pc" },
+        "sectionSpacing": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Space before/after section headings. Defaults: serif *1/*1; sans *2/*0.8.",
+          "properties": {
+            "before": { "$ref": "#/$defs/sectionLength" },
+            "after": { "$ref": "#/$defs/sectionLength" }
+          }
+        }
+      }
+    },
+    "checks": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "section": { "type": "string", "minLength": 1, "description": "Optional selector: check only this section. Omit to check all configured sections; without a sections map, falls back to WORK EXPERIENCE." },
+        "maxPages": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 },
+        "bullets": { "$ref": "#/$defs/contentChecks", "description": "Shared defaults for section length checks." }
+      }
+    },
+    "sections": {
+      "type": "object",
+      "propertyNames": { "type": "string", "minLength": 1 },
+      "description": "Policies keyed by rendered section title; matching ignores case and repeated whitespace. Only listed sections are checked. Unlisted content is not authorized for AI edits.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "editable": { "type": "boolean", "default": false, "description": "Whether the coding agent may rewrite the section's body entries while preserving facts. Guidance only, not an enforced file lock." },
+          "checks": { "anyOf": [{ "const": false }, { "$ref": "#/$defs/contentChecks" }], "description": "Per-entry length rules, inheriting checks.bullets. Set false to skip this section's length checks; independent of editable." }
+        }
+      }
+    },
+    "build": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "outDir": { "type": "string", "minLength": 1, "description": "Relative to this config file. Default: next to the source." },
+        "keepLogs": { "type": "boolean", "default": false }
+      }
+    }
+  },
+  "$defs": {
+    "contentChecks": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxLines": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum actual rendered lines per entry; inherited default 2." },
+        "minLastLineFill": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum fraction of the final line occupied by an entry, including single-line entries. Inherited default 0.8; 0 disables the minimum fill check." }
+      }
+    },
+    "absoluteLength": { "type": "string", "pattern": "^(?:[0-9]+(?:\\.[0-9]+)?|\\.[0-9]+)(?:pt|mm|cm|in|pc)$" },
+    "length": { "type": "string", "pattern": "^(?:[0-9]+(?:\\.[0-9]+)?|\\.[0-9]+)(?:pt|mm|cm|in|pc|em|ex)$" },
+    "sectionLength": { "anyOf": [{ "$ref": "#/$defs/length" }, { "type": "string", "pattern": "^\\*(?:[0-9]+(?:\\.[0-9]+)?|\\.[0-9]+)$" }] }
+  }
+}

package/resume.config.yaml

@@ -0,0 +1,65 @@
+# yaml-language-server: $schema=./resume.config.schema.json
+version: 1
+
+layout:
+  # Uncomment to override the style in every source's documentclass.
+  # style: sans
+  paper: a4
+  scale: 0.86       # Sans only
+  tracking: -1.5   # Sans only, percent of an em
+  ratio: 1.125     # Sans only, type scale
+  margins:
+    top: 0.4in
+    bottom: 0.3in
+    left: 0.35in
+    right: 0.35in
+  bulletSpacing: 0.15em
+  bulletIndent: 1.5pc
+  # Defaults: serif *1 / *1; sans *2 / *0.8.
+  # sectionSpacing:
+  #   before: "*2"
+  #   after: "*0.8"
+
+checks:
+  bullets:
+    maxLines: 2
+    minLastLineFill: 0.8 # Defaults inherited by each section below.
+  maxPages: 1
+
+sections:
+  SUMMARY:
+    editable: true
+    checks:
+      maxLines: 3
+      minLastLineFill: 0.5
+  EDUCATION:
+    editable: false
+    checks:
+      maxLines: 1
+      minLastLineFill: 0 # Facts do not need padding to fill the line.
+  WORK EXPERIENCE:
+    editable: true
+    checks:
+      maxLines: 2
+      minLastLineFill: 0.8
+  PROJECTS:
+    editable: true
+    checks:
+      maxLines: 2
+      minLastLineFill: 0.65
+  TALKS & AWARDS:
+    editable: true
+    checks:
+      maxLines: 2
+      minLastLineFill: 0.65
+  SKILLS:
+    editable: false
+    checks:
+      maxLines: 2
+      minLastLineFill: 0
+  # Use checks: false to skip a section's length checks.
+  # editable is an instruction for the coding agent, not a file lock.
+
+build:
+  # outDir: ./output  # Omit to write beside each source file.
+  keepLogs: false