job-application-agent 2.0.0

package/job-application-agent/references/ANALYTICS.md

@@ -0,0 +1,65 @@
+# Usage analytics
+
+Job Application Agent includes default-enabled, opt-out usage analytics. The purpose is to learn which discovery sources, job types, applicant-tracking systems, and application steps are useful or unreliable.
+
+The first eligible command displays a disclosure. New installations may send that command's events after the disclosure. Existing installations receive a one-command grace period before events begin.
+
+## Controls
+
+```text
+node scripts/job-application.mjs telemetry status
+node scripts/job-application.mjs telemetry disable
+node scripts/job-application.mjs telemetry enable
+node scripts/job-application.mjs telemetry reset
+node scripts/job-application.mjs telemetry preview --stdin
+node scripts/job-application.mjs telemetry record --stdin
+```
+
+- `disable` stops future collection while preserving the anonymous installation ID.
+- `enable` resumes collection with the same anonymous installation ID.
+- `reset` disables collection and removes the anonymous ID and relay token. Enabling later creates a new identity.
+- `preview` validates and shows an event without transmitting it.
+- `record` rejects undocumented events and properties; browser workflows use it for started, step, pause, skip, and round events. Confirmed submissions are emitted by `ledger add` and must not be recorded twice.
+- `status`, `disable`, `reset`, and `preview` never transmit an event. After `enable`, collection resumes on the next eligible workflow command.
+- Previously collected events remain until the analytics retention period expires. Disabling or resetting does not issue a historical-deletion request.
+
+Telemetry is best effort. It has no offline queue, uses a short network timeout, and never changes the result of a job-application command.
+
+## Identity boundary
+
+Analytics never includes the candidate's name, email, phone, exact address, profile URLs, candidate location, work authorization, personal compensation or compensation floor, target profile or thresholds, resume or attachments, must-have evidence or coverage details, rejection reasons, prompts, responses, job descriptions, form questions, drafted answers, notes, passwords, MFA, CAPTCHA, legal or demographic answers, browser data, IP address, request headers, user agent, or raw error messages.
+
+Structured job context may include company, role title, canonical destination domain, a SHA-256 hash of the job URL after removing query parameters and fragments, ATS, source channel, job country, work mode, employment type, seniority, role family, published salary band, fit score, match/gap categories, workflow stages, field categories, pause reasons, submission result, outcome, bounded interview quality, and bounded interview failure point.
+
+Company and title values are bounded and rejected when they resemble an email, phone number, URL, LinkedIn profile, or GitHub profile.
+
+## Event schema
+
+| Event | Structured properties |
+|---|---|
+| `installation_started` | OS family, Node major version, submission mode |
+| `command_completed` | Command category, result, duration bucket |
+| `job_discovered` | Company, title, job hash/domain, ATS/source, job country, work mode, seniority, employment type, role family, published salary band |
+| `job_assessed` | Company, title, job hash/domain, ATS, fit score, eligibility, decision, match/gap tags |
+| `application_started` | Job hash, ATS, approval mode, required-field count, resume/cover-letter/referral requirements |
+| `application_step` | Job hash, ATS, stage, field category, retry count, duration bucket |
+| `application_paused` | Job hash, ATS, stage, bounded reason |
+| `application_skipped` | Job hash, bounded reason, fit score, eligibility |
+| `application_submitted` | Company, title, job hash/domain, ATS, duration, fields filled, short-answer count, resume-upload Boolean, approval mode |
+| `round_completed` | Requested/submitted/assessed/skipped/paused/error counts, duration bucket |
+| `outcome_recorded` | Company, title, job hash/domain, ATS, outcome, days since submission, optional bounded interview quality/failure point |
+| `review_generated` | Canonical unique-submission and outcome counts, review-due Boolean |
+| `skill_error` | Stable error code, workflow stage, ATS/job hash when available, recoverable Boolean |
+
+Only documented enums, bounded numbers, Booleans, bounded company/title/country strings, and documented tag arrays are accepted. Client and relay both reject unknown properties. Payloads are limited to 4 KB.
+
+## Processing and retention
+
+- A Cloudflare Worker validates events, signs anonymous installation tokens, and forwards accepted payloads.
+- PostHog US Cloud stores personless events with `$process_person_profile: false`.
+- Every event disables GeoIP enrichment with `$geoip_disable: true`, and the PostHog project discards incoming IP data.
+- The project does not call PostHog identify, alias, group, person-property, autocapture, or session-replay features.
+- Anonymous installation IDs remain stable until reset.
+- The product retention policy is 24 months and dashboards are private. Dashboard queries exclude data older than 24 months.
+- PostHog US Cloud must be configured with a 24-month raw-event TTL before production telemetry is considered fully retention-compliant. The current free project does not expose a self-service raw-event TTL, so the owner must enable that control through an eligible PostHog plan or arrange time-bounded deletion with PostHog. This limitation does not weaken any collection-time identity boundary.
+- The Worker does not forward client IPs or request headers, and Worker observability is disabled.

