Studigo

Studigo is an AI study companion that turns a student's own class materials into a grounded, course-specific tutor.

Students create a Study Room, upload teacher study guides, textbook chapters, notes, worksheets, and presentations, then use one workspace to learn, ask questions, quiz themselves, generate flashcards, track mastery, and keep the work as a downloadable study guide.

Give Studigo what you are supposed to learn and the resources you are supposed to learn it from. Studigo turns them into a study companion.

Play the math game (beta)

▶ Play Moon Keep. It's a multiplication Metroidvania prototype and the current golden build.

• The previous golden builds are Moon Keep (POC X) and Moon Keep (POC IX).
• It plays in the browser with a keyboard or touch, and ↺ in the header restarts a run.
• It's a standalone prototype served from GitHub Pages, not part of the Studigo app.
• The source, rules and tests are in prototypes/moon-road/. Start with POC-XI.md.
• Run and test it: python -m http.server 8123 from prototypes/moon-road/dist (open /poc-xi/), and node --test "prototypes/moon-road/test/**/*.test.mjs" from the repo root.
• Making art or levels for the game? The local tools (Pixelorama, LDtk, TexturePacker, Blender, Godot) and the pipeline are in TOOLCHAIN.md. Tool binaries stay on your machine and are never committed.

Engineering start here

For engineers, reviewers, and coding agents, start with ENGINEERING.md. It explains the AI/software authority boundary, why the main technologies were selected, the end-to-end data path, where each responsibility lives in the codebase, and which deeper contract to open next.

The canonical execution plan is implementation/ENGINEERING_PLAN.md. Security readiness and public-launch blockers are maintained under implementation/security-readiness/.

Status

The core student loop — sign up → create a Study Room → upload materials → ingest → ask → cited answer — is implemented and working end to end, along with Learn, Quiz, Flashcards, and mastery derived from real practice.

• Frontend: Next.js + React, responsive PWA shell.
• Backend: Next.js route handlers + Supabase Auth/Postgres/Storage.
• Authentication: Supabase Auth with Google, Apple, and Microsoft social OAuth as the launch providers, plus email fallback. Facebook is a later optional provider.
• AI layer: provider-isolated OpenAI Responses + embeddings package.
• RAG: Supabase Postgres + pgvector with room-scoped similarity search.
• Documents: private uploads, metadata, processing states, and signed downloads.
• Executable layer: installable PWA now; Tauri desktop shell is reserved separately, and the chosen App Store route is an Expo/React Native iOS client over the existing hosted backend.
• Engineering handoff: ENGINEERING.md is the compact start-here map; deeper product/architecture contracts live in docs/, and the canonical engineering execution plan lives in implementation/ENGINEERING_PLAN.md.

What works today:

• Accounts. Email/password sign up, sign in, sign out; sessions refreshed in middleware and persisted across visits.
• Study Rooms. Create, open, rename, retitle, set a test date, delete (originals removed from storage with the room). Scoped per user by RLS.
• Uploads. Drag-and-drop PDF, DOCX, PPTX, TXT, Markdown, and photos of handouts, tagged by source type, with live processing state, duplicate detection, retry, and the original always openable and downloadable.
• Ingestion. Text extraction preserving page and slide numbers, OCR for scanned pages and images, normalization, page-accurate chunking, batched embeddings into pgvector.
• Ask Studigo. Streaming answers retrieved from that room only, with citations that open the learner's own file at the cited page, and an explicit "not in your materials" response when the evidence is not there.
• Study-guide intelligence. A teacher study guide automatically produces the topic map, each topic linked to the passages supporting it.
• Coach, with Ask and Learn inside. The Study Room has five pages: Coach, Practice, Progress, Plan and Materials. Learn answers from the room's own materials as a cited outline built from the study guide, never grades, and has four starter chips (including "How Learn works") that explain how it differs from Coach. Replies need no special format: small misspellings are understood and an irrelevant reply is redirected without penalty.
• Quiz / Flashcards / Practice Test. Real modes over the same knowledge base: generated multiple-choice, true/false, fill-in and short-answer questions with model-graded free text, and spaced-repetition cards. Fill-in blanks read past typos (credited at 85, exact at 100) through one shared typo module.
• Mastery. Calculated from actual quiz and review performance — unpracticed topics count as zero, and a room with no practice shows no number at all.
• Adaptive learning control plane. The shared deterministic director now owns progression/scaffolding/recommendations underneath Coach. Production enables the atomic Coach and adaptive-session paths; the standalone durable-session route remains off until its lifecycle is atomically linked to Coach pending encounters.
• Companion. Studigo's interactive companion is integrated across the Study Room and homepage with shared sprites and state-driven reactions. It is presentation only and cannot award mastery or alter progression.
• Study Guide recovery. Materials includes Refresh study guide to force a clean reread/reindex and rebuild the topic map when derived scope becomes stale, without deleting learning history.

