Quick start

Before you start

Use Python 3.11 or newer and a clone of this toolkit review branch. This development version has no public package release. Create a new private workspace with the synthetic starter, or connect an existing one with reviewed QMD and a trusted renderer.

For Quarto PDF/Word rendering, install Quarto and the TeX/fonts required by that project. Quarto-managed TinyTeX can supply XeLaTeX without placing it on PATH. The toolkit installs no rendering software or fonts. Inspect unfamiliar renderer scripts before executing them.

1. Install from the toolkit checkout

These commands use a local virtual environment. Windows commands call its executables directly, avoiding changes to shell execution policy.

python3 -m venv .venv
.venv/bin/python -m pip install .
py -3 -m venv .venv
.venv\Scripts\python.exe -m pip install .

2. Create a new private workspace

From the toolkit checkout, use the installed executable. On Windows replace .venv/bin/cv-buid with .venv\Scripts\cv-buid.exe.

.venv/bin/cv-buid init /path/to/new-private-cv
.venv/bin/cv-buid build --project /path/to/new-private-cv

Init refuses an existing directory. All initial facts and identities are fictional. Edit private/profile.json for evidence/facts and the two QMD files for reviewed wording and selection. Owner preferences belong in the private AGENTS.md. The starter’s outputs are private/quarto/output/{resume,full-cv}.{pdf,docx}. PDF uses TeX’s Helvetica-compatible sans-serif family; Word explicitly uses Arial. Configure Quarto/TinyTeX first, including titlesec enumitem needspace psnfss helvetic. No Office font installation is required for the starter PDF. Existing projects retain their own font requirements.

Or: preview adoption of an existing project

Stay in the toolkit checkout. Replace the project path with your own clone. Paths after --qmd and --evidence-profile are relative to that private project.

.venv/bin/cv-buid adopt /path/to/private-project --renderer render.py --evidence-profile private/profile.json --qmd private/quarto/resume.qmd --qmd private/quarto/full-cv.qmd --dry-run
.venv\Scripts\cv-buid.exe adopt C:/path/to/private-project --renderer render.py --evidence-profile private/profile.json --qmd private/quarto/resume.qmd --qmd private/quarto/full-cv.qmd --dry-run

Review the plan and repeat without --dry-run to create cv-buid.json and .agents/skills/cv-project/SKILL.md. Existing adoption targets cause a refusal; there is no overwrite option. Existing AGENTS.md, QMD, evidence and presentation files stay intact. Each private project keeps its own instructions.

3. Edit QMD, then build or watch

Edit the requested QMD variant directly in your private project. From the toolkit checkout, use the installed executable to select that project:

.venv/bin/cv-buid build --project /path/to/private-project
.venv/bin/cv-buid build --project /path/to/private-project --watch
.venv\Scripts\cv-buid.exe build --project C:/path/to/private-project
.venv\Scripts\cv-buid.exe build --project C:/path/to/private-project --watch

If cv-buid is on PATH, you can instead run cv-buid build from the private project root. Ctrl+C stops watch mode. Read your renderer’s instructions for output paths and font/profile requirements; --profile NAME is forwarded to it. Restart watching after changing config, renderer code or toolkit installation.

If something fails

  • Adoption target exists: inspect the existing config/skill and compare it manually. Preserve it rather than rerunning adoption over it.
  • Tool, profile or font missing: follow the private renderer’s error and setup instructions. No font is silently substituted.
  • Output open in Word/PDF software: close it and retry if the renderer reports a replacement lock, especially on Windows.
  • New project: use init at a new path. Use adopt only for existing reviewed content; it does not regenerate QMD.
  • Toolkit upgrade: create an upgrade plan, read its diff, then apply it with hash guards and backups. Customized private skills require manual review.