I'll implement the ActivityStage sequential activity progression system. Let me start by creating a todo list to track the implementation.

Let me first read the relevant existing files to understand the patterns used.

Let me also read the group-activity server component and an existing API route to understand the patterns better.

Now I understand the patterns. Let me start implementing. I'll begin with documenting the donut pattern in CLAUDE.md.

Now let me create the database schema for activity stages.

Now let me add the export to the schema index.

Let me check if the dev server is running, then push the schema changes.

Let me read the auth middleware to understand how to use it properly.

Now let me create the student API routes for activity stages.

Now let me register these routes in the API index.ts.

Let me read the SWR fetcher and env patterns used in the web app.

Now let me create the context provider for activity stages.

Let me check how server-side API fetching works.

Now let me create the server components. First the container component.

Now let me create the ActivityStage server component.

Now let me add the GroupActivity integration. I'll create a hook that GroupActivityClient can use to notify when a group completes.

Now let me update GroupActivityClient to trigger stage completion when the group becomes complete.

Let me check the testing directory structure.

Let me run the type checker to make sure everything compiles.

There's a TypeScript error. Let me fix it.

Let me fix these TypeScript errors.

TypeScript checks pass. Let me also run the linter.

Let me fix the lint errors.

I see that activityGroups is unused but also I should add cleanup for the new activity stages tables. Let me update the e2e routes.

Let me read an existing E2E test to understand the pattern.

Let me run the E2E tests.

The test is failing because the session from the previous test persists. Let me update the tests to reset the session at the beginning.

The test is failing because the session persists from previous tests. Let me update the test to handle this more gracefully.

Let me look at the reset function more carefully and fix it.

All tests pass. Let me run the full E2E test suite to make sure nothing is broken.

Let me update the todo list and provide a summary of the implementation.

The ActivityStage implementation is complete. Here's a summary of what was created:

Files Created

Database Schema:

• packages/db/src/schema/activity-stages.ts - Three tables: activity_sessions, activity_stage_timings, activity_stage_completions

API Routes:

• apps/api/src/routes/activity-stages.ts - Student endpoints for getting session status and completing stages
• apps/api/src/routes/admin/activity-stages.ts - Instructor endpoints for starting, advancing, resetting sessions and viewing completion counts

React Components:

• apps/web/components/mdx/activity-stages.tsx - Server component container that fetches session data
• apps/web/components/mdx/activity-stage.tsx - Server component wrapper for individual stages
• apps/web/components/mdx/activity-stage-client.tsx - Client component for stage UI and completion
• apps/web/components/mdx/activity-stage-context.tsx - React context provider with SWR for state management
• apps/web/components/mdx/activity-stage-instructor.tsx - Instructor control panel with timers and completion tracking

Test Page:

• apps/web/app/testing/components/activity-stages/page.tsx - Test page at /testing/components/activity-stages

E2E Tests:

• testing/e2e/tests/activity-stages.spec.ts - 15 tests covering student and instructor flows

Files Modified

• CLAUDE.md - Added documentation for the "donut" pattern
• packages/db/src/schema/index.ts - Added export for activity stages schema
• apps/api/src/index.ts - Registered new routes
• apps/web/mdx-components.tsx - Registered ActivityStages and ActivityStage components
• apps/web/components/mdx/group-activity-client.tsx - Added integration to trigger stage completion when group forms
• apps/api/src/routes/e2e.ts - Added cleanup for activityStageCompletions
• testing/e2e/playwright.config.ts - Added activity-stages test project

Usage Example

<ActivityStages meetingSlug="2026-01-27-ethics">
  <ActivityStage label="Opening Discussion" time="5m">
    Discuss with your neighbor...
  </ActivityStage>
  
  <ActivityStage label="Group Formation" time="3m" autoAdvance>
    <GroupActivity id="ethics-groups" group="ethics-meeting-1">
      Partner content here...
    </GroupActivity>
  </ActivityStage>
  
  <ActivityStage label="Case Study" time="15m">
    Review and discuss...
  </ActivityStage>
</ActivityStages>

<thinking> Now let me check the new files for any debugging statements or unnecessary logging before committing. </thinking>

Let me check the new and modified files for any debugging statements or unnecessary logging.

