How It Works — Written Guide

This learning app is a self-paced AI-engineering curriculum delivered as a single Next.js App Router application, deployed to one Cloudflare Worker. The entire site—interactive explainers, persistent audiobook player, lesson pages—is a static-plus-dynamic hybrid where every piece of content resolves from the same ordered source of truth.

The curriculum lives as plain markdown files under content/. Each file is named by its slug (e.g., tokenization.md) and contains a level-1 heading for the title, followed by body text. The critical structural constant is LESSON_SLUGS in lib/articles.ts. This array lists every slug in the exact order the authors intend students to study—starting with the foundation phase (lessons 1–9) and running through phase 8 (lessons 73–80). Position in this list fixes each lesson’s number; a derived constant LESSON_NUMBER maps slug to that 1-indexed position. The array also defines the audiobook spine: the persistent player auto-advances through slugs in this order, and anything beyond lesson 80 (the Appendix) is excluded from continuous-play but is still reachable via direct links.

lib/data.ts consumes that ordered list to build lesson metadata. The function getAllLessons() reads every .md file from content/, filters only those slugs that appear in LESSON_NUMBER, then extracts title, excerpt, word count, reading time, and difficulty (computed from the lesson’s position inside its phase). The resulting Lesson objects are sorted by number, producing a static array that drives the roadmap, category groupings, and the audio player’s playlist.

When a user requests a specific lesson, getLessonBySlug(slug) in lib/data.ts resolves the content. It follows a three-layer fallback: first it tries to fetch from a D1 database (the content-cache written by a Rust sync-d1 pipeline—new or edited markdown appears after a refresh without redeploying the Worker). If D1 is unconfigured or empty, it falls through to a JSON file exported at build time by export-content. As a last resort, it reads the raw markdown from disk using resolveContentFile(slug), which constructs the path content/${slug}.md and parses the file with fs.readFileSync. The content is then combined with the metadata into a LessonWithContent object.

This single ordered list is the source of truth for both numbering and the play order because it prevents the kind of drift that would occur if numbering were derived from filesystem ordering, a database row, or a separate menu config. The list is version-controlled alongside the markdown files, so adding a new lesson or reordering an existing one is a single edit in one place: insert the slug at the correct index, bump subsequent numbers automatically via the position-based LESSON_NUMBER map, and the rest of the system—roadmap grouping, difficulty calculation, player progression, URL paths—adjusts consistently. The design trades the flexibility of dynamic ordering for a guarantee that every lesson’s number and position is deterministic, auditable, and synchronized with the author’s intended learning sequence.

The deployment pipeline for this site is built around a deliberate inversion of the usual “deploy fast, test later” philosophy: gate the build, not the deploy. Every broken audio manifest, missing section, or malformed JSON is caught before a single byte reaches the edge, so the production site almost never sees a 500 from bad data. The price is a longer build sequence, but the reward is a deploy that is trusted to serve.

The chain begins in package.json with the cf:deploy script, which runs three steps in order: cf:build, wrangler deploy, and cf:verify. The build step itself is a composition. First, npm run test:audio:all (also hooked as prebuild) checks every audio‑guide metadata file offline using scripts/test-audio-meta.mjs. This is the integrity gate: if a .json is missing a required field or references a non‑existent audio file, the script exits non‑zero and the entire deploy aborts. Only after that passes does the actual compilation begin.

The Next.js build is pinned to next build --webpack. This is not accidental. Next 16 defaults to the new Rust‑based bundler (Turbopack for production), but OpenNext—the adapter that converts the Next output into a Cloudflare Worker bundle—expects Webpack’s module graph. Using the default bundler produces a .next directory that OpenNext cannot reshape into a valid Worker; the --webpack flag forces the older, fully compatible Webpack pipeline. It is slower, but re‑guarantees that the intermediate artifacts are consumable.

After next build finishes, OpenNext runs with --skipNextBuild (because the Next build already happened) and emits a single Worker bundle into .open-next/worker.js. This is the actual server‑side logic, but it is not referenced directly in the deployment configuration. Instead, wrangler.jsonc declares its entry point as workers/app/index.ts. That file is a thin wrapper—its job is to import .open-next/worker.js and re‑export its fetch handler, while also attaching the scheduled cron handler. The wrapper pattern is a deliberate decoupling: the build can change the internal structure of .open-next/ without requiring a change to the deployment configuration, and it keeps the wrangler.jsonc stable across OpenNext upgrades.

