Phase 5 — Final sweep and demo readiness

.github/workflows/ci.yml

@@ -41,6 +41,21 @@ jobs:
 
       - run: pnpm test
 
+      - run: pnpm knip
+
+      - run: pnpm tsx scripts/check-doc-paths.ts
+
+      # scripts/find-unnamed-buttons.mts lands via a sibling task. Guarded so
+      # this step is a no-op until that branch merges, rather than failing
+      # every run in the meantime.
+      - name: Check for unnamed accessible buttons (client)
+        run: |
+          if [ -f scripts/find-unnamed-buttons.mts ]; then
+            pnpm tsx scripts/find-unnamed-buttons.mts client
+          else
+            echo "scripts/find-unnamed-buttons.mts not present yet (lands via a sibling task) — skipping."
+          fi
+
       # docs/api-routes.md is generated from the Fastify route registry, so it
       # can only be wrong if someone changed a route and did not regenerate it.
       # This step is what makes that impossible to merge. It runs last because

README.md

@@ -1,13 +1,17 @@
 # Tutor
 
+[![CI](https://img.shields.io/github/actions/workflow/status/rsml/tutor/ci.yml?branch=master&label=CI)](https://github.com/rsml/tutor/actions/workflows/ci.yml)
+[![License: GPL-3.0](https://img.shields.io/github/license/rsml/tutor)](LICENSE)
+[![Latest Release](https://img.shields.io/github/v/release/rsml/tutor)](https://github.com/rsml/tutor/releases/latest)
+
+Start here. [ARCHITECTURE.md](ARCHITECTURE.md) is the entry point for technical readers. The vocabulary is in [CONTEXT.md](CONTEXT.md) and the decisions, with what each one cost, are in [docs/adr/](docs/adr/README.md).
+
 **Read smarter — personal tutors disguised as books.**
 
 Books suggested and generated just for you based on your feedback, quiz results, and unique learning style.
 
 Talks about this project live in [rsml/talks](https://github.com/rsml/talks).
 
-Reading the code? Start at [ARCHITECTURE.md](ARCHITECTURE.md). The vocabulary is in [CONTEXT.md](CONTEXT.md) and the decisions, with what each one cost, are in [docs/adr/](docs/adr/README.md).
-
 <p align="center">
   <img src="docs/screenshots/library.png" alt="Tutor library showing AI-generated books with custom covers" width="100%">
 </p>
@@ -98,6 +102,34 @@ Give feedback on each chapter. The next one adapts to your quiz results and lear
   <img src="docs/screenshots/settings.png" alt="Learning profile and settings" width="100%">
 </p>
 
+## Architecture
+
+```mermaid
+flowchart LR
+  features["client/features/<br/>feature slices"] --> api["client/api/<br/>typed API client"]
+  api -->|"HTTP and SSE"| routes["server/routes/<br/>thin routes"]
+  routes --> services["server/services/"]
+  services --> ports["server/ports/"]
+  ports --> adapters["server/adapters/"]
+```
+
+Client feature slices call the server through one typed API client. Routes stay thin and hand off to services, which depend on ports rather than concrete adapters.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full five-diagram hub, including how the pieces talk to each other, the server hexagon, the adaptive loop, and the dependency rule.
+
+What each top-level directory is, in one line each.
+
+```
+client/    React renderer, feature slices, one typed API client
+server/    Fastify core, thin routes over services over ports over adapters
+shared/    Zod domain schemas and contract types both sides import
+electron/  desktop shell, window chrome, IPC, embedded server boot
+e2e/       Playwright journeys driving the real app on fake adapters
+           (unit and contract tests are colocated with their source)
+scripts/   generators and repo checks, all wired into CI
+docs/      ADRs, the generated API reference, screenshots, phase plans
+```
+
 ## Build Standalone DMG
 
 ```bash
@@ -112,6 +144,7 @@ pnpm install
 pnpm dev:server         # Keep this running one tab
 pnpm electron:dev       # Run this in a different tab
 pnpm test               # Run tests
+pnpm e2e                # Run end-to-end tests
 ```
 
 Set your Claude, ChatGPT or Gemini API key in Settings (gear icon) on first launch.
@@ -128,7 +161,7 @@ Set your Claude, ChatGPT or Gemini API key in Settings (gear icon) on first laun
 | AI | Vercel AI SDK |
 | Storage | Filesystem (Markdown + YAML) |
 | Desktop | Electron (via vite-plugin-electron) |
-| Testing | Vitest |
+| Testing | Vitest + Playwright (e2e) |
 
 ## License
 

client/api/chat.ts

@@ -12,9 +12,6 @@ import { streamText } from './sse'
  * browser bundle.
  */
 
-/** One turn of chat history, sent to the server as context for the next reply. */
-export type ChatHistoryMessage = z.infer<typeof ChatBodySchema>['history'][number]
-
 /** Everything streamChat needs to ask the tutor about a chapter or a selection. */
 export type StreamChatParams = z.infer<typeof ChatBodySchema> & {
   /** Lets the caller abort the request in flight, since the chat panel cancels one whenever the user restarts or clears the conversation. */

client/api/index.ts

@@ -13,8 +13,7 @@
  * endpoints.
  */
 
-export { ApiError, apiUrl, getApiPort, initApiBase } from './http'
-export type { ApiRequestInit, JsonRequestInit } from './http'
+export { ApiError, getApiPort } from './http'
 
 export { audiobookFileUrl, coverUrl, voicePreviewUrl } from './urls'
 

client/api/profile.ts

@@ -5,7 +5,8 @@ import type {
   SuggestSkillsBodySchema,
   UpdateProfileBodySchema,
 } from '@shared/contracts'
-import type { LearningProfile, Preferences } from '@shared/domain'
+import type { LearningProfile } from '@shared/domain'
+import type { ProfileResponse } from '@shared/responses'
 import { request } from './http'
 import { streamNdjson } from './sse'
 
@@ -25,21 +26,7 @@ export type Skill = LearningProfile['skills'][number]
 /** The model and provider choice every AI-backed profile call sends. */
 type AiRequest = z.infer<typeof AiRequestSchema>
 
-/**
- * The learning profile as the server answers or accepts it over the wire.
- *
- * This is not LearningProfile from shared/domain.ts. That type's fields are
- * style and identity, the shape the profile is persisted as on disk. The
- * profile route folds those two fields into a single aboutMe string before
- * it answers. That aboutMe field is what every caller actually reads, so
- * this module names the wire shape on its own rather than importing a type
- * that would be misleading.
- */
-export interface ProfileResponse {
-  aboutMe: string
-  preferences: Preferences
-  skills: Skill[]
-}
+export type { ProfileResponse }
 
 /** Fetch the learning profile, meaning About Me, preferences, and prior knowledge skills. */
 export async function getProfile(): Promise<ProfileResponse> {