package/job-application-agent/references/APPLICATION_GUIDANCE.md

@@ -0,0 +1,12 @@
+# Application answer guidance
+
+Use this structure for motivation and fit answers:
+
+1. State one company-specific motivation tied to the product, customers, technical problem, or mission visible in a reliable company source.
+2. Give two concrete, resume-backed achievements that demonstrate the most important requirements. Prefer outcomes and shipped work over tool lists.
+3. If a material gap exists, add one honest bridge: name the adjacent evidence, state what is not yet demonstrated, and explain the credible learning path without implying experience the candidate does not have.
+
+Keep the answer direct and human. Aim for roughly 100–150 words unless the form requires another length. Adapt the evidence to the question; do not paste a keyword-dense summary.
+
+Never invent experience, scale, security ownership, technologies, employment terms, motivation, or company knowledge. Do not claim GraphQL, Temporal, Rust, P2P, networking, security, or other experience unless it is explicit in the canonical resume or candidate-provided evidence.
+

package/job-application-agent/references/SCHEMAS.md

@@ -0,0 +1,156 @@
+# Data schemas
+
+## Profile input
+
+Send one JSON object to `profile set --stdin`. Send an object containing only intentional overrides to `profile migrate --stdin`; migration preserves existing identity fields, maps legacy `salaryPreference` to `targetCompensation`, adds current defaults, validates the complete result, and writes it atomically.
+
+```json
+{
+  "name": "Candidate Name",
+  "email": "candidate@example.com",
+  "phone": "+91 90000 00000",
+  "location": "Bengaluru, India",
+  "workAuthorization": "Exact countries or arrangements",
+  "linkedin": "https://linkedin.com/in/example",
+  "github": "https://github.com/example",
+  "portfolio": "https://example.com",
+  "availability": "30 days",
+  "currentCompensation": "Optional exact value and currency",
+  "targetCompensation": "Optional legacy-compatible free text",
+  "compensationFloor": { "amount": 9000000, "currency": "INR", "period": "year" },
+  "roleFamilies": ["product-engineering", "full-stack", "ai-ml"],
+  "seniority": ["senior", "staff"],
+  "skills": ["TypeScript", "Python", "React", "Node.js", "PostgreSQL", "MCP", "AI agents"],
+  "targetLocations": ["India", "Remote", "Worldwide"],
+  "excludedLocations": [],
+  "workModes": ["remote"],
+  "industries": ["AI", "developer tools"],
+  "excludedCompanies": [],
+  "submissionMode": "routine-auto",
+  "yearsExperience": 10,
+  "autoSubmitMinScore": 80,
+  "manualReviewMinScore": 70,
+  "minMustHaveCoverage": 70
+}
+```
+
+Required fields are `name`, `email`, `phone`, `location`, `workAuthorization`, `roleFamilies`, `seniority`, `targetLocations`, `workModes`, `submissionMode`, `yearsExperience`, `autoSubmitMinScore`, `manualReviewMinScore`, and `minMustHaveCoverage`.
+
+`compensationFloor` is optional and must use a three-letter currency code and `period: "year"`. Compare a job salary only when its basis and currency are directly comparable.
+
+## Job assessment input
+
+Treat `mustHaves[].evidence` as private resume analysis. It is used locally and is not included in telemetry.
+
+```json
+{
+  "title": "Senior Product Engineer",
+  "company": "Example",
+  "description": "Posting text",
+  "source": "greenhouse",
+  "url": "https://job-boards.greenhouse.io/example/jobs/123",
+  "postingStatus": "active",
+  "eligibility": "eligible",
+  "roleFamily": "product-engineering",
+  "seniority": "senior",
+  "experienceMin": 7,
+  "experienceMax": 12,
+  "workMode": "remote",
+  "remote": true,
+  "locations": ["Remote", "India"],
+  "salaryMaximum": 12000000,
+  "salaryCurrency": "INR",
+  "mustHaves": [
+    { "requirement": "TypeScript", "status": "met", "evidence": "Resume-backed example" },
+    { "requirement": "Distributed systems", "status": "partial", "evidence": "Related platform work, not exact claim" },
+    { "requirement": "GraphQL", "status": "missing" }
+  ]
+}
+```
+
+Allowed sources: `linkedin`, `greenhouse`, `lever`, `ashby`, `workable`, `comeet`, `workday`, `rippling`, `smartrecruiters`, `google-form`, `company`, `email`, and `other`.
+
+Allowed posting statuses: `active`, `closed`, `unclear`. Allowed eligibility: `eligible`, `unclear`, `ineligible`. Allowed seniority: `junior`, `mid`, `senior`, `staff`, `principal`, `lead`, `manager`, `director`, `founding`, `unspecified`. Allowed work modes: `remote`, `hybrid`, `onsite`, `unspecified`. Must-have statuses: `met`, `partial`, `missing`, `unclear`.
+
+Assessment output retains `review`, `ask`, `skip`, and `exclude`, and adds `autoEligible`, `mustHaveCoverage`, and structured `gates`. `review` does not itself authorize submission.
+
+## Duplicate check input
+
+Include as many identifiers as are known.
+
+```json
+{
+  "id": "example-senior-product-engineer-2026-01-15",
+  "company": "Example",
+  "role": "Senior Product Engineer",
+  "url": "https://jobs.example.com/roles/123?utm_source=board",
+  "employerJobId": "greenhouse:123"
+}
+```
+
+The check removes fragments and non-job query parameters while retaining recognized job or requisition identifiers. Matching ledger ID, canonical URL, or same-company employer job ID is a hard duplicate. Same company and role without a shared job ID is a possible duplicate.
+
+## Confirmed submission input
+
+Add only after visible success confirmation.
+
+```json
+{
+  "id": "example-senior-product-engineer-2026-01-15",
+  "company": "Example",
+  "role": "Senior Product Engineer",
+  "url": "https://jobs.example.com/roles/123",
+  "employerJobId": "greenhouse:123",
+  "source": "company",
+  "score": 84,
+  "status": "submitted",
+  "submittedAt": "2026-01-15T10:00:00.000Z",
+  "approval": "STANDING AUTHORIZATION",
+  "duplicateOverride": "NEW REQUISITION CONFIRMED",
+  "answers": { "Resume": "Canonical resume.pdf" },
+  "telemetry": {
+    "durationBucket": "5-15m",
+    "fieldsFilled": 14,
+    "shortAnswerCount": 2,
+    "resumeUploaded": true
+  }
+}
+```
+
+Use `duplicateOverride` only for a verified distinct requisition after a possible-duplicate warning. It and `telemetry` are transient and are not written to the application ledger. Use approval `APPROVE SUBMIT` for per-application approval or `STANDING AUTHORIZATION` when the current request authorizes routine batch submission.
+
+## Outcome input
+
+```json
+{
+  "id": "example-senior-product-engineer-2026-01-15",
+  "status": "rejected",
+  "occurredAt": "2026-01-20T09:00:00.000Z",
+  "note": "Optional private note",
+  "interviewQuality": "weak",
+  "failurePoint": "constraints",
+  "reasons": [
+    { "category": "eligibility", "evidence": "explicit" }
+  ]
+}
+```
+
+Allowed outcomes: `interview`, `rejected`, `offer`, `withdrawn`.
+
+Optional interview quality values: `promising`, `viable`, `weak`, `dead`. Optional failure points: `role-scope`, `company-problem`, `constraints`, `interviewer`, `process`, `unknown`. A failure point requires an interview quality. Free-form notes remain private and are never included in telemetry.
+
+Allowed reason categories: `eligibility`, `closed-stale`, `level-compensation`, `must-have-gap`, `generic-resume-screen`, `interview-stage`, `unknown`. Evidence is `explicit` or `inferred`. An identical event is idempotent. Adding reasons or interview-quality fields to an earlier identical occurrence appends one local enrichment row but suppresses duplicate outcome telemetry.
+
+## Review acknowledgement input
+
+Generate `ledger review` first. Acknowledge only after the candidate has reviewed it.
+
+```json
+{
+  "reviewedAt": "2026-01-21T09:00:00.000Z"
+}
+```
+
+The acknowledgement stores the current canonical unique-submission and mature-application counts in append-only `reviews.ndjson`.
+
+`ledger review` also returns `interviewLearningSegments`. Each row combines the canonical application's source and ten-point fit-score band with the latest recorded interview quality and failure point, plus a count. This supports evidence-based targeting reviews without exposing private notes or automatically changing score weights.