Once the Worker bundle is ready, wrangler deploy uploads it to Cloudflare. The deploy command exits 0 as soon as the upload succeeds—it does not verify that the site actually renders. This is a known blind spot: a revoked D1 token or a misconfigured binding can leave every route returning a 500 while the deploy “succeeds”. That hole is patched by npm run cf:verify, which runs scripts/verify-deploy.sh. The script issues curl requests to two routes: the apex (/) and a dynamic, D1‑backed lesson route (/embeddings). Each request includes a cache‑busting query parameter (?cb=<timestamp>-<attempt>) so that edge cached responses don’t mask a runtime failure. It retries up to five times with a four‑second sleep between attempts (both configurable via environment variables) to absorb cold starts and edge propagation delays. Only when both routes return 200 does the script exit cleanly; otherwise it prints a failure message and suggests running npx wrangler tail to inspect the logs.

The full pipeline—integrity gate, Webpack‑backed Next build, OpenNext emission, wrapper entry point, and post‑deploy smoke test—means that a broken manifest never reaches production. If the build passes, the deploy is almost guaranteed to work. If the deploy succeeds, the smoke test confirms it. The only remaining risk is a runtime failure that occurs after the first request (e.g., a D1 query that times out under load), but that is a different class of problem, handled by monitoring and alerting. For the data‑path failures that historically haunted this site, the chain has proven robust.

The guide pages are not written from memory; they are generated by retrieval over the real source files, using the content grounding pipeline assembled in roadmap-kg/kg/memory_common.py. The pipeline’s first step is to split the raw source text into chunks suitable for embedding and search. This is done by _default_splitter, a SentenceSplitter from LlamaIndex that cuts text into tokens. By default it uses a chunk size of 512 tokens and a chunk overlap of 64 tokens, both tunable via the environment variables CHUNK_SIZE and CHUNK_OVERLAP. Every memory lane — the on‑page reading lane and the spoken audio lane — uses this identical splitter so they segment source content the same way.

The overlap is not a cosmetic detail; it is the precondition for faithful retrieval. An important fact or phrase that straddles the exact boundary between two 512‑token chunks would be truncated in one and start in the next, making it invisible to a nearest‑neighbour search that only sees whole chunks. By overlapping the chunks, each boundary fact is fully present in at least one chunk, and often appears redundantly in two, so retrieval never loses the middle of a sentence or a cross‑chunk reference. Without overlap, the pipeline would systematically miss content at chunk seams, producing gaps in the generated guide.

Once the source is split, each chunk is embedded into a vector. The embedding is performed by a call to cached_text_embeddings, which consults a persistent SQLite cache keyed on a SHA‑256 hash of the text and the model name (default BAAI/bge-small-en-v1.5). This cache lives at _APP_ROOT / ".embed-cache" / "embeddings.db" and is shared with the /query service, so repeated grounding runs re‑use vectors instead of re‑embedding unchanged texts. The cache can be bypassed with EMBED_CACHE=0 for benchmarking.

The embedded chunks are then assembled into a searchable index. The function sync_nodes (also in memory_common.py) takes the list of chunk nodes and their embeddings, and pushes them into a vector store. By default the store is Qdrant, falling back to an in‑memory VectorStoreIndex when Qdrant is not configured. The index is opened via open_vector_index with the same namespace (e.g. "inline-memory" or "audio-memory"), ensuring each lane has its own collection. A single document ID is attached via _attach_scope so chapters can be tracked as groups.

This index is the engine that powers the recall cues and callback devices in the guide. When a chapter needs a grounded term or sentence to quiz the reader, the pipeline queries the index for the most relevant chunk, extracts the centermost term using term_centroid_score (a cosine‑bonus scoring function that rewards terms that are semantically close to the chapter’s centroid), and presents it as the recall answer. The chunk boundary that overlap made safe is now the boundary that delivers a complete, answerable fact. The entire chain – split, embed, index, retrieve, score – runs over the real source, not a human‑written summary, which means the generated guide stays mechanically faithful to the codebase it explains.

