Repository navigation
Foundation: reader documentation for getting started, offline and live modes, and the glossary #72
Description
Goal
A reader who lands on the repository can run recipe 01 in a few minutes and understands what an offline run does and does not show.
Scope
docs/getting-started.md: install, open a notebook, run offline, switch to live.docs/offline-and-live.md: the two modes, provenance, and why synthetic metrics are pipeline checks.docs/glossary.md: state, question, Choice, Noul, Score, criteria, probabilities, confidence, threshold, each linked to its source.- A quick start section in the root
README.md, placed outside the generated catalog regions.
Acceptance criteria
- Every command in the docs was run in a clean environment and works
- Every statement about Jev's behaviour links to a source in the README sources table
-
python tools/render_catalog.py --checkstill passes - Lint and tests pass in CI, or locally with the output pasted in the pull request if CI does not exist yet
Dependencies
- Blocked by Foundation: opt-in live Jev backend and response recorder #64 (opt-in live Jev backend and response recorder)
- Blocked by Foundation: recipe template and scaffolder #68 (recipe template and scaffolder)
- Tracked in Epic: Foundation #74
References
- Recipe contract
- Catalog
- TypeSafe documentation index for tools: https://docs.typesafe.ai/llms.txt
- Python SDK: https://docs.typesafe.ai/sdk/python
Activity
CompleteDotTech commentedon Oct 6, 2026
Documentation handoff: dedicated PR91/#90 fixes the root handwritten publication NOTE (currently approved head f1a47c6). Please adopt its final merged wording and avoid duplicating that paragraph. Independent review #91 (comment) identified future ambiguity in root README Data and Claims rows: clarify synthetic INPUT data versus authentic RECORDED RESPONSE fixtures, and synthetic-fixture pipeline demonstrations versus measurements derived from authentic recorded inference. Resolve before first recorded fixtures land; preserve truthful model/date/sample-size/held-out disclosure and offline replay guidance. Review any reader-facing edits independently through the usual PR gates.
CompleteDotTech commentedon Oct 7, 2026
Additional documentation handoff from genuine Opus review of PR91 head1e2d1b8, comment6027936392 (nonblocking for91, required accurate reader guidance before recordings/recipepublication): README Data row must distinguish synthetic INPUTS from authentic recorded RESPONSES; Claims row must distinguish synthetic demonstrations from measured recorded replay numbers with N/model/date. Backend also exposes scripted mode with synthetic provenance and no fixtures; describe synthetic (fixtures or scripted) versus recorded consistently. README opt-in live statement must match delivered64 rather than unavailable backend. Template68 should provide explicit README mode/model/date/N disclosure matching note. Prior mixed-fixture concern withdrawn because ReplayBackend enforces uniformsource/model; do not invent a blocker or loosen provenance. Incorporate through the existing72/68 Sonnet owners and independent review, without expanding91 or fabricated recording claims.