docs(prd): mark public-courses and reset-student-course-progress as done

2026-07-20 01:31:13 +01:00
parent 55e6ddd37e
commit b398836c04
7 changed files with 2 additions and 2 deletions
@@ -0,0 +1,301 @@
+# Public Courses PRD
+
+## Purpose
+Enable course creators to publish **Public Courses** — a new course type where content is fully accessible without signup. Public courses treat every visitor as a guest: there is no "sign in to unlock" flow, no progress tracking, no submissions sent to the server. The goal is a low-friction, SEO-indexable surface that creators can use as top-of-funnel content marketing.
+
+## Product Goals
+1. Add a third course type: **Public** (alongside Live Class and Self Paced; Compliance stays unchanged).
+2. Allow anonymous browsing of a public course's full tree (sections, lessons, exercises) with clean readable URLs.
+3. Keep the implementation deliberately small: no auth gating on public courses, no server-side submissions, no analytics, no donations, no live viewer counts.
+4. Give creators a single customizable **Callout** to drive viewers somewhere (main site, sign-up, paid course, etc.).
+5. Design the lesson surface as a focused, distraction-free reading/watching experience.
+
+## Non-Goals (v1)
+Everything below is explicitly out of scope for this PRD:
+- Guest vs authenticated distinction on public courses (everyone is treated the same)
+- Progress tracking (server, database, or localStorage)
+- Server-side exercise submissions and scoring
+- Guest-to-account conversion / progress merge
+- Analytics, guest events, conversion funnels
+- Live viewer counts / "people learning now"
+- Donations / Stripe payment links on public courses
+- Public-courses directory or landing-page tab
+- Feature flag / phased rollout gating
+- Downloadable asset gating
+- Discussion / community for public courses
+- Per-lesson public/private toggle beyond the existing lock state
+- Public course certificates
+
+## User Roles
+
+Public courses have **one** viewer role: everyone. Authentication state does not change what a viewer can do on a public course — a logged-in user visiting a public course is treated identically to an anonymous visitor.
+
+### Course Creator / Admin
+- Selects course type at creation: **Live Class | Self Paced | Public** (Compliance remains a separate flow).
+- Can convert an existing course between types (behavior of conversion is not changed by this PRD).
+- When the course type is `PUBLIC`:
+  - The question-type picker is filtered to **only auto-gradable** question types.
+  - Per-item slugs (lesson / exercise) are editable; otherwise they are auto-generated from the title.
+  - A **Callout** settings panel is available (title, description, button label, button URL).
+
+## Functional Requirements
+
+### 1. Course Type Selection
+
+`COURSE_TYPE` enum today is `['SELF_PACED', 'LIVE_CLASS', 'COMPLIANCE']` with default `'LIVE_CLASS'`. This PRD changes it to:
+
+```
+enum COURSE_TYPE = ['SELF_PACED', 'LIVE_CLASS', 'COMPLIANCE', 'PUBLIC']
+default = 'SELF_PACED'
+```
+
+Changing the default from `LIVE_CLASS` to `SELF_PACED` is intentional.
+
+A public course must still have `isPublished = true` to be reachable at its public URL. An unpublished public course behaves like any other unpublished course (not accessible).
+
+### 2. Only Auto-Gradable Question Types in Public Courses
+
+Public courses are graded **entirely on the client**. The question-type registry already exposes an `autoGradable: boolean` flag on every question type.
+
+- When the course type is `PUBLIC`, the question-type picker only shows question types with `autoGradable === true`.
+- The API rejects attempts to attach a non-auto-gradable question to an exercise belonging to a public course.
+- If a course is converted **into** `PUBLIC` and it already contains non-auto-gradable questions, the conversion is blocked with a clear error listing the offending questions. (No silent data loss.)
+
+### 3. Lock State (reuse existing)
+
+Public courses reuse the existing `lesson.isUnlocked` flag (and the existing `exercise.isUnlocked` flag) as the gate for "free vs gated" content.
+
+- `isUnlocked = true` → content renders normally.
+- `isUnlocked = false` → the content area is replaced by the course's **Callout** (see §5). The sidebar row for a locked item still renders, with a lock icon next to the number.
+
+Since every visitor is treated as a guest, there is no "sign in to unlock" path. A locked item is a call-to-action surface for the creator's callout.
+
+### 4. Public URLs and Slugs
+
+#### Routes
+```
+(org-site)/course/[courseSlug]                    # course overview: tree of sections/lessons/exercises
+(org-site)/course/[courseSlug]/lesson/[itemSlug]  # a single lesson or exercise page
+```
+
+The URL segment is always `/lesson/` whether the item is a lesson or an exercise. The `itemSlug` resolves to one or the other.
+
+#### Slug storage
+- Add `slug VARCHAR` to `lesson` and `exercise` tables.
+- Slugs are **unique per course** across both `lesson` and `exercise` (they share the same URL segment).
+- On lesson / exercise create, slug is auto-generated from the title (kebab-case, collision-resolved by appending `-2`, `-3`, ...).
+- On title rename, slug is **not** automatically updated (URLs are stable).
+- When the course type is `PUBLIC`, creators can edit the slug from the lesson / exercise settings UI.
+- When the course type is not `PUBLIC`, slugs are still generated and stored (so converting a course to `PUBLIC` later works) but are not surfaced in the UI.
+
+#### Slug format
+- 1–80 chars, `[a-z0-9]` with single `-` separators, no leading/trailing `-`.
+- Validated on both client and server with a shared Zod schema.
+
+### 5. Data Loading Strategy
+
+- `GET (org-site) /course/[courseSlug]` loads the **full tree** server-side: course metadata, sections, lessons, exercises, slugs, titles, order, and `isUnlocked`. No lesson bodies, no exercise question bodies.
+- `GET (org-site) /course/[courseSlug]/lesson/[itemSlug]` loads the **content** of the single item server-side (video URL, lesson body, or exercise questions with answer keys). This render is SSR for SEO.
+- The tree is not re-fetched when the client navigates between lesson URLs — it is passed down through the shared `+layout.server.ts`.
+
+### 6. Lesson Page Layout
+
+Reference designs in `prd/public-courses/design/`:
+- `lesson-page-reference.png` — overall layout
+- `lesson-page-full.png` — full composition (hero video + title + body)
+- `sidebar-active-state.png` — active lesson state in the sidebar
+
+Two-column, non-collapsible layout. No hamburger toggle, no accordion on the sidebar, no hide/show. Sidebar is always visible on desktop.
+
+#### Left sidebar (navigation)
+- Grouped by the course's **sections** (existing `courseSection` / lesson-section concept).
+- Each section renders:
+  - A small, muted section heading (e.g. "AI Foundations"). Plain text — not a button, not collapsible.
+  - A vertical list of that section's lessons and exercises, in their existing `order`.
+- Each row contains:
+  - A **square number badge** on the left with the per-section index (1, 2, 3, …). Numbering resets at the start of each section and is shared across lessons + exercises (they interleave by `order`).
+  - The item title to the right of the badge.
+  - If the item's `isUnlocked === false`, a lock icon replaces the number badge or sits next to it (final placement: TBD with design).
+- The active item (matching the current `itemSlug`) renders with:
+  - **Primary color** (the app's `--primary` token, *not* the hard-coded orange in the screenshots) filling the number badge background, white number text.
+  - **Primary color** title text.
+  - A subtle primary-colored vertical accent bar on the far left edge (outside the sidebar content area, aligned with the row).
+- Hover state (non-active rows):
+  - Number badge gets a slightly darker muted fill.
+  - Title text gets a subtle color shift (muted-foreground → foreground).
+  - Cursor is pointer.
+- No icons on normal rows, no progress rings, no status dots. Keep it text-first.
+
+#### Right content column
+Vertical order, top to bottom:
+1. **Video** (if the item has one) — full-width within the content column, rounded corners, single centered play affordance. Omitted entirely if no video (no empty placeholder).
+2. **Section label** — small, muted text above the title (the name of the section this item belongs to).
+3. **Item title** — large, prominent heading.
+4. **Body** — prose / rich text for lessons, or the rendered question UI for exercises. Readable line length, generous line-height.
+5. **Callout** (see §7) — rendered as an inline card at the bottom of the body, only if the course has a callout configured.
+
+If the item is **locked** (`isUnlocked = false`), the body and video are replaced by the callout card rendered in a larger, centered variant; steps 1–4 above are skipped.
+
+No top banner, no hero image above the video, no breadcrumb. Minimal page chrome.
+
+#### Responsive
+
+**Desktop (≥ `lg`)**
+- Two columns: sidebar fixed width on the left, content column fluid on the right.
+- Sidebar is always visible (not collapsible).
+- No bottom navigation bar.
+
+**Mobile / tablet (< `lg`)**
+- The left sidebar is **hidden**.
+- A **fixed bottom navigation bar** is pinned to the viewport. It has three regions:
+  - **Left**: previous-item button (arrow-left icon). Navigates to the previous item in the flattened, section-ordered sequence. Disabled visually at the first item.
+  - **Center**: large tap target. Shows the current item's position (e.g. the per-section number badge + the item title, or "3 / 12"). Tapping opens a bottom sheet.
+  - **Right**: next-item button (arrow-right icon). Disabled visually at the last item.
+- The bottom sheet (built on `@cio/ui/base/drawer` — vaul-based) slides up from the bottom and contains the **full sidebar tree**: every section with its heading and every numbered row. The sheet supports the native drag-to-dismiss gesture ("swiper from bottom up"). The current item is visually active in the sheet. Tapping a row navigates and auto-closes the sheet.
+- The content column takes the full viewport width minus the bottom bar's height. The page adds bottom padding equal to the bar's height so the callout / body never sits under the bar.
+- The bottom bar uses `--primary` for the center button's accent (matching the sidebar active state) and solid surface background with a top hairline border.
+
+**Shared**
+- "Prev / next sequence" is the flat `ORDER BY sections.order, items.order` across all items (lessons + exercises interleaved). Locked items are part of the sequence — tapping prev/next into a locked item still navigates; the locked state is then rendered in the content column as described in §6.
+- Keyboard shortcuts on desktop: `←` / `→` also move through this sequence (nice-to-have, not required for v1 acceptance).
+
+#### Colors
+All accent colors in the sidebar must resolve to the app's **primary** color token (`--primary`), not the hard-coded orange visible in the reference screenshots. The screenshots are from Cursor Learn and are included purely as a layout reference.
+
+### 7. Creator Callout (per-course setting)
+
+Each public course has an optional **Callout** configured by the creator:
+
+```typescript
+type CourseCallout = {
+  title: string;        // short, 1 line
+  description: string;  // 1–3 lines
+  buttonLabel: string;  // e.g. "Read more on my site"
+  buttonUrl: string;    // absolute URL, validated
+} | null;
+```
+
+- Stored as a nullable JSONB column on `course` (e.g. `callout`).
+- Configured from the course settings page (only visible when course type is `PUBLIC`).
+- Rendered on the public lesson page:
+  - As an inline card at the bottom of the lesson/exercise body (on every item).
+  - As the full replacement when an item is locked (larger centered variant).
+- Opens `buttonUrl` in a new tab (`target="_blank" rel="noopener"`).
+
+When `callout` is `null`, no callout is rendered anywhere (lesson still reads cleanly without it; locked items show a plain "This lesson is locked" state).
+
+### 8. Client-Side Grading
+
+For exercises on a public course:
+- The server ships full question data including answer keys to the client.
+- Grading happens entirely in the browser — correctness, explanations, and "you got X / Y correct" all computed locally.
+- No submission is sent to the server.
+- No attempt history is recorded.
+- Refreshing the page resets the exercise state.
+
+This is an intentional trade-off: public courses are marketing surfaces, so answer keys are not considered sensitive.
+
+### 9. SEO
+
+- Public course lesson URLs render server-side (SvelteKit SSR).
+- Each lesson page sets:
+  - `<title>` = item title + course title
+  - `<meta name="description">` = course description or first ~150 chars of the item body
+  - `<link rel="canonical">` = the public URL
+  - `og:type=article`, `og:title`, `og:description`, `og:image` (course banner)
+- Locked items still render meta tags but the body is replaced by the callout; the `<description>` falls back to the course description.
+- No `robots` meta restrictions beyond what the org already sets globally.
+
+## Data Model Changes
+
+### `course` table
+- `type` enum: add `'PUBLIC'`, change default to `'SELF_PACED'`.
+- New column `callout JSONB NULL` (shape described in §7).
+
+### `lesson` table
+- New column `slug VARCHAR NULL`.
+- Backfill existing rows with kebab-cased titles (collision-resolved per course).
+- After backfill, `slug` becomes `NOT NULL` in a follow-up migration.
+- Existing `public BOOLEAN` column is deprecated — not referenced in new code. Column is **not** dropped in this PRD (to keep the migration small).
+
+### `exercise` table
+- New column `slug VARCHAR NULL`, same treatment as `lesson.slug`.
+
+### Slug uniqueness
+- Enforced at the application layer: a slug is unique per-course across the union of `lesson.slug` and `exercise.slug`.
+- A DB-level constraint is not added in v1 (would require a materialized view or a trigger across two tables); application code must check before insert/update.
+
+## API Changes
+
+### New / modified endpoints (high level)
+
+```
+GET  (public) /org-site/course/:courseSlug
+  → Returns course metadata + tree (sections, lessons, exercises with slugs, titles, order, isUnlocked).
+  → No auth required when course.type === 'PUBLIC' && course.isPublished === true.
+
+GET  (public) /org-site/course/:courseSlug/item/:itemSlug
+  → Returns either a lesson content payload or an exercise payload (with answer keys).
+  → Response is a single shape with a discriminator field (e.g. `kind: 'lesson' | 'exercise'`).
+  → No auth required under the same conditions as above.
+
+PATCH (authed) /courses/:courseId/lessons/:lessonId
+  → Accepts `slug` field (validated against slug regex and per-course uniqueness).
+PATCH (authed) /courses/:courseId/exercises/:exerciseId
+  → Accepts `slug` field (same validation).
+
+POST (authed)  /courses/:courseId/exercises/:exerciseId/questions
+PATCH (authed) /courses/:courseId/exercises/:exerciseId/questions/:questionId
+  → Reject non-auto-gradable question types when the parent course is PUBLIC.
+
+PATCH (authed) /courses/:courseId
+  → Accepts `callout` object (nullable).
+  → Accepts `type` (validates transition, including the "no non-auto-gradable questions exist" check when converting to PUBLIC).
+```
+
+Per the repo's single-response-shape rule: the item endpoint returns one response shape with a `kind` discriminator; client narrows on `kind`.
+
+## UI Components Needed
+
+- `PublicCourseShell` (layout wrapper: sidebar + content)
+- `PublicCourseSidebar` (the numbered, sectioned nav — reusable for any item count)
+- `PublicCourseSidebarRow` (number badge + title + lock state)
+- `PublicLessonView` (video + section label + title + body + callout)
+- `PublicExerciseView` (exercise questions rendered for client-side grading)
+- `PublicCourseCallout` (inline + locked variants)
+- `CourseCalloutSettings` (creator settings panel, only visible when course is PUBLIC)
+- `LessonSlugField` / `ExerciseSlugField` (editable slug inputs in item settings, only visible when course is PUBLIC)
+
+Existing components (`QuestionRenderer`, `QuestionList`, etc.) are reused for exercise rendering, configured with the client-grading mode.
+
+## Storybook-First Build
+
+The public course UI is built as a set of Storybook components and consumed by the `(org-site)` routes. Stories are the primary development + review surface — reviewers test desktop and mobile layouts in Storybook before the routes are wired up.
+
+Required stories (at minimum):
+- `PublicCourseShell` — desktop and mobile viewports, with and without callout.
+- `PublicCourseSidebar` — default state, with a locked item, with many sections.
+- `PublicCourseSidebarRow` — default, hover, active, locked variants as individual stories.
+- `PublicCourseBottomNav` — first item (prev disabled), middle item, last item (next disabled).
+- `PublicCourseMobileSheet` — closed and open states (open state is the default story for review).
+- `PublicLessonView` — with video, without video, long body, short body.
+- `PublicExerciseView` — unanswered, mid-answer, after-grade (client-side).
+- `PublicCourseCallout` — inline and full (locked) variants, and "no callout configured" fallback.
+- `PublicCoursePage` — composed story showing the full page; run with Storybook's viewport addon to verify desktop and mobile side-by-side.
+
+All stories must resolve colors through the app's theme tokens (`--primary`, etc.), not hard-coded values.
+
+## Open Items (non-blocking)
+
+- Precise placement of the lock icon in a sidebar row (inside the number badge, replacing it, or beside it) — design review later.
+- Center button content in the mobile bottom bar — "3 / 12" vs "Section • item title" vs both — finalized during Storybook review.
+
+## Success Criteria
+
+1. A creator can set a course's type to `PUBLIC` and the course becomes reachable at `(org-site)/course/[slug]` with no sign-in required.
+2. The question-type picker hides non-auto-gradable types when the course type is `PUBLIC`.
+3. Lesson and exercise slugs are auto-generated and editable (for public courses).
+4. Locked items on a public course render the creator's callout in place of content; unlocked items render normally.
+5. Exercises on public courses are graded entirely in the browser with no server submission.
+6. The lesson page layout matches the reference designs: non-collapsible sidebar, per-section numbering, content column order (video → section label → title → body → callout).
+7. All accent colors resolve to `--primary`, not a hard-coded orange.
@@ -0,0 +1,270 @@
+# Public Courses Implementation Plan
+
+## Scope Lock
+
+1. **Course type**: add `PUBLIC` to `COURSE_TYPE` enum, change default to `SELF_PACED`.
+2. **Everyone is a guest**: no auth-based branching on public courses.
+3. **Content access**: entire tree + per-item content readable without auth when `course.type === 'PUBLIC'` and `course.isPublished === true`.
+4. **Gating**: reuse existing `lesson.isUnlocked` / `exercise.isUnlocked`. Locked items show the creator callout in place of content.
+5. **Grading**: exercises on public courses are graded entirely client-side. Answer keys ship to the client. No server submissions.
+6. **Question types**: only `autoGradable` question types allowed in public courses. Enforced in UI picker, API writes, and type-conversion checks.
+7. **URLs**: `(org-site)/course/[courseSlug]` (tree) and `(org-site)/course/[courseSlug]/lesson/[itemSlug]` (content). Single `/lesson/` segment for both lessons and exercises.
+8. **Slugs**: new `slug` columns on `lesson` and `exercise`. Auto-generated from title, editable when course is `PUBLIC`. Unique per course across lesson + exercise.
+9. **Callout**: new `callout` JSONB on `course` with `{ title, description, buttonLabel, buttonUrl }`. Optional.
+10. **Out of scope**: analytics, donations, live viewer counts, feature flag, localStorage progress, directory tab, discussion, progress tracking of any kind.
+
+## Delivery Phases
+
+### Phase A — Data model + validation (Days 1–2)
+Schema changes, migrations, slug backfill, validation schemas.
+
+### Phase B — API: public read endpoints + slug + callout (Days 3–5)
+Public-facing GET endpoints for the tree and item content; PATCH endpoints accept slug and callout; guard writes against non-auto-gradable question types.
+
+### Phase C — Creator UI (Days 6–8)
+Course type picker adds `PUBLIC`; question-type picker filters by `autoGradable` for public courses; slug field in lesson / exercise settings; callout settings panel.
+
+### Phase D — Public course UI in Storybook (Days 9–12)
+**Storybook first.** Build every component with its stories in `packages/ui` + `packages/storybook` so desktop and mobile layouts can be reviewed in isolation before wiring up the routes. Includes: `PublicCourseShell`, `PublicCourseSidebar`, `PublicCourseSidebarRow`, `PublicCourseBottomNav`, `PublicCourseMobileSheet`, `PublicLessonView`, `PublicExerciseView`, `PublicCourseCallout`, plus a composed `PublicCoursePage` story.
+
+### Phase E — Wire routes + polish (Days 13–14)
+Mount the storybook-ready components at `(org-site)/course/[slug]` and `(org-site)/course/[slug]/lesson/[itemSlug]`. SEO meta tags, canonical URLs, locked-state rendering, a11y pass, manual QA against the reference designs.
+
+---
+
+## Ticket Breakdown
+
+| ID | Area | Task | Key Files | Dependencies | Done When |
+|----|------|------|-----------|--------------|-----------|
+| PC-A1 | DB | Add `PUBLIC` to `COURSE_TYPE` enum; change default to `SELF_PACED` | `packages/db/src/schema.ts`, new migration | None | Migration applied; enum accepts `PUBLIC`; default is `SELF_PACED` |
+| PC-A2 | DB | Add `callout JSONB NULL` column on `course` | `packages/db/src/schema.ts`, migration | PC-A1 | Column exists; type matches `CourseCallout` shape |
+| PC-A3 | DB | Add `slug VARCHAR NULL` to `lesson` and `exercise` | `packages/db/src/schema.ts`, migration | None | Columns exist on both tables |
+| PC-A4 | DB | Backfill slugs for existing `lesson` and `exercise` rows (kebab-case from title, collision-resolved per course) | Migration SQL or one-shot script | PC-A3 | All rows have non-null slug; uniqueness holds per course |
+| PC-A5 | DB | Follow-up migration making `lesson.slug` and `exercise.slug` `NOT NULL` | Migration | PC-A4 | Columns are `NOT NULL` |
+| PC-A6 | DB queries | Update lesson / exercise queries to return `slug` | `packages/db/src/queries/course/**/*.ts` | PC-A3 | Queries project the new column |
+| PC-A7 | Utils | Slug validator (Zod: kebab-case, 1–80 chars) | `packages/utils/src/validation/shared/slug.ts` | None | Schema exported and unit-tested |
+| PC-A8 | Utils | Callout validator (Zod for `{ title, description, buttonLabel, buttonUrl }`) | `packages/utils/src/validation/course/callout.ts` | None | Schema exported; URL validated |
+| PC-A9 | Utils | Extend course validation schemas to accept `type: 'PUBLIC'`, `callout`, and `slug` fields on lesson / exercise | `packages/utils/src/validation/course/**`, `lesson/**`, `exercise/**` | PC-A7, PC-A8 | Schemas accept new fields |
+| PC-A10 | Question types | Expose an `autoGradable` filter helper for pickers (if not already exported) | `packages/question-types/src/question-type-capabilities.ts` | None | Helper available via `isAutoGradableQuestionType` / registry filter |
+| PC-B1 | API service | `slugFromTitle(title, existingSlugsInCourse)` utility (generate + collision-resolve) | `apps/api/src/services/course/slug.ts` | PC-A7 | Pure function; unit tests cover collision cases |
+| PC-B2 | API service | On lesson / exercise create, auto-generate `slug` if not provided | `apps/api/src/services/course/lesson.ts`, `apps/api/src/services/exercise/exercise.ts` | PC-B1 | New items get slugs automatically |
+| PC-B3 | API service | On lesson / exercise update, accept slug edit; enforce per-course uniqueness across lessons + exercises | Same services | PC-B1 | Conflicting slugs are rejected with a clear error code |
+| PC-B4 | API service | Block non-auto-gradable question types on public courses (create + update) | `apps/api/src/services/exercise/exercise.ts` | PC-A10 | Attempts rejected with `QUESTION_TYPE_NOT_ALLOWED_IN_PUBLIC_COURSE` |
+| PC-B5 | API service | `convertCourseType(courseId, newType)` — when converting **to** `PUBLIC`, reject if any attached question is non-auto-gradable; return list of offenders | `apps/api/src/services/course/course.ts` | PC-A10 | Conversion blocked with actionable error; passes when all questions are auto-gradable |
+| PC-B6 | API service | Accept `callout` on course update | `apps/api/src/services/course/course.ts` | PC-A8 | Callout round-trips through create/update/read |
+| PC-B7 | API route | `GET /org-site/course/:courseSlug` (no auth) returns course + section tree + item metadata incl. slugs | `apps/api/src/routes/org-site/course.ts` (new file) | PC-A6 | Anonymous requests succeed when course is public + published; 404 otherwise |
+| PC-B8 | API route | `GET /org-site/course/:courseSlug/item/:itemSlug` (no auth) returns one of two shapes with discriminator `kind: 'lesson' \| 'exercise'` | Same router | PC-B7 | Returns lesson body or exercise payload (with answer keys) |
+| PC-B9 | API route | Register the new router in `app.ts`; ensure `authMiddleware` is NOT applied to this router | `apps/api/src/app.ts` | PC-B7, PC-B8 | Router mounted; smoke test as anonymous user succeeds |
+| PC-C1 | Dashboard | Add `PUBLIC` option to course type picker at course creation | `apps/dashboard/src/lib/features/course/components/course-create/*` (existing) | PC-A9 | Creator can pick `Public` and create a course with `type: 'PUBLIC'` |
+| PC-C2 | Dashboard | Filter question-type picker to `autoGradable` only when `course.type === 'PUBLIC'` | `apps/dashboard/src/lib/features/ui/question/constants.ts`, `packages/ui/src/custom/question-type-picker/*` | PC-A10 | Non-auto-gradable types are hidden from the picker in public courses |
+| PC-C3 | Dashboard | Add slug editor to lesson and exercise settings (visible only when course is `PUBLIC`) | Lesson / exercise settings components under `features/course/components/...` | PC-A7 | Creator can edit slug; server validation errors surface inline |
+| PC-C4 | Dashboard | Add **Callout Settings** panel on the course settings page (visible only when `PUBLIC`) | `apps/dashboard/src/lib/features/course/components/settings/callout-settings.svelte` (new) | PC-B6 | Creator can set / clear title, description, button label, button URL |
+| PC-C5 | Dashboard | Warn in UI when switching a course **to** `PUBLIC` with non-auto-gradable questions (surface server error nicely) | Course settings type picker | PC-B5 | Clear error modal listing offending items |
+| PC-D1 | UI | `PublicCourseShell` — responsive two-column layout. Desktop: sidebar + content. Mobile: hides sidebar, reserves bottom padding for the bottom bar. Accepts `sidebar`, `bottomNav`, `main` slots. | `packages/ui/src/custom/public-course/shell.svelte` | None | Component renders correctly at both breakpoints; bottom padding reserved on mobile |
+| PC-D2 | UI | `PublicCourseSidebarRow` — number badge + title + lock indicator. Variants: default, hover, active (uses `--primary`), locked. | `packages/ui/src/custom/public-course/sidebar-row.svelte` | None | Matches `design/sidebar-active-state.png`; no hard-coded orange |
+| PC-D3 | UI | `PublicCourseSidebar` — sections with muted headings and their rows. Per-section numbering resets across lessons + exercises interleaved by `order`. | `packages/ui/src/custom/public-course/sidebar.svelte` | PC-D2 | Sections render in order; numbering resets per section |
+| PC-D4 | UI | `PublicCourseBottomNav` — mobile-only fixed bottom bar with prev / center / next. Emits `onPrev`, `onNext`, `onCenterTap`. Disables prev / next at boundaries. | `packages/ui/src/custom/public-course/bottom-nav.svelte` | None | Three regions render; disabled states work; `--primary` used for accent |
+| PC-D5 | UI | `PublicCourseMobileSheet` — vaul-based drawer that slides up with the full sidebar tree inside. Drag-to-dismiss. Auto-closes on item tap. | `packages/ui/src/custom/public-course/mobile-sheet.svelte` (uses `@cio/ui/base/drawer`) | PC-D3 | Opens on center-tap; swipe-down dismisses; tapping a row navigates + closes |
+| PC-D6 | UI | `PublicLessonView` — video → section label → title → body → inline callout. Video slot omitted entirely when no video. | `packages/ui/src/custom/public-course/lesson-view.svelte` | PC-D8 | Matches `design/lesson-page-full.png` |
+| PC-D7 | UI | `PublicExerciseView` — renders exercise questions in client-grading mode. Uses existing question-type render contract. No server submit. | `packages/ui/src/custom/public-course/exercise-view.svelte` | None | Exercises grade locally; "you got X / Y" displayed; refresh resets state |
+| PC-D8 | UI | `PublicCourseCallout` — inline variant (below body) and full variant (replaces body for locked items). | `packages/ui/src/custom/public-course/callout.svelte` | None | Both variants render; button opens URL in new tab |
+| PC-D9 | Storybook | `PublicCourseSidebarRow` stories: default, hover, active, locked. | `packages/storybook/src/molecules/public-course/sidebar-row.stories.svelte` | PC-D2 | All four variants selectable |
+| PC-D10 | Storybook | `PublicCourseSidebar` stories: default, with locked item, many sections. | `...sidebar.stories.svelte` | PC-D3 | Three scenarios render correctly |
+| PC-D11 | Storybook | `PublicCourseBottomNav` stories: first item (prev disabled), middle item, last item (next disabled). | `...bottom-nav.stories.svelte` | PC-D4 | Three position states selectable |
+| PC-D12 | Storybook | `PublicCourseMobileSheet` stories: closed, open (default), open-at-section. | `...mobile-sheet.stories.svelte` | PC-D5 | Stories demonstrate drag-to-dismiss and row-tap close |
+| PC-D13 | Storybook | `PublicLessonView` stories: with video, without video, long body, short body. | `...lesson-view.stories.svelte` | PC-D6 | Four stories render |
+| PC-D14 | Storybook | `PublicExerciseView` stories: unanswered, mid-answer, after-grade. | `...exercise-view.stories.svelte` | PC-D7 | Three stories render; after-grade shows correct/incorrect marks |
+| PC-D15 | Storybook | `PublicCourseCallout` stories: inline, full (locked), no-callout fallback. | `...callout.stories.svelte` | PC-D8 | Three variants render |
+| PC-D16 | Storybook | **Composed** `PublicCoursePage` story — mounts `Shell` + `Sidebar` + `LessonView` + `BottomNav`. Use Storybook's viewport addon to switch desktop / tablet / mobile. This is the primary review surface for design sign-off. | `...public-course-page.stories.svelte` | PC-D1..PC-D8 | Desktop shows two columns (no bottom bar); mobile hides sidebar and shows bottom bar; center-tap opens sheet |
+| PC-D17 | Dashboard types | Frontend types for public tree + item responses (inferred from API). | `apps/dashboard/src/lib/features/public-course/utils/types.ts` (new feature folder) | PC-B7, PC-B8 | Typed responses usable in routes |
+| PC-D18 | Dashboard route | `(org-site)/course/[slug]/+layout.server.ts` — SSR fetch of the tree, exposes to child routes. | New file | PC-D17 | Tree available via layout data |
+| PC-D19 | Dashboard route | `(org-site)/course/[slug]/+page.svelte` — overview page linking into items by slug. | New file | PC-D18 | Renders overview; links use `itemSlug` |
+| PC-D20 | Dashboard route | `(org-site)/course/[slug]/lesson/[itemSlug]/+page.server.ts` — SSR fetch for item content. | New file | PC-B8 | Server-rendered content on first paint |
+| PC-D21 | Dashboard route | `(org-site)/course/[slug]/lesson/[itemSlug]/+page.svelte` — composes `Shell` + `Sidebar` + `LessonView` / `ExerciseView` + `BottomNav` + `MobileSheet`. | New file | PC-D16, PC-D20 | Page matches the composed Storybook story behavior |
+| PC-D22 | Dashboard | Locked-item rendering: when `isUnlocked === false`, swap body for the full-variant callout. | Inside `+page.svelte` or container component | PC-D8 | Locked items render the callout; sidebar shows lock icon |
+| PC-D23 | Dashboard | Wire prev / next navigation (both desktop keyboard shortcuts and mobile bottom bar) to `goto()` the next / previous `itemSlug`. | New util: `features/public-course/utils/navigation.ts` | PC-D4 | Arrow keys and bottom bar both navigate; disabled at boundaries |
+| PC-E1 | SEO | Set `<title>`, `<meta description>`, canonical, and OG tags on public lesson pages. | `+page.svelte` head blocks | PC-D21 | View-source shows correct tags |
+| PC-E2 | i18n | All new user-facing strings in `apps/dashboard/src/lib/utils/translations/en.json` (callout settings, locked-state fallback text, prev / next labels for a11y, etc.). | translations file | PC-C4, PC-D22 | No hardcoded English in new components |
+| PC-E3 | a11y | Keyboard + screen-reader review: sidebar rows are links, bottom-nav buttons have labels, sheet traps focus while open. | All new components | PC-D16, PC-D21 | `axe` passes on the composed story and on a live page |
+| PC-E4 | Tests | Service + route tests for public GET endpoints, slug uniqueness, non-auto-gradable rejection, type-conversion guard. | `apps/api/src/**/__tests__/public-course*.test.ts` | PC-B* | Tests pass |
+
+---
+
+## Schema Snippets
+
+### Migration: enum + default + columns
+
+```sql
+-- Add PUBLIC to the existing COURSE_TYPE enum
+ALTER TYPE "COURSE_TYPE" ADD VALUE IF NOT EXISTS 'PUBLIC';
+
+-- Change default
+ALTER TABLE "course" ALTER COLUMN "type" SET DEFAULT 'SELF_PACED';
+
+-- Callout
+ALTER TABLE "course" ADD COLUMN "callout" JSONB;
+
+-- Slugs (nullable first; NOT NULL after backfill)
+ALTER TABLE "lesson"   ADD COLUMN "slug" VARCHAR;
+ALTER TABLE "exercise" ADD COLUMN "slug" VARCHAR;
+```
+
+Backfill (pseudo):
+
+```ts
+// For each course, iterate lessons + exercises ordered by order,
+// generate kebab-case slugs from titles, resolve collisions per course
+// by appending -2, -3, ... across the union of both tables.
+```
+
+Follow-up migration:
+
+```sql
+ALTER TABLE "lesson"   ALTER COLUMN "slug" SET NOT NULL;
+ALTER TABLE "exercise" ALTER COLUMN "slug" SET NOT NULL;
+```
+
+(No per-course unique constraint in SQL; enforced in application code.)
+
+---
+
+## API Response Shapes
+
+### Tree response
+
+```ts
+GET /org-site/course/:courseSlug
+// 200
+{
+  success: true,
+  data: {
+    course: {
+      id: string;
+      slug: string;
+      title: string;
+      description: string | null;
+      bannerImage: string | null;
+      callout: {
+        title: string;
+        description: string;
+        buttonLabel: string;
+        buttonUrl: string;
+      } | null;
+    };
+    sections: Array<{
+      id: string;
+      title: string;
+      order: number;
+      items: Array<
+        | { kind: 'lesson';   id: string; slug: string; title: string; order: number; isUnlocked: boolean; hasVideo: boolean }
+        | { kind: 'exercise'; id: string; slug: string; title: string; order: number; isUnlocked: boolean }
+      >;
+    }>;
+  }
+}
+// 404 if course is not public or not published
+```
+
+### Item response (single type, discriminator)
+
+```ts
+GET /org-site/course/:courseSlug/item/:itemSlug
+// 200
+{
+  success: true,
+  data:
+    | {
+        kind: 'lesson';
+        id: string;
+        slug: string;
+        title: string;
+        sectionTitle: string;
+        isUnlocked: boolean;
+        video: { type: 'youtube' | 'upload' | 'generic' | 'google_drive'; link: string } | null;
+        body: string; // rich text / HTML
+      }
+    | {
+        kind: 'exercise';
+        id: string;
+        slug: string;
+        title: string;
+        sectionTitle: string;
+        isUnlocked: boolean;
+        questions: ExercisePayloadWithAnswerKeys; // uses question-types render contract
+      };
+}
+// 404 if course not public/published or item not found
+```
+
+---
+
+## Acceptance Criteria
+
+### Phase A
+- [ ] `COURSE_TYPE` enum includes `PUBLIC`.
+- [ ] `course.type` default is `SELF_PACED` for new rows.
+- [ ] `course.callout` column exists and accepts null or full object.
+- [ ] `lesson.slug` and `exercise.slug` exist, backfilled, and `NOT NULL`.
+- [ ] Slug validator rejects invalid shapes (spaces, uppercase, >80 chars).
+
+### Phase B
+- [ ] `GET /org-site/course/:courseSlug` returns the tree anonymously for public + published courses.
+- [ ] `GET /org-site/course/:courseSlug/item/:itemSlug` returns lesson or exercise content with `kind` discriminator.
+- [ ] Anonymous request on a non-public or unpublished course returns 404.
+- [ ] Creating / updating a question with a non-auto-gradable type on a PUBLIC course is rejected with a clear error.
+- [ ] Converting a course to `PUBLIC` fails when non-auto-gradable questions exist; error lists the offending items.
+- [ ] Lesson / exercise PATCH accepts `slug` edits and enforces per-course uniqueness across both tables.
+
+### Phase C
+- [ ] Creator can select `PUBLIC` as a course type.
+- [ ] Question-type picker hides non-auto-gradable types when the course is `PUBLIC`.
+- [ ] Slug field is visible and editable on lesson / exercise settings (only when course is `PUBLIC`).
+- [ ] Callout settings panel is visible on the course settings page (only when `PUBLIC`) and round-trips the callout object.
+
+### Phase D
+- [ ] Every new component in `packages/ui/src/custom/public-course/*` has at least one Storybook story (listed in PC-D9..PC-D16).
+- [ ] The composed `PublicCoursePage` story renders correctly at desktop, tablet, and mobile viewports (via Storybook's viewport addon).
+- [ ] Desktop: two columns, no bottom bar, sidebar visible.
+- [ ] Mobile: sidebar hidden, fixed bottom bar visible with prev / center / next regions; center tap opens a drag-dismissible bottom sheet containing the full sidebar tree; tapping a row navigates and closes the sheet.
+- [ ] Sidebar numbers reset per section; active state uses `--primary`; hover state matches the reference designs.
+- [ ] Locked items render the creator callout in place of content; sidebar shows a lock indicator.
+- [ ] Exercises grade entirely client-side; no network request on answer submit.
+- [ ] No hard-coded orange anywhere; all accents resolve to `--primary`.
+- [ ] `(org-site)/course/[slug]` renders the course overview.
+- [ ] `(org-site)/course/[slug]/lesson/[itemSlug]` matches the composed Storybook story on a live browser.
+- [ ] Anonymous visitors see the same experience regardless of auth state.
+
+### Phase E
+- [ ] View-source on a public lesson page shows the item title, description, canonical URL, and OG tags.
+- [ ] All user-facing strings are translation keys.
+- [ ] Keyboard navigation works on desktop (`←` / `→` move through items); bottom-nav buttons have a11y labels; the mobile sheet traps focus while open.
+- [ ] `axe` passes on both the composed Storybook story and a live public lesson page.
+- [ ] API tests pass.
+
+---
+
+## Verification Commands
+
+```bash
+pnpm --filter @cio/utils build
+pnpm --filter @cio/question-types build
+pnpm --filter @cio/db build
+pnpm --filter @cio/api build
+pnpm --filter @cio/ui build
+pnpm --filter @cio/dashboard build
+
+pnpm --filter @cio/api test public-course
+pnpm --filter @cio/dashboard check
+```
+
+---
+
+## Risks & Mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Slug collisions during backfill | Two-pass backfill script: generate all candidates, resolve collisions per course, then write. Wrap in a transaction and dry-run in staging first. |
+| Answer keys shipped to the client | Accepted trade-off (public courses are marketing surfaces). Documented in the PRD. |
+| Converting a course with many non-auto-gradable questions to `PUBLIC` is painful | Server error lists every offending question with its exercise + section so the creator can fix them in one pass. |
+| SEO duplicate content between `(app)/courses/[id]/lessons/[lessonId]` and the new public URL | Canonical URL on public pages points at the `(org-site)` URL. `(app)` URLs remain auth-gated and are not indexed. |
+| Hard-coded orange in screenshots leaking into the build | Explicit rule in the PRD: all accents use `--primary`. Reviewer should grep new components for raw orange hex values. |