# Jev Wiki — Schema and Maintenance Rules

This repository is an **LLM-agent-facing knowledge base about Jev**, TypeSafe AI's System One model, and everything around it (HTTP API, Python/JS SDKs, patterns, cookbooks, company, pricing, limits). It follows the Karpathy "LLM Wiki" pattern as used by agentwikis.com: raw sources are immutable, the LLM writes and maintains structured wiki pages, and every page is plain Markdown with YAML frontmatter so any agent (Claude, Codex, Cursor, Kimi, DeepSeek, ...) can read it natively.

**Primary consumer:** an LLM coding agent that has been told "build X with Jev" and needs to know exact field names, limits, prices, SDK signatures, failure modes, and design patterns without re-reading 1 MB of upstream docs.

## Layout

```
CLAUDE.md            this file (also symlinked as AGENTS.md)
README.md            human/agent entry point; how to consume the wiki
raw/                 immutable sources (docs pages, OpenAPI, repos, site, blog, evals, press, raw/x = captured X posts, raw/x-repos = READMEs of repos they link). NOT deployed; only wiki/ is published
raw/MANIFEST.json    raw file -> source URL -> fetch date / commit
wiki/index.md        master catalog of every page — GENERATED by scripts/build.mjs from frontmatter; never hand-edit
wiki/log.md          append-only activity log
wiki/concepts/       how Jev and System One work
wiki/reference/      exact contracts: HTTP API, schemas, models, SDKs, env vars, errors
wiki/patterns/       architectural patterns
wiki/cookbooks/      one page per upstream cookbook, distilled
wiki/guides/         task-oriented how-tos and the agent playbook
wiki/ideas/          COMMUNITY tier: consult guide, decision patterns, field reports, community repos (from raw/x, raw/x-repos)
wiki/entities/       company, people, repos, products, blog posts, press
wiki/syntheses/      cross-cutting analyses, FAQ, glossary, timelines
scripts/             build (llms.txt, llms-full.txt, index.json, HTML), refresh, lint
site/                Cloudflare Worker that serves the wiki
```

## Page format (mandatory)

Every page under `wiki/` is:

```markdown
---
title: "Exact page title"
type: concept | reference | pattern | cookbook | guide | entity | synthesis | community | index
source_tier: community      # REQUIRED on every page under wiki/ideas/ (community | mixed); omit elsewhere (= official)
tags: [lowercase, kebab-case, 2-6 tags]
created: 2026-09-17
updated: 2026-09-17
confidence: high | medium | low
sources:
  - raw/docs/primitives__choice.md
  - https://typesafe.ai/blog/introducing-system-one-models-and-jev
jev_version: "jev-1.13.0"
sdk_python: "0.6.0"        # only on pages that describe the Python SDK
sdk_js: "0.6.0"            # only on pages that describe the JS SDK
summary: "One sentence, <= 200 chars, used in index.md and llms.txt"
---

# Exact page title

> **TL;DR** one to three sentences an agent can act on without reading further.

## (H2 sections; see type-specific guidance below)

## Related

- [[concepts/system-one]] — why this matters
- [[reference/http-api]] — the wire contract

## Sources

- raw/docs/primitives__choice.md (https://docs.typesafe.ai/primitives/choice)
```

Rules:

- **Frontmatter first**, exactly one `# H1` matching `title`, then the TL;DR blockquote.
- **Wikilinks** are `[[dir/slug]]` or `[[dir/slug|label]]`, relative to `wiki/`, no `.md`. Only link to pages in the inventory below (or pages you create and add to the inventory). The build script fails on dangling links.
- **Fidelity over fluency.** Every number, field name, enum value, default, limit, price, version, and code sample must come from a source in `raw/`. Quote field names and enum values in backticks exactly as the API spells them. If you infer something, write "(inferred)". If sources disagree, say so and cite both.
- **Code samples must be complete and runnable** (imports, client construction, the call, reading the answer). Prefer the upstream sample verbatim; when you adapt, keep it consistent with SDK v0.6.0 (`Score.criteria` is an ordered sequence, not an int-keyed dict).
- **Agent-oriented.** Each page should answer "when do I use this, what exactly do I send, what exactly comes back, what goes wrong." Include "When to use / When not to use" where it applies.
- **Length:** concepts/guides 500–1500 words; reference pages as long as the contract needs (tables preferred); cookbooks 600–1800 words; entities 200–800 words.
- **No marketing voice.** State claims as claims with attribution ("TypeSafe claims 193.6x faster on its workflow evals").
- Dates are absolute ISO (`2026-09-15`), never "yesterday" or "recently".
- Do not modify anything in `raw/`.