The site never stores an embedding API key. Every vector in the pipeline is produced locally by a single in-process FastEmbed model built in roadmap-kg/kg/llm.py’s make_embed function. That function instantiates a FastEmbedEmbedding with the model named by the environment variable EMBED_MODEL (defaulting to BAAI/bge-small-en-v1.5, 384 dimensions). The ONNX weights are downloaded exactly once per process life: the constructed object is stored in a module-level dictionary _EMBED_CACHE keyed by the model name, so any subsequent call to make_embed returns the same object without re‑loading the weights. This means there is no embedding API key anywhere in the stack — the operation is purely local and works with the network unplugged.

That local model alone would still re‑embed the entire corpus every time a lane runs (audio memory, inline memory, mnemonic grounding). To eliminate that cost, roadmap-kg/kg/memory_common.py provides a persistent cache: cached_text_embeddings. It accepts a list of texts, computes a SHA‑256 hash of model + separator + text via embed_cache_key (optionally partitioned by a namespace), and checks a local SQLite database. Only the texts whose hashes are not yet stored are sent to the embedding model; all others are returned from the cache as packed float32 vectors. The database lives at the path given by _embed_cache_path() (which defaults to a .embed-cache/embeddings.db in the app root), and the cache can be disabled entirely by setting EMBED_CACHE=0.

The trade‑off this design buys is speed and autonomy. Because the cache key includes the model name, swapping EMBED_MODEL is a clean miss — no stale vectors from a different model can leak in. And because the cache is incremental (one row per unique text, not per batch), editing a single chapter re‑embeds only that chapter’s text; the rest are served from disk at near‑zero cost. The result is a pipeline that runs locally, requires no network, and on the second run over an unchanged corpus makes zero embeddings calls — the same ~98× repeat‑run speedup that the /query service already enjoyed. The only side effect is the cache file, and the embedding values are bit‑for‑bit identical to what the uncached model would produce.

The language model egress in the roadmap knowledge‑graph service is resolved by make_llm() inside roadmap‑kg/kg/llm.py. That function inspects environment variables in strict, first‑available‑wins order — three tiers, each with its own API base, key source, timeout, and retry configuration. The precedence is enforced by early return statements, not by a cascade that tries whatever is around. That choice is deliberate: it prevents a stray environment variable from silently pulling a production request onto a local model.

The highest‑priority tier fires when DEEPSEEK_API_KEY is set. In that case _build_deepseek() is called directly with api_base=“https://api.deepseek.com”. No fallthrough occurs — the key is sourced out‑of‑band (a one‑shot env or an out‑of‑repo .env file) and must never be committed. The model id is read from DEEPSEEK_MODEL_DIRECT; if it happens to be the legacy deepseek-chat, the code transparently maps it to deepseek-v4-flash, its current non‑thinking successor. A direct key means the code never reaches the local server branch, so a stray LLM_BASE_URL cannot quietly hijack the request.

If no DEEPSEEK_API_KEY exists but LLM_BASE_URL is set, the function instantiates a plain OpenAILike from llama_index.llms.openai_like, pointed at wherever LLM_BASE_URL points — typically a local llama.cpp server or LM Studio. The model field is informational (the server ignores it), and a smaller default context window (LLM_CONTEXT_WINDOW, default 32768) plus a longer timeout (LLM_TIMEOUT, default 300 seconds) compensate for a slower local box. Tool calling is disabled because quantized models handle it unevenly.

The lowest‑priority fallback is the Cloudflare AI Gateway. It calls _build_deepseek() with api_base from deepseek_base_url() (which defaults to a Cloudflare gateway URL, or reads CF_AIG_BASE_URL) and api_key from deepseek_token() (reads CF_AIG_TOKEN). The model id is provider‑prefixed by _gateway_model() — it prepends deepseek/ so the compat surface knows which provider to route to. The same DEEPSEEK_CONTEXT_WINDOW and optional LLM_MAX_TOKENS cap apply across both DeepSeek tiers.

Fixed precedence with early returns is safer than “try whatever is around” because it avoids ambiguous fallthrough when multiple environment variables are accidentally set. If the code attempted a local server only when the direct API call failed, a transient network blip could cause an unexpected local fallback with different behavior and no warning. By committing to the first available tier and returning immediately, the developer controls exactly which path runs, and any mismatched configuration produces a clear error rather than a silent substitution. The LLM_BASE_URL guard is especially sharp: when DEEPSEEK_API_KEY is present, the local branch is unreachable even if LLM_BASE_URL happens to be set elsewhere in the environment — the intention of “I want the real DeepSeek” is honoured without risk of accidental local routing.

