job-application-agent 3.1.1 → 3.2.0

package/README.md

@@ -35,6 +35,7 @@ After onboarding, use natural commands:
 
 ```text
 search jobs
+list discovery sources for India and global remote engineering
 apply https://company.example/jobs/123
 apply all relevant jobs from this thread: <URL>
 run a round of 10
@@ -48,7 +49,7 @@ Requires Node.js 20 or newer and a browser-capable coding agent.
 
 | Stage | Behavior |
 |---|---|
-| **Discover** | Searches direct career pages, ATS platforms, and candidate-provided leads. |
+| **Discover** | Searches a shared, versioned catalog of direct careers, ATS platforms, networks, feeds, and job boards, then verifies every lead at the employer. |
 | **Qualify** | Checks seniority, skills, location, authorization, compensation, and posting status. |
 | **Apply** | Fills forms and uploads one canonical résumé using verified facts only. |
 | **Track** | Deduplicates applications and records only visible submission confirmations. |
@@ -101,6 +102,8 @@ flowchart LR
 
 The bundled CLI handles private profile storage, résumé import, scoring, duplicate checks, resumable rounds, attention queues, and application/outcome ledgers. The coding agent handles discovery and browser interaction under the rules in [`SKILL.md`](job-application-agent/SKILL.md).
 
+Discovery combines the reviewed [`SOURCES.json`](job-application-agent/references/SOURCES.json) catalog with an anonymous community registry. Every confirmed application automatically contributes its canonical public job URL, company, role, application channel, and provider; prior confirmed ledger entries backfill during later commands after a one-command disclosure grace period. Jobs, repeatable boards, and feeds are logged pending and become visible in the public dashboard or CLI only after maintainer review. Disable both forms of community sharing independently from analytics with `sources sharing disable`.
+
 ## 🔐 Privacy
 
 | Data | Where it stays |
@@ -108,15 +111,21 @@ The bundled CLI handles private profile storage, résumé import, scoring, dupli
 | Profile | macOS Keychain or Windows Credential Manager |
 | Résumé and ledgers | Owner-only local state directory |
 | Browser login | Existing browser session |
+| Community-sharing preference and delivery receipts | Owner-only local state directory |
 | Skill code | Version-controlled installation directory |
 
 Candidate data, résumés, application history, credentials, and browser sessions are never committed to this repository.
 
 Anonymous structured analytics are enabled by default to improve the agent. They may include job and workflow categories, but never candidate identity, résumé content, prompts, answers, browser data, IP addresses, or raw errors.
 
+Anonymous community sharing is also enabled by default, separately from analytics. Confirmed applications share only a canonical public job URL, company, role, application channel, optional coarse discovery source, and derived provider URL—never candidate identity, answers, résumé, score, referral parameters, or submission timestamp. Repeatable discovery surfaces share their bounded catalog metadata through a maintainer-review queue. The registry stores no raw installation IDs; record-scoped contributor hashes are used only for deduplication and counts, never as identity or publication authority.
+
 ```bash
 node ~/.agents/skills/job-application-agent/scripts/job-application.mjs telemetry status
 node ~/.agents/skills/job-application-agent/scripts/job-application.mjs telemetry disable
+node ~/.agents/skills/job-application-agent/scripts/job-application.mjs sources sharing status
+node ~/.agents/skills/job-application-agent/scripts/job-application.mjs sources sharing disable
+node ~/.agents/skills/job-application-agent/scripts/job-application.mjs sources jobs
 ```
 
 See [`ANALYTICS.md`](job-application-agent/references/ANALYTICS.md) for the event contract and retention policy, or view the [public aggregate dashboard](https://job-application-agent-telemetry.varora1406.workers.dev/).
@@ -143,7 +152,7 @@ Updates are staged and validated before replacement. Private candidate state liv
 npm test
 ```
 
-GitHub Actions validates the skill and runs the same test suite on every pull request. To try the workflow without installing, paste [`SHARE_PROMPT.md`](SHARE_PROMPT.md) into a new agent chat.
+GitHub Actions validates the skill and runs the same test suite on every pull request. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full local verification and review contract. To try the workflow without installing, paste [`SHARE_PROMPT.md`](SHARE_PROMPT.md) into a new agent chat.
 
 ## ⚖️ Responsible use
 

package/job-application-agent/SKILL.md