### Type-specific guidance

- **concept**: What it is → How it works (mechanism) → Why it matters for code → Gotchas → Related.
- **reference**: Contract tables (field, type, required, default, description) → verbatim request/response examples → error cases → version notes. Cover every field in the source; do not summarize away optional fields.
- **pattern**: Problem → Pattern → Implementation (Python and JS or HTTP) → When it fails → Variants.
- **cookbook**: Goal → Inputs/state shape → Questions asked (exact `type`, `instructions`, `criteria`) → Combining logic in code → Results/what the cookbook reports → Adapting it (what to change for a new domain) → Gotchas. Keep the key code.
- **guide**: Steps in order, each with the exact command or code. Checklists welcome.
- **entity**: Facts table (name, url, version, dates, license, owner) → description → relationship to Jev → Related.
- **synthesis**: The question answered → the analysis with citations to wiki pages → decision table → Related.

## Page inventory

Slugs are fixed; use them verbatim in wikilinks. Agents writing pages own the rows assigned to them.

### concepts/
| slug | title | primary sources |
|---|---|---|
| concepts/system-one | System One Models | raw/docs/concepts__system-one.md, raw/docs/introduction.md, raw/site/blog-introducing-system-one.txt |
| concepts/state | State: what you send Jev | raw/docs/concepts__state.md |
| concepts/how-to-build | How to build software with System One | raw/docs/concepts__how-to-build-with-system-one.md |
| concepts/machine-learning-primer | AI primer: why calibrated decision models | raw/docs/introduction__machine-learning-primer.md |
| concepts/use-case-map | Use-case map by industry | raw/docs/concepts__use-case-map.md |
| concepts/confidence | Confidence vs probability | raw/docs/confidence.md |
| concepts/workflow-evals | Workflow evals: how TypeSafe measures Jev | raw/site/evals-*.txt, raw/site/blog-introducing-system-one.txt |
| concepts/primitives | Primitives: Choice, Score, Noul | raw/docs/primitives.md |
| concepts/choice | Choice questions | raw/docs/primitives__choice.md |
| concepts/score | Score questions | raw/docs/primitives__score.md |
| concepts/noul | Noul (yes/no) questions | raw/docs/primitives__noul.md |
| concepts/advanced-structure | Structured instructions, options, levels, criteria | raw/docs/primitives__advanced.md |
| concepts/jaggedness-jev-1-13 | Jev 1.13 jaggedness: known failure modes | raw/docs/model-jaggedness__jev-1.13.md |