A grounded code excerpt is only as reliable as the LLM that produced it. Even when the generator is constrained by a retrieval-augmented pipeline, it can still fabricate plausible-looking APIs — a function called execute might appear correct but never exist in the real source. To catch these hallucinations before they reach a reader, the grounding pipeline adds a lightweight verification step that checks every generated code block against the real source identifiers.

The tokenizer that builds the source’s identifier set is _source_identifiers. It uses a regex _IDENT_RE to extract every whole identifier — sequences like index_documents, _build_query_engine, source_idents — and stores them as a Python set[str]. Whole‑token membership is critical: if the real source contains index_documents, then a hallucinated documents or index must not count as grounded just because those tokens appear as substrings of a longer real name. The old substring‑containment test allowed that loophole, so the current design requires an exact match of the entire token.

The checker function is _code_grounding_violations. It first verifies that the emitted markdown contains exactly one fenced code block (_FENCE_RE). Then it extracts all identifiers from that block, discards generic Python stopwords (_CODE_STOPWORDS like def, return, list), and computes the ratio of grounded identifiers — those that appear in the real source’s identifier set — to total identifiers. If the ratio falls below ²⁄₃ (67%), the function returns a list of violation messages naming the unknown symbols.

When a violation is found, the caller _ground_code_chapter retries the query. It feeds the previous violation messages back into the prompt as explicit feedback — e.g., “only 2/4 identifiers trace to the source — quote real symbols, do not invent APIs”. This loop runs up to max_attempts = 3. After the final attempt, if violations still exist, the chapter is still written to the output JSON, but the ground_code function increments a residual counter and prints a warning ("WARNING residual grounding issues"). The residual count is logged so the content team can manually inspect the offending excerpt, but the system does not silently ship unverified code: the warning flags it for human review. The combination of automated retry and persistent logging enforces the “trust but verify” principle — the pipeline trusts the generator enough to try again, but it verifies that the final output actually draws from the real source before considering it clean.

Every guide on this site can be listened to, yet none of the audio is recorded by hand. The narration is synthesized from the same prose text that appears on the screen. The mechanism is a three‑stage pipeline in roadmap‑kg/kg/audio/pipeline.py, which wraps three independently runnable stages: tts, finalize, and stitch.

The pipeline runs from the command line with a slug (e.g. --slug how‑it‑works) and a mode — --per‑chapter or --per‑paragraph — plus an --upload flag. Stage one, tts.main, sends each chapter’s (or paragraph’s) text to a TTS provider, produces MP3 fragments, and optionally uploads them to R2. Stage two, finalize.main, reads those fragments and writes the page‑served data/<slug>.json — a single manifest that maps chapter titles to their audio URLs and seek offsets. Stage three, stitch.main, concatenates every chapter MP3 into one full‑length file on R2 (e.g. knowledge/case‑study‑audio/full.mp3), also producing a unified manifest with per‑chapter start times. The build script make stitch‑langgraph automates this for the LangGraph content, but the same pattern applies across guides.

The MP3s live on R2 rather than in the app bundle because the Cloudflare Worker runtime has no filesystem — anything a page needs must be compiled into the bundle, and audio files are too large. R2 is the same‑origin object store that serves the Worker itself, so streaming stays inside the same Cloudflare network. The player never fetches the files directly from the R2 public domain (tts.vadim.blog). Instead, app/api/audio/[...path]/route.ts runs on the same Worker and acts as a same‑origin proxy. It accepts a path like /api/audio/knowledge/case‑study‑audio/full.mp3, validates the key against the regex KEY_RE = /^knowledge\/…\.mp3$/ (to prevent open proxying), forwards the browser’s Range and If‑Range headers upstream, and relays the 206 Partial Content or 200 response — including Accept‑Ranges, Content‑Range, and Content‑Length. The <audio> element can seek freely because the browser receives proper byte ranges from the same origin.

