PRD: Launch-readiness QA and interactive workflow polish

[rushtanu14]

Problem Statement

Relay is close to launch, but Rushil needs confidence that the core classroom continuity loop works end to end across teacher, student, hosted web, desktop, billing, sync, parser, legal, and operations surfaces. The product also needs to feel more alive and responsive: teachers should get lightweight celebration feedback when they create a new session and when they publish student follow-ups, and buttons/cards should feel tactile without making the UI unstable.

The immediate risk is not just missing polish. It is that launch confidence can be undermined by false-positive success states: hosted demo data accidentally persisting, installer download buttons implying success when packaging is pending, ad-hoc macOS packages passing superficial checks but failing first-run state writes, or automated tests claiming coverage while clean-host/manual/operator checks remain undone.

A second risk surfaced during implementation: concurrent workspace churn can erase source/test edits or stage unrelated generated/user changes. Relay needs a repeatable implementation and QA path that protects user work, detects host-specific gaps, and avoids committing unrelated changes.

Solution

Build a focused launch-readiness and interaction-polish slice for Relay:

• Add reduced-motion-aware celebration feedback when a teacher successfully generates a draft from Class Artifacts and when a teacher publishes student follow-ups.
• Add subtle cursor-following gleam and hover scale to primary interactive controls, while keeping click targets stable for real users and Playwright.
• Extend automated browser coverage so local teacher/student flows verify the celebration and interaction behavior from the outside, not implementation internals.
• Extend hosted Vercel smoke coverage so the sample-only demo creates and publishes a temporary session, reloads, and verifies that the sample work did not persist.
• Extend the manual QA script to include the new interaction checks, live Vercel demo ephemerality checks, and Computer Use/operator-mode instructions for native desktop, installers, OS prompts, file pickers, microphone/screen capture, and clean-machine behavior.
• Keep the release rule explicit: do not publish desktop installers until signed/notarized macOS first-run passes and Windows/Linux first-run is verified on matching clean machines.
• Add a safe handoff expectation for agents: detect concurrent workspace/index changes, avoid committing unrelated files, and report host-specific gaps clearly.

User Stories

