New_Micro_Learning/docs/phase-checklist.md

# Phase Completion Checklist

This file is the execution record for the Master Prompt phases. An item is checked only after implementation and proportional verification. Passing tests alone does not make a product capability complete.

## Phase 1 — Design System and Application Shells

### Design foundations

- [x] Semantic light/dark color tokens, typography, spacing, radii, elevation, motion, breakpoints, and z-index scales are implemented.
- [x] FA/EN locale changes the document language and true RTL/LTR direction without hard-coded physical layout assumptions.
- [x] Theme and locale preferences persist across reloads and respect the initial system preference.
- [x] Reusable primitives exist for buttons, fields, validation, alerts, badges, loading/skeleton, empty, error, permission-denied, offline, modal, and toast feedback.
- [x] Interactive controls have visible focus, disabled, pending, pressed, and error states with minimum 44px targets.

### Application shells

- [x] Designer shell contains the complete Master Prompt navigation and header actions.
- [x] Super Admin shell contains the complete platform-operations navigation.
- [x] Manager shell contains the complete team-management navigation.
- [x] Learner shell is mobile-first and uses at most five labelled bottom-navigation destinations.
- [x] Desktop sidebar, tablet collapse, and mobile drawer behavior work without horizontal overflow.
- [x] Command palette opens with Ctrl/Cmd+K, is keyboard accessible, searches authorized navigation, and supports dismissal/focus restoration.
- [x] Shell profile and organization labels are data-driven; no demo identity is presented as real user data.
- [x] Route transitions move focus to main content and all shells provide skip navigation.

### Phase 1 quality gates

- [x] Component and shell tests pass.
- [x] TypeScript strict typecheck passes.
- [x] Lint passes.
- [x] Production build passes.
- [x] Visual review passes at 375px-equivalent CSS breakpoint, 768px, 1024px, and desktop in RTL and LTR.
- [x] Reduced-motion and light/dark modes are reviewed.

## Phase 2 — Authentication, Tenancy, and Organization Infrastructure

### Backend

- [x] Login, logout, current-user, forgot-password, reset-password, invitation acceptance, and disabled-account behavior are implemented.
- [x] Auth responses expose the minimum safe identity, role, locale, timezone, organization context, permissions, and deployment capabilities.
- [x] Auth and password endpoints have validation, privacy-safe errors, and rate limiting.
- [x] Tenant context is resolved exclusively from the authenticated user and ignores client-supplied organization identifiers.
- [x] Tenant-owned queries and route-model lookups used in this phase are organization scoped.
- [x] Super Admin organization list/create/read/update endpoints exist without exposing tenant learning analytics.
- [x] SaaS/On-Prem capabilities are served through the deployment abstraction.

### Frontend

- [x] Central typed API client handles bearer tokens, validation errors, unauthenticated responses, and abort signals.
- [x] Auth session provider restores the current session and keeps remote identity out of Zustand.
- [x] Login screen is complete, accessible, bilingual, responsive, and handles pending/success/failure.
- [x] Forgot-password and reset-password screens are complete and privacy-safe.
- [x] Invitation-acceptance screen is complete and validates token/name/password states.
- [x] Protected routes redirect unauthenticated users and role guards reject unauthorized workspaces.
- [x] Signed-in shell displays the real user and organization context.
- [x] Logout revokes the current token and clears local session state.
- [x] Organization administration screen consumes real APIs and implements loading, empty, populated, error, and permission-denied states.
- [x] Deployment capabilities hide SaaS-only organization administration in On-Prem mode.

### Phase 2 quality gates

- [x] Backend auth, tenancy, organization authorization, and isolation tests pass.
- [x] Frontend auth/provider/guard/form tests pass.
- [x] Typecheck, lint, and production build pass.
- [x] Login and recovery screens pass RTL/LTR and mobile visual review.
- [x] No client-provided organization ID is trusted by authenticated tenant APIs.

## Phase 3 — Users, Teams, Subscriptions, and Permissions

### Backend

- [x] User directory supports tenant-scoped search, role/status filters, pagination, and safe user payloads.
- [x] Course Designers can update user role/status within allowed tenant boundaries; last active Designer protection is enforced.
- [x] Invitations expose pending/expired status and can be resent or revoked without leaking tokens.
- [x] Team APIs support list/create/read/update plus member and manager attach/detach with tenant validation.
- [x] Manager reads remain restricted to managed teams and their members.
- [x] Subscription API exposes dates, feature flags, seat/storage/AI quotas, and current usage without pricing logic.
- [x] Seat quota is enforced consistently for invitations and activations.
- [x] Central permission matrix is returned by the session and enforced server-side for every Phase 3 mutation.

### Frontend

