# Start Here (/docs)



OpenOpps v0.1 is a Python CLI for discovering firm hiring boards from aggregate sources, detecting public provider routes, syncing normalized jobs, caching repeated HTTP JSON requests, and exporting an auditable local opportunity ledger. Ingestion and durable state are CLI-driven; the published [Jobs](/) and [Explorer](/explorer) surfaces are a static docs workbench over a committed search snapshot, not a hosted sync service. There is no prompt UI or TUI.

<div className="not-prose my-6 rounded-2xl border border-primary/30 bg-primary/5 p-4 text-sm leading-6">
  <strong className="text-foreground">
    Browse the committed snapshot
  </strong>

  <span className="mt-2 block text-muted-foreground">
    Use the{" "}

    <a href="/" className="font-semibold text-primary hover:underline">
      Jobs
    </a>

    {" "}

    surface for open-role search and posting previews, or{" "}

    <a href="/explorer" className="font-semibold text-primary hover:underline">
      Explorer
    </a>

    {" "}

    for source, provider, route, and data-quality analysis.
  </span>
</div>

<div className="openopps-ref-grid">
  <div className="openopps-ref-card">
    <strong>
      Discover
    </strong>

    <span>
      Read source catalogs and persist durable board records.
    </span>
  </div>

  <div className="openopps-ref-card">
    <strong>
      Resolve
    </strong>

    <span>
      Promote provider hints into executable public job routes.
    </span>
  </div>

  <div className="openopps-ref-card">
    <strong>
      Export
    </strong>

    <span>
      Write normalized boards and jobs as JSONL, CSV, Parquet, or SQLite.
    </span>
  </div>
</div>

## Domain [#domain]

* `sources` are aggregate discovery catalogs such as `a16z`, `accel`, `lsvp`, `sequoia`, `bvp`, `greylock`, `kleinerperkins`, `southparkcommons`, `signalfire`, and `yc`.
* `boards` are firm/company hiring boards discovered from sources.
* `jobs` are normalized postings fetched from boards.
* `providers` are adapters that detect or fetch provider-specific boards, such as Ashby, Greenhouse, Lever, Workday, Workable, Teamtailor, BambooHR, Rippling, and WP Job Manager.
* `cache`, `plugins`, and `examples` cover operational cache inspection, installed Python plugin discovery, and deterministic demo data.
* `discovery` is an advanced quarantined scout (`openopps discovery scout|verify-scout|preview-promotion`). It does not write the daily snapshot and has no `--apply` path.

## Install and Run [#install-and-run]

Use `uv run` while working inside the repository checkout:

```bash
uv sync
just --list
uv run openopps --help
uv run openopps status
```

If you want `openopps` available directly from this editable checkout, install the repo as a uv tool from the repository root:

```bash
uv tool install -e .
openopps --help
openopps status
```

`uv tool install -e .` installs the console entry point from the current checkout. Runtime settings such as `OPENOPPS_DB_URL` still control where local SQLite state is read and written.

## First run [#first-run]

Before live syncs against public upstreams, initialize the durable SQLite schema for the database you intend to use:

```bash
uv run openopps admin db init
uv run openopps admin db status
```

`OPENOPPS_DB_URL` defaults to `sqlite:///openoppsdb.sqlite` relative to the process working directory. For an isolated smoke database, point at a dedicated file before `admin db init` and sync:

```bash
OPENOPPS_DB_URL=sqlite:///./tmp/openopps-smoke.sqlite uv run openopps admin db init
OPENOPPS_DB_URL=sqlite:///./tmp/openopps-smoke.sqlite uv run openopps examples seed --json
```

See [Configuration](/docs/configuration) for concurrency and job-route settings.

## Contributor Command Map [#contributor-command-map]

The root `Justfile` is the quickest way to discover local validation without hiding the underlying toolchain:

```bash
just --list
just quick
just ci
just openspec-validate-all
just web-check
just cli-help
```

`just ci` composes the `ci-python`, `ci-openspec`, `ci-web`, and `ci-artifacts` lanes. Those cover the Python release gate, strict OpenSpec validation, web type/build/unit/browser/accessibility/lint/search-artifact checks, Kaggle metadata/bundle smoke, and repository drift. Use the raw `uv`, `pnpm`, and OpenSpec commands from the reference pages when a CI failure needs exact reproduction; use `just ci-full` when network-dependent security audits and lowest-direct dependency tests are required.

## Safe Local Smoke Path [#safe-local-smoke-path]

These commands seed deterministic demo records and do not hit upstream source or provider services:

```bash
uv run openopps examples seed --seed 42 --boards 4 --jobs-per-board 2 --json
uv run openopps jobs list --source example --json
uv run openopps providers coverage --json
```

## Live Quickstart [#live-quickstart]

The commands below read public upstream catalogs and provider endpoints. They write local SQLite state unless a command is explicitly marked no-DB or dry-run.