1. As a teacher, I want a small celebration after I generate a new Relay session, so that I know Relay accepted my Class Artifacts and is preparing a reviewable draft.
2. As a teacher, I want a small celebration after I publish student follow-ups, so that publishing feels complete and intentional.
3. As a teacher, I want celebrations to be brief and non-blocking, so that I can keep reviewing, publishing, or exporting without waiting on animation.
4. As a teacher with reduced-motion preferences, I want celebration and hover motion to be minimized, so that Relay remains comfortable to use.
5. As a teacher, I want buttons and key controls to react subtly to my cursor, so that the website feels polished and interactive.
6. As a teacher, I want hover polish to preserve stable click targets, so that buttons do not dodge my pointer or make the app harder to use.
7. As a student, I want the student dashboard to remain calm and readable even if teacher-facing workflows get more animated, so that my follow-up work stays clear.
8. As a student, I want role boundaries to stay strict after UI polish changes, so that I only see sessions and follow-ups meant for me.
9. As a hosted demo visitor, I want to try the teacher side without creating an account, so that I can understand Relay quickly.
10. As a hosted demo visitor, I want sample demo changes to disappear after reload/sign-out, so that I know I am not creating durable student records in the hosted demo.
11. As a hosted demo visitor, I want no editable email/password signup fields in demo-only mode, so that the hosted demo does not imply durable public account creation.
12. As a hosted demo visitor, I want missing installer URLs to say packaging is pending, so that I am not misled by a broken download button.
13. As a hosted mobile visitor, I want the PWA install/add-to-phone path to stay visible and readable, so that I can try Relay on a phone or tablet.
14. As a teacher running a Solo Simulation, I want to import Redacted Real-Class Data from a realistic CS4ALL/Scratch Club Session, so that Relay is validated against real classroom shape without exposing private student data.
15. As a teacher running a Solo Simulation, I want parser regressions for noisy Zoom/CSV variations to remain covered, so that Class Artifacts from real classrooms keep importing reliably.
16. As a teacher, I want duplicate emails, duplicate names, empty roster rows, aliases, malformed rows, and transcript-only mode to be tested, so that messy inputs do not silently produce bad follow-ups.
17. As a teacher, I want large-session imports with 100+ students to remain responsive, so that Relay can handle realistic class sections.
18. As a teacher, I want repeated imports to avoid state bleed, so that one class session never contaminates another session.
19. As a teacher, I want the publish preview to remain inspectable for every student, so that I can approve exactly what each learner receives.
20. As a teacher, I want report JSON/CSV/print exports to keep working after polish changes, so that Relay remains useful beyond the in-app view.
21. As a teacher, I want saved rosters and class groups to stay isolated by account, so that another teacher never sees my classes or students.
22. As a student, I want completion check-ins to update only my follow-up, so that another student’s state is not changed accidentally.
23. As a teacher, I want submitted student check-ins to be reviewable, so that Relay supports the follow-through loop after publishing.
24. As a free user, I want clear Free limits and locked Pro surfaces, so that I understand what is available without surprise.
25. As a Pro user, I want upgraded entitlements to unlock paid capabilities consistently, so that billing status maps to product access.
26. As an unpaid or past-due user, I want locked states to be visible and understandable, so that Relay does not silently fail.
27. As a desktop user without Supabase credentials, I want Relay to keep working locally, so that cloud setup is optional.
28. As a hosted sync user, I want login, logout, token expiry, network loss, offline queueing, and conflict resolution to behave predictably, so that multi-device data does not get corrupted.
29. As a desktop user, I want encrypted local state to survive relaunch, corruption recovery, and backup/restore, so that private classroom data is durable.
30. As a desktop user, I want first-run packaged launch to write state outside the app bundle, so that macOS/Windows/Linux packages behave like real apps.
31. As a release operator, I want macOS signed/notarized first-run to pass before publishing installers, so that teachers do not hit Keychain/Gatekeeper/state-write regressions.
32. As a release operator, I want Windows and Linux first-run to be verified on clean matching machines, so that foreign-OS build artifacts are not mistaken for launch proof.
33. As a release operator, I want rollback drills to remain runnable, so that a bad installer or bad hosted release can be quarantined quickly.
34. As a release operator, I want billing/auth/sync/parser incident drills to remain runnable, so that launch outages have rehearsed recovery paths.
35. As a release operator, I want legal/privacy/support/EULA/retention/child-safety baseline checks to stay in the launch gate, so that public signup/download surfaces do not go live with missing policy boundaries.
36. As a tester, I want the manual QA script to name which operator mode to use, so that Browser, Chrome, Computer Use, Supabase, Stripe, Vercel, and GitHub checks are applied in the right places.
37. As a tester, I want manual QA output to separate correctness errors from feature issues, so that bugs are not blurred with product suggestions.
38. As a tester, I want suggested new features and cohesion improvements to be captured after a run, so that Relay keeps improving beyond pass/fail.
39. As a future Codex agent, I want the testing script to encode the newest feature expectations, so that future changes keep validating confetti, hover polish, hosted demo ephemerality, and platform gaps.
40. As a future Codex agent, I want concurrent workspace changes to be detected before commit/push, so that unrelated user/generated changes are not accidentally included.
41. As Rushil, I want the outcome recorded durably in Relay project memory and/or the issue tracker, so that launch readiness does not live only in one chat.
42. As Rushil, I want a concise pass/fail report with host-specific gaps, so that I know exactly what is done, what is blocked, and what cannot be claimed yet.

Implementation Decisions

• Build or preserve a deep interaction-effects module with a simple external interface: install once at app startup, observe workflow completion from user-visible state, and render transient celebration DOM for successful session generation and publish completion.
• The interaction-effects module should encapsulate cursor-following gleam, hover scale, celebration rendering, reduced-motion handling, duplicate-install guards, and workflow-trigger polling.
• The interaction-effects module should not rely on fragile component internals. It should trigger from stable user-visible outcomes: draft processing/review visibility for session creation, and report/follow-through tracker visibility for publish completion.
• Hover behavior should move the gleam, not the click target. Scale/translation should be subtle and deterministic enough for Playwright and real users.
• Celebration behavior should be non-blocking, aria-hidden, and short-lived. It should reuse existing Relay confetti styling where available instead of inventing a second visual language.
• The local browser workflow tests should assert external behavior: visible celebration layers after Generate draft and Publish to students, plus cursor-driven shine CSS state after a synthetic pointer move.
• Hosted web smoke should remain deploy-aware. It may optionally assert interaction effects strictly when the deployed build is expected to contain them, but it should always verify the hosted demo can create/publish a sample session and that the sample session does not persist after reload.
• The manual QA checklist should be the canonical operator script for “test everything” requests. It should include the automated gate commands, live Vercel smoke, manual write command, operator modes, interaction polish checks, and hosted demo ephemerality checks.
• Desktop installer publication remains gated behind real platform evidence. Local macOS arm64 first-run passing is useful but does not replace signed/notarized macOS validation or clean Windows/Linux validation.
• The release/ops runbook should continue to treat missing installer URLs as Packaging pending rather than success.
• Agent workflow should include a pre-commit safety check: inspect git status, staged files, and recent unexpected file churn before staging/committing/pushing. If unrelated staged files exist, stop and report instead of sweeping them into the PR.
• The domain language should use Relay terminology and the current validation path: Class Artifacts, Redacted Real-Class Data, Solo Simulation, and CS4ALL/Scratch Club Session where relevant. Do not revive ClassLoop as the public product name.
• No schema or API contract changes are required for interaction polish. Hosted sync, billing, and parser contracts are tested as regression gates rather than modified by this PRD.