- [x] Users screen uses real APIs with search, role/status filters, loading/empty/populated/error/permission states, and invitation workflow.
- [x] Teams screen uses real APIs with create, details, member/manager assignment, removal, and responsive states.
- [x] Subscription screen presents real plan dates, feature flags, quota usage, and accessible progress indicators.
- [x] UI actions are permission-aware while backend authorization remains authoritative.
- [x] Mutation pending/success/failure feedback is visible and accessible.
- [x] Phase 3 tables/cards remain usable on mobile, tablet, RTL/LTR, and light/dark themes.

### Phase 3 quality gates

- [x] Backend users/teams/subscription/permission/quota tests pass.
- [x] Frontend Users/Teams/Subscription tests pass.
- [x] Typecheck, lint, and production build pass.
- [x] Responsive and RTL/LTR visual review passes.
- [x] No Phase 3 tenant resource can be accessed or mutated cross-tenant.

## Phase 4 — Course Domain, Versions, Modules, and Lessons

### Backend

- [x] Course list supports tenant-scoped search, status filters, sorting, pagination, and safe summary payloads.
- [x] Blank-course creation atomically creates Course, Draft Version 1, initial Module, and initial Lesson.
- [x] Course workspace API exposes overview, ordered structure, and version history without learner analytics placeholders.
- [x] Draft version metadata can be edited while Published versions remain immutable.
- [x] Editing a Published version forks a complete new Draft version with stable source-version history.
- [x] Module APIs support create/update/delete/reorder with contiguous positions and draft-only mutations.
- [x] Lesson APIs support create/update/delete/reorder/move with contiguous positions and draft-only mutations.
- [x] Existing blocks are copied when a Published version is forked and remain linked to the new version hierarchy.
- [x] All Course, Version, Module, Lesson, and fork operations are tenant-scoped and permission-enforced.

### Frontend

- [x] Courses screen uses real APIs with search, status views, sorting, and loading/empty/populated/error/permission states.
- [x] New Course screen presents exactly four creation paths and completes the Blank Course workflow.
- [x] Future Template, Import, and AI paths are clearly unavailable without fake progress or generated results.
- [x] Course Workspace provides Overview, Content, and Versions views backed by real API data.
- [x] Content view supports module and lesson creation, rename, deletion, and ordering with visible mutation feedback.
- [x] Published versions expose a clear “Create editable draft” action instead of direct editing.
- [x] Course routes are deep-linkable, permission-aware, responsive, RTL/LTR-safe, and light/dark compatible.

### Phase 4 quality gates

- [x] Backend course/version/module/lesson authorization, immutability, ordering, fork, and tenant-isolation tests pass.
- [x] Frontend Courses/New Course/Course Workspace tests pass.
- [x] Typecheck, lint, formatting, and production build pass.
- [x] Responsive RTL/LTR and light/dark visual review passes.
- [x] No Phase 4 resource can be accessed or mutated cross-tenant.

## Phase 5 — Builder Core

### Backend and contracts

- [x] Builder reads the canonical Course Version/Lesson structure through tenant-scoped APIs.
- [x] Block creation supports an explicit insertion position and keeps lesson positions contiguous.
- [x] Block duplication preserves the unified contract and creates an independent Draft copy.
- [x] Module and Lesson duplication copy their nested Draft content without crossing tenant/version boundaries.
- [x] Module and Lesson lock state is explicit and prevents protected structure/content mutations.
- [x] All Builder mutations remain Draft-only, permission-enforced, revision-aware, and tenant-isolated.

### Builder experience

- [x] Builder uses the central authenticated API client and works with the real application session.
- [x] RTL Builder layout provides Canvas, Course Structure, Block Library, and Inspector with functional collapsible panels.
- [x] Toolbar provides functional Undo/Redo for persisted content edits and block ordering.
- [x] Autosave exposes clear idle, saving, saved, and failed states with a retry path.
- [x] Primary Heading, Text, and Key Point content can be edited inline on the Canvas.
- [x] Insertion affordances between blocks open an accessible Block Picker at the selected position.
- [x] Slash commands open the same Block Picker without creating a second block-selection system.
- [x] Keyboard shortcuts support save, undo, redo, selection dismissal, and safe deletion.
- [x] Drag-and-drop reordering has optimistic feedback, clear drop state, and keyboard-accessible move controls.
- [x] Course Structure supports real lesson navigation plus module/lesson add, rename, duplicate, reorder, delete, and lock controls.
- [x] Desktop, Tablet, and Mobile preview widths use the same canonical block renderer.
- [x] Published versions are visibly read-only and never expose active mutation controls.
- [x] Comments, collaboration, AI, learner preview, and publishing controls are labelled honestly as later-phase capabilities.

### Phase 5 quality gates

- [x] Backend insertion/duplication/locking/revision/immutability/tenant tests pass.
- [x] Frontend history/autosave/inline editing/picker/shortcuts/panel tests pass.
- [x] Typecheck, lint, formatting, and production build pass.
- [x] Builder visual review passes at desktop, tablet, mobile preview, RTL/LTR, and light/dark states.
- [x] No fake save, preview, collaboration, AI, or publishing result is presented as functional.

