job-application-agent 3.1.1 → 3.1.2

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. Repeatable public boards and feeds found by users or agents are sanitized and shared by default through `sources suggest --stdin`; disable this independently with `sources sharing disable`. Each contribution enters a private pending moderation queue. Only a maintainer-reviewed source becomes publicly searchable. One-off jobs, personal profiles, referral parameters, and candidate data are never published as sources, and every lead must still resolve to a direct employer or ATS before use.
+
 ## 🔐 Privacy
 
 | Data | Where it stays |
@@ -108,15 +111,20 @@ 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 |
+| Source-sharing preference | 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 source sharing is also enabled by default, separately from analytics. It shares only sanitized metadata for repeatable public job-discovery surfaces. The registry stores no raw installation IDs; source-scoped contributor hashes and counts are used only for deduplication and moderation prioritization, 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
 ```
 
 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 +151,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 source sharing and 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 list` (optionally filtered) and search the highest-signal packaged and maintainer-reviewed community sources. Resolve every lead to the direct employer or ATS page.
+2. Attribute the lead with coarse `discoverySource`, stable packaged-catalog `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. 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,11 @@ 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 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 source sharing is a separate default-enabled feature with independent `sources sharing status|enable|disable|reset` controls. It does not send analytics events or store a raw contributor identity with a source; a source-scoped HMAC is used only for unique-system counting. See [`SOURCES.md`](SOURCES.md) for its exact public metadata contract.
+
 ## 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` remains local and is not included in telemetry. `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,66 @@
+# 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 newly discovered sources contributed by users and agents. Both are 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
+```
+
+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 community registry. Public v1 community entries are always maintainer-approved and have `registryStatus: "community-reviewed"`. They include a `communitySourceId` and remain 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. Respect `requiresSession`; do not upload a résumé or transmit profile data merely to unlock discovery unless the candidate has authorized that destination.
+
+Store three independent attribution fields when available:
+
+- `discoverySource`: coarse compatible channel such as `linkedin`, `x`, `yc`, `job-board`, or `user-supplied`.
+- `discoverySourceId`: stable catalog ID such as `yc-work-at-a-startup` or `hacker-news-who-is-hiring`.
+- `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 source sharing is enabled by default and independent of usage analytics. Whenever the user or agent discovers a repeatable public discovery surface—not a one-off company job, recruiter profile, referral link, or personal URL—queue and contribute it:
+
+```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 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 contribution displays a disclosure and sends during that command. `disable` stops future sharing; `enable` resumes it; `reset` disables sharing and removes its anonymous relay credentials. The source-sharing preference and anonymous credential are stored in an owner-only local file.
+
+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, suggestions stay in the owner-only local queue. `sources pending` reports only these locally unsent suggestions; it does not expose server moderation status. `sources sync` retries locally unsent suggestions, and `sources list` performs a best-effort retry before reading the community registry. A server-accepted contribution is considered delivered even while its source is pending publication. Network failure never blocks discovery or an application.
+
+Every accepted community contribution remains in the private pending queue until an owner explicitly approves it with the owner-only D1 moderation commands. Rejected sources remain hidden after later contributions and cannot republish automatically. Maintainer commands and metadata-correction 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). Never publish candidate identity, job history, prompts, referral parameters, private URLs, contributor hashes, or one-off jobs.