resume-builder: Instructions file for Codex

🤖 Agent instructions

Cursor Cloud: see docs/cursor-cloud.md.

This CLI is agent-operated: you are the primary operator, and the CLI is your deterministic toolbelt for parsing, validating, rendering, and tracking resumes. See ADR 0001 for the design rationale.

Use this repo to help a person run an evidence-backed resume workflow. The person is a working professional. You run the tool. They decide what is true and when anything is sent.

Guide the person

At the start of a new setup, before any other step:

1. Read docs/first-run/README.md. That file is only the index. The long path is docs/first-run/FAQ.md.
2. Open docs/first-run/guide.html in their browser and walk the page with them.
3. Follow docs/first-run/FAQ.md from an empty folder through a resume, a job list, and a study guide. Say only the sentences in docs/first-run/what-to-say.md.

Do not ask them to run commands. Do not ask them to edit files. Do not open a practice application form during first-run.

Files and paths

Always name real folders from the repo root. Never say "the resumes folder" or other vague folder names.

• The person puts files in my-documents.
• Ingest still reads candidate/inputs/resumes and candidate/inputs/notes. With no source flags, npm run workspace:ingest -- --workspace candidate reads those folders by default. Do not invent candidate/resumes.
• After they drop files, copy from my-documents into candidate/inputs/resumes or candidate/inputs/notes, then run ingest. Do not ask them to drop files into candidate/inputs/.
• Home Introduction tells the person that copy happens, in plain words. Exact candidate/inputs/ paths stay here and in the collapsed "For your AI agent" note on home.
• Jobs Go to setup opens the About you form on Introduction, scrolls to it, and focuses the first field.
• The Jobs tab has an "Add a job" box. It never adds a job itself: it saves {link, text, createdAt} entries to candidate/job-requests.json and tells the person to say "check my job requests". At the start of each session and whenever they mention a job, run npm run workspace:job-requests -- --workspace candidate list. For each pending request, run add-role with the posting text (--jd-text or --jd-file; fetch the link only if no text was pasted) and then tailor. add-role and tailor mark the request done when the URL matches; npm run workspace:job-requests -- --workspace candidate done --link <url> (or done --all) closes one by hand. Never apply.
• If Open folder fails, or the home page shows the fallback note, open my-documents yourself from the repo root. That note appears only when opening fails or cannot be confirmed.