## Later phases

## Pre-Phase 7 Product Corrections

- [x] Asset and video uploads accept files up to 2 GB in API validation and the local launcher PHP configuration.
- [x] Content Library supports a compact row view and an exact 5 cm × 5 cm desktop card view.
- [x] Workforce import accepts XLSX/CSV files with first name, last name, department, job level, direct manager, and email columns.
- [x] Workforce import validates job levels, duplicate/ambiguous identities, tenant boundaries, seat quota, and applies changes atomically.
- [x] Course cards are approximately 30% denser and preserve responsive behavior.
- [x] Designers can select, replace, or remove a private image Asset as the Course cover.
- [x] Selecting a Team manager automatically attaches that manager and their active direct reports.
- [x] Teams screen presents consolidated metrics, search, structured manager/member groups, and clearer hierarchy details.
- [x] Positive/confirmation actions use semantic green and destructive/negative actions use semantic red.
- [x] Seeded Manager and Learner review accounts are documented and usable.
- [x] User directory renders name, email, department, job position, manager, role, status, and actions in independent columns.
- [x] User profiles can be edited with hierarchy-cycle and cross-tenant manager protection.
- [x] Every Draft-safe Asset exposes deletion; used Draft references are detached atomically while Published references remain protected.
- [x] Content cards keep title, size, usage count, and destructive action in non-overlapping regions.
- [x] Image, video, audio, and PDF Assets open in an accessible preview dialog; unsupported documents offer a safe open/download path.
- [x] Workforce import includes a real downloadable RTL XLSX template with manager-first sample rows.
- [x] Backend and Frontend regression suites, typecheck, lint, formatting, production build, migrations, launcher check, API smoke tests, and visual review pass.

## Phase 6 — Block System and Block Registry

### Canonical block platform

- [x] Backend and Frontend registries expose one unified Block contract: data, style, behavior, responsive, accessibility, capabilities, web behavior, and export compatibility.
- [x] Registry validation covers every implemented non-assessment Phase 6 block and rejects unknown fields/types safely.
- [x] Schema-version migration infrastructure can upgrade persisted Block data without silently rewriting Published versions.
- [x] Builder availability is driven by Registry metadata and parity is protected by automated tests.
- [x] Heading, Text, Quote, Key Point, Divider, and Button blocks are implemented.
- [x] Image, Gallery, Video, Audio, Document, and Embed blocks are implemented with safe URL/file behavior.
- [x] Flashcard, Accordion, Tabs, Timeline, Steps, Process, and Checklist blocks are implemented.
- [x] Section, preset Columns, and Controlled Grid blocks are implemented with responsive stacking configuration.
- [x] Phase 6 shipped no fake assessment interactions; the real assessment catalog is completed in Phase 7 below.

### Editing and rendering

- [x] Each registered block supplies its own Renderer, Editor configuration, validation schema, defaults, icon, and category without Builder-level type switches.
- [x] Inspector Content, Design, and Behavior tabs are functional for the properties supported in Phase 6.
- [x] Design controls persist alignment, width, spacing, background, border, and radius using controlled tokens.
- [x] Behavior controls persist visibility, completion, animation, and Block lock state without claiming Player behavior before Phase 9.
- [x] Accessibility controls persist alt text, labels, transcript/caption information, and decorative intent where applicable.
- [x] Canonical renderers are reused by Builder preview widths and nested controlled layouts stack safely on mobile.
- [x] Navigator supports locate/select plus visible/locked state and keyboard ordering alternatives.

### Assets and learning mapping

- [x] Tenant-scoped Asset API validates type, MIME, size, extension, filename, authorization, and private access.
- [x] Asset list supports search/type filtering, preview metadata, and usage-reference counts.
- [x] Used Draft assets can be detached and deleted atomically; Published references and cross-tenant assets remain protected.
- [x] Content Library provides real upload, search, filter, preview, usage, empty/loading/error, and safe-delete states.
- [x] Media Block editors select uploaded assets through one reusable Asset Picker.
- [x] Reusable LearningMappingPanel lists direct Block mappings and searches taxonomy nodes by name/code/type.
- [x] Designers can add and remove confirmed develops/practices/assesses/related mappings on Draft Blocks.
- [x] Published and cross-tenant mapping mutations remain rejected; AI suggestions are not presented as confirmed mappings.

### Phase 6 quality gates

- [x] Backend Registry, schema, Asset validation/privacy/usage, mapping, authorization, and tenant-isolation tests pass.
- [x] Frontend Registry/editor/renderer, Asset Library/Picker, Mapping Panel, Inspector, and responsive-layout tests pass.
- [x] Typecheck, lint, backend formatting, and production build pass.
- [x] Builder and Content Library visual review passes in RTL/LTR, light/dark, desktop/tablet/mobile states.
- [x] `start-dev.bat --check`, authenticated API smoke tests, and temporary-service cleanup pass.
- [x] No Phase 8 publishing or Phase 9 Player result is presented as functional.