```bash
uv run openopps sources list
uv run openopps admin sources test a16z
uv run openopps sources sync a16z --metrics-json --refresh-cache
uv run openopps sources sync accel --metrics-json
uv run openopps sources sync greylock --metrics-json
uv run openopps boards list --source a16z --limit 10
uv run openopps admin boards enrich --source a16z --json
uv run openopps providers health --source a16z --provider any --limit 25 --json
uv run openopps admin providers probe-routes --source a16z --provider any --limit 25 --json
uv run openopps jobs sync --provider ashbyhq --metrics-json --refresh-cache
uv run openopps cache status --json
uv run openopps plugins list --json
```

Unscoped list, export, and sync commands use the full known superset unless narrowed by `--source`, `--board`, or `--provider`. Provider filters accept `any` and `all` as aliases for removing the provider filter, which keeps reusable scripts explicit without narrowing to one provider.

Overlapping source coverage uses the persisted board keys shown by `boards list`, and provider requests are deduped before route probing or job sync. The relevant metrics include `duplicateRoutesSkipped`.

## Provider Levels [#provider-levels]

| Level         | Meaning                                                  |
| ------------- | -------------------------------------------------------- |
| `detect`      | OpenOpps can preserve provider metadata and route hints. |
| `jobs`        | OpenOpps can fetch public jobs for the provider.         |
| `unsupported` | The provider is known only as raw metadata.              |

Ashby, Greenhouse, Lever, public Workday CXS, Workable, Teamtailor, BambooHR, Rippling, and explicit WP Job Manager boards are job-capable in v0.1 through public no-auth routes. Manatal and Gem hints remain detect-only until stable public fetching is added. See [Providers](/docs/providers) for the generated provider registry and route diagnostics.

Ashby postings marked `isListed: false` are direct-link-only and are excluded from normal job sync output.

## Documentation Map [#documentation-map]

| Page                                               | Use it for                                                                                                                                                                                    |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [CLI](/docs/cli)                                   | Command groups, common flags, JSON output, filters, exports, and quarantined `discovery scout` / `verify-scout` / `preview-promotion`.                                                        |
| [Configuration](/docs/configuration)               | `OPENOPPS_` environment variables, isolated `OPENOPPS_DISCOVERY_*` scout limits, `.env` loading, and runtime policy.                                                                          |
| [Data Model](/docs/data-model)                     | Sources, boards, providers, jobs, exports, static indices, counts, and telemetry event-lake guidance.                                                                                         |
| [Providers](/docs/providers)                       | Source catalogs, eight required taxonomy fields, route diagnostics, and limitations.                                                                                                          |
| [Operations](/docs/operations)                     | Storage, cache, exports, quarantined scout accounting and promotion preview, policy declaration versus verification, validation, telemetry operations, Kaggle, and troubleshooting workflows. |
| [Public Data Releases](/docs/public-data-releases) | V7 manifests, source-rights gates, release-pinned web reads, static delivery, rollback, recovery, and the v6 cutover boundary.                                                                |
| [Agent Plugins](/docs/agent-plugins)               | Two Agent Plugins 1.0.0 packages (`openopps` and `openopps-dev`), local client paths, and MCP `help`/`run` filters.                                                                           |
| [Contributing](/docs/contributing)                 | Local setup, validation, docs generation, source-scout skill non-authority, and review expectations.                                                                                          |
| [Jobs](/)                                          | Filter and preview open roles from the static search index.                                                                                                                                   |
| [Explorer](/explorer)                              | Analyze source/provider coverage, route health, freshness, and data quality.                                                                                                                  |

## Public Docs Routes [#public-docs-routes]

The canonical jobs workbench is `/`, the canonical analytics explorer is `/explorer`, and thin job detail pages live at `/jobs/:id` for direct posting previews. Legacy `/jobs` redirects to `/`, and legacy `/docs/explorer` redirects to `/explorer`; do not add broad `/jobs/:path` redirects because detail pages must remain addressable.

## LLM-readable docs [#llm-readable-docs]

The docs app exposes machine-readable exports for agents and tooling:

| URL              | Purpose                                               |
| ---------------- | ----------------------------------------------------- |
| `/llms.txt`      | Compact index of documentation pages for LLM context. |
| `/llms-full.txt` | Full concatenated docs text for deeper retrieval.     |

Per-page markdown routes are also available under `/llms.mdx/` when you need a single MDX page in isolation.

## Route Probing Summary [#route-probing-summary]

Provider hints from source catalogs may not include the token or URL needed for job fetching. `admin providers probe-routes` tries candidate tokens from upstream slugs, remote ids, names, domains, and websites, then reports both matched routes and unknown boards with the candidate tokens it tried. Its JSON output includes per-provider selected/matched counts, unresolved reason counts, and duplicate route skips.

```bash
uv run openopps admin providers probe-routes --source a16z --provider all --limit 25 --json
```

Probing is read-only unless `--apply` is passed. Use [CLI](/docs/cli) for command flags and [Operations](/docs/operations) for local-state runbooks.