### reference/
| slug | title | primary sources |
|---|---|---|
| reference/http-api | HTTP API: POST /v1/systemone and GET /v1/models | raw/docs/api.md, raw/site/openapi.json |
| reference/openapi-schemas | OpenAPI component schemas | raw/site/openapi.json |
| reference/models-and-pricing | Models, aliases, pricing, rate limits, context | raw/docs/models.md |
| reference/rate-limits-and-errors | HTTP status codes, rate limits, retry semantics | raw/docs/api.md, raw/docs/models.md, SDK exception pages |
| reference/migrating-to-v1 | Migrating from /preview/evaluation to /v1/systemone | raw/docs/migrating-to-v1.md |
| reference/environment-variables | TYPESAFE_* environment variables across SDKs | raw/docs/sdk__python__api__constants.md, raw/docs/sdk__javascript__api__variables__ENV.md, raw/github/*/src |
| reference/legal-and-data | Legal: MCA, DPA, privacy, data retention | raw/docs/legal.md, raw/site/typesafe-ai-legal_*.txt |
| reference/python-sdk | Python SDK: install, clients, system_one() | raw/docs/sdk__python*.md, raw/github/typesafe-sdk-python |
| reference/python-sdk-questions | Python SDK question types (Noul, Choice, Score) | raw/docs/sdk__python__api__types__questions.md, raw/docs/sdk__python__api__types__common.md |
| reference/python-sdk-responses | Python SDK responses, answers, usage, models | raw/docs/sdk__python__api__types__responses.md, raw/docs/sdk__python__api__clients__*__models.md |
| reference/python-sdk-retries-errors | Python SDK retries, exceptions, constants | raw/docs/sdk__python__api__retries.md, raw/docs/sdk__python__api__exceptions.md, raw/docs/sdk__python__api__constants.md |
| reference/python-sdk-changelog | Python SDK changelog | raw/docs/sdk__python__changelog.md, raw/github/typesafe-sdk-python/docs/changelog.md |
| reference/javascript-sdk | JavaScript/TypeScript SDK: install, client, choice/score/noul | raw/docs/sdk__javascript*.md, raw/github/typesafe-sdk-js |
| reference/javascript-sdk-types | JavaScript SDK interfaces and type aliases | raw/docs/sdk__javascript__api__interfaces__*.md, raw/docs/sdk__javascript__api__type-aliases__*.md |
| reference/javascript-sdk-errors | JavaScript SDK error classes, RetryPolicy, RequestOptions | raw/docs/sdk__javascript__api__classes__*Error*.md, RetryPolicy, RequestOptions |
| reference/javascript-sdk-changelog | JavaScript SDK changelog | raw/docs/sdk__javascript__changelog.md, raw/github/typesafe-sdk-js/docs/changelog.md |
| reference/agent-skill | The typesafe-ai agent skill and Claude Code plugin | raw/docs/agent-skill.md, raw/github/skills |
| reference/system-one-adapter | system-one-adapter: LLM-backed drop-in for TypeSafeClient | raw/github/system-one-adapter-python |

### patterns/
| slug | title | primary sources |
|---|---|---|
| patterns/overview | Patterns overview | raw/docs/patterns.md |
| patterns/fan-out | Speculative fan-out | raw/docs/patterns__fan-out.md |
| patterns/confidence-routing | Confidence-gated routing | raw/docs/patterns__confidence-routing.md |
| patterns/composite-scoring | Composite scoring | raw/docs/patterns__composite-scoring.md |
| patterns/intent-routing | Intent routing | raw/docs/patterns__intent-routing.md |

### cookbooks/ (slug = upstream slug with underscores → hyphens)
| slug | source |
|---|---|
| cookbooks/overview | raw/docs/cookbooks.md |
| cookbooks/autoformat | raw/docs/cookbooks__autoformat.md |
| cookbooks/autoresearch-feature-discovery | raw/docs/cookbooks__autoresearch_feature_discovery.md |
| cookbooks/citation-check | raw/docs/cookbooks__citation_check.md |
| cookbooks/classification-using-confidence | raw/docs/cookbooks__classification_using_confidence.md |
| cookbooks/classifying-rag-passages | raw/docs/cookbooks__classifying_rag_passages.md |
| cookbooks/consistency-choice | raw/docs/cookbooks__consistency_choice_cookbook.md |
| cookbooks/consistency-noul | raw/docs/cookbooks__consistency_noul_cookbook.md |
| cookbooks/date-extraction | raw/docs/cookbooks__date_extraction_cookbook.md |
| cookbooks/entity-alignment | raw/docs/cookbooks__entity_alignment.md |
| cookbooks/function-calling | raw/docs/cookbooks__function_calling.md |
| cookbooks/hierarchical-classification | raw/docs/cookbooks__hierarchical_classification.md |
| cookbooks/llm-guardrails | raw/docs/cookbooks__llm_guardrails.md |
| cookbooks/parallel-questions | raw/docs/cookbooks__parallel_questions.md |
| cookbooks/pre-parsed-value-extraction | raw/docs/cookbooks__pre_parsed_value_extraction_cookbook.md |
| cookbooks/rerank | raw/docs/cookbooks__rerank_typesafe.md |
| cookbooks/sde-cascade | raw/docs/cookbooks__sde_cascade.md |
| cookbooks/semantic-find | raw/docs/cookbooks__semantic_find.md |
| cookbooks/skill-suggestion | raw/docs/cookbooks__skill_suggestion.md |

### guides/
| slug | title | primary sources |
|---|---|---|
| guides/quickstart | Quickstart: first call in HTTP, Python, JS | raw/docs/introduction__quickstart.md, SDK READMEs |
| guides/choosing-a-primitive | Choosing between Choice, Score, Noul | raw/docs/primitives.md and the three primitive pages |
| guides/writing-instructions-and-criteria | Writing instructions and criteria that Jev reads correctly | primitive pages, raw/docs/model-jaggedness__jev-1.13.md, raw/docs/primitives__advanced.md |
| guides/smart-home-demo | Smart home assistant demo walkthrough | raw/docs/demos.md, raw/docs/demos__smart-home.md |
| guides/testing-and-evaluation | Testing and evaluating a Jev workflow | consistency cookbooks, evals site, jaggedness |
| guides/agent-integration-playbook | Playbook for LLM agents building with Jev | whole wiki |

### entities/
| slug | title | primary sources |
|---|---|---|
| entities/typesafe-ai | TypeSafe AI (company) | raw/site/typesafe-ai-home.txt, press-*, team, blog |
| entities/jev | Jev (model) | raw/docs/models.md, blog, jaggedness |
| entities/team | Founders and team | raw/site/team.txt, pyproject maintainers |
| entities/typesafe-console | console.typesafe.ai (console + playground) | raw/site/console.txt, docs quickstart, MCA |
| entities/github-repos | typesafe-ai GitHub organisation and repos | raw/github/*, gh listing in this file's notes |
| entities/manifesto | Manifesto: Composable AI — Build Prod, Not God | raw/site/typesafe-ai-manifesto.txt |
| entities/blog-introducing-system-one | Blog: Introducing System One Models & Jev (2026-09-15) | raw/site/blog-introducing-system-one.txt |
| entities/blog-bitterest-lesson | Blog: The Bitterest Lesson | raw/site/blog-bitterest-lesson.txt |
| entities/blog-antibenchmaxxing | Blog: Lies, Damned Lies, and Benchmarks | raw/site/blog-antibenchmaxxing.txt |
| entities/blog-too-good-to-be-true | Blog: AI: too good to be true, too bad to be useful (2026-06-19) | raw/site/blog-too-good-to-be-true.txt (body not captured) |
| entities/press-and-coverage | Press and third-party coverage | raw/site/press-*.txt |

### ideas/ (community tier)

Source: the owner's curated X bookmark folder "Jev" (61 posts captured 2026-09-20 in raw/x/, index at raw/x/INDEX.json) and the 42 GitHub repos those posts link (raw/x-repos/, index at raw/x-repos/INDEX.json). To add posts: `python3 scripts/capture_x.py handle/statusid ...`, then re-ingest.

| slug | title | budget |
|---|---|---|
| ideas/overview | Ideas section overview | <= 600 tokens |
| ideas/consult | Consult guide: "could Jev help this project?" | <= 2,000 tokens |
| ideas/patterns | Decision patterns from the community (with fit verdicts) | <= 5,500 tokens |
| ideas/field-reports | Field reports: independent evaluations, critiques, open replicas | <= 3,500 tokens |
| ideas/community-repos | Community repos: what people built and how they use Jev | <= 4,500 tokens |

Rules specific to ideas/:

- **Token budgets are hard.** An agent doing a consult should spend 10-15k tokens total. Tables and terse bullets, no prose padding. One token ~ 4 characters of the file.
- **Community tier.** `source_tier: community`, `confidence` never `high`. Official pages (reference/, concepts/) win every conflict; when a community claim contradicts them, say so inline and link the official page.
- **Verify technical claims.** Any API detail, price, limit, or code idea taken from a post must be checked against reference/ and concepts/ pages and marked `verified`, `contradicts docs`, or `unverified`. Performance numbers are always attributed ("@handle reports ...").
- **Fit verdicts.** Every pattern carries `fit: strong | workable | poor`, judged against [[concepts/jaggedness-jev-1-13]] and [[concepts/system-one]] (math, date arithmetic, deep indirection, generation, huge irrelevant state = poor).
- **Digest, don't reproduce.** Summarise in your own words, at most one short quote (< 15 words) per source, always link the post URL. Hype posts that repeat the launch numbers are merged, not given separate entries.
- **No financial advice.** Trading/betting demos are described as engineering patterns with the documented numeric/time-series weaknesses flagged; never recommend trading.

### syntheses/
| slug | title |
|---|---|
| syntheses/faq | FAQ for agents and developers |
| syntheses/glossary | Glossary |
| syntheses/jev-vs-llm-structured-outputs | Jev vs LLM JSON mode / structured outputs |
| syntheses/version-timeline | Versions and timeline (models, SDKs, API, company) |

## Workflows

- **Ingest** (`ingest raw/<file>`): read the source, create/update the pages in the inventory that it feeds, add cross-links, append to `wiki/log.md`, run `npm run build` (regenerates `wiki/index.md`).
- **Query**: answer from the wiki, cite pages; if a novel synthesis emerges, add a `syntheses/` page.
- **Lint**: run `python3 scripts/build.py --check` (frontmatter, dangling wikilinks, orphans, missing sections), then read flagged pages and fix.
- **Refresh**: `python3 scripts/refresh.py` re-fetches every source in `raw/MANIFEST.json`, reports changed files, and lists wiki pages whose `sources` include a changed file so they can be re-ingested. Bump `updated` on every page you touch.

## Log format

`wiki/log.md` entries: `- 2026-09-17 — <action>: <what changed> (<pages>)`, newest at the bottom.

## Facts collected during ingestion (for entity pages)

- GitHub org `typesafe-ai` repos (2026-09-17): system-one-adapter-python (Python, pushed 2026-09-16), typesafe-sdk-js (TypeScript, 2026-09-15), typesafe-sdk-python (Python, 2026-09-15), skills (2026-09-12), daggerverse (Python, Dagger modules, 2026-09-09), Overwatch (Python, no description, 2026-09-03), pulumi-clickhouse (Go, 2026-07-08), typesafe-ai.github.io (HTML, 2026-06-04), LLaDA fork (2025-06-17), vllm fork (2025-05-23).
- PyPI: `typesafe-sdk` 0.6.0 (releases 0.0.1a0, 0.5.7, 0.6.0); `typesafe-ai` 0.1.0 is a redirect shim that depends on `typesafe-sdk`. Unrelated package `typesafe` 0.9.1 is NOT TypeSafe AI. `pypi.typesafe.ai` (used in cookbook pip commands with `cooksafe`) returns 404 publicly as of 2026-09-17.
- npm: `@typesafe-ai/sdk` latest 0.6.0 (0.5.7 on 2026-09-12, 0.6.0 on 2026-09-15); engines node >= 20; MIT.
- Python SDK deps: httpx2>=2.0.0, msgspec>=0.21.1, tenacity>=9.0.0, typing-extensions>=4.13.0; requires-python >= 3.10; maintainer Daniel Gafni <daniel@typesafe.ai>; support@typesafe.ai.
- Console/login at https://console.typesafe.ai (Google or email code). Playground share links look like `https://console.typesafe.ai/playground?share=shr_...`.
- Contacts: hello@typesafe.ai, sales@typesafe.ai, support@typesafe.ai. Jobs: https://jobs.ashbyhq.com/typesafe-ai. Socials: https://x.com/typesafeai, https://www.linkedin.com/company/typesafe-ai/.
- Evals site: https://evals.typesafe.ai/ with four workflows (Security Incidents, Agent Trace Observability, Invoice Processing, Customer Service).