FreeApply

Runs one email reply check (the freeapply-replies procedure), always beginning with action start, and, when the user saved an email login in Settings, reads and marks their mailbox itself. Each email found is recorded with freeapply_record_outcome. Use: start first; then read (start's mail.reader freeapply) or the Gmail connector (connector); mark after recording each email read returned; finish once everything found is recorded. Behavior: start: read-only, repeatable. read: signs in with the app password kept on this computer (you never see it), returns matching emails, changes nothing. mark: stars and/or labels one email as the user chose in Settings. finish: sets the last check to now, so the next check reads only newer email: only after recording everything found. Returns: start (the plan) {since, gmail (the user's mail settings: action none|star|label|star_and_label, label_name, ...), mail {reader: freeapply|connector, address}, applied [{job_id, company, title, submitted_at}], known_message_ids (already recorded)}. read {emails: [{gmail_message_id, gmail_thread_id, sender, subject, received_at, text}] newest first, already-recorded left out, count}. mark {mail_action} (for freeapply_record_outcome). finish {last_check}. Errors: an action other than start, read, mark or finish; read or mark without a saved email login; the mail server refusing the login.

Checks a cover letter or free-text answer against what the user really has; saves a passing cover letter as a PDF to upload. Every piece of prose is checked here before you type or attach it (freeapply_update_job only records). Use: before typing any written answer or attaching any letter, and after each fix. Not for short fields straight from settings (name, date, yes/no). Behavior: flags every skill, tool, number or claim the résumé, settings, highlights and saved answers don't support. Without save, changes nothing. With save, a passing letter becomes a PDF in the documents folder, kept with the job; a failing one is never saved; saving again replaces the file; refused once the job is applied. Until setup has stored the résumé's text, most claims are reported unsupported. Returns: {ok, problems} (plain sentences: fix, remove or ask the user). With job_id also keywords {used, unused}: the posting's supported skills this text uses / could still use. With save also file {path, name, bytes}, or note (why not saved). Errors: save without kind cover_letter and job_id; unknown job_id.

Claims a job before you work on it: duplicate check, the user's rules, starts tracking, returns the job_id every later call needs. Makes the job's first record (listing: freeapply_list_jobs; changing: freeapply_update_job). Use: before opening any application form; also to record a reviewed job you won't pursue (status skipped + status_note) so it isn't reviewed again. Not for a job already claimed. Behavior, first match wins: posting id already tracked: returns that job (existing true, nothing added); job site the user didn't choose, or signed out or paused: refused (refused says why, sites lists ready ones); same company and title as an applied job: refused as a repost; posted pay below the user's minimum: saved as skipped (rule pay_floor). Otherwise the job is added. A refused or existing claim changes nothing, so repeating the call is safe. Returns: {job_id, existing, status, rule, earlier}. earlier: up to 20 other jobs at the company [{id, title, company, status, same_title}]; if an applied one is clearly the same role under another title, mark this one skipped (freeapply_update_job). restart true (auto-run): the user saved new settings and wants them used now: don't work this job; the run finishes and starts again. Errors: a missing title or company.

