# 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, pattern index + domain pattern pages, field reports, repo index + domain repo pages (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 posts about Jev (raw/x/, index raw/x/INDEX.json; 61 captured 2026-09-20, more added since) and the GitHub repos those posts link (raw/x-repos/, index raw/x-repos/INDEX.json). Also raw/community/ (Diogo Almeida's public coding-agent notes, Archer Hume's architecture essay; point-in-time text captures) and raw/nate/jev-shaped-problems.md: our own digest notes of Nate B. Jones's member guide, used with his permission on condition of credit (2026-09-21); always credit and link him, never reproduce his prompts or guide text. To add posts: `python3 scripts/capture_x.py handle/statusid ...`, capture linked repo READMEs into raw/x-repos/, then re-ingest.

**Structure: index + domain pages.** A consult reads `ideas/consult`, the `ideas/patterns` index, then ONE (at most two) domain page. Growth goes into domain pages (split a domain page when it passes its budget); index pages stay slim so consult cost stays flat.

| slug | title | budget |
|---|---|---|
| ideas/overview | Ideas section overview (carries the credit line for Nate B. Jones) | <= 800 tokens |
| ideas/consult | Consult guide: "could Jev help this project?" | <= 2,000 tokens |
| ideas/patterns | Pattern index: every Pxx in one table, routing by project type, retrofit order, anti-patterns | <= 2,500 tokens |
| ideas/patterns-agents | Patterns: agent internals and orchestration, context and memory, coding agents (P01-P11, P35-P37) | <= 4,500 tokens |
| ideas/patterns-interface | Patterns: browser, computer use, voice, classifier inside a product UI (P12-P14, P34) | <= 3,000 tokens |
| ideas/patterns-data | Patterns: judging and moderation, search and data, documents, transcripts, real-time, markets (P15-P18, P24-P27) | <= 4,000 tokens |
| ideas/patterns-business | Patterns: marketing, sales, GTM, content, support and ops (P19-P23, P28-P33) | <= 4,500 tokens |
| ideas/field-reports | Field reports: what held up, what broke, what it means when advising | <= 3,500 tokens |
| ideas/measurements | Measured numbers, access routes and gateways, open-replica trust notes | <= 3,500 tokens |
| ideas/community-repos | Repo index: every captured repo in one table, top picks, reusable designs, vetting caveats | <= 3,000 tokens (one short row per repo; move prose out before raising again) |
| ideas/repos-agents | Repos: coding agents, orchestration, memory, browser/computer use, MCP servers and integrations | <= 4,500 tokens |
| ideas/repos-apps | Repos: search/data/documents, moderation and judging, real-time/games/IoT, markets, business apps, open replicas and servers | <= 4,500 tokens |

Pattern IDs are permanent (never renumber; new patterns take the next free number, currently P38). Refer to a pattern from another page as `[[ideas/patterns-agents]] P07`.

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 `npm run check` (frontmatter, dangling wikilinks, orphans, missing sections), then read flagged pages and fix.
- **Refresh**: `npm run refresh` 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).