## Phase 7 — Assessments and Scenarios

### Question bank and assessment authoring

- [x] Tenant-scoped Question Bank supports create, edit, delete, search, type, difficulty, topic, tags, explanation, usage, and performance metadata.
- [x] Single Choice, Multiple Choice, True/False, Matching, Sorting, Drag and Drop, and Hotspot question schemas are validated server-side.
- [x] Assessments support reusable bank questions, direct question copies, ordering, random selection, pools, shuffling, passing score, attempt limit, feedback mode, and time limit.
- [x] Draft assessment/question mutations are authorized, tenant-isolated, and rejected for Published Course Versions.
- [x] Assessments and individual assessment questions support weighted taxonomy/competency mappings.

### Scenarios and interactive blocks

- [x] Scenario authoring supports context, choices, score, feedback, topic, difficulty, and tags.
- [x] Branching Scenario visual authoring supports Scene, Question, Choice/Branch, and Result nodes.
- [x] Branch graphs reject missing start nodes, broken targets, duplicate nodes, and unreachable nodes.
- [x] Interactive Image and Before/After blocks are registered with real editors, renderers, schemas, and Asset references.
- [x] Backend and Frontend Block registries expose the complete Phase 7 assessment/interaction catalog with validated defaults.

### Phase 7 quality gates

- [x] Question Bank, assessment settings, scenario graph, authorization, Published immutability, and tenant-isolation tests pass.
- [x] Assessment Studio and Registry UI tests pass, including taxonomy mapping access.
- [x] Full backend suite passes: 93 tests and 559 assertions.
- [x] Full frontend suite passes: 11 files and 35 tests.
- [x] Typecheck, lint, backend formatting, migrations, seed data, and production build pass.
- [x] Visual review passes for Question Bank, assessment mapping, scenarios, users, Excel import, and both Content Library layouts.

## Later phases

- [x] Phase 7 — Assessments and scenarios
- [x] Phase 8 — Publishing, assignments, and Learning Paths
- [x] Phase 9 — Learner Player, PWA, and offline
- [x] Phase 10 — Manager Workspace and Learner iOS Experience
- [x] Phase 11 — Events, analytics, and Monitoring
- [x] Phase 12 — Collaboration and realtime
- [x] Phase 13 — AI Studio and ingestion
- [x] Phase 14 — Export Center and certificates
- [x] Phase 15 — Production hardening and deployment

## Phase 8 — Publishing, Assignments, and Learning Paths

### Publishing and version integrity

- [x] Course versions support Draft, In Review, Published, scheduled publish, scheduled unpublish, and safe unpublish states.
- [x] Readiness checks validate metadata, structure, lesson content, Blocks, Assets, assessments, scenarios, and completion rules before review/publish.
- [x] Completion rules use a controlled logical model for required lessons, minimum lesson percentage, assessment pass, minimum score, and required interaction.
- [x] Publishing snapshots taxonomy mappings so later Draft changes never rewrite Published evidence context.
- [x] Published versions remain immutable; forking copies modules, lessons, Blocks, assessments, questions, completion rules, and taxonomy mappings.
- [x] Publishing a new version supports no reassignment or copying all active assignments from its source version.

### Assignment engine

- [x] Published Courses and Learning Paths can be assigned to an individual, Team, department, organization, controlled rule, or an uploaded XLSX/CSV audience list.
- [x] Assignments support mandatory status, start/due dates, recurring month interval, reminder days, and manager escalation policy.
- [x] Recipient snapshots preserve assignment history and cancellation state.
- [x] Team and rule audiences are dynamically resolved; newly imported/edited users and newly attached Team members are synchronized automatically.
- [x] Designers can list, create, cancel, filter, and manually resynchronize Assignments from the product UI/API.

### Learning Paths

- [x] Learning Paths contain ordered Published Course Versions with optional prerequisites and controlled completion rules.
- [x] The V1 editor is a clean responsive ordered list with visible move controls instead of a complex node canvas.
- [x] Draft paths support add, remove, reorder, metadata, enforced-order setting, review, and publish workflows.
- [x] Published Learning Path Versions are immutable and can be forked without changing prior history.
- [x] Published Learning Paths are available to the Assignment Engine.

### Phase 8 quality gates

- [x] Dedicated backend tests cover publish immutability, dynamic Team assignment, and Learning Path version history.
- [x] Full backend suite, frontend typecheck, and production build pass.
- [x] UI follows the existing responsive RTL design system with semantic success/danger states, labelled controls, loading/error/empty states, and confirmation for sensitive actions.

## Phase 9 — Learner Player, PWA, and Offline

### Learner experience and Player