The rewrite that makes this possible is toSameOriginAudioUrl in app/how‑it‑works/_shared.ts. It takes an R2 public URL (e.g. from the unified audio manifest), extracts the pathname, and prepends /api/audio. The function is used when building fullAudioMeta: the audio_url field is rewritten to the proxy URL, and each per‑chapter URL is cleared so the player uses a single <audio> element and seeks within the stream via chapters[].start_secs. Because the fetch goes to the Worker’s own origin, no CORS headers are needed, and the service worker — which has been intentionally neutered (public/sw.js registers no fetch handler and self‑unregisters) — cannot intercept or stall the stream. The audio plays progressively, byte by byte, just as the browser expects.

A static site is immutable: new content means a build and deploy. This site sidesteps that limitation with a runtime data plane that reads fresh content from Cloudflare D1, a SQLite database that lives at the edge. When a lesson or audio guide is added or edited, the Rust sync-d1 pipeline writes an updated row into the content_cache table, and the next user refresh sees it without a redeploy.

The table has a minimal schema: a compound key of kind and slug together identify each row, and a payload column holds the exact JSON objects the frontend already consumes — ContentIndex, LessonFull, or AudioMeta. Reading is deliberately boring. Inside lib/content-d1.ts, the function getDoc<T>(kind, slug) constructs a SELECT payload FROM content_cache WHERE kind = ? AND slug = ? LIMIT 1, calls d1Query with D1QueryOptions that enable ISR caching (revalidate: 3600 and a tag like "lesson:my-slug"), parses the first row’s payload with JSON.parse, and hands the result to the existing shaper (e.g. lessonWithContentFromFull). If D1 is not configured or the row is missing, every reader returns null — the page then falls back gracefully to the bundled JSON from the build step.

The trade-off here is deliberate simplicity over flexibility. No ORM, no schema migrations in the app code, no secondary indexes — just a key-value‑ish cache that mirrors the static JSON shape. This keeps the read path extremely cheap and easy to reason about, and the single payload column means the data plane never needs to know the internal structure of every content type. The downside is that queries beyond a single-row lookup (e.g. “all lessons updated this week”) are impossible without adding another table or doing full scans, but the pipeline handles that offline.

The d1Query function itself, in lib/d1.ts, has two execution paths. In the Worker runtime, it grabs the native DB binding (declared in wrangler.jsonc as a d1_databases entry) via getCloudflareContext().env.DB. That path uses the Worker’s platform identity, needs no API token, and never triggers fetch — so it never forces a route to dynamic rendering. The fallback path (used during local dev or if the binding is unavailable) constructs an HTTP request to the Cloudflare API v4 endpoint, using environment variables CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_AUDIO_D1_ID, and CLOUDFLARE_D1. That path is explicitly a build/dev fallback and depends on a revocable token; the comment in d1.ts warns that it should be avoided in production.

The fail‑open design is central. Every D1 access is guarded by d1Configured(), which checks whether the native binding exists or the three environment variables are set. If D1 is unconfigured, d1Query throws an error — but the content‑reader functions in lib/content-d1.ts catch that error inside getDoc and return null. Similarly, if a SELECT returns zero rows, getDoc returns null. This means a page that calls getIndexFromD1 or getLessonBySlugFromD1 can immediately fall back to the static JSON imported at build time, and the site never hard‑depends on D1 being available.

Media assets (audio files, images) are not in D1; they live in R2, served from a public domain (tts.vadim.blog). Wrangler config maps the R2_BUCKET_NAME and R2_PUBLIC_DOMAIN, but media reading is handled separately, not through d1Query. The data plane covers only the structured content that changes between deploys.

The ISR caching layer (next: { revalidate: 3600, tags: [...] }) on the HTTP fallback path is a further optimisation: shared content reads are stored in the Next.js Data Cache for one hour, so they do not force every consuming route into fully dynamic rendering. The tags allow the pipeline to bust specific entries on demand via /api/revalidate. On the native binding path, ISR caching is not applied because the binding is already zero‑latency and does not participate in the fetch cache. Callers wrap the entire content‑read chain in React’s cache() — getIndexFromD1 is cache(async () => ...) — which deduplicates concurrent calls for the same page render.

This runtime data plane is the mechanism that lets new lessons appear on refresh without redeployment, while preserving the static‑first character of the app. The fail‑open fallbacks mean an outage in D1 or a missing row never breaks the site — it merely shows the slightly stale build‑time content.

