jobyssey/.agents/skills/jobsdb-search/SKILL.md

---
name: jobsdb-search
version: 1.0.0
description: >
  Use this skill to search the local SQLite snapshot of job postings at
  documents/postings/jobs.db (~87k postings across ~10k companies, scraped from
  Greenhouse/Ashby/Lever/Workday boards, enriched with company sector, funding
  stage, crypto-native flag, and a priority tier). Trigger phrases: search the
  postings database, jobs.db, local job snapshot, which target companies are
  hiring, crypto/fintech roles in New York or San Francisco.
context: fork
enabled: true  # set to false to keep this portal installed but have /scrape skip it
allowed-tools: Bash(bun run .agents/skills/jobsdb-search/cli/src/cli.ts *)
---

# jobsdb Search Skill

Searches a **local SQLite snapshot** of job postings with `bun:sqlite`. No network,
no credentials, zero dependencies. The database is user-supplied at
`documents/postings/jobs.db` (override with `JOBSDB_PATH`); it is git-ignored
personal data, not part of the framework.

## ⚠️ This is a static snapshot, not a live board

Rows carry the `scrape_timestamp` they were captured at (currently May 16 to
Jun 1, 2026). Two consequences for `/scrape`:

- **Recency is relative to the snapshot.** `--jobage N` means "posted within N
  days of the row's own scrape date". Do **not** apply the calendar 14-day cutoff
  to this portal's `date` field; it would drop everything. Treat `meta.snapshot`
  as "today" for this source and say so in the results table.
- **Postings may have closed.** Every hit must be confirmed live by fetching its
  `url` before it is presented or ranked. A 404 or "job closed" page means skip.

Refresh the snapshot by replacing the `.db` file; the CLI needs no changes.

## Commands

### Search

```bash
bun run .agents/skills/jobsdb-search/cli/src/cli.ts search [flags]
```

- `-q, --query <text>`: FTS5 full-text match on title, company, and location. Tokens are AND-ed; quoting is handled for you.
- `--company <text>`: company name contains text.
- `--location <text>`: location text contains text (`"New York"`, `"San Francisco"`, `Remote`).
- `--country <code>`: exact `location_country` (e.g. `US`).
- `--remote <list>`: comma list of `remote` (global), `remote-regional`, `hybrid`, `onsite`.
- `--seniority <list>`: comma list of `senior`, `staff_principal`, `manager`, `director`, `head_of`, `vp`, `c_level_founder`, `mid_unclassified`, `junior_associate`, `intern`, `unclassified`.
- `--sector <list>`: company `target_sector`: `crypto`, `fintech-nc`, `ai-ml`, `devtools`, `enterprise-saas`, `hardware`, `other`. Most companies are untagged; omit this flag for a wide net.
- `--crypto-native`: only companies flagged crypto-native (~4.4k postings).
- `--tier <n>`: company `priority_tier` at or below n (1 = highest-priority target list).
- `--jobage <days>`: posted within N days of the snapshot (see warning above).
- `--page <n>`, `-n, --limit <n>` (default 20), `--format json|table`.

Unknown flags exit 1 with `{"error":...,"code":"BAD_ARG"}` on stderr.

### Detail

```bash
bun run .agents/skills/jobsdb-search/cli/src/cli.ts detail <posting_id|url> [--format json|plain]
```

The snapshot stores **no description text**. `detail` returns the structured row
(title, company, location, remote class, seniority, salary range when stated,
sector, tier, ATS, resolved date) and the URL; fetch the URL for requirements.

## Usage examples

```bash
# Senior/staff backend roles at crypto-native companies in NYC, snapshot-recent
bun run .agents/skills/jobsdb-search/cli/src/cli.ts search -q "backend engineer" --crypto-native --location "New York" --seniority senior,staff_principal --jobage 30 --format table

# Everything at tier-1 target companies, remote or hybrid
bun run .agents/skills/jobsdb-search/cli/src/cli.ts search --tier 1 --remote remote,hybrid -n 50 --format table

# Founding engineer roles anywhere
bun run .agents/skills/jobsdb-search/cli/src/cli.ts search -q "founding engineer" --format table

# Go / protocol roles
bun run .agents/skills/jobsdb-search/cli/src/cli.ts search -q "protocol engineer" --sector crypto -n 20
```

## Output

Search JSON is `{ "meta": { "count", "page", "total", "snapshot", "db" }, "results": [...] }`.
Each result carries `id`, `title`, `company`, `location`, `date` (ISO, resolved
from ISO or "Posted N Days Ago" text; `date_approximate: true` when the source
said "30+ days"), `url`, `description` (always `null`, see Detail), plus `remote`,
`seniority`, `salary`, `sector`, `crypto_native`, `priority_tier`, `ats`, `snapshot`.
Results are ordered by company priority tier, then newest scrape first.

## Notes

- Workday rows often have no posted date at all; they come back with `date: null` and are dropped by `--jobage`. Search without `--jobage` to include them.
- `location_text` is free text from each ATS ("2 Locations", "US-TX-HOUSTON-011"); `--location` is a substring match, so try the city name without the state.
- The `companies` table also holds funding, headcount growth, GitHub activity, and investor data; this CLI exposes only sector, crypto flag, and tier. Query the `.db` directly with `sqlite3` for anything else.