- [x] Learner navigation provides Home, My Learning, Daily, Progress, and More without exposing a public Course catalog.
- [x] Home uses assigned data for greeting, Continue Learning, Daily Learning, Assigned to You, Due Soon, and verified progress summaries.
- [x] Assignment and tenant authorization protects every Player payload and only exposes referenced private Assets through signed URLs.
- [x] Flow and card/story presentation modes use the same canonical Course Version, Lesson, and Block content.
- [x] Card/story mode remains card-based on desktop and supports vertical touch navigation on mobile.
- [x] Player chrome includes Course, Lesson and overall progress, collapsed outline, previous/next controls, sticky mobile progress, and accessible interaction controls.
- [x] Single Choice, Multiple Choice, True/False, Matching, Sorting, Drag and Drop, Hotspot, Scenario, and Branching Scenario interactions are functional in Player.
- [x] Assessment scores are recalculated from canonical answers on the server and never trusted from the browser payload.
- [x] Completion rules update lesson, course, and Assignment recipient progress from idempotent learning events.

### Learner tools and social learning

- [x] Private notes, Block bookmarks, selected-text highlights, and Course favorites persist with learner/tenant scope.
- [x] Lesson discussions support posts, replies, helpful reactions, and scoped authorization.
- [x] Notes can be printed or saved as PDF using a dedicated print layout.
- [x] Notes and saved highlights are visible in one compact Player drawer.

### PWA and offline architecture

- [x] Installable web manifest, application icon, theme metadata, and Service Worker registration are present.
- [x] Explicit Course download uses the server manifest and caches only approved referenced Assets.
- [x] IndexedDB stores cached Course payload/download metadata, private notes, progress, and queued learning events.
- [x] Offline events synchronize on reconnect, reconcile local note state, and use client event IDs to prevent duplicate progress and notes.
- [x] Large videos follow an explicit manifest policy and are excluded from automatic offline download above the configured threshold.
- [x] Online, offline, loading, empty, authorization, and recovery states are represented honestly.

### Phase 9 quality gates

- [x] Dedicated backend Player tests pass for assignment scope, tenant isolation, event idempotency, completion, private notes/bookmarks, social features, offline notes, and server-side scoring.
- [x] Full backend suite passes: 103 tests and 624 assertions; PHP formatting passes.
- [x] Full frontend suite passes: 12 files and 36 tests; typecheck and zero-warning lint pass.
- [x] Production build and `start-dev.bat --check` pass.
- [x] Seeded desktop/mobile, light/dark RTL visual review passes for Learner Home and Player; temporary review services are cleaned up.

## Phase 10 — Manager Workspace and Learner iOS Experience

### Cross-role session controls

- [x] A visible Logout action is available to Designer, Super Admin, Manager, and Learner users.
- [x] Logout shows pending/error feedback, revokes the current API token, clears local authentication state, and returns to Login.
- [x] Learner Player provides a predictable route back to the learner workspace where account and Logout controls remain reachable.
- [x] Automated tests cover Logout visibility and behavior for workspace and learner shells.

### Manager authorization and data contracts

- [x] Manager APIs are protected by Manager role/permission checks and derive tenant context only from the authenticated user.
- [x] Every Manager query is restricted to Teams explicitly managed by that Manager; unmanaged and cross-tenant records are not disclosed.
- [x] Manager cannot author, publish, assign, mutate Team membership, or manage organization settings through UI or API.
- [x] Manager Overview returns real, explainable Team Learning Health, completion, engagement, assessment, overdue, at-risk, and attention metrics.
- [x] My Team returns managed Teams and member profiles with assignment/progress summaries and safe drill-down data.
- [x] Learning Status, Courses, Assessments, Attention, Reports, and Notifications use scoped server data with documented empty states.
- [x] No Phase 11 predictive/Monitoring metric is fabricated; unavailable future analytics are labelled honestly.

### Manager workspace UI

- [x] `/manager` provides Overview, My Team, Learning Status, Courses, Assessments, Attention, Reports, and Notifications routes.
- [x] Overview composes reusable metric, health, attention, progress, and status components rather than page-local duplicates.
- [x] Tables/lists support useful Team, status, Course, and due-state filters with responsive card alternatives on mobile.
- [x] Attention items explain why a person needs attention and link to a scoped detail or recommended follow-up.
- [x] Manager pages include loading, empty, error, permission-denied, and retry states.
- [x] Manager workspace is responsive, bilingual, RTL/LTR-safe, keyboard accessible, and uses semantic success/danger colors.

### Learner iOS-style redesign

- [x] Learner Home, My Learning, Daily, Progress, More, and Player use one cohesive iOS-inspired visual language in light and dark themes.
- [x] Learner screens use large-title hierarchy, grouped surfaces, restrained blur/elevation, system-like controls, and consistent rounded geometry.
- [x] Bottom navigation is a floating rounded tab bar with five labelled icons, safe-area spacing, visible selected state, and at least 44×44 px touch targets.
- [x] Scroll content reserves enough bottom inset so the floating navigation never covers cards or actions.
- [x] More includes account identity, theme/language access, offline information, and visible Logout.
- [x] Player retains minimal chrome, readable progress, offline state, notes/discussion access, and safe-area-aware controls after the redesign.
- [x] Motion is subtle, interruptible, and disabled/reduced when `prefers-reduced-motion` is enabled.