<thinking> I found two console.error statements: 1. `apps/web/components/mdx/group-activity.tsx:68` - This is a pre-existing one (not in my changes) 2. `apps/web/components/mdx/activity-stages.tsx:118` - This is in my new file

The one in activity-stages.tsx is similar to the existing one in group-activity.tsx - both are server-side error logging for API fetch failures, which is appropriate for debugging server-side issues. Since the existing codebase has this pattern, it's consistent.

Let me confirm there are no other debugging statements in my new files and then proceed with the commit. </thinking>

The console.error in activity-stages.tsx:118 is for server-side error logging, matching the existing pattern in group-activity.tsx:68. This is appropriate for debugging server-side fetch failures.

Here's a summary of changes:

Modified Files (7):

• CLAUDE.md - Added documentation for the donut pattern
• apps/api/src/index.ts - Registered new API routes
• apps/api/src/routes/e2e.ts - Added cleanup for activity stage completions
• apps/web/components/mdx/group-activity-client.tsx - Added activity stage integration
• apps/web/mdx-components.tsx - Registered ActivityStages and ActivityStage components
• packages/db/src/schema/index.ts - Added export for activity stages schema
• testing/e2e/playwright.config.ts - Added activity-stages test project

Untracked Files (10 new files):

• packages/db/src/schema/activity-stages.ts - Database schema
• apps/api/src/routes/activity-stages.ts - Student API routes
• apps/api/src/routes/admin/activity-stages.ts - Admin API routes
• apps/web/components/mdx/activity-stage.tsx - Server component
• apps/web/components/mdx/activity-stages.tsx - Container server component
• apps/web/components/mdx/activity-stage-client.tsx - Client component
• apps/web/components/mdx/activity-stage-context.tsx - React context provider
• apps/web/components/mdx/activity-stage-instructor.tsx - Instructor controls
• apps/web/app/testing/components/activity-stages/page.tsx - Test page
• testing/e2e/tests/activity-stages.spec.ts - E2E tests

Committed successfully: b1b4761 - Add ActivityStages MDX component for sequential activity progression

17 files changed with 1958 insertions. The working tree is clean.

Let me first read the existing plan file and then understand the current implementation to propose a good design for roles.

This is a great idea! Let me think through how the markup might look. Here are a few approaches to consider:

---

Option A: Roles on GroupActivity, rotation on stages

<ActivityStages meetingSlug="2026-01-27-pair-programming">

<ActivityStage label="Find a Partner" autoAdvance>
  <GroupActivity id="pp-groups" group="pair-programming-1" roles={["driver", "observer"]}>
    You found a partner!
  </GroupActivity>
</ActivityStage>

<ActivityStage label="Exercise 1" time="10m">
  <RoleContent role="driver">
    **You are the driver.** Open the editor and implement the `factorial` function.
  </RoleContent>
  <RoleContent role="observer">
    **You are the observer.** Watch your partner code and offer suggestions.
  </RoleContent>
</ActivityStage>

<ActivityStage label="Exercise 2" time="10m" rotateRoles>
  <!-- rotateRoles swaps driver/observer from previous stage -->
  <RoleContent role="driver">
    **Your turn to drive!** Now implement the `fibonacci` function.
  </RoleContent>
  <RoleContent role="observer">
    **Now you observe.** Help your partner think through the approach.
  </RoleContent>
</ActivityStage>

</ActivityStages>

---

Option B: Explicit role assignment per stage

<ActivityStages meetingSlug="2026-01-27-pair-programming">

<ActivityStage label="Find a Partner" autoAdvance>
  <GroupActivity id="pp-groups" group="pair-programming-1" roles={["driver", "observer"]}>
    You found a partner!
  </GroupActivity>
</ActivityStage>

<ActivityStage label="Exercise 1" time="10m" roles={{ driver: 0, observer: 1 }}>
  <!-- Member 0 = driver, Member 1 = observer -->
  <RoleContent role="driver">...</RoleContent>
  <RoleContent role="observer">...</RoleContent>
</ActivityStage>

<ActivityStage label="Exercise 2" time="10m" roles={{ driver: 1, observer: 0 }}>
  <!-- Swapped: Member 1 = driver, Member 0 = observer -->
  <RoleContent role="driver">...</RoleContent>
  <RoleContent role="observer">...</RoleContent>
</ActivityStage>