@@ -24,24 +24,27 @@ Use `scripts/job-application.mjs` for private state and deterministic checks. Re
 5. Use `review-each` for per-application approval. Use `routine-auto` only when the current request authorizes the destination or batch and every automatic-eligibility condition passes.
 6. When the candidate explicitly grants continuing autonomy, read [references/AUTONOMY.md](references/AUTONOMY.md) and persist it with `autonomy grant --stdin`. Do not repeat skill-level upload or submission approval prompts while the active grant and profile both use `routine-auto`.
 7. Obey browser and tool confirmation requirements regardless of the stored mode or autonomy grant.
-8. Disclose default-enabled structured anonymous analytics and the `telemetry disable` control. The CLI also displays this disclosure.
+8. Disclose default-enabled structured anonymous analytics and the `telemetry disable` control. Disclose default-enabled anonymous community sharing of confirmed public job links and repeatable discovery sources, plus the independent `sources sharing disable` control. The CLI also displays these disclosures before the first eligible transmission.
 
 Never store passwords, MFA codes, government IDs, demographic data, CAPTCHA answers, browser session data, or inferred candidate facts.
 
 ## Discover and assess
 
-1. Resolve discovery leads to the direct employer or ATS page.
-2. Verify the application channel immediately before assessment. Mark it `active`, `closed`, or `unclear`.
-3. Classify eligibility only after checking residence, location, work authorization, sponsorship, schedule, and employment type.
-4. Extract explicit seniority, experience range, work mode, locations, comparable published salary maximum, and all must-have requirements.
-5. Classify each must-have as `met`, `partial`, `missing`, or `unclear`. Attach private, resume-backed evidence for `met` and `partial`; never invent evidence.
-6. Run `score --stdin`. Apply the returned gate decision before considering the score:
+Read [references/SOURCES.md](references/SOURCES.md) before the first discovery pass in a workflow.
+
+1. Run `sources jobs` for recently confirmed direct job links and `sources list` (optionally filtered) for the highest-signal packaged and maintainer-reviewed discovery sources. Resolve every lead to the direct employer or ATS page.
+2. Attribute the lead with coarse `discoverySource`, stable packaged or community `discoverySourceId` when known, and independent `applicationChannel`. Treat a one-off user link as `user-supplied`. Whenever a user or agent discovers a repeatable public board, feed, directory, or careers index that is not already listed, run `sources suggest --stdin`; the CLI contributes its sanitized metadata by default unless community sharing has been disabled.
+3. Verify the application channel immediately before assessment. Mark it `active`, `closed`, or `unclear`.
+4. Classify eligibility only after checking residence, location, work authorization, sponsorship, schedule, and employment type.
+5. Extract explicit seniority, experience range, work mode, locations, comparable published salary maximum, and all must-have requirements.
+6. Classify each must-have as `met`, `partial`, `missing`, or `unclear`. Attach private, resume-backed evidence for `met` and `partial`; never invent evidence.
+7. Run `score --stdin`. Apply the returned gate decision before considering the score:
    - `exclude`: closed or stale channel, explicit ineligibility, excluded company/location, or incompatible work mode.
    - `ask`: unclear posting status, eligibility, authorization, location/work mode, seniority, or requirement evidence.
    - `skip`: explicit non-target seniority, comparable compensation below the configured floor, insufficient must-have coverage, or score below the manual-review floor.
    - `review`: a candidate for manual review or routine auto-submission.
-7. Treat `autoEligible: true` as necessary but not sufficient to submit. It requires all gates to pass, exact Senior/Staff alignment, score at least 80, at least 70% evidenced must-have coverage, and no material experience-range mismatch.
-8. Keep scores from 70 through 79 in manual review. Do not auto-submit when must-have analysis is absent or uncertain.
+8. Treat `autoEligible: true` as necessary but not sufficient to submit. It requires all gates to pass, exact Senior/Staff alignment, score at least 80, at least 70% evidenced must-have coverage, and no material experience-range mismatch.
+9. Keep scores from 70 through 79 in manual review. Do not auto-submit when must-have analysis is absent or uncertain.
 
 Do not lower seniority, compensation, location, work mode, or evidence thresholds to increase volume. Unknown compensation does not exclude a role; pause if the application asks the candidate to state or accept compensation.
 