The Next.js application ships as a single Cloudflare Worker, built by OpenNext into a bundle at .open-next/worker.js. That bundle handles all request routing, middleware, and API routes — but it does not export a scheduled handler for cron triggers. Cloudflare Workers receive cron invocations as a distinct scheduled event, not an HTTP request, so the worker entry point must define a scheduled method to process them. This is why a thin wrapper at workers/app/index.ts exists: it becomes the actual default export that Cloudflare runs. The wrapper’s fetch method is a one-line delegation to openNextHandler.fetch, preserving every Next.js behaviour unchanged. The only addition is a scheduled handler that translates cron events into synthetic HTTP requests to the Next.js app.

Inside the scheduled method, the code reads the cron expression from event.cron and maps it to a specific API route. Two cron schedules are declared in wrangler.jsonc under triggers.crons: "0 4 * * *" for a daily backup and "0 * * * *" for the hourly autonomous knowledge-graph tick. The wrapper constructs a Request targeting the app’s origin (from env.APP_ORIGIN or a hardcoded fallback), appending the corresponding path — /api/cron/backup or /api/cron/kg-tick — and signs it with a bearer token from env.CRON_SECRET. That synthetic request is then passed to openNextHandler.fetch, so the Next.js bundle handles the cron logic as if it were a normal HTTP call. This design means the Next.js codebase never needs to know about Cloudflare’s event system; all scheduling translation lives in the small wrapper.

A separate Python-based Cloudflare Worker at workers/edge-tasks handles auxiliary tasks: it includes a keepwarm cron (*/10 * * * *) that pings a Render-hosted LlamaIndex RAG endpoint to prevent cold starts, and a POST / endpoint that expands interview-prep content using DeepSeek through Cloudflare’s AI Gateway. That worker is configured in its own wrangler.toml with independent secrets and environment variables. The fleet therefore comprises two independent workers: the main Next.js worker (wrapped with the cron shim) and the edge-tasks worker. The separation keeps the core Next.js path simple and fast while offloading background tasks to a simpler, language-appropriate worker that can be deployed and scaled separately.

Machine-generated audio scripts cannot be trusted blindly. A TTS pipeline might produce a chapter with no narration, a title that runs fifty words, or a sentence so complex it is unreadable when spoken. Any of those would ship a broken guide to the user. The eval gates exist to catch these defects before publish, and the cheapest, most reliable gate is the mechanical audio gate—kg.audio_gate.

The gate runs over a single AudioMeta JSON (the structure that holds the full script, chapters, duration, and audio URL for a guide) and returns exit code 0 if the guide is ok, exit code 1 if it has hard failures. It is intentionally self-contained: it pulls in no LlamaIndex, no embedding models, no environment machinery. That means it can run on every guide during generation without adding latency or dependency risk. The entire gate lives in one file and costs a fraction of a second per guide.

Inside gate_audio(meta), the gate collects two lists: failures and warnings. Only failures flip the ok bit. The hard failures are crisp, deterministic rules that block publish when violated. The meta-level checks verify that the slug and title are non‑empty, that there are at least MIN_CHAPTERS chapters (currently three), that duration_secs is not zero, and that the TTS state is consistent (a pending-tts voice must have an empty audio URL). Per‑chapter hard checks include verifying the chapter index matches the array position, that chapter titles are non‑empty, no longer than MAX_TITLE_WORDS (five words) and MAX_TITLE_CHARS, and that titles are unique. The script itself is scanned by a series of _scan_* functions: prose rules reject backticks, code fences, pipe characters, bullet lists, headings, markdown links, visual references, and closing phrases; _scan_hostile_tokens catches common mispronunciations; _scan_pacing_rhythm enforces a maximum sentence length (hard failure when a sentence exceeds thirty words); _scan_audio_readability enforces a minimum Flesch Reading Ease score; _scan_small_digits_hard flags digits below ten that should be spelled out; _scan_sentence_integrity and _scan_sentence_nesting catch structural issues; and _scan_acronym_first_use ensures every acronym is expanded at its first appearance in the chapter.

Alongside these hard blocks, a set of WARN-only heuristics live in a separate path. They are too false‑positive‑prone to block publish—things like monotone sentence‑variety cadence, teens that should be spelled out, and seven TTS‑quality signals (prosodic‑break density, garden‑path sentences, cloze floor, homograph risk, filler density, pronoun ambiguity, working‑memory load). These warnings never appear in the failures list; they contribute to a quality score that can be reviewed offline.