Go-ahead for one submit after checking the pace, the user's limits and, in auto-run, the Stop button. Comes right before the submit; freeapply_update_job refuses applied without its clearance. Use: right before every submit, with job_id. Not early, not for a job you won't submit now: each clearance counts toward the per-minute pace at once. Behavior: at most 3 submits a minute (or the user's slower setting) and the user's daily cap. A clearance: one job, 15 minutes, used up when applied is recorded; asking again for the same job issues a new one; kept only while FreeApply runs. Parameters: job_id ties the clearance to that one job (without it you only see the pace). method: external (employer or ATS form, the default), easy_apply or email; the pace and daily cap count submits by that method, and easy_apply also needs one-click apply allowed in Settings. run_id, only in auto-run (from freeapply_manage_autorun start), adds the user's Stop and limits, and counts as the run checking in. Returns: {clear, advice, last_minute, limit_per_minute, today, daily_cap}, plus clearance {job_id, expires_at} when clear. clear false: don't submit; prepare the next job, call again later. refused: one-click apply is off; apply on the employer's site or skip the job. stop_run true (with reason): the run must end now: freeapply_manage_autorun action finish. restart true: the user saved new settings and wants them used now: submit and record this job, start no other, finish the run; the next begins at once.

Fetches one job posting from the user's computer, trimmed: description, form questions, suggested answers, skills asked. Costs few tokens next to the browser, which you still use to fill and submit the form. Use: read each posting you found before scoring or applying. FreeApply has no job search of its own: search the user's job sites in the browser. Not for search-result or sign-in pages: read those in the browser. Behavior: read-only; one web request. Greenhouse, Lever, Ashby via their public APIs, other sites as page text. Public http(s) only: an address on this computer or a local network, or a redirect to one, is refused. Remembered this session, so freeapply_claim_job keeps its keywords. Parameters: url, the posting or its application form; max_chars caps only the description (default 6000, at least 500; description_chars tells you when it was cut); source, the job site where you found it (e.g. linkedin), picks the saved answers meant for that site. Returns: ats, title, company, location, work_mode, pay, description, description_chars (full length), questions [{label, required, type, options}], suggested_answers (from settings and saved answers; answer anything else only from the résumé or the user), keywords {matched, missing, coverage}: use matched in the posting's words, never claim missing; coverage = matched share in %, null if the posting names none. Errors: a bad or local address, or an unfetchable page, with the reason: read it in the browser. Next: freeapply_claim_job.

Whether the user already made an account on an employer's careers site, and with which email. Employer sites only (job boards such as LinkedIn that signed the user out: freeapply_report_site_problem). Use: when an application form asks you to sign in or create an account. Not for signing in or up: FreeApply stores no passwords and you never type one. Behavior: read-only. The user records the accounts they make on the dashboard's Needs you tab. Parameters: site, the host the sign-in form is on, or any URL there. It is reduced to the domain without www. and matched exactly, so careers.example.com and example.com are different sites: pass the one the form is on. Returns: known account {domain, email_used, created_at, job_id, note}: ask the user to sign in in the browser, then continue in their session. None {domain, account: null}: freeapply_update_job status needs_account, account_url = the sign-up page. Errors: a site that isn't a domain or web address.

Reads the user's settings: who they are, what they seek and how FreeApply should work. Single form answers: freeapply_manage_answers; whether FreeApply can run: freeapply_get_status. Use: once per session or helper, and again after each auto-run go, before scoring jobs or filling a form. With the résumé text and the user's own words, the only source of facts about the user: never invent beyond it. To change: freeapply_update_settings. Behavior: read-only; never includes installation secrets. Parameters: sections, the sections to return (default all, named under Returns): ask only for what the step needs, e.g. ["profile", "eligibility"] for a form, and leave out resume, the largest, unless you need its text. Returns: {settings, missing}. Sections: profile, targets, eligibility, resume (file paths, text, profile; the user adds and replaces résumé files in the dashboard), cover_letter, automation, autorun, gmail, custom_answers, models, model_choices, sharing (choices only). missing: required fields still empty [{key, label}]; while non-empty, apply nowhere: open the settings tab (freeapply_open_dashboard) and ask the user to fill them. Errors: an unknown section; the message lists valid ones.

The user's job search in numbers: applications, replies, interviews, offers, rates (individual jobs: freeapply_list_jobs; whether FreeApply can run: freeapply_get_status). Use: to report progress, e.g. when wrapping up a session. Not for finding a particular job. Behavior: read-only, cheap: counted fresh from the local database each call, nothing cached. No parameters. Returns: tracked, applied, applied_today, queued, needs_you (jobs waiting on the user), interviews, offers, rejections, acknowledged, response_rate (% of applications with a real reply; automatic acknowledgements not counted), avg_fit, last_reply_check (when the last Gmail reply check finished), counts by_status, by_outcome, by_method, daily (applications per day), top_companies, top_titles, top_jobs.

Whether FreeApply can work now, plus the signed step-by-step procedure for a task. About FreeApply itself (user details: freeapply_get_settings; job search: freeapply_get_stats). Use: first in every session and before each task; with wait after asking the user to accept the Terms or finish setup in the dashboard. Works while locked or the Terms are unaccepted, so it can say why. Behavior: read-only: reports what FreeApply set up when it started (data folder, database, dashboard, the résumé copy to upload). wait holds the call up to 10 minutes until the Terms are accepted and setup is complete, and returns within seconds of that. Parameters: none for status only; procedure adds that task's signed steps; lane (with procedure freeapply-apply) is for a helper: only the hard rules and that lane's steps, with a short status; wait as above, with or without procedure. Returns: workflow {ok, problem}, terms {ok}, setup_complete, missing, sites [{id, name, ready}] (chosen job sites), autorun, update, dashboard (URL), data_dir, documents {dir, resume, cover_letters}, stats, procedures, models {can_delegate, rescan, levels, lanes, unfilled} (each level and lane {model, effort, source}; model current = your own model does it). With procedure also procedure {name, description, text, workflow_version, workflow_hash}, null while locked. wait_again true: a wait ran out first; call again. Next: workflow.ok false: tell the user why, stop. terms.ok or setup_complete false: follow freeapply-setup. models.rescan true: do its AI models step first.

Lists the user's tracked jobs, most recent activity first (submitted, else updated, else found): the jobs themselves (totals and rates: freeapply_get_stats). Use: to find a job_id, look up one job by job_id, or answer questions about particular jobs. Not for adding or changing jobs (freeapply_claim_job, freeapply_update_job). Removing a job is the user's, in the dashboard. Behavior: read-only. Filters combine: a job must match all given. limit and offset page through the same order (default 200 from 0); a page shorter than limit is the last. Parameters: job_id returns just that job (empty if unknown); status and outcome match exactly; search finds text in the title, company or location, ignoring case. Returns: [{id, title, company, location, work_mode, pay_text, pay_min, pay_max, url, apply_url, fit_score, status, status_note, outcome, outcome_at, source, found_at, updated_at, method, submitted_at, confirmation, resume_path, cover_path, reply_count}]; empty when nothing matched.

Gets or saves the user's own answers to specific form questions, so you never guess one (general details: freeapply_get_settings). A new question for the user goes through freeapply_update_job status needs_info instead. Use: get before retrying a job the user re-queued from the Needs you tab; save when the user answers a question in this conversation, for later forms. Save only the user's own words: saved answers count as facts in freeapply_check_text. Behavior: get is read-only. save replaces the answer saved under the same question; an empty answer removes it. Returns: get {job_id, answers: [{label, answer}] the user gave for this job, saved_answers: {question: reusable answer}, cover_letter: the job's saved letter {path, text} (text: for a text-box letter field) or null}. save {label, saved, removed, saved_answers}. Errors: get without job_id or with an unknown one; save without label; an action other than get or save.

Keeps FreeApply applying on its own from this session, with no scheduled task: start waits until something is due, finish ends a run (freeapply_get_status only shows the run state). Use: auto-run mode of freeapply-apply, which setup's last step enters: start with wait (takeover on the first call), finish after each run, then start again. Not in a session the user runs by hand. Behavior: start with wait holds the call up to 10 minutes while nothing is due (auto-run stopped by the user's Stop or a limit in Settings, the rest after a search found nothing new, the daily cap) and returns as soon as something is, within seconds of the user pressing Start. One session runs it at a time. A run checks in with each job-work tool call and freeapply_clear_to_submit (15 minutes without one counts as ended); freeapply_clear_to_submit with the run_id ends it at a hard stop. finish releases the run and starts the rest (autorun.every_hours), or none when the user asked for a restart with new settings; harmless on a run that already ended. Parameters: action start or finish. wait (start): hold as above; without it start answers at once. takeover (start with wait): only on the call right after the user asked for setup or to keep applying: it presses Start (clears a Stop, a reached limit and the rest) and makes this session the runner; the session it replaced gets replaced at its next start. run_id (finish): the run start returned. summary (finish): one line shown in the dashboard's run history. Returns: start {go: true, run_id, minutes (left before the time limit, null: none), max_applications, sites}; {go: false, replies_due: true}: do freeapply-replies, then start again; {go: false, needs_user: terms|setup}: ask the user (freeapply_open_dashboard), freeapply_get_status with wait, then start again; {go: false, wait_again: true}: start again; {go: false, replaced: true} or any other go false: end quietly. finish {finished, applied_this_run}, null for a run no longer active. Errors: f…

Opens the local FreeApply dashboard in the user's browser, one tab (freeapply_get_status only reports its URL). Use: when the user must act there: accept the Terms, fill settings, answer questions waiting on them, review applications and replies. Not for reading data: other tools return it. Behavior: changes no data. Starts the dashboard if needed at http://127.0.0.1:7878 or the next free port; reachable only from this computer. Parameters: tab, the page to open: overview (default; shows the Terms until they're accepted), settings (setup fields), issues (Needs you: questions, sign-ups), applications or replies. Returns: {url, opened}. url null: it couldn't start (no free port); tell the user. opened false with a url: no browser launched; give the user the url.