</ActivityStages>

---

Key design questions:

1. Role assignment strategy - When a group forms, how are roles initially assigned?

   • First to join = first role (driver), second = second role (observer)?
   • Random assignment?
   • Student chooses?

2. Rotation behavior - How should rotateRoles work?

   • Simple swap for pairs (driver↔observer)?
   • Round-robin for larger groups?

3. Content visibility - What does the other role see?

   • Nothing (content hidden)?
   • Their own role-specific instructions?
   • Both, but their role highlighted?

Which approach feels more natural for your use case? And any preferences on the design questions above?

You're right! That's a much cleaner design. The GroupActivity provides the group context (members, roles), and the ActivityStages operate within that context:

<GroupActivity id="pp-groups" group="pair-programming-1" roles={["driver", "observer"]}>

  <!-- This content only shows after group forms -->
  <ActivityStages meetingSlug="2026-01-27-pair-programming">
    
    <ActivityStage label="Exercise 1" time="10m">
      <RoleContent role="driver">
        **You are the driver.** Open the editor and implement `factorial`.
      </RoleContent>
      <RoleContent role="observer">
        **You are the observer.** Watch and offer suggestions.
      </RoleContent>
    </ActivityStage>

    <ActivityStage label="Exercise 2" time="10m" rotateRoles>
      <RoleContent role="driver">
        **Your turn to drive!** Now implement `fibonacci`.
      </RoleContent>
      <RoleContent role="observer">
        **Now you observe.** Help your partner think through it.
      </RoleContent>
    </ActivityStage>

  </ActivityStages>

</GroupActivity>

This way:

• GroupActivity forms the group, assigns initial roles, provides context
• ActivityStages (children) only render after group is complete
• ActivityStage can read group context and optionally rotateRoles
• RoleContent checks the user's current role from context and conditionally renders

The context chain would be: GroupActivity → ActivityStages → ActivityStage → RoleContent

Does this structure match what you had in mind?

I agree, this design is better for several reasons:

1. Natural data flow - Group context (members, roles) flows down to stages and role content. No need to wire things up manually.

2. Automatic gating - GroupActivity already hides children until the group forms. No changes needed there.

3. Compositional - Each component does one thing:

   • GroupActivity - forms group, assigns roles, provides context
   • ActivityStages - manages stage progression (works with or without group)
   • RoleContent - conditionally renders based on role context

4. Clean mental model - "Within this group, do these stages, with these role-specific instructions"

5. Instructor view - Instructors could see all role content labeled, so they understand what each student sees

The only thing I'd add: RoleContent should probably still render its content (maybe dimmed or labeled) if there's no group context, so the MDX is previewable and instructors can see everything.

Want me to plan the implementation? The main pieces would be:

• Add roles prop to GroupActivity and store role assignments in the database
• Create a group context that exposes current user's role
• Add rotateRoles prop to ActivityStage that cycles role assignments
• Create RoleContent component that conditionally renders based on role

Great question. Let me lay out the composition rules clearly:

---

Composition Rules

ActivityStages (standalone)

<ActivityStages meetingSlug="...">
  <ActivityStage label="Step 1">...</ActivityStage>
  <ActivityStage label="Step 2">...</ActivityStage>
</ActivityStages>

• Class-wide stage progression
• Instructor controls advancement
• No roles, no rotateRoles, no RoleContent

---

GroupActivity (standalone)

<GroupActivity id="..." group="...">
  Content shown after group forms
</GroupActivity>

• Group formation only
• No roles (or roles could be assigned but never used)
• No stages, no rotation

---

GroupActivity wrapping ActivityStages

<GroupActivity id="..." group="..." roles={["driver", "observer"]}>
  <ActivityStages meetingSlug="...">
    <ActivityStage label="Exercise 1">
      <RoleContent role="driver">...</RoleContent>
      <RoleContent role="observer">...</RoleContent>
    </ActivityStage>
    <ActivityStage label="Exercise 2" rotateRoles>
      <RoleContent role="driver">...</RoleContent>
    </ActivityStage>
  </ActivityStages>
</GroupActivity>

• Full feature set: group + roles + stages + rotation
• rotateRoles cycles role assignments for that stage
• RoleContent renders based on user's current role

---

ActivityStages wrapping GroupActivity (existing pattern)

