Merge pull request #36 from ZDOSS/codex/new-user-tutorial

Add guided new user tutorial

Author: zeidalidiez

AI.md

@@ -676,6 +676,14 @@ The core domain in `packages/core/src/domain/` covers the entities the plan call
   - replacing the stale read-only flow report with `docs/gph-user-flows-review.md`, updating `Readme.md`, and adding focused regressions across AppShell, CommandPalette, WorkItemModal, ProjectsListView, BoardView, TableView, and RoadmapView
   - verifying the finished pass with 53 focused UI tests, the complete 230-test repository suite, all workspace TypeScript checks, a successful production web build, and matched-state desktop/mobile browser comparisons
   - aligning the Playwright project bootstrap with the calmer launcher behavior through a shared `createProjectFromLauncher()` helper, so E2E coverage chooses `New project` before submitting the creation modal instead of depending on the removed automatic first-run modal
+- added the guided New user tutorial by:
+  - placing a `New user tutorial` link directly beneath the launcher’s Demo project explanation and registering `/tutorial` in both the web and desktop shells without treating it as an active project route
+  - adding a focused tutorial landing surface that sets expectations, lists the covered workspace areas, and refuses to replace a dirty or otherwise unsaved active project
+  - opening a disposable `buildDemoProject()` bundle named `Tutorial Project`, keeping its storage trust unsaved, and clearly explaining that tutorial changes remain sample data unless explicitly exported
+  - adding an external tutorial state store persisted in `sessionStorage`, tied to the exact generated tutorial project id so the guide ends instead of leaking into another project
+  - mounting a non-modal, keyboard-readable tutorial panel in `AppShell` with 13 steps, progress semantics, Back/Next/Exit controls, responsive bottom-sheet behavior, and real route transitions across Overview, Board, Backlog, Table, Roadmap, Calendar, Docs, Bug Triage, My Work, Search/commands, Trash, and Settings
+  - synchronizing the wizard with manual sidebar navigation so users can skip ahead or revisit a feature without being forced back to the previous route
+  - adding focused launcher/tutorial component coverage plus a full Playwright journey that advances through every tutorial stop and verifies the final handoff back to Overview
 
 ## Open follow-on planning
 

Readme.md

@@ -44,6 +44,7 @@ For real project work, run the repo locally or use the future release builds.
 Grillo is past the skeleton stage. The current app includes:
 
 - Workspace launcher with new, open/import, demo, recent-project, template preview, explicit browser-vs-folder storage guidance, and a calm first-run state that waits for the user to choose a path.
+- A guided New user tutorial beneath the demo entry that opens safe sample data and walks through all 12 core workspace surfaces in a resumable 13-step wizard.
 - Overview, board, backlog, table, roadmap, calendar, docs, bug triage, my work, search, trash, and settings surfaces.
 - Board-local column management for adding unmapped workflow statuses, removing columns without deleting their statuses or work items, and creating a new categorized status and column together.
 - Explicit save-state UI in the project header, including save destination, dirty state, save failures, manual save/retry, switch project, and guarded close-project actions.

apps/desktop/src/main.tsx

@@ -14,6 +14,7 @@ import {
   ProjectsListView,
   OpenProjectView,
   DemoFolderView,
+  NewUserTutorialView,
   ThemeProvider,
   useRestoreProjectSession
 } from "@gph/ui";