Records what an employer did with an application (your side, e.g. applied or skipped: freeapply_update_job). Use: for each employer email found in a reply check, between freeapply_check_replies start and finish, and when the user tells you about a call or corrects an outcome. Not for your own steps. Behavior: with an email (gmail_message_id): stores it; raises the job's outcome only if this email ranks higher than the current one (an interview outranks an acknowledgement); the same gmail_message_id again stores nothing new. Without an email: sets the outcome exactly, whatever its rank. The email fields fill the dashboard's Replies tab. Returns: with an email {recorded (false: recorded before), kind, job_id, outcome (the job's, afterwards)}, job_id and outcome null without job_id; without one {job_id, outcome}. Errors: an unknown job_id; no job_id and no email; an empty outcome with an email.

Marks a job site the user chose in Settings (e.g. LinkedIn, Indeed) unusable for now: it signed the user out or showed its own daily limit (an employer's own careers site: freeapply_find_site_account). Use: as soon as a chosen site shows a sign-in page or a daily limit; then keep applying on the ready sites or company career sites. Never type a password. Behavior: signed_out: unavailable until the user signs in again and confirms it in the dashboard; limit_reached: paused until midnight. Meanwhile freeapply_claim_job refuses new jobs from it. Reporting again changes nothing; only the user can mark a site ready. Returns: {site, status, sites} (each chosen site with ready). Errors: a site the user didn't choose.

Shows or sends the exact data the user chose to share with the FreeApply server (the sharing choices themselves: freeapply_get_settings). Use: preview when the user asks what is shared; sync only when the user asks to send now (it also runs on its own every 12 hours). Not for changing the choices: the user does that in the dashboard (Settings, Data sharing). Behavior: preview: read-only, sends nothing, safe any time. sync: sends over the internet only what the current choices allow; can't be undone from here (the user can delete shared data in the dashboard); refused moments after the last sync. Returns: preview: the exact requests that would be sent: analytics_request (anonymous usage and job-market data), the talent-pool request only if the user joined; secrets hidden. sync: {sent, result} or {sent: false, reason}: Terms not accepted, a sync moments ago, or the server unreachable (the automatic sync retries later). Errors: an action other than preview or sync.

Sets a claimed job's status: your side of the application (employer's response: freeapply_record_outcome; adding a job: freeapply_claim_job). Use: after a submit (applied); giving up (skipped, failed); when the user must act: needs_info with the form's questions, needs_account with the sign-up page, blocked by a check you can't pass. Behavior: replaces the status. Enforced: applied needs a fresh freeapply_clear_to_submit clearance for this job; cover_text must pass the truthfulness check; an applied job only the user can change. needs_info questions go to the Needs you tab and re-queue the job once answered; if the user already answered them all, refused with the answers to use. A field marked for one status is refused with any other. Returns: {job_id, status} and when relevant: already_waiting; questions (each added, duplicate, grouped or already_answered, with its answer), questions_added; same_account (needs_account: jobs sharing one sign-up card); same_site (blocked: jobs blocked on the same site). Errors: an unknown job_id or a broken rule, saying what is missing.

Changes the user's settings: facts and preferences the user states, the résumé's text and profile (setup), and the AI models scan. Reading: freeapply_get_settings; single form answers: freeapply_manage_answers. Use: when the user states a fact or preference, in setup's résumé step, in the AI models step. Never fill a field the user didn't give you. Behavior: overwrites the sent fields, no undo. Deep merge: only sent fields change, nested objects merge, lists are replaced whole. User-only sections (legal, sharing, automation, autorun, onboarding, integrity, model_choices) are skipped and listed in ignored. All or nothing: one wrong field saves nothing. Parameters: patch, nested by section with the names freeapply_get_settings returns, e.g. {"targets": {"min_pay": 60000}}. Writable: profile, targets, eligibility, cover_letter, custom_answers (one at a time: freeapply_manage_answers), gmail (not last_check or manual_logins); resume only text and profile {headline, skills, titles, education, certifications}, taken from the résumé text alone; models only the scan {app, current, can_delegate, available, efforts}, read from your own tools, which replaces the last one. Returns: {changed, ignored, setup_complete, missing}; after a scan also models (model and effort chosen per level). Errors: nothing writable, unknown section or field, wrong type, value outside its choices (e.g. cover_letter.length short|standard|long), résumé files (the user adds them in the dashboard), malformed scan; the message names every problem.