@@ -51,16 +54,17 @@ For batches, scheduled work, or resumable handoffs, read [references/RUNS.md](re
 
 1. Recheck employer, title, direct domain, posting status, eligibility, and `autoEligible` immediately before submission.
 2. Run `ledger check --stdin` with the internal ledger ID, canonical URL, employer job ID, company, and role when available. Review both requisition duplicate status and same-company history.
-3. Stop on a hard duplicate. Treat a same-company/same-role match without a shared job ID as a possible duplicate. Use `duplicateOverride: "NEW REQUISITION CONFIRMED"` only after verifying it is a distinct requisition.
-4. Keep authentication in the existing browser session. Never inspect cookies, local storage, passwords, or session files.
-5. Fill only explicit profile fields, candidate-provided answers, or facts verified in the canonical resume.
-6. Follow [references/APPLICATION_GUIDANCE.md](references/APPLICATION_GUIDANCE.md) for narrative answers.
-7. Upload only the canonical resume unless the candidate explicitly provides another attachment. Resolve its absolute path with `resume path`, then follow [references/BROWSER_UPLOADS.md](references/BROWSER_UPLOADS.md). Use the browser's privileged path-based upload capability first; treat a visible native file picker as a fallback.
-8. Do not answer demographic questions. Stop for login/SSO/MFA, CAPTCHA, legal attestations, unclear authorization or compensation, sensitive identifiers, and judgment-only questions.
-9. Verify every required field, answer, attachment, and disclosure. Submit when the current request or active autonomy grant authorizes it.
-10. Record `submitted` only after visible success confirmation, using independent `discoverySource`, `applicationChannel`, and `roundId` values. Record no submission when confirmation is missing or ambiguous.
-11. Record workflow telemetry with `telemetry record --stdin`. Let `ledger add` emit `application_submitted`; do not emit it twice. Pass job URLs and structured metrics only through documented transient fields.
-12. Queue hard stops with `attention add --stdin` and continue elsewhere. Record reproducible general-purpose failures with `friction record --stdin`; improvement work must never delay application work.
+3. Stop on a hard ledger-ID, canonical-URL, employer-job-ID, or requisition duplicate. Treat a same-company/same-role alias as a possible duplicate. Use `duplicateOverride: "NEW REQUISITION CONFIRMED"` only after verifying it is a distinct requisition.
+4. For a genuinely different role at a previously applied company, follow `companyReapply`: proceed automatically only when it returns `eligible-after-cooldown` (15 full days since the latest company application and no recorded outcome). `cooldown-active` and `follow-up-present` require the candidate's explicit approval and `companyReapplyOverride: "CANDIDATE APPROVED EARLY REAPPLICATION"`.
+5. Keep authentication in the existing browser session. Never inspect cookies, local storage, passwords, or session files.
+6. Fill only explicit profile fields, candidate-provided answers, or facts verified in the canonical resume.
+7. Follow [references/APPLICATION_GUIDANCE.md](references/APPLICATION_GUIDANCE.md) for narrative answers.
+8. Upload only the canonical resume unless the candidate explicitly provides another attachment. Resolve its absolute path with `resume path`, then follow [references/BROWSER_UPLOADS.md](references/BROWSER_UPLOADS.md). Use the browser's privileged path-based upload capability first; treat a visible native file picker as a fallback.
+9. Do not answer demographic questions. Stop for login/SSO/MFA, CAPTCHA, legal attestations, unclear authorization or compensation, sensitive identifiers, and judgment-only questions.
+10. Verify every required field, answer, attachment, and disclosure. Submit when the current request or active autonomy grant authorizes it.
+11. Record `submitted` only after visible success confirmation, using independent `discoverySource`, `discoverySourceId`, `applicationChannel`, and `roundId` values. `ledger add` automatically shares the sanitized public job metadata and durably retries on relay failure; do not run a separate manual contribution. Record no submission when confirmation is missing or ambiguous.
+12. Record workflow telemetry with `telemetry record --stdin`. Let `ledger add` emit `application_submitted`; do not emit it twice. Pass job URLs and structured metrics only through documented transient fields.
+13. Queue hard stops with `attention add --stdin` and continue elsewhere. Record reproducible general-purpose failures with `friction record --stdin`; improvement work must never delay application work.
 
 ## Outcomes and reviews
 
@@ -93,6 +97,12 @@ node scripts/job-application.mjs autonomy grant --stdin
 node scripts/job-application.mjs autonomy status|preview|revoke
 node scripts/job-application.mjs round start|complete --stdin
 node scripts/job-application.mjs round status [round-id]
+node scripts/job-application.mjs sources list [--stdin]
+node scripts/job-application.mjs sources jobs [--stdin]
+node scripts/job-application.mjs sources suggest --stdin
+node scripts/job-application.mjs sources pending
+node scripts/job-application.mjs sources sync
+node scripts/job-application.mjs sources sharing status|enable|disable|reset
 node scripts/job-application.mjs attention add|resolve --stdin
 node scripts/job-application.mjs attention list
 node scripts/job-application.mjs friction record --stdin

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

@@ -25,12 +25,16 @@ node scripts/job-application.mjs telemetry record --stdin
 
 Telemetry is best effort. It has no offline queue, uses a short network timeout, and never changes the result of a job-application command.
 
+Community sharing is a separate default-enabled feature with independent `sources sharing status|enable|disable|reset` controls. Confirmed applications contribute bounded public job metadata, while repeatable discovery sources use maintainer review. Neither sends analytics events nor stores a raw contributor identity with a record; a record-scoped HMAC is used only for deduplication and unique-system counting. See [`SOURCES.md`](SOURCES.md) for the exact public metadata contracts.
+
 ## 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, bounded discovery source, ATS/application 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.
 
+The more specific local `discoverySourceId` catalog attribution is not transmitted in v1.
+
 Local attention details and friction evidence are never transmitted. Analytics may receive only their already-documented bounded stage, ATS, pause reason, result, and aggregate count fields.
 
 Company and title values are bounded and rejected when they resemble an email, phone number, URL, LinkedIn profile, or GitHub profile.

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

@@ -14,13 +14,14 @@ Start input: `{ "requestedCount": 30 }`. Complete input: `{ "roundId": "round-..
 
 Count only unique applications with a visible employer/ATS confirmation or a verified sent recruiting email that were also added to the ledger with the same `roundId`. Filled forms, blockers, drafts, unsent email, and ambiguous confirmations never count. `round complete` rejects an under-target round.
 
-Run both company-level and requisition-level duplicate checks before filling and again immediately before transmission. A prior company application is a review signal, not by itself proof that a distinct requisition is a duplicate.
+Run both company-level and requisition-level duplicate checks before filling and again immediately before transmission. Hard ledger-ID, canonical-URL, employer-job-ID, and requisition duplicates always stop. Same-role aliases require a verified distinct requisition and `NEW REQUISITION CONFIRMED`. A genuinely different role at the same company may proceed automatically only when `companyReapply.decision` is `eligible-after-cooldown`: 15 full days have passed since the latest company application and no outcome has been recorded. `cooldown-active` and `follow-up-present` require explicit candidate approval.
 
 Resolve the canonical résumé with `resume path`, upload its absolute path through the browser’s privileged chooser first, and verify the filename and parsed fields. Use a visible native picker only as a fallback.
 
 Store independent attribution on every new ledger row:
 
 - `discoverySource`: where the lead was found (`linkedin`, `x`, `yc`, `hacker-news`, `job-board`, `direct-company`, `email`, `user-supplied`, `web-search`, or `other`).
+- `discoverySourceId`: stable packaged catalog ID such as `yc-work-at-a-startup` or `hacker-news-who-is-hiring`, when known.
 - `applicationChannel`: where it was submitted (`ashby`, `greenhouse`, `lever`, `workday`, `company`, `email`, and the other documented ATS values).
 - `source`: the legacy-compatible application channel.
 

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

@@ -49,6 +49,7 @@ Treat `mustHaves[].evidence` as private resume analysis. It is used locally and
   "description": "Posting text",
   "source": "greenhouse",
   "discoverySource": "linkedin",
+  "discoverySourceId": "linkedin-jobs-feed",
   "applicationChannel": "greenhouse",
   "url": "https://job-boards.greenhouse.io/example/jobs/123",
   "postingStatus": "active",
@@ -72,7 +73,7 @@ Treat `mustHaves[].evidence` as private resume analysis. It is used locally and
 
 Allowed sources: `linkedin`, `greenhouse`, `lever`, `ashby`, `workable`, `comeet`, `workday`, `rippling`, `smartrecruiters`, `google-form`, `company`, `email`, and `other`.
 
-`source` remains the backward-compatible application channel. New workflows should also supply `discoverySource` (`direct-company`, `linkedin`, `x`, `yc`, `hacker-news`, `job-board`, `email`, `user-supplied`, `web-search`, or `other`) and `applicationChannel` using the allowed `source` values.
+`source` remains the backward-compatible application channel. New workflows should also supply `discoverySource` (`direct-company`, `linkedin`, `x`, `yc`, `hacker-news`, `job-board`, `email`, `user-supplied`, `web-search`, or `other`), the kebab-case `discoverySourceId` from [`SOURCES.json`](SOURCES.json) when known, and `applicationChannel` using the allowed `source` values.
 
 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`.
 
@@ -94,6 +95,8 @@ Include as many identifiers as are known.
 
 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.
 
+`ledger check` also returns `companyReapply`. A genuinely different role is `eligible-after-cooldown` only when at least 15 full days have passed since the latest application to that company and no outcome has been recorded for that application. Hard duplicates are never eligible. Same-role matches, `cooldown-active`, and `follow-up-present` remain blocked at `ledger add` unless their exact documented override is present.
+
 ## Confirmed submission input
 
 Add only after visible success confirmation.
@@ -107,6 +110,7 @@ Add only after visible success confirmation.
   "employerJobId": "greenhouse:123",
   "source": "company",
   "discoverySource": "x",
+  "discoverySourceId": "x-hiring-feed",
   "applicationChannel": "company",
   "roundId": "round-2026-01-15-00000000-0000-4000-8000-000000000000",
   "score": 84,
@@ -114,6 +118,7 @@ Add only after visible success confirmation.
   "submittedAt": "2026-01-15T10:00:00.000Z",
   "approval": "STANDING AUTHORIZATION",
   "duplicateOverride": "NEW REQUISITION CONFIRMED",
+  "companyReapplyOverride": "CANDIDATE APPROVED EARLY REAPPLICATION",
   "answers": { "Resume": "Canonical resume.pdf" },
   "telemetry": {
     "durationBucket": "5-15m",
@@ -124,9 +129,9 @@ Add only after visible success confirmation.
 }
 ```
 
-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.
+Use `duplicateOverride` only for a verified distinct requisition after a possible-duplicate warning. Use `companyReapplyOverride` only when the candidate explicitly approves a different-role reapplication during the cooldown or after a recorded outcome. Both override phrases and `telemetry` are transient. An accepted company reapplication override stores only `reapplicationApproval: "candidate-explicit"` in the private ledger. Use approval `APPROVE SUBMIT` for per-application approval or `STANDING AUTHORIZATION` when the current request authorizes routine batch submission.
 
-`discoverySource`, `applicationChannel`, and `roundId` are optional for backward compatibility and should be supplied for new resumable rounds. `ledger check` returns hard requisition/URL duplicate status plus bounded same-company history so a distinct role can be reviewed without conflating it with a duplicate.
+`discoverySource`, `discoverySourceId`, `applicationChannel`, and `roundId` are optional for backward compatibility and should be supplied for new resumable rounds. `discoverySourceId` accepts stable packaged and `community-…` source IDs; it remains local and is not included in telemetry. After a visibly confirmed submission, `ledger add` automatically contributes only the canonical public URL, company, role, application channel, optional coarse discovery source, and derived provider URL to the pending community job registry. Existing installations receive a one-command disclosure grace period before historical backfill; `sources sharing disable` opts out. The private answers, score, submission time, IDs, and round remain local, and no job appears publicly before maintainer review. `ledger check` returns hard duplicate status, bounded same-company history, and the same `companyReapply` decision enforced by `ledger add` while holding the application lock.
 
 ## Autonomy grant input
 

package/job-application-agent/references/SOURCES.json

@@ -0,0 +1,156 @@
+[
+  {
+    "id": "direct-company-careers",
+    "name": "Direct company careers pages",
+    "kind": "direct-employer",
+    "jobsUrl": null,
+    "regions": ["global"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": false,
+    "access": "public",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "linkedin-jobs-feed",
+    "name": "LinkedIn jobs, posts, and feed",
+    "kind": "professional-network",
+    "jobsUrl": "https://www.linkedin.com/jobs/",
+    "regions": ["global"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": true,
+    "access": "session",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "x-hiring-feed",
+    "name": "X hiring posts and feed",
+    "kind": "social-feed",
+    "jobsUrl": "https://x.com/home",
+    "regions": ["global"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": true,
+    "access": "session",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "yc-work-at-a-startup",
+    "name": "YC Work at a Startup",
+    "kind": "startup-network",
+    "jobsUrl": "https://www.workatastartup.com/jobs",
+    "regions": ["global", "india", "north-america"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": true,
+    "access": "session",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "yc-company-directory",
+    "name": "Y Combinator company hiring directory",
+    "kind": "startup-network",
+    "jobsUrl": "https://www.ycombinator.com/companies/hiring",
+    "regions": ["global", "india", "north-america"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": false,
+    "access": "public",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "hacker-news-who-is-hiring",
+    "name": "Hacker News Who is Hiring",
+    "kind": "community-thread",
+    "jobsUrl": "https://news.ycombinator.com/submitted?id=whoishiring",
+    "regions": ["global"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": false,
+    "access": "public",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "we-work-remotely",
+    "name": "We Work Remotely",
+    "kind": "job-board",
+    "jobsUrl": "https://weworkremotely.com/remote-jobs/search?term=software+engineer",
+    "regions": ["global", "remote"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": false,
+    "access": "public",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "a16z-build-jobs",
+    "name": "a16z Build open roles",
+    "kind": "curated-board",
+    "jobsUrl": "https://a16zbuild.substack.com/",
+    "regions": ["global", "north-america"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": false,
+    "access": "public",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "engg-space",
+    "name": "Engg.space",
+    "kind": "curated-board",
+    "jobsUrl": "https://www.engg.space/",
+    "regions": ["india", "global", "remote"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": false,
+    "access": "public",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "js-guru-jobs",
+    "name": "JS Guru Jobs",
+    "kind": "curated-board",
+    "jobsUrl": "https://jsgurujobs.com/jobs",
+    "regions": ["global", "remote"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": true,
+    "access": "session",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "linux-careers",
+    "name": "Linux Careers",
+    "kind": "job-board",
+    "jobsUrl": "https://www.linuxcareers.com/jobs",
+    "regions": ["global", "remote"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": false,
+    "access": "public",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "indeed",
+    "name": "Indeed",
+    "kind": "job-board",
+    "jobsUrl": "https://www.indeed.com/",
+    "regions": ["global", "india"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": true,
+    "access": "session",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "recruiter-inbound",
+    "name": "Verified recruiter email and direct messages",
+    "kind": "inbound",
+    "jobsUrl": null,
+    "regions": ["global"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": true,
+    "access": "connector-or-session",
+    "verification": "direct-employer-or-ats"
+  },
+  {
+    "id": "user-supplied-leads",
+    "name": "User-supplied job links and hiring posts",
+    "kind": "user-supplied",
+    "jobsUrl": null,
+    "regions": ["global"],
+    "roleFamilies": ["engineering"],
+    "requiresSession": false,
+    "access": "candidate-provided",
+    "verification": "direct-employer-or-ats"
+  }
+]

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

@@ -0,0 +1,73 @@
+# Discovery source registry
+
+The packaged [`SOURCES.json`](SOURCES.json) catalog is the reviewed, versioned list of repeatable discovery surfaces available to every installation. A community registry supplements it with maintainer-reviewed discovery sources and direct public job links from confirmed applications. Both remain distinct from application channels such as Greenhouse, Ashby, Lever, and Workday.
+
+## Use the catalog
+
+```text
+node scripts/job-application.mjs sources list
+node scripts/job-application.mjs sources list --stdin
+node scripts/job-application.mjs sources jobs
+echo '{"limit":25,"cursor":"opaque-cursor"}' | node scripts/job-application.mjs sources jobs --stdin
+```
+
+Optional filter input:
+
+```json
+{
+  "regions": ["india", "global", "remote"],
+  "roleFamilies": ["engineering"],
+  "kinds": ["job-board", "startup-network"],
+  "requiresSession": false
+}
+```
+
+`sources list` combines the packaged catalog with the live repeatable-source registry. Public v1 community entries are always maintainer-approved and have `registryStatus: "community-reviewed"`. Their `id` and `communitySourceId` are the same stable community ID and may be stored as `discoverySourceId`. `sources jobs` returns the newest maintainer-reviewed confirmed job links, 50 at a time by default, with an opaque `nextCursor` for pagination. Both are discovery leads, not endorsements or eligibility claims. Resolve every lead to the direct employer or ATS page and verify that posting immediately before assessment and submission.
+
+Store three independent attribution fields when available:
+
+- `discoverySource`: coarse compatible channel such as `linkedin`, `x`, `yc`, `job-board`, or `user-supplied`.
+- `discoverySourceId`: stable packaged or community ID such as `yc-work-at-a-startup` or `community-abcdef1234567890`.
+- `applicationChannel`: actual submission channel such as `greenhouse`, `ashby`, `lever`, `company`, or `email`.
+
+`discoverySourceId` remains local in v1 and is not transmitted by telemetry.
+
+## Community sharing
+
+Community sharing is enabled by default and independent of usage analytics. A confirmed `ledger add` queues and attempts the sanitized public job metadata automatically. Installations with historical applications consume one full disclosure command without transmission before backfill, giving them time to run `sources sharing disable`; an explicit `sources sharing enable` opts in immediately. New installations have no historical backfill and contribute the first newly confirmed job after displaying the notice. Existing confirmed ledger entries are the durable backfill/retry queue and are retried in bounded batches during later commands. No separate contribution command is required for applied jobs.
+
+Whenever the user or agent discovers a repeatable public discovery surface—not a recruiter profile, referral link, personal URL, or one-off job detail route—queue it for maintainer review:
+
+```text
+node scripts/job-application.mjs sources suggest --stdin
+node scripts/job-application.mjs sources pending
+node scripts/job-application.mjs sources sync
+node scripts/job-application.mjs sources jobs
+node scripts/job-application.mjs sources sharing status
+node scripts/job-application.mjs sources sharing disable
+```
+
+Suggestion input:
+
+```json
+{
+  "name": "Example Engineering Board",
+  "baseUrl": "https://jobs.example.org/openings/engineering",
+  "kind": "job-board",
+  "regions": ["global"],
+  "roleFamilies": ["engineering"],
+  "requiresSession": false
+}
+```
+
+The first eligible contribution displays a disclosure and sends during that command. `disable` stops both job and discovery-source sharing; `enable` resumes and retries it; `reset` disables sharing and removes its anonymous relay credentials. The preference, anonymous credential, and delivery receipts are stored in owner-only local files.
+
+The applied-job contract contains only the canonical HTTPS job URL, company, role, application channel, optional coarse discovery source, and a server-derived provider URL. Referral, tracking, and fragment data are removed; a small allowlist of stable job/requisition query identifiers is retained so query-addressed jobs do not collapse together. The server adds day-bucketed first/last-seen dates and an anonymous agent-report count. Candidate identity, résumé, form answers, score, application timestamp, referral parameters, raw installation ID, and contributor hash are never public or stored with a community job. Every accepted record is logged as pending; only a maintainer-reviewed destination and matching company/role can become public. Canonical URL deduplication prevents repeated rows, and rejected records never republish automatically.
+
+The client and relay use the same fail-closed source-route classifier. They remove query parameters and fragments; reject embedded credentials, credential-like opaque path segments, identity-like names and paths, personal profiles, local/private hosts, unknown fields, oversized payloads, and known detail routes from Workday, LinkedIn Jobs, Greenhouse, Lever, Ashby, Workable, and SmartRecruiters. Unknown domains are accepted only at the root or on explicit collection, directory, feed, careers, openings, or job-index routes. Only the source name, canonical public base URL, kind, regions, role families, and session requirement are shared.
+
+The raw anonymous installation ID authenticates and rate-limits a request but is never stored in the registry. The relay stores a source-scoped HMAC only to deduplicate contributions and help a maintainer prioritize review. One system contributes at most once to a canonical source, and `contributionCount` always means unique contributing systems—not people. It is never identity, trust, authority, or a condition for publication. The first valid contribution owns the canonical metadata; later contributions cannot rewrite it.
+
+If sharing is disabled or offline, repeatable-source suggestions remain in their owner-only queue and confirmed jobs remain pending in the canonical ledger until a minimal delivery receipt exists. `sources pending` reports both kinds of locally unsent work. `sources sync` retries both, and `sources list` performs a best-effort retry before reading the registry. A server-accepted source suggestion is delivered even while pending moderation. Network failure never blocks discovery or an application.
+
+Every accepted repeatable-source contribution remains in the private moderation queue until an owner explicitly approves it with owner-only D1 commands. Rejected sources remain hidden after later contributions and cannot republish automatically. Maintainer procedures are documented in [`telemetry-worker/COMMUNITY_SOURCE_MODERATION.md`](https://github.com/vaibhavarora14/job-application-agent/blob/main/telemetry-worker/COMMUNITY_SOURCE_MODERATION.md). This moderation rule does not delay sanitized confirmed-job links.