@@ -35,6 +36,7 @@ function App() {
             <Route path="/projects" element={<ProjectsListView />} />
             <Route path="/open" element={<OpenProjectView />} />
             <Route path="/demo" element={<DemoFolderView />} />
+            <Route path="/tutorial" element={<NewUserTutorialView />} />
             <Route path="/*" element={<ProjectRouter />} />
           </Routes>
         </AppShell>

apps/web/src/main.tsx

@@ -14,6 +14,7 @@ import {
   ProjectsListView,
   OpenProjectView,
   DemoFolderView,
+  NewUserTutorialView,
   ThemeProvider,
   useRestoreProjectSession
 } from "@gph/ui";
@@ -42,6 +43,7 @@ function App() {
             <Route path="/projects" element={<ProjectsListView />} />
             <Route path="/open" element={<OpenProjectView />} />
             <Route path="/demo" element={<DemoFolderView />} />
+            <Route path="/tutorial" element={<NewUserTutorialView />} />
             <Route path="/*" element={<ProjectRouter />} />
           </Routes>
         </AppShell>

docs/gph-user-flows-review.md

@@ -2,6 +2,8 @@
 
 **Review date:** 2026-07-16
 
+**Feature update:** 2026-07-17 — added the guided New user tutorial described below.
+
 **Scope:** The complete browser product journey, reviewed in the running app at desktop and mobile widths, followed by implementation and regression verification.
 
 **Primary environment:** Local web app, demo workspace, 1280 x 720 desktop viewport, and 390 x 844 mobile viewport.
@@ -16,14 +18,15 @@ The audit did expose several interaction-level problems that source review alone
 
 ### 1. Workspace launcher, first run, open/import, and demo
 
-**Journey:** Open Grillo -> review launcher -> create a project, open/import a bundle, or enter the demo -> arrive at Overview.
+**Journey:** Open Grillo -> review launcher -> create a project, open/import a bundle, enter the demo, or start the New user tutorial -> arrive at Overview.
 
 **Health after this pass:** Good.
 
 - The launcher now remains visible on first run instead of opening `New project` automatically. The visible launcher already explains all three entry paths, so the modal is now shown only after an explicit action.
 - When no project is open, the sidebar contains only Projects, Open, and Demo. Project views and Settings no longer lead users into guarded routes that cannot work yet.
 - Closing an unsaved demo still uses the existing confirmation dialog, but confirming now returns to the clean launcher without immediately reopening project creation.
 - Disabled primary actions now look inactive instead of retaining the full green emphasis of an available action.
+- The Demo project explanation now includes a `New user tutorial` link. Its landing page opens a disposable demo only when existing unsaved work is protected, then a 13-step wizard moves through every core project surface with visible progress, Back/Next/Exit controls, and manual sidebar-route synchronization.
 
 ### 2. Create, save, switch, and close project
 
@@ -136,6 +139,7 @@ The audit did expose several interaction-level problems that source review alone
 - Reflowed work-item metadata for mobile and replaced native multi-select labels with checkbox chips.
 - Shortened Bug Triage action copy without losing item-specific accessible labels.
 - Improved disabled primary-action styling and mobile Overview density.
+- Added the safe demo-backed New user tutorial entry, landing page, persistent route-aware wizard, and responsive desktop/mobile presentation.
 
 ## Verification
 

packages/ui/src/AppShell.tsx

@@ -36,6 +36,7 @@ import { Button, ConfirmDialog, HelpTip, IconButton, InlineAlert, ToastProvider,
 import { PROJECT_NAV_ITEMS } from "./nav-config";
 import { useWorkspaceStore } from "./store/workspace-store";
 import { hasRegisteredSavedRoute, savedViewsForBundle, viewRoute } from "./views/planning/view-helpers";
+import { NewUserTutorial } from "./tutorial";
 
 export type AppShellProps = {
   appMode: "web" | "desktop";
@@ -455,7 +456,8 @@ function AppShellFrame({ appMode, appDistribution = "local", children }: AppShel
       location.pathname !== "/" &&
       !location.pathname.startsWith("/projects") &&
       !location.pathname.startsWith("/open") &&
-      !location.pathname.startsWith("/demo"),
+      !location.pathname.startsWith("/demo") &&
+      !location.pathname.startsWith("/tutorial"),
     [location.pathname]
   );
 
@@ -664,6 +666,7 @@ function AppShellFrame({ appMode, appDistribution = "local", children }: AppShel
         />
       ) : null}
 
+      <NewUserTutorial activeProjectId={bundle?.project.id ?? null} />
       <CommandPalette />
     </div>
   );

packages/ui/src/index.ts

@@ -26,3 +26,4 @@ export * from "./views/search";
 export * from "./views/settings";
 export * from "./views/projects";
 export * from "./work-item";
+export * from "./tutorial";