Downloadable study guide

A Study Room now exposes a one-click Download study guide action. The first release generates a PDF from the current learner-edited topic map, grounded source passages, source/page references, and check-yourself prompts. Empty or insufficient rooms return an explicit error rather than a fabricated guide.

Mobile open/download and print-layout validation still belong in the real-user beta pass. See docs/USER_TEST_CASES.md.

The next product-validation cycle is defined in docs/USER_TEST_CASES.md. Coach now exposes only Show me / Coach me / Challenge me while the room-wide explanation level remains Simpler / Standard / Deeper across Coach and Learn. The older coaching-style, learning-tradition and practice-recipe research remains an internal strategy/reference library in knowledge/teaching-coaching/README.md.

Known limits: ingestion still runs inside the request (idempotent and retryable, but a very large scanned PDF can exceed the function timeout) rather than on a durable worker. Durable learning sessions exist, but the standalone session route stays disabled until Coach/session pending-state linkage is atomic. Native iOS packaging is not implemented yet; the selected release path is in docs/APP_STORE_RELEASE_PLAN.md.

Active investigation — Coach "give me N questions"

The Coach routes "give me 10 questions" into a dedicated practice-generation path, spreads generic sets across enough high-priority room material to sustain the requested count, avoids prior prompts during top-up generation, and treats follow-up answers as tutoring interactions rather than literal text matching.

Short answers are graded for semantic understanding. Partial understanding gets partial credit plus a targeted nudge; an unrelated answer is redirected with a simpler rephrasing and source-grounded hint; "I don't know" enters scaffold mode. Live-site verification against the production model is still required.

The temporary anonymous-app and production fixture bypasses used during earlier Coach debugging have been removed. /app requires authentication again, and /dev/study plus /api/dev/coach are development-only.

• Problem, scope, and root causes: PROBLEM_STATEMENT.md
• Chronological change log and reversion checklist: ATTEMPTED_FIXES.md

Authentication direction

Studigo uses Supabase Auth as the single identity layer for the web/PWA product and future native shells.

Launch priority:

1. Google
2. Apple
3. Microsoft (Azure / Entra ID)
4. Email fallback
5. Facebook later if product demand justifies it

The Next.js implementation should use Supabase's SSR/cookie pattern with an /auth/callback route. Provider credentials belong in Supabase Auth provider configuration, never in browser source code.

The login experience should use the Studigo "Personal Learning Device" design system (docs/DESIGN_SYSTEM.md) around provider-recognizable sign-in controls. Keep Google/Apple/Microsoft buttons familiar and trustworthy rather than restyling them into generic product CTAs.

See docs/AUTH.md for the canonical provider, callback, session, security, and first-login architecture.

Repository layout

apps/
  web/                 Next.js UI + server/API routes
  desktop/             Tauri executable-shell placeholder
