Jev SEO

Jev SEO

One command, one homepage URL, a complete audit. The operating rule is the Jev brain's: a source finds, code decides, Jev judges, Claude writes. Code crawls, counts, parses and scores. Jev answers only narrow semantic questions, with probabilities kept. You (the lead agent) review the evidence and write the narrative. Nobody invents a number.

The CLI lives in this skill folder. Call it through bin/jevseo using the skill's base directory, for example "<skill-dir>/bin/jevseo" doctor.

Workflow

1. Resolve the input. The user supplies a homepage URL. If none was given, ask for it (one question). Accept a bare domain. Only public sites: the crawler refuses private and local addresses by design.
2. Preflight. Run bin/jevseo doctor. It reports dependencies and whether TYPESAFE_API_KEY and PAGESPEED_API_KEY exist (never their values). Without the TypeSafe key, the audit still runs and marks the Jev sections as not assessed and the score as a partial audit; say so. Keys are read from the environment, then $JEVSEO_ENV_FILE, ./.env, the repository's .env (template: .env.example), then ~/Desktop/Keys/.env.
3. Audit live, and keep the user posted. Before running anything, tell the user in one line that the audit has started, which site, and that it usually takes 1 to 4 minutes. Then start it in the background so the conversation never sits silent:

   "<skill-dir>/bin/jevseo" audit <url> --out "<reports-dir>/<domain>-<YYYY-MM-DD>"

   The CLI streams timestamped progress to stderr in seven stages (== 1/7 Crawl to == 7/7 Render) with live counters: URLs crawled and queued, Jev pages judged with spend so far, each PageSpeed run as it lands. Read the output as it grows and relay one short line per stage (for example "Crawl done: 15 URLs. Jev is judging 13 pages."). Do not dump raw logs. Default reports dir: ./jev-seo-reports/ in the current project unless the user names one. Defaults: 60 pages, depth 5, 10 minute crawl budget, Jev budget cap 0.25 USD (a 60 page run costs about 0.01 USD), 3 pages on PageSpeed. Options are in the table below.
4. Read the digest, not the raw JSON. Open <out>/digest.md. It lists scores, every action with ID, priority, impact, effort, evidence, Jev review flags, what passed, PageSpeed and the Jev ledger. Open audit.json only to check a specific fact.
5. Review before writing. Spot-check each P1 and any surprising finding against its evidence (fetch the URL if needed). If a finding is a false positive, say so in the narrative rather than hiding it, and note it for a rule fix. Actions flagged "to verify" carry Jev answers outside the decisive band: present them as signals, not verdicts.
6. Write narrative.json in the output folder, following references/narrative.md. Ground every sentence in the digest, cite action IDs (JEV-003), use the site's own words where helpful, and add no metric that the audit did not measure. Copy numbers exactly from the digest (it lists confidences, field-data level and URLs per action); write counts as digits so they can be checked. Describe what a finding's URLs actually are (an orphan list can mix posts and legal pages). Do not infer causes the audit did not observe. The renderer refuses unknown action IDs and warns about any number that matches nothing in the audit: fix every warning and re-render before delivering.
7. Render. "<skill-dir>/bin/jevseo" render <out> writes report.pdf, report.xlsx, report.md (plus report.html and charts/). Use --formats pdf etc. to limit formats.
8. Look at it. Rasterise two or three PDF pages (pdftoppm -r 60 -png -f 1 -l 3 report.pdf /tmp/p) and view them. Fix layout problems before reporting.
9. Report back. Lead with the score and the three to five actions that matter most, then the file paths, Jev cost, pages crawled, and limits (page cap reached, no field data, Jev answers to verify, keys missing). Offer to go deeper on any action.

Full mode (--full). Adds DataForSEO: ranking keywords and positions, estimated traffic (ETV), competitors, referring domains compared with those competitors, keyword ideas, suggestions and gaps, live Google results for the top keywords (including whether AI Overviews cite the site), and mentions in AI answers. Jev then judges every keyword's relevance, drops searches for other brands, and maps each keeper to the page that should own it (or says a new page is needed). DataForSEO is paid per call, about 0.30 USD for one site, with a hard --dfs-budget cap (default 1.00 USD). Use it when the user asks for the full version, rankings, keywords, competitors or backlinks; tell them the expected cost first. Default the market to the United States (--location-code 2840 --language en) unless the user names another. To iterate without paying again, reuse collected data: --full --reuse-dfs <earlier-audit-dir>. Volumes, difficulty and ETV are DataForSEO estimates; say so.

bin/jevseo rescore <dir> rebuilds findings, scores and the digest from a saved audit with no network or spend (useful after a rule change; action IDs may shift, so re-check narrative.json).

bin/jevseo run <url> does steps 3 and 7 in one go with an automatic evidence-only summary. Use it only when the user wants speed over a written narrative.