Why a cheap deterministic gate? Because the generation loop runs it after every chapter rewrite, inside a retry loop, and any expensive or non‑deterministic check would make the loop slow or unstable. The gate’s hard rules are compile‑time constants shared with the Rust parity oracle (gate.rs) so there is no drift between the in‑loop gate and the standalone publish gate. By keeping the gate rule‑based, cheap, and stateless, the system catches the majority of shipping defects—mispronunciations, formatting leaks, missing chapters, unreadable prose—without ever needing to run a language model. The rare, fuzzy issues bubble up as warnings and are handled by human review.

The app exposes two distinct learning surfaces, both engineered for remembering what you read: /memorize (spaced‑repetition flashcards) and /loci (a memory‑palace trainer that walks cards along a route). They rest on the same FSRS‑6 core in lib/sm2.ts, but each has its own scheduler — only the FSRS‑6 model is shared, not the whole scheduling logic.

lib/sm2.ts exports fsrsUpdate, which takes a rating (FsrsRating: again, hard, good, easy) and a prior FsrsState (stability, difficulty, reps, lapses) and returns the updated state along with a suggested interval via intervalForRetention. This is the mathematical engine that estimates how long a memory will last. Both surfaces call it, but they wrap it in different layers to fit their interaction models.

/loci uses the scheduler in lib/loci-scheduler.ts, a set of pure functions — no React, no localStorage, no I/O. It adds two thin wrappers on top of lib/sm2.ts. First, an onboarding ladder: new cards graduate through fixed short intervals defined by the PHASES constant (["onboard1", "onboard2", "onboard3", "fsrs"]), with default durations like DEFAULT_ONBOARDING_MINUTES (10 minutes, 1 day, 3 days). Every grade still calls fsrsUpdate so the latent DSR state stays honest, but the ladder overrides the resulting interval while phase !== "fsrs". Once graduated, intervals come from intervalForRetention(stability). Second, an in‑session Leitner queue: buildSession orders due cards along the route; an again grade recycles the card to the back for another pass in the same sitting. The first grade a card receives in a session is persisted to FSRS — recycle passes are practice‑only, logged but never re‑persisted. That rule lives in gradeSessionCard. The data shape LociSchedState also includes a cueFp fingerprint: when the cue later differs (e.g., a new route), the schedule resets via reconcileCues — encoding specificity in action.

/memorize uses a different scheduler; the code for it isn’t shown in the provided context, but it also depends on fsrsUpdate from lib/sm2.ts. The design decision to keep separate schedulers means each surface optimises for its own cognitive‑load pattern. /memorize can be a straightforward implementation of FSRS‑6 with no extra wrappers. /loci needs the onboarding ladder (so users don’t drown in brand‑new cards) and the Leitner queue (to support walking the same route multiple times in a session). The shared core is the model itself, not the scheduling policy.

The learning‑science and principles pages under app/how‑it‑works/ document the evidence base each feature applies. The catalogue at app/how‑it‑works/learning-science/page.tsx is a fully static page built from data/learning-science.json and data/technique-recommendations.json at build time. It lists techniques (spaced repetition, retrieval practice, interleaving) sorted by paper count, each linked to DOI‑verified papers, with JSON‑LD structured data on a CollectionPage / Dataset. The principles deep‑dive at app/how‑it‑works/learning-science/principles/page.tsx is hand‑authored in ./content.tsx with typed Principle, Citation, and EvidenceItem interfaces — ReactNode paragraphs for inline emphasis and compile‑time checking of citation keys. It explains mechanism, boundary conditions, and implications for mnemonic‑generation systems. The /loci feature directly implements spacing (via FSRS intervals), retrieval practice (through graded recall), and encoding specificity (via cueFp). The learning‑science pages are the written justification for why these schedulers are built the way they are — grounded in peer‑reviewed evidence, not intuition.

The "How It Works" guide acts as the centerpiece of a small family of companion guides — the primers (First Principles, LlamaIndex, Memory Science), the pillar walkthroughs (Agentic RAG, Evaluation, Autonomy), and a standalone Glossary — that all share a single navigation shell. Every piece of that shell is driven by one plain JavaScript array in lib/case-study-guides.ts called CASE_STUDY_GUIDES. Each entry in the array is an object with properties like slug, basePath, title, short, icon, kind, single, and textAtBase. There is no second list of links, no manual href string scattered across components.

