Files

SocratiQ

SocratiQ is the book's in-page tutor and study workspace. The shared reader is included in the HTML configuration for all four volumes. The larger study bundle loads only when a reader opens Study tools.

Reading and studying

The reader supports selected text → Explain this, follow-up questions, Simplify, Show an example, and Check my understanding. On touch screens, Choose a paragraph previews a passage before a request is sent. Recent passages retains up to five discussions and drafts on the current page. Start over clears only the current discussion. Copy answer includes source provenance; the source link returns to the passage in the same tab.

Study tools opens the existing workspace for quizzes, flashcards, saved conversations, progress, the knowledge graph, settings, and exports. Returning to the reader preserves its current discussion. The workspace mounts once per page; opening it does not enable a persistent activation cookie.

The first deliberate reader opening offers a skippable tour; Replay tour reopens it. Learning preferences saves the explanation level and optional background/goal in this browser, shared with study settings. Saving preferences sends nothing; subsequent AI requests include them. Clear preferences resets the intermediate level and clears both text fields. No account or device sync is provided.

AI-generated explanations and questions can be wrong. A source link identifies the supplied passage; it does not establish that every generated claim is supported. Check-understanding feedback is not a graded assessment or evidence of mastery. The graph's extracted relationships are not authored prerequisite relationships.

Data and service boundaries

  • Reader discussions live in page memory and disappear on reload or navigation.
  • Study records use browser-local IndexedDB and local storage. They are not synchronized to an account or another device. Browser data deletion also removes these records; use the workspace's exports to retain study material.
  • Progress summarizes recorded results and cumulative-quiz outcomes. An unknown number of available chapter quizzes is not replaced with an invented target.
  • Quiz identities include their source page so matching titles in different volumes do not share scores. Old records without an unambiguous source remain unassigned rather than being attributed to an arbitrary volume.
  • Schema repairs preserve existing stores and records. Saved chat HTML is sanitized on restoration; imports are validated before writes.
  • Selecting or previewing text does not send it. Asking for AI help sends the selected passage, local section context, question, and bounded conversation history to the configured proxy. Study AI actions likewise send their requested source content. There is no reader usage or learning analytics pipeline.
  • Cloud quiz submission and collaborative synchronization are unavailable. Local storage does not imply that those services have been restored.

The production chat gateway is https://mlsysbook.ai/api/socratiq. Its source and operating contract are documented in cloudflare/. Reader and study Groq defaults use the shared configuration in src_shared/provider-config.js; provider credentials stay on the Worker. The gateway supports the explicitly allowed Groq models and rejects unsupported providers without choosing a fallback. The study workspace's custom API option is an explicit user override, separate from the public gateway.

The Worker is activated with a dedicated encrypted Groq credential, after verification of Groq and Cloudflare Free plans. Activation and local transport tests do not establish live model quality or available quota. Local tests use constructed upstream responses. The deployment health check establishes dispatch only; live inference controls and browser checks establish different parts of the request path. See the gateway README for limits, disable/rollback procedures, provider privacy, and the manual deployment workflow. No API key belongs in a book script or build.

Build and test

cd socratiq
npm ci
npx playwright install chromium webkit
npm run build:reader
npm run build:vite
npm run test:local
npm run test:gateway
npm run test:reader:browser
cd ..
python -m pytest -q binder/tests/test_socratiq_html_integration.py --confcutdir=binder/tests

The reader build writes books/shared/assets/scripts/socratiq/reader.js. The study build writes books/shared/assets/scripts/socratiq/study.js and the legacy artifact at binder/tools/scripts/socratiQ/bundle.js. Commit generated artifacts with their source changes. Both builds embed WOFF2 math fonts without duplicate TTF/WOFF copies. Quarto stages the shared directory in every volume; the study loader resolves its URL beside the deployed reader script, preserving the volume prefix. The socratiq-validate.yml workflow checks rebuild drift and runs local, browser, and Quarto integration tests.

Tests using constructed responses exercise behavior, not model quality. Storage tests use isolated browser data. Chromium and WebKit viewport tests cover phone and tablet layouts; they do not replace physical-device checks of native selection handles, software keyboards, or assistive technology.

Optional live checks send public or author-constructed passages to the configured service and save raw evidence. They are excluded from CI:

node tests/reader-live-smoke.mjs /tmp/socratiq-live-UNIQUE-RUN
node tests/reader-quality-probes.mjs /tmp/socratiq-probes-UNIQUE-RUN

Review the saved answers against the source and the declared criteria. Do not interpret these small, unscored probes as learning-effectiveness measurements.

Code map

Location Responsibility
src_reader/index.js Book entry point and configuration
src_reader/context.js Visible passage capture, math source, bounded context, source return
src_reader/picker.js Explicit paragraph picking
src_reader/ui.js Reader interaction and request lifecycle
src_reader/passage-sessions.js Bounded discussion snapshots and restoration
src_reader/environment.js Theme, viewport geometry, and listener cleanup
src_reader/study.js Lazy study loading and recovery
src_reader/transport.mjs Request validation, streaming, cancellation, and service errors
src_reader/render.js, styles.js Sanitized Markdown/math and responsive presentation
src_shadow/js/index.js Study bootstrap and embedded open/close bridge
src_shadow/js/components/ Quizzes, flashcards, progress, history, graph, settings
src_shadow/js/libs/ Provider adapters, storage, and shared utilities
src_shadow/configs/ Study provider settings and prompts

For standalone study development, npm run dev starts the Vite fixture with legacy activation enabled. The book integration instead uses an explicit embedded bridge and keeps the reader as its single entry point.

Release and rollback

Publish through the existing book release process after review. Neither a local merge nor a successful build updates the public website. Confirm live inference and operational ownership before describing a release as restored. Removing the reader script includes from books/config/_quarto-html-vol{1,2,3,4}.yml disables the companion without changing book content or deleting stored study records.