# Job Search

<!-- BEGIN GENERATED: guide-map -->
## Guide map

Read only the section needed for the next decision. Line ranges are exact
for this generated runtime target.

| Section | What it covers | Lines |
| --- | --- | --- |
| [Purpose](#purpose) | Scope, ownership, and the central operating question. | 27-31 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 32-38 |
| [Do Not Use This For](#do-not-use-this-for) | Boundaries and the correct routes for excluded work. | 39-48 |
| [Choose A Path](#choose-a-path) | Decision hierarchy for selecting the right capability or provider. | 49-62 |
| [Primary SDK Paths](#primary-sdk-paths) | Operating guidance and contracts for this section. | 63-71 |
| [Supporting References](#supporting-references) | Capability, provider, policy, and runtime guides for this outcome. | 72-82 |
| [Mental Model](#mental-model) | Concepts and state boundaries needed for correct operation. | 83-93 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 94-104 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 105-113 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 114-124 |
| [Data Contracts](#data-contracts) | Required identities, fields, evidence, handles, and durable shapes. | 125-138 |
| [Verification](#verification) | Evidence required before reporting success. | 139-146 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 147-156 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 157-166 |
<!-- END GENERATED: guide-map -->

## Purpose

Find current job openings and turn hiring evidence into qualified company or
contact rows. This is not the same as inspecting asynchronous SDK jobs.

## Use This When

Use this guide for job postings, companies hiring for a role, or people attached
to hiring evidence. Use `artifacts_jobs.md` only for provider-job lifecycle.
The hiring predicate owns this route regardless of whether the requested final
rows are jobs, companies, or contacts.

## Do Not Use This For

| Need | Owning Guide |
| --- | --- |
| Inspect, wait for, page, cancel, or export an asynchronous SDK job | `artifacts_jobs.md` |
| Discover companies for a predicate unrelated to hiring | `company-search.md` |
| Find people at companies without a hiring predicate | `contact-search.md` |
| Add facts to known jobs, companies, or contacts | The matching enrichment guide |
| Convert hiring evidence into alerts or outbound activation | `signals.md`, then the notification or outbound owner |

## Choose A Path

1. Define the job predicate, freshness window, geography, and desired company or
   contact output.
2. Use `audience_discovery.md` for structured job postings, hiring-qualified
   companies, or contacts derived from active postings. When company LinkedIn
   URLs are known, use the company-filtered job source and qualify its
   high-recall output.
3. Use `web-research.md` for an explicit job URL, an official careers page, or
   a source the structured jobs surface does not cover. Use
   `artifacts_jobs.md` only to resume or page the resulting asynchronous job.
4. Preserve the canonical job URL, observed date, company identity, title, and
   location before deriving a GTM signal.

## Primary SDK Paths

<!-- BEGIN GENERATED: primary-sdk-paths -->
| Primary function | Choose it when | Required inputs | Returns | Exact contract |
| --- | --- | --- | --- | --- |
| `vf.sources.jobs.find_jobs` | Use when the requested evidence is job postings or hiring-qualified companies. Optionally constrain to known LinkedIn company URLs. | None | `pending_jobs` | [`audience_discovery.md`](audience_discovery.md) · installed SDK: `verbiflow/sources.py:550-744` |
| `vf.sources.jobs.find_contacts` | Use when the final deliverable is people derived from companies with matching active job postings. | `job_title_tags` | `pending_artifact_job` | [`audience_discovery.md`](audience_discovery.md) · installed SDK: `verbiflow/sources.py:428-534` |
<!-- END GENERATED: primary-sdk-paths -->

## Supporting References

Open only the child that resolves the next material decision.

| Reference | Use it for | Kind |
| --- | --- | --- |
| [`artifacts_jobs.md`](artifacts_jobs.md) | Durable artifact paging, job polling, cancellation, and export handles. | capability |
| [`audience_discovery.md`](audience_discovery.md) | Provider-neutral acquisition, qualification, source quality, and audience evidence. | capability |
| [`web.md`](web.md) | Public web search, page extraction, screenshots, Markdown, and browser evidence. | capability |
| [`sources.md`](sources.md) | Classify ambiguous source-shaped work and choose the owning acquisition surface. | policy |

## Mental Model

The job posting is the observed event. A company or contact derived from that
posting is a separate entity whose qualification must cite the posting. Keep
one posting, one company, and one contact as distinct row identities even when
the requested deliverable contains only one of those entity types.

Freshness is part of membership. An old or closed posting may be useful history,
but it is not evidence that the company is hiring now unless the user's predicate
explicitly allows it.

## Preflight

1. Define the posting predicate, observation window, geography, target entity,
   required fields, and maximum rows.
2. Decide what counts as current and how closed, undated, duplicated, or
   syndicated postings will be handled.
3. Confirm whether the source should be structured job discovery, an explicit
   URL, or an official careers page through the existing choice hierarchy.
4. Bound source pages, companies, titles, concurrency, and deadline before a
   broad search.

## Risk And Side Effects

| Stage | Risk | Rule |
| --- | --- | --- |
| Inspect an explicit posting or bounded sample | Read or bounded provider work | Preserve canonical URL, source, and observation time. |
| Start broad structured discovery | Provider work, credits, and durable artifacts | Bound titles, geography, freshness, pages, rows, and no-progress behavior. |
| Derive companies or people | False inference or identity mismatch | Preserve the posting-to-entity edge and independently qualify the derived row. |
| Turn hiring evidence into a signal | Prioritization or notification effect | Leave interpretation and delivery to `signals.md` and the relevant activation guide. |

## Canonical Operating Pattern

1. Record the job predicate and requested final entity.
2. Select one source path and inspect a bounded sample for schema, freshness,
   canonical URLs, and relevance.
3. Acquire with explicit limits and preserve each raw posting identity.
4. Normalize company identity, deduplicate postings, apply freshness and content
   qualification, and retain rejected reasons.
5. Derive company or contact rows only through explicit posting relationships.
6. Materialize the final entity artifact with posting evidence and limitations.

## Data Contracts

Each qualified posting should retain:

- canonical job URL or stable provider posting ID;
- title, company identity, location, source, and observed time;
- posted time and closed/active state when available;
- freshness and membership decision with reason;
- source receipt and any ambiguity or missing-field status.

Derived company or contact rows must retain the posting identity, relationship
type, and qualification rule that produced them. Do not collapse posting count,
company count, and contact count into one metric.

## Verification

Re-open representative source URLs, verify freshness and membership, distinguish
one job from one company, and verify the final rows match the requested entity.

Inspect duplicates, stale or closed postings, accepted and rejected rows, and
the exact final artifact bytes.

## Troubleshooting

| Symptom | Likely Cause | Next Step |
| --- | --- | --- |
| Results match keywords but not the hiring intent | High-recall source results were not qualified. | Apply the complete posting predicate and inspect rejected examples. |
| Old or closed postings appear current | Observation time was confused with posting freshness. | Recheck posted/closed evidence and preserve unknown freshness explicitly. |
| Several URLs represent one opening | Syndication or tracking variants were treated as distinct jobs. | Prefer canonical URLs/provider IDs and retain source variants as evidence. |
| Company totals look inflated | Postings were counted as companies. | Deduplicate company identities independently from posting identities. |
| The source job completed but no deliverable exists | Provider-job lifecycle was mistaken for the requested outcome. | Read the artifact, qualify rows, and materialize the requested entity output. |

## Related References

| Next Decision | Read |
| --- | --- |
| Select structured job acquisition | `audience_discovery.md` |
| Inspect an explicit URL or careers page | `web-research.md` |
| Resume or page the asynchronous source job | `artifacts_jobs.md` |
| Turn hiring evidence into a why-now signal | `signals.md` |
| Enrich derived companies or contacts | `company-enrichment.md` or `contact-enrichment.md` |
| Publish the final rows | `artifacts.md` |