Testing Decisions

• Good tests should assert user-visible behavior and durable state boundaries, not implementation details. For animation, assert that a celebration is visible after the workflow succeeds and that hover state is observable, not the exact animation frame or CSS keyframe.
• Test the interaction-effects module through Playwright browser flows because its contract is DOM/user interaction behavior.
• Test local teacher flow using the existing teacher login/import/review/publish/student/analytics Playwright coverage.
• Test multi-account role isolation using the existing heavy Chromium E2E that covers Math review, CS workshop, and Club meeting scenarios.
• Test hosted demo ephemerality through the hosted web smoke suite, across desktop and phone-sized projects.
• Test parser, scale, repeated imports, malformed inputs, transcript-only mode, and noisy Zoom/CSV variations through the existing import regression suite.
• Test hosted auth/sync resilience through the existing cloud sync tests that simulate signed-out, signed-in, expired, missing credentials, conflict resolution, network loss, and offline queues.
• Test Free/Pro entitlement boundaries through the existing entitlement gate suite and browser locked-feature checks.
• Test desktop data integrity through the existing desktop state smoke covering encrypted write/read, corruption recovery, write blocking, and backup/restore.
• Test packaged first-run with the existing packaged smoke script, but only claim host-specific launch proof for the OS/architecture actually exercised.
• Test release rollback and outage readiness through the existing rollback and incident drills.
• Test legal/security baseline through the existing security baseline, including secrets, local data tracking, encrypted storage, hosted boundaries, logging, and legal page requirements.
• Update the manual QA checklist and write-generated checklist so future agents can run or inspect the same operator plan.
• Prior art in the codebase includes the Playwright browser suite, hosted web smoke config, import-flow regression runner, cloud sync tests, entitlement tests, desktop state smoke, packaged first-run smoke, security baseline, rollback drill, incident drill, and manual QA checklist script.

Out of Scope

• Building new paid API-key features.
• Adding Google Classroom, Canvas, Schoology, OpenAI transcription, or external LMS posting.
• Shipping or publishing desktop installers before signed/notarized macOS and clean Windows/Linux validation.
• Replacing the existing parser architecture.
• Redesigning the whole landing page or collapsing public pages into one scroll-through page.
• Enabling durable account creation in the hosted public demo.
• Guaranteeing biometric speaker identification; live capture remains teacher-assisted and should not claim voiceprints.
• Running real teacher alpha recruitment as part of this PRD. The current validation language should prefer Solo Simulation with Redacted Real-Class Data unless Rushil explicitly reopens teacher alpha.
• Committing unrelated generated assets, staged changes, or user edits discovered during implementation.

Further Notes

• The previous retry revealed a live workspace/index churn problem. Agents implementing this PRD should treat unexpected source disappearance, staged-file changes, or unrelated generated assets as a blocker and report it rather than forcing a commit.
• The hosted URL currently used for smoke testing is https://relay-class.vercel.app/.
• The launch bar should remain conservative: a local passing build or package smoke is evidence, not permission to publish installers.
• The manual QA report should continue to include pass/fail by command, correctness errors, feature issues, suggested new features/functions, cohesion improvements, and remaining coverage gaps.
• If interaction effects land on the deployed site, set strict hosted interaction assertions for that deployment. Until then, hosted tests should verify the demo workflow and ephemerality while allowing animation checks to be optional for the current production build.

[rushtanu14]

Grill-with-docs decision update:

• Canonical release gate: Clean-Host Release Validation. Each desktop installer target must pass first-run validation on its actual OS/architecture before it is public-ready. macOS arm64 passing locally does not certify Windows, Linux, or other architectures.
• Website download UX requirement: show one Detected Installer first based on visitor OS. If detection is wrong or unclear, show a small “Not your system?” control that reveals the Installer Choice List for macOS, Windows, Linux, and hosted/PWA options.
• Sample Workspace boundary remains: Sample Publication proves the workflow only inside non-durable sample data; it is not real delivery or persistent student-facing publish.

[rushtanu14]

Grill-with-docs decision update:

• Download page should not be desktop-only overall.
• Web/PWA Entry Point belongs near the hero/top-level public CTA area, not buried in the desktop installer section.
• Desktop installer section should show one Detected Installer when OS detection is confident.
• “Not your system?” reveals desktop-only Installer Choice List: macOS, Windows, Linux.
• If OS detection is not confident, show non-desktop Install Fallback first instead of guessing macOS or any desktop target.

[rushtanu14]

Grill-with-docs decision update:

• OS auto-detect must use Browser Hint Detection only: non-permission browser platform hints such as client hints/platform/UA fallback.
• Relay must not use browser fingerprinting, device scans, permission prompts, or invasive detection to choose installers.
• Relay app flows must follow No Device Credential Prompt: never ask for device password, OS password, fingerprint, or biometric credential for install detection or local app storage.

[rushtanu14]

Grill-with-docs update: No Device Credential Prompt now explicitly bans OS password, fingerprint/biometric, Keychain access prompts, and Electron safeStorage prompts. Relay desktop storage should stay prompt-free; ADR added at docs/adr/0001-prompt-free-local-storage.md.

Installer detection should use Browser Hint Detection only: browser platform hints, no fingerprinting, no permission prompts, and no device scans.

[rushtanu14]

Grill-with-docs update: mobile, tablet, ChromeOS, and ambiguous platforms should show the Web/PWA Entry Point or Install Fallback first, not a guessed desktop installer. Still include a clear Desktop Installer Escape Hatch such as "View desktop installers" so visitors can open the Installer Choice List and download Relay for another computer.

[rushtanu14]

Grill-with-docs update: Sample Workspace visitor-created sessions are Memory-Only Sample State. Reload, sign-out, or tab close clears them. Visitor-created Class Artifacts must not be written to localStorage, Supabase, cookies, telemetry payloads, or analytics. Static seeded sample content may reload because it is product demo content, not visitor-created class data.

[rushtanu14]

Grill-with-docs update: Celebration Moment now covers teacher new-session draft creation, teacher publish success, and student completion check-in. Confetti must fire only after the underlying state change succeeds, respect reduced-motion preferences, and avoid false-success states. Microinteraction Polish is allowed across buttons/controls, but must avoid layout shift and stay off disabled/loading controls.

[rushtanu14]

Grill-with-docs update: student-side confetti should trigger when the student submits/marks the full follow-up complete, not for every individual task checkbox. Individual task toggles can use small microinteraction polish such as a checkmark animation.

[rushtanu14]

Grill-with-docs update: student completion must commit first. After the full completion check-in succeeds, show success/confetti, then optionally show the Student Feedback Popup as a Non-Blocking Feedback Prompt. Feedback must never block completion, undo progress, or be required to finish.

[rushtanu14]

Grill-with-docs update: completion-popup student feedback is Creator Product Feedback for Rushil/the Relay creator. It must not appear in teacher analytics, classroom records, grades, or named teacher-visible student reports. Teacher-visible classroom feedback would be a separate future feature.

[rushtanu14]

Grill-with-docs update: product feedback should use Product Feedback Data Minimum only: rating, optional improvement note, app/version/context metadata, and timestamp. Do not include transcript text, roster content, student email, teacher email, class artifact content, or other classroom-identifying payloads.

[rushtanu14]

Correction to prior feedback payload note: student completion-popup feedback should be Transcript-Attached Product Feedback. Store the rating, optional improvement note, app/version/context metadata, timestamp, and the relevant session transcript so Rushil/the Relay creator can diagnose product quality. This feedback goes to the creator, not the teacher, and must not appear in teacher analytics, classroom records, grades, or named teacher-visible reports. Do not add separate roster exports, student emails, teacher emails, grades, or non-transcript class artifacts unless a later explicit support/export flow asks for them.