jev-sources
Finds and quotes TypeSafe's docs on Jev, including Noul, Choice, Score and Box questions, models and limits. Use when a question, review, design or claim involves Jev or System One, when briefing a subagent on Jev work, or when relaying a subagent's Jev finding.
Install
npx skills add https://github.com/tiffygk/jev-mode/tree/main/jev-sources
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install tiffygk-jev-mode@llmmart
git clone https://github.com/tiffygk/jev-mode.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole tiffygk/jev-mode collection as a plugin from our marketplace. Git is the plain clone.
README
Jev Sources
Hate when your coding harness hallucinates Jev functionality or implements Jev from memory? Want to avoid a research agent getting called every session? Jev Sources (updated for 1.14) matches your question by keywords and meaning. Only the most relevant TypeSafe documentation sections land in your coding harness's context.
It answers Jev questions from TypeSafe's official docs, cookbooks, patterns and blog posts. It never calls Jev: your coding agent's Claude or Codex model does the reading, so no TypeSafe key is needed.
Sample
jev.py on "can I put 30 passages in one call?", trimmed
How many questions you can ask
CITE AS: docs/primitives.md#How many questions you can ask (reference rule)"There is no limit on the number of questions in a request."CITE AS: cookbooks/parallel_questions.md#Parallel questions (cookbook example)
Labels
Each section jev.py finds gets a label:
| Label | The model | Set when |
|---|---|---|
| READ FULL | Reads it all before any claim | Short, or the question limits a design |
| EXTRACT | Gets a pointer; claims from it are unverified | Long, or matched by meaning only |
| NEEDS | Names the model the section needs; reads it last when you named an older one | The page needs a newer model than yours (or than jev-latest), per a list of TypeSafe's stated limits |
| EXPERIMENTAL | Quotes TypeSafe's line that it isn't production-ready | TypeSafe calls it experimental (same list) |
How it works
- A hook sees a Jev message and tells the model to run
jev.py. jev.pymatches your question to the docs two ways, then reads the best matches:- Keywords rank sections and boost reference rules; names like
request_idalso match their parts. - A small offline model compares meanings and adds up to two sections the keywords missed.
- Both read the docs without the site's display code stuffing context.
jev.pyreads the READ FULL sections, reference rules first, up to a size cap. The model reads small leftovers itself; past a third of the cap, subagents read the rest.- A question reads what it asks. A build request runs one question per part and names any that found nothing.
- Keywords rank sections and boost reference rules; names like
- The model answers in its own words, citing each section and label, or says "the docs don't say". A hook sends back misquotes and citations to missing sections.
| Step | Who enforces it |
|---|---|
| Routing, labels, reading order, cap | Code, once the model runs jev.py |
| Reminder; refusing subagent instructions without their source line; checking citations, a subagent's or the answer's | Hooks, once installed |
Running jev.py, the answer, its sources |
The model, following SKILL.md |
Data stays in ~/.claude/jev-sources-data/; JEV_LOG=off stops logging your questions.
How it stays current
With the hooks installed, your first Jev message after two days starts a background check for new or re-dated TypeSafe pages. A later message names any changes. If no check finishes in seven days, the model tells you to run the refresh command. Without the hooks, run refresh.sh --fetch yourself.
Each check confirms the index matches the saved pages and flags any mismatch or broken page. After a page changes, it also reruns the routing tests and lists the citations it affects. With pytest installed, it runs the library tests; JEV_LIBRARY_TESTS=off skips them.
What it reads
It reads TypeSafe's docs (including Models and the API and SDK reference), patterns, cookbooks and blog posts (labeled vendor claims). SOURCES.md in the data folder lists every page your copy holds and when it was saved. Updated for Jev 1.14, including image input and Box questions, both experimental per TypeSafe.
Where the rules come from
Jev Sources adds no rules. It cites TypeSafe and says each page's kind: reference pages say what the API allows; cookbooks show one working build. A cookbook that sends one request per item shows one way to build it; a reference page or its scope note says whether you must. Rating a design is a separate skill, Jevaluate.
How accurate it is
| Questions | n | Difficulty | Counts as found when the section is | Found (recall), with 95% confidence interval |
|---|---|---|---|---|
| Everyday questions | 21 | 🟢 Easy | listed, at any label | 95% (20 of 21; 77% to 99%) |
| Everyday questions | 21 | 🟢 Easy | printed in full within the cap | 90% (19 of 21; 71% to 97%) |
| Release-check questions | 23 | 🟢 Easy | printed in full within the cap | 100% (23 of 23; 86% to 100%) |
| New questions, blinded | 11 | 🟡 Medium | marked READ FULL | 64% (7 of 11; 35% to 85%) |
| New questions, blinded | 11 | 🟡 Medium | on the same page as the answer | 91% (10 of 11; 62% to 98%) |
| SDK questions, blinded | 24 | 🔴 Hard | printed in full within the cap | 42% (10 of 24; 24% to 61%) |
| Broad first-time goals, blinded | 12 | 🔴 Hard | read or left for later reading | 49% of needed sections (40% to 60%); unsplit, 9% |
How to read it:
- 🟢 Easy questions cover the docs broadly; the routing was tuned on them.
- 🟡 Medium questions cover the same ground, but the routing never saw them. Expect these numbers on new questions.
- 🔴 Hard questions each ask about one function, field or error in the SDK reference.
- Listed means the section is anywhere in the list
jev.pyreturns. Printed in full is stricter: the whole section, within the cap. - Found is recall: the share of questions whose section was found. For goals, it is the average share of each goal's needed sections, as a separate reviewer marked them. Ranges are 95% confidence intervals (Wilson; bootstrap for goals), wide on small rows.
- Broad goals are first-time requests, such as moving a classifier to Jev, blinded. Splitting reads about 4 times the tokens.
The table measures jev.py once it runs; scripts/firing_report.py shows how often the reminder hook prompts it. Live sessions in projects that say they use Jev met blind answer keys on 18 of 19 tests, twice, and 10 of 11 held out.
Install and use
Needs Claude Code or Codex, git and Python 3.8+. Meaning matching needs model2vec, installed by the first refresh.
Claude Code plugin, with hooks:
claude plugin marketplace add tiffygk/jev-mode
claude plugin install jev-sources@jev-mode
Codex plugin:
codex plugin marketplace add tiffygk/jev-mode
codex plugin add jev-sources@jev-mode
Then ask your agent to refresh. Codex runs no plugin hooks: have it run scripts/codex_hooks.py install. By copy (Codex: ~/.agents/skills/ throughout):
git clone https://github.com/tiffygk/jev-mode
mkdir -p ~/.claude/skills
cp -r jev-mode/jev-sources ~/.claude/skills/
bash ~/.claude/skills/jev-sources/refresh.sh --fetch
python3 ~/.claude/skills/jev-sources/scripts/jev.py "can I put 30 passages in one call?"
Copy installs add hooks by hand: hooks/install-hooks.md.
To install every jev-mode skill at once, or to copy skills by hand, see the repo README.
Limits
A page TypeSafe edits without updating its sitemap date stays stale until a full refresh (refresh.sh --fetch). A question worded unlike the docs can miss its section. Not affiliated with TypeSafe.
License
PolyForm Noncommercial 1.0.0: free for personal and noncommercial use, with credit. Company or paid use needs a commercial license: open an issue.
Skill manifest
Jev sources
Answers about Jev rest on TypeSafe sections you opened in full this session, found by the router, not by grep or memory. This skill decides what to read; deciding what it means for a design belongs to jev-mode/shared/jev-rules.md.
Before any Jev claim
<skill> below is this skill's base directory, shown when the skill loads; write it out in full, since the shell runs in the user's project. Run one command and read what it prints:
python3 <skill>/scripts/jev.py "<the question, in your words>" --docs-words "<the same question in the docs' words>"
Add --model <id> when the project pins a model. The docs' words are the terms the docs use (for example "second request", "depends on", "one request", "Choice options", "threshold"); the command routes both phrasings and merges them. It reads every READ FULL section, reference rules first, then patterns, SDK pages, cookbook examples and vendor claims, within the bundle cap (--cap N), and starts each with a CITE AS: line to quote. Route each separate question on its own.
- A section printed under
NOT YET READcomes with itsread.pycommand: run it before relying on that section. These leftovers are at most a third of the cap; more go to readers. - An
EXTRACTline points somewhere (read.py '<id>' --extract <word> <word>). A claim resting on it is labeled unverified. - If it prints "no section found", say so, then run
JEV_LIBRARY_TESTS=off bash <skill>/refresh.sh --fetchand ask again. Never fill the gap from memory, even when asked to answer from memory or in a hurry: the lookup takes seconds, so run it, keep the answer to a few lines, and cite.
Questions and builds
A question, broad or narrow ("where do I start", "is Jev right for this"), gets one jev.py run on what it asks. Add --also only for parts the question itself raises; a volume, a deadline or code that will call the API raises rate limits, errors and cost at that volume, so route and answer those now. When the printout covers more, use only the sections that answer the question. Answer it, with at most three next steps, and name in one line what they will need when they build, to look up then.
Building
When the person says they are building, asks for a plan, is in plan mode, or pastes code to fix, run one jev.py with one question per part: jev.py "<part 1>" --also "<part 2>" --also "<part 3>".
- Write 3 to 8 questions, one per part this build has (the question type, sending at volume, errors and retries, model version, the closest pattern or cookbook); add no part it lacks. Choosing between options routes each option.
- Read the
COVERAGE:block; relay eachNO SOURCE FOUNDquestion as "the docs I routed don't cover
Over the cap
When jev.py prints READING PLAN, the unread sections are more than a third of the cap. Keep the sections it already printed in full; don't read them again. It also prints one READER BRIEF block per batch: start one read-only reader subagent per block, with the block pasted whole as its brief. Batches may run in parallel. The MAP lines list the unread headings to choose from; never state a fact from a MAP line.
Where you can't start subagents, read at most one batch yourself, the sections your task relies on: write its finding lines under that batch's JEV-READER: line. If the task needs more, say which parts to split into separate tasks. Then check the replies through a quoted heredoc:
python3 <skill>/scripts/check_findings.py <plan_id> <<'REPLIES'
<every reader's reply>
REPLIES
Relay only OK lines as checked. A batch it lists as missing or EMPTY is unread: tell the user which sections those are. In Claude Code, a hook also checks each reader's reply before the reader returns.
The answer
A Jev answer has these parts, in order:
- The direct answer, in one or two sentences ("yes, on Jev 1.14 only"). Write part 2 first, then build this from its sentences: no fact that part 2 doesn't cite, and no estimate of yours (that goes under My read). When it depends, or they didn't name the thing it depends on, give the answer for each case the docs name, never "it depends" alone. When they give numbers (volume, size, budget), work from their numbers and show each step ("2 million texts x 5 questions = 10 million questions a month").
- What the docs say: only the facts the direct answer, the next steps or My read rely on. Every sentence stating how Jev or TypeSafe works (a limit, price, output, retry, failure or version) goes here, in your own words, one fact per sentence, with the
path#headingfrom itsCITE AS:line in backticks beside it, and that line's label: reference rule (what the API allows), pattern, cookbook example (one build TypeSafe published), sdk reference or vendor claim. Keep each number, unit, name and model ID exactly as the section writes it, and keep its strength and conditions: can or must, up to or exactly, which model, EXPERIMENTAL. Give TypeSafe's exact words, in quotation marks, only when the person asks for the wording. Cite only the library: a page fetched from the web has noCITE AS:line and can't be checked. For a link, use theURL:on the section'sSOURCE:line. - Coverage and gaps, one line each: what you read, and any section you left unread or sent to readers; each thing they asked that the docs you read don't cover, named ("the docs I read don't cover
- My read: your advice for this person's case, labeled as yours and holding no Jev facts (those go in part 2), on the topics their question raises: one line for each detail they gave (their data and how messy it is, volume, languages, sensitive data, a pinned older model) and each case their wording leaves open (ties, mixed languages, items that fit no option). With a volume or code, or on a build, add: how to test on their own data; what to do on errors, rate limits, timeouts and low confidence; a human check before any risky action. Route each such topic first and cite the docs where they speak.
- Next steps: a short numbered list they can start on.
A narrow question gets the direct answer and its citation, and nothing it didn't ask for. A plan to confirm gets each part checked against the docs (question type and wording, the cases it must tell apart, cost and limits at their volume), then yes, no, or yes with changes.
Pasted code or a pasted request gets a fix list, and a question on how to call the API gets the call, in place of parts 1 and 2 (part 3 stays), most serious first, each line in this shape:
1. <the change or step>, per `path#heading` (label)
- One numbered line for each Jev call or request: its shape (auth, headers, body), each field read from the result, each model ID and how to pin it, and, whatever the code does, errors and rate limits. Route them with the code's purpose:
--also "API errors and handling rate limits" --also "model aliases and pinning a version". Every line carries a citation; where no section you read shows it, mark that line "unconfirmed". Code you write or adapt is labeled as yours. - Then My read, one line each: secrets in source; comparisons that break on free text. Then the corrected code, with error and rate-limit handling in it.
Before sending, check the answer's citations and any quotes (in Claude Code a stop hook also does):
python3 <skill>/scripts/check_answer.py <<'ANSWER'
<the answer>
ANSWER
Fix each line it prints: cite the section that holds the fact, correct a quote from its section, or label it unverified. Wording you made up (an example question or option) and the user's own text (their error, log or message) go in backticks, never quotation marks: quotation marks are for the docs' words only. Send only the corrected answer, with no note about the check.
A section labeled NEEDS or EXPERIMENTAL is never a best practice for a project on an older model, or for production: say which model it needs and give TypeSafe's readiness line in its exact words (the one exception to paraphrasing).
A cookbook's code layout, diagram or call count is an example, never an API limit. "The cookbook does one request per candidate" is a fact about that cookbook. Whether you must do it too is answered by a reference rule, or by the cookbook's own scope note, which the printout shows under "Scope notes elsewhere in this file". Read that note before citing the cookbook.
When the reference pages don't settle a question, say "the docs don't say". Your own inference goes under My read and is never the verdict.
- An absence is reported as one: "the pages I read don't show X". Never "X is untested", "Jev can't X", or a risk.
- Never widen a cited fact with a "so" sentence. An inference is labeled "my read:" and is never stated as TypeSafe's view.
- Before stating any Jev capability or limit (can, can't, reads well, poorly, untested, expects), route that capability as its own question.
Briefing a subagent on Jev
Paste this line into the brief with <skill> written out in full, since the subagent has no skill folder (the dispatch hook refuses a Jev brief without it):
JEV-SOURCES: before any finding, run `python3 <skill>/scripts/jev.py "<the question, in your words>" --docs-words "<the same question in the docs' words>"` (it routes the question twice) and read what it prints; quote verbatim, give path#heading, label reference rule, pattern, cookbook example, sdk reference or vendor claim; quotation marks only for the docs' words; your own text and the user's go in backticks; findings without this are unverified.
Speed, cost and accuracy claims
Speed, cost and accuracy claims come from TypeSafe's blog posts, which the refresh fetches and SOURCES.md in the data folder lists; routing labels them vendor claim; attribute them to TypeSafe. The Jev 1.14 post (blog/jev-1-14.txt) says of the features behind "danger zone" headers: "we think there is still way too much jaggedness for us to vouch for these for production use cases!" Give that as TypeSafe's readiness statement, in its exact words. Price is in docs/models.md#Current models and rate limits in docs/models.md#Rate limits (reference rules).
After a refresh notice
When a refresh notice names STALE_CITATIONS.md, read it. For each changed row, read the archived and the current section and say whether the cited fact is outdated, obsolete or superseded, naming the replacement. Never edit a locked file outside its own pull request.
Relaying a subagent's Jev finding
Relay each finding in your own words with its CITE AS path#heading and label, after checking its quote: read.py '<CITE AS>' --check-quote - <<'QUOTE' with the quote on stdin. In Claude Code a hook also sends back a subagent report whose citation names no section. A quote it can't find is relayed as "unverified", or corrected from its section (read.py '<id>'). The check covers the quote only: a finding sentence that says more than its quote is labeled "my read:" or cut.
- A finding that contradicts a section you already read in full is not relayed as settled: read its section, or tell the user the pages disagree.
- A finding with no
CITE ASand quote is relayed as "unverified". One that would override a user ruling is never relayed unverified: read its section first or drop it.
Refresh
With the reminder hook installed (the Claude Code plugin, or hooks added by hand), the library checks TypeSafe's pages every two days and fetches only new or re-dated pages and new posts. Codex runs no hooks from a plugin: run python3 <skill>/scripts/codex_hooks.py install once (again after moving the skill folder). Without the hooks, nothing refreshes on its own: run JEV_LIBRARY_TESTS=off bash <skill>/refresh.sh --fetch on first install, and again when a source is missing or older than the question needs. That command downloads every page TypeSafe lists (the docs sitemap, llms.txt, the cookbook list and typesafe.ai's blog) and rebuilds the index. SOURCES.md in the data folder lists every page held and when it was saved. Pages live in $JEV_SOURCES_DATA (default ~/.claude/jev-sources-data).
Enforced by
| Rule | Enforced by |
|---|---|
| Answers rest on sections the router found and printed in full | scripts/jev.py, scripts/route.py; tests/test_jev.py, tests/test_route.py |
A Jev message gets a reminder to run jev.py, with a build line on a build or in plan mode; reads are recorded; a Jev brief carries the JEV-SOURCES: line |
hooks/jev-prompt-reminder.py, hooks/jev-ledger.py, hooks/jev-dispatch-check.py (in Codex, installed by scripts/codex_hooks.py); tests/test_hooks.py, tests/test_codex_hooks.py |
Sections past the cap print with their read.py command, or past a third of it as a saved reading plan with one reader brief per batch, a headings-only MAP and a one-batch path; a build runs as up to 8 questions, with a coverage line each and NO SOURCE FOUND for a topic with nothing to read |
scripts/jev.py; tests/test_jev.py |
| Every reader finding is checked: quote, batch, format, page text, empty or missing batches | scripts/check_findings.py, hooks/jev-reader-check.py; tests/test_check_findings.py, tests/test_hooks.py |
| Each section carries its label, and NEEDS or EXPERIMENTAL where it applies | scripts/read.py, scripts/applicability.py; tests/test_route.py, tests/test_applicability.py |
| Every citation in an answer names a real section, and any quoted docs words are on the section cited for them; a subagent report's citations name real sections; a finding's quote is checked | scripts/check_answer.py, hooks/jev-answer-check.py, hooks/jev-reader-check.py, scripts/read.py (--check-quote); tests/test_check_answer.py, tests/test_hooks.py, tests/test_route.py |
| Saved pages hold no site code, and the build warns when some is left | scripts/clean.py, scripts/build_index.py; tests/test_clean.py, tests/test_health.py |
| The library checks for new pages every two days, lists stale citations, and runs the tests that read the library, naming any failure in the notice or the refresh output | hooks/refresh_trigger.py, scripts/check_new.py, scripts/citations.py, scripts/library_tests.py, refresh.sh; tests/test_refresh_trigger.py, tests/test_check_new.py, tests/test_citations.py, tests/test_library_tests.py, tests/test_refresh.py |
| Every background check and refresh reports whether a docs update landed: the index and vectors match the saved pages, no page or library collapsed, and a pass names what it checked | scripts/landing_check.py, scripts/check_new.py, refresh.sh; tests/test_landing_check.py |
Running jev.py before a claim, the answer's five parts in order, facts in your own words with their strength kept and exact words on request, a question turn reading only what it asks and a build turn reading per part with a brief per builder, starting readers on a reading plan, relaying EXTRACT and unchecked findings as unverified, quoting readiness lines, cookbook layouts as examples, "the docs don't say", no widening "so" sentences, reading stale-citation rows, locked files |
the model, following this file |
Files (jev-mode)
-
hooks
-
firing.py 3.5 KB
Loading… -
install-hooks.md 5.1 KB
Loading… -
jev-answer-check.py 5.3 KB
Loading… -
jev-dispatch-check.py 2.3 KB
Loading… -
jev-ledger.py 2.4 KB
Loading… -
jev-prompt-reminder.py 2.6 KB
Loading… -
jev-reader-check.py 9.5 KB
Loading… -
jev_terms.py 9.2 KB
Loading… -
refresh_trigger.py 3.4 KB
Loading… -
reminder_state.py 1.7 KB
Loading…
-
-
images
-
how-it-works-dark.svg 15.5 KB · in bundle
-
how-it-works.svg 15.5 KB · in bundle
-
-
scripts
-
applicability.py 4.8 KB
Loading… -
blog.py 4.8 KB
Loading… -
build_index.py 11.9 KB
Loading… -
check_answer.py 24.2 KB
Loading… -
check_findings.py 9.3 KB
Loading… -
check_new.py 14.1 KB
Loading… -
citations.py 7 KB
Loading… -
clean.py 5.5 KB
Loading… -
codex_hooks.py 5.6 KB
Loading… -
fetch.py 4.7 KB
Loading… -
firing_report.py 7.7 KB
Loading… -
jev.py 16.4 KB
Loading… -
landing_check.py 6.5 KB
Loading… -
library_tests.py 6.8 KB
Loading… -
pages.py 16.7 KB
Loading… -
paths.py 993 B
Loading… -
read.py 14.4 KB
Loading… -
route.py 15.3 KB
Loading… -
route_check.py 3.5 KB
Loading… -
semantic.py 5.2 KB
Loading… -
sources.py 1.7 KB
Loading… -
urls.txt 1 KB
Loading… -
usage_log.py 595 B
Loading…
-
-
tests
-
conftest.py 3.7 KB
Loading… -
firing_cases.json 10.4 KB
Loading… -
paraphrases.json 3.3 KB
Loading… -
release_questions.json 3.3 KB
Loading… -
test_applicability.py 19 KB
Loading… -
test_blog.py 7.9 KB
Loading… -
test_brief.py 2.7 KB
Loading… -
test_check_answer.py 33.1 KB
Loading… -
test_check_findings.py 16.1 KB
Loading… -
test_check_new.py 21.2 KB
Loading… -
test_citations.py 8.4 KB
Loading… -
test_clean.py 6.2 KB
Loading… -
test_clean_real.py 7.7 KB
Loading… -
test_codex_hooks.py 5.3 KB
Loading… -
test_env_isolation.py 797 B
Loading… -
test_firing.py 13.9 KB
Loading… -
test_health.py 3.7 KB
Loading… -
test_hooks.py 45.8 KB
Loading… -
test_index.py 2.2 KB
Loading… -
test_jev.py 39.6 KB
Loading… -
test_landing_check.py 26.8 KB
Loading… -
test_ledger.py 7.5 KB
Loading… -
test_library_guard.py 1.5 KB
Loading… -
test_library_tests.py 14.6 KB
Loading… -
test_pages.py 5.1 KB
Loading… -
test_pages_raw.py 21 KB
Loading… -
test_private_scan.py 4.8 KB
Loading… -
test_refresh.py 9.4 KB
Loading… -
test_refresh_trigger.py 6.7 KB
Loading… -
test_route.py 34.6 KB
Loading… -
test_route_check.py 9.8 KB
Loading… -
test_semantic.py 7 KB
Loading… -
test_skill_shape.py 2.3 KB
Loading… -
test_sources.py 4 KB
Loading… -
test_usage_log.py 4.2 KB
Loading…
-
-
.gitignore 152 B · in bundle
-
applicability.json 4.1 KB
Loading… -
README.md 7.6 KB
# Jev Sources Hate when your coding harness hallucinates Jev functionality or implements Jev from memory? Want to avoid a research agent getting called every session? Jev Sources (updated for 1.14) matches your question by keywords and meaning. Only the most relevant TypeSafe documentation sections land in your coding harness's context. It answers Jev questions from TypeSafe's official docs, cookbooks, patterns and blog posts. It never calls Jev: your coding agent's Claude or Codex model does the reading, so no TypeSafe key is needed. ## Sample > **jev.py** on "can I put 30 passages in one call?", trimmed > ### How many questions you can ask > > - `CITE AS: docs/primitives.md#How many questions you can ask (reference rule)` "There is no limit on the number of questions in a request." > - `CITE AS: cookbooks/parallel_questions.md#Parallel questions (cookbook example)` ## Labels Each section `jev.py` finds gets a label: | Label | The model | Set when | |---|---|---| | **READ FULL** | Reads it all before any claim | Short, or the question limits a design | | **EXTRACT** | Gets a pointer; claims from it are unverified | Long, or matched by meaning only | | **NEEDS** | Names the model the section needs; reads it last when you named an older one | The page needs a newer model than yours (or than jev-latest), per a list of TypeSafe's stated limits | | **EXPERIMENTAL** | Quotes TypeSafe's line that it isn't production-ready | TypeSafe calls it experimental (same list) | ## How it works <picture> <source media="(prefers-color-scheme: dark)" srcset="images/how-it-works-dark.svg"> <img alt="How a Jev question flows: reminder hook, jev.py, keyword and meaning routes, labels, sections read in full or a reading plan, then a cited answer." src="images/how-it-works.svg"> </picture> 1. A hook sees a Jev message and tells the model to run `jev.py`. 2. `jev.py` matches your question to the docs two ways, then reads the best matches: - Keywords rank sections and boost reference rules; names like `request_id` also match their parts. - A small offline model compares meanings and adds up to two sections the keywords missed. - Both read the docs without the site's display code stuffing context. - `jev.py` reads the READ FULL sections, reference rules first, up to a size cap. The model reads small leftovers itself; past a third of the cap, subagents read the rest. - A question reads what it asks. A build request runs one question per part and names any that found nothing. 3. The model answers in its own words, citing each section and label, or says "the docs don't say". A hook sends back misquotes and citations to missing sections. | Step | Who enforces it | |---|---| | Routing, labels, reading order, cap | Code, once the model runs `jev.py` | | Reminder; refusing subagent instructions without their source line; checking citations, a subagent's or the answer's | Hooks, once installed | | Running `jev.py`, the answer, its sources | The model, following `SKILL.md` | Data stays in `~/.claude/jev-sources-data/`; `JEV_LOG=off` stops logging your questions. ## How it stays current With the hooks installed, your first Jev message after two days starts a background check for new or re-dated TypeSafe pages. A later message names any changes. If no check finishes in seven days, the model tells you to run the refresh command. Without the hooks, run `refresh.sh --fetch` yourself. Each check confirms the index matches the saved pages and flags any mismatch or broken page. After a page changes, it also reruns the routing tests and lists the citations it affects. With pytest installed, it runs the library tests; `JEV_LIBRARY_TESTS=off` skips them. ## What it reads It reads TypeSafe's docs (including Models and the API and SDK reference), patterns, cookbooks and blog posts (labeled vendor claims). `SOURCES.md` in the data folder lists every page your copy holds and when it was saved. Updated for Jev 1.14, including image input and Box questions, both experimental per TypeSafe. ## Where the rules come from Jev Sources adds no rules. It cites TypeSafe and says each page's kind: reference pages say what the API allows; cookbooks show one working build. A cookbook that sends one request per item shows one way to build it; a reference page or its scope note says whether you must. Rating a design is a separate skill, [Jevaluate](../jevaluate/). ## How accurate it is | Questions | n | Difficulty | Counts as found when the section is | Found (recall), with 95% confidence interval | |---|---|---|---|---| | Everyday questions | 21 | 🟢 Easy | listed, at any label | 95% (20 of 21; 77% to 99%) | | Everyday questions | 21 | 🟢 Easy | printed in full within the cap | 90% (19 of 21; 71% to 97%) | | Release-check questions | 23 | 🟢 Easy | printed in full within the cap | 100% (23 of 23; 86% to 100%) | | New questions, blinded | 11 | 🟡 Medium | marked READ FULL | 64% (7 of 11; 35% to 85%) | | New questions, blinded | 11 | 🟡 Medium | on the same page as the answer | 91% (10 of 11; 62% to 98%) | | SDK questions, blinded | 24 | 🔴 Hard | printed in full within the cap | 42% (10 of 24; 24% to 61%) | | Broad first-time goals, blinded | 12 | 🔴 Hard | read or left for later reading | 49% of needed sections (40% to 60%); unsplit, 9% | How to read it: - 🟢 **Easy** questions cover the docs broadly; the routing was tuned on them. - 🟡 **Medium** questions cover the same ground, but the routing never saw them. Expect these numbers on new questions. - 🔴 **Hard** questions each ask about one function, field or error in the SDK reference. - **Listed** means the section is anywhere in the list `jev.py` returns. **Printed in full** is stricter: the whole section, within the cap. - **Found** is recall: the share of questions whose section was found. For goals, it is the average share of each goal's needed sections, as a separate reviewer marked them. Ranges are 95% confidence intervals (Wilson; bootstrap for goals), wide on small rows. - **Broad goals** are first-time requests, such as moving a classifier to Jev, blinded. Splitting reads about 4 times the tokens. The table measures `jev.py` once it runs; `scripts/firing_report.py` shows how often the reminder hook prompts it. Live sessions in projects that say they use Jev met blind answer keys on 18 of 19 tests, twice, and 10 of 11 held out. ## Install and use Needs Claude Code or Codex, git and Python 3.8+. Meaning matching needs model2vec, installed by the first refresh. Claude Code plugin, with hooks: ``` claude plugin marketplace add tiffygk/jev-mode claude plugin install jev-sources@jev-mode ``` Codex plugin: ``` codex plugin marketplace add tiffygk/jev-mode codex plugin add jev-sources@jev-mode ``` Then ask your agent to refresh. Codex runs no plugin hooks: have it run `scripts/codex_hooks.py install`. By copy (Codex: `~/.agents/skills/` throughout): ``` git clone https://github.com/tiffygk/jev-mode mkdir -p ~/.claude/skills cp -r jev-mode/jev-sources ~/.claude/skills/ bash ~/.claude/skills/jev-sources/refresh.sh --fetch python3 ~/.claude/skills/jev-sources/scripts/jev.py "can I put 30 passages in one call?" ``` Copy installs add hooks by hand: [`hooks/install-hooks.md`](hooks/install-hooks.md). To install every jev-mode skill at once, or to copy skills by hand, see the [repo README](../README.md#install). ## Limits A page TypeSafe edits without updating its sitemap date stays stale until a full refresh (`refresh.sh --fetch`). A question worded unlike the docs can miss its section. Not affiliated with TypeSafe. ## License PolyForm Noncommercial 1.0.0: free for personal and noncommercial use, with credit. Company or paid use needs a commercial license: [open an issue](https://github.com/tiffygk/jev-mode/issues). -
refresh.sh 3.4 KB
Loading… -
SKILL.md 15.6 KB
--- name: jev-sources description: Finds and cites TypeSafe's docs on Jev, including Noul, Choice, Score and Box questions, models and limits. Use when a question, review, design or claim involves Jev or System One, when briefing a subagent on Jev work, or when relaying a subagent's Jev finding. --- # Jev sources Answers about Jev rest on TypeSafe sections you opened in full this session, found by the router, not by grep or memory. This skill decides what to read; deciding what it means for a design belongs to `jev-mode/shared/jev-rules.md`. ## Before any Jev claim `<skill>` below is this skill's base directory, shown when the skill loads; write it out in full, since the shell runs in the user's project. Run one command and read what it prints: ``` python3 <skill>/scripts/jev.py "<the question, in your words>" --docs-words "<the same question in the docs' words>" ``` Add `--model <id>` when the project pins a model. The docs' words are the terms the docs use (for example "second request", "depends on", "one request", "Choice options", "threshold"); the command routes both phrasings and merges them. It reads every READ FULL section, reference rules first, then patterns, SDK pages, cookbook examples and vendor claims, within the bundle cap (`--cap N`), and starts each with a `CITE AS:` line to quote. Route each separate question on its own. - A section printed under `NOT YET READ` comes with its `read.py` command: run it before relying on that section. These leftovers are at most a third of the cap; more go to readers. - An `EXTRACT` line points somewhere (`read.py '<id>' --extract <word> <word>`). A claim resting on it is labeled **unverified**. - If it prints "no section found", say so, then run `JEV_LIBRARY_TESTS=off bash <skill>/refresh.sh --fetch` and ask again. Never fill the gap from memory, even when asked to answer from memory or in a hurry: the lookup takes seconds, so run it, keep the answer to a few lines, and cite. ## Questions and builds A question, broad or narrow ("where do I start", "is Jev right for this"), gets one `jev.py` run on what it asks. Add `--also` only for parts the question itself raises; a volume, a deadline or code that will call the API raises rate limits, errors and cost at that volume, so route and answer those now. When the printout covers more, use only the sections that answer the question. Answer it, with at most three next steps, and name in one line what they will need when they build, to look up then. ## Building When the person says they are building, asks for a plan, is in plan mode, or pastes code to fix, run one `jev.py` with one question per part: `jev.py "<part 1>" --also "<part 2>" --also "<part 3>"`. - Write 3 to 8 questions, one per part this build has (the question type, sending at volume, errors and retries, model version, the closest pattern or cookbook); add no part it lacks. Choosing between options routes each option. - Read the `COVERAGE:` block; relay each `NO SOURCE FOUND` question as "the docs I routed don't cover <topic>". More than 8 parts: split into two runs. Give each builder subagent its own brief: the `JEV-SOURCES:` line (below) with one question per thing its part needs, never one question for several, and the `path#heading` sections already found for that part, to read first. ## Over the cap When `jev.py` prints `READING PLAN`, the unread sections are more than a third of the cap. Keep the sections it already printed in full; don't read them again. It also prints one `READER BRIEF` block per batch: start one read-only reader subagent per block, with the block pasted whole as its brief. Batches may run in parallel. The `MAP` lines list the unread headings to choose from; never state a fact from a MAP line. Where you can't start subagents, read at most one batch yourself, the sections your task relies on: write its finding lines under that batch's `JEV-READER:` line. If the task needs more, say which parts to split into separate tasks. Then check the replies through a quoted heredoc: ``` python3 <skill>/scripts/check_findings.py <plan_id> <<'REPLIES' <every reader's reply> REPLIES ``` Relay only `OK` lines as checked. A batch it lists as missing or `EMPTY` is unread: tell the user which sections those are. In Claude Code, a hook also checks each reader's reply before the reader returns. ## The answer A Jev answer has these parts, in order: 1. The direct answer, in one or two sentences ("yes, on Jev 1.14 only"). Write part 2 first, then build this from its sentences: no fact that part 2 doesn't cite, and no estimate of yours (that goes under My read). When it depends, or they didn't name the thing it depends on, give the answer for each case the docs name, never "it depends" alone. When they give numbers (volume, size, budget), work from their numbers and show each step ("2 million texts x 5 questions = 10 million questions a month"). 2. What the docs say: only the facts the direct answer, the next steps or My read rely on. Every sentence stating how Jev or TypeSafe works (a limit, price, output, retry, failure or version) goes here, in your own words, one fact per sentence, with the `path#heading` from its `CITE AS:` line in backticks beside it, and that line's label: **reference rule** (what the API allows), **pattern**, **cookbook example** (one build TypeSafe published), **sdk reference** or **vendor claim**. Keep each number, unit, name and model ID exactly as the section writes it, and keep its strength and conditions: can or must, up to or exactly, which model, EXPERIMENTAL. Give TypeSafe's exact words, in quotation marks, only when the person asks for the wording. Cite only the library: a page fetched from the web has no `CITE AS:` line and can't be checked. For a link, use the `URL:` on the section's `SOURCE:` line. 3. Coverage and gaps, one line each: what you read, and any section you left unread or sent to readers; each thing they asked that the docs you read don't cover, named ("the docs I read don't cover <topic>"); where they can't speak to the person's own model, data or numbers. Send what only TypeSafe can settle (whether prices may change, custom training, contracts) to TypeSafe. 4. **My read:** your advice for this person's case, labeled as yours and holding no Jev facts (those go in part 2), on the topics their question raises: one line for each detail they gave (their data and how messy it is, volume, languages, sensitive data, a pinned older model) and each case their wording leaves open (ties, mixed languages, items that fit no option). With a volume or code, or on a build, add: how to test on their own data; what to do on errors, rate limits, timeouts and low confidence; a human check before any risky action. Route each such topic first and cite the docs where they speak. 5. Next steps: a short numbered list they can start on. A narrow question gets the direct answer and its citation, and nothing it didn't ask for. A plan to confirm gets each part checked against the docs (question type and wording, the cases it must tell apart, cost and limits at their volume), then yes, no, or yes with changes. Pasted code or a pasted request gets a fix list, and a question on how to call the API gets the call, in place of parts 1 and 2 (part 3 stays), most serious first, each line in this shape: ``` 1. <the change or step>, per `path#heading` (label) ``` - One numbered line for each Jev call or request: its shape (auth, headers, body), each field read from the result, each model ID and how to pin it, and, whatever the code does, errors and rate limits. Route them with the code's purpose: `--also "API errors and handling rate limits" --also "model aliases and pinning a version"`. Every line carries a citation; where no section you read shows it, mark that line "unconfirmed". Code you write or adapt is labeled as yours. - Then **My read**, one line each: secrets in source; comparisons that break on free text. Then the corrected code, with error and rate-limit handling in it. Before sending, check the answer's citations and any quotes (in Claude Code a stop hook also does): ``` python3 <skill>/scripts/check_answer.py <<'ANSWER' <the answer> ANSWER ``` Fix each line it prints: cite the section that holds the fact, correct a quote from its section, or label it unverified. Wording you made up (an example question or option) and the user's own text (their error, log or message) go in backticks, never quotation marks: quotation marks are for the docs' words only. Send only the corrected answer, with no note about the check. A section labeled NEEDS or EXPERIMENTAL is never a best practice for a project on an older model, or for production: say which model it needs and give TypeSafe's readiness line in its exact words (the one exception to paraphrasing). A cookbook's code layout, diagram or call count is an example, never an API limit. "The cookbook does one request per candidate" is a fact about that cookbook. Whether you must do it too is answered by a reference rule, or by the cookbook's own scope note, which the printout shows under "Scope notes elsewhere in this file". Read that note before citing the cookbook. When the reference pages don't settle a question, say "the docs don't say". Your own inference goes under My read and is never the verdict. - An absence is reported as one: "the pages I read don't show X". Never "X is untested", "Jev can't X", or a risk. - Never widen a cited fact with a "so" sentence. An inference is labeled "my read:" and is never stated as TypeSafe's view. - Before stating any Jev capability or limit (can, can't, reads well, poorly, untested, expects), route that capability as its own question. ## Briefing a subagent on Jev Paste this line into the brief with `<skill>` written out in full, since the subagent has no skill folder (the dispatch hook refuses a Jev brief without it): ``` JEV-SOURCES: before any finding, run `python3 <skill>/scripts/jev.py "<the question, in your words>" --docs-words "<the same question in the docs' words>"` (it routes the question twice) and read what it prints; quote verbatim, give path#heading, label reference rule, pattern, cookbook example, sdk reference or vendor claim; quotation marks only for the docs' words; your own text and the user's go in backticks; findings without this are unverified. ``` ## Speed, cost and accuracy claims Speed, cost and accuracy claims come from TypeSafe's blog posts, which the refresh fetches and `SOURCES.md` in the data folder lists; routing labels them **vendor claim**; attribute them to TypeSafe. The Jev 1.14 post (`blog/jev-1-14.txt`) says of the features behind "danger zone" headers: "we think there is still way too much jaggedness for us to vouch for these for production use cases!" Give that as TypeSafe's readiness statement, in its exact words. Price is in `docs/models.md#Current models` and rate limits in `docs/models.md#Rate limits` (reference rules). ## After a refresh notice When a refresh notice names `STALE_CITATIONS.md`, read it. For each `changed` row, read the archived and the current section and say whether the cited fact is outdated, obsolete or superseded, naming the replacement. Never edit a locked file outside its own pull request. ## Relaying a subagent's Jev finding Relay each finding in your own words with its `CITE AS` path#heading and label, after checking its quote: `read.py '<CITE AS>' --check-quote - <<'QUOTE'` with the quote on stdin. In Claude Code a hook also sends back a subagent report whose citation names no section. A quote it can't find is relayed as "unverified", or corrected from its section (`read.py '<id>'`). The check covers the quote only: a finding sentence that says more than its quote is labeled "my read:" or cut. - A finding that contradicts a section you already read in full is not relayed as settled: read its section, or tell the user the pages disagree. - A finding with no `CITE AS` and quote is relayed as "unverified". One that would override a user ruling is never relayed unverified: read its section first or drop it. ## Refresh With the reminder hook installed (the Claude Code plugin, or hooks added by hand), the library checks TypeSafe's pages every two days and fetches only new or re-dated pages and new posts. Codex runs no hooks from a plugin: run `python3 <skill>/scripts/codex_hooks.py install` once (again after moving the skill folder). Without the hooks, nothing refreshes on its own: run `JEV_LIBRARY_TESTS=off bash <skill>/refresh.sh --fetch` on first install, and again when a source is missing or older than the question needs. That command downloads every page TypeSafe lists (the docs sitemap, llms.txt, the cookbook list and typesafe.ai's blog) and rebuilds the index. `SOURCES.md` in the data folder lists every page held and when it was saved. Pages live in `$JEV_SOURCES_DATA` (default `~/.claude/jev-sources-data`). ## Enforced by | Rule | Enforced by | |---|---| | Answers rest on sections the router found and printed in full | `scripts/jev.py`, `scripts/route.py`; `tests/test_jev.py`, `tests/test_route.py` | | A Jev message gets a reminder to run `jev.py`, with a build line on a build or in plan mode; reads are recorded; a Jev brief carries the `JEV-SOURCES:` line | `hooks/jev-prompt-reminder.py`, `hooks/jev-ledger.py`, `hooks/jev-dispatch-check.py` (in Codex, installed by `scripts/codex_hooks.py`); `tests/test_hooks.py`, `tests/test_codex_hooks.py` | | Sections past the cap print with their `read.py` command, or past a third of it as a saved reading plan with one reader brief per batch, a headings-only MAP and a one-batch path; a build runs as up to 8 questions, with a coverage line each and NO SOURCE FOUND for a topic with nothing to read | `scripts/jev.py`; `tests/test_jev.py` | | Every reader finding is checked: quote, batch, format, page text, empty or missing batches | `scripts/check_findings.py`, `hooks/jev-reader-check.py`; `tests/test_check_findings.py`, `tests/test_hooks.py` | | Each section carries its label, and NEEDS or EXPERIMENTAL where it applies | `scripts/read.py`, `scripts/applicability.py`; `tests/test_route.py`, `tests/test_applicability.py` | | Every citation in an answer names a real section, and any quoted docs words are on the section cited for them; a subagent report's citations name real sections; a finding's quote is checked | `scripts/check_answer.py`, `hooks/jev-answer-check.py`, `hooks/jev-reader-check.py`, `scripts/read.py` (`--check-quote`); `tests/test_check_answer.py`, `tests/test_hooks.py`, `tests/test_route.py` | | Saved pages hold no site code, and the build warns when some is left | `scripts/clean.py`, `scripts/build_index.py`; `tests/test_clean.py`, `tests/test_health.py` | | The library checks for new pages every two days, lists stale citations, and runs the tests that read the library, naming any failure in the notice or the refresh output | `hooks/refresh_trigger.py`, `scripts/check_new.py`, `scripts/citations.py`, `scripts/library_tests.py`, `refresh.sh`; `tests/test_refresh_trigger.py`, `tests/test_check_new.py`, `tests/test_citations.py`, `tests/test_library_tests.py`, `tests/test_refresh.py` | | Every background check and refresh reports whether a docs update landed: the index and vectors match the saved pages, no page or library collapsed, and a pass names what it checked | `scripts/landing_check.py`, `scripts/check_new.py`, `refresh.sh`; `tests/test_landing_check.py` | | Running `jev.py` before a claim, the answer's five parts in order, facts in your own words with their strength kept and exact words on request, a question turn reading only what it asks and a build turn reading per part with a brief per builder, starting readers on a reading plan, relaying EXTRACT and unchecked findings as unverified, quoting readiness lines, cookbook layouts as examples, "the docs don't say", no widening "so" sentences, reading stale-citation rows, locked files | the model, following this file | -
synonyms.json 2.4 KB
Loading… -
topics.json 10.5 KB
Loading…
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.