### Phase 10 quality gates

- [x] Backend tests cover Manager scope, unmanaged/cross-tenant denial, real metric calculations, and forbidden mutations.
- [x] Frontend tests cover Manager routes/states, filters/drill-down, Logout, and learner floating navigation.
- [x] Full backend/frontend tests, typecheck, zero-warning lint, PHP formatting, and production build pass.
- [x] `start-dev.bat --check`, seeded Manager/Learner smoke tests, and temporary-service cleanup pass.
- [x] Visual review passes for Manager desktop/tablet/mobile and learner iOS-style small-phone/large-phone/desktop in FA/EN, RTL/LTR, light/dark.

## Phase 11 — Event Pipeline, Analytics, and Monitoring Engine

### Event contracts and processing

- [x] Learning Events use a versioned, allow-listed taxonomy with server-owned tenant and actor context.
- [x] Event ingestion preserves immutable raw facts, client idempotency, occurred/received time, session, correlation, causation, and device context.
- [x] Offline and late events are accepted safely without duplicate projections or client-controlled analytics values.
- [x] Projection processing is idempotent, retryable, observable, and can rebuild derived metrics from raw events.
- [x] Meaningful Course, Lesson, Block, video, assessment, social, note, and completion interactions emit documented events.

### Metrics and learning intelligence

- [x] Metrics Engine derives completion, on-time completion, engagement, learning time, inactivity, and progress velocity from canonical data.
- [x] Course/Lesson/Block analytics expose starts, completions, drop-off, and drill-down without fabricated telemetry.
- [x] Video analytics support reliable start, 25/50/75 percent, completion, average watch, exit point, replay, and skip signals.
- [x] Assessment analytics expose score, pass rate, attempts, question difficulty, common wrong answers, and Team comparison.
- [x] Evidence processing remains immutable and triggers versioned Capability score, confidence, snapshot, gap, and coverage recalculation.
- [x] Insufficient evidence is labelled honestly and score precision never exceeds evidence quality.

### Monitoring, Risk, Attention, and actions

- [x] Learning Health uses centrally configured weights and exposes every contributing factor.
- [x] V1 Risk Score is an explainable heuristic behind a provider abstraction and is never labelled as ML probability.
- [x] Insight and Attention items contain severity, reason, entity, evidence, trend, suggested action, and drill-down destination.
- [x] Attention supports inactivity, deadline risk, engagement decline, drop-off, assessment difficulty, capability gaps, confidence, and coverage warnings.
- [x] Raw events remain conceptually and physically separate from metrics, insights, risks, and attention projections.

### APIs, privacy, and UI

- [x] Designer Monitoring APIs are tenant-scoped; Manager analytics are limited to managed Teams; Super Admin cannot access employee learning analytics.
- [x] Analytics filters support date, Team, Course, learner status, skill/competency, evidence type, and confidence where relevant.
- [x] Drill-down supports Organization → Team → Course → Module → Lesson → Block with stable URLs and a predictable back path.
- [x] Monitoring UI provides Overview, Health, Engagement, Courses, Teams, Learners, Assessments, Skills & Competencies, Risk, and Reports.
- [x] Charts use suitable forms, visible units/legends, keyboard-readable summaries, responsive layouts, and accessible table alternatives.
- [x] Every Monitoring screen includes loading, empty, insufficient-data, error, retry, FA/EN, RTL/LTR, light/dark, and reduced-motion states.

### Phase 11 quality gates

- [x] Backend tests cover event schema, idempotency, late events, projection rebuild, metric formulas, risk explanation, privacy, and tenant isolation.
- [x] Frontend tests cover Monitoring routes, filters, chart summaries, drill-down, empty/error states, and role authorization.
- [x] Full backend/frontend tests, PHP formatting, lint, typecheck, migrations, seed, and production build pass.
- [x] `start-dev.bat --check`, four-role smoke tests, seeded analytics smoke test, and temporary-service cleanup pass.
- [x] Visual review passes for Monitoring desktop/tablet/mobile in FA/EN, RTL/LTR, light/dark, including a 375px viewport.

## Phase 12 — Collaboration and Realtime

### Cross-role routing and account header corrections

- [x] Login replaces an existing session safely and redirects only to a route compatible with the newly authenticated role.
- [x] Designer, Super Admin, Manager, and Learner can switch accounts without landing in another role's workspace or a permission dead end.
- [x] Direct navigation to an incompatible workspace redirects to the authenticated role home while backend authorization remains authoritative.
- [x] Workspace profile moves from the sidebar to the top bar beside theme and notifications, with accessible account details and Logout.
- [x] Header account controls remain usable at 375px, RTL/LTR, light/dark, keyboard, and reduced-motion settings.