<ActivityStages meetingSlug="...">
  <ActivityStage label="Find Partner" autoAdvance>
    <GroupActivity id="..." group="...">
      Partner found!
    </GroupActivity>
  </ActivityStage>
  <ActivityStage label="Discussion">
    <!-- No group context here - GroupActivity ended -->
  </ActivityStage>
</ActivityStages>

• Stages control class progression
• Group forms within a stage but context doesn't persist to other stages
• No roles - use the other pattern for roles

---

Invalid/Warning cases

• rotateRoles on ActivityStage without GroupActivity ancestor → ignored (or console warning)
• RoleContent without GroupActivity ancestor → render nothing? render all? warning?

---

Does this capture the composition rules correctly? And for RoleContent outside a group context - should it render nothing, render its content anyway (for testing/previewing), or show a warning message?

Yes, exactly. The strict containment rules are:

Component	Must be inside
ActivityStage	ActivityStages
RoleContent	GroupActivity

And the flexible parts:

Component	Can be...
ActivityStages	Standalone, OR inside GroupActivity
GroupActivity	Standalone, OR inside ActivityStage, OR wrapping ActivityStages

So there are really two valid patterns for roles:

Pattern 1: Group wraps Stages (roles + rotation)

<GroupActivity roles={["driver", "observer"]}>
  <ActivityStages>
    <ActivityStage rotateRoles>
      <RoleContent role="driver">...</RoleContent>
    </ActivityStage>
  </ActivityStages>
</GroupActivity>

Pattern 2: Stage contains Group (no roles outside group)

<ActivityStages>
  <ActivityStage>
    <GroupActivity>
      <!-- RoleContent only valid here, inside GroupActivity -->
    </GroupActivity>
  </ActivityStage>
  <ActivityStage>
    <!-- No RoleContent here - outside GroupActivity -->
  </ActivityStage>
</ActivityStages>

Does that capture the rules correctly?

Right. ActivityStage consumes from two contexts:

1. ActivityStages context (required) - stage index, visibility, completion state
2. GroupActivity context (optional) - for rotateRoles to actually rotate roles

So when you have:

<GroupActivity roles={["driver", "observer"]}>
  <ActivityStages>
    <ActivityStage rotateRoles>
      ...
    </ActivityStage>
  </ActivityStages>
</GroupActivity>

The ActivityStage reaches "up" to both:

• Its parent ActivityStages for stage mechanics
• Its ancestor GroupActivity for role rotation

And rotateRoles without a GroupActivity ancestor would just be ignored (no roles to rotate).

This cross-context communication is fine - React contexts are designed for this. The ActivityStage client component would do something like:

const stagesContext = useActivityStages(); // required
const groupContext = useOptionalGroupActivity(); // optional

if (rotateRoles && groupContext) {
  // trigger role rotation
}

Is that the interaction model you had in mind?

Good catch. The role configuration needs to express cardinality. A few syntax options:

Option A: Object with counts

<GroupActivity 
  size={3} 
  roles={{ driver: 1, observer: "*" }}
>

• 1 = exactly one
• "*" = fill remaining slots

Option B: More explicit

<GroupActivity 
  size={3} 
  roles={{ driver: { count: 1 }, observer: { count: "rest" } }}
>

---

Rotation behavior for 3-person group with 1 driver:

Stage	Alice	Bob	Carol
1	driver	observer	observer
2 (rotate)	observer	driver	observer
3 (rotate)	observer	observer	driver

The single-count role (driver) rotates through members; the "*" role (observer) fills the rest.

---

Edge cases to handle:

• What if driver: 2, observer: "*" and group has only 2 people? Both are drivers, no observers?
• What if total role counts exceed group size? Error?

---

I lean toward Option A for simplicity:

<GroupActivity size={3} roles={{ driver: 1, observer: "*" }}>

Does that syntax work for you? And how strict should validation be for mismatched sizes?

Let me write up the implementation plan.

I've written up the implementation plan. The key points:

• Role syntax: roles={{ driver: 1, observer: "*" }}
• Composition: GroupActivity wraps ActivityStages for full role support
• Rotation: rotateRoles on ActivityStage cycles the limited-count role through members
• RoleContent: Simple conditional rendering based on user's current role
• Database: Store role config on groups, track rotation offset per stage