Reference #

Technical reference for logging, repository layout, and troubleshooting common issues.

Pages in this section #

Logging #

All Raven job commands emit live progress and write timestamped log files.

Default behavior #

Progress phases printed to stdout
Summary line with counts and elapsed time
Log file written to data/logs/

Example log paths:

data/logs/discover-2026-07-04T08-30-00.log
data/logs/draft-2026-07-04T08-35-12.log
data/logs/sync-jobs-2026-07-04T07-00-00.log
data/logs/send-2026-07-04T09-00-00.log

Flags #

Flag	Effect
(default)	Live progress + log file
`--verbose`	Extra detail (per-ATS logs during discover)
`--quiet`	One-line summary only
`--no-log`	Disable log file (stdout only)

Commands with logging #

raven discover
raven draft
raven sync-jobs
raven scan-ats / scan-boards
raven query
raven send

Log contents #

Typical discover log:

File layout

Repository layout #

raven/
├── bin/raven              # CLI entry (npm link → global raven)
├── raven                  # Symlink to bin/raven
├── scripts/               # Bash wrappers (_lib.sh, discover.sh, draft.sh, …)
├── jobs/                  # Node.js job engine
│   ├── discover.mjs       # Unified discovery orchestrator
│   ├── draft-outreach.mjs # Draft orchestrator
│   ├── lib/               # Shared modules (profile, resume, log, portals, …)
│   └── plugins/           # Optional plugins (gemini-draft.mjs)
├── config/
│   ├── portals.example.yml
│   ├── profile.example.yml
│   └── outreach.example.yml
├── files/
│   └── resume.example.md  # Template resume
├── data/                  # Gitignored runtime data
│   ├── jobs.json          # Latest discover results
│   ├── jobs.db            # openjobdata SQLite index
│   ├── cache/             # Resume parse cache, ATS slug lists
│   └── logs/              # Command logs
├── drafts/                # Generated outreach CSV/MD/XLSX
├── docs/                  # Markdown docs (source for this site)
└── raven-web-docs/        # Hugo documentation site

Tracked vs gitignored #

Tracked (committed)	Gitignored (local)
`*.example.yml`	`config/profile.yml`
`files/resume.example.md`	`config/portals.yml`
Source code	`config/outreach.yml`
	`files/resume.md`
	`data/*.json`, `data/jobs.db`
	`data/logs/`, `data/cache/`
	`drafts/outreach-*`
	`.env`

Key data files #

Path	Created by	Purpose
`data/jobs.json`	`raven discover`	Latest job matches (default draft input)
`data/jobs.db`	`raven sync-jobs`	Local openjobdata index
`data/cache/resume-parsed.json`	`raven draft`	Parsed resume cache
`drafts/outreach-*.csv`	`raven draft`	Send-ready spreadsheet

npm scripts #

Equivalent to ./raven subcommands:

Troubleshooting

Troubleshooting #

Common issues and fixes.

`raven: command not found` #

# From repo root
./raven --help

# Or install globally
npm link
raven --help

If npm link resolves to the wrong path, use ./raven from the repo root.

`raven draft` — no input file #

Discover auto-saves to data/jobs.json. Run discover first:

raven discover --q "engineer"
raven draft --max 25

Or pass explicit input:

raven draft --input data/jobs.json

Unrelated jobs (nurse, sales, etc.) #

Bare raven discover reads config/portals.yml. Fix filters:

Quick diagnostics #

./raven discover --verbose          # see per-source progress
ls -lt data/logs/                   # find latest log file
tail -50 data/logs/discover-*.log   # inspect filters and matches
./raven draft --refresh-resume      # re-parse resume after edits

Important paths #

Path	Purpose
`data/jobs.json`	Latest discover results (default draft input)
`data/jobs.db`	Local openjobdata index
`data/logs/`	Timestamped command logs
`data/cache/resume-parsed.json`	Parsed resume cache
`drafts/outreach-*`	Generated application drafts

Gitignored (local only) #

config/profile.yml, config/portals.yml, .env, files/resume.md, data/*.json, drafts/

Start with Logging →