### Collaboration domain and authorization

- [x] Multiple Designers can open the same Course Version and see active presence with stale-session expiry.
- [x] Block-level soft locks use renewable leases, prevent conflicting edits, identify the holder, and never become permanent hard locks.
- [x] Collaboration access is tenant-scoped and restricted to authorized Course Designers; published content remains immutable.
- [x] Collaboration mutations are idempotent where retry/offline behavior can duplicate a request.
- [x] The canonical Course/Version/Lesson/Block model remains the single collaboration target; no duplicate editor document is introduced.

### Comments, review, mentions, reactions, and notifications

- [x] Block and Course review comments support open/resolved state, threaded replies, @mentions, and reactions.
- [x] Mention targets are restricted to active same-tenant collaborators and cannot disclose cross-tenant identities.
- [x] Review Center aggregates unresolved threads, resolution state, author, target, timestamps, and stable Builder deep-links.
- [x] In-app notifications cover mentions, replies, reactions, review changes, and lock conflicts with read/unread state.
- [x] Notification links route each role to an authorized destination and degrade safely when a target is no longer available.

### Realtime transport and UI

- [x] Presence, soft locks, comments, and notifications publish versioned collaboration changes through a transport abstraction.
- [x] UI updates promptly when change delivery is available and falls back to bounded API refresh without losing core functionality.
- [x] Builder shows presence and lock ownership without implying Google Docs-style simultaneous text editing.
- [x] Collaboration panel and Review Center include loading, empty, error, retry, offline/degraded, and permission states.
- [x] Collaboration UI is responsive, bilingual, RTL/LTR-safe, light/dark, keyboard accessible, and uses 44px minimum targets.

### Phase 12 quality gates

- [x] Backend tests cover presence expiry, lock acquire/renew/release/conflict, comments, mentions, reactions, notifications, permissions, and tenant isolation.
- [x] Frontend tests cover four-role routing, header profile behavior, collaboration states, lock conflicts, review actions, and refresh fallback.
- [x] Full backend/frontend tests, PHP formatting, lint, typecheck, migrations, seed, and production build pass.
- [x] `start-dev.bat --check`, four-role account-switch smoke tests, collaboration smoke tests, and temporary-service cleanup pass.
- [x] Visual review passes for account header, Builder collaboration, and Review Center on desktop/tablet/375px in FA/EN, RTL/LTR, light/dark.

## Phase 13 — Product Completion, AI Studio, and Document Ingestion

### Cross-role product completion

- [x] Designer Dashboard opens the complete Monitoring experience instead of the Foundation placeholder.
- [x] Designer Reports, Export Center, Skills & Competencies, Certificates, Brand Kit, Settings, and Templates are functional screens with real data or honest actionable empty states.
- [x] Admin Dashboard exposes real platform monitoring and Organizations, subscriptions, usage, storage, AI usage, system health, audit, and settings no longer use Foundation placeholders.
- [x] Course Workspace Learners, Analytics, Discussion, and Settings tabs are active, distinct, and explain their purpose without duplicate Settings tabs.
- [x] User directory uses an 11px dense table presentation while preserving readable mobile cards and 44px actions.

### Branding and role-aware personalization

- [x] Supplied MicroLearn logo is installed as the application mark, favicon, Apple touch icon, and PWA icons.
- [x] Organization Brand Kit supports logo, display name, primary/accent colors, learner welcome copy, and certificate identity.
- [x] Designer, Admin, Manager, and Learner personalization surfaces expose only role-appropriate preferences.
- [x] Branding and preferences persist with tenant/user scoping and safe defaults across FA/EN and light/dark themes.

### Notifications

- [x] Notifications are removed from Designer and Manager side navigation and open from an accessible top-bar popover.
- [x] Learner receives an iOS-style notification sheet from the learner header.
- [x] Manager and Learner notification cards support left/right swipe with visible non-gesture alternatives.
- [x] Notification read/dismiss actions are tenant-scoped, keyboard accessible, reduced-motion-safe, and show honest empty/error states.

### AI provider and governance

- [x] AI operations use a provider abstraction with explicit local/external/disabled state and no direct provider coupling in Course code.
- [x] AI operations record organization, actor, provider, operation, status, usage, error, and timing without logging private prompts unnecessarily.
- [x] Organization quota and On-Prem external-AI disablement are enforced server-side.
- [x] Generated content and taxonomy mappings are always Draft proposals requiring Designer confirmation and can never auto-publish.

### Document ingestion and provenance

- [x] PDF, DOCX, and PPTX uploads are privately stored, MIME-validated, size-limited, and processed through resumable/idempotent ingestion jobs.
- [x] Extraction normalizes text, identifies sections, proposes Modules/Lessons, and preserves page/slide/source-fragment provenance.
- [x] Existing SCORM is retained as packaged external learning content and is never reverse-engineered into editable Blocks.
- [x] Designers can inspect source versus proposal, edit structure, retry/cancel failures, and accept a proposal into a canonical Draft Course Version.