The GuideNav component in components/case-study-guide-nav.tsx consumes this array to produce three navigation elements: the cross-guide hub (a row of pills linking every guide), the per-guide Text/Audio tab bar, and the sequential Back/Next pager. The component receives only activeSlug and activeTab as props; it never needs to know how many guides exist or what their URLs should be. That knowledge lives entirely in the data array.

URLs for every link are derived from a guide’s basePath using a small helper function, also inside the component file, called guideHref. It checks the single and textAtBase flags to decide whether the default view lives at the raw basePath (for single‑page guides like the Glossary or for guides whose reading page predates an audio companion) or at ${basePath}/text. Because guideHref is used by the hub pills, the tab bar’s Text link, and the Back/Next pager, all three navigation elements automatically stay synchronized with any change to a guide’s basePath or flags. The tab bar itself is conditionally rendered — it is hidden for guides with single: true, because those guides have no Text/Audio split and their hub link already points to the single view.

The Back/Next pager relies on the order of CASE_STUDY_GUIDES itself. It finds the current guide’s index in the array, then picks the previous and next entries. This guarantees that the pager follows the same sequence as the hub pills, and that adding or removing a guide from the array updates the pager automatically.

The design trades a tiny duplication of field names (each guide object repeats the same shape) for a massive reduction in cross‑file coupling. There is no need to update a separate navigation config, no risk of a hub link pointing to one URL while the pager points to another. The array becomes a single point of truth that defines the order, the labels, the icons, and the URL construction rules for the entire guide family. Anyone adding a new companion guide can do so by inserting one row of data; the navigation shell, including the hub’s aria-current highlight and the pager’s sequential arrows, will adapt without touching any JSX.

The hand-rolled loops that originally grounded claims and judged flashcard relevance in a single while cycle are being systematically ported to event-driven workflows from the llama-index-workflows package. The migration costs exactly zero new dependency entries because the pinned llama-index-core already bundles llama-index-workflows as a standalone package, and llama_index.core.workflow is merely a one-line shim. Direct imports like from workflows import Context, Workflow, step survive any future core bump without a lockfile change.

In kg/claim_workflow.py, the old retrieve → draft → assess → revise loop is re-expressed not as procedural logic but as a graph of @step methods connected by typed events. ClaimStartEvent carries the technique slug; the retrieval step produces an EvidenceEvent with corpus evidence and vocabulary terms; the drafting step emits a DraftEvent holding the candidate claim; the oracle’s rejection sends a ReviseEvent carrying the missing terms back into the drafting step. A CiteEvent marks the end of the grounding loop, and a ProgressEvent streams every step’s action and observation for external consumers. Each edge is declared as a Python dataclass, so the workflow graph is explicit data, not implicit control flow. Loops (revision cycles) are handled by emitting ReviseEvent from the assessment step; the step machinery re-queues that event naturally, bounded by the max_revisions parameter.

Durability and resumability come from kg/workflow_store.py. This module maintains a SQLite database at .workflow-runs/runs.db. After every ProgressEvent, the running Context is serialized with JsonSerializer and upserted into the store via save_ctx. If a run crashes, a later invocation with --resume RUN_ID calls Context.from_dict on the stored snapshot. The restored context is already marked as running, so completed steps are not re-executed; only the in-flight events are re-queued. The store also tracks status (running/done) and final results, and is entirely local-first using only stdlib sqlite3 and json.

The FastAPI service in rag_service/main.py wires the workflow into its endpoints. Routes, defined in research-routes and routes, invoke run_claim_workflow (or its async wrapper arun_claim_workflow) with an on_progress callback. That callback pushes each ProgressEvent to the client, typically via Server-Sent Events or a WebSocket channel, so the user sees the agent thinking live. Because the workflow steps themselves are deterministic and the progress events carry the same shape as the reference loop’s in-memory trajectory, the streaming layer is a transparent addition—not a separate simulation.

What this buys over a hand-rolled loop is twofold. First, streaming makes the agent’s reasoning observable to the user without polling or storing the entire trajectory in a mutable variable. Second, durability turns a single-session operation into a recoverable, auditable run: a production crash during a long citation check no longer wastes the already-completed retrieval and drafting work. The typed event graph also makes the extension path obvious—adding an extra validation step requires only a new event class and a @step that receives and emits it, without touching the existing loop structure.