packages/
  ai/                  model/provider + RAG prompt contracts
  documents/           file policy, extraction, OCR splitting, chunking
supabase/
  migrations/          database, pgvector, RLS, retrieval RPC
  functions/           reserved for future out-of-request workers
knowledge/
  teaching-coaching/   Coach-method KB derived from the live UI taxonomy
implementation/
  ENGINEERING_PLAN.md  single execution plan (workstreams L, E, P, M, G, O, S, H, W)
  security-readiness/  reusable evidence-backed security control framework
docs/
  README.md            specialist documentation map
  ...                  product, architecture, release and verification contracts

GitHub Codespaces preview

Studigo includes a dev-container configuration for a browser-based preview directly from GitHub.

1. Open the repository in GitHub.
2. Choose Code → Codespaces → Create codespace.
3. Wait for dependency installation; the container starts pnpm dev automatically.
4. Open forwarded port 3000.
5. Visit /dev/study?mode=coach for a no-secrets fixture that exercises the current Coach UI/engine and the downloadable Study Guide PDF.

The fixture is development-only and uses synthetic study material. To run the full authenticated Study Room flow inside Codespaces, add the normal Studigo environment variables as Codespaces secrets and configure the forwarded Codespaces URL as an allowed Supabase redirect URL.

Local development

Prerequisites: Node 22, pnpm, a Supabase project, and an OpenAI API key for backend/AI features. The current homepage can render without Supabase/OpenAI configuration.

pnpm install
cp .env.example .env.local
pnpm dev

Apply the migrations in order before using the app:

supabase db push   # or run 001_initial.sql then 002_core_loop.sql by hand

002_core_loop.sql adds ingestion bookkeeping, the topic map, quizzes, flashcards, the derived-readiness function, and the owner-scoped retrieval RPC.

Run the test suite with pnpm test (extraction, chunking, citation grounding, and the spaced-repetition schedule), and pnpm typecheck across the workspace.

Vercel

Studigo is a monorepo. The deployable Next.js application is apps/web, not the repository root.

For Vercel, configure the project with:

• Root Directory: apps/web
• Framework: Next.js
• Node.js: 22.x
• Output Directory: framework default (.next)
• Include source files outside the Root Directory: enabled

See docs/VERCEL_DEPLOYMENT.md for the authoritative deployment and environment-variable checklist.

For social auth, production and approved preview callback URLs must also be configured in Supabase Auth. See docs/AUTH.md.

Environment

See .env.example. Never commit real keys. SUPABASE_SERVICE_ROLE_KEY and OPENAI_API_KEY are server-only.

Social provider secrets are configured in Supabase Auth and must not be committed to this repository.

Core retrieval rule

Teacher-provided study guides and teacher materials should carry the highest retrieval/teaching priority. The textbook is supporting evidence. General model knowledge is not the default source of truth.

Current handoff target

Start with ENGINEERING.md. It is the compact map: authority boundary, technology choices, and which file owns a change.

Execute from implementation/ENGINEERING_PLAN.md. That is the single plan (workstreams L, E, P, M, G, O, S, H, W). It replaces the separate draft on PR #81. Do not scan the whole repository to find the next task.

Then open only the specialist contract required for the task, using AGENTS.md and the documentation map. The learning app and Moon Keep have separate release tracks and golden baselines.

Current main is the integrated V3 web beta. The staged V3 engine/UI passes have already landed; do not restart Phase 1/2/3 from scratch. Read docs/ADAPTIVE_BETA_EVIDENCE.md for what is actually verified and what remains open.

The next release gates are: atomically bind durable learning sessions to Coach pending encounters; finish trusted Quiz/Practice-Test evidence provenance; complete independently reviewed live RAG plus provider latency/cost measurements; move large-document ingestion to a durable worker; close physical-device Study-Guide/PDF acceptance; finish minor/privacy/vendor requirements; then build the universal Expo iOS/iPadOS client and TestFlight path.