### AI Studio and Builder assistance

- [x] `/app/ai-studio` shows ingestion/generation jobs, progress, provider state, quota, retry/cancel, and source traceability.
- [x] Create Course offers Blank, Template, Import Content, and Create with AI as four working paths.
- [x] AI course creation accepts topic, audience, objective, duration, difficulty, language, tone, lesson count, assessment level, and interaction density.
- [x] Builder assistant supports Generate Lesson/Quiz, Rewrite, Shorten, Simplify, Examples, Interaction, Split, Audit, Objectives, and Assessment Alignment through preview/diff confirmation.
- [x] AI taxonomy assistance suggests existing same-tenant Skills/Competencies with rationale/confidence and persists only after explicit confirmation.

### Phase 13 quality gates

- [x] Backend tests cover authorization, tenant isolation, provider disabled/quota states, ingestion formats, provenance, idempotency, Draft-only acceptance, and taxonomy confirmation.
- [x] Frontend tests cover completed routes, notification popovers/swipe alternatives, Course tabs, personalization, AI Studio states, and proposal confirmation.
- [x] Full backend/frontend tests, migrations, seed, Pint, lint, typecheck, and production build pass.
- [x] Four-role smoke tests and visual review pass on desktop/tablet/375px in FA/EN, RTL/LTR, light/dark, and reduced motion.

## Phase 14 — Export Center and Certificates

### Export engine

- [x] Central Export Center lists Published Course Versions, formats, queue status, progress, history, size, errors, retry, cancel, and download.
- [x] SCORM 1.2, SCORM 2004, xAPI, cmi5, Standalone HTML5, PDF Workbook, and adapter-based MP4 are represented behind canonical render adapters.
- [x] Compatibility checks run before generation and require explicit confirmation for deterministic static fallbacks.
- [x] Export generation is asynchronous, tenant-scoped, retained according to policy, and stored through the configured filesystem abstraction.
- [x] PDF Workbook includes cover, TOC, modules, lessons, static interaction representations, branding, and page footer/numbering.

### Certificates

- [x] Completion-rule satisfaction issues an idempotent certificate automatically and manual issuance is limited to eligible completions.
- [x] Certificates include unique number/code, issue date, optional expiry, branded PDF, QR, verification URL, and immutable issuance snapshot.
- [x] Public `/certificate/verify/:code` shows only safe verification data and clearly distinguishes valid, expired, revoked, and unknown credentials.
- [x] Certificate Builder supports branded canvas preview, layers, colors, signature identity, default templates, download, and reasoned revocation.
- [x] Certificate issuance creates a learner notification and remains tenant-isolated.

### Phase 14 quality gates

- [x] Backend tests cover compatibility, queue jobs, tenant isolation, artifact download, eligibility, idempotent issuance, QR verification, expiry, and revocation.
- [x] Frontend tests cover export states, warning confirmation, certificate builder/issuance, and public verification states.
- [x] Full backend/frontend tests, Pint, lint, typecheck, migration, seed, build, and browser smoke pass.

## Phase 15 — Production Hardening, On-Prem, and Deployment

### Runtime and security

- [x] Production containers provide Nginx, PHP-FPM, worker, scheduler, MySQL, Redis, and S3-compatible storage with restart and health policies.
- [x] Nginx/PHP enforce 2 GB uploads, safe timeouts, security headers, private storage boundaries, SPA routing, and API proxying.
- [x] Production and On-Prem environment templates keep secrets out of source and expose deployment/storage/queue/mail/AI controls.
- [x] Health checks report API, database, storage, queue, scheduler, mail, WebSocket, export worker, and AI adapter status without exposing credentials.
- [x] On-Prem capability mode hides SaaS-only controls and defaults external AI off while supporting local or S3-compatible storage.

### Operations and release

- [x] Backup and restore scripts cover MySQL and private storage with explicit verification and migration steps.
- [x] Upgrade, rollback, backup/restore, incident, queue, scheduler, storage, and certificate/export runbooks are documented.
- [x] CI runs dependency audit, formatting, backend/frontend tests, lint, typecheck, migrations, and production build.
- [x] Deployment documentation includes prerequisites, TLS boundary, first boot, migrations, workers, scheduler, health, scaling, observability, and disaster recovery.
- [x] Final live smoke verifies launcher, four roles, core APIs, Export/Certificate flows, and clean runtime logs.

### Phase 15 quality gates

- [x] Docker Compose configuration validation and production image builds are enforced in CI; local Docker was unavailable for a duplicate build.
- [x] SaaS and On-Prem capability tests, production config checks, dependency audits, and full automated suites pass.
- [x] No implemented-scope placeholder remains; final checklist and handoff documentation are complete.